Skip to content

Commit 37ac520

Browse files
partheaparthea
authored
chore: update stale README.rst files (#14777)
PR #14751 added ability to generate docs/README.rst. As a result, in the subsequent `librarian generate` PR #14776 there were a lot of unrelated changes where stale readmes in the `docs` directory were updated. This PR updates the stale README files.
1 parent b0ce064 commit 37ac520

File tree

20 files changed

+2704
-543
lines changed

20 files changed

+2704
-543
lines changed

‎packages/google-analytics-admin/docs/README.rst‎

Lines changed: 148 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
Python Client for Analytics Admin API
2-
=====================================
1+
Python Client for Analytics Admin
2+
=================================
33

4-
|beta| |pypi| |versions|
4+
|preview| |pypi| |versions|
55

6-
`Analytics Admin API`_
6+
`Analytics Admin`_: allows you to manage Google Analytics accounts and properties.
77

88
- `Client Library Documentation`_
99
- `Product Documentation`_
1010

11-
.. |beta| image:: https://img.shields.io/badge/support-beta-orange.svg
12-
:target: https://github.com/googleapis/google-cloud-python/blob/master/README.rst#beta-support
11+
.. |preview| image:: https://img.shields.io/badge/support-preview-orange.svg
12+
:target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels
1313
.. |pypi| image:: https://img.shields.io/pypi/v/google-analytics-admin.svg
1414
:target: https://pypi.org/project/google-analytics-admin/
1515
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-analytics-admin.svg
1616
:target: https://pypi.org/project/google-analytics-admin/
17-
.. _Analytics Admin API: https://developers.google.com/analytics/
17+
.. _Analytics Admin: https://developers.google.com/analytics/
1818
.. _Client Library Documentation: https://googleapis.dev/python/analyticsadmin/latest
1919
.. _Product Documentation: https://developers.google.com/analytics/
2020

@@ -23,55 +23,175 @@ Quick Start
2323

2424
In order to use this library, you first need to go through the following steps:
2525

26-
1. `Enable the Analytics Admin API.`_
27-
2. `Setup Authentication.`_
28-
3. `Install the library.`_
26+
1. `Select or create a Cloud Platform project.`_
27+
2. `Enable billing for your project.`_
28+
3. `Enable the Analytics Admin.`_
29+
4. `Set up Authentication.`_
2930

30-
.. _Enable the Analytics Admin API.: https://developers.google.com/analytics/devguides/config/admin/v1/quickstart-client-libraries#step_1_enable_the_api
31-
.. _Setup Authentication.: https://developers.google.com/analytics/devguides/config/admin/v1/quickstart-client-libraries#step_2_configure_authentication
32-
.. _Install the library.: https://developers.google.com/analytics/devguides/config/admin/v1/quickstart-client-libraries#step_3_install_the_client_library
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 Analytics Admin.: https://developers.google.com/analytics/
34+
.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
3335

3436
Installation
3537
~~~~~~~~~~~~
3638

37-
Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
38-
create isolated Python environments. The basic problem it addresses is one of
39-
dependencies and versions, and indirectly permissions.
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.
4043

41-
With `virtualenv`_, it's possible to install this library without needing system
44+
With `venv`_, it's possible to install this library without needing system
4245
install permissions, and without clashing with the installed system
4346
dependencies.
4447

45-
.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
48+
.. _`venv`: https://docs.python.org/3/library/venv.html
4649

4750

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/google-analytics-admin/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+
4878
Mac/Linux
4979
^^^^^^^^^
5080

5181
.. code-block:: console
5282
53-
pip install virtualenv
54-
virtualenv <your-env>
83+
python3 -m venv <your-env>
5584
source <your-env>/bin/activate
56-
<your-env>/bin/pip install google-analytics-admin
85+
pip install google-analytics-admin
5786
5887
5988
Windows
6089
^^^^^^^
6190

6291
.. code-block:: console
6392
64-
pip install virtualenv
65-
virtualenv <your-env>
66-
<your-env>\Scripts\activate
67-
<your-env>\Scripts\pip.exe install google-analytics-admin
93+
py -m venv <your-env>
94+
.\<your-env>\Scripts\activate
95+
pip install google-analytics-admin
6896
6997
Next Steps
7098
~~~~~~~~~~
7199

72-
- Read the `Client Library Documentation`_ for Analytics Admin API
100+
- Read the `Client Library Documentation`_ for Analytics Admin
73101
to see other available methods on the client.
74-
- Read the `Analytics Admin API Product documentation`_ to learn
102+
- Read the `Analytics Admin Product documentation`_ to learn
75103
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+
.. _Analytics Admin Product documentation: https://developers.google.com/analytics/
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.
76194

77-
.. _Analytics Admin API Product documentation: https://developers.google.com/analytics/
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.)

0 commit comments

Comments
 (0)