From cda44dd83d5a20344b6b32f382c6d0911832e75d Mon Sep 17 00:00:00 2001 From: Dustin Ingram Date: Mon, 27 Apr 2020 19:18:23 -0500 Subject: [PATCH] Update docs (#31) * Update README to show v1 examples Signed-off-by: Dustin Ingram * Update release process Signed-off-by: Dustin Ingram * Update CHANGELOG Signed-off-by: Dustin Ingram --- CHANGELOG.md | 4 +- README.md | 107 +++++++++++++++++++++++++++++++------------------ release.sh | 31 +++++++++++++- release_doc.md | 52 +++++++++++------------- setup.cfg | 3 ++ 5 files changed, 125 insertions(+), 72 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ef5c756..dac430f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [0.3.0] ### Added - Added Cloudevents V0.3 and V1 implementations ([#22]) - Add helpful text to README ([#23]) @@ -45,7 +45,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Initial release -[Unreleased]: https://github.com/cloudevents/sdk-python/compare/0.2.4...HEAD +[0.3.0]: https://github.com/cloudevents/sdk-python/compare/0.2.4...HEAD [0.2.4]: https://github.com/cloudevents/sdk-python/compare/0.2.3...0.2.4 [0.2.3]: https://github.com/cloudevents/sdk-python/compare/0.2.2...0.2.3 [0.2.2]: https://github.com/cloudevents/sdk-python/compare/0.2.1...0.2.2 diff --git a/README.md b/README.md index 4098d70..df5d7b2 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ 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 - v0.2 - v0.1 @@ -13,70 +15,97 @@ This SDK current supports the following versions of CloudEvents: Package **cloudevents** provides primitives to work with CloudEvents specification: https://github.com/cloudevents/spec. -Parsing upstream Event from HTTP Request: +Parsing upstream structured Event from HTTP request: + ```python import io -from cloudevents.sdk.event import v02 +from cloudevents.sdk.event import v1 from cloudevents.sdk import marshaller m = marshaller.NewDefaultHTTPMarshaller() -event = m.FromRequest( - v02.Event(), - { - "content-type": "application/cloudevents+json", - "ce-specversion": "0.2", - "ce-time": "2018-10-23T12:28:22.4579346Z", - "ce-id": "96fb5f0b-001e-0108-6dfe-da6e2806f124", - "ce-source": "", - "ce-type": "word.found.name", - }, - io.BytesIO(b"this is where your CloudEvent data"), - lambda x: x.read() -) +event = m.FromRequest( + v1.Event(), + {"content-type": "application/cloudevents+json"}, + io.StringIO( + """ + { + "specversion": "1.0", + "datacontenttype": "application/json", + "type": "word.found.name", + "id": "96fb5f0b-001e-0108-6dfe-da6e2806f124", + "time": "2018-10-23T12:28:22.4579346Z", + "source": "" + } + """ + ), + lambda x: x.read(), +) +``` + +Parsing upstream binary Event from HTTP request: + +```python +import io + +from cloudevents.sdk.event import v1 +from cloudevents.sdk import marshaller + +m = marshaller.NewDefaultHTTPMarshaller() + +event = m.FromRequest( + v1.Event(), + { + "ce-specversion": "1.0", + "content-type": "application/json", + "ce-type": "word.found.name", + "ce-id": "96fb5f0b-001e-0108-6dfe-da6e2806f124", + "ce-time": "2018-10-23T12:28:22.4579346Z", + "ce-source": "", + }, + io.BytesIO(b"this is where your CloudEvent data"), + lambda x: x.read(), +) ``` Creating a minimal CloudEvent in version 0.1: + ```python -from cloudevents.sdk.event import v01 +from cloudevents.sdk.event import v1 event = ( - v01.Event(). - SetContentType("application/json"). - SetData('{"name":"john"}'). - SetEventID("my-id"). - SetSource("from-galaxy-far-far-away"). - SetEventTime("tomorrow"). - SetEventType("cloudevent.greet.you") + v1.Event() + .SetContentType("application/json") + .SetData('{"name":"john"}') + .SetEventID("my-id") + .SetSource("from-galaxy-far-far-away") + .SetEventTime("tomorrow") + .SetEventType("cloudevent.greet.you") ) - ``` Creating HTTP request from CloudEvent: + ```python from cloudevents.sdk import converters from cloudevents.sdk import marshaller from cloudevents.sdk.converters import structured -from cloudevents.sdk.event import v01 +from cloudevents.sdk.event import v1 event = ( - v01.Event(). - SetContentType("application/json"). - SetData('{"name":"john"}'). - SetEventID("my-id"). - SetSource("from-galaxy-far-far-away"). - SetEventTime("tomorrow"). - SetEventType("cloudevent.greet.you") -) -m = marshaller.NewHTTPMarshaller( - [ - structured.NewJSONHTTPCloudEventConverter() - ] + v1.Event() + .SetContentType("application/json") + .SetData('{"name":"john"}') + .SetEventID("my-id") + .SetSource("from-galaxy-far-far-away") + .SetEventTime("tomorrow") + .SetEventType("cloudevent.greet.you") ) +m = marshaller.NewHTTPMarshaller([structured.NewJSONHTTPCloudEventConverter()]) + headers, body = m.ToRequest(event, converters.TypeStructured, lambda x: x) - ``` ## HOWTOs with various Python HTTP frameworks @@ -85,7 +114,7 @@ In this topic you'd find various example how to integrate an SDK with various HT ### Python requests -One of popular framework is [0.2-force-improvements](http://docs.python-requests.org/en/master/). +One of popular framework is [`requests`](http://docs.python-requests.org/en/master/). #### CloudEvent to request diff --git a/release.sh b/release.sh index cce630e..8d276b9 100644 --- a/release.sh +++ b/release.sh @@ -1,8 +1,35 @@ #!/usr/bin/env bash +# Fail fast and fail hard. +set -eo pipefail +# Check for our version +if [ -z "$CLOUDEVENTS_SDK_VERSION" ]; then + echo "Need to set CLOUDEVENTS_SDK_VERSION" + exit 1 +fi + +# Run tests on target branch +tox + +# Cut off stable branch git checkout -b v${CLOUDEVENTS_SDK_VERSION}-stable + +# Create GitHub tag +git tag -a ${CLOUDEVENTS_SDK_VERSION} -m "${CLOUDEVENTS_SDK_VERSION}" + +# Build distribution package +rm -rf dist +pip install -U setuptools wheel +python setup.py sdist bdist_wheel + +# Submit relase to PyPI +pip install -U twine +twine upload dist/* + +# Push the release to GitHub git push origin v${CLOUDEVENTS_SDK_VERSION}-stable -PBR_VERSION=${CLOUDEVENTS_SDK_VERSION} python setup.py sdist bdist_wheel -twine upload dist/cloudevents-${CLOUDEVENTS_SDK_VERSIONN}* +git push --tags + +# Switch back to the master branch git checkout master diff --git a/release_doc.md b/release_doc.md index 194d543..46980ba 100644 --- a/release_doc.md +++ b/release_doc.md @@ -1,49 +1,35 @@ -Release process -=============== +# Release process -Run tests on target brunch --------------------------- +## Run tests on target branch Steps: tox -Cut off stable branch ---------------------- +## Cut off stable branch Steps: git checkout -b vX.X.X-stable - git push origin vX.X.X-stable -Create GitHub tag ------------------ +## Create GitHub tag Steps: - Releases ---> Draft New Release - Name: CloudEvents Python SDK version X.X.X stable release + git tag -a X.X.X -m "X.X.X" -Collect changes from previous version -------------------------------------- +## Build distribution package Steps: - git log --oneline --decorate + rm -rf dist + pip install -U setuptools wheel + python setup.py sdist bdist_wheel -Build distribution package --------------------------- - -Steps: - - PBR_VERSION=X.X.X python setup.py sdist bdist_wheel - - -Check install capability for the wheel --------------------------------------- +## Check install capability for the wheel Steps: @@ -52,15 +38,23 @@ Steps: pip install dist/cloudevents-X.X.X-py3-none-any.whl -Submit release to PYPI ----------------------- +## Submit release to PyPI Steps: - twine upload dist/cloudevents-X.X.X-py3-none-any.whl + pip install -U twine + twine upload dist/* -Verify install capability for the wheel ---------------------------------------- + +## Push the release to GitHub + +Steps: + + git push origin vX.X.X-stable + git push --tags + + +## Verify install capability for the wheel Steps: diff --git a/setup.cfg b/setup.cfg index 275d769..e01208e 100644 --- a/setup.cfg +++ b/setup.cfg @@ -24,3 +24,6 @@ packages = [global] setup-hooks = pbr.hooks.setup_hook + +[pbr] +skip_changelog = True