feat: add common_resources.proto

.librarian/state.yaml

@@ -4447,10 +4447,12 @@ libraries:
     tag_format: '{id}-v{version}'
   - id: googleapis-common-protos
     version: 1.71.0
-    last_generated_commit: 91361b6b2df5f7f3bfc0858be061e31fd2b7be98
+    last_generated_commit: 53af3b727f84acc34e31c23f3b6e7b8aa4b7e837
     apis:
       - path: google/api
         service_config: serviceconfig.yaml
+      - path: google/cloud
+        service_config: ""
       - path: google/cloud/location
         service_config: cloud.yaml
       - path: google/logging/type
@@ -4465,7 +4467,10 @@ libraries:
       - packages/googleapis-common-protos
     preserve_regex: []
     remove_regex:
-      - ^packages/googleapis-common-protos/google/(?:api|cloud|rpc|type)/.*/.*_pb2\.(?:py|pyi)$/
+      - ^packages/googleapis-common-protos/google/(?:api|cloud|logging|rpc|type)/.*(?:\.proto|_pb2\.(?:py|pyi))$
+      - .repo-metadata.json
+      - README.rst
+      - docs/summary_overview.md
     tag_format: '{id}-v{version}'
   - id: grafeas
     version: 1.16.0

packages/googleapis-common-protos/docs/README.rst

@@ -0,0 +1,197 @@
+Python Client for Google APIs Common Protos
+===========================================
+
+|stable| |pypi| |versions|
+
+`Google APIs Common Protos`_: 
+
+- `Client Library Documentation`_
+- `Product Documentation`_
+
+.. |stable| image:: https://img.shields.io/badge/support-stable-gold.svg
+   :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels
+.. |pypi| image:: https://img.shields.io/pypi/v/googleapis-common-protos.svg
+   :target: https://pypi.org/project/googleapis-common-protos/
+.. |versions| image:: https://img.shields.io/pypi/pyversions/googleapis-common-protos.svg
+   :target: https://pypi.org/project/googleapis-common-protos/
+.. _Google APIs Common Protos: https://github.com/googleapis/googleapis/tree/master/google
+.. _Client Library Documentation: https://github.com/googleapis/google-cloud-python/tree/main/packages/googleapis-common-protos/summary_overview
+.. _Product Documentation:  https://github.com/googleapis/googleapis/tree/master/google
+
+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 APIs Common Protos.`_
+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 APIs Common Protos.:  https://github.com/googleapis/googleapis/tree/master/google
+.. _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/googleapis-common-protos/samples
+
+
+Supported Python Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of
+Python.
+
+Python >= 3.7, including 3.14
+
+.. _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 <your-env>
+    source <your-env>/bin/activate
+    pip install googleapis-common-protos
+
+
+Windows
+^^^^^^^
+
+.. code-block:: console
+
+    py -m venv <your-env>
+    .\<your-env>\Scripts\activate
+    pip install googleapis-common-protos
+
+Next Steps
+~~~~~~~~~~
+
+-  Read the `Client Library Documentation`_ for Google APIs Common Protos
+   to see other available methods on the client.
+-  Read the `Google APIs Common Protos 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 APIs Common Protos Product documentation:  https://github.com/googleapis/googleapis/tree/master/google
+.. _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.)

packages/googleapis-common-protos/google/cloud/common_resources.proto

@@ -0,0 +1,52 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// This file contains stub messages for common resources in GCP.
+// It is not intended to be directly generated, and is instead used by
+// other tooling to be able to match common resource patterns.
+syntax = "proto3";
+
+package google.cloud;
+
+import "google/api/resource.proto";
+
+
+option (google.api.resource_definition) = {
+  type: "cloudresourcemanager.googleapis.com/Project"
+  pattern: "projects/{project}"
+};
+
+
+option (google.api.resource_definition) = {
+  type: "cloudresourcemanager.googleapis.com/Organization"
+  pattern: "organizations/{organization}"
+};
+
+
+option (google.api.resource_definition) = {
+  type: "cloudresourcemanager.googleapis.com/Folder"
+  pattern: "folders/{folder}"
+};
+
+
+option (google.api.resource_definition) = {
+  type: "cloudbilling.googleapis.com/BillingAccount"
+  pattern: "billingAccounts/{billing_account}"
+};
+
+option (google.api.resource_definition) = {
+  type: "locations.googleapis.com/Location"
+  pattern: "projects/{project}/locations/{location}"
+};
+

packages/googleapis-common-protos/google/cloud/common_resources_pb2.py

@@ -0,0 +1,47 @@
+# -*- coding: utf-8 -*-
+
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: google/cloud/common_resources.proto
+# Protobuf Python Version: 4.25.3
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.api import resource_pb2 as google_dot_api_dot_resource__pb2
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
+    b"\n#google/cloud/common_resources.proto\x12\x0cgoogle.cloud\x1a\x19google/api/resource.protoB\xf9\x02\xea\x41\x41\n+cloudresourcemanager.googleapis.com/Project\x12\x12projects/{project}\xea\x41P\n0cloudresourcemanager.googleapis.com/Organization\x12\x1corganizations/{organization}\xea\x41>\n*cloudresourcemanager.googleapis.com/Folder\x12\x10\x66olders/{folder}\xea\x41O\n*cloudbilling.googleapis.com/BillingAccount\x12!billingAccounts/{billing_account}\xea\x41L\n!locations.googleapis.com/Location\x12'projects/{project}/locations/{location}b\x06proto3"
+)
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(
+    DESCRIPTOR, "google.cloud.common_resources_pb2", _globals
+)
+if _descriptor._USE_C_DESCRIPTORS == False:
+    _globals["DESCRIPTOR"]._options = None
+    _globals[
+        "DESCRIPTOR"
+    ]._serialized_options = b"\352AA\n+cloudresourcemanager.googleapis.com/Project\022\022projects/{project}\352AP\n0cloudresourcemanager.googleapis.com/Organization\022\034organizations/{organization}\352A>\n*cloudresourcemanager.googleapis.com/Folder\022\020folders/{folder}\352AO\n*cloudbilling.googleapis.com/BillingAccount\022!billingAccounts/{billing_account}\352AL\n!locations.googleapis.com/Location\022'projects/{project}/locations/{location}"
+# @@protoc_insertion_point(module_scope)

packages/googleapis-common-protos/google/cloud/common_resources_pb2.pyi

@@ -0,0 +1,20 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import ClassVar as _ClassVar
+
+from google.api import resource_pb2 as _resource_pb2
+from google.protobuf import descriptor as _descriptor
+
+DESCRIPTOR: _descriptor.FileDescriptor