processcube-etw-library 2026.1.22.145211__py3-none-any.whl → 2026.1.29.71849b0__py3-none-any.whl

processcube_etw_library/processcube_client/core/api/helpers/process_models.py

@@ -0,0 +1,51 @@
+from dataclasses import dataclass, field
+from dataclasses_json import dataclass_json, LetterCase
+from enum import IntFlag
+from typing import Callable, Optional
+
+from ..base_client import BaseClient
+
+
+class StartCallbackType(IntFlag):
+    CallbackOnProcessInstanceCreated = 1
+    CallbackOnProcessInstanceFinished = 2
+    CallbackOnEndEventReached = 3
+
+
+@dataclass_json(letter_case=LetterCase.CAMEL)
+@dataclass
+class ProcessStartRequest:
+    process_model_id: str
+    return_on: StartCallbackType = StartCallbackType.CallbackOnEndEventReached
+    end_event_id: str = None
+    start_event_id: str = None
+    correlation_id: str = None
+    initial_token: dict = None
+    parent_process_instance_id: str = None
+
+
+@dataclass_json(letter_case=LetterCase.CAMEL)
+@dataclass
+class ProcessStartResponse:
+    process_instance_id: str
+    correlation_id: str
+    end_event_id: Optional[str] = None
+    token_payload: dict = field(default_factory=dict)
+
+
+class ProcessModelHandler(BaseClient):
+    def __init__(self, url: str, identity: Callable = None, api_version: str = "v1"):
+        super(ProcessModelHandler, self).__init__(url, identity, api_version)
+
+    def start(
+        self, process_model_id: str, request: ProcessStartRequest, options: dict = {}
+    ) -> ProcessStartResponse:
+        path = f"process_models/{process_model_id}/start"
+
+        payload = request.to_dict()
+
+        response_json = self.do_post(path, payload, options)
+
+        response = ProcessStartResponse.from_dict(response_json)
+
+        return response

processcube_etw_library/processcube_client/core/api/helpers/user_tasks.py

@@ -0,0 +1,130 @@
+from dataclasses import dataclass, field
+from dataclasses_json import dataclass_json, LetterCase, Undefined, config
+from typing import Any, Callable, List, Dict, Optional
+from urllib import parse
+
+from ..base_client import BaseClient
+
+
+@dataclass_json(letter_case=LetterCase.CAMEL)
+@dataclass
+class UserTaskQuery:
+    limit: int = 0
+    offset: int = 0
+    user_task_instance_id: str = field(
+        metadata=config(field_name="flowNodeInstanceId"), default=None
+    )
+    flow_node_id: str = None
+    flow_node_name: str = None
+    flow_node_lane: str = None
+    correlation_id: str = None
+    process_definition_id: str = None
+    process_model_id: str = None
+    process_instance_id: str = None
+    owner_id: str = None
+    state: str = None
+
+
+@dataclass_json(letter_case=LetterCase.CAMEL)
+@dataclass
+class FormFields:
+    id: str
+    type: str
+    label: str
+    default_value: Optional[str] = None
+
+
+@dataclass_json(letter_case=LetterCase.CAMEL)
+@dataclass
+class UserTaskConfig:
+    form_fields: List[FormFields]
+    custom_form: str = "DynamicForm"
+
+
+@dataclass_json(letter_case=LetterCase.CAMEL, undefined=Undefined.EXCLUDE)
+# @dataclass_json(letter_case=LetterCase.CAMEL, undefined=Undefined.INCLUDE)
+@dataclass
+class UserTaskResponse:
+    user_task_instance_id: str = field(metadata=config(field_name="flowNodeInstanceId"))
+    user_task_config: UserTaskConfig
+    owner_id: str
+    correlation_id: str
+    process_instance_id: str
+    process_model_id: str
+    flow_node_name: str
+    actual_owner_id: Optional[str] = None
+    # place_holder: CatchAll
+
+
+@dataclass_json(letter_case=LetterCase.CAMEL)
+@dataclass
+class ReserveUserTaskRequest:
+    actual_owner_id: str = None
+
+
+class UserTaskHandler(BaseClient):
+    BPMN_TYPE = "bpmn:UserTask"
+
+    def __init__(self, url: str, identity: Callable = None, api_version: str = "v1"):
+        super(UserTaskHandler, self).__init__(url, identity, api_version)
+
+    def query(
+        self, request: UserTaskQuery = UserTaskQuery(), options: dict = {}
+    ) -> List[UserTaskResponse]:
+        query_dict = request.to_dict()
+        query_dict.update(
+            {
+                "state": "suspended",
+                "flowNodeType": UserTaskHandler.BPMN_TYPE,
+            }
+        )
+
+        filtered_query = list(
+            filter(lambda dict_entry: dict_entry[1] is not None, query_dict.items())
+        )
+
+        query_str = parse.urlencode(filtered_query, doseq=False)
+
+        path = f"flow_node_instances?{query_str}"
+
+        response_list_of_dict = self.do_get(path, options)
+
+        if response_list_of_dict.get("totalCount", 0) > 0:
+            json_data = response_list_of_dict.get("flowNodeInstances", {})
+            response = UserTaskResponse.schema().load(json_data, many=True)
+        else:
+            response = []
+
+        return response
+
+    def reserve(
+        self,
+        user_task_instance_id: str,
+        request: ReserveUserTaskRequest,
+        options: dict = {},
+    ) -> bool:
+        path = f"user_tasks/{user_task_instance_id}/reserve"
+
+        payload = request.to_dict()
+
+        _ = self.do_put(path, payload, options)
+
+        return True
+
+    def finish(
+        self, user_task_instance_id: str, request: Dict[str, Any], options: dict = {}
+    ) -> bool:
+        path = f"user_tasks/{user_task_instance_id}/finish"
+
+        _ = self.do_put(path, request, options)
+
+        return True
+
+    def cancel_reservation(
+        self, user_task_instance_id: str, options: dict = {}
+    ) -> bool:
+        path = f"user_tasks/{user_task_instance_id}/cancel-reservation"
+
+        _ = self.do_delete(path, options)
+
+        return True

