Merge pull request #222 from camunda-community-hub/development

v3.0.0

.bumpversion.cfg

@@ -0,0 +1,23 @@
+[bumpversion]
+current_version = 3.0.0
+commit = True
+parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(?P<rc>.*)
+serialize = 
+	{major}.{minor}.{patch}{rc}
+	{major}.{minor}.{patch}
+
+[bumpversion:part:rc]
+optional_value = final
+values = 
+	rc1
+	rc2
+	rc3
+	rc4
+	rc5
+	final
+
+[bumpversion:file:setup.py]
+
+[bumpversion:file:pyzeebe/__init__.py]
+
+[bumpversion:file:docs/conf.py]

.github/workflows/lint.yml

@@ -0,0 +1,33 @@
+name: Lint pyzeebe
+
+on: [push, pull_request]
+
+jobs:
+  type-checking:
+
+    runs-on: ubuntu-latest
+
+    container: python:3.8
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install dependencies
+        run: |
+          pip install pipenv
+          pipenv install --dev
+      - name: Lint with mypy
+        run: |
+          pipenv run mypy pyzeebe
+
+  import-checking:
+    runs-on: ubuntu-latest
+
+    container: python:3.8
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install dependencies
+        run: |
+          pip install pipenv
+          pipenv install --dev
+      - name: Check imports
+        run: |
+          pipenv run isort . --check --diff

.github/workflows/publish-python-package.yml

@@ -2,7 +2,7 @@ name: Publish pyzeebe
 
 on:
   release:
-    types: [created]
+    types: [created, prereleased]
 
 jobs:
   publish:

.github/workflows/test-python-package.yml

@@ -1,10 +1,6 @@
 name: Test pyzeebe
 
