iris-pex-embedded-python 4.0.0b5__tar.gz → 4.0.0b7__tar.gz

{iris_pex_embedded_python-4.0.0b5/src/iris_pex_embedded_python.egg-info → iris_pex_embedded_python-4.0.0b7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris_pex_embedded_python
-Version: 4.0.0b5
+Version: 4.0.0b7
 Summary: Iris Interoperability based on Embedded Python
 Author-email: grongier <guillaume.rongier@intersystems.com>
 License: MIT License
@@ -86,6 +86,6 @@ pip install iris-pex-embedded-python
 
 ## Getting Started
 
-If you're new to this project, begin by reading the [installation guide](https://grongierisc.github.io/interoperability-embedded-python/getting-started/installation). Then, follow the [first steps](https://grongierisc.github.io/interoperability-embedded-python/getting-started/first-steps) to create your first Business Operation.
+If you're new to this project, begin by reading the [installation guide](https://grongierisc.github.io/interoperability-embedded-python/getting-started/installation). Then, follow the [first steps](https://grongierisc.github.io/interoperability-embedded-python/getting-started/first-steps) to create your first Python-authored production.
 
 Happy coding!

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/README.md

@@ -32,6 +32,6 @@ pip install iris-pex-embedded-python
 
 ## Getting Started
 
-If you're new to this project, begin by reading the [installation guide](https://grongierisc.github.io/interoperability-embedded-python/getting-started/installation). Then, follow the [first steps](https://grongierisc.github.io/interoperability-embedded-python/getting-started/first-steps) to create your first Business Operation.
+If you're new to this project, begin by reading the [installation guide](https://grongierisc.github.io/interoperability-embedded-python/getting-started/installation). Then, follow the [first steps](https://grongierisc.github.io/interoperability-embedded-python/getting-started/first-steps) to create your first Python-authored production.
 
-Happy coding!
+Happy coding!

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/pyproject.toml

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

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/src/iop/__init__.py

@@ -16,6 +16,7 @@ from iop.messages.base import (
     _PydanticMessage,
     _PydanticPickleMessage,
 )
+from iop.messages.decorators import handler as handler
 from iop.messages.persistent import Field as Field
 from iop.messages.persistent import Model as Model
 from iop.messages.persistent import _PersistentMessage
@@ -85,6 +86,7 @@ __all__ = [
     "Utils",
     "bind_component",
     "controls",
+    "handler",
     "list_bindings",
     "register_component",
     "setting",

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/src/iop/cls/IOP/Common.cls

@@ -187,7 +187,7 @@ Method OnTearDown() As %Status
     set tSC = $$$OK
     if $isObject(..%class) {
         try {
-            do ..%class."_dispatch_on_tear_down"()
+            do ..%class."_dispatch_on_tear_down"($this)
         } catch ex {
             set tSC = ex.AsStatus()
         }
@@ -313,7 +313,7 @@ ClassMethod OnGetConnections(
     do pItem.GetModifiedSetting("%classname", .tClassname)
     do pItem.GetModifiedSetting("%module", .tModule)
 
-    // try to instantiate class
+    // Prepare the Python import path for connection discovery.
     if tClasspaths '="" {
             set sys = ##class(%SYS.Python).Import("sys")
             set delimiter = $s($system.Version.GetOS()="Windows":";",1:":")
@@ -329,7 +329,14 @@ ClassMethod OnGetConnections(
     set builtins = ##class(%SYS.Python).Import("builtins")
     set module = ##class(%SYS.Python).Import(tModule)
     set class = builtins.getattr(module, tClassname)
+    // Allocate without calling Python __init__. Connection discovery must not
+    // run user startup code; IoP uses on_init() as the lifecycle hook.
     set tClass = class."__new__"(class)
+    Try {
+        do tClass."_warn_if_custom_init"()
+    }
+    Catch ex {
+    }
 
     set tPythonList = tClass."on_get_connections"()
     set tPythonListLen = tPythonList."__len__"()
@@ -535,6 +542,8 @@ Method CreateClassInstance(module As %SYS.Python) As %SYS.Python [ Private ]
 {
     set builtins = ##class(%SYS.Python).Import("builtins")
     set class = builtins.getattr(module, ..%classname)
+    // Intentionally bypass Python __init__. IRIS applies handles/settings and
+    // then calls on_init() through _dispatch_on_init().
     quit class."__new__"(class)
 }
 

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/src/iop/cls/IOP/PrivateSession/Duplex.cls

@@ -250,7 +250,7 @@ Method OnTearDown() As %Status
     #dim tSC As %Status = $$$OK
     try {
         If ..%InPrivateSession Set tSC=..StopPrivateSession() Quit:$$$ISERR(tSC)
-        do ..%class."_dispatch_on_tear_down"()
+        do ..%class."_dispatch_on_tear_down"($this)
     } catch {
         Set tSC=$$$EnsSystemError
     }

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/src/iop/cls/IOP/Utils.cls

@@ -281,7 +281,14 @@ ClassMethod GetRemoteClassInfo(
 
 		// Get the class
 		set class = builtins.getattr(module, pRemoteClassname)
+		// Allocate without calling Python __init__. Registration only reads
+		// metadata; runtime startup belongs in on_init().
 		set tClass = class."__new__"(class)
+		Try {
+			Do tClass."_warn_if_custom_init"()
+		}
+		Catch ex {
+		}
 
 		If $IsObject(tClass) {
 			#; List of information about the class as a whole - $lb(SuperClass, Description, InfoURL, IconURL, Adapter)

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/src/iop/components/business_operation.py

@@ -55,11 +55,12 @@ class _BusinessOperation(_BusinessHost):
             self.Adapter = self.adapter = handle_partner
         return
 
-    def _dispatch_on_init(self, host_object: Any) -> None:
-        """For internal use only."""
-        create_dispatch(self)
-        self.on_init()
-        return
+    def _dispatch_on_init(self, host_object: Any) -> None:
+        """For internal use only."""
+        self._log_custom_init_warning()
+        create_dispatch(self)
+        self.on_init()
+        return
 
     @input_deserializer
     @output_serializer

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/src/iop/components/business_process.py

@@ -165,11 +165,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
 

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/src/iop/components/business_service.py

@@ -34,11 +34,12 @@ class _BusinessService(_BusinessHost):
     Adapter = adapter = None
     _wait_for_next_call_interval = False
 
-    def _dispatch_on_init(self, host_object) -> None:
-        """For internal use only."""
-        self.on_init()
-
-        return
+    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):
         """Handle a message received by the business service.

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/src/iop/components/common.py

@@ -1,7 +1,8 @@
 import inspect
-import traceback
-from enum import Enum
-from types import UnionType
+import traceback
+import warnings
+from enum import Enum
+from types import UnionType
 from typing import (
     Annotated,
     Any,
@@ -133,8 +134,17 @@ def _is_setting_member(name: str, value: Any) -> bool:
     return not (
         inspect.ismethod(value) or inspect.isfunction(value) or inspect.isclass(value)
     )
-
-
+
+
+def _custom_init_owner(cls: type) -> type | None:
+    for base in inspect.getmro(cls):
+        init = base.__dict__.get("__init__", _NO_VALUE)
+        if init is _NO_VALUE or init is object.__init__:
+            continue
+        return base
+    return None
+
+
 class _Common:
     """Base class that defines common methods for all component types.
 
@@ -144,13 +154,52 @@ class _Common:
 
     INFO_URL: ClassVar[str]
     ICON_URL: ClassVar[str]
-    iris_handle: Any = None
-    _log_to_console: bool = False
-    _logger: logging.Logger | None = None
-
-    @staticmethod
-    def get_adapter_type() -> str | None:
-        """Get the adapter type for this component. Override in subclasses."""
+    iris_handle: Any = None
+    _log_to_console: bool = False
+    _logger: logging.Logger | None = None
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        cls._warn_if_custom_init_defined(stacklevel=2)
+
+    @classmethod
+    def _custom_init_warning_message(cls) -> str | None:
+        if _custom_init_owner(cls) is None:
+            return None
+        classname = f"{cls.__module__}.{cls.__qualname__}"
+        return (
+            f"{classname} defines or inherits __init__(), but IoP/IRIS "
+            "instantiates components with __new__() and does not call "
+            "__init__(). Move startup logic to on_init(); use class attributes "
+            "or iop.Setting for configurable defaults."
+        )
+
+    @classmethod
+    def _warn_if_custom_init_defined(cls, stacklevel: int = 2) -> None:
+        message = cls._custom_init_warning_message()
+        if message is None:
+            return
+        warnings.warn(message, RuntimeWarning, stacklevel=stacklevel)
+
+    def _log_custom_init_warning(self) -> None:
+        message = self.__class__._custom_init_warning_message()
+        if message is None:
+            return
+        try:
+            self.log_warning(message)
+        except Exception:
+            try:
+                warnings.warn(message, RuntimeWarning, stacklevel=2)
+            except Exception:
+                pass
+
+    def _warn_if_custom_init(self) -> None:
+        """Metadata-safe warning hook for ObjectScript __new__ allocations."""
+        self._log_custom_init_warning()
+
+    @staticmethod
+    def get_adapter_type() -> str | None:
+        """Get the adapter type for this component. Override in subclasses."""
         return None
 
     @property
@@ -191,9 +240,10 @@ class _Common:
     def _dispatch_on_connected(self, host_object: Any) -> None:
         self.on_connected()
 
-    def _dispatch_on_init(self, host_object: Any) -> None:
-        """Initialize component when started."""
-        self.on_init()
+    def _dispatch_on_init(self, host_object: Any) -> None:
+        """Initialize component when started."""
+        self._log_custom_init_warning()
+        self.on_init()
 
     def _dispatch_on_tear_down(self, host_object: Any) -> None:
         self.on_tear_down()

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/src/iop/messages/decorators.py

@@ -3,6 +3,7 @@ from functools import wraps
 from typing import Any
 
 from .dispatch import dispatch_deserializer, dispatch_serializer
+from .dispatch import handler as handler
 
 
 def input_serializer(fonction: Callable) -> Callable:

{iris_pex_embedded_python-4.0.0b5 → iris_pex_embedded_python-4.0.0b7}/src/iop/messages/dispatch.py

@@ -1,3 +1,6 @@
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
 from inspect import Parameter, signature
 from typing import Any
 
@@ -29,6 +32,34 @@ _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.
+
+    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:
@@ -119,7 +150,7 @@ def dispatch_message(host: Any, request: Any) -> Any:
 
     for msg, method in host.DISPATCH:
         if msg == module + "." + classname:
-            call = method
+            return getattr(host, method)(request)
 
     return getattr(host, call)(request)
 
@@ -129,14 +160,35 @@ def create_dispatch(host: Any) -> None:
     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.
     """
-    dispatch = _declared_dispatch(host)
+    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 and handler_info not in dispatch:
-            dispatch.append(handler_info)
+        if handler_info:
+            message, method = handler_info
+            candidates.append(
+                _DispatchCandidate(
+                    message, method, "typed method", priority=1, index=index
+                )
+            )
+            index += 1
 
-    host.DISPATCH = dispatch
+    host.DISPATCH = _deduplicate_dispatch(host, candidates)
 
 
 def _declared_dispatch(host: Any) -> list[tuple[str, str]]:
@@ -150,6 +202,82 @@ def _declared_dispatch(host: Any) -> list[tuple[str, str]]:
     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 [
@@ -172,20 +300,27 @@ def get_handler_info(host: Any, method_name: str) -> tuple[str, str] | None:
         param: Parameter = next(iter(params.values()))
         annotation = param.annotation
 
-        if isinstance(annotation, str):
-            # return it as is, assuming it's a fully qualified class name
-            return annotation, method_name
-
-        if is_iris_object_instance(annotation):
-            return (
-                f"{type(annotation).__module__}.{type(annotation).__name__}",
-                method_name,
-            )
+        if annotation == Parameter.empty:
+            return None
 
-        if annotation == Parameter.empty or not isinstance(annotation, type):
+        message = _message_class_name(annotation)
+        if message is None:
             return None
 
-        return f"{annotation.__module__}.{annotation.__name__}", method_name
+        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 not isinstance(message_type, type):
+        return None
+
+    return f"{message_type.__module__}.{message_type.__name__}"