processcube_etw_library/processcube_client/core/base_client.py

@@ -0,0 +1,175 @@
+import asyncio
+import aiohttp
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def run_async_in_sync_context(coro):
+    """Run an async coroutine in a synchronous context, compatible with Python 3.10+
+
+    This function handles the proper creation and management of event loops
+    for running async code from sync code. It's compatible with nested event loops
+    (e.g., in Jupyter notebooks when nest_asyncio is applied).
+
+    Args:
+        coro: The coroutine to run
+
+    Returns:
+        The result of the coroutine
+    """
+    try:
+        # Try to get the running loop (will work in async context)
+        loop = asyncio.get_running_loop()
+        # If we're here, we're already in an async context - this shouldn't happen
+        # in normal sync-to-async transitions but can happen with nest_asyncio
+        raise RuntimeError("Cannot use run_async_in_sync_context from an async context")
+    except RuntimeError:
+        # No running loop - we're in a sync context, which is what we want
+        pass
+
+    # Try to get or create an event loop
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_closed():
+            raise RuntimeError("Event loop is closed")
+        if loop.is_running():
+            # Loop is running but we're not in it - this can happen with nest_asyncio
+            # In this case, we need to schedule the coroutine on the existing loop
+            import concurrent.futures
+            future = asyncio.run_coroutine_threadsafe(coro, loop)
+            return future.result()
+    except RuntimeError:
+        # No event loop or it's closed - create a new one
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+    # Run the coroutine
+    try:
+        result = loop.run_until_complete(coro)
+        return result
+    finally:
+        # Don't close the loop if it was already set as the event loop for this thread
+        # This allows it to be reused in subsequent calls
+        pass
+
+
+class BaseClient:
+
+    def __init__(self, url, session=None, identity=None):
+        self._url = url
+        self._session = session
+
+        if identity is None:
+            self._identity = {"token": "ZHVtbXlfdG9rZW4="}
+        else:
+            self._identity = identity
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exception_type, exception_value, traceback):
+        await self.close() 
+
+    async def close(self):
+        if self._session:
+            await self._session.close()
+
+    async def do_get(self, path, options={}):
+        headers = self.__get_default_headers()
+        headers.update(options.get('headers', {}))
+        headers.update(self.__get_auth_headers())
+
+        request_url = f"{self._url}{path}"
+
+        async with aiohttp.ClientSession() as session:
+
+            current_session = self._session if self._session else session
+
+            async with current_session.get(request_url, headers=headers) as response:
+                response.raise_for_status()
+                if response.status == 200:
+                    return await response.json()
+
+    async def do_delete(self, path, options={}):
+        headers = self.__get_default_headers()
+        headers.update(options.get('headers', {}))
+        headers.update(self.__get_auth_headers())
+
+        request_url = f"{self._url}{path}"
+
+        async with aiohttp.ClientSession() as session:
+
+            current_session = self._session if self._session else session
+
+            async with current_session.delete(request_url, headers=headers) as response:
+                response.raise_for_status()
+                if response.status == 200:
+                    return await response.json()
+
+    async def do_post(self, path, payload, options={}):
+        headers = self.__get_default_headers()
+        headers.update(options.get('headers', {}))
+        headers.update(self.__get_auth_headers())
+
+        request_url = f"{self._url}{path}"
+
+        logger.debug(f"post request to {request_url} with json payload {payload}")
+
+        async with aiohttp.ClientSession() as session:
+
+            current_session = self._session if self._session else session
+
+            async with current_session.post(request_url, json=payload, headers=headers) as response:
+                logger.debug(f"handle response {response.status}")
+                response.raise_for_status()
+                if response.status in [200, 201, 202]:
+                    return await response.json()
+                elif response.status == 204:
+                    return ""
+                else:
+                    raise Exception(f"TODO: need a better error {response.status}")
+    
+    async def do_put(self, path, payload, options={}):
+        headers = self.__get_default_headers()
+        headers.update(options.get('headers', {}))
+        headers.update(self.__get_auth_headers())
+
+        request_url = f"{self._url}{path}"
+
+        logger.debug(f"put request to {request_url} with json payload {payload}")
+
+        async with aiohttp.ClientSession() as session:
+
+            current_session = self._session if self._session else session
+
+            async with current_session.put(request_url, json=payload, headers=headers) as response:
+                logger.debug(f"handle response {response.status}")
+                response.raise_for_status()
+                if response.status in [200, 201, 202]:
+                    return await response.json()
+                elif response.status == 204:
+                    return ""
+                else:
+                    raise Exception(f"TODO: need a better error {response.status}")
+    
+    async def get_serverinfo(self):
+        return await self.do_get('/atlas_engine/api/v1/info')
+
+    def __get_auth_headers(self):
+        identity = self.__get_identity()
+        token = identity['token']
+        return {'Authorization': 'Bearer {}'.format(token)}
+
+    def __get_default_headers(self):
+        return {'Content-Type': 'application/json'}
+
+    def __get_identity(self):
+        identity = self._identity
+
+        if callable(self._identity):
+            identity = self._identity()
+
+        return identity
+            

