cloudevents-pydantic

This is an implementation of the CloudEvents spec using Pydantic V2 for high performance during validation and serialization.

It is meant to support natively FastAPI and FastStream (WIP)

Currently supported bindings:

Binding	Format	Single	Batch
HTTP	JSON	✅	✅
HTTP	Binary	planned	planned
KAFKA	JSON	planned	planned
KAFKA	Binary	planned	planned

How to use

pip install cloudevents-pydantic

from cloudevents_pydantic.bindings.http import HTTPHandler
from cloudevents_pydantic.events import CloudEvent

handler = HTTPHandler()
minimal_attributes = {
    "type": "com.example.string",
    "source": "https://example.com/event-producer",
}

# `CloudEvent` is a Pydantic model to handle validation and serialization
# `event_factory` is a helper method to autogenerate some of the mandatory 
# such as id, time, specversion
event = CloudEvent.event_factory(**minimal_attributes)

# Single event HTTP serialization
headers, single_event_as_json = handler.to_json(event)

# Batch of events HTTP serialization
headers, batch_of_events_as_json = handler.to_json_batch([event])

# Parsing a JSON string for a single event
parsed_event = handler.from_json(single_event_as_json)

# Parsing a JSON string for a single event
parsed_event_list = handler.from_json(batch_of_events_as_json)

Refer to the docs for more advanced use cases and for details on how to create custom events.

Performance

Using pydantic gives a great performance boost if compared to the official SDK. (there's obviously some performance issue in the official serialization using pydantic)

These results come from a Macbook Pro M3 Max on python 3.12. Feel free to run the benchmark.py script yourself.

Timings for HTTP JSON deserialization:
This package: 3.0855846670019673
Official SDK with pydantic model: 15.35431600001175
Official SDK with http model: 13.728038166998886

Timings for HTTP JSON serialization:
This package: 4.292417042001034
Official SDK with pydantic model: 44.50933354199515
Official SDK with http model: 8.929204874992138

Commands for development

All the common commands used during development can be run using make targets:

• make dev-dependencies: Install dev requirements
• make update-dependencies: Update dev requirements
• make fix: Run code style and lint automatic fixes (where possible)
• make test: Run test suite against system python version
• make check: Run tests against all available python versions, code style and lint checks
• make type, make format, make lint, make bandit: Run the relevant check
• make docs: Render the mkdocs website locally