-on:
-  push:
-    branches: [ master, development, feature/*, bugfix/*, maintenance/* ]
-  pull_request:
-    branches: [ master, development, feature/*, bugfix/*, maintenance/* ]
+on: [push, pull_request]
 
 jobs:
   build:

.github/workflows/test-zeebe-integration.yml

@@ -1,10 +1,6 @@
 name: Integration test pyzeebe
 
-on:
-  push:
-    branches: [ master, development, feature/*, bugfix/*, maintenance/* ]
-  pull_request:
-    branches: [ master, development, feature/*, bugfix/*, maintenance/* ]
+on: [push, pull_request]
 
 jobs:
   test:
@@ -13,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        zeebe-version: [ "0.23.7", "0.24.6", "0.25.3", "0.26.0" ]
+        zeebe-version: [ "1.0.0" ]
 
     container: python:3.6
 

.mypy.ini

@@ -0,0 +1,22 @@
+[mypy]
+
+[mypy-grpc]
+ignore_missing_imports = True
+
+[mypy-oauthlib]
+ignore_missing_imports = True
+
+[mypy-requests_oauthlib]
+ignore_missing_imports = True
+
+[mypy-zeebe_grpc.gateway_pb2]
+ignore_missing_imports = True
+
+[mypy-zeebe_grpc.gateway_pb2_grpc]
+ignore_missing_imports = True
+
+[mypy-requests]
+ignore_missing_imports = True
+
+[mypy-aiofiles]
+ignore_missing_imports = True

Pipfile

@@ -16,8 +16,16 @@ pyzeebe = {editable = true, path = "."}
 sphinx = "~=3.5.2"
 sphinx-rtd-theme = "*"
 pytest-mock = "*"
+pytest-asyncio = "~=0.15.1"
+asyncmock = "~=0.4.2"
+bump2version = "~=1.0.1"
+responses = "~=0.13.3"
 
 [packages]
 oauthlib = "~=3.1.0"
 requests-oauthlib = "~=1.3.0"
-zeebe-grpc = "~=0.26.0.0"
+zeebe-grpc = "~=1.0.0"
+aiofiles = "~=0.7.0"
+
+[pipenv]
+allow_prereleases = true

README.md

@@ -19,6 +19,7 @@ Zeebe version support:
 
 | Pyzeebe version | Tested Zeebe versions  |
 | :-------------: | ---------------------- |
+|      3.x.x      | 1.0.0                  |
 |      2.x.x      | 0.23, 0.24, 0.25, 0.26 |
 |      1.x.x      | 0.23, 0.24             |
 
@@ -37,58 +38,68 @@ For full documentation please visit: https://pyzeebe.readthedocs.io/en/stable/
 The `ZeebeWorker` class uses threading to get and run jobs.
 
 ```python
-from pyzeebe import ZeebeWorker, Job
+import asyncio
 
+from pyzeebe import ZeebeWorker, Job, create_insecure_channel
 
-def on_error(exception: Exception, job: Job):
+
+channel = create_insecure_channel(hostname="localhost", port=26500) # Create grpc channel
+worker = ZeebeWorker(channel) # Create a zeebe worker
+
+
+async def on_error(exception: Exception, job: Job):
     """
     on_error will be called when the task fails
     """
     print(exception)
-    job.set_error_status(f"Failed to handle job {job}. Error: {str(exception)}")
+    await job.set_error_status(f"Failed to handle job {job}. Error: {str(exception)}")
 
 
-
-worker = ZeebeWorker(hostname="<zeebe_host>", port=26500) # Create a zeebe worker
-
 @worker.task(task_type="example", exception_handler=on_error)
-def example_task(input: str):
+def example_task(input: str) -> dict:
     return {"output": f"Hello world, {input}!"}
 
 
-worker.work() # Now every time that a task with type example is called example_task will be called
+@worker.task(task_type="example2", exception_handler=on_error)
+async def another_example_task(name: str) -> dict: # Tasks can also be async
+    return {"output": f"Hello world, {name} from async task!"}
+
+loop = asyncio.get_running_loop()
+loop.run_until_complete(worker.work()) # Now every time that a task with type `example` or `example2` is called, the corresponding function will be called
 ```
 
 Stop a worker:
 
 ```python
-zeebe_worker.work() # Worker will begin working
-zeebe_worker.stop() # Stops worker after all running jobs have been completed
+await zeebe_worker.stop() # Stops worker after all running jobs have been completed
 ```
 
 ### Client
 
 ```python
-from pyzeebe import ZeebeClient
+from pyzeebe import ZeebeClient, create_insecure_channel
 
 # Create a zeebe client
-zeebe_client = ZeebeClient(hostname="localhost", port=26500)
+channel = create_insecure_channel(hostname="localhost", port=26500)
+zeebe_client = ZeebeClient(channel)
 
-# Run a workflow
-workflow_instance_key = zeebe_client.run_workflow(bpmn_process_id="My zeebe workflow", variables={})
+# Run a Zeebe process instance
+process_instance_key = await zeebe_client.run_process(bpmn_process_id="My zeebe process", variables={})
 
-# Run a workflow and receive the result
-workflow_result = zeebe_client.run_workflow_with_result(bpmn_process_id="My zeebe workflow",
-                                                        timeout=10000)  # Will wait 10000 milliseconds (10 seconds)
+# Run a process and receive the result
+process_instance_key, process_result = await zeebe_client.run_process_with_result(
+    bpmn_process_id="My zeebe process",
+    timeout=10000
+)
 
-# Deploy a bpmn workflow definition
-zeebe_client.deploy_workflow("workflow.bpmn")
+# Deploy a BPMN process definition
+await zeebe_client.deploy_process("process.bpmn")
 
-# Cancel a running workflow
-zeebe_client.cancel_workflow_instance(workflow_instance_key=12345)
+# Cancel a running process
+await zeebe_client.cancel_process_instance(process_instance_key=12345)
 
 # Publish message
-zeebe_client.publish_message(name="message_name", correlation_key="some_id")
+await zeebe_client.publish_message(name="message_name", correlation_key="some_id")
 
 ```
 
@@ -108,6 +119,16 @@ Please make sure to update tests as appropriate.
 
 We use [SemVer](semver.org) for versioning. For the versions available, see the tags on this repository.
 
+In order to bump the current version run:
+
+```shell
+$ bump2version <part>
+```
+
+where part is the part that will be bumped (major/minor/patch/rc).
+
+This will bump the version in all relevant files as well as create a git commit.
+
 ## License
 
 We use the MIT license, see [LICENSE.md](LICENSE.md) for details

docs/channels.rst

@@ -0,0 +1,61 @@
+========
+Channels
+========
+
+In order to instantiate a ZeebeWorker or ZeebeClient you will need to provide an instance of a `grpc.aio.Channel`.
+
+Pyzeebe provides a couple standard ways to achieve this:
+
+
+Insecure
+--------
+
+Create a grpc channel connected to a Zeebe Gateway with tls disabled
+
+
+.. autofunction:: pyzeebe.create_insecure_channel
+
+
+Example:
+
+.. code-block:: python
+
+    from pyzeebe import create_insecure_channel
+
+    channel = create_insecure_channel(hostname="zeebe", port=443)
+
+
+Secure
+------
+
+Create a grpc channel with a secure connection to a Zeebe Gateway with tls
+
+.. autofunction:: pyzeebe.create_secure_channel
+
+Example:
+
+.. code-block:: python
+
+    import grpc
+    from pyzeebe import create_secure_channel
+
+
+    grpc.ssl_channel_credentials(root_certificates="<root_certificate>", private_key="<private_key>")
+    channel = create_secure_channel(channel_credentials=credentials)
+
+
+Camunda Cloud
+-------------
+
+Create a grpc channel connected to a Zeebe Gateway running in camunda cloud
+
+.. autofunction:: pyzeebe.create_camunda_cloud_channel
+
+Example:
+
+.. code-block:: python
+
+    from pyzeebe import create_camunda_cloud_channel
+
+    
+    channel = create_camunda_cloud_channel("client_id", "client_secret", "cluster_id")