processcube_etw_library/processcube_client/core/loop_helper.py

@@ -0,0 +1,200 @@
+import asyncio
+import logging
+import signal
+import os
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_DELAY = 0.1
+
+def ensure_has_loop():
+    loop = get_or_create_loop()
+
+    return loop
+
+def get_or_create_loop():
+    """Get or create an event loop, compatible with Python 3.10+
+
+    In Python 3.10+, asyncio.get_event_loop() raises RuntimeError if there's
+    no running event loop in the current thread. This function handles that gracefully.
+    """
+    try:
+        # Try to get the current event loop
+        loop = asyncio.get_event_loop()
+        # Check if the loop is closed (also an error condition)
+        if loop.is_closed():
+            raise RuntimeError("Event loop is closed")
+        return loop
+    except RuntimeError:
+        # No event loop in current thread or loop is closed - create a new one
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        return loop
+
+class LoopHelper:
+
+    # TODO: mm - remove kwargs with better readable params
+    def __init__(self, loop=get_or_create_loop(), **kwargs):
+        self._loop = loop
+        self._tasks = []
+        self._run_forever = kwargs.get('run_forever', not self._loop.is_running())
+        self._install_signals = kwargs.get('install_signals', True)
+
+        self.on_shutdown = kwargs.get('on_shutdown', self.__internal_on_shutdown)
+
+    def create_task(self, task_callback):
+        task = asyncio.run_coroutine_threadsafe(task_callback(), self._loop)
+        self._tasks.append(task)
+
+    def register_delayed_task(self, task_func, **options):
+        logger.info(f"Create delayed tasks with options ({options}).")
+        task = asyncio.run_coroutine_threadsafe(self.__create_delayed_task(task_func, **options), self._loop)
+        self._tasks.append(task)
+
+        return task
+
+    def unregister_delayed_task(self, delayed_task, msg=""):
+        return self.__unregister_task(delayed_task, msg)
+
+    async def __create_delayed_task(self, task_func, **options):
+        async def _worker(delay):
+            try:
+                logger.info("sleep for {deplay} ms")
+                await asyncio.sleep(delay)
+
+                if asyncio.iscoroutinefunction(task_func):
+                    logger.debug("running delayed job (async)")
+                    await task_func()
+                else:
+                    logger.debug("running delayed job (sync)")
+                    task_func()
+
+            except asyncio.CancelledError as ce:
+                logger.debug(f"Cancel the task {ce}")
+
+
+        if options.get('delay', None) is not None:
+            logger.warning('delay is deprecated, please use delay_in_ms')
+            options['delay_in_ms'] = options['delay']
+
+        delay = options.get('delay_in_ms', _DEFAULT_DELAY)
+        return await _worker(delay)
+
+    def register_background_task(self, task_func, **options):
+        logger.info(f"Create background worker with options ({options}).")
+
+        task = asyncio.run_coroutine_threadsafe(self.__create_background_task(task_func, **options), self._loop)
+        self._tasks.append(task)
+
+        return task
+
+    def unregister_background_task(self, background_task, msg=""):
+        return self.__unregister_task(background_task, msg)
+
+    def __unregister_task(self, task, msg):
+        can_unregister = True
+
+        if self._tasks.index(task) >= 0:
+            logger.debug(f"cancel and unregister task: {msg}")
+            self._tasks.remove(task)
+
+            try:
+                task.cancel()
+                logger.debug(f"cancelled task: {msg}")
+            except asyncio.CancelledError as ce:
+                logger.error(f"__unregister_task: {ce}")
+                pass
+        else:
+            logger.warning("did'nt found task to unregister")
+            can_unregister = False
+
+        return can_unregister
+
+    async def __create_background_task(self, task_func, **options):
+        async def _task(delay):
+            running = True
+
+            while running:
+                try:
+                    if with_delay:
+                        logger.debug(f"background worker delay for {delay}")
+                        await asyncio.sleep(delay)
+
+                    if asyncio.iscoroutinefunction(task_func):
+                        logger.debug("running background job (async)")
+                        await task_func()
+                    else:
+                        logger.debug("running background job (sync)")
+                        task_func()
+
+                except asyncio.CancelledError:
+                    running = False
+                except Exception as e:
+                    logger.error(f"Failed run background job with error {e}")
+
+        if options.get('delay', None) is not None:
+            logger.warning('delay is deprecated, please use delay_in_seconds')
+            options['delay_in_seconds'] = options['delay']
+
+        delay_in_seconds = options.get('delay_in_seconds', _DEFAULT_DELAY)
+        with_delay = True if delay_in_seconds > 0 else False
+
+        return await _task(delay_in_seconds)
+
+    def start(self, **kwargs):
+        logger.info(f"Starting event loop {kwargs}.")
+        try:
+            self._run_forever = kwargs.get('run_forever', self._run_forever)
+
+            if self._install_signals:
+                self.__register_shutdown()
+
+            if self._run_forever:
+                self._loop.run_forever()
+        except KeyboardInterrupt:
+            self._loop.close()
+
+    def run_forever(self):
+        self.start(run_forever=True)
+
+    def stop_all_tasks(self):
+        logger.info("Stopping tasks.")
+        for task in self._tasks:
+            try:
+                task.cancel()
+            except Exception as e:
+                logger.warning(f"Task stopped with exception {e}")
+
+    def stop(self):
+        logger.info("Stopping event loop.")
+        self.stop_all_tasks()
+
+        if self._run_forever:
+            logger.info("close the event loop.")
+            self._loop.stop()
+
+    async def __internal_on_shutdown(self):
+        logger.debug('only internal on_shutdown called')
+        await asyncio.sleep(0)
+
+    def __register_shutdown(self):
+        async def shutdown(sig):
+            logger.info(f"Received exit signal {sig.name}...")
+
+            await self.on_shutdown()
+
+            self.stop()
+
+        signal_handler = lambda sig: asyncio.create_task(shutdown(sig))
+
+        if self.is_win():
+            # See https://docs.python.org/3/library/asyncio-platforms.html#windows
+            logger.warning("Cannot register signal handler on windows. To indicate shutdown use the close() method.")
+        else:
+            signals = (signal.SIGHUP, signal.SIGTERM, signal.SIGINT, signal.SIGQUIT)
+
+            for s in signals:
+                self._loop.add_signal_handler(s, signal_handler, s)
+
+    def is_win(self):
+        return os.name == 'nt'

