iris-pex-embedded-python 4.0.0b14__tar.gz → 4.0.0b15__tar.gz

{iris_pex_embedded_python-4.0.0b14/src/iris_pex_embedded_python.egg-info → iris_pex_embedded_python-4.0.0b15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris_pex_embedded_python
-Version: 4.0.0b14
+Version: 4.0.0b15
 Summary: Iris Interoperability based on Embedded Python
 Author-email: grongier <guillaume.rongier@intersystems.com>
 License: MIT License

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.0b15}/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools", "wheel"]
 
 [project]
 name = "iris_pex_embedded_python"
-version = "4.0.0b14"
+version = "4.0.0b15"
 description = "Iris Interoperability based on Embedded Python"
 readme = "README.md"
 requires-python = ">=3.10"

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.0b15}/src/iop/__init__.py

@@ -117,46 +117,137 @@ class OutboundAdapter(_OutboundAdapter):
 
 
 class BusinessService(_BusinessService):
-    """Inbound production entry point.
+    """Purpose:
+        Inbound production entry point for messages entering an IoP production.
 
-    Use for message-driven services or Python services that receive data and
-    send messages into a production. For polling services, prefer
-    PollingBusinessService. For task recipes, see
-    docs/cookbooks/add-polling-service.md and docs/cookbooks/hl7v2-native-input.md.
+    Use when:
+        External data, an adapter, or custom code must send a message into the
+        production graph.
+
+    Lifecycle:
+        IRIS calls on_process_input(); the default implementation delegates to
+        on_process_input(request).
+
+    Best practices:
+        Declare outbound routes with target() and wire them in a Production
+        graph. Use PollingBusinessService for scheduled Python polling.
+
+    Common mistakes:
+        Do not put startup work in __init__(); use on_init(). Do not instantiate
+        downstream components directly.
+
+    Minimal example:
+        class FileIn(BusinessService):
+            Output = target()
+
+            def on_process_input(self, request):
+                self.send_request_async(self.Output, request)
+
+    Related:
+        docs/cookbooks/add-polling-service.md,
+        docs/cookbooks/hl7v2-native-input.md
     """
 
     pass
 
 
 class PollingBusinessService(_PollingBusinessServiceMixin, BusinessService):
-    """Scheduled inbound service called by the default IRIS inbound adapter.
+    """Purpose:
+        Scheduled Python service called by the default IRIS inbound adapter.
+
+    Use when:
+        A production must poll an API, directory, queue, database, or other
+        source from Python.
+
+    Lifecycle:
+        IRIS calls on_process_input(); the mixin delegates that call to
+        on_poll().
+
+    Best practices:
+        Put one polling cycle in on_poll(). Declare outbound routes with
+        target() and send messages with send_request_async(...).
+
+    Common mistakes:
+        Do not block forever inside on_poll(). Do not put startup work in
+        __init__(); use on_init().
+
+    Minimal example:
+        class ApiPoller(PollingBusinessService):
+            Output = target()
+
+            def on_poll(self):
+                self.send_request_async(self.Output, MyRequest())
 
-    Declare outbound routes with target() and send messages with
-    send_request_async(...). Do not put startup work in __init__(); use
-    on_init(). See docs/cookbooks/add-polling-service.md.
+    Related:
+        docs/cookbooks/add-polling-service.md
     """
 
     pass
 
 
 class BusinessOperation(_BusinessOperation):
-    """Outbound side-effect boundary for production messages.
+    """Purpose:
+        Outbound side-effect boundary for production messages.
 
