diff --git a/gapic/generator/generator.py b/gapic/generator/generator.py index f42e40655e..55f9526ba8 100644 --- a/gapic/generator/generator.py +++ b/gapic/generator/generator.py @@ -269,12 +269,28 @@ def _render_template( # library. This means that the module names will need to be versioned in # import statements. For example `import google.cloud.library_v2` instead # of `import google.cloud.library`. - if ( - template_name.startswith("%namespace/%name/") - and api_schema.all_library_settings[ - api_schema.naming.proto_package - ].python_settings.experimental_features.unversioned_package_disabled - ): + # If default version is specified, and doesn't match the current version being generated or + # `python_settings.experimental_features.unversioned_package_disabled` is set + if template_name.startswith("%namespace/%name/") and \ + ( + api_schema.all_library_settings[ + api_schema.naming.proto_package + ].python_settings.experimental_features.unversioned_package_disabled or + ( + len(opts.default_proto_package) > 0 and + # same proto package, excluding version + opts.default_proto_package.split(".")[0:-1] == api_schema.naming.proto_package.split(".")[0:-1] + and opts.default_proto_package != api_schema.naming.proto_package + ) + ): + return answer + + # Don't generate docs/index.rst if `default_proto_package` is specified and the default proto package does not match + if template_name == "docs/index.rst.j2" and len(opts.default_proto_package) > 0 and opts.default_proto_package != api_schema.naming.proto_package: + return answer + + # Don't generate `docs/summary_overview.md` for non-cloud APIs + if template_name == "docs/summary_overview.md.j2" and (api_schema.naming.module_namespace[0] != "google" or api_schema.naming.module_namespace[1] != "cloud"): return answer # Quick check: Rendering per service and per proto would be a diff --git a/gapic/samplegen_utils/snippet_index.py b/gapic/samplegen_utils/snippet_index.py index 07003d701e..6fe41937c6 100644 --- a/gapic/samplegen_utils/snippet_index.py +++ b/gapic/samplegen_utils/snippet_index.py @@ -121,7 +121,7 @@ def __init__(self, api_schema: api.API): # This is just a placeholder. release-please is responsible for # updating the metadata file to the correct library version. - self.metadata_index.client_library.version = "0.1.0" + self.metadata_index.client_library.version = api_schema.naming.gapic_version self.metadata_index.client_library.apis.append( snippet_metadata_pb2.Api( # type: ignore diff --git a/gapic/schema/naming.py b/gapic/schema/naming.py index ebf650944f..14c39a7bdb 100644 --- a/gapic/schema/naming.py +++ b/gapic/schema/naming.py @@ -45,6 +45,15 @@ class Naming(abc.ABC): proto_package: str = "" _warehouse_package_name: str = "" proto_plus_deps: Tuple[str, ...] = dataclasses.field(default_factory=tuple) + reference_doc_includes: Tuple[str, ...] = dataclasses.field(default_factory=tuple) + api_description: str = "" + default_proto_package: str = "" + _documentation_name: str = "" + documentation_uri: str = "" + release_level: str = "" + title: str = "" + include_upgrading_doc: bool = False + gapic_version: str = "" def __post_init__(self): if not self.product_name: @@ -154,12 +163,58 @@ def build( package_info = dataclasses.replace( package_info, _warehouse_package_name=opts.warehouse_package_name ) + + if opts.reference_doc_includes: + package_info = dataclasses.replace( + package_info, reference_doc_includes=opts.reference_doc_includes + ) + + if opts.api_description: + package_info = dataclasses.replace( + package_info, api_description=opts.api_description + ) + + if opts.default_proto_package: + package_info = dataclasses.replace( + package_info, default_proto_package=opts.default_proto_package + ) + + if opts.documentation_name: + package_info = dataclasses.replace( + package_info, _documentation_name=opts.documentation_name + ) + + if opts.documentation_uri: + package_info = dataclasses.replace( + package_info, documentation_uri=opts.documentation_uri + ) + + if opts.release_level: + package_info = dataclasses.replace( + package_info, release_level=opts.release_level + ) + + if opts.title: + package_info = dataclasses.replace(package_info, title=opts.title) + if opts.proto_plus_deps: package_info = dataclasses.replace( package_info, proto_plus_deps=opts.proto_plus_deps, ) + if opts.include_upgrading_doc: + package_info = dataclasses.replace( + package_info, + include_upgrading_doc=opts.include_upgrading_doc, + ) + + if opts.gapic_version: + package_info = dataclasses.replace( + package_info, + gapic_version=opts.gapic_version, + ) + # Done; return the naming information. return package_info @@ -212,6 +267,15 @@ def warehouse_package_name(self) -> str: answer = list(self.namespace) + self.name.split(" ") return "-".join(answer).lower() + @property + def documentation_name(self) -> str: + """Return the appropriate name for documentation.""" + # If a custom name has been set, use it + if self._documentation_name: + return self._documentation_name + # Otherwise use `name` for backwards compatibility + return self.name.lower().replace(" ", "") + class NewNaming(Naming): @property diff --git a/gapic/templates/%namespace/%name/gapic_version.py.j2 b/gapic/templates/%namespace/%name/gapic_version.py.j2 index b3243d8eff..abc62bb8e9 100644 --- a/gapic/templates/%namespace/%name/gapic_version.py.j2 +++ b/gapic/templates/%namespace/%name/gapic_version.py.j2 @@ -1,5 +1,5 @@ {% extends '_base.py.j2' %} {% block content %} -__version__ = "0.0.0" # {x-release-please-version} +__version__ = "{% if api.naming.gapic_version %}{{ api.naming.gapic_version }}{% else %}0.0.0{% endif %}" # {x-release-please-version} {% endblock %} diff --git a/gapic/templates/%namespace/%name_%version/gapic_version.py.j2 b/gapic/templates/%namespace/%name_%version/gapic_version.py.j2 index b3243d8eff..abc62bb8e9 100644 --- a/gapic/templates/%namespace/%name_%version/gapic_version.py.j2 +++ b/gapic/templates/%namespace/%name_%version/gapic_version.py.j2 @@ -1,5 +1,5 @@ {% extends '_base.py.j2' %} {% block content %} -__version__ = "0.0.0" # {x-release-please-version} +__version__ = "{% if api.naming.gapic_version %}{{ api.naming.gapic_version }}{% else %}0.0.0{% endif %}" # {x-release-please-version} {% endblock %} diff --git a/gapic/templates/README.rst.j2 b/gapic/templates/README.rst.j2 index 3e6b3746d4..bcab8085f1 100644 --- a/gapic/templates/README.rst.j2 +++ b/gapic/templates/README.rst.j2 @@ -1,5 +1,28 @@ -Python Client for {{ api.naming.long_name }} API -================================================= +Python Client for {{ api.naming.title }} +=================={% for i in range( api.naming.title | length ) %}={% endfor %} + + +|{{ api.naming.release_level }}| |pypi| |versions| + +`{{ api.naming.title }}`_: {% if api.naming.api_description %}{{ api.naming.api_description.replace("\n", " ") }}{% endif %} + + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |{{ api.naming.release_level }}| image:: https://img.shields.io/badge/support-{{ api.naming.release_level }}-{% if api.naming.release_level == "stable" %}gold{% else %}orange{% endif %}.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/{{ api.naming.warehouse_package_name }}.svg + :target: https://pypi.org/project/{{ api.naming.warehouse_package_name }}/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/{{ api.naming.warehouse_package_name }}.svg + :target: https://pypi.org/project/{{ api.naming.warehouse_package_name }}/ +.. _{{ api.naming.title }}: {{ api.naming.documentation_uri }} +{% if api.naming.module_namespace|length >= 2 and api.naming.module_namespace[0] == "google" and api.naming.module_namespace[1] == "cloud" %} +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/{{ api.naming.documentation_name }}/latest/summary_overview +{% else %} +.. _Client Library Documentation: https://googleapis.dev/python/{{ api.naming.documentation_name }}/latest +{% endif %} +.. _Product Documentation: {{ api.naming.documentation_uri }} Quick Start ----------- @@ -8,26 +31,55 @@ In order to use this library, you first need to go through the following steps: 1. `Select or create a Cloud Platform project.`_ 2. `Enable billing for your project.`_ -3. Enable the {{ api.naming.long_name }} API. -4. `Setup Authentication.`_ +3. `Enable the {{ api.naming.title }}.`_ +4. `Set up Authentication.`_ .. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project .. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project -.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html +.. _Enable the {{ api.naming.title }}.: {{ api.naming.documentation_uri }} +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html Installation ~~~~~~~~~~~~ -Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to -create isolated Python environments. The basic problem it addresses is one of -dependencies and versions, and indirectly permissions. +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. -With `virtualenv`_, it's possible to install this library without needing system +With `venv`_, it's possible to install this library without needing system install permissions, and without clashing with the installed system dependencies. -.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/{{ api.naming.warehouse_package_name }}/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 + +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches Mac/Linux ^^^^^^^^^ @@ -36,7 +88,7 @@ Mac/Linux python3 -m venv source /bin/activate - /bin/pip install /path/to/library + pip install {{ api.naming.warehouse_package_name }} Windows @@ -44,10 +96,22 @@ Windows .. code-block:: console - python3 -m venv - \Scripts\activate - \Scripts\pip.exe install \path\to\library + py -m venv + .\\Scripts\activate + pip install {{ api.naming.warehouse_package_name }} + +Next Steps +~~~~~~~~~~ +- Read the `Client Library Documentation`_ for {{ api.naming.title }} + to see other available methods on the client. +- Read the `{{ api.naming.title }} Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _{{ api.naming.title }} Product documentation: {{ api.naming.documentation_uri }} +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst Logging ------- @@ -59,7 +123,6 @@ Note the following: #. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. #. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. - Simple, environment-based configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -75,9 +138,8 @@ A logging scope is a period-separated namespace that begins with :code:`google`, **NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. - -Examples -^^^^^^^^ +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Enabling the default handler for all Google-based loggers @@ -97,18 +159,17 @@ Advanced, code-based configuration You can also configure a valid logging scope using Python's standard `logging` mechanism. - -Examples -^^^^^^^^ +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ - Configuring a handler for all Google-based loggers .. code-block:: python import logging - - from google.cloud.translate_v3 import translate - + + from google.cloud import library_v1 + base_logger = logging.getLogger("google") base_logger.addHandler(logging.StreamHandler()) base_logger.setLevel(logging.DEBUG) @@ -118,14 +179,13 @@ Examples .. code-block:: python import logging - - from google.cloud.translate_v3 import translate - + + from google.cloud import library_v1 + base_logger = logging.getLogger("google.cloud.library_v1") base_logger.addHandler(logging.StreamHandler()) base_logger.setLevel(logging.DEBUG) - Logging details ~~~~~~~~~~~~~~~ diff --git a/gapic/templates/docs/README.rst.j2 b/gapic/templates/docs/README.rst.j2 new file mode 120000 index 0000000000..f013762517 --- /dev/null +++ b/gapic/templates/docs/README.rst.j2 @@ -0,0 +1 @@ +../README.rst.j2 \ No newline at end of file diff --git a/gapic/templates/docs/index.rst.j2 b/gapic/templates/docs/index.rst.j2 index 4e55a05ff9..2539c15cec 100644 --- a/gapic/templates/docs/index.rst.j2 +++ b/gapic/templates/docs/index.rst.j2 @@ -1,5 +1,11 @@ +.. include:: README.rst + .. include:: multiprocessing.rst +{% if api.naming.reference_doc_includes|length>=1 %}This package includes clients for multiple versions of {{ api.naming.title }}. +By default, you will get version ``{{ api.naming.versioned_module_name }}``. + +{% endif %} API Reference ------------- @@ -8,3 +14,43 @@ API Reference {{ api.naming.versioned_module_name }}/services_ {{ api.naming.versioned_module_name }}/types_ + +{% for reference_doc_include in api.naming.reference_doc_includes %} +API Reference +------------- +.. toctree:: + :maxdepth: 2 + + {{ reference_doc_include }}/services_ + {{ reference_doc_include }}/types_ + +{% endfor %} +{% if api.naming.include_upgrading_doc %} +Migration Guide +--------------- + +See the guide below for instructions on migrating to the latest version. + +.. toctree:: + :maxdepth: 2 + + UPGRADING + +{% endif %} + +Changelog +--------- + +For a list of all ``{{ api.naming.warehouse_package_name }}`` releases: + +.. toctree:: + :maxdepth: 2 + + CHANGELOG + +{% if api.naming.module_namespace|length >= 2 and api.naming.module_namespace[0] == "google" and api.naming.module_namespace[1] == "cloud" %} +.. toctree:: + :hidden: + + summary_overview.md +{% endif %} diff --git a/gapic/templates/docs/summary_overview.md.j2 b/gapic/templates/docs/summary_overview.md.j2 new file mode 100644 index 0000000000..1f5765ee1f --- /dev/null +++ b/gapic/templates/docs/summary_overview.md.j2 @@ -0,0 +1,22 @@ +[ +This is a templated file. Adding content to this file may result in it being +reverted. Instead, if you want to place additional content, create an +"overview_content.md" file in `docs/` directory. The Sphinx tool will +pick up on the content and merge the content. +]: # + +# {{ api.naming.title }} + +Overview of the APIs available for {{ api.naming.title }}. + +## All entries + +Classes, methods and properties & attributes for +{{ api.naming.title }}. + +[classes](https://cloud.google.com/python/docs/reference/{{ api.naming.documentation_name }}/latest/summary_class.html) + +[methods](https://cloud.google.com/python/docs/reference/{{ api.naming.documentation_name }}/latest/summary_method.html) + +[properties and +attributes](https://cloud.google.com/python/docs/reference/{{ api.naming.documentation_name }}/latest/summary_property.html) \ No newline at end of file diff --git a/gapic/utils/options.py b/gapic/utils/options.py index ef6497e39a..bace08fd81 100644 --- a/gapic/utils/options.py +++ b/gapic/utils/options.py @@ -50,6 +50,15 @@ class Options: service_yaml_config: Dict[str, Any] = dataclasses.field(default_factory=dict) rest_numeric_enums: bool = False proto_plus_deps: Tuple[str, ...] = dataclasses.field(default=("",)) + reference_doc_includes: Tuple[str, ...] = dataclasses.field(default=("",)) + api_description: str = "" + default_proto_package: str = "" + documentation_name: str = "" + documentation_uri: str = "" + release_level: str = "" + title: str = "" + include_upgrading_doc: bool = False + gapic_version: str = "" # Class constants PYTHON_GAPIC_PREFIX: str = "python-gapic-" @@ -71,6 +80,14 @@ class Options: # proto plus dependencies delineated by '+' # For example, 'google.cloud.api.v1+google.cloud.anotherapi.v2' "proto-plus-deps", + "reference-doc-includes", + "release-level", # One of ["preview", "stable"] + "default-proto-package", + "documentation-name", + "documentation-uri", + "include-upgrading-doc", + "gapic-version", + "api-description", ) ) @@ -152,6 +169,14 @@ def tweak_path(p): # but it is not a field in the gogle.api.Service proto. service_yaml_config.pop("type", None) + api_description = service_yaml_config.get("documentation", {}).get( + "summary", opts.pop("api-description", [""])[0].replace("|", ",") + ) + + documentation_uri = service_yaml_config.get("publishing", {}).get( + "documentation_uri", opts.pop("documentation-uri", [""])[0] + ) + # Build the options instance. sample_paths = opts.pop("samples", []) @@ -172,6 +197,10 @@ def tweak_path(p): if old_naming: autogen_snippets = False + reference_doc_includes = tuple(opts.pop("reference-doc-includes", "")) + if len(reference_doc_includes): + reference_doc_includes = tuple(reference_doc_includes[0].split("+")) + proto_plus_deps = tuple(opts.pop("proto-plus-deps", "")) if len(proto_plus_deps): proto_plus_deps = tuple(proto_plus_deps[0].split("+")) @@ -196,7 +225,18 @@ def tweak_path(p): transport=opts.pop("transport", ["grpc"])[0].split("+"), service_yaml_config=service_yaml_config, rest_numeric_enums=bool(opts.pop("rest-numeric-enums", False)), + reference_doc_includes=reference_doc_includes, + default_proto_package=opts.pop("default-proto-package", [""]).pop(), + documentation_name=opts.pop("documentation-name", [""]).pop(), + documentation_uri=documentation_uri, + api_description=api_description, proto_plus_deps=proto_plus_deps, + release_level=opts.pop( + "release-level", ["preview"] + ).pop(), # Default to "preview" unless explicitly set to "stable" + title=service_yaml_config.get("title", ""), + include_upgrading_doc=bool(opts.pop("include-upgrading-doc", False)), + gapic_version=opts.pop("gapic-version", [""]).pop(), ) # Note: if we ever need to recursively check directories for sample diff --git a/tests/integration/cloudasset_v1.yaml b/tests/integration/cloudasset_v1.yaml index 65bc90f6e2..48e671d2df 100644 --- a/tests/integration/cloudasset_v1.yaml +++ b/tests/integration/cloudasset_v1.yaml @@ -44,4 +44,13 @@ authentication: - selector: google.longrunning.Operations.GetOperation oauth: canonical_scopes: |- - https://www.googleapis.com/auth/cloud-platform \ No newline at end of file + https://www.googleapis.com/auth/cloud-platform +publishing: + organization: CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED + new_issue_uri: '' + documentation_uri: 'https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview' + api_short_name: '' + github_label: '' + doc_tag_prefix: '' + codeowner_github_teams: + library_settings: diff --git a/tests/integration/eventarc_v1.yaml b/tests/integration/eventarc_v1.yaml index 0a354f0aa2..9ef4147a25 100644 --- a/tests/integration/eventarc_v1.yaml +++ b/tests/integration/eventarc_v1.yaml @@ -119,6 +119,13 @@ authentication: publishing: + organization: CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED + new_issue_uri: '' + documentation_uri: 'https://cloud.google.com/eventarc' + api_short_name: '' + github_label: '' + doc_tag_prefix: '' + codeowner_github_teams: library_settings: - version: 'google.cloud.eventarc.v1' python_settings: diff --git a/tests/integration/goldens/asset/README.rst b/tests/integration/goldens/asset/README.rst index a10b3ef1e9..b21233e0f9 100755 --- a/tests/integration/goldens/asset/README.rst +++ b/tests/integration/goldens/asset/README.rst @@ -1,5 +1,22 @@ -Python Client for Google Cloud Asset API -================================================= +Python Client for Cloud Asset API +================================= + +|preview| |pypi| |versions| + +`Cloud Asset API`_: The Cloud Asset API manages the history and inventory of Google Cloud resources. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-asset.svg + :target: https://pypi.org/project/google-cloud-asset/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-asset.svg + :target: https://pypi.org/project/google-cloud-asset/ +.. _Cloud Asset API: https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/asset/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview Quick Start ----------- @@ -8,26 +25,55 @@ In order to use this library, you first need to go through the following steps: 1. `Select or create a Cloud Platform project.`_ 2. `Enable billing for your project.`_ -3. Enable the Google Cloud Asset API. -4. `Setup Authentication.`_ +3. `Enable the Cloud Asset API.`_ +4. `Set up Authentication.`_ .. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project .. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project -.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html +.. _Enable the Cloud Asset API.: https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html Installation ~~~~~~~~~~~~ -Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to -create isolated Python environments. The basic problem it addresses is one of -dependencies and versions, and indirectly permissions. +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. -With `virtualenv`_, it's possible to install this library without needing system +With `venv`_, it's possible to install this library without needing system install permissions, and without clashing with the installed system dependencies. -.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-asset/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches Mac/Linux ^^^^^^^^^ @@ -36,7 +82,7 @@ Mac/Linux python3 -m venv source /bin/activate - /bin/pip install /path/to/library + pip install google-cloud-asset Windows @@ -44,10 +90,22 @@ Windows .. code-block:: console - python3 -m venv - \Scripts\activate - \Scripts\pip.exe install \path\to\library + py -m venv + .\\Scripts\activate + pip install google-cloud-asset + +Next Steps +~~~~~~~~~~ +- Read the `Client Library Documentation`_ for Cloud Asset API + to see other available methods on the client. +- Read the `Cloud Asset API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Cloud Asset API Product documentation: https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst Logging ------- @@ -59,7 +117,6 @@ Note the following: #. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. #. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. - Simple, environment-based configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -75,9 +132,8 @@ A logging scope is a period-separated namespace that begins with :code:`google`, **NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. - -Examples -^^^^^^^^ +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Enabling the default handler for all Google-based loggers @@ -97,9 +153,8 @@ Advanced, code-based configuration You can also configure a valid logging scope using Python's standard `logging` mechanism. - -Examples -^^^^^^^^ +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ - Configuring a handler for all Google-based loggers @@ -107,7 +162,7 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google") base_logger.addHandler(logging.StreamHandler()) @@ -119,13 +174,12 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google.cloud.library_v1") base_logger.addHandler(logging.StreamHandler()) base_logger.setLevel(logging.DEBUG) - Logging details ~~~~~~~~~~~~~~~ diff --git a/tests/integration/goldens/asset/docs/README.rst b/tests/integration/goldens/asset/docs/README.rst new file mode 100755 index 0000000000..b21233e0f9 --- /dev/null +++ b/tests/integration/goldens/asset/docs/README.rst @@ -0,0 +1,197 @@ +Python Client for Cloud Asset API +================================= + +|preview| |pypi| |versions| + +`Cloud Asset API`_: The Cloud Asset API manages the history and inventory of Google Cloud resources. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-asset.svg + :target: https://pypi.org/project/google-cloud-asset/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-asset.svg + :target: https://pypi.org/project/google-cloud-asset/ +.. _Cloud Asset API: https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/asset/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview + +Quick Start +----------- + +In order to use this library, you first need to go through the following steps: + +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Cloud Asset API.`_ +4. `Set up Authentication.`_ + +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project +.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project +.. _Enable the Cloud Asset API.: https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html + +Installation +~~~~~~~~~~~~ + +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. + +With `venv`_, it's possible to install this library without needing system +install permissions, and without clashing with the installed system +dependencies. + +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-asset/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 + +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches + +Mac/Linux +^^^^^^^^^ + +.. code-block:: console + + python3 -m venv + source /bin/activate + pip install google-cloud-asset + + +Windows +^^^^^^^ + +.. code-block:: console + + py -m venv + .\\Scripts\activate + pip install google-cloud-asset + +Next Steps +~~~~~~~~~~ + +- Read the `Client Library Documentation`_ for Cloud Asset API + to see other available methods on the client. +- Read the `Cloud Asset API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Cloud Asset API Product documentation: https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst + +Logging +------- + +This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes. +Note the following: + +#. Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or on Google Cloud Logging. +#. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. +#. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. + +Simple, environment-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable logging for this library without any changes in your code, set the :code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to a valid Google +logging scope. This configures handling of logging events (at level :code:`logging.DEBUG` or higher) from this library in a default manner, emitting the logged +messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging +event. + +A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. + +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Enabling the default handler for all Google-based loggers + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +- Enabling the default handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_v1 + + +Advanced, code-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also configure a valid logging scope using Python's standard `logging` mechanism. + +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ + +- Configuring a handler for all Google-based loggers + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +- Configuring a handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google.cloud.library_v1") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +Logging details +~~~~~~~~~~~~~~~ + +#. Regardless of which of the mechanisms above you use to configure logging for this library, by default logging events are not propagated up to the root + logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set + :code:`logging.getLogger("google").propagate = True` in your code. +#. You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for + one library, but decide you need to also set up environment-based logging configuration for another library. + + #. If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual + if the code -based configuration gets applied first. + +#. The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get + executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured. + (This is the reason for 2.i. above.) diff --git a/tests/integration/goldens/asset/docs/index.rst b/tests/integration/goldens/asset/docs/index.rst index fab3d489ef..04ca2f302c 100755 --- a/tests/integration/goldens/asset/docs/index.rst +++ b/tests/integration/goldens/asset/docs/index.rst @@ -1,3 +1,5 @@ +.. include:: README.rst + .. include:: multiprocessing.rst @@ -8,3 +10,19 @@ API Reference asset_v1/services_ asset_v1/types_ + + +Changelog +--------- + +For a list of all ``google-cloud-asset`` releases: + +.. toctree:: + :maxdepth: 2 + + CHANGELOG + +.. toctree:: + :hidden: + + summary_overview.md diff --git a/tests/integration/goldens/asset/docs/summary_overview.md b/tests/integration/goldens/asset/docs/summary_overview.md new file mode 100755 index 0000000000..a5e23fb657 --- /dev/null +++ b/tests/integration/goldens/asset/docs/summary_overview.md @@ -0,0 +1,22 @@ +[ +This is a templated file. Adding content to this file may result in it being +reverted. Instead, if you want to place additional content, create an +"overview_content.md" file in `docs/` directory. The Sphinx tool will +pick up on the content and merge the content. +]: # + +# Cloud Asset API + +Overview of the APIs available for Cloud Asset API. + +## All entries + +Classes, methods and properties & attributes for +Cloud Asset API. + +[classes](https://cloud.google.com/python/docs/reference/asset/latest/summary_class.html) + +[methods](https://cloud.google.com/python/docs/reference/asset/latest/summary_method.html) + +[properties and +attributes](https://cloud.google.com/python/docs/reference/asset/latest/summary_property.html) diff --git a/tests/integration/goldens/credentials/README.rst b/tests/integration/goldens/credentials/README.rst index 44a6987f42..35f4f78fc7 100755 --- a/tests/integration/goldens/credentials/README.rst +++ b/tests/integration/goldens/credentials/README.rst @@ -1,5 +1,22 @@ -Python Client for Google Iam Credentials API -================================================= +Python Client for IAM Service Account Credentials API +===================================================== + +|preview| |pypi| |versions| + +`IAM Service Account Credentials API`_: Creates short-lived, limited-privilege credentials for IAM service accounts. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-iam-credentials.svg + :target: https://pypi.org/project/google-iam-credentials/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-iam-credentials.svg + :target: https://pypi.org/project/google-iam-credentials/ +.. _IAM Service Account Credentials API: https://cloud.google.com/iam/docs/reference/credentials/rest +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/credentials/latest +.. _Product Documentation: https://cloud.google.com/iam/docs/reference/credentials/rest Quick Start ----------- @@ -8,26 +25,55 @@ In order to use this library, you first need to go through the following steps: 1. `Select or create a Cloud Platform project.`_ 2. `Enable billing for your project.`_ -3. Enable the Google Iam Credentials API. -4. `Setup Authentication.`_ +3. `Enable the IAM Service Account Credentials API.`_ +4. `Set up Authentication.`_ .. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project .. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project -.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html +.. _Enable the IAM Service Account Credentials API.: https://cloud.google.com/iam/docs/reference/credentials/rest +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html Installation ~~~~~~~~~~~~ -Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to -create isolated Python environments. The basic problem it addresses is one of -dependencies and versions, and indirectly permissions. +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. -With `virtualenv`_, it's possible to install this library without needing system +With `venv`_, it's possible to install this library without needing system install permissions, and without clashing with the installed system dependencies. -.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-iam-credentials/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches Mac/Linux ^^^^^^^^^ @@ -36,7 +82,7 @@ Mac/Linux python3 -m venv source /bin/activate - /bin/pip install /path/to/library + pip install google-iam-credentials Windows @@ -44,10 +90,22 @@ Windows .. code-block:: console - python3 -m venv - \Scripts\activate - \Scripts\pip.exe install \path\to\library + py -m venv + .\\Scripts\activate + pip install google-iam-credentials + +Next Steps +~~~~~~~~~~ +- Read the `Client Library Documentation`_ for IAM Service Account Credentials API + to see other available methods on the client. +- Read the `IAM Service Account Credentials API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _IAM Service Account Credentials API Product documentation: https://cloud.google.com/iam/docs/reference/credentials/rest +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst Logging ------- @@ -59,7 +117,6 @@ Note the following: #. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. #. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. - Simple, environment-based configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -75,9 +132,8 @@ A logging scope is a period-separated namespace that begins with :code:`google`, **NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. - -Examples -^^^^^^^^ +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Enabling the default handler for all Google-based loggers @@ -97,9 +153,8 @@ Advanced, code-based configuration You can also configure a valid logging scope using Python's standard `logging` mechanism. - -Examples -^^^^^^^^ +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ - Configuring a handler for all Google-based loggers @@ -107,7 +162,7 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google") base_logger.addHandler(logging.StreamHandler()) @@ -119,13 +174,12 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google.cloud.library_v1") base_logger.addHandler(logging.StreamHandler()) base_logger.setLevel(logging.DEBUG) - Logging details ~~~~~~~~~~~~~~~ diff --git a/tests/integration/goldens/credentials/docs/README.rst b/tests/integration/goldens/credentials/docs/README.rst new file mode 100755 index 0000000000..35f4f78fc7 --- /dev/null +++ b/tests/integration/goldens/credentials/docs/README.rst @@ -0,0 +1,197 @@ +Python Client for IAM Service Account Credentials API +===================================================== + +|preview| |pypi| |versions| + +`IAM Service Account Credentials API`_: Creates short-lived, limited-privilege credentials for IAM service accounts. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-iam-credentials.svg + :target: https://pypi.org/project/google-iam-credentials/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-iam-credentials.svg + :target: https://pypi.org/project/google-iam-credentials/ +.. _IAM Service Account Credentials API: https://cloud.google.com/iam/docs/reference/credentials/rest +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/credentials/latest +.. _Product Documentation: https://cloud.google.com/iam/docs/reference/credentials/rest + +Quick Start +----------- + +In order to use this library, you first need to go through the following steps: + +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the IAM Service Account Credentials API.`_ +4. `Set up Authentication.`_ + +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project +.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project +.. _Enable the IAM Service Account Credentials API.: https://cloud.google.com/iam/docs/reference/credentials/rest +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html + +Installation +~~~~~~~~~~~~ + +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. + +With `venv`_, it's possible to install this library without needing system +install permissions, and without clashing with the installed system +dependencies. + +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-iam-credentials/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 + +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches + +Mac/Linux +^^^^^^^^^ + +.. code-block:: console + + python3 -m venv + source /bin/activate + pip install google-iam-credentials + + +Windows +^^^^^^^ + +.. code-block:: console + + py -m venv + .\\Scripts\activate + pip install google-iam-credentials + +Next Steps +~~~~~~~~~~ + +- Read the `Client Library Documentation`_ for IAM Service Account Credentials API + to see other available methods on the client. +- Read the `IAM Service Account Credentials API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _IAM Service Account Credentials API Product documentation: https://cloud.google.com/iam/docs/reference/credentials/rest +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst + +Logging +------- + +This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes. +Note the following: + +#. Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or on Google Cloud Logging. +#. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. +#. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. + +Simple, environment-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable logging for this library without any changes in your code, set the :code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to a valid Google +logging scope. This configures handling of logging events (at level :code:`logging.DEBUG` or higher) from this library in a default manner, emitting the logged +messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging +event. + +A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. + +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Enabling the default handler for all Google-based loggers + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +- Enabling the default handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_v1 + + +Advanced, code-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also configure a valid logging scope using Python's standard `logging` mechanism. + +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ + +- Configuring a handler for all Google-based loggers + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +- Configuring a handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google.cloud.library_v1") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +Logging details +~~~~~~~~~~~~~~~ + +#. Regardless of which of the mechanisms above you use to configure logging for this library, by default logging events are not propagated up to the root + logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set + :code:`logging.getLogger("google").propagate = True` in your code. +#. You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for + one library, but decide you need to also set up environment-based logging configuration for another library. + + #. If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual + if the code -based configuration gets applied first. + +#. The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get + executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured. + (This is the reason for 2.i. above.) diff --git a/tests/integration/goldens/credentials/docs/index.rst b/tests/integration/goldens/credentials/docs/index.rst index a2f172d3d0..5d405af759 100755 --- a/tests/integration/goldens/credentials/docs/index.rst +++ b/tests/integration/goldens/credentials/docs/index.rst @@ -1,3 +1,5 @@ +.. include:: README.rst + .. include:: multiprocessing.rst @@ -8,3 +10,17 @@ API Reference credentials_v1/services_ credentials_v1/types_ + + +Changelog +--------- + +For a list of all ``google-iam-credentials`` releases: + +.. toctree:: + :maxdepth: 2 + + CHANGELOG + +.. toctree:: + :hidden: diff --git a/tests/integration/goldens/credentials/docs/summary_overview.md b/tests/integration/goldens/credentials/docs/summary_overview.md new file mode 100755 index 0000000000..6ac5ee02b3 --- /dev/null +++ b/tests/integration/goldens/credentials/docs/summary_overview.md @@ -0,0 +1,22 @@ +[ +This is a templated file. Adding content to this file may result in it being +reverted. Instead, if you want to place additional content, create an +"overview_content.md" file in `docs/` directory. The Sphinx tool will +pick up on the content and merge the content. +]: # + +# IAM Service Account Credentials API + +Overview of the APIs available for IAM Service Account Credentials API. + +## All entries + +Classes, methods and properties & attributes for +IAM Service Account Credentials API. + +[classes](https://cloud.google.com/python/docs/reference/credentials/latest/summary_class.html) + +[methods](https://cloud.google.com/python/docs/reference/credentials/latest/summary_method.html) + +[properties and +attributes](https://cloud.google.com/python/docs/reference/credentials/latest/summary_property.html) diff --git a/tests/integration/goldens/eventarc/README.rst b/tests/integration/goldens/eventarc/README.rst index bbf4c3f725..7267248da7 100755 --- a/tests/integration/goldens/eventarc/README.rst +++ b/tests/integration/goldens/eventarc/README.rst @@ -1,5 +1,22 @@ -Python Client for Google Cloud Eventarc API -================================================= +Python Client for Eventarc API +============================== + +|preview| |pypi| |versions| + +`Eventarc API`_: Build event-driven applications on Google Cloud Platform. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-eventarc.svg + :target: https://pypi.org/project/google-cloud-eventarc/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-eventarc.svg + :target: https://pypi.org/project/google-cloud-eventarc/ +.. _Eventarc API: https://cloud.google.com/eventarc +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/eventarc/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/eventarc Quick Start ----------- @@ -8,26 +25,55 @@ In order to use this library, you first need to go through the following steps: 1. `Select or create a Cloud Platform project.`_ 2. `Enable billing for your project.`_ -3. Enable the Google Cloud Eventarc API. -4. `Setup Authentication.`_ +3. `Enable the Eventarc API.`_ +4. `Set up Authentication.`_ .. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project .. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project -.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html +.. _Enable the Eventarc API.: https://cloud.google.com/eventarc +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html Installation ~~~~~~~~~~~~ -Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to -create isolated Python environments. The basic problem it addresses is one of -dependencies and versions, and indirectly permissions. +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. -With `virtualenv`_, it's possible to install this library without needing system +With `venv`_, it's possible to install this library without needing system install permissions, and without clashing with the installed system dependencies. -.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-eventarc/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches Mac/Linux ^^^^^^^^^ @@ -36,7 +82,7 @@ Mac/Linux python3 -m venv source /bin/activate - /bin/pip install /path/to/library + pip install google-cloud-eventarc Windows @@ -44,10 +90,22 @@ Windows .. code-block:: console - python3 -m venv - \Scripts\activate - \Scripts\pip.exe install \path\to\library + py -m venv + .\\Scripts\activate + pip install google-cloud-eventarc + +Next Steps +~~~~~~~~~~ +- Read the `Client Library Documentation`_ for Eventarc API + to see other available methods on the client. +- Read the `Eventarc API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Eventarc API Product documentation: https://cloud.google.com/eventarc +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst Logging ------- @@ -59,7 +117,6 @@ Note the following: #. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. #. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. - Simple, environment-based configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -75,9 +132,8 @@ A logging scope is a period-separated namespace that begins with :code:`google`, **NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. - -Examples -^^^^^^^^ +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Enabling the default handler for all Google-based loggers @@ -97,9 +153,8 @@ Advanced, code-based configuration You can also configure a valid logging scope using Python's standard `logging` mechanism. - -Examples -^^^^^^^^ +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ - Configuring a handler for all Google-based loggers @@ -107,7 +162,7 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google") base_logger.addHandler(logging.StreamHandler()) @@ -119,13 +174,12 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google.cloud.library_v1") base_logger.addHandler(logging.StreamHandler()) base_logger.setLevel(logging.DEBUG) - Logging details ~~~~~~~~~~~~~~~ diff --git a/tests/integration/goldens/eventarc/docs/README.rst b/tests/integration/goldens/eventarc/docs/README.rst new file mode 100755 index 0000000000..7267248da7 --- /dev/null +++ b/tests/integration/goldens/eventarc/docs/README.rst @@ -0,0 +1,197 @@ +Python Client for Eventarc API +============================== + +|preview| |pypi| |versions| + +`Eventarc API`_: Build event-driven applications on Google Cloud Platform. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-eventarc.svg + :target: https://pypi.org/project/google-cloud-eventarc/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-eventarc.svg + :target: https://pypi.org/project/google-cloud-eventarc/ +.. _Eventarc API: https://cloud.google.com/eventarc +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/eventarc/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/eventarc + +Quick Start +----------- + +In order to use this library, you first need to go through the following steps: + +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Eventarc API.`_ +4. `Set up Authentication.`_ + +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project +.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project +.. _Enable the Eventarc API.: https://cloud.google.com/eventarc +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html + +Installation +~~~~~~~~~~~~ + +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. + +With `venv`_, it's possible to install this library without needing system +install permissions, and without clashing with the installed system +dependencies. + +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-eventarc/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 + +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches + +Mac/Linux +^^^^^^^^^ + +.. code-block:: console + + python3 -m venv + source /bin/activate + pip install google-cloud-eventarc + + +Windows +^^^^^^^ + +.. code-block:: console + + py -m venv + .\\Scripts\activate + pip install google-cloud-eventarc + +Next Steps +~~~~~~~~~~ + +- Read the `Client Library Documentation`_ for Eventarc API + to see other available methods on the client. +- Read the `Eventarc API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Eventarc API Product documentation: https://cloud.google.com/eventarc +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst + +Logging +------- + +This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes. +Note the following: + +#. Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or on Google Cloud Logging. +#. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. +#. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. + +Simple, environment-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable logging for this library without any changes in your code, set the :code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to a valid Google +logging scope. This configures handling of logging events (at level :code:`logging.DEBUG` or higher) from this library in a default manner, emitting the logged +messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging +event. + +A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. + +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Enabling the default handler for all Google-based loggers + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +- Enabling the default handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_v1 + + +Advanced, code-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also configure a valid logging scope using Python's standard `logging` mechanism. + +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ + +- Configuring a handler for all Google-based loggers + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +- Configuring a handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google.cloud.library_v1") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +Logging details +~~~~~~~~~~~~~~~ + +#. Regardless of which of the mechanisms above you use to configure logging for this library, by default logging events are not propagated up to the root + logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set + :code:`logging.getLogger("google").propagate = True` in your code. +#. You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for + one library, but decide you need to also set up environment-based logging configuration for another library. + + #. If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual + if the code -based configuration gets applied first. + +#. The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get + executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured. + (This is the reason for 2.i. above.) diff --git a/tests/integration/goldens/eventarc/docs/index.rst b/tests/integration/goldens/eventarc/docs/index.rst index e1c01ae7c9..0bffe915c0 100755 --- a/tests/integration/goldens/eventarc/docs/index.rst +++ b/tests/integration/goldens/eventarc/docs/index.rst @@ -1,3 +1,5 @@ +.. include:: README.rst + .. include:: multiprocessing.rst @@ -8,3 +10,19 @@ API Reference eventarc_v1/services_ eventarc_v1/types_ + + +Changelog +--------- + +For a list of all ``google-cloud-eventarc`` releases: + +.. toctree:: + :maxdepth: 2 + + CHANGELOG + +.. toctree:: + :hidden: + + summary_overview.md diff --git a/tests/integration/goldens/eventarc/docs/summary_overview.md b/tests/integration/goldens/eventarc/docs/summary_overview.md new file mode 100755 index 0000000000..d98fbf7519 --- /dev/null +++ b/tests/integration/goldens/eventarc/docs/summary_overview.md @@ -0,0 +1,22 @@ +[ +This is a templated file. Adding content to this file may result in it being +reverted. Instead, if you want to place additional content, create an +"overview_content.md" file in `docs/` directory. The Sphinx tool will +pick up on the content and merge the content. +]: # + +# Eventarc API + +Overview of the APIs available for Eventarc API. + +## All entries + +Classes, methods and properties & attributes for +Eventarc API. + +[classes](https://cloud.google.com/python/docs/reference/eventarc/latest/summary_class.html) + +[methods](https://cloud.google.com/python/docs/reference/eventarc/latest/summary_method.html) + +[properties and +attributes](https://cloud.google.com/python/docs/reference/eventarc/latest/summary_property.html) diff --git a/tests/integration/goldens/logging/README.rst b/tests/integration/goldens/logging/README.rst index c3f6248ae3..0fa3853d84 100755 --- a/tests/integration/goldens/logging/README.rst +++ b/tests/integration/goldens/logging/README.rst @@ -1,5 +1,22 @@ -Python Client for Google Cloud Logging API -================================================= +Python Client for Cloud Logging API +=================================== + +|preview| |pypi| |versions| + +`Cloud Logging API`_: Writes log entries and manages your Cloud Logging configuration. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-logging.svg + :target: https://pypi.org/project/google-cloud-logging/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-logging.svg + :target: https://pypi.org/project/google-cloud-logging/ +.. _Cloud Logging API: https://cloud.google.com/logging/docs +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/logging/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/logging/docs Quick Start ----------- @@ -8,26 +25,55 @@ In order to use this library, you first need to go through the following steps: 1. `Select or create a Cloud Platform project.`_ 2. `Enable billing for your project.`_ -3. Enable the Google Cloud Logging API. -4. `Setup Authentication.`_ +3. `Enable the Cloud Logging API.`_ +4. `Set up Authentication.`_ .. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project .. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project -.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html +.. _Enable the Cloud Logging API.: https://cloud.google.com/logging/docs +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html Installation ~~~~~~~~~~~~ -Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to -create isolated Python environments. The basic problem it addresses is one of -dependencies and versions, and indirectly permissions. +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. -With `virtualenv`_, it's possible to install this library without needing system +With `venv`_, it's possible to install this library without needing system install permissions, and without clashing with the installed system dependencies. -.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-logging/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches Mac/Linux ^^^^^^^^^ @@ -36,7 +82,7 @@ Mac/Linux python3 -m venv source /bin/activate - /bin/pip install /path/to/library + pip install google-cloud-logging Windows @@ -44,10 +90,22 @@ Windows .. code-block:: console - python3 -m venv - \Scripts\activate - \Scripts\pip.exe install \path\to\library + py -m venv + .\\Scripts\activate + pip install google-cloud-logging + +Next Steps +~~~~~~~~~~ +- Read the `Client Library Documentation`_ for Cloud Logging API + to see other available methods on the client. +- Read the `Cloud Logging API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Cloud Logging API Product documentation: https://cloud.google.com/logging/docs +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst Logging ------- @@ -59,7 +117,6 @@ Note the following: #. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. #. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. - Simple, environment-based configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -75,9 +132,8 @@ A logging scope is a period-separated namespace that begins with :code:`google`, **NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. - -Examples -^^^^^^^^ +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Enabling the default handler for all Google-based loggers @@ -97,9 +153,8 @@ Advanced, code-based configuration You can also configure a valid logging scope using Python's standard `logging` mechanism. - -Examples -^^^^^^^^ +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ - Configuring a handler for all Google-based loggers @@ -107,7 +162,7 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google") base_logger.addHandler(logging.StreamHandler()) @@ -119,13 +174,12 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google.cloud.library_v1") base_logger.addHandler(logging.StreamHandler()) base_logger.setLevel(logging.DEBUG) - Logging details ~~~~~~~~~~~~~~~ diff --git a/tests/integration/goldens/logging/docs/README.rst b/tests/integration/goldens/logging/docs/README.rst new file mode 100755 index 0000000000..0fa3853d84 --- /dev/null +++ b/tests/integration/goldens/logging/docs/README.rst @@ -0,0 +1,197 @@ +Python Client for Cloud Logging API +=================================== + +|preview| |pypi| |versions| + +`Cloud Logging API`_: Writes log entries and manages your Cloud Logging configuration. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-logging.svg + :target: https://pypi.org/project/google-cloud-logging/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-logging.svg + :target: https://pypi.org/project/google-cloud-logging/ +.. _Cloud Logging API: https://cloud.google.com/logging/docs +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/logging/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/logging/docs + +Quick Start +----------- + +In order to use this library, you first need to go through the following steps: + +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Cloud Logging API.`_ +4. `Set up Authentication.`_ + +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project +.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project +.. _Enable the Cloud Logging API.: https://cloud.google.com/logging/docs +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html + +Installation +~~~~~~~~~~~~ + +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. + +With `venv`_, it's possible to install this library without needing system +install permissions, and without clashing with the installed system +dependencies. + +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-logging/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 + +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches + +Mac/Linux +^^^^^^^^^ + +.. code-block:: console + + python3 -m venv + source /bin/activate + pip install google-cloud-logging + + +Windows +^^^^^^^ + +.. code-block:: console + + py -m venv + .\\Scripts\activate + pip install google-cloud-logging + +Next Steps +~~~~~~~~~~ + +- Read the `Client Library Documentation`_ for Cloud Logging API + to see other available methods on the client. +- Read the `Cloud Logging API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Cloud Logging API Product documentation: https://cloud.google.com/logging/docs +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst + +Logging +------- + +This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes. +Note the following: + +#. Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or on Google Cloud Logging. +#. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. +#. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. + +Simple, environment-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable logging for this library without any changes in your code, set the :code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to a valid Google +logging scope. This configures handling of logging events (at level :code:`logging.DEBUG` or higher) from this library in a default manner, emitting the logged +messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging +event. + +A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. + +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Enabling the default handler for all Google-based loggers + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +- Enabling the default handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_v1 + + +Advanced, code-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also configure a valid logging scope using Python's standard `logging` mechanism. + +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ + +- Configuring a handler for all Google-based loggers + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +- Configuring a handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google.cloud.library_v1") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +Logging details +~~~~~~~~~~~~~~~ + +#. Regardless of which of the mechanisms above you use to configure logging for this library, by default logging events are not propagated up to the root + logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set + :code:`logging.getLogger("google").propagate = True` in your code. +#. You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for + one library, but decide you need to also set up environment-based logging configuration for another library. + + #. If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual + if the code -based configuration gets applied first. + +#. The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get + executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured. + (This is the reason for 2.i. above.) diff --git a/tests/integration/goldens/logging/docs/index.rst b/tests/integration/goldens/logging/docs/index.rst index 2be5cab965..c2396cfc34 100755 --- a/tests/integration/goldens/logging/docs/index.rst +++ b/tests/integration/goldens/logging/docs/index.rst @@ -1,3 +1,5 @@ +.. include:: README.rst + .. include:: multiprocessing.rst @@ -8,3 +10,19 @@ API Reference logging_v2/services_ logging_v2/types_ + + +Changelog +--------- + +For a list of all ``google-cloud-logging`` releases: + +.. toctree:: + :maxdepth: 2 + + CHANGELOG + +.. toctree:: + :hidden: + + summary_overview.md diff --git a/tests/integration/goldens/logging/docs/summary_overview.md b/tests/integration/goldens/logging/docs/summary_overview.md new file mode 100755 index 0000000000..4786fbcaab --- /dev/null +++ b/tests/integration/goldens/logging/docs/summary_overview.md @@ -0,0 +1,22 @@ +[ +This is a templated file. Adding content to this file may result in it being +reverted. Instead, if you want to place additional content, create an +"overview_content.md" file in `docs/` directory. The Sphinx tool will +pick up on the content and merge the content. +]: # + +# Cloud Logging API + +Overview of the APIs available for Cloud Logging API. + +## All entries + +Classes, methods and properties & attributes for +Cloud Logging API. + +[classes](https://cloud.google.com/python/docs/reference/logging/latest/summary_class.html) + +[methods](https://cloud.google.com/python/docs/reference/logging/latest/summary_method.html) + +[properties and +attributes](https://cloud.google.com/python/docs/reference/logging/latest/summary_property.html) diff --git a/tests/integration/goldens/logging_internal/README.rst b/tests/integration/goldens/logging_internal/README.rst index c3f6248ae3..c830d1aa89 100755 --- a/tests/integration/goldens/logging_internal/README.rst +++ b/tests/integration/goldens/logging_internal/README.rst @@ -1,5 +1,22 @@ -Python Client for Google Cloud Logging API -================================================= +Python Client for Cloud Logging API +=================================== + +|preview| |pypi| |versions| + +`Cloud Logging API`_: Writes log entries and manages your Cloud Logging configuration. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-logging.svg + :target: https://pypi.org/project/google-cloud-logging/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-logging.svg + :target: https://pypi.org/project/google-cloud-logging/ +.. _Cloud Logging API: https://cloud.google.com/logging/docs/ +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/logging/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/logging/docs/ Quick Start ----------- @@ -8,26 +25,55 @@ In order to use this library, you first need to go through the following steps: 1. `Select or create a Cloud Platform project.`_ 2. `Enable billing for your project.`_ -3. Enable the Google Cloud Logging API. -4. `Setup Authentication.`_ +3. `Enable the Cloud Logging API.`_ +4. `Set up Authentication.`_ .. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project .. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project -.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html +.. _Enable the Cloud Logging API.: https://cloud.google.com/logging/docs/ +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html Installation ~~~~~~~~~~~~ -Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to -create isolated Python environments. The basic problem it addresses is one of -dependencies and versions, and indirectly permissions. +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. -With `virtualenv`_, it's possible to install this library without needing system +With `venv`_, it's possible to install this library without needing system install permissions, and without clashing with the installed system dependencies. -.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-logging/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches Mac/Linux ^^^^^^^^^ @@ -36,7 +82,7 @@ Mac/Linux python3 -m venv source /bin/activate - /bin/pip install /path/to/library + pip install google-cloud-logging Windows @@ -44,10 +90,22 @@ Windows .. code-block:: console - python3 -m venv - \Scripts\activate - \Scripts\pip.exe install \path\to\library + py -m venv + .\\Scripts\activate + pip install google-cloud-logging + +Next Steps +~~~~~~~~~~ +- Read the `Client Library Documentation`_ for Cloud Logging API + to see other available methods on the client. +- Read the `Cloud Logging API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Cloud Logging API Product documentation: https://cloud.google.com/logging/docs/ +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst Logging ------- @@ -59,7 +117,6 @@ Note the following: #. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. #. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. - Simple, environment-based configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -75,9 +132,8 @@ A logging scope is a period-separated namespace that begins with :code:`google`, **NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. - -Examples -^^^^^^^^ +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Enabling the default handler for all Google-based loggers @@ -97,9 +153,8 @@ Advanced, code-based configuration You can also configure a valid logging scope using Python's standard `logging` mechanism. - -Examples -^^^^^^^^ +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ - Configuring a handler for all Google-based loggers @@ -107,7 +162,7 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google") base_logger.addHandler(logging.StreamHandler()) @@ -119,13 +174,12 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google.cloud.library_v1") base_logger.addHandler(logging.StreamHandler()) base_logger.setLevel(logging.DEBUG) - Logging details ~~~~~~~~~~~~~~~ diff --git a/tests/integration/goldens/logging_internal/docs/README.rst b/tests/integration/goldens/logging_internal/docs/README.rst new file mode 100755 index 0000000000..c830d1aa89 --- /dev/null +++ b/tests/integration/goldens/logging_internal/docs/README.rst @@ -0,0 +1,197 @@ +Python Client for Cloud Logging API +=================================== + +|preview| |pypi| |versions| + +`Cloud Logging API`_: Writes log entries and manages your Cloud Logging configuration. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-logging.svg + :target: https://pypi.org/project/google-cloud-logging/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-logging.svg + :target: https://pypi.org/project/google-cloud-logging/ +.. _Cloud Logging API: https://cloud.google.com/logging/docs/ +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/logging/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/logging/docs/ + +Quick Start +----------- + +In order to use this library, you first need to go through the following steps: + +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Cloud Logging API.`_ +4. `Set up Authentication.`_ + +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project +.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project +.. _Enable the Cloud Logging API.: https://cloud.google.com/logging/docs/ +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html + +Installation +~~~~~~~~~~~~ + +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. + +With `venv`_, it's possible to install this library without needing system +install permissions, and without clashing with the installed system +dependencies. + +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-logging/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 + +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches + +Mac/Linux +^^^^^^^^^ + +.. code-block:: console + + python3 -m venv + source /bin/activate + pip install google-cloud-logging + + +Windows +^^^^^^^ + +.. code-block:: console + + py -m venv + .\\Scripts\activate + pip install google-cloud-logging + +Next Steps +~~~~~~~~~~ + +- Read the `Client Library Documentation`_ for Cloud Logging API + to see other available methods on the client. +- Read the `Cloud Logging API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Cloud Logging API Product documentation: https://cloud.google.com/logging/docs/ +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst + +Logging +------- + +This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes. +Note the following: + +#. Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or on Google Cloud Logging. +#. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. +#. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. + +Simple, environment-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable logging for this library without any changes in your code, set the :code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to a valid Google +logging scope. This configures handling of logging events (at level :code:`logging.DEBUG` or higher) from this library in a default manner, emitting the logged +messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging +event. + +A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. + +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Enabling the default handler for all Google-based loggers + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +- Enabling the default handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_v1 + + +Advanced, code-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also configure a valid logging scope using Python's standard `logging` mechanism. + +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ + +- Configuring a handler for all Google-based loggers + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +- Configuring a handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google.cloud.library_v1") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +Logging details +~~~~~~~~~~~~~~~ + +#. Regardless of which of the mechanisms above you use to configure logging for this library, by default logging events are not propagated up to the root + logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set + :code:`logging.getLogger("google").propagate = True` in your code. +#. You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for + one library, but decide you need to also set up environment-based logging configuration for another library. + + #. If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual + if the code -based configuration gets applied first. + +#. The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get + executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured. + (This is the reason for 2.i. above.) diff --git a/tests/integration/goldens/logging_internal/docs/index.rst b/tests/integration/goldens/logging_internal/docs/index.rst index 2be5cab965..c2396cfc34 100755 --- a/tests/integration/goldens/logging_internal/docs/index.rst +++ b/tests/integration/goldens/logging_internal/docs/index.rst @@ -1,3 +1,5 @@ +.. include:: README.rst + .. include:: multiprocessing.rst @@ -8,3 +10,19 @@ API Reference logging_v2/services_ logging_v2/types_ + + +Changelog +--------- + +For a list of all ``google-cloud-logging`` releases: + +.. toctree:: + :maxdepth: 2 + + CHANGELOG + +.. toctree:: + :hidden: + + summary_overview.md diff --git a/tests/integration/goldens/logging_internal/docs/summary_overview.md b/tests/integration/goldens/logging_internal/docs/summary_overview.md new file mode 100755 index 0000000000..4786fbcaab --- /dev/null +++ b/tests/integration/goldens/logging_internal/docs/summary_overview.md @@ -0,0 +1,22 @@ +[ +This is a templated file. Adding content to this file may result in it being +reverted. Instead, if you want to place additional content, create an +"overview_content.md" file in `docs/` directory. The Sphinx tool will +pick up on the content and merge the content. +]: # + +# Cloud Logging API + +Overview of the APIs available for Cloud Logging API. + +## All entries + +Classes, methods and properties & attributes for +Cloud Logging API. + +[classes](https://cloud.google.com/python/docs/reference/logging/latest/summary_class.html) + +[methods](https://cloud.google.com/python/docs/reference/logging/latest/summary_method.html) + +[properties and +attributes](https://cloud.google.com/python/docs/reference/logging/latest/summary_property.html) diff --git a/tests/integration/goldens/redis/README.rst b/tests/integration/goldens/redis/README.rst index 2ad783a17a..baaef77753 100755 --- a/tests/integration/goldens/redis/README.rst +++ b/tests/integration/goldens/redis/README.rst @@ -1,5 +1,22 @@ -Python Client for Google Cloud Redis API -================================================= +Python Client for Google Cloud Memorystore for Redis API +======================================================== + +|preview| |pypi| |versions| + +`Google Cloud Memorystore for Redis API`_: Creates and manages Redis instances on the Google Cloud Platform. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-redis.svg + :target: https://pypi.org/project/google-cloud-redis/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-redis.svg + :target: https://pypi.org/project/google-cloud-redis/ +.. _Google Cloud Memorystore for Redis API: https://cloud.google.com/memorystore/docs/redis/ +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/redis/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/memorystore/docs/redis/ Quick Start ----------- @@ -8,26 +25,55 @@ In order to use this library, you first need to go through the following steps: 1. `Select or create a Cloud Platform project.`_ 2. `Enable billing for your project.`_ -3. Enable the Google Cloud Redis API. -4. `Setup Authentication.`_ +3. `Enable the Google Cloud Memorystore for Redis API.`_ +4. `Set up Authentication.`_ .. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project .. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project -.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html +.. _Enable the Google Cloud Memorystore for Redis API.: https://cloud.google.com/memorystore/docs/redis/ +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html Installation ~~~~~~~~~~~~ -Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to -create isolated Python environments. The basic problem it addresses is one of -dependencies and versions, and indirectly permissions. +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. -With `virtualenv`_, it's possible to install this library without needing system +With `venv`_, it's possible to install this library without needing system install permissions, and without clashing with the installed system dependencies. -.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-redis/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches Mac/Linux ^^^^^^^^^ @@ -36,7 +82,7 @@ Mac/Linux python3 -m venv source /bin/activate - /bin/pip install /path/to/library + pip install google-cloud-redis Windows @@ -44,10 +90,22 @@ Windows .. code-block:: console - python3 -m venv - \Scripts\activate - \Scripts\pip.exe install \path\to\library + py -m venv + .\\Scripts\activate + pip install google-cloud-redis + +Next Steps +~~~~~~~~~~ +- Read the `Client Library Documentation`_ for Google Cloud Memorystore for Redis API + to see other available methods on the client. +- Read the `Google Cloud Memorystore for Redis API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Google Cloud Memorystore for Redis API Product documentation: https://cloud.google.com/memorystore/docs/redis/ +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst Logging ------- @@ -59,7 +117,6 @@ Note the following: #. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. #. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. - Simple, environment-based configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -75,9 +132,8 @@ A logging scope is a period-separated namespace that begins with :code:`google`, **NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. - -Examples -^^^^^^^^ +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Enabling the default handler for all Google-based loggers @@ -97,9 +153,8 @@ Advanced, code-based configuration You can also configure a valid logging scope using Python's standard `logging` mechanism. - -Examples -^^^^^^^^ +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ - Configuring a handler for all Google-based loggers @@ -107,7 +162,7 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google") base_logger.addHandler(logging.StreamHandler()) @@ -119,13 +174,12 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google.cloud.library_v1") base_logger.addHandler(logging.StreamHandler()) base_logger.setLevel(logging.DEBUG) - Logging details ~~~~~~~~~~~~~~~ diff --git a/tests/integration/goldens/redis/docs/README.rst b/tests/integration/goldens/redis/docs/README.rst new file mode 100755 index 0000000000..baaef77753 --- /dev/null +++ b/tests/integration/goldens/redis/docs/README.rst @@ -0,0 +1,197 @@ +Python Client for Google Cloud Memorystore for Redis API +======================================================== + +|preview| |pypi| |versions| + +`Google Cloud Memorystore for Redis API`_: Creates and manages Redis instances on the Google Cloud Platform. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-redis.svg + :target: https://pypi.org/project/google-cloud-redis/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-redis.svg + :target: https://pypi.org/project/google-cloud-redis/ +.. _Google Cloud Memorystore for Redis API: https://cloud.google.com/memorystore/docs/redis/ +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/redis/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/memorystore/docs/redis/ + +Quick Start +----------- + +In order to use this library, you first need to go through the following steps: + +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Google Cloud Memorystore for Redis API.`_ +4. `Set up Authentication.`_ + +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project +.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project +.. _Enable the Google Cloud Memorystore for Redis API.: https://cloud.google.com/memorystore/docs/redis/ +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html + +Installation +~~~~~~~~~~~~ + +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. + +With `venv`_, it's possible to install this library without needing system +install permissions, and without clashing with the installed system +dependencies. + +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-redis/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 + +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches + +Mac/Linux +^^^^^^^^^ + +.. code-block:: console + + python3 -m venv + source /bin/activate + pip install google-cloud-redis + + +Windows +^^^^^^^ + +.. code-block:: console + + py -m venv + .\\Scripts\activate + pip install google-cloud-redis + +Next Steps +~~~~~~~~~~ + +- Read the `Client Library Documentation`_ for Google Cloud Memorystore for Redis API + to see other available methods on the client. +- Read the `Google Cloud Memorystore for Redis API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Google Cloud Memorystore for Redis API Product documentation: https://cloud.google.com/memorystore/docs/redis/ +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst + +Logging +------- + +This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes. +Note the following: + +#. Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or on Google Cloud Logging. +#. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. +#. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. + +Simple, environment-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable logging for this library without any changes in your code, set the :code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to a valid Google +logging scope. This configures handling of logging events (at level :code:`logging.DEBUG` or higher) from this library in a default manner, emitting the logged +messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging +event. + +A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. + +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Enabling the default handler for all Google-based loggers + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +- Enabling the default handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_v1 + + +Advanced, code-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also configure a valid logging scope using Python's standard `logging` mechanism. + +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ + +- Configuring a handler for all Google-based loggers + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +- Configuring a handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google.cloud.library_v1") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +Logging details +~~~~~~~~~~~~~~~ + +#. Regardless of which of the mechanisms above you use to configure logging for this library, by default logging events are not propagated up to the root + logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set + :code:`logging.getLogger("google").propagate = True` in your code. +#. You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for + one library, but decide you need to also set up environment-based logging configuration for another library. + + #. If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual + if the code -based configuration gets applied first. + +#. The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get + executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured. + (This is the reason for 2.i. above.) diff --git a/tests/integration/goldens/redis/docs/index.rst b/tests/integration/goldens/redis/docs/index.rst index 59c3a95dee..d650e5acd9 100755 --- a/tests/integration/goldens/redis/docs/index.rst +++ b/tests/integration/goldens/redis/docs/index.rst @@ -1,3 +1,5 @@ +.. include:: README.rst + .. include:: multiprocessing.rst @@ -8,3 +10,19 @@ API Reference redis_v1/services_ redis_v1/types_ + + +Changelog +--------- + +For a list of all ``google-cloud-redis`` releases: + +.. toctree:: + :maxdepth: 2 + + CHANGELOG + +.. toctree:: + :hidden: + + summary_overview.md diff --git a/tests/integration/goldens/redis/docs/summary_overview.md b/tests/integration/goldens/redis/docs/summary_overview.md new file mode 100755 index 0000000000..7a5488c2e0 --- /dev/null +++ b/tests/integration/goldens/redis/docs/summary_overview.md @@ -0,0 +1,22 @@ +[ +This is a templated file. Adding content to this file may result in it being +reverted. Instead, if you want to place additional content, create an +"overview_content.md" file in `docs/` directory. The Sphinx tool will +pick up on the content and merge the content. +]: # + +# Google Cloud Memorystore for Redis API + +Overview of the APIs available for Google Cloud Memorystore for Redis API. + +## All entries + +Classes, methods and properties & attributes for +Google Cloud Memorystore for Redis API. + +[classes](https://cloud.google.com/python/docs/reference/redis/latest/summary_class.html) + +[methods](https://cloud.google.com/python/docs/reference/redis/latest/summary_method.html) + +[properties and +attributes](https://cloud.google.com/python/docs/reference/redis/latest/summary_property.html) diff --git a/tests/integration/goldens/redis_selective/README.rst b/tests/integration/goldens/redis_selective/README.rst index 2ad783a17a..b1172d13a5 100755 --- a/tests/integration/goldens/redis_selective/README.rst +++ b/tests/integration/goldens/redis_selective/README.rst @@ -1,5 +1,22 @@ -Python Client for Google Cloud Redis API -================================================= +Python Client for Google Cloud Memorystore for Redis API +======================================================== + +|preview| |pypi| |versions| + +`Google Cloud Memorystore for Redis API`_: Creates and manages Redis instances on the Google Cloud Platform. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-redis.svg + :target: https://pypi.org/project/google-cloud-redis/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-redis.svg + :target: https://pypi.org/project/google-cloud-redis/ +.. _Google Cloud Memorystore for Redis API: +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/redis/latest/summary_overview +.. _Product Documentation: Quick Start ----------- @@ -8,26 +25,55 @@ In order to use this library, you first need to go through the following steps: 1. `Select or create a Cloud Platform project.`_ 2. `Enable billing for your project.`_ -3. Enable the Google Cloud Redis API. -4. `Setup Authentication.`_ +3. `Enable the Google Cloud Memorystore for Redis API.`_ +4. `Set up Authentication.`_ .. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project .. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project -.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html +.. _Enable the Google Cloud Memorystore for Redis API.: +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html Installation ~~~~~~~~~~~~ -Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to -create isolated Python environments. The basic problem it addresses is one of -dependencies and versions, and indirectly permissions. +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. -With `virtualenv`_, it's possible to install this library without needing system +With `venv`_, it's possible to install this library without needing system install permissions, and without clashing with the installed system dependencies. -.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-redis/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches Mac/Linux ^^^^^^^^^ @@ -36,7 +82,7 @@ Mac/Linux python3 -m venv source /bin/activate - /bin/pip install /path/to/library + pip install google-cloud-redis Windows @@ -44,10 +90,22 @@ Windows .. code-block:: console - python3 -m venv - \Scripts\activate - \Scripts\pip.exe install \path\to\library + py -m venv + .\\Scripts\activate + pip install google-cloud-redis + +Next Steps +~~~~~~~~~~ +- Read the `Client Library Documentation`_ for Google Cloud Memorystore for Redis API + to see other available methods on the client. +- Read the `Google Cloud Memorystore for Redis API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Google Cloud Memorystore for Redis API Product documentation: +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst Logging ------- @@ -59,7 +117,6 @@ Note the following: #. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. #. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. - Simple, environment-based configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -75,9 +132,8 @@ A logging scope is a period-separated namespace that begins with :code:`google`, **NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. - -Examples -^^^^^^^^ +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Enabling the default handler for all Google-based loggers @@ -97,9 +153,8 @@ Advanced, code-based configuration You can also configure a valid logging scope using Python's standard `logging` mechanism. - -Examples -^^^^^^^^ +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ - Configuring a handler for all Google-based loggers @@ -107,7 +162,7 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google") base_logger.addHandler(logging.StreamHandler()) @@ -119,13 +174,12 @@ Examples import logging - from google.cloud.translate_v3 import translate + from google.cloud import library_v1 base_logger = logging.getLogger("google.cloud.library_v1") base_logger.addHandler(logging.StreamHandler()) base_logger.setLevel(logging.DEBUG) - Logging details ~~~~~~~~~~~~~~~ diff --git a/tests/integration/goldens/redis_selective/docs/README.rst b/tests/integration/goldens/redis_selective/docs/README.rst new file mode 100755 index 0000000000..b1172d13a5 --- /dev/null +++ b/tests/integration/goldens/redis_selective/docs/README.rst @@ -0,0 +1,197 @@ +Python Client for Google Cloud Memorystore for Redis API +======================================================== + +|preview| |pypi| |versions| + +`Google Cloud Memorystore for Redis API`_: Creates and manages Redis instances on the Google Cloud Platform. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-redis.svg + :target: https://pypi.org/project/google-cloud-redis/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-redis.svg + :target: https://pypi.org/project/google-cloud-redis/ +.. _Google Cloud Memorystore for Redis API: +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/redis/latest/summary_overview +.. _Product Documentation: + +Quick Start +----------- + +In order to use this library, you first need to go through the following steps: + +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Google Cloud Memorystore for Redis API.`_ +4. `Set up Authentication.`_ + +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project +.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project +.. _Enable the Google Cloud Memorystore for Redis API.: +.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html + +Installation +~~~~~~~~~~~~ + +Install this library in a virtual environment using `venv`_. `venv`_ is a tool that +creates isolated Python environments. These isolated environments can have separate +versions of Python packages, which allows you to isolate one project's dependencies +from the dependencies of other projects. + +With `venv`_, it's possible to install this library without needing system +install permissions, and without clashing with the installed system +dependencies. + +.. _`venv`: https://docs.python.org/3/library/venv.html + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/`_ folder. + +.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-redis/samples + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.7 + +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 + +If you are using an `end-of-life`_ +version of Python, we recommend that you update as soon as possible to an actively supported version. + +.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches + +Mac/Linux +^^^^^^^^^ + +.. code-block:: console + + python3 -m venv + source /bin/activate + pip install google-cloud-redis + + +Windows +^^^^^^^ + +.. code-block:: console + + py -m venv + .\\Scripts\activate + pip install google-cloud-redis + +Next Steps +~~~~~~~~~~ + +- Read the `Client Library Documentation`_ for Google Cloud Memorystore for Redis API + to see other available methods on the client. +- Read the `Google Cloud Memorystore for Redis API Product documentation`_ to learn + more about the product and see How-to Guides. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _Google Cloud Memorystore for Redis API Product documentation: +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst + +Logging +------- + +This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes. +Note the following: + +#. Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or on Google Cloud Logging. +#. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. +#. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. + +Simple, environment-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable logging for this library without any changes in your code, set the :code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to a valid Google +logging scope. This configures handling of logging events (at level :code:`logging.DEBUG` or higher) from this library in a default manner, emitting the logged +messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging +event. + +A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. + +Environment-Based Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Enabling the default handler for all Google-based loggers + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +- Enabling the default handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_v1 + + +Advanced, code-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also configure a valid logging scope using Python's standard `logging` mechanism. + +Code-Based Examples +^^^^^^^^^^^^^^^^^^^ + +- Configuring a handler for all Google-based loggers + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +- Configuring a handler for a specific Google module (for a client library called :code:`library_v1`): + +.. code-block:: python + + import logging + + from google.cloud import library_v1 + + base_logger = logging.getLogger("google.cloud.library_v1") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + +Logging details +~~~~~~~~~~~~~~~ + +#. Regardless of which of the mechanisms above you use to configure logging for this library, by default logging events are not propagated up to the root + logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set + :code:`logging.getLogger("google").propagate = True` in your code. +#. You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for + one library, but decide you need to also set up environment-based logging configuration for another library. + + #. If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual + if the code -based configuration gets applied first. + +#. The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get + executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured. + (This is the reason for 2.i. above.) diff --git a/tests/integration/goldens/redis_selective/docs/index.rst b/tests/integration/goldens/redis_selective/docs/index.rst index 59c3a95dee..d650e5acd9 100755 --- a/tests/integration/goldens/redis_selective/docs/index.rst +++ b/tests/integration/goldens/redis_selective/docs/index.rst @@ -1,3 +1,5 @@ +.. include:: README.rst + .. include:: multiprocessing.rst @@ -8,3 +10,19 @@ API Reference redis_v1/services_ redis_v1/types_ + + +Changelog +--------- + +For a list of all ``google-cloud-redis`` releases: + +.. toctree:: + :maxdepth: 2 + + CHANGELOG + +.. toctree:: + :hidden: + + summary_overview.md diff --git a/tests/integration/goldens/redis_selective/docs/summary_overview.md b/tests/integration/goldens/redis_selective/docs/summary_overview.md new file mode 100755 index 0000000000..7a5488c2e0 --- /dev/null +++ b/tests/integration/goldens/redis_selective/docs/summary_overview.md @@ -0,0 +1,22 @@ +[ +This is a templated file. Adding content to this file may result in it being +reverted. Instead, if you want to place additional content, create an +"overview_content.md" file in `docs/` directory. The Sphinx tool will +pick up on the content and merge the content. +]: # + +# Google Cloud Memorystore for Redis API + +Overview of the APIs available for Google Cloud Memorystore for Redis API. + +## All entries + +Classes, methods and properties & attributes for +Google Cloud Memorystore for Redis API. + +[classes](https://cloud.google.com/python/docs/reference/redis/latest/summary_class.html) + +[methods](https://cloud.google.com/python/docs/reference/redis/latest/summary_method.html) + +[properties and +attributes](https://cloud.google.com/python/docs/reference/redis/latest/summary_property.html) diff --git a/tests/integration/iamcredentials_v1.yaml b/tests/integration/iamcredentials_v1.yaml index 6f3f05ab34..34a9480bdf 100644 --- a/tests/integration/iamcredentials_v1.yaml +++ b/tests/integration/iamcredentials_v1.yaml @@ -14,4 +14,13 @@ authentication: - selector: 'google.iam.credentials.v1.IAMCredentials.*' oauth: canonical_scopes: |- - https://www.googleapis.com/auth/cloud-platform \ No newline at end of file + https://www.googleapis.com/auth/cloud-platform +publishing: + organization: CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED + new_issue_uri: '' + documentation_uri: 'https://cloud.google.com/iam/docs/reference/credentials/rest' + api_short_name: '' + github_label: '' + doc_tag_prefix: '' + codeowner_github_teams: + library_settings: diff --git a/tests/integration/logging_v2.yaml b/tests/integration/logging_v2.yaml index 7f10ee0bd1..a1adf3a477 100644 --- a/tests/integration/logging_v2.yaml +++ b/tests/integration/logging_v2.yaml @@ -217,5 +217,14 @@ authentication: https://www.googleapis.com/auth/cloud-platform.read-only, https://www.googleapis.com/auth/logging.admin, https://www.googleapis.com/auth/logging.read + publishing: - documentation_uri: https://cloud.google.com/logging/docs/ \ No newline at end of file + documentation_uri: https://cloud.google.com/logging/docs/ + organization: CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED + new_issue_uri: '' + documentation_uri: 'https://cloud.google.com/logging/docs' + api_short_name: '' + github_label: '' + doc_tag_prefix: '' + codeowner_github_teams: + library_settings: diff --git a/tests/integration/redis_v1.yaml b/tests/integration/redis_v1.yaml index efb6675bbf..98775115c3 100644 --- a/tests/integration/redis_v1.yaml +++ b/tests/integration/redis_v1.yaml @@ -72,10 +72,17 @@ authentication: canonical_scopes: |- https://www.googleapis.com/auth/cloud-platform -# TODO(https://github.com/googleapis/gapic-generator-python/issues/2121): Remove this section -# when async rest is GA. publishing: + organization: CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED + new_issue_uri: '' + documentation_uri: 'https://cloud.google.com/memorystore/docs/redis/' + api_short_name: '' + github_label: '' + doc_tag_prefix: '' + codeowner_github_teams: library_settings: + # TODO(https://github.com/googleapis/gapic-generator-python/issues/2121): Remove this section + # when async rest is GA. - version: 'google.cloud.redis.v1' python_settings: experimental_features: diff --git a/tests/unit/generator/test_options.py b/tests/unit/generator/test_options.py index 9c1effb769..cff01aa36f 100644 --- a/tests/unit/generator/test_options.py +++ b/tests/unit/generator/test_options.py @@ -225,6 +225,35 @@ def test_options_autogen_snippets_false_for_old_naming(): assert not options.autogen_snippets +def test_options_reference_doc_includes(): + opts = Options.build("reference-doc-includes=") + assert opts.reference_doc_includes == ("",) + + opts = Options.build("reference-doc-includes=google.apps.script.type.calendar") + assert opts.reference_doc_includes == ("google.apps.script.type.calendar",) + + opts = Options.build( + "reference-doc-includes=\ +google.apps.script.type.calendar+\ +google.apps.script.type.docs+\ +google.apps.script.type.drive+\ +google.apps.script.type.gmail+\ +google.apps.script.type.sheets+\ +google.apps.script.type.slides+\ +google.apps.script.type" + ) + + assert opts.reference_doc_includes == ( + "google.apps.script.type.calendar", + "google.apps.script.type.docs", + "google.apps.script.type.drive", + "google.apps.script.type.gmail", + "google.apps.script.type.sheets", + "google.apps.script.type.slides", + "google.apps.script.type", + ) + + def test_options_proto_plus_deps(): opts = Options.build("proto-plus-deps=") assert opts.proto_plus_deps == ("",) @@ -251,3 +280,60 @@ def test_options_proto_plus_deps(): "google.apps.script.type.slides", "google.apps.script.type", ) + + +def test_read_documentation_name(): + opts = Options.build("documentation-name=testapi") + assert opts.documentation_name == "testapi" + opts = Options.build("documentation-name=") + assert opts.documentation_name == "" + + +def test_read_documentation_uri(fs): + service_yaml_fpath = "testapi.yaml" + fs.create_file( + service_yaml_fpath, + contents=( + "config_version: 3\n" + "name: testapi.googleapis.com\n" + "publishing:\n" + " documentation_uri: https://cloud.google.com/test\n" + ), + ) + opt_string = f"service-yaml={service_yaml_fpath}" + opts = Options.build(opt_string) + assert opts.documentation_uri == "https://cloud.google.com/test" + + +def test_read_api_description(fs): + service_yaml_fpath = "testapi.yaml" + fs.create_file( + service_yaml_fpath, + contents=( + "config_version: 3\n" + "name: testapi.googleapis.com\n" + "documentation:\n" + " summary: |-\n" + " The Google VMware Engine API lets you programmatically manage VMware\n" + " environments." + ), + ) + opt_string = f"service-yaml={service_yaml_fpath}" + opts = Options.build(opt_string) + assert ( + opts.api_description.replace("\n", " ") + == "The Google VMware Engine API lets you programmatically manage VMware environments." + ) + + +def test_read_title(fs): + service_yaml_fpath = "testapi.yaml" + fs.create_file( + service_yaml_fpath, + contents=( + "config_version: 3\n" "name: testapi.googleapis.com\n" "title: Test Title" + ), + ) + opt_string = f"service-yaml={service_yaml_fpath}" + opts = Options.build(opt_string) + assert opts.title == "Test Title" diff --git a/tests/unit/schema/test_naming.py b/tests/unit/schema/test_naming.py index 08612f3bf4..459196bda6 100644 --- a/tests/unit/schema/test_naming.py +++ b/tests/unit/schema/test_naming.py @@ -27,6 +27,16 @@ def test_long_name(): assert n.long_name == "Agrabah Lamp Genie" +def test_title(): + n = make_naming(title="Test Title") + n.title == "Test Title" + + +def test_api_descriptin(): + n = make_naming(api_description="Test Description") + n.api_description == "Test Description" + + def test_module_name(): n = make_naming( name="Genie", @@ -239,6 +249,66 @@ def test_cli_override_proto_plus_deps(): assert n.proto_plus_deps == ("google.dep1", "google.dep2") +def test_cli_override_title(): + FileDesc = descriptor_pb2.FileDescriptorProto + proto1 = FileDesc(package="google.translation") + n = naming.Naming.build( + proto1, + opts=Options(title="Test Title Override"), + ) + assert n.title == "Test Title Override" + + +def test_cli_documentation_name(): + n = naming.Naming.build( + descriptor_pb2.FileDescriptorProto(package="google.translation") + ) + assert n.documentation_name == ("translation") + + +def test_cli_override_documentation_name(): + FileDesc = descriptor_pb2.FileDescriptorProto + proto1 = FileDesc(package="google.translation") + n = naming.Naming.build( + proto1, + opts=Options( + documentation_name="testingapi", warehouse_package_name="google-testing-api" + ), + ) + assert n.documentation_name == ("testingapi") + + +def test_cli_override_api_description(): + FileDesc = descriptor_pb2.FileDescriptorProto + proto1 = FileDesc(package="google.translation") + n = naming.Naming.build( + proto1, + opts=Options(api_description="Test Api Description Override"), + ) + assert n.api_description == "Test Api Description Override" + + +def test_cli_override_documentation_uri(): + FileDesc = descriptor_pb2.FileDescriptorProto + proto1 = FileDesc(package="google.translation") + n = naming.Naming.build( + proto1, + opts=Options(documentation_uri="https://cloud.google.com/testoverride"), + ) + assert n.documentation_uri == "https://cloud.google.com/testoverride" + + +def test_cli_override_default_proto_package(): + FileDesc = descriptor_pb2.FileDescriptorProto + proto1 = FileDesc(package="google.translation.v1") + n = naming.Naming.build( + proto1, + opts=Options(default_proto_package="google.translation.v2"), + ) + assert n.default_proto_package != "google.translation.v1" + + + def test_build_factory(): proto = descriptor_pb2.FileDescriptorProto(package="google.mollusc.v1alpha1") old = naming.Naming.build(proto, opts=Options(old_naming=True))