processcube_etw_library/processcube_client/event/__init__.py

@@ -0,0 +1 @@
+from .event_client import EventClient

processcube_etw_library/processcube_client/event/event_client.py

@@ -0,0 +1,43 @@
+import logging
+
+from ..core.base_client import BaseClient, run_async_in_sync_context
+
+logger = logging.getLogger(__name__)
+
+
+class EventClient(BaseClient):
+    def __init__(self, url, session=None, identity=None):
+        super(EventClient, self).__init__(url, session, identity)
+
+    async def __trigger_message(self, event_name, payload, process_instance_id):
+        url = f"/atlas_engine/api/v1/messages/{event_name}/trigger"
+
+        if process_instance_id is not None:
+            url = f"{url}?process_instance_id={process_instance_id}"
+
+        result = await self.do_post(url, payload)
+
+        return result
+
+    def trigger_message(self, event_name, payload={}, process_instance_id=None):
+        logger.info(f"Connection to atlas engine at url '{self._url}'.")
+        logger.info(
+            f"Trigger message event {event_name} for process instance {process_instance_id} with payload {payload}."
+        )
+
+        return run_async_in_sync_context(
+            self.__trigger_message(event_name, payload, process_instance_id)
+        )
+
+    async def __trigger_signal(self, signal_name):
+        url = f"/atlas_engine/api/v1/signals/{signal_name}/trigger"
+
+        result = await self.do_post(url, {})
+
+        return result
+
+    def trigger_signal(self, signal_name):
+        logger.info(f"Connection to atlas engine at url '{self._url}'.")
+        logger.info(f"Trigger signal event {signal_name}.")
+
+        return run_async_in_sync_context(self.__trigger_signal(signal_name))

