{"id":4949,"library":"gcloud-aio-pubsub","title":"Google Cloud Pub/Sub Client (Async)","description":"Python Client for Google Cloud Pub/Sub using `aiohttp` for asynchronous operations. It is part of the `gcloud-aio` monorepo, which provides async clients for various Google Cloud services. The library is actively maintained with regular updates across its sub-packages.","status":"active","version":"6.3.0","language":"en","source_language":"en","source_url":"https://github.com/talkiq/gcloud-aio","tags":["google cloud","pubsub","async","aiohttp","gcp"],"install":[{"cmd":"pip install gcloud-aio-pubsub","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core HTTP client for asynchronous requests.","package":"aiohttp"},{"reason":"Handles authentication with Google Cloud services.","package":"gcloud-aio-auth"},{"reason":"Provides shared utilities and base classes for gcloud-aio clients.","package":"gcloud-aio-core"},{"reason":"Used for CRC32C checksum calculations in Pub/Sub.","package":"google-crc32c"},{"reason":"Handles Google's Protocol Buffers for data serialization.","package":"protobuf"}],"imports":[{"symbol":"Publisher","correct":"from gcloud.aio.pubsub import Publisher"},{"symbol":"Subscriber","correct":"from gcloud.aio.pubsub import Subscriber"}],"quickstart":{"code":"import asyncio\nimport json\nimport os\n\nfrom aiohttp import ClientSession\nfrom gcloud.aio.pubsub import Publisher, Subscriber\n\nasync def main():\n    # Ensure GCP_PROJECT and GCP_CREDENTIALS are set as environment variables.\n    # For local testing, GCP_CREDENTIALS should be the JSON key file content.\n    # Example: export GCP_CREDENTIALS=$(cat /path/to/keyfile.json)\n    project = os.environ.get('GCP_PROJECT', '')\n    if not project:\n        print(\"Error: GCP_PROJECT environment variable not set.\")\n        return\n\n    topic_name = 'my-test-topic' # Replace with an existing topic\n    subscription_name = 'my-test-subscription' # Replace with an existing subscription\n\n    async with ClientSession() as session:\n        # --- Publisher Example ---\n        publisher = Publisher(session=session, project=project)\n        data = {'message': 'Hello, gcloud-aio-pubsub!'}\n        message_id = await publisher.publish(topic_name, [data])\n        print(f\"Published message to '{topic_name}' with ID: {message_id}\")\n\n        # --- Subscriber Example ---\n        subscriber = Subscriber(session=session, project=project)\n        print(f\"Listening for messages on '{subscription_name}'...\")\n        try:\n            # Fetch up to 1 message for this example\n            async for message in subscriber.subscribe(subscription_name, max_messages=1):\n                print(f\"Received message: {message.data.decode('utf-8')}\")\n                await message.ack()\n                print(\"Message acknowledged.\")\n                break # Exit after first message for this quickstart\n        except Exception as e:\n            print(f\"Error during subscription: {e}\")\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to publish a message to a Pub/Sub topic and then subscribe to a subscription to receive and acknowledge a message using `gcloud-aio-pubsub`. It assumes you have `GCP_PROJECT` and `GCP_CREDENTIALS` environment variables set up, and that the specified topic and subscription already exist in your Google Cloud Project."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer.","message":"As of `gcloud-aio-auth` version 5.4.4 (a dependency of `gcloud-aio-pubsub`), support for Python 3.9 has been dropped. While `gcloud-aio-pubsub`'s `requires_python` might still indicate `>=3.9`, its transitive dependency on `gcloud-aio-auth>=5.4.4` means Python 3.9 is no longer supported across the `gcloud-aio` ecosystem.","severity":"breaking","affected_versions":"gcloud-aio-pubsub>=6.3.0, gcloud-aio-auth>=5.4.4"},{"fix":"Use `await` before all async calls (e.g., `await publisher.publish(...)`, `async for message in subscriber.subscribe(...)`).","message":"All operations in `gcloud-aio-pubsub` are asynchronous. Ensure that all calls to `Publisher` and `Subscriber` methods are properly `await`ed, and that your code runs within an `async` context (e.g., using `asyncio.run()` or an `async` function).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `GCP_PROJECT` and `GCP_CREDENTIALS` (containing the JSON key file content) environment variables before running your application.","message":"Authentication requires setting the `GCP_PROJECT` environment variable for your Google Cloud Project ID and `GCP_CREDENTIALS` with the full JSON string of your service account key. The client library does not automatically discover credentials from `gcloud auth login` or default service accounts without these variables for explicit `gcloud-aio` usage.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Wrap `ClientSession()` creation in `async with ClientSession() as session:`, and pass `session=session` to `Publisher` and `Subscriber` constructors. If not using `async with` for the client itself, explicitly call `await client.close()`.","message":"Proper `aiohttp.ClientSession` lifecycle management is crucial. It's recommended to create a single `ClientSession` per application and pass it to all `gcloud-aio` clients. Ensure the session is closed when no longer needed, typically using an `async with` statement.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}