iris-pex-embedded-python 3.7.2b2__py3-none-any.whl → 4.0.0__py3-none-any.whl

iop/{_business_process.py → components/business_process.py}

@@ -1,8 +1,13 @@
-from typing import Any, List, Optional, Union
+from typing import Any
 
-from ._business_host import _BusinessHost
-from ._decorators import input_deserializer, input_serializer_param, output_serializer
-from ._dispatch import create_dispatch, dispach_message
+from ..messages.decorators import (
+    input_deserializer,
+    input_serializer_param,
+    output_serializer,
+)
+from ..messages.dispatch import create_dispatch, dispatch_message
+from ..production import TargetSettingRef, resolve_target
+from .business_host import _BusinessHost
 
 
 class _BusinessProcess(_BusinessHost):
@@ -12,19 +17,38 @@ class _BusinessProcess(_BusinessHost):
     It can modify messages, transform formats, and route based on content.
     """
 
-    DISPATCH: List[tuple] = []
-    PERSISTENT_PROPERTY_LIST: Optional[List[str]] = None
-
-    def on_message(self, request: Any) -> Any:
-        """Handle incoming messages.
-
-        Args:
-            request: The incoming message
-
-        Returns:
-            Response message
-        """
-        return self.on_request(request)
+    DISPATCH: list[tuple] = []
+    PERSISTENT_PROPERTY_LIST: list[str] | None = None
+
+    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.
@@ -35,43 +59,70 @@ class _BusinessProcess(_BusinessHost):
         Returns:
             Response message
         """
-        return self.OnRequest(request)
+        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
-        """
-        return self.OnResponse(
-            request, response, call_request, call_response, completion_key
-        )
-
-    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
-        """
-        return self.OnComplete(request, response)
+    ) -> 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:
+        """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")
     def reply(self, response: Any) -> None:
@@ -83,37 +134,52 @@ class _BusinessProcess(_BusinessHost):
         return self.iris_handle.dispatchReply(response)
 
     @input_serializer_param(1, "request")
-    def send_request_async(
-        self,
-        target: str,
-        request: Any,
-        description: Optional[str] = None,
-        completion_key: Optional[str] = None,
+    def send_request_async(
+        self,
+        target: str | TargetSettingRef,
+        request: Any,
+        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
-        else:
-            response_required = 0  # type: ignore
-        return self.iris_handle.dispatchSendRequestAsync(
-            target, request, response_required, completion_key, description
-        )
+        else:
+            response_required = 0  # type: ignore
+        target = resolve_target(target)
+        return self.iris_handle.dispatchSendRequestAsync(
+            target, request, response_required, completion_key, description
+        )
 
     def set_timer(
-        self, timeout: Union[int, str], completion_key: Optional[str] = None
+        self, timeout: int | str, completion_key: str | None = None
     ) -> None:
         """Specify the maximum time the business process will wait for responses.
 
@@ -161,11 +227,12 @@ class _BusinessProcess(_BusinessHost):
         self._save_persistent_properties(host_object)
         return
 
-    def _dispatch_on_init(self, host_object: Any) -> None:
-        """For internal use only."""
-        self._restore_persistent_properties(host_object)
-        create_dispatch(self)
-        self.on_init()
+    def _dispatch_on_init(self, host_object: Any) -> None:
+        """For internal use only."""
+        self._log_custom_init_warning()
+        self._restore_persistent_properties(host_object)
+        create_dispatch(self)
+        self.on_init()
         self._save_persistent_properties(host_object)
         return
 
@@ -181,7 +248,7 @@ class _BusinessProcess(_BusinessHost):
     def _dispatch_on_request(self, host_object: Any, request: Any) -> Any:
         """For internal use only."""
         self._restore_persistent_properties(host_object)
-        return_object = dispach_message(self, request)
+        return_object = dispatch_message(self, request)
         self._save_persistent_properties(host_object)
         return return_object
 
@@ -215,50 +282,3 @@ class _BusinessProcess(_BusinessHost):
         self._save_persistent_properties(host_object)
         return return_object
 
-    def OnRequest(self, request: Any) -> Any:
-        """
-        DEPRECATED: Use on_request.
-
-        Args:
-            request: The incoming request message
-
-        Returns:
-            Response message
-        """
-        return
-
-    def OnResponse(
-        self,
-        request: Any,
-        response: Any,
-        call_request: Any,
-        call_response: Any,
-        completion_key: str,
-    ) -> Any:
-        """
-        DEPRECATED: Use on_response.
-
-        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
-        """
-        return response
-
-    def OnComplete(self, request: Any, response: Any) -> Any:
-        """
-        DEPRECATED: Use on_complete.
-
-        Args:
-            request: The initial request message
-            response: The response message
-
-        Returns:
-            Response message
-        """
-        return response

iop/components/business_service.py

@@ -0,0 +1,106 @@
+import importlib
+import warnings
+from inspect import signature
+
+from ..messages.decorators import input_deserializer, output_serializer
+from .business_host import _BusinessHost
+
+
+def _accepts_process_input_argument(method) -> bool:
+    try:
+        return len(signature(method).parameters) > 0
+    except (TypeError, ValueError):
+        return True
+
+
+def _call_process_input(method, request):
+    if _accepts_process_input_argument(method):
+        return method(request)
+    return method()
+
+
+class _BusinessService(_BusinessHost):
+    """This class is responsible for receiving the data from external system and sending it to business processes or business operations in the production.
+    The business service can use an adapter to access the external system, which is specified in the InboundAdapter property.
+    There are three ways of implementing a business service:
+    1) Polling business service with an adapter - The production framework at regular intervals calls the adapter's task method,
+        which sends incoming data to the business service process input method.
+    2) Polling business service that uses the default adapter - In this case, the framework calls the default adapter's OnTask method with no data.
+        The on_process_input() method then performs the role of the adapter and is responsible for accessing the external system and receiving the data.
+    3) Nonpolling business service - The production framework does not initiate the business service. Instead custom code in either a long-running process
+        or one that is started at regular intervals initiates the business service through the Director API.
+    """
+
+    Adapter = adapter = None
+    _wait_for_next_call_interval = False
+
+    def _dispatch_on_init(self, host_object) -> None:
+        """For internal use only."""
+        self._log_custom_init_warning()
+        self.on_init()
+
+        return
+
+    def on_message(self, request=None):
+        """Purpose:
+            Handle a message received by a BusinessService.
+
+        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 "
+            "on_process_input(); the incoming service message 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):
+        """Receives the message from the inbond adapter via the PRocessInput method and is responsible for forwarding it to target business processes or operations.
+        If the business service does not specify an adapter, then the default adapter calls this method with no message
+        and the business service is responsible for receiving the data from the external system and validating it.
+
+        Parameters:
+        message_input: an instance of IRISObject or subclass of Message containing the data that the inbound adapter passes in.
+            The message can have any structure agreed upon by the inbound adapter and the business service.
+        """
+        return self.on_message(message_input)
+
+    def _set_iris_handles(self, handle_current, handle_partner):
+        """For internal use only."""
+        self.iris_handle = handle_current
+        if type(handle_partner).__module__.find("iris") == 0:
+            if handle_partner._IsA("IOP.InboundAdapter"):
+                module = importlib.import_module(handle_partner.GetModule())
+                handle_partner = getattr(module, handle_partner.GetClassname())()
+        self.Adapter = self.adapter = handle_partner
+        return
+
+    @input_deserializer
+    @output_serializer
+    def _dispatch_on_process_input(self, request):
+        """For internal use only."""
+        return _call_process_input(self.on_process_input, request)