{"id":6372,"library":"google-events","title":"Google CloudEvents Python Library","description":"The `google-events` library provides strongly-typed data payload schemas (using `proto-plus`) for various Google Cloud services that emit CloudEvents. It helps developers safely deserialize and interact with event data, ensuring type correctness and reducing runtime errors. The library is actively maintained by Google and sees frequent updates, primarily adding new event types and fields as Google Cloud services evolve.","status":"active","version":"0.14.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/google-cloudevents-python/","tags":["google-cloud","cloudevents","eventing","protobuf","schema","data-types"],"install":[{"cmd":"pip install google-events","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides Pythonic wrappers around Protocol Buffers, used for event data schemas.","package":"proto-plus"},{"reason":"Core library for Protocol Buffers, underlying the event data schemas.","package":"protobuf"}],"imports":[{"note":"Event types are typically versioned; always import from the specific 'vX' module (e.g., v1).","wrong":"from google.events.cloud.storage import StorageObjectData","symbol":"StorageObjectData","correct":"from google.events.cloud.storage.v1 import StorageObjectData"},{"note":"Example for another common event type (Pub/Sub).","symbol":"MessagePublishedData","correct":"from google.events.cloud.pubsub.v1 import MessagePublishedData"}],"quickstart":{"code":"import json\nfrom google.events.cloud.storage.v1 import StorageObjectData\n\n# Simulate a raw CloudEvent 'data' payload for a GCS object finalization\n# This would typically come from an HTTP request body or Pub/Sub message.\nraw_event_data = {\n    \"bucket\": \"my-test-bucket\",\n    \"name\": \"my-folder/new-file.txt\",\n    \"contentType\": \"text/plain\",\n    \"size\": \"12345\",\n    \"storageClass\": \"STANDARD\",\n    \"timeCreated\": \"2023-10-27T10:00:00.000Z\",\n    \"updated\": \"2023-10-27T10:00:00.000Z\"\n}\n\n# Deserialize the raw JSON data into a strongly-typed StorageObjectData object\nstorage_object_data = StorageObjectData.from_json(json.dumps(raw_event_data))\n\n# Access properties with type safety\nprint(f\"Bucket: {storage_object_data.bucket}\")\nprint(f\"Object Name: {storage_object_data.name}\")\nprint(f\"Content Type: {storage_object_data.content_type}\")\nprint(f\"Size: {storage_object_data.size}\")\n\n# Example of a field that might not always be present (e.g., etag)\nif storage_object_data.etag: # proto-plus fields return None or default for missing/empty\n    print(f\"ETag: {storage_object_data.etag}\")\nelse:\n    print(\"ETag not present in event data.\")\n","lang":"python","description":"This quickstart demonstrates how to deserialize a raw JSON event data payload (e.g., from a Cloud Storage object finalization event) into a `StorageObjectData` object and access its strongly-typed properties."},"warnings":[{"fix":"Install `cloudevents` (`pip install cloudevents`) and use its `CloudEvent` class, then pass the `google-events` data object to `event.data` or deserialize `event.data` using a `google-events` schema.","message":"The `google-events` library primarily provides *data payload schemas* (Protobuf definitions) for Google CloudEvents. To work with full CloudEvent objects (which include context attributes like `id`, `source`, `type`, `time`, etc.), you typically need to use the separate `cloudevents` Python SDK (e.g., `pip install cloudevents`). `google-events` is designed to be used *with* a CloudEvents SDK, not as a standalone replacement.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly use versioned imports, e.g., `from google.events.cloud.service.vX import EventData` where `vX` matches the event type version you expect.","message":"Google CloudEvent data schemas are often versioned (e.g., `v1`). Always import the specific data type from its versioned module (e.g., `from google.events.cloud.storage.v1 import StorageObjectData`). Importing from a non-versioned parent module may not provide the correct or most up-to-date schema, and future updates to service schemas could introduce incompatible changes.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `EventTypeData.from_json(json_string)` or `EventTypeData.from_dict(dictionary)` for deserialization before accessing event data fields.","message":"When consuming raw event data (e.g., a dictionary or JSON string from an HTTP POST body or Pub/Sub message), you must deserialize it into the appropriate `google-events` proto-plus object using `.from_json()` or `.from_dict()`. Attempting to access attributes directly on the raw dictionary or parsing it into a generic object will bypass type safety and lead to runtime errors or incorrect data interpretation.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}