iris-pex-embedded-python 4.0.0b14__tar.gz → 4.0.1b1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris_pex_embedded_python
-Version: 4.0.0b14
+Version: 4.0.1b1
 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.1b1}/docs/agents-template.md

@@ -53,6 +53,21 @@ Update this list for the local project:
 - `tests/`: local test suite.
 - `data/` or `samples/`: example payloads.
 
+## settings.py Import Rules
+
+- Treat the directory containing `settings.py` as the project import root for
+  migration.
+- Import production graph, message, and component modules from paths reachable
+  relative to `settings.py`.
+- If `production.py` is next to `settings.py`, use
+  `from production import prod`.
+- If the application is packaged under a directory next to `settings.py`, use
+  package imports such as `from myapp.production import prod`.
+- Do not ask users to set `PYTHONPATH` to make migration imports work.
+- Do not patch `os.environ["PYTHONPATH"]` or global `sys.path` in application
+  code to hide import problems.
+- Fix import errors by changing the project layout or import statements.
+
 ## IoP Rules
 
 - Prefer a Python `Production` object exported through `PRODUCTIONS`.
@@ -115,6 +130,10 @@ iop --migrate settings.py --dry-run
 iop --migrate settings.py
 ```
 
+Do not use `iop --test` as the normal way to test Business Services. Test
+services through the runtime director or production runtime API so the deployed
+production context, component settings, and configured targets are used.
+
 If this repository uses Docker or Compose, add the exact command here:
 
 ```bash

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/docs/ai-coding.md

@@ -10,7 +10,7 @@ Ask the tool to read the project guidance before it writes code:
 ```text
 You are helping me build an IoP application.
 Read these files first:
-- AGENTS.md
+- local AGENTS.md, if this application repository has one
 - docs/ai-coding.md
 - docs/cookbooks/index.md
 - docs/getting-started/first-steps.md
@@ -19,15 +19,16 @@ Read these files first:
 
 Use the Python Production graph workflow for new applications.
 Do not put component startup logic in __init__(); use on_init().
+Treat the directory containing settings.py as the project import root.
+Import production modules relative to settings.py; do not modify PYTHONPATH.
+Do not use iop --test to test Business Services; use the runtime director.
 Use the relevant cookbook for the task.
 Show the migration and verification commands.
 ```
 
