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

iop/{_common.py → components/common.py}

@@ -1,27 +1,23 @@
-import abc
-import inspect
-import traceback
+import inspect
+import traceback
+import warnings
 from enum import Enum
 from types import UnionType
-from typing import (
-    Annotated,
-    Any,
-    ClassVar,
-    List,
-    Optional,
-    Tuple,
-    Union,
-    get_args,
-    get_origin,
-    get_type_hints,
-)
-
-from . import _iris
-from ._debugpy import debugpython
-from ._log_manager import LogManager, logging
-from ._settings import Setting
-
-
+from typing import (
+    Annotated,
+    Any,
+    ClassVar,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from ..runtime import iris as _iris
+from .debugpy import debugpython
+from .log_manager import LogManager, logging
+from .settings import Setting
+
 _NO_VALUE = object()
 
 _EXCLUDED_SETTING_NAMES = {
@@ -88,7 +84,7 @@ def _unwrap_annotated(data_type: Any) -> tuple[Any, tuple[Any, ...]]:
     return data_type, ()
 
 
-def _setting_from_annotation(data_type: Any) -> tuple[Any, Optional[Setting]]:
+def _setting_from_annotation(data_type: Any) -> tuple[Any, Setting | None]:
     data_type, metadata = _unwrap_annotated(data_type)
     setting = None
     for item in metadata:
@@ -106,7 +102,7 @@ def _unwrap_optional(data_type: Any) -> Any:
     return data_type
 
 
-def _iris_data_type(data_type: Any) -> Optional[str]:
+def _iris_data_type(data_type: Any) -> str | None:
     if data_type is None or data_type == "":
         return None
 
@@ -138,9 +134,18 @@ def _is_setting_member(name: str, value: Any) -> bool:
     return not (
         inspect.ismethod(value) or inspect.isfunction(value) or inspect.isclass(value)
     )
-
-
-class _Common(metaclass=abc.ABCMeta):
+
+
+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.
 
     Provides core functionality like initialization, teardown, connection handling
@@ -149,13 +154,52 @@ class _Common(metaclass=abc.ABCMeta):
 
     INFO_URL: ClassVar[str]
     ICON_URL: ClassVar[str]
-    iris_handle: Any = None
-    _log_to_console: bool = False
-    _logger: Optional[logging.Logger] = None
-
-    @staticmethod
-    def get_adapter_type() -> Optional[str]:
-        """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
@@ -179,10 +223,36 @@ class _Common(metaclass=abc.ABCMeta):
         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."""
@@ -196,9 +266,10 @@ class _Common(metaclass=abc.ABCMeta):
     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()
@@ -214,7 +285,7 @@ class _Common(metaclass=abc.ABCMeta):
 
     # Component information methods
     @classmethod
-    def _get_info(cls) -> List[str]:
+    def _get_info(cls) -> list[str]:
         """Get component configuration information.
 
         Returns information used to display in Production config UI including:
@@ -231,37 +302,26 @@ class _Common(metaclass=abc.ABCMeta):
         super_class = ""
         adapter = ""
         try:
-            # Get tuple of the class's base classes and loop through them until we find one of the PEX component classes
-            classes = inspect.getmro(cls)
-            for cl in classes:
-                classname = str(cl)[7:-1]
+            # Get tuple of the class's base classes and loop through them until we find one of the public component classes.
+            classes = inspect.getmro(cls)
+            for cl in classes:
+                classname = str(cl)[7:-1]
                 if classname in [
                     "'iop.BusinessService'",
-                    "'iop.BusinessOperation'",
-                    "'iop.DuplexOperation'",
-                    "'iop.DuplexService'",
-                    "'grongier.pex.BusinessService'",
-                    "'grongier.pex.BusinessOperation'",
-                    "'grongier.pex.DuplexOperation'",
-                    "'grongier.pex.DuplexService'",
-                ]:
-                    # Remove the apostrophes and set as super_class, then find if it uses an adapter
-                    super_class = classname[1:-1]
-                    adapter = cls.get_adapter_type()
-                    if adapter is None:
-                        # for retro-compatibility
-                        adapter = cls.getAdapterType()  # type: ignore
-                    break
-                elif classname in [
-                    "'iop.BusinessProcess'",
-                    "'iop.DuplexProcess'",
-                    "'iop.InboundAdapter'",
-                    "'iop.OutboundAdapter'",
-                    "'grongier.pex.BusinessProcess'",
-                    "'grongier.pex.DuplexProcess'",
-                    "'grongier.pex.InboundAdapter'",
-                    "'grongier.pex.OutboundAdapter'",
-                ]:
+                    "'iop.BusinessOperation'",
+                    "'iop.DuplexOperation'",
+                    "'iop.DuplexService'",
+                ]:
+                    # Remove the apostrophes and set as super_class, then find if it uses an adapter
+                    super_class = classname[1:-1]
+                    adapter = cls.get_adapter_type() or ""
+                    break
+                elif classname in [
+                    "'iop.BusinessProcess'",
+                    "'iop.DuplexProcess'",
+                    "'iop.InboundAdapter'",
+                    "'iop.OutboundAdapter'",
+                ]:
                     # Remove the apostrophes and set as super_class
                     super_class = classname[1:-1]
                     break
@@ -290,7 +350,7 @@ class _Common(metaclass=abc.ABCMeta):
         return ret
 
     @classmethod
-    def _get_properties(cls) -> List[List[Any]]:
+    def _get_properties(cls) -> list[list[Any]]:
         """Get component properties for Production configuration.
 
         Returns list of property definitions containing:
@@ -304,8 +364,8 @@ class _Common(metaclass=abc.ABCMeta):
 
         Only includes non-private class attributes and properties.
         """
-        ret = []
-        try:
+        ret = []
+        try:
             annotations = _type_hints_with_extras(cls)
             members = dict(inspect.getmembers(cls))
 
@@ -411,12 +471,15 @@ class _Common(metaclass=abc.ABCMeta):
                         _string_metadata(control),  # Control/editor context
                     ]
                 )
-        except Exception:
-            pass
-        return ret
+        except Exception as exc:
+            raise RuntimeError(
+                f"Failed to build settings metadata for "
+                f"{cls.__module__}.{cls.__qualname__}"
+            ) from exc
+        return ret
 
     # Logging methods
-    def _log(self) -> Tuple[str, Optional[str]]:
+    def _log(self) -> tuple[str, str | None]:
         """Get class and method name for logging.
 
         Returns:
@@ -432,7 +495,7 @@ class _Common(metaclass=abc.ABCMeta):
         return current_class, current_method
 
     def _logging(
-        self, message: str, level: int, to_console: Optional[bool] = None
+        self, message: str, level: int, to_console: bool | None = None
     ) -> None:
         """Write log entry.
 
@@ -441,56 +504,20 @@ class _Common(metaclass=abc.ABCMeta):
             level: Log level
             to_console: If True, log to console instead of IRIS
         """
-        current_class, current_method = self._log()
-        if to_console is None:
-            to_console = self.log_to_console
-        if level == logging.DEBUG:
-            self.logger.debug(
-                message,
-                extra={
-                    "to_console": to_console,
-                    "class_name": current_class,
-                    "method_name": current_method,
-                },
-            )
-        elif level == logging.INFO:
-            self.logger.info(
-                message,
-                extra={
-                    "to_console": to_console,
-                    "class_name": current_class,
-                    "method_name": current_method,
-                },
-            )
-        elif level == logging.CRITICAL:
-            self.logger.critical(
-                message,
-                extra={
-                    "to_console": to_console,
-                    "class_name": current_class,
-                    "method_name": current_method,
-                },
-            )
-        elif level == logging.WARNING:
-            self.logger.warning(
-                message,
-                extra={
-                    "to_console": to_console,
-                    "class_name": current_class,
-                    "method_name": current_method,
-                },
-            )
-        elif level == logging.ERROR:
-            self.logger.error(
-                message,
-                extra={
-                    "to_console": to_console,
-                    "class_name": current_class,
-                    "method_name": current_method,
-                },
-            )
-
-    def trace(self, message: str, to_console: Optional[bool] = None) -> None:
+        current_class, current_method = self._log()
+        if to_console is None:
+            to_console = self.log_to_console
+        self.logger.log(
+            level,
+            message,
+            extra={
+                "to_console": to_console,
+                "class_name": current_class,
+                "method_name": current_method,
+            },
+        )
+
+    def trace(self, message: str, to_console: bool | None = None) -> None:
         """Write trace log entry.
 
         Args:
@@ -499,7 +526,7 @@ class _Common(metaclass=abc.ABCMeta):
         """
         self._logging(message, logging.DEBUG, to_console)
 
-    def log_info(self, message: str, to_console: Optional[bool] = None) -> None:
+    def log_info(self, message: str, to_console: bool | None = None) -> None:
         """Write info log entry.
 
         Args:
@@ -508,7 +535,7 @@ class _Common(metaclass=abc.ABCMeta):
         """
         self._logging(message, logging.INFO, to_console)
 
-    def log_alert(self, message: str, to_console: Optional[bool] = None) -> None:
+    def log_alert(self, message: str, to_console: bool | None = None) -> None:
         """Write alert log entry.
 
         Args:
@@ -517,7 +544,7 @@ class _Common(metaclass=abc.ABCMeta):
         """
         self._logging(message, logging.CRITICAL, to_console)
 
-    def log_warning(self, message: str, to_console: Optional[bool] = None) -> None:
+    def log_warning(self, message: str, to_console: bool | None = None) -> None:
         """Write warning log entry.
 
         Args:
@@ -526,7 +553,7 @@ class _Common(metaclass=abc.ABCMeta):
         """
         self._logging(message, logging.WARNING, to_console)
 
-    def log_error(self, message: str, to_console: Optional[bool] = None) -> None:
+    def log_error(self, message: str, to_console: bool | None = None) -> None:
         """Write error log entry.
 
         Args:
@@ -545,34 +572,3 @@ class _Common(metaclass=abc.ABCMeta):
         current_class, current_method = self._log()
         iris.cls("Ens.Util.Log").LogAssert(current_class, current_method, message)
 
-    def LOGINFO(self, message: str) -> None:
-        """DEPRECATED: Use log_info."""
-        return self.log_info(message=message)
-
-    def LOGALERT(self, message: str) -> None:
-        """DEPRECATED: Use log_alert."""
-        return self.log_alert(message)
-
-    def LOGWARNING(self, message: str) -> None:
-        """DEPRECATED: Use log_warning."""
-        return self.log_warning(message)
-
-    def LOGERROR(self, message: str) -> None:
-        """DEPRECATED: Use log_error."""
-        return self.log_error(message)
-
-    def LOGASSERT(self, message: str) -> None:
-        """DEPRECATED: Use log_assert."""
-        return self.log_assert(message)
-
-    def OnInit(self) -> None:
-        """DEPRECATED: Use on_init."""
-        return
-
-    def OnTearDown(self) -> None:
-        """DEPRECATED: Use on_tear_down."""
-        return
-
-    def OnConnected(self) -> None:
-        """DEPRECATED: Use on_connected."""
-        return

iop/{_debugpy.py → components/debugpy.py}

@@ -1,14 +1,14 @@
-import threading
-import time
 import contextlib
-import socket
 import os
+import socket
 import sys
+import threading
+import time
 from contextlib import closing
-from typing import Optional, cast, Any, Dict
+from typing import Any, cast
 
 
-def find_free_port(start: Optional[int] = None, end: Optional[int] = None) -> int:
+def find_free_port(start: int | None = None, end: int | None = None) -> int:
     port = start
     if port is None:
         port = 0
@@ -42,7 +42,7 @@ def is_debugpy_installed() -> bool:
         return False
 
 
-def _get_python_interpreter_path(install_dir: Optional[str]) -> Optional[str]:
+def _get_python_interpreter_path(install_dir: str | None) -> str | None:
     """Get the path to the Python interpreter."""
     if not install_dir:
         return None
@@ -53,12 +53,12 @@ def _get_python_interpreter_path(install_dir: Optional[str]) -> Optional[str]:
     return python_path if os.path.exists(python_path) else None
 
 
-def _get_debugpy_config(python_path: str) -> Dict[str, str]:
+def _get_debugpy_config(python_path: str) -> dict[str, str]:
     """Get the debugpy configuration."""
     return {"python": python_path}
 
 
-def configure_debugpy(self, python_path: Optional[str] = None) -> bool:
+def configure_debugpy(self, python_path: str | None = None) -> bool:
     """Configure debugpy with the appropriate Python interpreter."""
     import debugpy
 
@@ -116,7 +116,7 @@ def debugpython(self, host_object: Any) -> None:
     # hack to set __file__ for os module in debugpy
     # This is a workaround for the issue where debugpy cannot find the __file__ attribute of the os module.
     if not hasattr(os, "__file__"):
-        setattr(os, "__file__", __file__)
+        os.__file__ = __file__
 
     if host_object is None:
         self.log_alert("No host object found, cannot enable debugpy.")
@@ -164,7 +164,7 @@ def debugpython(self, host_object: Any) -> None:
 def debugpy_in_iris(iris_dir, port) -> bool:
 
     if not hasattr(os, "__file__"):
-        setattr(os, "__file__", __file__)
+        os.__file__ = __file__
 
     if not is_debugpy_installed():
         print("debugpy is not installed.")
@@ -195,7 +195,7 @@ def debugpy_in_iris(iris_dir, port) -> bool:
         return False
 
 
-def mgr_dir_to_install_dir(mgr_dir: str) -> Optional[str]:
+def mgr_dir_to_install_dir(mgr_dir: str) -> str | None:
     """Convert manager directory to install directory."""
     import os
 

iop/{_generator_request.py → components/generator_request.py}

@@ -1,7 +1,7 @@
-from typing import Any, Optional
+from typing import Any
 
-from . import _iris
-from ._dispatch import dispatch_serializer
+from ..messages.dispatch import dispatch_serializer
+from ..runtime import iris as _iris
 
 
 class _GeneratorRequest:
@@ -14,7 +14,7 @@ class _GeneratorRequest:
         target: str,
         request: Any,
         timeout: int = -1,
-        description: Optional[str] = None,
+        description: str | None = None,
     ) -> None:
         self.host = host
         self.target = target

iop/{_inbound_adapter.py → components/inbound_adapter.py}

@@ -1,4 +1,4 @@
-from ._common import _Common
+from .common import _Common
 
 
 class _InboundAdapter(_Common):
@@ -8,12 +8,12 @@ class _InboundAdapter(_Common):
 
     BusinessHost = business_host = business_host_python = None
 
-    def on_task(self):
-        """Called by the production framework at intervals determined by the business service CallInterval property.
-        It is responsible for receiving the data from the external system, validating the data, and sending it in a message to the business service OnProcessInput method.
-        The message can have any structure agreed upon by the inbound adapter and the business service.
-        """
-        return self.OnTask()
+    def on_task(self):
+        """Called by the production framework at intervals determined by the business service CallInterval property.
+        It is responsible for receiving the data from the external system, validating the data, and sending it in a message to the business service.
+        The message can have any structure agreed upon by the inbound adapter and the business service.
+        """
+        return None
 
     def _set_iris_handles(self, handle_current, handle_partner):
         """For internal use only."""
@@ -22,14 +22,6 @@ class _InboundAdapter(_Common):
         self.business_host = handle_partner
         try:
             self.business_host_python = handle_partner.GetClass()
-        except Exception:
-            pass
-        return
-
-    def OnTask(self):
-        """DEPRECATED : use on_task
-        Called by the production framework at intervals determined by the business service CallInterval property.
-        It is responsible for receiving the data from the external system, validating the data, and sending it in a message to the business service OnProcessInput method.
-        The message can have any structure agreed upon by the inbound adapter and the business service.
-        """
-        return
+        except Exception:
+            pass
+        return

iop/{_log_manager.py → components/log_manager.py}

@@ -1,6 +1,6 @@
 import logging
 
-from . import _iris
+from ..runtime import iris as _iris
 
 
 class LogManager:

iop/{_outbound_adapter.py → components/outbound_adapter.py}

@@ -1,4 +1,4 @@
-from ._common import _Common
+from .common import _Common
 
 
 class _OutboundAdapter(_Common):

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()