Registry / gcp / google-cloud-pubsub

google-cloud-pubsub

JSON →
library2.36.0pypypi✓ verified 50d ago

The `google-cloud-pubsub` Python client library provides a fully-managed, real-time messaging service for Google Cloud Pub/Sub. It facilitates asynchronous communication, decoupling services that produce messages from those that consume them, offering 'at least once' delivery, low latency, and on-demand scalability. The library is actively maintained with frequent, often weekly, releases for bug fixes and minor features within the broader `google-cloud-python` monorepo.

gcphttp-networkingcommunicationdata
pip install google-cloud-pubsub
Install & Compatibility
Where this runs
tested against v2.39.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.925 runs
installs and imports cleanly · install 0.0s · import 2.483s · 75.6MB
glibc
py 3.103.925 runs
installs and imports cleanly · install 6.1s · import 1.711s · 73MB
74MB installed
● package 74MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PublisherClient
from google.cloud.pubsub_v1 import PublisherClient
from google.cloud import pubsub_v1
SubscriberClient
from google.cloud.pubsub_v1 import SubscriberClient
from google.cloud import pubsub_v1

This quickstart demonstrates how to publish a message to a Google Cloud Pub/Sub topic and then subscribe to and consume that message from a subscription. It handles topic and subscription creation if they don't exist and uses environment variables for project configuration.

import os import time from concurrent.futures import TimeoutError from google.cloud import pubsub_v1 project_id = os.environ.get('GOOGLE_CLOUD_PROJECT') or os.environ.get('GCP_PROJECT') or 'your-gcp-project-id' topic_id = 'my-topic-id' subscription_id = 'my-subscription-id' if not project_id or project_id == 'your-gcp-project-id': raise ValueError("Please set the GOOGLE_CLOUD_PROJECT environment variable or replace 'your-gcp-project-id'.") publisher = pubsub_v1.PublisherClient() subscriber = pubsub_v1.SubscriberClient() topic_path = publisher.topic_path(project_id, topic_id) subscription_path = subscriber.subscription_path(project_id, subscription_id) # Create topic if it doesn't exist try: publisher.get_topic(request={"topic": topic_path}) print(f"Topic {topic_path} already exists.") except Exception: print(f"Creating topic {topic_path}...") publisher.create_topic(request={"name": topic_path}) print(f"Topic {topic_path} created.") # Create subscription if it doesn't exist try: subscriber.get_subscription(request={"subscription": subscription_path}) print(f"Subscription {subscription_path} already exists.") except Exception: print(f"Creating subscription {subscription_path}...") subscriber.create_subscription(request={"name": subscription_path, "topic": topic_path}) print(f"Subscription {subscription_path} created.") # --- Publisher --- message_data = "Hello, Pub/Sub!" print(f"Publishing message: '{message_data}' to {topic_path}") future = publisher.publish(topic_path, message_data.encode('utf-8')) message_id = future.result() print(f"Published message with ID: {message_id}") # --- Subscriber --- def callback(message: pubsub_v1.subscriber.message.Message): print(f"Received message: {message.data.decode('utf-8')}") print(f"Acknowledging message: {message.message_id}") message.ack() print(f"Listening for messages on {subscription_path}...") streaming_pull_future = subscriber.subscribe(subscription_path, callback=callback) # Wrap subscriber in a 'with' block to automatically call close() when done. with subscriber: try: # `subscribe` is non-blocking, so we must keep the main thread from exiting to allow it to run. streaming_pull_future.result(timeout=30) # Wait 30 seconds for messages except TimeoutError: streaming_pull_future.cancel() # Trigger the shutdown. streaming_pull_future.result() # Block until the shutdown is complete. except KeyboardInterrupt: streaming_pull_future.cancel() # Trigger the shutdown. streaming_pull_future.result() # Block until the shutdown is complete. print("Finished listening for messages.") # Clean up resources (optional) # publisher.delete_topic(request={"topic": topic_path}) # subscriber.delete_subscription(request={"subscription": subscription_path}) # print(f"Topic {topic_id} and subscription {subscription_id} deleted.")
Debug
Known issues
breakingVersions of `google-cloud-pubsub` from `2.35.0` and higher require Python 3.9 or newer. If you are using Python 3.7 or 3.8, you must pin the library version to `google-cloud-pubsub==2.34.0` or earlier.
fix
Upgrade your Python environment to 3.9+ or pin the library version: `pip install google-cloud-pubsub==2.34.0`.
affects: >=2.35.0
gotchaInstantiating multiple `PublisherClient` or `SubscriberClient` instances unnecessarily can lead to resource inefficiencies. These clients handle connection pooling and caching internally.
fix
For most applications, create a single `PublisherClient` and a single `SubscriberClient` instance per process and reuse them across operations to optimize resource utilization.
affects: All versions
gotchaIncorrectly configuring subscriber acknowledgment deadlines or flow control (prefetch settings) can cause 'stuck subscribers', messages being redelivered repeatedly (poison pill effect), or excessive resource consumption.
fix
Carefully tune your subscription's acknowledgment deadline to allow sufficient time for message processing. Implement appropriate flow control settings (`max_messages`, `max_bytes`) to prevent your application from being overwhelmed by messages. Always call `message.ack()` or `message.nack()` after processing.
affects: All versions
gotchaPub/Sub guarantees at-least-once delivery, meaning a message might be delivered more than once in certain scenarios (e.g., subscriber restarts, ack deadline issues).
fix
Design your subscriber logic to be *idempotent*. Your message processing should produce the same result whether it's executed once or multiple times for the same message. Utilize unique business keys (like a transaction ID) and check against a fast-access store to prevent duplicate processing.
affects: All versions
gotchaFailing to capture and log the `message_id` returned by `publisher.publish().result()` can severely hinder debugging and traceability in production.
fix
Always store or log the `message_id` returned by the publish operation. This ID is the primary way to correlate a published message with its ingestion in Google Cloud Logs Explorer and track its lifecycle.
affects: All versions
breakingThe Google Cloud Project ID must be provided to the Pub/Sub client libraries to identify the project where resources reside. This can be done by setting the `GOOGLE_CLOUD_PROJECT` environment variable or by explicitly passing the `project` argument to client constructors. Failing to provide a valid project ID (or leaving it as a placeholder like 'your-gcp-project-id') will prevent client initialization.
fix
Ensure the `GOOGLE_CLOUD_PROJECT` environment variable is set to your actual Google Cloud Project ID (e.g., `my-project-123`) before initializing clients, or explicitly pass the project ID to the client constructor, for example: `PublisherClient(project='my-project-123')`.
affects: All versions
Upgrade
Version history
2.39.0latest on PyPI
Audit
Dependencies

No dependency data recorded yet.

Agent activity
48 hits · last 30 days
node
8
mj12bot
4
ahrefsbot
2
seranking-bot
2
Resources