FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

feat: add common_resources.proto (#14851) · googleapis/google-cloud-python@e4e0e2a · GitHub

/ google-cloud-python Public

Commit e4e0e2a

Browse files
parthea
authored
feat: add common_resources.proto (#14851)
This PR depends on #14850 `google/cloud` was not listed as an api path for `googleapis-common-protos` for code was not being generated for https://github.com/googleapis/googleapis/blob/master/google/cloud/extended_operations.proto and https://github.com/googleapis/googleapis/blob/master/google/cloud/common_resources.proto
1 parent 881963d commit e4e0e2a

5 files changed

Lines changed: 319 additions & 2 deletions

File tree

‎.librarian/state.yaml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4448,10 +4448,12 @@ libraries:
44484448
tag_format: '{id}-v{version}'
44494449
- id: googleapis-common-protos
44504450
version: 1.71.0
4451-
last_generated_commit: 91361b6b2df5f7f3bfc0858be061e31fd2b7be98
4451+
last_generated_commit: 53af3b727f84acc34e31c23f3b6e7b8aa4b7e837
44524452
apis:
44534453
- path: google/api
44544454
service_config: serviceconfig.yaml
4455+
- path: google/cloud
4456+
service_config: ""
44554457
- path: google/cloud/location
44564458
service_config: cloud.yaml
44574459
- path: google/logging/type

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

Lines changed: 0 additions & 1 deletion
This file was deleted.

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

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
Python Client for Google APIs Common Protos
2+
===========================================
3+
4+
|stable| |pypi| |versions|
5+
6+
`Google APIs Common Protos`_:
7+
8+
- `Client Library Documentation`_
9+
- `Product Documentation`_
10+
11+
.. |stable| image:: https://img.shields.io/badge/support-stable-gold.svg
12+
:target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels
13+
.. |pypi| image:: https://img.shields.io/pypi/v/googleapis-common-protos.svg
14+
:target: https://pypi.org/project/googleapis-common-protos/
15+
.. |versions| image:: https://img.shields.io/pypi/pyversions/googleapis-common-protos.svg
16+
:target: https://pypi.org/project/googleapis-common-protos/
17+
.. _Google APIs Common Protos: https://github.com/googleapis/googleapis/tree/master/google
18+
.. _Client Library Documentation: https://github.com/googleapis/google-cloud-python/tree/main/packages/googleapis-common-protos/summary_overview
19+
.. _Product Documentation: https://github.com/googleapis/googleapis/tree/master/google
20+
21+
Quick Start
22+
-----------
23+
24+
In order to use this library, you first need to go through the following steps:
25+
26+
1. `Select or create a Cloud Platform project.`_
27+
2. `Enable billing for your project.`_
28+
3. `Enable the Google APIs Common Protos.`_
29+
4. `Set up Authentication.`_
30+
31+
.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
32+
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
33+
.. _Enable the Google APIs Common Protos.: https://github.com/googleapis/googleapis/tree/master/google
34+
.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
35+
36+
Installation
37+
~~~~~~~~~~~~
38+
39+
Install this library in a virtual environment using `venv`_. `venv`_ is a tool that
40+
creates isolated Python environments. These isolated environments can have separate
41+
versions of Python packages, which allows you to isolate one project's dependencies
42+
from the dependencies of other projects.
43+
44+
With `venv`_, it's possible to install this library without needing system
45+
install permissions, and without clashing with the installed system
46+
dependencies.
47+
48+
.. _`venv`: https://docs.python.org/3/library/venv.html
49+
50+
51+
Code samples and snippets
52+
~~~~~~~~~~~~~~~~~~~~~~~~~
53+
54+
Code samples and snippets live in the `samples/`_ folder.
55+
56+
.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/googleapis-common-protos/samples
57+
58+
59+
Supported Python Versions
60+
^^^^^^^^^^^^^^^^^^^^^^^^^
61+
Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of
62+
Python.
63+
64+
Python >= 3.7, including 3.14
65+
66+
.. _active: https://devguide.python.org/devcycle/#in-development-main-branch
67+
.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches
68+
69+
Unsupported Python Versions
70+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
71+
Python <= 3.6
72+
73+
If you are using an `end-of-life`_
74+
version of Python, we recommend that you update as soon as possible to an actively supported version.
75+
76+
.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches
77+
78+
Mac/Linux
79+
^^^^^^^^^
80+
81+
.. code-block:: console
82+
83+
python3 -m venv <your-env>
84+
source <your-env>/bin/activate
85+
pip install googleapis-common-protos
86+
87+
88+
Windows
89+
^^^^^^^
90+
91+
.. code-block:: console
92+
93+
py -m venv <your-env>
94+
.\<your-env>\Scripts\activate
95+
pip install googleapis-common-protos
96+
97+
Next Steps
98+
~~~~~~~~~~
99+
100+
- Read the `Client Library Documentation`_ for Google APIs Common Protos
101+
to see other available methods on the client.
102+
- Read the `Google APIs Common Protos Product documentation`_ to learn
103+
more about the product and see How-to Guides.
104+
- View this `README`_ to see the full list of Cloud
105+
APIs that we cover.
106+
107+
.. _Google APIs Common Protos Product documentation: https://github.com/googleapis/googleapis/tree/master/google
108+
.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst
109+
110+
Logging
111+
-------
112+
113+
This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes.
114+
Note the following:
115+
116+
#. 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.
117+
#. 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**.
118+
#. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below.
119+
120+
Simple, environment-based configuration
121+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
122+
123+
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
124+
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
125+
messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging
126+
event.
127+
128+
A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log.
129+
130+
- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc.
131+
- Invalid logging scopes: :code:`foo`, :code:`123`, etc.
132+
133+
**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers.
134+
135+
Environment-Based Examples
136+
^^^^^^^^^^^^^^^^^^^^^^^^^^
137+
138+
- Enabling the default handler for all Google-based loggers
139+
140+
.. code-block:: console
141+
142+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google
143+
144+
- Enabling the default handler for a specific Google module (for a client library called :code:`library_v1`):
145+
146+
.. code-block:: console
147+
148+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_v1
149+
150+
151+
Advanced, code-based configuration
152+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
153+
154+
You can also configure a valid logging scope using Python's standard `logging` mechanism.
155+
156+
Code-Based Examples
157+
^^^^^^^^^^^^^^^^^^^
158+
159+
- Configuring a handler for all Google-based loggers
160+
161+
.. code-block:: python
162+
163+
import logging
164+
165+
from google.cloud import library_v1
166+
167+
base_logger = logging.getLogger("google")
168+
base_logger.addHandler(logging.StreamHandler())
169+
base_logger.setLevel(logging.DEBUG)
170+
171+
- Configuring a handler for a specific Google module (for a client library called :code:`library_v1`):
172+
173+
.. code-block:: python
174+
175+
import logging
176+
177+
from google.cloud import library_v1
178+
179+
base_logger = logging.getLogger("google.cloud.library_v1")
180+
base_logger.addHandler(logging.StreamHandler())
181+
base_logger.setLevel(logging.DEBUG)
182+
183+
Logging details
184+
~~~~~~~~~~~~~~~
185+
186+
#. 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
187+
logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set
188+
:code:`logging.getLogger("google").propagate = True` in your code.
189+
#. You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for
190+
one library, but decide you need to also set up environment-based logging configuration for another library.
191+
192+
#. If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual
193+
if the code -based configuration gets applied first.
194+
195+
#. The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get
196+
executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured.
197+
(This is the reason for 2.i. above.)

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

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Copyright 2025 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
// This file contains stub messages for common resources in GCP.
16+
// It is not intended to be directly generated, and is instead used by
17+
// other tooling to be able to match common resource patterns.
18+
syntax = "proto3";
19+
20+
package google.cloud;
21+
22+
import "google/api/resource.proto";
23+
24+
25+
option (google.api.resource_definition) = {
26+
type: "cloudresourcemanager.googleapis.com/Project"
27+
pattern: "projects/{project}"
28+
};
29+
30+
31+
option (google.api.resource_definition) = {
32+
type: "cloudresourcemanager.googleapis.com/Organization"
33+
pattern: "organizations/{organization}"
34+
};
35+
36+
37+
option (google.api.resource_definition) = {
38+
type: "cloudresourcemanager.googleapis.com/Folder"
39+
pattern: "folders/{folder}"
40+
};
41+
42+
43+
option (google.api.resource_definition) = {
44+
type: "cloudbilling.googleapis.com/BillingAccount"
45+
pattern: "billingAccounts/{billing_account}"
46+
};
47+
48+
option (google.api.resource_definition) = {
49+
type: "locations.googleapis.com/Location"
50+
pattern: "projects/{project}/locations/{location}"
51+
};
52+

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

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# -*- coding: utf-8 -*-
2+
3+
# Copyright 2025 Google LLC
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
# Generated by the protocol buffer compiler. DO NOT EDIT!
18+
# source: google/cloud/common_resources.proto
19+
# Protobuf Python Version: 4.25.3
20+
"""Generated protocol buffer code."""
21+
from google.protobuf import descriptor as _descriptor
22+
from google.protobuf import descriptor_pool as _descriptor_pool
23+
from google.protobuf import symbol_database as _symbol_database
24+
from google.protobuf.internal import builder as _builder
25+
26+
# @@protoc_insertion_point(imports)
27+
28+
_sym_db = _symbol_database.Default()
29+
30+
31+
from google.api import resource_pb2 as google_dot_api_dot_resource__pb2
32+
33+
DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
34+
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"
35+
)
36+
37+
_globals = globals()
38+
_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
39+
_builder.BuildTopDescriptorsAndMessages(
40+
DESCRIPTOR, "google.cloud.common_resources_pb2", _globals
41+
)
42+
if _descriptor._USE_C_DESCRIPTORS == False:
43+
_globals["DESCRIPTOR"]._options = None
44+
_globals[
45+
"DESCRIPTOR"
46+
]._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}"
47+
# @@protoc_insertion_point(module_scope)

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

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Copyright 2025 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
from typing import ClassVar as _ClassVar
16+
17+
from google.api import resource_pb2 as _resource_pb2
18+
from google.protobuf import descriptor as _descriptor
19+
20+
DESCRIPTOR: _descriptor.FileDescriptor

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL