Registry / gcp / google-cloud-pubsublite

google-cloud-pubsublite

JSON →
library1.13.0pypypi✓ verified 23d ago

Google Cloud Pub/Sub Lite is a specialized messaging service for high-volume, low-cost event ingestion and delivery with partitioned topics. This Python client library, currently at version 1.13.0, provides a programmatic interface to interact with Pub/Sub Lite topics, subscriptions, and administrative operations, receiving regular updates from Google.

pip install google-cloud-pubsublite
INSTALL
IMPORT
SIG · GOOGLE-CLOUD-PUBSU
G
google-cloud-pubsublite
gcppythonv1.13.0
Install
6.5s avg
Import
2086ms
Disk
78MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.13.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.95 runs
installs and imports cleanly · install 0.0s · import 2.488s · 79.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 6.5s · import 1.684s · 78MB
78MB installed
● package 78MB
Code
Verified usage

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

PublisherClient
from google.cloud.pubsublite.cloudpubsub import PublisherClient
from google.cloud.pubsublite import PublisherClient
Client classes are nested under `cloudpubsub` or `admin` modules.
SubscriberClient
from google.cloud.pubsublite.cloudpubsub import SubscriberClient
from google.cloud.pubsublite import SubscriberClient
Client classes are nested under `cloudpubsub` or `admin` modules.
AdminClient
from google.cloud.pubsublite.admin import AdminClient
from google.cloud.pubsublite import AdminClient
Client classes are nested under `cloudpubsub` or `admin` modules.
TopicPath
from google.cloud.pubsublite.types import TopicPath
from google.cloud.pubsublite import TopicPath
Path and configuration types are under the `types` module.
FlowControlSettings
from google.cloud.pubsublite.types import FlowControlSettings
from google.cloud.pubsublite.cloudpubsub import FlowControlSettings
Flow control settings are part of common types, not specific client modules.

This quickstart demonstrates how to publish a message to a Pub/Sub Lite topic and then subscribe to and consume that message from a subscription. It assumes you have already created the necessary Pub/Sub Lite topic and subscription within your GCP project and set the required environment variables (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_ZONE).