-    Use operations for external APIs, file writes, database writes, FHIR
-    submission, and other side effects. Dispatch can use on_message(), typed
-    one-argument methods, or @handler(MessageType). See
-    docs/cookbooks/add-business-operation.md.
+    Use when:
+        A production must call an external API, write a file, update a database,
+        submit FHIR resources, or perform another side effect.
+
+    Lifecycle:
+        IRIS calls on_message(request). IoP can dispatch to @handler methods,
+        typed one-argument methods, or the on_message fallback.
+
+    Best practices:
+        Keep external-system code here. Return a response message when callers
+        expect synchronous results.
+
+    Common mistakes:
+        Do not put routing orchestration in an operation when a BusinessProcess
+        should own the decision.
+
+    Minimal example:
+        class SubmitOrder(BusinessOperation):
+            def on_message(self, request):
+                return SubmitResult(ok=True)
+
+    Related:
+        docs/cookbooks/add-business-operation.md
     """
 
     pass
 
 
 class BusinessProcess(_BusinessProcess):
-    """Routing, orchestration, decision, and transformation component.
+    """Purpose:
+        Routing, orchestration, decision, and transformation component.
+
+    Use when:
+        A production needs branching, enrichment, transformation, fan-out,
+        request/reply orchestration, or response aggregation.
 
-    Declare outbound routes with target() and connect them in a Production
-    graph. Dispatch can use on_message(), typed one-argument methods, or
-    @handler(MessageType). See docs/cookbooks/add-business-process.md.
+    Lifecycle:
+        IRIS calls on_message(request). For async requests, IRIS can later call
+        on_response(...) and on_complete(...).
+
+    Best practices:
+        Declare outbound routes with target() and wire them with
+        Production.connect(...). Use @handler(MessageType) or typed methods for
+        multiple message types.
+
+    Common mistakes:
+        Do not hard-code target component names when target() can expose a
+        configurable route.
+
+    Minimal example:
+        class Router(BusinessProcess):
+            Accepted = target()
+
+            def on_message(self, request):
+                return self.send_request_sync(self.Accepted, request)
+
+    Related:
+        docs/cookbooks/add-business-process.md,
+        docs/cookbooks/production-settings-and-targets.md
     """
 
     pass
@@ -175,12 +266,34 @@ class DuplexProcess(_PrivateSessionProcess):
 
 
 class Message(_Message):
-    """Python-only JSON-serialized message contract.
-
-    Use @dataclass for ordinary app messages between IoP components. Prefer
-    PersistentMessage only when IRIS needs a native persistent message body. See
-    docs/cookbooks/add-business-process.md and
-    docs/cookbooks/add-business-operation.md.
+    """Purpose:
+        Python-only JSON-serialized message contract.
+
+    Use when:
+        IoP components exchange structured Python data and IRIS does not need a
+        native persistent message body.
+
+    Lifecycle:
+        IoP serializes dataclass fields into IOP.Message and restores the Python
+        class on receipt.
+
+    Best practices:
+        Decorate subclasses with @dataclass. Use PydanticMessage when runtime
+        validation is more important.
+
+    Common mistakes:
+        Do not use Message without @dataclass. Do not register Message classes
+        in CLASSES; use PersistentMessage for native IRIS message bodies.
+
+    Minimal example:
+        @dataclass
+        class OrderRequest(Message):
+            order_id: str
+
+    Related:
+        docs/cookbooks/add-business-process.md,
+        docs/cookbooks/add-business-operation.md,
+        docs/getting-started/register-component.md
     """
 
     pass

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.0b15}/src/iop/components/business_host.py

@@ -108,23 +108,30 @@ class _BusinessHost(_Common):
         timeout: int = -1,
         description: str | None = None,
     ) -> Any:
-        """Send message synchronously to target component.
+        """Purpose:
+            Send a message to a target component and wait for the response.
 
-        Prefer a target() attribute such as self.Output for configurable
-        routing. BusinessProcess examples are in
-        docs/cookbooks/add-business-process.md.
+        Use when:
+            The caller needs the target response before continuing.
 
-        Args:
-            target: Name of target component
-            request: Message to send
-            timeout: Timeout in seconds, -1 means wait forever
-            description: Optional description for logging
-
-        Returns:
-            Response from target component
-
-        Raises:
-            TypeError: If request is invalid type
+        Lifecycle:
+            IoP serializes request, calls the IRIS synchronous dispatch API, and
+            deserializes the response before returning.
+
+        Best practices:
+            Pass a target() attribute such as self.Output so the route is
+            configurable in the Production graph.
+
+        Common mistakes:
+            Do not use synchronous calls for long-running work unless the caller
+            really must block.
+
+        Minimal example:
+            response = self.send_request_sync(self.Output, request)
+
+        Related:
+            docs/cookbooks/add-business-process.md,
+            docs/cookbooks/production-settings-and-targets.md
         """
         target = resolve_target(target)
         return self.iris_handle.dispatchSendRequestSync(
@@ -138,19 +145,29 @@ class _BusinessHost(_Common):
         request: Message | Any,
         description: str | None = None,
     ) -> None:
-        """Send message asynchronously to target component.
+        """Purpose:
+            Send a message to a target component without waiting for a response.
 
-        Prefer a target() attribute such as self.Output for configurable
-        routing. Polling service examples are in
-        docs/cookbooks/add-polling-service.md.
+        Use when:
+            A service or operation should enqueue downstream work and continue.
 
-        Args:
-            target: Name of target component
-            request: Message to send
-            description: Optional description for logging
-
-        Raises:
-            TypeError: If request is invalid type
+        Lifecycle:
+            IoP serializes request and calls the IRIS asynchronous dispatch API.
+
+        Best practices:
+            Pass a target() attribute such as self.Output so the route is
+            configurable in the Production graph.
+
+        Common mistakes:
+            Do not use this helper when the caller requires a response; use
+            send_request_sync(...) or the BusinessProcess async response flow.
+
+        Minimal example:
+            self.send_request_async(self.Output, request)
+
+        Related:
+            docs/cookbooks/add-polling-service.md,
+            docs/cookbooks/production-settings-and-targets.md
         """
         target = resolve_target(target)
         return self.iris_handle.dispatchSendRequestAsync(target, request, description)

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.0b15}/src/iop/components/business_operation.py

@@ -19,16 +19,31 @@ class _BusinessOperation(_BusinessHost):
     adapter: Any = None
 
     def on_message(self, request: Any) -> Any:
-        """Handle incoming messages.
-
-        Process messages received from other production components and either
-        send to external system or forward to another component.
-
-        Args:
-            request: The incoming message
-
-        Returns:
-            Response message
+        """Purpose:
+            Handle an incoming message sent to a BusinessOperation.
+
+        Use when:
+            The operation must perform an outbound side effect or submit data to
+            an external system.
+
+        Lifecycle:
+            IRIS invokes this hook for operation requests unless dispatch routes
+            the message to a @handler or typed one-argument method first.
+
+        Best practices:
+            Keep side effects isolated here. Return a response message when the
+            caller uses send_request_sync(...).
+
+        Common mistakes:
+            Do not put routing decisions here when a BusinessProcess should
+            orchestrate them.
+
+        Minimal example:
+            def on_message(self, request):
+                return SubmitResult(ok=True)
+
+        Related:
+            docs/cookbooks/add-business-operation.md
         """
         warnings.warn(
             f"{self.__class__.__name__} did not override on_message(); "

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.0b15}/src/iop/components/business_process.py

@@ -20,16 +20,35 @@ class _BusinessProcess(_BusinessHost):
     DISPATCH: list[tuple] = []
     PERSISTENT_PROPERTY_LIST: list[str] | None = None
 
-    def on_message(self, request: Any) -> Any:
-        """Handle incoming messages.
-
-        Args:
-            request: The incoming message
-
-        Returns:
-            Response message
-        """
-        return self.on_request(request)
+    def on_message(self, request: Any) -> Any:
+        """Purpose:
+            Handle an incoming message sent to a BusinessProcess.
+
+        Use when:
+            The process owns routing, orchestration, transformation, or
+            decisions for a request.
+
+        Lifecycle:
+            IRIS invokes this hook for process requests unless dispatch routes
+            the message to a @handler or typed one-argument method first. The
+            default implementation delegates to on_request(request).
+
+        Best practices:
+            Declare outbound routes with target() and call
+            send_request_sync(...) or send_request_async(...).
+
+        Common mistakes:
+            Do not hide routing in raw strings when target() can make routes
+            configurable in the production graph.
+
+        Minimal example:
+            def on_message(self, request):
+                return self.send_request_sync(self.Output, request)
+
+        Related:
+            docs/cookbooks/add-business-process.md
+        """
+        return self.on_request(request)
 
     def on_request(self, request: Any) -> Any:
         """Process initial requests sent to this component.
@@ -42,38 +61,67 @@ class _BusinessProcess(_BusinessHost):
         """
         return None
 