processcube_etw_library/processcube_client/external_task/__init__.py

@@ -0,0 +1,3 @@
+from .client_wrapper import ClientWrapper
+from .external_task_client import ExternalTaskClient
+from .functional_error import FunctionalError

processcube_etw_library/processcube_client/external_task/client_wrapper.py

@@ -0,0 +1,28 @@
+import asyncio
+import warnings
+
+from .external_task_client import ExternalTaskClient
+from ..core.loop_helper import get_or_create_loop
+
+
+class ClientWrapper:
+
+    def __init__(self, atlas_engine_url):
+        self._atlas_engine_url = atlas_engine_url
+
+    def subscribe_to_external_task_for_topic(self, topic, handler, **task_options):
+
+        loop = task_options.get('loop', get_or_create_loop())
+
+        warnings.warn("Please use 'subscribe_to_external_task_topic' instead of 'subscribe_to_external_task_for_topic'.", DeprecationWarning)
+        return self.subscribe_to_external_task_topic(topic, handler, loop=loop)
+
+    def subscribe_to_external_task_topic(self, topic, handler, **task_options):
+        loop = task_options.get('loop', get_or_create_loop())
+
+        external_task_client = ExternalTaskClient(self._atlas_engine_url, loop=loop)
+
+        external_task_client.subscribe_to_external_task_for_topic(topic, handler)
+
+        return external_task_client
+