Merge pull request #499 from felicijus/feature/497-change-channel-par…

…ameter-grpc_address

feat: change channel parameter hostname, port to grpc_adress

README.md

@@ -45,7 +45,7 @@ import asyncio
 from pyzeebe import ZeebeWorker, Job, JobController, create_insecure_channel
 
 
-channel = create_insecure_channel(hostname="localhost", port=26500) # Create grpc channel
+channel = create_insecure_channel(grpc_address="localhost:26500") # Create grpc channel
 worker = ZeebeWorker(channel) # Create a zeebe worker
 
 
@@ -82,7 +82,7 @@ await zeebe_worker.stop() # Stops worker after all running jobs have been comple
 from pyzeebe import ZeebeClient, create_insecure_channel
 
 # Create a zeebe client
-channel = create_insecure_channel(hostname="localhost", port=26500)
+channel = create_insecure_channel(grpc_address="localhost:26500")
 zeebe_client = ZeebeClient(channel)
 
 # Run a Zeebe process instance

docs/channels.rst

@@ -22,7 +22,7 @@ Example:
 
     from pyzeebe import create_insecure_channel
 
-    channel = create_insecure_channel(hostname="zeebe", port=443)
+    channel = create_insecure_channel(grpc_address="localhost:26500")
 
 
 Secure
@@ -41,7 +41,7 @@ Example:
 
 
     grpc.ssl_channel_credentials(root_certificates="<root_certificate>", private_key="<private_key>")
-    channel = create_secure_channel(channel_credentials=credentials)
+    channel = create_secure_channel(grpc_address="host:port", channel_credentials=credentials)
 
 
 Example with oauth2 (like Camunda Identity):
@@ -57,7 +57,7 @@ Example with oauth2 (like Camunda Identity):
     call_credentials = grpc.metadata_call_credentials(AuthMetadataPlugin(credentials=credentials))
     ssl_credentials = grpc.ssl_channel_credentials(root_certificates="<root_certificate>", private_key="<private_key>")
     channel_credentials = grpc.composite_channel_credentials(ssl_credentials, call_credentials)
-    channel = create_secure_channel(channel_credentials=channel_credentials)
+    channel = create_secure_channel(grpc_address="host:port", channel_credentials=channel_credentials)
 
 
 Camunda Cloud

examples/client.py

@@ -6,7 +6,7 @@
 )
 
 # Create a zeebe client without credentials
-grpc_channel = create_insecure_channel(hostname="localhost", port=26500)
+grpc_channel = create_insecure_channel(grpc_address="localhost:26500")
 zeebe_client = ZeebeClient(grpc_channel)
 
 # Create a zeebe client with TLS

examples/worker.py

@@ -24,16 +24,16 @@ async def example_logging_task_decorator(job: Job) -> Job:
 grpc_channel = create_insecure_channel()
 worker = ZeebeWorker(grpc_channel)
 
-# With custom hostname/port
-grpc_channel = create_insecure_channel(hostname="zeebe-gateway.mydomain", port=443)
+# With custom grpc_address
+grpc_channel = create_insecure_channel(grpc_address="zeebe-gateway.mydomain:443")
 worker = ZeebeWorker(grpc_channel)
 
 # Will use environment variable ZEEBE_ADDRESS or localhost:26500 and use TLS
 grpc_channel = create_secure_channel()
 worker = ZeebeWorker(grpc_channel)
 
-# With custom hostname/port
-grpc_channel = create_secure_channel(hostname="zeebe-gateway.mydomain", port=443)
+# With custom grpc_address
+grpc_channel = create_secure_channel(grpc_address="zeebe-gateway.mydomain:443")
 worker = ZeebeWorker(grpc_channel)
 
 # Connect to zeebe cluster in camunda cloud

pyzeebe/channel/insecure_channel.py

