From 0a0707478dc8aa2e06c5cc6bd19d905ac0eaf96c Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Wed, 15 Apr 2026 11:56:13 +0000 Subject: [PATCH] chore: replace symlinks with copies for README.rst --- packages/bigquery-magics/docs/README.rst | 104 +++++++++- packages/db-dtypes/docs/README.rst | 64 +++++- packages/google-auth-httplib2/docs/README.rst | 50 ++++- .../google-cloud-bigquery/docs/README.rst | 142 ++++++++++++- packages/google-cloud-core/docs/README.rst | 41 +++- packages/google-cloud-dns/docs/README.rst | 110 +++++++++- .../docs/README.rst | 115 ++++++++++- .../docs/README.rst | 190 +++++++++++++++++- .../google-resumable-media/docs/README.rst | 33 ++- 9 files changed, 840 insertions(+), 9 deletions(-) mode change 120000 => 100644 packages/bigquery-magics/docs/README.rst mode change 120000 => 100644 packages/db-dtypes/docs/README.rst mode change 120000 => 100644 packages/google-auth-httplib2/docs/README.rst mode change 120000 => 100644 packages/google-cloud-bigquery/docs/README.rst mode change 120000 => 100644 packages/google-cloud-core/docs/README.rst mode change 120000 => 100644 packages/google-cloud-dns/docs/README.rst mode change 120000 => 100644 packages/google-cloud-documentai-toolbox/docs/README.rst mode change 120000 => 100644 packages/google-cloud-runtimeconfig/docs/README.rst mode change 120000 => 100644 packages/google-resumable-media/docs/README.rst diff --git a/packages/bigquery-magics/docs/README.rst b/packages/bigquery-magics/docs/README.rst deleted file mode 120000 index 89a0106941ff..000000000000 --- a/packages/bigquery-magics/docs/README.rst +++ /dev/null @@ -1 +0,0 @@ -../README.rst \ No newline at end of file diff --git a/packages/bigquery-magics/docs/README.rst b/packages/bigquery-magics/docs/README.rst new file mode 100644 index 000000000000..dd8f041ffa16 --- /dev/null +++ b/packages/bigquery-magics/docs/README.rst @@ -0,0 +1,103 @@ +IPython Magics for BigQuery +=========================== + +|GA| |pypi| |versions| + +Querying massive datasets can be time consuming and expensive without the +right hardware and infrastructure. Google `BigQuery`_ solves this problem by +enabling super-fast, SQL queries against append-mostly tables, using the +processing power of Google's infrastructure. + +- `Library Documentation`_ +- `Product Documentation`_ + +.. |GA| image:: https://img.shields.io/badge/support-GA-gold.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability +.. |pypi| image:: https://img.shields.io/pypi/v/bigquery-magics.svg + :target: https://pypi.org/project/bigquery-magics/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/bigquery-magics.svg + :target: https://pypi.org/project/bigquery-magics/ +.. _BigQuery: https://cloud.google.com/bigquery/what-is-bigquery +.. _Library Documentation: https://googleapis.dev/python/bigquery-magics/latest +.. _Product Documentation: https://cloud.google.com/bigquery/docs/reference/v2/ + +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 BigQuery API.`_ +4. `Setup 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 BigQuery API.: https://cloud.google.com/bigquery +.. _Setup 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. + +With `virtualenv`_, 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/ + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Python >= 3.9 + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.8. + + +Mac/Linux +^^^^^^^^^ + +.. code-block:: console + + pip install virtualenv + virtualenv + source /bin/activate + /bin/pip install bigquery-magics + + +Windows +^^^^^^^ + +.. code-block:: console + + pip install virtualenv + virtualenv + \Scripts\activate + \Scripts\pip.exe install bigquery-magics + +Example Usage +------------- + +To use these magics, you must first register them. Run the ``%load_ext bigquery_magics`` +in a Jupyter notebook cell. + +.. code-block:: + + %load_ext bigquery_magics + +Perform a query +~~~~~~~~~~~~~~~ + +.. code:: python + + %%bigquery + SELECT name, SUM(number) as count + FROM 'bigquery-public-data.usa_names.usa_1910_current' + GROUP BY name + ORDER BY count DESC + LIMIT 3 diff --git a/packages/db-dtypes/docs/README.rst b/packages/db-dtypes/docs/README.rst deleted file mode 120000 index 89a0106941ff..000000000000 --- a/packages/db-dtypes/docs/README.rst +++ /dev/null @@ -1 +0,0 @@ -../README.rst \ No newline at end of file diff --git a/packages/db-dtypes/docs/README.rst b/packages/db-dtypes/docs/README.rst new file mode 100644 index 000000000000..eab2705e2487 --- /dev/null +++ b/packages/db-dtypes/docs/README.rst @@ -0,0 +1,63 @@ +Pandas Data Types for SQL systems (BigQuery, Spanner) +===================================================== + +|ga| |pypi| |versions| + +`Pandas extension data types`_ for data from SQL systems such as `BigQuery`_. + +- `Library Documentation`_ + +.. |ga| image:: https://img.shields.io/badge/support-GA-gold.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability +.. |pypi| image:: https://img.shields.io/pypi/v/db-dtypes.svg + :target: https://pypi.org/project/db-dtypes/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/db-dtypes.svg + :target: https://pypi.org/project/db-dtypes/ +.. _Pandas extension data types: https://pandas.pydata.org/docs/development/extending.html#extension-types +.. _BigQuery: https://cloud.google.com/bigquery/docs/ +.. _Library Documentation: https://googleapis.dev/python/db-dtypes/latest + + +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. + +With `virtualenv`_, 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/ + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Python >= 3.9 + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.8. + + +Mac/Linux +^^^^^^^^^ + +.. code-block:: console + + pip install virtualenv + virtualenv + source /bin/activate + /bin/pip install db-dtypes + + +Windows +^^^^^^^ + +.. code-block:: console + + pip install virtualenv + virtualenv + \Scripts\activate + \Scripts\pip.exe install db-dtypes diff --git a/packages/google-auth-httplib2/docs/README.rst b/packages/google-auth-httplib2/docs/README.rst deleted file mode 120000 index 89a0106941ff..000000000000 --- a/packages/google-auth-httplib2/docs/README.rst +++ /dev/null @@ -1 +0,0 @@ -../README.rst \ No newline at end of file diff --git a/packages/google-auth-httplib2/docs/README.rst b/packages/google-auth-httplib2/docs/README.rst new file mode 100644 index 000000000000..2b7af77f51cd --- /dev/null +++ b/packages/google-auth-httplib2/docs/README.rst @@ -0,0 +1,49 @@ +``httplib2`` Transport for Google Auth +====================================== + +.. image:: https://img.shields.io/badge/status-deprecated-red.svg + :target: https://github.com/httplib2/httplib2 + +The library was created to help clients migrate from `oauth2client `_ to `google-auth`_, however this library is no longer maintained. For any new usages please see provided transport layers by `google-auth`_ library. + + +Documentation +------------- + +`httplib2 Transport for Google Auth Documentation`_ + + +Introduction +------------ +|pypi| + +This library provides an `httplib2`_ transport for `google-auth`_. + +.. note:: ``httplib`` has lots of problems such as lack of threadsafety + and insecure usage of TLS. Using it is highly discouraged. This + library is intended to help existing users of ``oauth2client`` migrate to + ``google-auth``. + +.. |pypi| image:: https://img.shields.io/pypi/v/google-auth-httplib2.svg + :target: https://pypi.python.org/pypi/google-auth-httplib2 + +.. _httplib2: https://github.com/httplib2/httplib2 +.. _httplib2 Transport for Google Auth Documentation: https://googleapis.dev/python/google-auth-httplib2/latest +.. _google-auth: https://github.com/GoogleCloudPlatform/google-auth-library-python/ + + +Installing +---------- + +You can install using `pip`_:: + + $ pip install google-auth-httplib2 + +.. _pip: https://pip.pypa.io/en/stable/ + +License +------- + +Apache 2.0 - See `the LICENSE`_ for more information. + +.. _the LICENSE: https://github.com/GoogleCloudPlatform/google-auth-library-python/blob/main/LICENSE diff --git a/packages/google-cloud-bigquery/docs/README.rst b/packages/google-cloud-bigquery/docs/README.rst deleted file mode 120000 index 89a0106941ff..000000000000 --- a/packages/google-cloud-bigquery/docs/README.rst +++ /dev/null @@ -1 +0,0 @@ -../README.rst \ No newline at end of file diff --git a/packages/google-cloud-bigquery/docs/README.rst b/packages/google-cloud-bigquery/docs/README.rst new file mode 100644 index 000000000000..23ed9257ddc4 --- /dev/null +++ b/packages/google-cloud-bigquery/docs/README.rst @@ -0,0 +1,141 @@ +Python Client for Google BigQuery +================================= + +|GA| |pypi| |versions| + +Querying massive datasets can be time consuming and expensive without the +right hardware and infrastructure. Google `BigQuery`_ solves this problem by +enabling super-fast, SQL queries against append-mostly tables, using the +processing power of Google's infrastructure. + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |GA| image:: https://img.shields.io/badge/support-GA-gold.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-bigquery.svg + :target: https://pypi.org/project/google-cloud-bigquery/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-bigquery.svg + :target: https://pypi.org/project/google-cloud-bigquery/ +.. _BigQuery: https://cloud.google.com/bigquery/what-is-bigquery +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/bigquery/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/bigquery/docs/reference/v2/ + +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 BigQuery API.`_ +4. `Setup 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 BigQuery API.: https://cloud.google.com/bigquery +.. _Setup 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. + +With `virtualenv`_, 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/ + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Python >= 3.9 + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python == 2.7, Python == 3.5, Python == 3.6, Python == 3.7, and Python == 3.8. + +The last version of this library compatible with Python 2.7 and 3.5 is +`google-cloud-bigquery==1.28.0`. + + +Mac/Linux +^^^^^^^^^ + +.. code-block:: console + + pip install virtualenv + virtualenv + source /bin/activate + /bin/pip install google-cloud-bigquery + + +Windows +^^^^^^^ + +.. code-block:: console + + pip install virtualenv + virtualenv + \Scripts\activate + \Scripts\pip.exe install google-cloud-bigquery + +Example Usage +------------- + +Perform a query +~~~~~~~~~~~~~~~ + +.. code:: python + + from google.cloud import bigquery + + client = bigquery.Client() + + # Perform a query. + QUERY = ( + 'SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` ' + 'WHERE state = "TX" ' + 'LIMIT 100') + query_job = client.query(QUERY) # API request + rows = query_job.result() # Waits for query to finish + + for row in rows: + print(row.name) + +Instrumenting With OpenTelemetry +-------------------------------- + +This application uses `OpenTelemetry`_ to output tracing data from +API calls to BigQuery. To enable OpenTelemetry tracing in +the BigQuery client the following PyPI packages need to be installed: + +.. _OpenTelemetry: https://opentelemetry.io + +.. code-block:: console + + pip install google-cloud-bigquery[opentelemetry] opentelemetry-exporter-gcp-trace + +After installation, OpenTelemetry can be used in the BigQuery +client and in BigQuery jobs. First, however, an exporter must be +specified for where the trace data will be outputted to. An +example of this can be found here: + +.. code-block:: python + + from opentelemetry import trace + from opentelemetry.sdk.trace import TracerProvider + from opentelemetry.sdk.trace.export import BatchSpanProcessor + from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter + tracer_provider = TracerProvider() + tracer_provider = BatchSpanProcessor(CloudTraceSpanExporter()) + trace.set_tracer_provider(TracerProvider()) + +In this example all tracing data will be published to the Google +`Cloud Trace`_ console. For more information on OpenTelemetry, please consult the `OpenTelemetry documentation`_. + +.. _OpenTelemetry documentation: https://opentelemetry-python.readthedocs.io +.. _Cloud Trace: https://cloud.google.com/trace diff --git a/packages/google-cloud-core/docs/README.rst b/packages/google-cloud-core/docs/README.rst deleted file mode 120000 index 89a0106941ff..000000000000 --- a/packages/google-cloud-core/docs/README.rst +++ /dev/null @@ -1 +0,0 @@ -../README.rst \ No newline at end of file diff --git a/packages/google-cloud-core/docs/README.rst b/packages/google-cloud-core/docs/README.rst new file mode 100644 index 000000000000..bfd89a74e64c --- /dev/null +++ b/packages/google-cloud-core/docs/README.rst @@ -0,0 +1,40 @@ +Core Helpers for Google Cloud Python Client Library +=================================================== + +|pypi| |versions| + +This library is not meant to stand-alone. Instead it defines +common helpers (e.g. base ``Client`` classes) used by all of the +``google-cloud-*`` packages. + + +- `Documentation`_ + +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-core.svg + :target: https://pypi.org/project/google-cloud-core/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-core.svg + :target: https://pypi.org/project/google-cloud-core/ +.. _Documentation: https://cloud.google.com/python/docs/reference/google-cloud-core/latest + +Quick Start +----------- + +.. code-block:: console + + $ pip install --upgrade google-cloud-core + +For more information on setting up your Python development environment, +such as installing ``pip`` and ``virtualenv`` on your system, please refer +to `Python Development Environment Setup Guide`_ for Google Cloud Platform. + +.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup + + +Supported Python Versions +------------------------- +Python >= 3.9 + +Unsupported Python Versions +--------------------------- + +Python <= 3.8 diff --git a/packages/google-cloud-dns/docs/README.rst b/packages/google-cloud-dns/docs/README.rst deleted file mode 120000 index 89a0106941ff..000000000000 --- a/packages/google-cloud-dns/docs/README.rst +++ /dev/null @@ -1 +0,0 @@ -../README.rst \ No newline at end of file diff --git a/packages/google-cloud-dns/docs/README.rst b/packages/google-cloud-dns/docs/README.rst new file mode 100644 index 000000000000..ca28886a43d7 --- /dev/null +++ b/packages/google-cloud-dns/docs/README.rst @@ -0,0 +1,109 @@ +Python Client for Cloud DNS API +=============================== + +|preview| |pypi| |versions| + +`Cloud DNS API`_: provides methods that you can use to manage DNS for your applications. + +- `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-dns.svg + :target: https://pypi.org/project/google-cloud-dns/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-dns.svg + :target: https://pypi.org/project/google-cloud-dns/ +.. _Cloud DNS API: https://cloud.google.com/dns +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/dns/latest +.. _Product Documentation: https://cloud.google.com/dns + +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 DNS API.`_ +4. `Setup 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 DNS API.: https://cloud.google.com/dns +.. _Setup 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. + +With `virtualenv`_, 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/ + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in `python-docs-samples`_ repository. + +.. _python-docs-samples: https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/dns/api + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.9 + +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.8 + +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 + + pip install virtualenv + virtualenv + source /bin/activate + /bin/pip install google-cloud-dns + + +Windows +^^^^^^^ + +.. code-block:: console + + pip install virtualenv + virtualenv + \Scripts\activate + \Scripts\pip.exe install google-cloud-dns + +Next Steps +~~~~~~~~~~ + +- Read the `Client Library Documentation`_ for Cloud DNS API + to see other available methods on the client. +- Read the `Cloud DNS 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 DNS API Product documentation: https://cloud.google.com/dns +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst diff --git a/packages/google-cloud-documentai-toolbox/docs/README.rst b/packages/google-cloud-documentai-toolbox/docs/README.rst deleted file mode 120000 index 89a0106941ff..000000000000 --- a/packages/google-cloud-documentai-toolbox/docs/README.rst +++ /dev/null @@ -1 +0,0 @@ -../README.rst \ No newline at end of file diff --git a/packages/google-cloud-documentai-toolbox/docs/README.rst b/packages/google-cloud-documentai-toolbox/docs/README.rst new file mode 100644 index 000000000000..8ea93c665413 --- /dev/null +++ b/packages/google-cloud-documentai-toolbox/docs/README.rst @@ -0,0 +1,114 @@ +Document AI Toolbox +================================= + +|experimental| |versions| + +`Document AI Toolbox`_: Document AI Toolbox aims to reduce the friction of managing, manipulating, and extracting information from outputs of Document AI ``BatchProcessDocuments()`` (JSON files written to user-managed GCS buckets) and ``ProcessDocument()`` methods, programmatically. + +**Disclaimer** + +The Document AI Toolbox is in an experimental state. This library is a work-in-progress and is likely to have backwards-incompatible changes. Users of the toolbox might need to rewrite their code when upgrading the toolbox version. + +.. |experimental| image:: https://img.shields.io/badge/support-experimental-red.svg + :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-documentai-toolbox.svg + :target: https://pypi.org/project/google-cloud-documentai-toolbox/ + + +Quick Start +----------- + +In order to use this library, you first need to go through the following steps: + +Enabling Document AI may not be technically required to use this library, unless ``ProcessDocument()`` is intended to be used. +But you must enable the Storage API to access GCS buckets that contains the output of ``BatchProcessDocument()``. +You will need to enable the BigQuery API if you intend to use the BigQuery features. + +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Storage API.`_ +4. `Enable the Document AI API.`_ +5. `Enable the BigQuery API.`_ +6. `Setup 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 Storage API.: https://cloud.google.com/storage/docs +.. _Enable the Document AI API.: https://cloud.google.com/document-ai/docs +.. _Enable the BigQuery API.: https://cloud.google.com/bigquery/docs +.. _Setup 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. + +With `virtualenv`_, 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/ + + +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/` folder. + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.9 + +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.8 + +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 + + pip install virtualenv + virtualenv + source /bin/activate + /bin/pip install google-cloud-documentai-toolbox + + +Windows +^^^^^^^ + +.. code-block:: console + + pip install virtualenv + virtualenv + \Scripts\activate + \Scripts\pip.exe install google-cloud-documentai-toolbox + +Next Steps +~~~~~~~~~~ + +- Read the `Document AI product documentation`_ to learn + more about the product and see How-to Guides. +- Read the `Client Library Documentation`_ for Document AI Toolbox + to see other available methods on the client. +- View this `README`_ to see the full list of Cloud + APIs that we cover. + +.. _`Client Library Documentation`: https://cloud.google.com/python/docs/reference/documentai-toolbox/latest +.. _`Document AI documentation`: https://cloud.google.com/document-ai +.. _`Document AI product documentation`: https://cloud.google.com/document-ai/docs/overview +.. _`README`: https://github.com/googleapis/google-cloud-python/blob/main/README.rst diff --git a/packages/google-cloud-runtimeconfig/docs/README.rst b/packages/google-cloud-runtimeconfig/docs/README.rst deleted file mode 120000 index 89a0106941ff..000000000000 --- a/packages/google-cloud-runtimeconfig/docs/README.rst +++ /dev/null @@ -1 +0,0 @@ -../README.rst \ No newline at end of file diff --git a/packages/google-cloud-runtimeconfig/docs/README.rst b/packages/google-cloud-runtimeconfig/docs/README.rst new file mode 100644 index 000000000000..46a224c8fab0 --- /dev/null +++ b/packages/google-cloud-runtimeconfig/docs/README.rst @@ -0,0 +1,189 @@ +Python Client for Google Cloud Runtime Configurator API +======================================================= + +|preview| |pypi| |versions| + +`Google Cloud Runtime Configurator API`_: + +- `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-runtimeconfig.svg + :target: https://pypi.org/project/google-cloud-runtimeconfig/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-runtimeconfig.svg + :target: https://pypi.org/project/google-cloud-runtimeconfig/ +.. _Google Cloud Runtime Configurator API: https://cloud.google.com/deployment-manager/runtime-configurator/ +.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/runtimeconfig/latest/summary_overview +.. _Product Documentation: https://cloud.google.com/deployment-manager/runtime-configurator/ + +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 Runtime Configurator 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 Runtime Configurator API.: https://cloud.google.com/deployment-manager/runtime-configurator/ +.. _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 + + +Supported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^ +Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of +Python. + +Python >= 3.9 + +.. _active: https://devguide.python.org/devcycle/#in-development-main-branch +.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches + +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.8 + +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-runtimeconfig + + +Windows +^^^^^^^ + +.. code-block:: console + + py -m venv + .\\Scripts\activate + pip install google-cloud-runtimeconfig + +Next Steps +~~~~~~~~~~ + +- Read the `Client Library Documentation`_ for Google Cloud Runtime Configurator API + to see other available methods on the client. +- Read the `Google Cloud Runtime Configurator 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 Runtime Configurator API Product documentation: https://cloud.google.com/deployment-manager/runtime-configurator/ +.. _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/packages/google-resumable-media/docs/README.rst b/packages/google-resumable-media/docs/README.rst deleted file mode 120000 index 89a0106941ff..000000000000 --- a/packages/google-resumable-media/docs/README.rst +++ /dev/null @@ -1 +0,0 @@ -../README.rst \ No newline at end of file diff --git a/packages/google-resumable-media/docs/README.rst b/packages/google-resumable-media/docs/README.rst new file mode 100644 index 000000000000..ae3e8823aab4 --- /dev/null +++ b/packages/google-resumable-media/docs/README.rst @@ -0,0 +1,32 @@ +``google-resumable-media`` +========================== + + +Utilities for Google Media Downloads and Resumable Uploads + + +See the `docs`_ for examples and usage. + +.. _docs: https://googleapis.dev/python/google-resumable-media/latest/index.html + +Experimental `asyncio` Support +------------------------------ +While still in development and subject to change, this library has `asyncio` +support at `google._async_resumable_media`. + +Supported Python Versions +------------------------- +Python >= 3.9 + +Unsupported Python Versions +--------------------------- + +Python <= 3.8 + + +License +------- + +Apache 2.0 - See `the LICENSE`_ for more information. + +.. _the LICENSE: https://github.com/googleapis/google-resumable-media-python/blob/main/LICENSE