From 111aeea570b28022c27154b22e4f7e2057101356 Mon Sep 17 00:00:00 2001 From: acocuzzo Date: Wed, 6 Jul 2022 15:12:50 -0400 Subject: [PATCH] add changes from PR #730 --- .github/.OwlBot.lock.yaml | 4 +- .kokoro/test-samples-impl.sh | 4 +- README.rst | 200 +++--------------- .../templates/install_deps.tmpl.rst | 2 +- 4 files changed, 40 insertions(+), 170 deletions(-) diff --git a/.github/.OwlBot.lock.yaml b/.github/.OwlBot.lock.yaml index 50b29ffd2..1ce608523 100644 --- a/.github/.OwlBot.lock.yaml +++ b/.github/.OwlBot.lock.yaml @@ -13,5 +13,5 @@ # limitations under the License. docker: image: gcr.io/cloud-devrel-public-resources/owlbot-python:latest - digest: sha256:b2dc5f80edcf5d4486c39068c9fa11f7f851d9568eea4dcba130f994ea9b5e97 -# created: 2022-06-12T16:09:31.61859086Z + digest: sha256:e7bb19d47c13839fe8c147e50e02e8b6cf5da8edd1af8b82208cd6f66cc2829c +# created: 2022-07-05T18:31:20.838186805Z diff --git a/.kokoro/test-samples-impl.sh b/.kokoro/test-samples-impl.sh index 8a324c9c7..2c6500cae 100755 --- a/.kokoro/test-samples-impl.sh +++ b/.kokoro/test-samples-impl.sh @@ -33,7 +33,7 @@ export PYTHONUNBUFFERED=1 env | grep KOKORO # Install nox -python3.6 -m pip install --upgrade --quiet nox +python3.9 -m pip install --upgrade --quiet nox # Use secrets acessor service account to get secrets if [[ -f "${KOKORO_GFILE_DIR}/secrets_viewer_service_account.json" ]]; then @@ -76,7 +76,7 @@ for file in samples/**/requirements.txt; do echo "------------------------------------------------------------" # Use nox to execute the tests for the project. - python3.6 -m nox -s "$RUN_TESTS_SESSION" + python3.9 -m nox -s "$RUN_TESTS_SESSION" EXIT=$? # If this is a periodic build, send the test log to the FlakyBot. diff --git a/README.rst b/README.rst index 6432525b1..34c59b8f0 100644 --- a/README.rst +++ b/README.rst @@ -1,33 +1,22 @@ -Python Client for Google Cloud Pub / Sub -======================================== +Python Client for Google Cloud Pub/Sub API +========================================== -|GA| |pypi| |versions| +|stable| |pypi| |versions| -`Google Cloud Pub / Sub`_ is a fully-managed real-time messaging service that -allows you to send and receive messages between independent applications. You -can leverage Cloud Pub/Sub’s flexibility to decouple systems and components -hosted on Google Cloud Platform or elsewhere on the Internet. By building on -the same technology Google uses, Cloud Pub / Sub is designed to provide “at -least once” delivery at low latency with on-demand scalability to 1 million -messages per second (and beyond). +`Google Cloud Pub/Sub API`_: -Publisher applications can send messages to a ``topic`` and other applications -can subscribe to that topic to receive the messages. By decoupling senders and -receivers, Google Cloud Pub/Sub allows developers to communicate between -independently written applications. - -- `Product Documentation`_ - `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 +.. |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/google-cloud-pubsub.svg :target: https://pypi.org/project/google-cloud-pubsub/ .. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-pubsub.svg :target: https://pypi.org/project/google-cloud-pubsub/ -.. _Google Cloud Pub / Sub: https://cloud.google.com/pubsub/ -.. _Product Documentation: https://cloud.google.com/pubsub/docs +.. _Google Cloud Pub/Sub API: https://cloud.google.com/pubsub/docs/ .. _Client Library Documentation: https://cloud.google.com/python/docs/reference/pubsub/latest +.. _Product Documentation: https://cloud.google.com/pubsub/docs/ Quick Start ----------- @@ -36,7 +25,7 @@ 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 Pub / Sub API.`_ +3. `Enable the Google Cloud Pub/Sub API.`_ 4. `Setup Authentication.`_ .. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project @@ -58,15 +47,25 @@ dependencies. .. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ +Code samples and snippets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code samples and snippets live in the `samples/` folder. + + Supported Python Versions ^^^^^^^^^^^^^^^^^^^^^^^^^ -Python >= 3.6 +Our client libraries are compatible with all current [active](https://devguide.python.org/devcycle/#in-development-main-branch) and [maintenance](https://devguide.python.org/devcycle/#maintenance-branches) versions of +Python. + +Python >= 3.7 -Deprecated Python Versions -^^^^^^^^^^^^^^^^^^^^^^^^^^ -Python == 2.7. +Unsupported Python Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Python <= 3.6 -The last version of this library compatible with Python 2.7 is google-cloud-pubsub==1.7.0. +If you are using an [end-of-life](https://devguide.python.org/devcycle/#end-of-life-branches) +version of Python, we recommend that you update as soon as possible to an actively supported version. Mac/Linux @@ -90,144 +89,15 @@ Windows \Scripts\activate \Scripts\pip.exe install google-cloud-pubsub +Next Steps +~~~~~~~~~~ -Example Usage -~~~~~~~~~~~~~ - -Publishing -^^^^^^^^^^ - -To publish data to Cloud Pub/Sub you must create a topic, and then publish -messages to it - -.. code-block:: python - - import os - from google.cloud import pubsub_v1 - - publisher = pubsub_v1.PublisherClient() - topic_name = 'projects/{project_id}/topics/{topic}'.format( - project_id=os.getenv('GOOGLE_CLOUD_PROJECT'), - topic='MY_TOPIC_NAME', # Set this to something appropriate. - ) - publisher.create_topic(name=topic_name) - future = publisher.publish(topic_name, b'My first message!', spam='eggs') - future.result() - -To learn more, consult the `publishing documentation`_. - -.. _publishing documentation: https://cloud.google.com/python/docs/reference/pubsub/latest - - -Subscribing -^^^^^^^^^^^ - -To subscribe to data in Cloud Pub/Sub, you create a subscription based on -the topic, and subscribe to that, passing a callback function. - -.. code-block:: python - - import os - from google.cloud import pubsub_v1 - - topic_name = 'projects/{project_id}/topics/{topic}'.format( - project_id=os.getenv('GOOGLE_CLOUD_PROJECT'), - topic='MY_TOPIC_NAME', # Set this to something appropriate. - ) - - subscription_name = 'projects/{project_id}/subscriptions/{sub}'.format( - project_id=os.getenv('GOOGLE_CLOUD_PROJECT'), - sub='MY_SUBSCRIPTION_NAME', # Set this to something appropriate. - ) - - def callback(message): - print(message.data) - message.ack() - - with pubsub_v1.SubscriberClient() as subscriber: - subscriber.create_subscription( - name=subscription_name, topic=topic_name) - future = subscriber.subscribe(subscription_name, callback) - -The future returned by the call to ``subscriber.subscribe`` can be used to -block the current thread until a given condition obtains: - -.. code-block:: python - - try: - future.result() - except KeyboardInterrupt: - future.cancel() - -It is also possible to pull messages in a synchronous (blocking) fashion. To -learn more about subscribing, consult the `subscriber documentation`_. - -.. _subscriber documentation: https://cloud.google.com/python/docs/reference/pubsub/latest - - -Authentication -^^^^^^^^^^^^^^ - -It is possible to specify the authentication method to use with the Pub/Sub -clients. This can be done by providing an explicit `Credentials`_ instance. Support -for various authentication methods is available from the `google-auth`_ library. - -For example, to use JSON Web Tokens, provide a `google.auth.jwt.Credentials`_ instance: - -.. code-block:: python - - import json - from google.auth import jwt - - service_account_info = json.load(open("service-account-info.json")) - audience = "https://pubsub.googleapis.com/google.pubsub.v1.Subscriber" - - credentials = jwt.Credentials.from_service_account_info( - service_account_info, audience=audience - ) - - subscriber = pubsub_v1.SubscriberClient(credentials=credentials) - - # The same for the publisher, except that the "audience" claim needs to be adjusted - publisher_audience = "https://pubsub.googleapis.com/google.pubsub.v1.Publisher" - credentials_pub = credentials.with_claims(audience=publisher_audience) - publisher = pubsub_v1.PublisherClient(credentials=credentials_pub) - -.. _Credentials: https://google-auth.readthedocs.io/en/latest/reference/google.auth.credentials.html#google.auth.credentials.Credentials -.. _google-auth: https://google-auth.readthedocs.io/en/latest/index.html -.. _google.auth.jwt.Credentials: https://google-auth.readthedocs.io/en/latest/reference/google.auth.jwt.html#google.auth.jwt.Credentials - - -Versioning ----------- - -This library follows `Semantic Versioning`_. - -It is currently in major version one (1.y.z), which means that the public API should be considered stable. - -.. _Semantic Versioning: http://semver.org/ - -Contributing ------------- - -Contributions to this library are always welcome and highly encouraged. - -See the `CONTRIBUTING doc`_ for more information on how to get started. - -.. _CONTRIBUTING doc: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst - -Community ---------- - -Google Cloud Platform Python developers hang out in `Slack`_ in the ``#python`` -channel, click here to `get an invitation`_. - -.. _Slack: https://googlecloud-community.slack.com -.. _get an invitation: https://gcp-slack.appspot.com/ - -License -------- - -Apache 2.0 - See `the LICENSE`_ for more information. +- Read the `Client Library Documentation`_ for Google Cloud Pub/Sub API + to see other available methods on the client. +- Read the `Google Cloud Pub/Sub 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. -.. _the LICENSE: https://github.com/googleapis/google-cloud-python/blob/main/LICENSE +.. _Google Cloud Pub/Sub API Product documentation: https://cloud.google.com/pubsub/docs/ +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst diff --git a/scripts/readme-gen/templates/install_deps.tmpl.rst b/scripts/readme-gen/templates/install_deps.tmpl.rst index 275d64989..6f069c6c8 100644 --- a/scripts/readme-gen/templates/install_deps.tmpl.rst +++ b/scripts/readme-gen/templates/install_deps.tmpl.rst @@ -12,7 +12,7 @@ Install Dependencies .. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup -#. Create a virtualenv. Samples are compatible with Python 3.6+. +#. Create a virtualenv. Samples are compatible with Python 3.7+. .. code-block:: bash