import os import time from concurrent.futures import TimeoutError from google.cloud.pubsublite.cloudpubsub import PublisherClient, SubscriberClient from google.cloud.pubsublite.types import ( CloudZone, TopicPath, SubscriptionPath, FlowControlSettings, ) # Configuration: Ensure GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_ZONE are set # or replace placeholders with your actual GCP Project ID and a Lite zone (e.g., 'us-central1-a'). project_id = os.environ.get("GOOGLE_CLOUD_PROJECT", "your-gcp-project-id") zone = os.environ.get("GOOGLE_CLOUD_ZONE", "us-central1-a") topic_id = "my-pubsublite-topic" subscription_id = "my-pubsublite-subscription" # Define topic and subscription paths topic_path = TopicPath(project_id, CloudZone(zone), topic_id) subscription_path = SubscriptionPath(project_id, CloudZone(zone), subscription_id) if project_id == "your-gcp-project-id": print("Please set the GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_ZONE environment variables.") print("Alternatively, replace 'your-gcp-project-id' and 'us-central1-a' with your actual values.") exit(1) print(f"Using Topic: {topic_path}") print(f"Using Subscription: {subscription_path}") print("Ensure the topic and subscription already exist in your Pub/Sub Lite project.") # --- Publisher: Send a message --- print("\n--- Publishing messages ---") publisher = PublisherClient() message_data = b"Hello from Pub/Sub Lite Python client!" try: # publish returns a future; .result() waits for acknowledgement future = publisher.publish(topic_path, message_data) message_id = future.result(timeout=5) print(f"Published message '{message_data.decode()}' with ID: {message_id}") except TimeoutError: print("Publishing timed out.") except Exception as e: print(f"Error publishing message: {e}") finally: publisher.close() # Important to close the client to flush messages print("Publisher client closed.") # Allow a moment for the message to propagate time.sleep(2) # --- Subscriber: Receive messages --- print("\n--- Subscribing to messages ---") subscriber = SubscriberClient() # Configure flow control to limit outstanding messages and bytes flow_control_settings = FlowControlSettings( messages_outstanding=10, bytes_outstanding=10 * 1024 * 1024 # 10 MiB ) received_messages = [] def callback(message): payload = message.data.decode() print(f"Received message: '{payload}' (ID: {message.message_id})") received_messages.append(payload) message.ack() # Acknowledge the message to allow it to be discarded # The subscribe method returns a streaming_future that can be cancelled. streaming_future = subscriber.subscribe(subscription_path, callback, flow_control_settings) print(f"Listening for messages on {subscription_path} for 10 seconds...") try: # Wait for the future to complete (e.g., if cancelled) or timeout. streaming_future.result(timeout=10) except TimeoutError: print("No more messages received within 10 seconds or subscription completed.") except Exception as e: print(f"Error during subscription: {e}") finally: streaming_future.cancel() # Stop the subscription stream subscriber.close() # Important to close the client to release resources print("Subscriber client closed.") if received_messages: print(f"\nSuccessfully processed {len(received_messages)} message(s).") else: print("\nNo messages were processed by the subscriber.")
Debug
Known issues
gotchaPublish idempotence, introduced in v1.8.0, was disabled by default in v1.8.2. If you relied on automatic idempotence, you must now explicitly enable it via `PublisherClient.publish(..., id='your-id')` or `PublisherSettings(..., publish_idempotence=True)`.
fix
Upgrade to v1.8.2+ and explicitly set `publish_idempotence=True` in `PublisherSettings` or pass `id` to `publish` if desired.
affects: <=1.8.2
gotchaOlder versions of `google-cloud-pubsublite` (prior to v1.13.0) might inadvertently install pre-release versions of dependencies, leading to potential instability or unexpected behavior.
fix
Upgrade to `google-cloud-pubsublite` v1.13.0 or later to ensure stable dependency versions are used.
affects: <1.13.0
gotchaClient objects (`PublisherClient`, `SubscriberClient`, `AdminClient`) should always be explicitly closed using their `.close()` method to ensure all resources are released and pending operations (like publishing messages) are completed.
fix
Always call `client.close()` when you are done with a client instance. For asynchronous operations, consider using `async with` for context management.
affects: All versions
gotchaThe `google-cloud-pubsublite` library requires Python 3.8 or newer. Using older Python versions will result in installation failures or runtime errors.
fix
Ensure your environment is running Python 3.8 or a later compatible version.
affects: <3.8 Python runtime
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google.cloud.pubsublite'
The `google-cloud-pubsublite` library is not installed or the Python environment where the code is being run does not have access to it.
fix
Ensure the library is installed using pip: `pip install google-cloud-pubsublite`.
google.api_core.exceptions.PermissionDenied: 403 Permission denied on resource
The authenticated service account or user lacks the necessary IAM permissions (e.g., `pubsublite.topics.publish`, `pubsublite.subscriptions.consume`) to perform the requested operation on the Pub/Sub Lite resource.
fix
Grant the appropriate Pub/Sub Lite IAM roles (e.g., 'Pub/Sub Lite Publisher', 'Pub/Sub Lite Subscriber', 'Pub/Sub Lite Admin') to the service account or user in the Google Cloud Console.
google.api_core.exceptions.NotFound: 404 Resource not found
The specified Pub/Sub Lite topic or subscription name does not exist, or there is a typo in the project, region, or resource ID.
fix
Verify that the project ID, location (region/zone), topic ID, and subscription ID are correct and that the resource has been created in Google Cloud Platform.
google.api_core.exceptions.InvalidArgument: 400 The request contains an invalid argument
An API request was made with incorrectly formatted parameters, missing required arguments, or values that are outside the allowed range for Pub/Sub Lite resources (e.g., invalid topic path, incorrect message size).
fix
Review the specific error message details and the `google-cloud-pubsublite` client library documentation for the method being called to ensure all arguments are valid and correctly formatted.
Upgrade
Version history
1.13.0latest on PyPI · released Dec 16, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
35 hits · last 30 days
node
30
OpenAI (training)
1
Resources
google-cloud-pubsublite — pip install google-cloud-pubsublite · libregistry