cloudevents-pydantic
This is an implementation of the CloudEvents spec using Pydantic V2 for high performance during validation and serialization.
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 requirementsmake update-dependencies
: Update dev requirementsmake fix
: Run code style and lint automatic fixes (where possible)make test
: Run test suite against system python versionmake check
: Run tests against all available python versions, code style and lint checksmake type
,make format
,make lint
,make bandit
: Run the relevant checkmake docs
: Render the mkdocs website locally