Python Client for Google Cloud Pub / Sub
========================================
|GA| |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).
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`_
.. |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-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
.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/pubsub/latest
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 Pub / Sub 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 Pub / Sub API.: https://cloud.google.com/pubsub
.. _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.7
Deprecated Python Versions
^^^^^^^^^^^^^^^^^^^^^^^^^^
Python <= 3.6.
The last version of this library compatible with Python 2.7 is google-cloud-pubsub==1.7.0.
Mac/Linux
^^^^^^^^^
.. code-block:: console
pip install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install google-cloud-pubsub
Windows
^^^^^^^
.. code-block:: console
pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install google-cloud-pubsub
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
---------
The best place to ask questions is via Stackoverflow: https://stackoverflow.com/questions/tagged/google-cloud-pubsub
License
-------
Apache 2.0 - See `the LICENSE`_ for more information.
.. _the LICENSE: https://github.com/googleapis/google-cloud-python/blob/main/LICENSE
Raw data
{
"_id": null,
"home_page": "https://github.com/googleapis/python-pubsub",
"name": "google-cloud-pubsub",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Google LLC",
"author_email": "googleapis-packages@google.com",
"download_url": "https://files.pythonhosted.org/packages/bf/ab/39175fc8a3f7b4094e9c0bf781ea0e54841b8ae5706a169b9dcec84fb6b1/google_cloud_pubsub-2.27.1.tar.gz",
"platform": "Posix; MacOS X; Windows",
"description": "Python Client for Google Cloud Pub / Sub\n========================================\n\n|GA| |pypi| |versions| \n\n`Google Cloud Pub / Sub`_ is a fully-managed real-time messaging service that\nallows you to send and receive messages between independent applications. You\ncan leverage Cloud Pub/Sub\u2019s flexibility to decouple systems and components\nhosted on Google Cloud Platform or elsewhere on the Internet. By building on\nthe same technology Google uses, Cloud Pub / Sub is designed to provide \u201cat\nleast once\u201d delivery at low latency with on-demand scalability to 1 million\nmessages per second (and beyond).\n\nPublisher applications can send messages to a ``topic`` and other applications\ncan subscribe to that topic to receive the messages. By decoupling senders and\nreceivers, Google Cloud Pub/Sub allows developers to communicate between\nindependently written applications.\n\n- `Product Documentation`_\n- `Client Library Documentation`_\n\n.. |GA| image:: https://img.shields.io/badge/support-GA-gold.svg\n :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability\n.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-pubsub.svg\n :target: https://pypi.org/project/google-cloud-pubsub/\n.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-pubsub.svg\n :target: https://pypi.org/project/google-cloud-pubsub/\n.. _Google Cloud Pub / Sub: https://cloud.google.com/pubsub/\n.. _Product Documentation: https://cloud.google.com/pubsub/docs\n.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/pubsub/latest\n\nQuick Start\n-----------\n\nIn order to use this library, you first need to go through the following steps:\n\n1. `Select or create a Cloud Platform project.`_\n2. `Enable billing for your project.`_\n3. `Enable the Google Cloud Pub / Sub API.`_\n4. `Setup Authentication.`_\n\n.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project\n.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project\n.. _Enable the Google Cloud Pub / Sub API.: https://cloud.google.com/pubsub\n.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html\n\nInstallation\n~~~~~~~~~~~~\n\nInstall this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to\ncreate isolated Python environments. The basic problem it addresses is one of\ndependencies and versions, and indirectly permissions.\n\nWith `virtualenv`_, it's possible to install this library without needing system\ninstall permissions, and without clashing with the installed system\ndependencies.\n\n.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/\n\n\nSupported Python Versions\n^^^^^^^^^^^^^^^^^^^^^^^^^\nPython >= 3.7\n\nDeprecated Python Versions\n^^^^^^^^^^^^^^^^^^^^^^^^^^\nPython <= 3.6.\n\nThe last version of this library compatible with Python 2.7 is google-cloud-pubsub==1.7.0.\n\n\nMac/Linux\n^^^^^^^^^\n\n.. code-block:: console\n\n pip install virtualenv\n virtualenv <your-env>\n source <your-env>/bin/activate\n <your-env>/bin/pip install google-cloud-pubsub\n\n\nWindows\n^^^^^^^\n\n.. code-block:: console\n\n pip install virtualenv\n virtualenv <your-env>\n <your-env>\\Scripts\\activate\n <your-env>\\Scripts\\pip.exe install google-cloud-pubsub\n\n\nExample Usage\n~~~~~~~~~~~~~\n\nPublishing\n^^^^^^^^^^\n\nTo publish data to Cloud Pub/Sub you must create a topic, and then publish\nmessages to it\n\n.. code-block:: python\n\n import os\n from google.cloud import pubsub_v1\n\n publisher = pubsub_v1.PublisherClient()\n topic_name = 'projects/{project_id}/topics/{topic}'.format(\n project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),\n topic='MY_TOPIC_NAME', # Set this to something appropriate.\n )\n publisher.create_topic(name=topic_name)\n future = publisher.publish(topic_name, b'My first message!', spam='eggs')\n future.result()\n\nTo learn more, consult the `publishing documentation`_.\n\n.. _publishing documentation: https://cloud.google.com/python/docs/reference/pubsub/latest\n\n\nSubscribing\n^^^^^^^^^^^\n\nTo subscribe to data in Cloud Pub/Sub, you create a subscription based on\nthe topic, and subscribe to that, passing a callback function.\n\n.. code-block:: python\n\n import os\n from google.cloud import pubsub_v1\n\n topic_name = 'projects/{project_id}/topics/{topic}'.format(\n project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),\n topic='MY_TOPIC_NAME', # Set this to something appropriate.\n )\n\n subscription_name = 'projects/{project_id}/subscriptions/{sub}'.format(\n project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),\n sub='MY_SUBSCRIPTION_NAME', # Set this to something appropriate.\n )\n\n def callback(message):\n print(message.data)\n message.ack()\n\n with pubsub_v1.SubscriberClient() as subscriber:\n subscriber.create_subscription(\n name=subscription_name, topic=topic_name) \n future = subscriber.subscribe(subscription_name, callback)\n\nThe future returned by the call to ``subscriber.subscribe`` can be used to\nblock the current thread until a given condition obtains:\n\n.. code-block:: python\n\n try:\n future.result()\n except KeyboardInterrupt:\n future.cancel()\n\nIt is also possible to pull messages in a synchronous (blocking) fashion. To\nlearn more about subscribing, consult the `subscriber documentation`_.\n\n.. _subscriber documentation: https://cloud.google.com/python/docs/reference/pubsub/latest\n\n\nAuthentication\n^^^^^^^^^^^^^^\n\nIt is possible to specify the authentication method to use with the Pub/Sub\nclients. This can be done by providing an explicit `Credentials`_ instance. Support\nfor various authentication methods is available from the `google-auth`_ library.\n\nFor example, to use JSON Web Tokens, provide a `google.auth.jwt.Credentials`_ instance:\n\n.. code-block:: python\n\n import json\n from google.auth import jwt\n\n service_account_info = json.load(open(\"service-account-info.json\"))\n audience = \"https://pubsub.googleapis.com/google.pubsub.v1.Subscriber\"\n\n credentials = jwt.Credentials.from_service_account_info(\n service_account_info, audience=audience\n )\n\n subscriber = pubsub_v1.SubscriberClient(credentials=credentials)\n\n # The same for the publisher, except that the \"audience\" claim needs to be adjusted\n publisher_audience = \"https://pubsub.googleapis.com/google.pubsub.v1.Publisher\"\n credentials_pub = credentials.with_claims(audience=publisher_audience) \n publisher = pubsub_v1.PublisherClient(credentials=credentials_pub)\n\n.. _Credentials: https://google-auth.readthedocs.io/en/latest/reference/google.auth.credentials.html#google.auth.credentials.Credentials\n.. _google-auth: https://google-auth.readthedocs.io/en/latest/index.html\n.. _google.auth.jwt.Credentials: https://google-auth.readthedocs.io/en/latest/reference/google.auth.jwt.html#google.auth.jwt.Credentials\n\n\nVersioning\n----------\n\nThis library follows `Semantic Versioning`_.\n\nIt is currently in major version one (1.y.z), which means that the public API should be considered stable.\n\n.. _Semantic Versioning: http://semver.org/\n\nContributing\n------------\n\nContributions to this library are always welcome and highly encouraged.\n\nSee the `CONTRIBUTING doc`_ for more information on how to get started.\n\n.. _CONTRIBUTING doc: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst\n\nCommunity\n---------\n\nThe best place to ask questions is via Stackoverflow: https://stackoverflow.com/questions/tagged/google-cloud-pubsub\n\n\nLicense\n-------\n\nApache 2.0 - See `the LICENSE`_ for more information.\n\n.. _the LICENSE: https://github.com/googleapis/google-cloud-python/blob/main/LICENSE\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Google Cloud Pub/Sub API client library",
"version": "2.27.1",
"project_urls": {
"Homepage": "https://github.com/googleapis/python-pubsub"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d2af8930228f1f7e411dac722fd90e4235e87ea5b96ba3c3d1b721b80b8c34e4",
"md5": "4326e1b361a43d31c9e30080f6feaeb2",
"sha256": "3ca8980c198a847ee464845ab60f05478d4819cf693c9950ee89da96f0b80a41"
},
"downloads": -1,
"filename": "google_cloud_pubsub-2.27.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "4326e1b361a43d31c9e30080f6feaeb2",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 289646,
"upload_time": "2024-11-13T00:14:27",
"upload_time_iso_8601": "2024-11-13T00:14:27.228715Z",
"url": "https://files.pythonhosted.org/packages/d2/af/8930228f1f7e411dac722fd90e4235e87ea5b96ba3c3d1b721b80b8c34e4/google_cloud_pubsub-2.27.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bfab39175fc8a3f7b4094e9c0bf781ea0e54841b8ae5706a169b9dcec84fb6b1",
"md5": "9b3ab03fb2778d92bac55bfccc601b92",
"sha256": "7119dbc5af4b915ecdfa1289919f791a432927eaaa7bbfbeb740e6d7020c181e"
},
"downloads": -1,
"filename": "google_cloud_pubsub-2.27.1.tar.gz",
"has_sig": false,
"md5_digest": "9b3ab03fb2778d92bac55bfccc601b92",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 358515,
"upload_time": "2024-11-13T00:14:29",
"upload_time_iso_8601": "2024-11-13T00:14:29.456028Z",
"url": "https://files.pythonhosted.org/packages/bf/ab/39175fc8a3f7b4094e9c0bf781ea0e54841b8ae5706a169b9dcec84fb6b1/google_cloud_pubsub-2.27.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-13 00:14:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "googleapis",
"github_project": "python-pubsub",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "google-cloud-pubsub"
}
JSON