@@ -8,19 +8,19 @@
 
 
 def create_insecure_channel(
-    hostname: Optional[str] = None, port: Optional[int] = None, channel_options: Optional[ChannelArgumentType] = None
+    grpc_address: Optional[str] = None, channel_options: Optional[ChannelArgumentType] = None
 ) -> grpc.aio.Channel:
     """
     Create an insecure channel
 
     Args:
-        hostname (Optional[str], optional): Zeebe gateway hostname
-        port (Optional[int], optional): Zeebe gateway port
+        grpc_address (Optional[str], optional): Zeebe Gateway Address
+            Default: None, alias the ZEEBE_ADDRESS environment variable or "localhost:26500"
         channel_options (Optional[Dict], optional): GRPC channel options.
             See https://grpc.github.io/grpc/python/glossary.html#term-channel_arguments
 
     Returns:
         grpc.aio.Channel: A GRPC Channel connected to the Zeebe gateway.
     """
-    address = create_address(hostname, port)
-    return grpc.aio.insecure_channel(address, options=get_channel_options(channel_options))
+    grpc_address = create_address(grpc_address=grpc_address)
+    return grpc.aio.insecure_channel(target=grpc_address, options=get_channel_options(channel_options))

pyzeebe/channel/secure_channel.py

@@ -8,17 +8,16 @@
 
 
 def create_secure_channel(
-    hostname: Optional[str] = None,
-    port: Optional[int] = None,
+    grpc_address: Optional[str] = None,
     channel_options: Optional[ChannelArgumentType] = None,
     channel_credentials: Optional[grpc.ChannelCredentials] = None,
 ) -> grpc.aio.Channel:
     """
     Create a secure channel
 
     Args:
-        hostname (Optional[str], optional): Zeebe gateway hostname
-        port (Optional[int], optional): Zeebe gateway port
+        grpc_address (Optional[str], optional): Zeebe Gateway Address
+            Default: None, alias the ZEEBE_ADDRESS environment variable or "localhost:26500"
         channel_options (Optional[Dict], optional): GRPC channel options.
             See https://grpc.github.io/grpc/python/glossary.html#term-channel_arguments
         channel_credentials (Optional[grpc.ChannelCredentials]): Channel credentials to use.
@@ -27,6 +26,8 @@ def create_secure_channel(
     Returns:
         grpc.aio.Channel: A GRPC Channel connected to the Zeebe gateway.
     """
-    address = create_address(hostname, port)
+    grpc_address = create_address(grpc_address=grpc_address)
     credentials = channel_credentials or grpc.ssl_channel_credentials()
-    return grpc.aio.secure_channel(address, credentials, options=get_channel_options(channel_options))
+    return grpc.aio.secure_channel(
+        target=grpc_address, credentials=credentials, options=get_channel_options(channel_options)
+    )

pyzeebe/channel/utils.py

@@ -1,15 +1,12 @@
 import os
 from typing import Optional
 
-DEFAULT_HOSTNAME = "localhost"
-DEFAULT_PORT = 26500
-DEFAULT_ADDRESS = f"{DEFAULT_HOSTNAME}:{DEFAULT_PORT}"
+DEFAULT_ZEEBE_ADDRESS = "localhost:26500"
 
 
 def create_address(
-    hostname: Optional[str] = None,
-    port: Optional[int] = None,
+    grpc_address: Optional[str] = None,
 ) -> str:
-    if hostname or port:
-        return f"{hostname or DEFAULT_HOSTNAME}:{port or DEFAULT_PORT}"
-    return os.getenv("ZEEBE_ADDRESS", DEFAULT_ADDRESS)
+    if grpc_address:
+        return grpc_address
+    return os.getenv("ZEEBE_ADDRESS", DEFAULT_ZEEBE_ADDRESS)

tests/unit/channel/insecure_channel_test.py

@@ -1,12 +1,11 @@
 from unittest.mock import Mock, patch
-from uuid import uuid4
 
 import grpc
 import pytest
 
 from pyzeebe import create_insecure_channel
 from pyzeebe.channel.channel_options import get_channel_options
