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

iop/{_private_session_duplex.py → components/private_session_duplex.py}

@@ -1,13 +1,13 @@
 import importlib
 
-from ._business_host import _BusinessHost
-from ._decorators import (
+from ..messages.decorators import (
     input_deserializer,
     input_serializer_param,
-    output_serializer,
     output_deserializer,
+    output_serializer,
 )
-from ._dispatch import dispach_message
+from ..messages.dispatch import dispatch_message
+from .business_host import _BusinessHost
 
 
 class _PrivateSessionDuplex(_BusinessHost):
@@ -19,7 +19,7 @@ class _PrivateSessionDuplex(_BusinessHost):
         """Called when the business operation receives a message from another production component.
         Typically, the operation will either send the message to the external system or forward it to a business process or another business operation.
         If the operation has an adapter, it uses the Adapter.invoke() method to call the method on the adapter that sends the message to the external system.
-        If the operation is forwarding the message to another production component, it uses the SendRequestAsync() or the SendRequestSync() method
+        If the operation is forwarding the message to another production component, it uses send_request_async() or send_request_sync().
 
         Parameters:
         request: An instance of either a subclass of Message or of IRISObject containing the incoming message for the business operation.
@@ -33,16 +33,14 @@ class _PrivateSessionDuplex(_BusinessHost):
     @output_serializer
     def _dispatch_on_message(self, request):
         """For internal use only."""
-        return dispach_message(self, request)
+        return dispatch_message(self, request)
 
     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("Grongier.PEX.InboundAdapter")
-                or handle_partner._IsA("Grongier.PEX.OutboundAdapter")
-                or handle_partner._IsA("IOP.InboundAdapter")
+                handle_partner._IsA("IOP.InboundAdapter")
                 or handle_partner._IsA("IOP.OutboundAdapter")
             ):
                 module = importlib.import_module(handle_partner.GetModule())

iop/{_private_session_process.py → components/private_session_process.py}

@@ -1,5 +1,5 @@
-from ._business_process import _BusinessProcess
-from ._decorators import input_deserializer, output_serializer
+from ..messages.decorators import input_deserializer, output_serializer
+from .business_process import _BusinessProcess
 
 
 class _PrivateSessionProcess(_BusinessProcess):

iop/{_settings.py → components/settings.py}

@@ -1,6 +1,7 @@
-from enum import Enum
-from typing import Any
+from __future__ import annotations
 
+from enum import Enum
+from typing import Any, overload
 
 _MISSING = object()
 
@@ -23,7 +24,13 @@ def _string_value(value: Any) -> str:
 
 
 class Setting:
-    """Metadata for an IRIS production setting."""
+    """Metadata for an IRIS production setting.
+
+    Use Setting or setting(...) for configurable component values exposed in
+    the Management Portal. Use iop.target() instead for outbound component
+    routes. See docs/cookbooks/production-settings-and-targets.md and
+    docs/settings.md.
+    """
 
     def __init__(
         self,
@@ -46,9 +53,17 @@ class Setting:
         self.control = control or ""
         self.exclude = exclude
         self.name = ""
+        self.owner = None
 
     def __set_name__(self, owner, name):
         self.name = name
+        self.owner = owner
+
+    @overload
+    def __get__(self, instance: None, owner: type | None = None) -> Setting: ...
+
+    @overload
+    def __get__(self, instance: object, owner: type | None = None) -> Any: ...
 
     def __get__(self, instance, owner=None):
         if instance is None:
@@ -68,6 +83,11 @@ class Setting:
 
 
 def setting(default: Any = _MISSING, **kwargs) -> Setting:
+    """Declare a configurable IRIS production setting on a component class.
+
+    For outbound routing, prefer iop.target() so Production.connect(...) can
+    wire the graph explicitly. See docs/cookbooks/production-settings-and-targets.md.
+    """
     return Setting(default, **kwargs)
 
 

iop/messages/__init__.py

@@ -0,0 +1,7 @@
+from .base import _Message as _Message
+from .base import _PickleMessage as _PickleMessage
+from .base import _PydanticMessage as _PydanticMessage
+from .base import _PydanticPickleMessage as _PydanticPickleMessage
+from .persistent import Field as Field
+from .persistent import Model as Model
+from .persistent import _PersistentMessage as _PersistentMessage

iop/messages/base.py

@@ -0,0 +1,61 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class _Message:
+    """Base class for JSON-serialized messages sent between components.
+
+    Use Message for Python-only contracts that do not need native IRIS
+    persistence. Subclasses must be decorated with @dataclass. App builders
+    usually pair message classes with BusinessProcess or BusinessOperation
+    handlers; see
+    docs/cookbooks/add-business-process.md and
+    docs/cookbooks/add-business-operation.md.
+    """
+
+    _iris_id: str | None = None
+
+    def get_iris_id(self) -> str | None:
+        """Get the IRIS ID of the message."""
+        return self._iris_id
+
+
+class _PickleMessage(_Message):
+    """Base class for pickle-serialized messages sent between components.
+
+    Prefer Message or PydanticMessage for new application contracts. Use
+    PickleMessage only when a Python-only payload cannot be represented cleanly
+    as JSON-compatible fields.
+    """
+
+    pass
+
+
+class _PydanticMessage(BaseModel):
+    """Base class for Pydantic-based messages that can be serialized to IRIS.
+
+    Use PydanticMessage for Python-only contracts that benefit from Pydantic
+    validation. Do not decorate PydanticMessage classes with @dataclass and do
+    not register these classes in CLASSES; see docs/getting-started/register-component.md.
+    """
+
+    _iris_id: str | None = None
+
+    def __init__(self, **data: Any):
+        super().__init__(**data)
+
+    def get_iris_id(self) -> str | None:
+        """Get the IRIS ID of the message."""
+        return self._iris_id
+
+
+class _PydanticPickleMessage(_PydanticMessage):
+    """Base class for Pydantic-based messages serialized through pickle.
+
+    Prefer PydanticMessage unless the payload must preserve Python-only object
+    shapes that JSON serialization cannot represent.
+    """
+
+    def __init__(self, **data: Any):
+        super().__init__(**data)

iop/{_decorators.py → messages/decorators.py}

@@ -1,12 +1,15 @@
+from collections.abc import Callable
 from functools import wraps
-from typing import Any, Callable
+from typing import Any
 
-from ._dispatch import dispatch_deserializer, dispatch_serializer
+from .dispatch import dispatch_deserializer, dispatch_serializer
+from .dispatch import handler as handler
 
 
 def input_serializer(fonction: Callable) -> Callable:
     """Decorator that serializes all input arguments."""
 
+    @wraps(fonction)
     def _dispatch_serializer(self, *params: Any, **param2: Any) -> Any:
         serialized = [dispatch_serializer(param) for param in params]
         param2 = {key: dispatch_serializer(value) for key, value in param2.items()}
@@ -39,6 +42,7 @@ def input_serializer_param(position: int, name: str) -> Callable:
 def output_deserializer(fonction: Callable) -> Callable:
     """Decorator that deserializes function output."""
 
+    @wraps(fonction)
     def _dispatch_deserializer(self, *params: Any, **param2: Any) -> Any:
         return dispatch_deserializer(fonction(self, *params, **param2))
 
@@ -48,6 +52,7 @@ def output_deserializer(fonction: Callable) -> Callable:
 def input_deserializer(fonction: Callable) -> Callable:
     """Decorator that deserializes all input arguments."""
 
+    @wraps(fonction)
     def _dispatch_deserializer(self, *params: Any, **param2: Any) -> Any:
         serialized = [dispatch_deserializer(param) for param in params]
         param2 = {key: dispatch_deserializer(value) for key, value in param2.items()}
@@ -59,6 +64,7 @@ def input_deserializer(fonction: Callable) -> Callable:
 def output_serializer(fonction: Callable) -> Callable:
     """Decorator that serializes function output."""
 
+    @wraps(fonction)
     def _dispatch_serializer(self, *params: Any, **param2: Any) -> Any:
         return dispatch_serializer(fonction(self, *params, **param2))
 

iop/messages/dispatch.py

@@ -0,0 +1,351 @@
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from inspect import Parameter, signature
+from typing import Any
+
+from .persistent import (
+    deserialize_persistent_message,
+    get_iris_object_classname,
+    is_persistent_message_class,
+    is_persistent_message_instance,
+    serialize_persistent_message,
+)
+from .serialization import (
+    deserialize_message,
+    deserialize_pickle_message,
+    serialize_message,
+    serialize_message_generator,
+    serialize_pickle_message,
+    serialize_pickle_message_generator,
+)
+from .validation import (
+    is_iris_object_instance,
+    is_message_class,
+    is_message_instance,
+    is_pickle_message_class,
+    is_pickle_message_instance,
+)
+
+_MESSAGE_CLASSES = {
+    "IOP.Message",
+    "IOP.Generator.Message.Start",
+}
+_PICKLE_MESSAGE_CLASSES = {
+    "IOP.PickleMessage",
+    "IOP.Generator.Message.StartPickle",
+}
+_HANDLER_ATTRIBUTE = "__iop_handler_message__"
+
+
+@dataclass(frozen=True)
+class _DispatchCandidate:
+    message: str
+    method: str
+    source: str
+    priority: int
+    index: int
+
+
+def handler(message_type: Any) -> Callable[[Callable], Callable]:
+    """Declare a method as the handler for a message type.
+
+    Use @handler(MessageType) when a BusinessProcess or BusinessOperation should
+    route a specific message type to a specific method. Typed one-argument
+    methods are also auto-discovered; on_message() remains the fallback.
+    See docs/cookbooks/add-business-process.md and
+    docs/cookbooks/add-business-operation.md.
+
+    Args:
+        message_type: The message class, fully qualified class name string, or
+            IRIS object instance this method handles.
+    """
+    message = _message_class_name(message_type)
+    if message is None:
+        raise TypeError("handler() requires a message class or class name")
+
+    def _handler(method: Callable) -> Callable:
+        setattr(method, _HANDLER_ATTRIBUTE, message)
+        return method
+
+    return _handler
+
+
+def dispatch_serializer(message: Any, is_generator: bool = False) -> Any:
+    """Serializes the message based on its type.
+
+    Args:
+        message: The message to serialize
+
+    Returns:
+        The serialized message
+
+    Raises:
+        TypeError: If message is invalid type
+    """
+    if message is not None:
+        if is_persistent_message_instance(message):
+            return serialize_persistent_message(message, is_generator=is_generator)
+        elif is_message_instance(message):
+            if is_generator:
+                return serialize_message_generator(message)
+            return serialize_message(message)
+        elif is_pickle_message_instance(message):
+            if is_generator:
+                return serialize_pickle_message_generator(message)
+            return serialize_pickle_message(message)
+        elif is_iris_object_instance(message):
+            return message
+
+    if message == "" or message is None:
+        return message
+
+    if hasattr(message, "__iter__"):
+        raise TypeError(
+            "You may have tried to invoke a generator function without using the 'send_generator_request' method. Please use that method to handle generator functions."
+        )
+
+    raise TypeError(
+        "The message must be an instance of a class that is a subclass of Message or IRISObject %Persistent class."
+    )
+
+
+def dispatch_deserializer(serial: Any) -> Any:
+    """Deserializes the message based on its type.
+
+    Args:
+        serial: The serialized message
+
+    Returns:
+        The deserialized message
+    """
+    if serial is None or not type(serial).__module__.startswith("iris"):
+        return serial
+
+    iris_classname = get_iris_object_classname(serial)
+
+    if iris_classname in _MESSAGE_CLASSES:
+        return deserialize_message(serial)
+
+    if iris_classname in _PICKLE_MESSAGE_CLASSES:
+        return deserialize_pickle_message(serial)
+
+    deserialized = deserialize_persistent_message(serial, iris_classname=iris_classname)
+    if deserialized is not serial:
+        return deserialized
+
+    if serial._IsA("IOP.Message"):
+        return deserialize_message(serial)
+
+    if serial._IsA("IOP.PickleMessage"):
+        return deserialize_pickle_message(serial)
+
+    return serial
+
+
+def dispatch_message(host: Any, request: Any) -> Any:
+    """Dispatches the message to the appropriate method.
+
+    Args:
+        request: The request object
+
+    Returns:
+        The response object
+    """
+    call = "on_message"
+
+    module = request.__class__.__module__
+    classname = request.__class__.__name__
+
+    for msg, method in host.DISPATCH:
+        if msg == module + "." + classname:
+            return getattr(host, method)(request)
+
+    return getattr(host, call)(request)
+
+
+def create_dispatch(host: Any) -> None:
+    """Creates a dispatch table mapping class names to their handler methods.
+    The dispatch table consists of tuples of (fully_qualified_class_name, method_name).
+    Only methods that take a single typed parameter are considered as handlers.
+    """
+    candidates: list[_DispatchCandidate] = []
+    index = 0
+
+    for message, method in _decorated_dispatch(host):
+        candidates.append(
+            _DispatchCandidate(message, method, "@handler", priority=0, index=index)
+        )
+        index += 1
+
+    for message, method in _declared_dispatch(host):
+        candidates.append(
+            _DispatchCandidate(message, method, "DISPATCH", priority=1, index=index)
+        )
+        index += 1
+
+    for method_name in get_callable_methods(host):
+        if _handler_message(getattr(host, method_name)) is not None:
+            continue
+        handler_info = get_handler_info(host, method_name)
+        if handler_info:
+            message, method = handler_info
+            candidates.append(
+                _DispatchCandidate(
+                    message, method, "typed method", priority=1, index=index
+                )
+            )
+            index += 1
+
+    host.DISPATCH = _deduplicate_dispatch(host, candidates)
+
+
+def _declared_dispatch(host: Any) -> list[tuple[str, str]]:
+    if "DISPATCH" in getattr(host, "__dict__", {}):
+        return list(host.__dict__["DISPATCH"])
+
+    class_dispatch = host.__class__.__dict__.get("DISPATCH")
+    if class_dispatch is not None:
+        return list(class_dispatch)
+
+    return []
+
+
+def _decorated_dispatch(host: Any) -> list[tuple[str, str]]:
+    dispatch = []
+    for method_name in dir(host):
+        method = getattr(host, method_name)
+        if not callable(method):
+            continue
+        message = _handler_message(method)
+        if message is not None:
+            dispatch.append((message, method_name))
+    return dispatch
+
+
+def _deduplicate_dispatch(
+    host: Any, candidates: list[_DispatchCandidate]
+) -> list[tuple[str, str]]:
+    selected: dict[str, _DispatchCandidate] = {}
+
+    for candidate in candidates:
+        current = selected.get(candidate.message)
+        if current is None:
+            selected[candidate.message] = candidate
+            continue
+
+        if current.method == candidate.method:
+            if _is_higher_priority(candidate, current):
+                selected[candidate.message] = candidate
+            continue
+
+        if _is_higher_priority(candidate, current):
+            _log_duplicate_mapping(host, kept=candidate, discarded=current)
+            selected[candidate.message] = candidate
+        else:
+            _log_duplicate_mapping(host, kept=current, discarded=candidate)
+
+    return [
+        (candidate.message, candidate.method)
+        for candidate in sorted(selected.values(), key=lambda item: item.index)
+    ]
+
+
+def _is_higher_priority(
+    candidate: _DispatchCandidate, current: _DispatchCandidate
+) -> bool:
+    if candidate.priority != current.priority:
+        return candidate.priority < current.priority
+    return candidate.index > current.index
+
+
+def _log_duplicate_mapping(
+    host: Any, kept: _DispatchCandidate, discarded: _DispatchCandidate
+) -> None:
+    message = (
+        f"Duplicate dispatch mapping for {kept.message}: "
+        f"keeping {kept.method} from {kept.source}; "
+        f"discarding {discarded.method} from {discarded.source}."
+    )
+    log_warning = getattr(host, "log_warning", None)
+    if callable(log_warning):
+        try:
+            log_warning(message)
+            return
+        except Exception:
+            pass
+
+    logging.getLogger(__name__).warning(message)
+
+
+def _handler_message(method: Any) -> str | None:
+    message = getattr(method, _HANDLER_ATTRIBUTE, None)
+    if message is not None:
+        return message
+
+    func = getattr(method, "__func__", None)
+    return getattr(func, _HANDLER_ATTRIBUTE, None)
+
+
+def get_callable_methods(host: Any) -> list[str]:
+    """Returns a list of callable method names that don't start with underscore."""
+    return [
+        func
+        for func in dir(host)
+        if callable(getattr(host, func)) and not func.startswith("_")
+    ]
+
+
+def get_handler_info(host: Any, method_name: str) -> tuple[str, str] | None:
+    """Analyzes a method to determine if it's a valid message handler.
+    Returns a tuple of (fully_qualified_class_name, method_name) if valid,
+    None otherwise.
+    """
+    try:
+        params = signature(getattr(host, method_name)).parameters
+        if len(params) != 1:
+            return None
+
+        param: Parameter = next(iter(params.values()))
+        annotation = param.annotation
+
+        if annotation == Parameter.empty:
+            return None
+
+        message = _message_class_name(annotation)
+        if message is None:
+            return None
+
+        return message, method_name
+
+    except ValueError:
+        return None
+
+
+def _message_class_name(message_type: Any) -> str | None:
+    if isinstance(message_type, str):
+        return message_type
+
+    if is_iris_object_instance(message_type):
+        return f"{type(message_type).__module__}.{type(message_type).__name__}"
+
+    if message_type is Any or message_type is object:
+        return None
+
+    if not isinstance(message_type, type):
+        return None
+
+    if not _is_dispatch_message_class(message_type):
+        return None
+
+    return f"{message_type.__module__}.{message_type.__name__}"
+
+
+def _is_dispatch_message_class(klass: type) -> bool:
+    if is_message_class(klass):
+        return True
+    if is_pickle_message_class(klass):
+        return True
+    if is_persistent_message_class(klass):
+        return True
+    return klass.__module__.startswith("iris")