Python SDK v2 for CloudEvents
This SDK is still considered a work in progress, therefore things might (and will) break with every update.
This SDK current supports the following versions of CloudEvents:
- v1.0
- v0.3
Package cloudevents provides primitives to work with CloudEvents specification.
The CloudEvents SDK can be installed with pip:
pip install cloudevents
Below we will provide samples on how to send cloudevents using the popular
requests library.
from cloudevents.core.v1.event import CloudEvent from cloudevents.core.bindings.http import to_binary_event import requests # Create a CloudEvent # - The CloudEvent "id" is generated if omitted. "specversion" defaults to "1.0". attributes = { "type": "com.example.sampletype1", "source": "https://example.com/event-producer", } data = {"message": "Hello World!"} event = CloudEvent(attributes, data) # Creates the HTTP request representation of the CloudEvent in binary content mode message = to_binary_event(event) # POST requests.post("<some-url>", data=message.body, headers=message.headers)
from cloudevents.core.v1.event import CloudEvent from cloudevents.core.bindings.http import to_structured_event import requests # Create a CloudEvent # - The CloudEvent "id" is generated if omitted. "specversion" defaults to "1.0". attributes = { "type": "com.example.sampletype2", "source": "https://example.com/event-producer", } data = {"message": "Hello World!"} event = CloudEvent(attributes, data) # Creates the HTTP request representation of the CloudEvent in structured content mode message = to_structured_event(event) # POST requests.post("<some-url>", data=message.body, headers=message.headers)
You can find a complete example of turning a CloudEvent into a HTTP request in the samples' directory.
The code below shows how to consume a cloudevent using the popular python web framework flask:
from flask import Flask, request from cloudevents.core.bindings.http import from_http_event, HTTPMessage app = Flask(__name__) # create an endpoint at http://localhost:/3000/ @app.route("/", methods=["POST"]) def home(): # create a CloudEvent event = from_http_event(HTTPMessage(dict(request.headers), request.get_data())) # you can access cloudevent fields as seen below print( f"Found {event.get_id()} from {event.get_source()} with type " f"{event.get_type()} and specversion {event.get_specversion()}" ) return "", 204 if __name__ == "__main__": app.run(port=3000)
You can find a complete example of turning a CloudEvent into a HTTP request in the samples' directory.
The goal of this package is to provide support for all released versions of CloudEvents, ideally while maintaining the same API. It will use semantic versioning with following rules:
- MAJOR version increments when backwards incompatible changes is introduced.
- MINOR version increments when backwards compatible feature is introduced INCLUDING support for new CloudEvents version.
- PATCH version increments when a backwards compatible bug fix is introduced.
- There are bi-weekly calls immediately following the Serverless/CloudEvents call at 9am PT (US Pacific). Which means they will typically start at 10am PT, but if the other call ends early then the SDK call will start early as well. See the CloudEvents meeting minutes to determine which week will have the call.
- Slack: #cloudeventssdk channel under CNCF's Slack workspace.
- Email: https://lists.cncf.io/g/cncf-cloudevents-sdk
- Contact for additional information: Denis Makogon (
@denysmakogonon slack).
Each SDK may have its own unique processes, tooling and guidelines, common
governance related material can be found in the
CloudEvents docs
directory. In particular, in there you will find information concerning
how SDK projects are
managed,
guidelines
for how PR reviews and approval, and our
Code of Conduct
information.
If there is a security concern with one of the CloudEvents specifications, or with one of the project's SDKs, please send an email to [email protected].
- List of current active maintainers
- How to contribute to the project
- SDK's License
- SDK's Release process
We use uv for dependency and package management, ruff and isort for autoformatting and pre-commit to automate those with commit hooks.
For information on releasing version bumps see RELEASING.md