-On the published docs site, open
-[AGENTS.md](https://github.com/grongierisc/interoperability-embedded-python/blob/master/AGENTS.md)
-from the repository root.
-
-For your own IoP application repository, copy the
+The IoP framework repository root `AGENTS.md` is for framework source
+development, not application guidance. For your own IoP application repository,
+copy the
 [reusable AGENTS.md template](agents-template.md) into the project root and
 adapt it to the local production. For healthcare projects, also read
 [Healthcare AI-assisted coding](healthcare-ai-coding.md).

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/docs/command-line.md

@@ -377,7 +377,12 @@ python3 -m pip install "iris-persistence>=0.1.0"
 
 ## test
 
-The test command allows testing IoP components. You can optionally specify a test name, classname, and body.
+The test command is a low-level helper for testing IoP components. You can
+optionally specify a test name, classname, and body.
+
+Do not use `iop --test` as the normal way to test Business Services. Test
+services through the runtime director or production runtime API so the deployed
+production context, component settings, and configured targets are used.
 
 Basic test:
 ```bash

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/docs/cookbooks/add-polling-service.md

@@ -31,6 +31,8 @@ Implementation requirements:
 - Do not put startup code in __init__(); use on_init() only if required.
 - Update settings.py to add the service and connect service.Output to the
   destination component.
+- Do not use iop --test to test the service; use the runtime director or
+  production runtime API for service tests.
 - Include migration dry-run and verification commands.
 ```
 
@@ -68,7 +70,8 @@ iop --migrate settings.py
 - Dry-run migration shows the service, target setting, and destination
   component.
 - Unit tests cover any pure Python polling decisions or message construction.
-- Runtime verification confirms `on_poll()` emits the expected message.
+- Runtime verification confirms `on_poll()` emits the expected message through
+  the deployed production context.
 
 ## Common Mistakes
 
@@ -76,4 +79,3 @@ iop --migrate settings.py
   services.
 - Forgetting to connect `service.Output` to the destination.
 - Putting long-lived connection setup in `__init__()` instead of `on_init()`.
-

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/docs/cookbooks/code-index.md

@@ -70,6 +70,23 @@ When starting from source code, build applications through public imports from
 `iop` and a `Production` graph. Do not copy internal runtime classes such as
 `_BusinessHost` into application code; use them only to understand behavior.
 
+## settings.py Import Quick Reference
+
+Treat the directory containing `settings.py` as the project import root for
+migration. Import the production graph, messages, and components from modules
+reachable relative to that file, such as `from production import prod` or
+`from myapp.production import prod`.
+
+Do not set `PYTHONPATH`, patch `os.environ["PYTHONPATH"]`, or mutate global
+`sys.path` in application code to make migration imports pass. Fix the package
+layout or import statements instead.
+
+## Runtime Test Quick Reference
+
+Do not use `iop --test` as the normal way to test Business Services. Test
+services through the runtime director or production runtime API so the deployed
+production context, component settings, and configured targets are used.
+
 ## Healthcare Add-on
 
 If the code or task mentions HL7v2, FHIR, Health Connect, FHIR bundles, MLLP,

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/docs/cookbooks/hello-world-production.md

@@ -28,6 +28,8 @@ Requirements:
   the operation.
 - Export PRODUCTIONS = [prod].
 - Do not use __init__() for component startup.
+- Do not use iop --test to test HelloService; use the runtime director or
+  production runtime API for service tests.
 - Show the migration dry-run command and the command to run the production
   migration.
 ```
@@ -99,4 +101,3 @@ iop --migrate settings.py
   `Production` graph.
 - Calling `HelloOperation` directly from `HelloService` instead of sending a
   message through the production target.
-

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/docs/cookbooks/index.md

@@ -7,9 +7,13 @@ Before using a cookbook, give the assistant this context:
 
 ```text
 You are helping me build an IoP application.
-Read AGENTS.md, settings.py, and the relevant cookbook before changing code.
+Read local AGENTS.md if this application has one, settings.py, and the
+relevant cookbook before changing code.
 Use the Python Production graph workflow for new applications.
 Do not put component startup logic in __init__(); use on_init().
+Treat the directory containing settings.py as the project import root.
+Import production modules relative to settings.py; do not modify PYTHONPATH.
+Do not use iop --test to test Business Services; use the runtime director.
 Show the migration and verification commands.
 ```
 

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/docs/getting-started/first-steps.md

@@ -151,4 +151,9 @@ iop --migrate settings.py
 
 This command creates the IRIS proxy classes for the Python components and registers `HelloWorld.Production`.
 
+When you need to test `HelloService` at runtime, do not use `iop --test`.
+Business Service tests should go through the runtime director or production
+runtime API so the deployed production context, component settings, and
+configured targets are used.
+
 More information about registering components can be found [here](register-component.md).

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/docs/getting-started/register-component.md

@@ -58,6 +58,11 @@ Migration registers the generated IRIS proxy classes for `FileService` and
 class. `prod.connect(file.Output, orders)` sets that setting to the destination
 component and records the production graph edge.
 
+When you need to test `FileService` at runtime, do not use `iop --test`.
+Business Service tests should go through the runtime director or production
+runtime API so the deployed production context, component settings, and
+configured targets are used.
+
 ## Settings File Sections
 
 A migration file can define these sections:

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/docs/production-graph.md

@@ -79,7 +79,8 @@ object graph. It does not silently fall back to IRIS export. Existing deployed
 productions should be reconstructed explicitly with `Production.from_iris(...)`
 before testing by target setting path. Runtime status checks fail closed when the
 current production cannot be verified. `prod.test(...)` remains a compatibility
-alias.
+alias. For Business Services, use this production/director runtime path instead
+of `iop --test`.
 
 `ComponentRef` exposes convenience methods that delegate to its owning
 production: `inspect()`, `start()`, `stop()`, `restart()`, and `test(...)`.

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/docs/python-api.md

@@ -798,7 +798,8 @@ the reconstruction quality or route origin.
 `Production` object graph only. For an already deployed production, first build
 an operational reconstruction with `Production.from_iris(...)`, then call
 `test_component()` on that object. `prod.test(...)` remains as a compatibility
-alias.
+alias. For Business Services, use this production/director runtime path instead
+of `iop --test`.
 
 Lifecycle helpers such as `prod.stop()`, `prod.restart()`, `prod.kill()`, and
 `prod.update()` verify that IRIS currently points at the same production before

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/docs/settings.md

@@ -44,6 +44,38 @@ binding with:
 iop --unbind Python.MyBusinessOperation
 ```
 
+## Import Behavior
+
+IoP loads the migration file as a file-based Python module. The directory
+containing that file is temporarily placed first on `sys.path` while the file
+is imported. Treat the directory containing `settings.py` or `demo.py` as the
+project import root for migration.
+
+Keep production code in modules or packages reachable from that directory and
+import it normally:
+
+```python
+# settings.py next to production.py
+from production import prod
+
+PRODUCTIONS = [prod]
+```
+
+For a packaged application, keep the package next to the migration file and use
+package imports:
+
+```python
+# settings.py next to myapp/
+from myapp.production import prod
+
+PRODUCTIONS = [prod]
+```
+
+Do not require users or agents to set `PYTHONPATH` to make migration imports
+work. Do not patch `os.environ["PYTHONPATH"]` or global `sys.path` in
+application code to hide import problems. Fix imports by changing the project
+layout or import statements relative to the migration file location.
+
 ## Configuration Sections
 
 The migration file supports four main sections:
@@ -355,7 +387,8 @@ from runtime `OnGetConnections`, or inferred from Host settings.
 `Production` object graph only. If you want to test a production that already
 exists in IRIS, use `Production.from_iris(...)` first and call
 `test_component()` on the imported operational reconstruction. `prod.test(...)`
-remains available as a compatibility alias.
+remains available as a compatibility alias. For Business Services, use this
+production/director runtime path instead of `iop --test`.
 
 Lifecycle methods are scoped to the production object. `prod.stop()`,
 `prod.restart()`, `prod.kill()`, and `prod.update()` verify that IRIS currently

{iris_pex_embedded_python-4.0.0b14 → iris_pex_embedded_python-4.0.1b1}/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools", "wheel"]
 
 [project]
 name = "iris_pex_embedded_python"
-version = "4.0.0b14"
+version = "4.0.1b1"
 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.1b1}/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.1b1}/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.1b1}/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(); "