-    def on_response(
+    def on_response(
         self,
         request: Any,
         response: Any,
         call_request: Any,
         call_response: Any,
         completion_key: str,
-    ) -> Any:
-        """Handle responses to messages sent by this component.
-
-        Args:
-            request: The initial request message
-            response: The response message
-            call_request: The request sent to the target
-            call_response: The incoming response
-            completion_key: The completion key specified in the outgoing SendAsync() method
-
-        Returns:
-            Response message
-        """
+    ) -> Any:
+        """Purpose:
+            Handle one async response received by a BusinessProcess.
+
+        Use when:
+            The process sends async requests and needs to merge, inspect, or
+            transform each returned response.
+
+        Lifecycle:
+            IRIS calls on_response(...) after an async target response arrives.
+            on_complete(...) can run after all expected responses complete.
+
+        Best practices:
+            Use completion_key to identify which async call returned. Return
+            the accumulated or transformed response state.
+
+        Common mistakes:
+            Do not assume responses arrive in request order.
+
+        Minimal example:
+            def on_response(self, request, response, call_request, call_response, completion_key):
+                return call_response
+
+        Related:
+            docs/cookbooks/add-business-process.md
+        """
         return response
 
-    def on_complete(self, request: Any, response: Any) -> Any:
-        """Called after all responses to requests sent by this component have been handled.
-
-        Args:
-            request: The initial request message
-            response: The response message
-
-        Returns:
-            Response message
-        """
+    def on_complete(self, request: Any, response: Any) -> Any:
+        """Purpose:
+            Finish async request orchestration for a BusinessProcess.
+
+        Use when:
+            The process must return or finalize an aggregate response after
+            async sends, timers, or response handling.
+
+        Lifecycle:
+            IRIS calls on_complete(request, response) after expected async
+            responses have been handled or the completion path is reached.
+
+        Best practices:
+            Return the final response message expected by the original caller.
+
+        Common mistakes:
+            Do not put per-response logic here; use on_response(...) for each
+            individual async response.
+
+        Minimal example:
+            def on_complete(self, request, response):
+                return response
+
+        Related:
+            docs/cookbooks/add-business-process.md
+        """
         return response
 
     @input_serializer_param(0, "response")
@@ -93,19 +141,33 @@ class _BusinessProcess(_BusinessHost):
         description: str | None = None,
         completion_key: str | None = None,
         response_required: bool = True,
-    ) -> None:
-        """Send the specified message to the target business process or business operation asynchronously.
-
-        Args:
-            target: The name of the business process or operation to receive the request
-            request: The message to send to the target
-            description: An optional description property in the message header
-            completion_key: A string that will be returned with the response if the maximum time is exceeded
-            response_required: Whether a response is required
-
-        Raises:
-            TypeError: If request is not of type Message or IRISObject
-        """
+    ) -> None:
+        """Purpose:
+            Send a message asynchronously from a BusinessProcess.
+
+        Use when:
+            The process should continue without blocking for a target response,
+            or when responses will be handled later by on_response(...).
+
+        Lifecycle:
+            IoP serializes request before dispatching to IRIS. IRIS can call
+            on_response(...) and on_complete(...) when response_required is true.
+
+        Best practices:
+            Pass a target() attribute such as self.Output. Use completion_key
+            for fan-out or multiple async calls.
+
+        Common mistakes:
+            Do not pass an unresolved component instance or a hard-coded route
+            when the route should be configurable.
+
+        Minimal example:
+            self.send_request_async(self.Output, request, completion_key="out")
+
+        Related:
+            docs/cookbooks/add-business-process.md,
+            docs/cookbooks/production-settings-and-targets.md
+        """
         # Convert boolean to int for Iris API
         if response_required:
             response_required = 1  # type: ignore

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.0b15}/src/iop/components/business_service.py

