11# Python SDK for [ CloudEvents] ( https://github.com/cloudevents/spec )
22
3+ [ ![ PyPI version] ( https://badge.fury.io/py/cloudevents.svg )] ( https://badge.fury.io/py/cloudevents )
4+
35## Status
46
57This SDK is still considered a work in progress, therefore things might (and
@@ -14,159 +16,87 @@ This SDK current supports the following versions of CloudEvents:
1416
1517Package ** cloudevents** provides primitives to work with CloudEvents specification: https://github.com/cloudevents/spec .
1618
17- Parsing upstream structured Event from HTTP request:
19+ ## Sending CloudEvents
1820
19- ``` python
20- import io
21-
22- from cloudevents.sdk.event import v1
23- from cloudevents.sdk import marshaller
24-
25- m = marshaller.NewDefaultHTTPMarshaller()
26-
27- event = m.FromRequest(
28- v1.Event(),
29- {" content-type" " application/cloudevents+json"
30- io.StringIO(
31- """
32- {
33- "specversion": "1.0",
34- "datacontenttype": "application/json",
35- "type": "word.found.name",
36- "id": "96fb5f0b-001e-0108-6dfe-da6e2806f124",
37- "time": "2018-10-23T12:28:22.4579346Z",
38- "source": "<source-url>"
39- }
40- """
41- ),
42- lambda x : x.read(),
43- )
44- ```
21+ Below we will provide samples on how to send cloudevents using the popular
22+ [ ` requests ` ] ( http://docs.python-requests.org ) library.
4523
46- Parsing upstream binary Event from HTTP request:
24+ ### Binary HTTP CloudEvent
4725
4826``` python
49- import io
50-
51- from cloudevents.sdk.event import v1
52- from cloudevents.sdk import marshaller
53-
54- m = marshaller.NewDefaultHTTPMarshaller()
55-
56- event = m.FromRequest(
57- v1.Event(),
58- {
59- " ce-specversion" " 1.0"
60- " content-type" " application/json"
61- " ce-type" " word.found.name"
62- " ce-id" " 96fb5f0b-001e-0108-6dfe-da6e2806f124"
63- " ce-time" " 2018-10-23T12:28:22.4579346Z"
64- " ce-source" " <source-url>"
65- },
66- io.BytesIO(b " this is where your CloudEvent data"
67- lambda x : x.read(),
68- )
69- ```
27+ from cloudevents.http import CloudEvent, to_binary_http
28+ import requests
7029
71- Creating a minimal CloudEvent in version 0.1:
7230
73- ``` python
74- from cloudevents.sdk.event import v1
75-
76- event = (
77- v1.Event()
78- .SetContentType( " application/json " )
79- .SetData( ' {"name":"john"} ' )
80- .SetEventID( " my-id "
81- .SetSource( " from-galaxy-far-far-away "
82- .SetEventTime( " tomorrow " )
83- .SetEventType( " cloudevent.greet.you " )
84- )
31+ # This data defines a binary cloudevent
32+ attributes = {
33+ " type " : " com.example.sampletype1 " ,
34+ " source " : " https://example.com/event-producer " ,
35+ }
36+ data = { " message " : " Hello World! " }
37+
38+ event = CloudEvent(attributes, data )
39+ headers, body = to_binary_http(event )
40+
41+ # POST
42+ requests.post( " <some-url> " , data = body, headers = headers )
8543```
8644
87- Creating HTTP request from CloudEvent:
45+ ### Structured HTTP CloudEvent
8846
8947``` python
90- from cloudevents.sdk import converters
91- from cloudevents.sdk import marshaller
92- from cloudevents.sdk.converters import structured
93- from cloudevents.sdk.event import v1
94-
95- event = (
96- v1.Event()
97- .SetContentType(" application/json"
98- .SetData(' {"name":"john"}'
99- .SetEventID(" my-id"
100- .SetSource(" from-galaxy-far-far-away"
101- .SetEventTime(" tomorrow"
102- .SetEventType(" cloudevent.greet.you"
103- )
104-
105- m = marshaller.NewHTTPMarshaller([structured.NewJSONHTTPCloudEventConverter()])
106-
107- headers, body = m.ToRequest(event, converters.TypeStructured, lambda x : x)
108- ```
48+ from cloudevents.http import CloudEvent, to_structured_http
49+ import requests
10950
110- ## HOWTOs with various Python HTTP frameworks
11151
112- In this topic you'd find various example how to integrate an SDK with various HTTP frameworks.
52+ # This data defines a structured cloudevent
53+ attributes = {
54+ " type" " com.example.sampletype2"
55+ " source" " https://example.com/event-producer"
56+ }
57+ data = {" message" " Hello World!"
58+ event = CloudEvent(attributes, data)
59+ headers, body = to_structured_http(event)
11360
114- ### Python requests
61+ # POST
62+ requests.post(" <some-url>" data = body, headers = headers)
63+ ```
11564
116- One of popular framework is [ ` requests ` ] ( http://docs.python-requests.org/en/master/ ) .
65+ You can find a complete example of turning a CloudEvent into a HTTP request [ in the samples directory ] ( samples/http-json-cloudevents/client.py ) .
11766
118- #### CloudEvent to request
67+ #### Request to CloudEvent
11968
120- The code below shows how integrate both libraries in order to convert a CloudEvent into an HTTP request:
69+ The code below shows how to consume a cloudevent using the popular python web framework
70+ [ flask] ( https://flask.palletsprojects.com/en/1.1.x/quickstart/ ) :
12171
12272``` python
123- def run_binary (event , url ):
124- binary_headers, binary_data = http_marshaller.ToRequest(
125- event, converters.TypeBinary, json.dumps)
126-
127- print (" binary CloudEvent"
128- for k, v in binary_headers.items():
129- print (" {0} : {1} \r\n "
130- print (binary_data.getvalue())
131- response = requests.post(url,
132- headers = binary_headers,
133- data = binary_data.getvalue())
134- response.raise_for_status()
135-
136-
137- def run_structured (event , url ):
138- structured_headers, structured_data = http_marshaller.ToRequest(
139- event, converters.TypeStructured, json.dumps
140- )
141- print (" structured CloudEvent"
142- print (structured_data.getvalue())
73+ from flask import Flask, request
14374
144- response = requests.post(url,
145- headers = structured_headers,
146- data = structured_data.getvalue())
147- response.raise_for_status()
75+ from cloudevents.http import from_http
14876
149- ```
77+ app = Flask( __name__ )
15078
151- Complete example of turning a CloudEvent into a request you can find [ here] ( samples/python-requests/cloudevent_to_request.py ) .
15279
153- #### Request to CloudEvent
80+ # create an endpoint at http://localhost:/3000/
81+ @app.route (" /" methods = [" POST"
82+ def home ():
83+ # create a CloudEvent
84+ event = from_http(request.get_data(), request.headers)
15485
155- The code below shows how integrate both libraries in order to create a CloudEvent from an HTTP request:
86+ # you can access cloudevent fields as seen below
87+ print (
88+ f " Found { event[' id' } from { event[' source' } with type "
89+ f " { event[' type' } and specversion { event[' specversion' } "
90+ )
15691
157- ``` python
158- response = requests.get(url)
159- response.raise_for_status()
160- headers = response.headers
161- data = io.BytesIO(response.content)
162- event = v1.Event()
163- http_marshaller = marshaller.NewDefaultHTTPMarshaller()
164- event = http_marshaller.FromRequest(
165- event, headers, data, json.load)
92+ return " " 204
16693
94+
95+ if __name__ == " __main__"
96+ app.run(port = 3000 )
16797```
16898
169- Complete example of turning a CloudEvent into a request you can find [ here ] ( samples/python-requests/request_to_cloudevent .py ) .
99+ You can find a complete example of turning a CloudEvent into a HTTP request [ in the samples directory ] ( samples/http-json-cloudevents/server .py ) .
170100
171101## SDK versioning
172102
@@ -189,3 +119,17 @@ the same API. It will use semantic versioning with following rules:
189119 [ CNCF's Slack workspace] ( https://slack.cncf.io/ ) .
190120- Email: https://lists.cncf.io/g/cncf-cloudevents-sdk
191121- Contact for additional information: Denis Makogon (` @denysmakogon ` on slack).
122+
123+ ## Maintenance
124+
125+ We use black and isort for autoformatting. We setup a tox environment to reformat
126+ the codebase.
127+
128+ e.g.
129+
130+ ``` python
131+ pip install tox
132+ tox - e reformat
133+ ```
134+
135+ For information on releasing version bumps see [ RELEASING.md] ( RELEASING.md )
0 commit comments