Merge pull request #1 from denismakogon/initial-build

Initial release: CloudEvents Python SDK 0.0.1a0

Author: denismakogon

.github/pull_request_template.md

@@ -0,0 +1,9 @@
+- Link to issue this resolves
+
+- What I did
+
+- How I did it
+
+- How to verify it
+
+- One line description for the changelog

.gitignore

@@ -0,0 +1,125 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+*.pyc
+.testrepository
+.tox/*
+dist/*
+build/*
+html/*
+*.egg*
+cover/*
+.coverage
+rdserver.txt
+python-troveclient.iml
+
+# Files created by releasenotes build
+releasenotes/build
+.coverage.*
+*.json
+.cache
+*.log*
+*.csv
+venv
+.venv
+ChangeLog
+AUTHORS
+.pytest_cache/

Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = etc/docs_conf
+BUILDDIR      = docs
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.md

@@ -1,2 +1,68 @@
-# sdk-python
-Python SDK for CloudEvents
+# Python SDK for [CloudEvents](https://github.com/cloudevents/spec)
+
+**NOTE: This SDK is still considered work in progress, things might (and will) break with every update.**
+
+Package **cloudevents** provides primitives to work with CloudEvents specification: https://github.com/cloudevents/spec.
+
+Parsing upstream Event from HTTP Request:
+```python
+from cloudevents.sdk.event import upstream
+from cloudevents.sdk import marshaller
+
+data = "<this is where your CloudEvent comes from>"
+m = marshaller.NewDefaultHTTPMarshaller(upstream.Event)
+event = m.FromRequest(
+    {"Content-Type": "application/cloudevents+json"}, 
+    data, 
+    lambda x: x.read()
+)
+
+```
+
+Creating a minimal CloudEvent in version 0.1:
+```python
+from cloudevents.sdk.event import v01
+
+event = (
+    v01.Event().
+    WithContentType("application/json").
+    WithData('{"name":"john"}').
+    WithEventID("my-id").
+    WithSource("from-galaxy-far-far-away").
+    WithEventTime("tomorrow").
+    WithEventType("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
+
+event = (
+    v01.Event().
+    WithContentType("application/json").
+    WithData('{"name":"john"}').
+    WithEventID("my-id").
+    WithSource("from-galaxy-far-far-away").
+    WithEventTime("tomorrow").
+    WithEventType("cloudevent.greet.you")
+)
+m = marshaller.NewHTTPMarshaller(
+    [
+        structured.NewJSONHTTPCloudEventConverter(type(event))
+    ]
+)
+
+headers, body = m.ToRequest(event, converters.TypeStructured, lambda x: x)
+
+```
+
+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.

circle.yml

@@ -0,0 +1,30 @@
+version: 2
+jobs:
+  build:
+    docker:
+      - image: circleci/python:3.7.0
+    working_directory: ~/sdk-python
+    steps:
+      - checkout
+      - restore_cache:
+          key: deps1-{{ .Branch }}-{{ checksum "requirements.txt" }}
+      - setup_remote_docker:
+          docker_layer_caching: true
+      - run:
+          command: |
+            python3 -m venv venv
+            . venv/bin/activate
+            pip install tox
+            pip install -r requirements.txt
+      - save_cache:
+          key: deps1-{{ .Branch }}-{{ checksum "requirements.txt" }}
+          paths:
+            - "venv"
+      - run:
+          command: |
+            . venv/bin/activate
+            tox -epep8
+      - run:
+          command: |
+            . venv/bin/activate
+            tox -epy3.7

cloudevents/__init__.py

@@ -0,0 +1,19 @@
+# All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+from cloudevents.sdk.converters import binary
+from cloudevents.sdk.converters import structured
+
+TypeBinary = binary.BinaryHTTPCloudEventConverter.TYPE
+TypeStructured = structured.JSONHTTPCloudEventConverter.TYPE

cloudevents/sdk/__init__.py

@@ -0,0 +1,39 @@
+# All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+import typing
+
+from cloudevents.sdk.event import base
+
+
+class Converter(object):
+
+    TYPE = None
+
+    def __init__(
+            self, event_class: base.BaseEvent,
+            supported_media_types: typing.Mapping[str, bool]):
+        self.event = event_class()
+        self.supported_media_types = supported_media_types
+
+    def can_read(self, media_type: str) -> bool:
+        return media_type in self.supported_media_types
+
+    def read(self, headers: dict, body: typing.IO,
+             data_unmarshaller: typing.Callable) -> base.BaseEvent:
+        raise Exception("not implemented")
+
+    def write(self, event: base.BaseEvent,
+              data_marshaller: typing.Callable) -> (dict, typing.IO):
+        raise Exception("not implemented")

cloudevents/sdk/converters/__init__.py

@@ -0,0 +1,58 @@
+# All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+import typing
+
+from cloudevents.sdk import exceptions
+from cloudevents.sdk.converters import base
+from cloudevents.sdk.event import base as event_base
+from cloudevents.sdk.event import v01
+
+
+class BinaryHTTPCloudEventConverter(base.Converter):
+
+    TYPE = "binary"
+
+    def __init__(self, event_class: event_base.BaseEvent,
+                 supported_media_types: typing.Mapping[str, bool]):
+        if event_class == v01.Event:
+            raise exceptions.UnsupportedEvent(event_class)
+
+        super().__init__(event_class, supported_media_types)
+
+    def read(self,
+             headers: dict, body: typing.IO,
+             data_unmarshaller: typing.Callable) -> event_base.BaseEvent:
+        # we ignore headers, since the whole CE is in request body
+        event = self.event
+        event.UnmarshalBinary(headers, body, data_unmarshaller)
+        return event
+
+    def write(self, event: event_base.BaseEvent,
+              data_marshaller: typing.Callable) -> (dict, typing.IO):
+        if not isinstance(data_marshaller, typing.Callable):
+            raise exceptions.InvalidDataMarshaller()
+
+        hs, data = event.MarshalBinary()
+        return hs, data_marshaller(data)
+
+
+def NewBinaryHTTPCloudEventConverter(
+        event_class: event_base.BaseEvent) -> BinaryHTTPCloudEventConverter:
+    media_types = {
+        "application/json": True,
+        "application/xml": True,
+        "application/octet-stream": True,
+    }
+    return BinaryHTTPCloudEventConverter(event_class, media_types)