Merge pull request #50 from JonatanMartens/development

v2.2.0

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,66 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [master, development]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [master, development]
+  schedule:
+    - cron: '0 13 * * 0'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # Override automatic language detection by changing the below list
+        # Supported options are ['csharp', 'cpp', 'go', 'java', 'javascript', 'python']
+        language: ['python']
+        # Learn more...
+        # https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#overriding-automatic-language-detection
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+      with:
+        # We must fetch at least the immediate parents so that if this is
+        # a pull request then we can checkout the head.
+        fetch-depth: 2
+
+    # If this run was triggered by a pull request event, then checkout
+    # the head of the pull request instead of the merge commit.
+    - run: git checkout HEAD^2
+      if: ${{ github.event_name == 'pull_request' }}
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file. 
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v1
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 https://git.io/JvXDl
+
+    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+    #    and modify them (or add more) to build your code if your project
+    #    uses a compiled language
+
+    #- run: |
+    #   make bootstrap
+    #   make release
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

.readthedocs.yml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  image: latest
+python:
+  version: 3.8
+  install:
+    - method: pip
+      path: .
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+  fail_on_warning: true

Pipfile

@@ -13,6 +13,8 @@ mypy = "~=0.782"
 coveralls = "~=2.1.2"
 importlib-metadata = "~=1.7.0"
 pyzeebe = {editable = true, path = "."}
+sphinx = "~=3.2.1"
+sphinx-rtd-theme = "*"
 
 [packages]
 grpcio = "~=1.31.0"

README.md

@@ -25,6 +25,8 @@ To install:
 
 `pip install pyzeebe`
 
+For full documentation please visit: https://pyzeebe.readthedocs.io/en/stable/
+
 ## Usage
 
 ### Worker

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# 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)

docs/client.rst

@@ -0,0 +1,9 @@
+======
+Client
+======
+
+.. toctree::
+    :name: client
+
+    Quickstart <client_quickstart>
+    Reference <client_reference>

docs/client_quickstart.rst

@@ -0,0 +1,83 @@
+=================
+Client QuickStart
+=================
+
+Create a client
+---------------
+
+To create a client with default configuration:
+
+.. code-block:: python
+
+    from pyzeebe import ZeebeClient
+
+    client = ZeebeClient()  # Will use ZEEBE_ADDRESS environment variable or localhost:26500
+
+
+To create a client with custom hostname and port:
+
+.. code-block:: python
+
+    client = ZeebeClient(hostname="zeebe_gateway", port=26500)
+
+To create a client with a secure connection:
+
+.. code-block:: python
+
+    client = ZeebeClient(secure_connection=True)
+
+To create a client with OAuth 2.0 authentication:
+
+.. code-block:: python
+
+    from pyzeebe import ZeebeClient, OAuthCredentials
+
+    credentials = OAuthCredentials(url="oauth_token_url", client_id="client_id", client_secret="client_secret",
+                                   audience="audience")
+    client = ZeebeClient()
+
+To create a client for a Camunda Cloud instance:
+
+.. code-block:: python
+
+    from pyzeebe import ZeebeClient, CamundaCloudCredentials
+
+    credentials = CamundaCloudCredentials(client_id="client_id", client_secret="client_secret",
+                                          cluster_id="cluster_id")
+    client = ZeebeClient()
+
+
+Run a workflow
+--------------
+
+.. code-block:: python
+
+    workflow_instance_key = client.run_workflow("bpmn_process_id")
+
+
+Run a workflow with result
+--------------------------
+
+To run a workflow and receive the result directly:
+
+.. code-block:: python
+
+    result = client.run_workflow_with_result("bpmn_process_id")
+
+    # result will be a dict
+
+
+Deploy a workflow
+-----------------
+
+.. code-block:: python
+
+    client.deploy_workflow("workflow_file.bpmn")
+
+
+Publish a message
+-----------------
+
+.. code-block:: python
+
+    client.publish_message(name="message_name", correlation_key="correlation_key")

docs/client_reference.rst

@@ -0,0 +1,7 @@
+================
+Client Reference
+================
+
+.. autoclass:: pyzeebe.ZeebeClient
+   :members:
+   :undoc-members:

docs/conf.py

@@ -0,0 +1,64 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+import sphinx_rtd_theme
+
+sys.path.insert(0, os.path.abspath('..'))
+
+# -- Project information -----------------------------------------------------
+
+sphinx_rtd_theme  # So optimize imports doens't erase it
+
+project = 'pyzeebe'
+copyright = '2020, Jonatan Martens'
+author = 'Jonatan Martens'
+
+# The full version, including alpha/beta/rc tags
+release = '2.1.0'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon"
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+version = "2.2.0"
+
+master_doc = 'index'

docs/decorators.rst

@@ -0,0 +1,96 @@
+==========
+Decorators
+==========
+
+A ``pyzeebe`` decorator is a function that receives a :py:class:`Job` instance and returns a :py:class:`Job`.
+
+.. code-block:: python
+
+    Callable[[Job], Job]
+
+An example decorator:
+
+.. code-block:: python
+
+    def logging_decorator(job: Job) -> Job:
+        logging.info(job)
+        return job
+
+If a decorator raises an :class:`Exception` ``pyzeebe`` will just ignore it and continue the task/other decorators.
+
+Task Decorators
+---------------
+
+To add a decorator to a :py:class:`Task`:
+
+.. code-block:: python
+
+    from pyzeebe import Job
+
+
+    def my_decorator(job: Job) -> Job:
+        print(job)
+        return job
+
+
+    @worker.task(task_type="my_task", before=[my_decorator], after=[my_decorator])
+    def my_task():
+        return {}
+
+Now before and after a job is performed ``my_decorator`` will be called.
+
+TaskRouter Decorators
+---------------------
+
+You can also add a decorator to a :py:class:`ZeebeTaskRouter`. All tasks registered under the router will then have the decorator.
+
+
+.. code-block:: python
+
+    from pyzeebe import ZeebeTaskRouter, Job
+
+    router = ZeebeTaskRouter()
+
+    def my_decorator(job: Job) -> Job:
+        print(job)
+        return job
+
+
+    router.before(my_decorator)
+    router.after(my_decorator)
+
+Now all tasks registered to the router will have ``my_decorator``.
+
+Worker Decorators
+-----------------
+
+You can also add a decorator to a :py:class:`ZeebeWorker`. All tasks registered under the worker will then have the decorator.
+
+
+.. code-block:: python
+
+    from pyzeebe import ZeebeWorker, Job
+
+    worker = ZeebeWorker()
+
+    def my_decorator(job: Job) -> Job:
+        print(job)
+        return job
+
+
+    worker.before(my_decorator)
+    worker.after(my_decorator)
+
+Now all tasks registered to the worker will have ``my_decorator``.
+
+
+Decorator order
+---------------
+
+``Worker`` -> ``Router`` -> ``Task``  -> Actual task function -> ``Task`` -> ``Router`` -> ``Worker``
+
+``Worker`` - Decorators registered via the :py:class:`ZeebeWorker` class.
+
+``Router`` - Decorators registered via the :py:class:`ZeebeTaskRouter` class and included in the worker with ``include_router``.
+
+``Task`` - Decorators registered to the :py:class:`Task` class (with the worker/router ``task`` decorator).