Merge pull request #188 from camunda-community-hub/feature/custom-grp…

…c-channel

Provide custom grpc channel

.bumpversion.cfg

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

Pipfile

@@ -19,6 +19,7 @@ pytest-mock = "*"
 pytest-asyncio = "~=0.15.1"
 asyncmock = "~=0.4.2"
 bump2version = "~=1.0.1"
+responses = "~=0.13.3"
 
 [packages]
 oauthlib = "~=3.1.0"

README.md

@@ -37,7 +37,11 @@ The `ZeebeWorker` class uses threading to get and run jobs.
 ```python
 import asyncio
 
-from pyzeebe import ZeebeWorker, Job
+from pyzeebe import ZeebeWorker, Job, create_insecure_channel
+
+
+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):
@@ -48,9 +52,6 @@ async def on_error(exception: Exception, job: Job):
     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) -> dict:
     return {"output": f"Hello world, {input}!"}
@@ -72,10 +73,11 @@ await zeebe_worker.stop() # Stops worker after all running jobs have been comple
 ### 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 Zeebe process instance
 process_instance_key = await zeebe_client.run_process(bpmn_process_id="My zeebe process", variables={})

docs/channels.rst

@@ -0,0 +1,64 @@
+========
+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
+
+
+.. autoclass:: pyzeebe.create_insecure_channel
+    :members:
+
+
+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
+
+.. autoclass:: pyzeebe.create_secure_channel
+    :members:
+
+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
+
+.. autoclass:: pyzeebe.create_camunda_cloud_channel
+    :members:
+
+Example:
+
+.. code-block:: python
+
+    from pyzeebe import create_camunda_cloud_channel
+
+    
+    channel = create_camunda_cloud_channel("client_id", "client_secret", "cluster_id")

docs/client_quickstart.rst

@@ -9,23 +9,17 @@ To create a client with default configuration:
 
 .. code-block:: python
 
-    from pyzeebe import ZeebeClient
+    from pyzeebe import ZeebeClient, create_insecure_channel
 
-    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)
+    channel = create_insecure_channel()  # Will use ZEEBE_ADDRESS environment variable or localhost:26500
+    client = ZeebeClient(channel)
 
 
 To change connection retries:
 
 .. code-block:: python
 
-    client = ZeebeClient(max_connection_retries=1)  # Will only accept one failure and disconnect upon the second
+    client = ZeebeClient(grpc_channel, max_connection_retries=1)  # Will only accept one failure and disconnect upon the second
 
 
 This means the client will disconnect upon two consecutive failures. Each time the client connects successfully the counter is reset.
@@ -36,33 +30,6 @@ This means the client will disconnect upon two consecutive failures. Each time t
 
 
 
-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 Zeebe process instance
 ----------------------------
 

docs/conf.py

@@ -26,7 +26,7 @@
 author = 'Jonatan Martens'
 
 # The full version, including alpha/beta/rc tags
-release = '3.0.0rc2'
+release = '3.0.0rc3'
 
 # -- General configuration ---------------------------------------------------
 
@@ -59,6 +59,6 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-version = "3.0.0rc2"
+version = "3.0.0rc3"
 
 master_doc = 'index'

docs/index.rst

@@ -19,9 +19,10 @@ Creating a worker
 
 .. code-block:: python
 
-   from pyzeebe import ZeebeWorker
+   from pyzeebe import ZeebeWorker, create_insecure_channel
 
-   worker = ZeebeWorker()
+   channel = create_insecure_channel()
+   worker = ZeebeWorker(channel)
 
    @worker.task(task_type="my_task")
    async def my_task(x: int):
@@ -33,9 +34,10 @@ Creating a client
 
 .. code-block:: python
 
-   from pyzeebe import ZeebeClient
+   from pyzeebe import ZeebeClient, create_insecure_channel
 
-   client = ZeebeClient()
+   channel = create_insecure_channel()
+   client = ZeebeClient(channel)
 
    await client.run_process("my_process")
 
@@ -61,5 +63,6 @@ Table Of Contents
 
     Client <client>
     Worker <worker>
+    Channels <channels>
     Decorators <decorators>
     Exceptions <errors>