-from pyzeebe.channel.utils import DEFAULT_HOSTNAME, DEFAULT_PORT, create_address
+from pyzeebe.channel.utils import create_address
 
 
 class TestCreateInsecureChannel:
@@ -30,20 +29,4 @@ def test_uses_default_address(self, insecure_channel_mock: Mock):
         create_insecure_channel()
 
         insecure_channel_call = insecure_channel_mock.mock_calls[0]
-        assert insecure_channel_call.args[0] == create_address()
-
-    def test_overrides_default_port_if_provided(self, insecure_channel_mock: Mock):
-        port = 123
-
-        create_insecure_channel(port=port)
-
-        insecure_channel_call = insecure_channel_mock.mock_calls[0]
-        assert insecure_channel_call.args[0] == f"{DEFAULT_HOSTNAME}:{port}"
-
-    def test_overrides_default_hostname_if_provided(self, insecure_channel_mock: Mock):
-        hostname = str(uuid4())
-
-        create_insecure_channel(hostname=hostname)
-
-        insecure_channel_call = insecure_channel_mock.mock_calls[0]
-        assert insecure_channel_call.args[0] == f"{hostname}:{DEFAULT_PORT}"
+        assert insecure_channel_call.kwargs["target"] == create_address()

tests/unit/channel/secure_channel_test.py

@@ -1,12 +1,11 @@
 from unittest.mock import Mock, patch
-from uuid import uuid4
 
 import grpc
 import pytest
 
 from pyzeebe import create_secure_channel
 from pyzeebe.channel.channel_options import get_channel_options
-from pyzeebe.channel.utils import DEFAULT_HOSTNAME, DEFAULT_PORT, create_address
+from pyzeebe.channel.utils import create_address
 
 
 class TestCreateSecureChannel:
@@ -36,20 +35,4 @@ def test_uses_default_address(self, secure_channel_mock: Mock):
         create_secure_channel()
 
         secure_channel_call = secure_channel_mock.mock_calls[0]
-        assert secure_channel_call.args[0] == create_address()
-
-    def test_overrides_default_port_if_provided(self, secure_channel_mock: Mock):
-        port = 123
-
-        create_secure_channel(port=port)
-
-        secure_channel_call = secure_channel_mock.mock_calls[0]
-        assert secure_channel_call.args[0] == f"{DEFAULT_HOSTNAME}:{port}"
-
-    def test_overrides_default_hostname_if_provided(self, secure_channel_mock: Mock):
-        hostname = str(uuid4())
-
-        create_secure_channel(hostname=hostname)
-
-        secure_channel_call = secure_channel_mock.mock_calls[0]
-        assert secure_channel_call.args[0] == f"{hostname}:{DEFAULT_PORT}"
+        assert secure_channel_call.kwargs["target"] == create_address()

tests/unit/channel/utils_test.py

@@ -1,24 +1,20 @@
 import os
 from uuid import uuid4
 
-from pyzeebe.channel.utils import DEFAULT_ADDRESS, create_address
+from pyzeebe.channel.utils import DEFAULT_ZEEBE_ADDRESS, create_address
 
 
 class TestCreateAddress:
-    def test_returns_default_address(self):
-        address = create_address()
-
-        assert address == DEFAULT_ADDRESS
 
-    def test_default_port_is_26500(self):
-        address = create_address(hostname=str(uuid4()))
+    def test_returns_passed_address(self):
+        address = str(uuid4())
 
-        assert address.split(":")[1] == "26500"
+        assert address == create_address(address)
 
-    def test_default_hostname_is_localhost(self):
-        address = create_address(port=12)
+    def test_returns_default_address(self):
+        address = create_address()
 
-        assert address.split(":")[0] == "localhost"
+        assert address == DEFAULT_ZEEBE_ADDRESS
 
     def test_returns_env_var_if_provided(self):
         zeebe_address = str(uuid4())