@@ -42,11 +42,32 @@ class _BusinessService(_BusinessHost):
         return
 
     def on_message(self, request=None):
-        """Handle a message received by the business service.
+        """Purpose:
+            Handle a message received by a BusinessService.
 
-        Override this for message-driven services. Adapter-driven services may
-        still override on_process_input() directly when they need the lower
-        level IRIS ProcessInput hook.
+        Use when:
+            A service receives data from an adapter, Director API call, or
+            custom entry point and should send work into the production graph.
+
+        Lifecycle:
+            The default on_process_input(message_input) implementation delegates
+            to on_message(message_input).
+
+        Best practices:
+            Validate or normalize inbound data, then send a Message to a target
+            declared with target().
+
+        Common mistakes:
+            Do not call downstream component methods directly. Use
+            send_request_async(...) or send_request_sync(...).
+
+        Minimal example:
+            def on_message(self, request):
+                self.send_request_async(self.Output, request)
+
+        Related:
+            docs/cookbooks/add-polling-service.md,
+            docs/cookbooks/hl7v2-native-input.md
         """
         warnings.warn(
             f"{self.__class__.__name__} did not override on_message() or "

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.0b15}/src/iop/components/common.py

@@ -223,10 +223,36 @@ class _Common:
         self._log_to_console = value
         self.logger = LogManager.get_logger(self.__class__.__name__, value)
 
-    # Lifecycle methods
-    def on_init(self) -> None:
-        """Initialize component when started."""
-        pass
+    # Lifecycle methods
+    def on_init(self) -> None:
+        """Purpose:
+            Component startup hook.
+
+        Use when:
+            A component needs to initialize clients, caches, credentials,
+            counters, or other runtime state after IRIS creates the host.
+
+        Lifecycle:
+            IoP calls on_init() from the internal dispatch startup path. IRIS
+            may allocate the Python object without calling __init__().
+
+        Best practices:
+            Keep initialization idempotent and quick. Read production settings
+            from self inside this method.
+
+        Common mistakes:
+            Do not put component startup work in __init__(); it may not run in
+            the IRIS component lifecycle.
+
+        Minimal example:
+            def on_init(self):
+                self.client = make_client(self.Endpoint)
+
+        Related:
+            docs/ai-coding.md,
+            docs/cookbooks/index.md
+        """
+        pass
 
     def on_tear_down(self) -> None:
         """Clean up component before termination."""

iris_pex_embedded_python-4.0.0b15/src/iop/components/polling_business_service.py

@@ -0,0 +1,48 @@
+import warnings
+
+
+class _PollingBusinessServiceMixin:
+    """Mixin for services polled by the default IRIS inbound adapter."""
+
+    @staticmethod
+    def get_adapter_type() -> str:
+        return "Ens.InboundAdapter"
+
+    def on_poll(self):
+        """Purpose:
+            Run one scheduled polling cycle.
+
+        Use when:
+            A PollingBusinessService fetches or discovers new work from Python.
+
+        Lifecycle:
+            The default IRIS inbound adapter calls on_process_input(), and this
+            mixin delegates that call to on_poll().
+
+        Best practices:
+            Do a bounded unit of work, then return. Send produced messages with
+            send_request_async(self.Output, message).
+
+        Common mistakes:
+            Do not create an infinite loop inside on_poll(); use the production
+            schedule or call interval for repeated execution.
+
+        Minimal example:
+            def on_poll(self):
+                self.send_request_async(self.Output, PollRequest())
+
+        Related:
+            docs/cookbooks/add-polling-service.md
+        """
+        warnings.warn(
+            f"{self.__class__.__name__} did not override on_poll() or "
+            "on_process_input(); the scheduled poll was ignored. "
+            "This default no-op handler will raise NotImplementedError in v5.0.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return None
+
+    def on_process_input(self, message_input=None):
+        """Compatibility hook called by IRIS ProcessInput."""
+        return self.on_poll()