iris-pex-embedded-python 4.0.0b15__tar.gz → 4.0.1b2__tar.gz

{iris_pex_embedded_python-4.0.0b15/src/iris_pex_embedded_python.egg-info → iris_pex_embedded_python-4.0.1b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris_pex_embedded_python
-Version: 4.0.0b15
+Version: 4.0.1b2
 Summary: Iris Interoperability based on Embedded Python
 Author-email: grongier <guillaume.rongier@intersystems.com>
 License: MIT License
@@ -69,14 +69,38 @@ For application repositories, start from the [reusable AGENTS.md template](https
 
 ## Example
 
-Here's a simple example of how a Business Operation can be implemented in Python:
+Here's a tiny Python-authored production:
 
 ```python
-from iop import BusinessOperation
+from dataclasses import dataclass
 
-class MyBo(BusinessOperation):
-    def on_message(self, request):
-        self.log_info("Hello World")
+from iop import BusinessOperation, Message, PollingBusinessService, Production, target
+
+
+@dataclass
+class HelloRequest(Message):
+    text: str = "Hello World"
+
+
+class HelloService(PollingBusinessService):
+    Output = target()
+
+    def on_poll(self):
+        self.send_request_async(self.Output, HelloRequest())
+
+
+class HelloOperation(BusinessOperation):
+    def on_message(self, request: HelloRequest):
+        self.log_info(request.text)
+        return request
+
+
+prod = Production("HelloWorld.Production", testing_enabled=True)
+service = prod.service("HelloService", HelloService)
+operation = prod.operation("HelloOperation", HelloOperation)
+prod.connect(service.Output, operation)
+
+PRODUCTIONS = [prod]
 ```
 
 ## Installation

{iris_pex_embedded_python-4.0.0b15 → iris_pex_embedded_python-4.0.1b2}/README.md

@@ -15,14 +15,38 @@ For application repositories, start from the [reusable AGENTS.md template](https
 
 ## Example
 
-Here's a simple example of how a Business Operation can be implemented in Python:
+Here's a tiny Python-authored production:
 
 ```python
-from iop import BusinessOperation
+from dataclasses import dataclass
 
-class MyBo(BusinessOperation):
-    def on_message(self, request):
-        self.log_info("Hello World")
+from iop import BusinessOperation, Message, PollingBusinessService, Production, target
+
+
+@dataclass
+class HelloRequest(Message):
+    text: str = "Hello World"
+
+
+class HelloService(PollingBusinessService):
+    Output = target()
+
+    def on_poll(self):
+        self.send_request_async(self.Output, HelloRequest())
+
+
+class HelloOperation(BusinessOperation):
+    def on_message(self, request: HelloRequest):
+        self.log_info(request.text)
+        return request
+
+
+prod = Production("HelloWorld.Production", testing_enabled=True)
+service = prod.service("HelloService", HelloService)
+operation = prod.operation("HelloOperation", HelloOperation)
+prod.connect(service.Output, operation)
+
+PRODUCTIONS = [prod]
 ```
 
 ## Installation

{iris_pex_embedded_python-4.0.0b15 → iris_pex_embedded_python-4.0.1b2}/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`.
@@ -64,8 +79,8 @@ Update this list for the local project:
 - Use `@dataclass` on regular `Message` classes. Do not decorate
   `PydanticMessage` classes with `@dataclass`.
 - Use `PersistentMessage` only when IRIS needs a native persistent message body.
-- Avoid raw `CLASSES` entries for components already declared in the production
-  graph.
+- Put new graph components in `PRODUCTIONS`; avoid raw `CLASSES` entries for
+  components already declared in the production graph.
 - Keep executable sample code behind `if __name__ == "__main__":` when it lives
   in a migration file.
 
@@ -76,6 +91,8 @@ Update this list for the local project:
   `submit_order(self, request: OrderRequest)`.
 - Use `@handler(MessageType)` when the handler should be explicit or the type
   annotation is not enough.
+- Avoid explicit `DISPATCH` entries in new code; treat them as legacy or
+  advanced compatibility hooks.
 - Avoid duplicate handlers for the same message type unless the intended
   precedence is clear.
 
@@ -115,6 +132,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.0b15 → iris_pex_embedded_python-4.0.1b2}/docs/ai-coding.md

@@ -10,24 +10,26 @@ 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/cookbooks/code-index.md, when starting from source code
 - docs/getting-started/first-steps.md
 - docs/getting-started/register-component.md
 - docs/production-graph.md
 
 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.0b15 → iris_pex_embedded_python-4.0.1b2}/docs/command-line.md

@@ -209,6 +209,10 @@ The plan uses the same sections as the migration file: `CLASSES`, `SCHEMAS`,
 components or `PersistentMessage` classes. Migration output includes the mode,
 namespace, and a final `Migration succeeded` line when the migration completes.
 
+For new Python-authored production components, prefer `Production` objects in
+`PRODUCTIONS`; use `CLASSES` for standalone bindings, native
+`PersistentMessage` classes, and legacy migration files.
+
 Production validation warns by default. Pass `--strict-production-validation`
 to fail the dry-run or migration when validation reports an issue:
 
@@ -377,7 +381,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.0b15 → iris_pex_embedded_python-4.0.1b2}/docs/component-interaction.md

@@ -27,6 +27,11 @@ To exchange messages between components, you can use the following methods:
 - `send_multi_request_sync`: This method is used to send multiple requests synchronously. It will wait for all responses before continuing.
 - `send_generator_request`: This method is used to send a request synchronously and return a generator.
 
+For new Python-authored productions, pass a `target()` attribute such as
+`self.Output` to these methods and connect it in the `Production` graph with
+`prod.connect(...)`. Hard-coded target component names are mainly for legacy or
+manual code.
+
 ## send_request_sync
 
 This method is used to send a request synchronously. It will wait for a response before continuing.
@@ -34,12 +39,12 @@ This method is used to send a request synchronously. It will wait for a response
 ### Function signature
 
 ```python
-def send_request_sync(self, target: str, request: Union[Message, Any], 
+def send_request_sync(self, target: str | TargetSettingRef, request: Union[Message, Any],
                         timeout: int = -1, description: Optional[str] = None) -> Any:
     """Send message synchronously to target component.
     
     Args:
-        target: Name of target component
+        target: Target setting reference such as self.Output, or a target component name for legacy/manual code
         request: Message to send
         timeout: Timeout in seconds, -1 means wait forever 
         description: Optional description for logging
@@ -56,15 +61,16 @@ def send_request_sync(self, target: str, request: Union[Message, Any],
 ### Example usage
 
 ```python
-from iop import BusinessProcess
+from iop import BusinessProcess, target
 from msg import MyMessage
 
 class MyBP(BusinessProcess):
+    Output = target()
 
     def on_message(self, request):
         msg = MyMessage(message="Hello World")
         # Send a synchronous request to the target component
-        response = self.send_request_sync("Python.MyBO", msg)
+        response = self.send_request_sync(self.Output, msg)
         self.log_info(f"Received response: {response}")
 ```
 
@@ -75,12 +81,12 @@ This method is used to send a request asynchronously. It will not wait for a res
 ### Function signature (for BusinessService and BusinessOperation)
 
 ```python
-def send_request_async(self, target: str, request: Union[Message, Any], 
+def send_request_async(self, target: str | TargetSettingRef, request: Union[Message, Any],
                         description: Optional[str] = None) -> None:
     """Send message asynchronously to target component.
     
     Args:
-        target: Name of target component
+        target: Target setting reference such as self.Output, or a target component name for legacy/manual code
         request: Message to send
         description: Optional description for logging
         
@@ -93,15 +99,16 @@ def send_request_async(self, target: str, request: Union[Message, Any],
 ### Example usage (for BusinessService and BusinessOperation)
 
 ```python
-from iop import BusinessService
+from iop import BusinessService, target
 from msg import MyMessage
 
 class MyBS(BusinessService):
+    Output = target()
 
     def on_message(self, request):
         msg = MyMessage(message="Hello World")
         # Send an asynchronous request to the target component
-        self.send_request_async("Python.MyBO", msg)
+        self.send_request_async(self.Output, msg)
         self.log_info("Request sent asynchronously")
 ```
 
@@ -111,11 +118,11 @@ directly. For regular message-driven services, prefer `on_message()`.
 ### Function signature (for BusinessProcess)
 
 ```python
-def send_request_async(self, target: str, request: Any, description: Optional[str]=None, completion_key: Optional[str]=None, response_required: bool=True) -> None:
+def send_request_async(self, target: str | TargetSettingRef, request: Any, description: Optional[str]=None, completion_key: Optional[str]=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
+        target: Target setting reference such as self.Output, or a target component name for legacy/manual code
         request: The message to send to the target
         description: An optional description property in the message header
         completion_key: A token to identify the completion of the request
@@ -130,17 +137,18 @@ def send_request_async(self, target: str, request: Any, description: Optional[st
 ### Example usage (for BusinessProcess)
 
 ```python
-from iop import BusinessProcess
+from iop import BusinessProcess, target
 from msg import MyMessage
 
 class MyBP(BusinessProcess):
+    Output = target()
 
     def on_message(self, request):
         msg_one = MyMessage(message="Message1")
         msg_two = MyMessage(message="Message2")
 
-        self.send_request_async("Python.MyBO", msg_one,completion_key="1")
-        self.send_request_async("Python.MyBO", msg_two,completion_key="2")
+        self.send_request_async(self.Output, msg_one, completion_key="1")
+        self.send_request_async(self.Output, msg_two, completion_key="2")
 
     def on_response(self, request, response, call_request, call_response, completion_key):
         if completion_key == "1":
@@ -160,12 +168,12 @@ This method is used to send a request asynchronously using an asyncio implementa
 ### Function signature
 
 ```python
-async def send_request_async_ng(self, target: str, request: Union[Message, Any], 
+async def send_request_async_ng(self, target: str | TargetSettingRef, request: Union[Message, Any],
                                    timeout: int = -1, description: Optional[str] = None) -> Any:
     """Send message asynchronously to target component with asyncio.
     
     Args:
-        target: Name of target component
+        target: Target setting reference such as self.Output, or a target component name for legacy/manual code
         request: Message to send
         timeout: Timeout in seconds, -1 means wait forever 
         description: Optional description for logging
@@ -182,11 +190,12 @@ async def send_request_async_ng(self, target: str, request: Union[Message, Any],
 import asyncio
 import random
 
-from iop import BusinessProcess
+from iop import BusinessProcess, target
 from msg import MyMessage
 
 
 class MyAsyncNGBP(BusinessProcess):
+    Output = target()
 
     def on_message(self, request):
 
@@ -201,8 +210,12 @@ class MyAsyncNGBP(BusinessProcess):
         # create 1 to 10 messages
         tasks = []
         for i in range(random.randint(1, 10)):
-            tasks.append(self.send_request_async_ng("Python.MyAsyncNGBO",
-                                                    MyMessage(message=f"Message {i}")))
+            tasks.append(
+                self.send_request_async_ng(
+                    self.Output,
+                    MyMessage(message=f"Message {i}"),
+                )
+            )
 
         return await asyncio.gather(*tasks)
 
@@ -215,12 +228,12 @@ This method is used to send multiple requests synchronously. It will wait for al
 ### Function signature
 
 ```python
-def send_multi_request_sync(self, target_request: List[Tuple[str, Union[Message, Any]]], 
+def send_multi_request_sync(self, target_request: List[Tuple[str | TargetSettingRef, Union[Message, Any]]],
                                timeout: int = -1, description: Optional[str] = None) -> List[Tuple[str, Union[Message, Any], Any, int]]:
     """Send multiple messages synchronously to target components.
     
     Args:
-        target_request: List of tuples (target, request) to send
+        target_request: List of tuples (target setting reference or legacy target name, request) to send
         timeout: Timeout in seconds, -1 means wait forever 
         description: Optional description for logging
         
@@ -237,18 +250,21 @@ def send_multi_request_sync(self, target_request: List[Tuple[str, Union[Message,
 ### Example usage
 
 ```python
-from iop import BusinessProcess
+from iop import BusinessProcess, target
 from msg import MyMessage
 
 
 class MyMultiBP(BusinessProcess):
+    Output = target()
 
     def on_message(self, request):
         msg_one = MyMessage(message="Message1")
         msg_two = MyMessage(message="Message2")
 
-        tuple_responses = self.send_multi_request_sync([("Python.MyMultiBO", msg_one),
-                                                        ("Python.MyMultiBO", msg_two)])
+        tuple_responses = self.send_multi_request_sync([
+            (self.Output, msg_one),
+            (self.Output, msg_two),
+        ])
 
         self.log_info("All requests have been processed")
         for target,request,response,status in tuple_responses:
@@ -262,11 +278,11 @@ This method is used to send a request synchronously and return a generator.
 ### Function signature
 
 ```python
-    def send_generator_request(self, target: str, request: Union[Message, Any], 
+    def send_generator_request(self, target: str | TargetSettingRef, request: Union[Message, Any],
                               timeout: int = -1, description: Optional[str] = None) -> _GeneratorRequest:
     """Send message as a generator request to target component.
     Args:
-        target: Name of target component
+        target: Target setting reference such as self.Output, or a target component name for legacy/manual code
         request: Message to send
         timeout: Timeout in seconds, -1 means wait forever
         description: Optional description for logging
@@ -282,15 +298,16 @@ This method is used to send a request synchronously and return a generator.
 
 ```python
 from typing import Any
-from iop import BusinessProcess,BusinessOperation
+from iop import BusinessOperation, BusinessProcess, target
 
 from msg import MyGenerator,MyGeneratorResponse
 
 class MyGeneratorProcess(BusinessProcess):
+    Output = target()
 
     def on_request(self, request: Any) -> Any:
         gen = self.send_generator_request(
-            target="User.MyGeneratorOperation",
+            target=self.Output,
             request=MyGenerator(my_string="Hello, World!"),
             timeout=10,
             description="My generator request")

{iris_pex_embedded_python-4.0.0b15 → iris_pex_embedded_python-4.0.1b2}/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.0b15 → iris_pex_embedded_python-4.0.1b2}/docs/cookbooks/code-index.md

@@ -31,6 +31,8 @@ the fuller cookbook workflows.
 | `src/iop/messages/base.py` | Python-only message contracts |
 | `src/iop/messages/persistent.py` | Native persistent IRIS message contracts |
 | `src/iop/messages/dispatch.py` | `@handler`, typed method dispatch, fallback `on_message()` |
+| `src/iop/components/common.py` | component lifecycle hooks such as `on_init()` and `on_tear_down()` |
+| `src/iop/components/business_host.py` | shared `send_request_sync(...)` and `send_request_async(...)` helpers |
 | `src/iop/components/business_process.py` | process runtime hooks and request helpers |
 | `src/iop/components/business_operation.py` | operation runtime dispatch |
 | `src/iop/components/business_service.py` | service `on_message()` and `on_process_input()` hooks |
@@ -48,6 +50,10 @@ to:
 Use `@handler(MessageType)` when the handler must be explicit. Use typed
 one-argument methods when annotations are enough.
 
+Explicit `DISPATCH` entries are still supported for legacy and advanced code,
+but new application code should prefer `@handler(MessageType)` or typed
+one-argument methods.
+
 ## Message Quick Reference
 
 Use `@dataclass` with regular `Message` classes:
@@ -70,6 +76,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.0b15 → iris_pex_embedded_python-4.0.1b2}/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.0b15 → iris_pex_embedded_python-4.0.1b2}/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.
 ```