GHGA Event Schemas

13.0.0 verified Sat May 09 auth: no python

A library collecting Pydantic-based event schemas used for events exchanged between GHGA services. Current version is 13.0.0, requiring Python >=3.12. Maintained actively by the GHGA community.

pip install ghga-event-schemas

Common errors

error ModuleNotFoundError: No module named 'ghga' ↓

cause Trying to import 'ghga.event_schemas' with a dot instead of underscore.

fix

Use 'import ghga_event_schemas' (underscore) instead of 'import ghga.event_schemas' (dot).

error AttributeError: module 'ghga_event_schemas' has no attribute 'UploadAccepted' ↓

cause Importing directly from top-level package instead of the 'events' submodule.

fix

Use 'from ghga_event_schemas.events import UploadAccepted'.

error pydantic_core._pydantic_core.ValidationError: 1 validation error for FileUpload id ↓

cause Passing a string to a field that expects uuid.UUID4 (since v10.0.0).

fix

Convert the string to a uuid.UUID object: id=uuid.UUID('your-id-string')

Warnings

breaking In version 10.0.0, some ID fields changed from string to UUID4 and some string fields changed to UTCDatetime. If you are upgrading from pre-10.0.0, you must update your code to use UUID objects and datetime objects accordingly. ↓

fix Ensure all IDs are passed as uuid.UUID objects and date strings as datetime.datetime objects (with UTC timezone).

deprecated The 'id' field in FileUpload was renamed in version 10.1.1; previously it was called 'file_id'. ↓

fix Use 'id' instead of 'file_id' when constructing FileUpload models.

gotcha The package name uses hyphens (ghga-event-schemas) but the import module uses underscores (ghga_event_schemas). Common mistake is to use dots or hyphens in imports. ↓

fix Use 'import ghga_event_schemas' or 'from ghga_event_schemas import ...'

Imports

EventPublisher

wrong

from ghga.event_schemas import EventPublisher

correct

from ghga_event_schemas import EventPublisher

Package uses underscores in module names, not dots.

UploadAccepted

wrong

from ghga_event_schemas import UploadAccepted

correct

from ghga_event_schemas.events import UploadAccepted

Event schemas are located under ghga_event_schemas.events, not top-level.

FileUpload

wrong

from ghga_event_schemas import FileUpload

correct

from ghga_event_schemas.models import FileUpload

Data models are in the 'models' submodule.

Quickstart

Basic usage: import event and model classes, create a model instance, then wrap it in an event.

from ghga_event_schemas.events import UploadAccepted
from ghga_event_schemas.models import FileUpload

# Instantiate a FileUpload model
file_upload = FileUpload(
    file_id="some-file-id",
    upload_id="upload-123",
    object_id="obj-456",
    bucket_id="bucket-789",
    file_size=1000,
    upload_date="2023-01-01T00:00:00Z"
)

# Create an UploadAccepted event event = UploadAccepted(payload=file_upload)
print(event)