iris-pex-embedded-python 4.0.1b1__tar.gz → 4.0.1b2__tar.gz

{iris_pex_embedded_python-4.0.1b1/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.1b1
+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.1b1 → 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.1b1 → iris_pex_embedded_python-4.0.1b2}/docs/agents-template.md

@@ -79,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.
 
@@ -91,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.
 

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

@@ -13,6 +13,7 @@ Read these files first:
 - 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

{iris_pex_embedded_python-4.0.1b1 → 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:
 

{iris_pex_embedded_python-4.0.1b1 → 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.1b1 → 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:

{iris_pex_embedded_python-4.0.1b1 → iris_pex_embedded_python-4.0.1b2}/docs/example.md

@@ -5,7 +5,9 @@ Python-authored production that registers them with IRIS.
 
 ## Business Operation
 
-Below is an example of a business operation in Python:
+Below is a standalone business operation fragment. A normal application also
+declares a `Production` graph and connects senders with `target()` and
+`prod.connect(...)`.
 
 ```python
 from dataclasses import dataclass
@@ -80,7 +82,8 @@ iop --migrate /path/to/your/project/settings.py
 ```
 
 Use a standalone `CLASSES` entry only when you need to bind a Python component
-without adding it to a Python `Production` graph.
+without adding it to a Python `Production` graph. New graph components belong in
+`PRODUCTIONS`, where migration registers their Python classes automatically.
 
 ## Conservative Production Changes
 
@@ -113,15 +116,15 @@ Two kinds of business services can be created in Python:
 To create a business service, use the following code:
 
 ```python
-from iop import BusinessService
+from iop import BusinessService, target
 
 class MyBusinessService(BusinessService):
+    Output = target()
     
     def on_message(self, message_input: 'MyRequest'):
         # This method is called when the service is called
         self.log_info("[Python] MyBusinessService:on_message() is called with message: " + message_input.request_string)
-        response = MyResponse("MyBusinessService:on_message() echos")
-        return response
+        self.send_request_async(self.Output, message_input)
 ```
 
 ### Polling Business Service
@@ -129,18 +132,21 @@ class MyBusinessService(BusinessService):
 To create a polling business service, use the following code:
 
 ```python
-from iop import PollingBusinessService
+from iop import PollingBusinessService, target
 
 class MyBusinessService(PollingBusinessService):
+    Output = target()
 
     def on_poll(self):
         # This method is called by the scheduler
         self.log_info("[Python] MyBusinessService:on_poll() is called")
+        self.send_request_async(self.Output, MyRequest())
 ```
 
-## Flask app sending a message to an Business Service
+## Flask app sending a message to a Business Service
 
-To send a message to a business service, use the following code:
+To send a message to a deployed business service, use the runtime Director
+rather than instantiating production components directly:
 
 
 ```python
@@ -191,11 +197,12 @@ To make an async call with asyncio, use the following code:
 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):
 
@@ -208,8 +215,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)
 ```
@@ -219,18 +230,19 @@ class MyAsyncNGBP(BusinessProcess):
 To make an async call with the native `send_request_async` method, use the following code:
 
 ```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":
@@ -248,18 +260,21 @@ class MyBP(BusinessProcess):
 To make an async call with the `send_multi_request_sync` method, use the following code:
 
 ```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:

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

@@ -70,7 +70,7 @@ A migration file can define these sections:
 | Section | Purpose |
 |---------|---------|
 | `PRODUCTIONS` | Preferred way to register Python-authored production graphs |
-| `CLASSES` | Standalone bindings and native `PersistentMessage` registrations |
+| `CLASSES` | Standalone or legacy component bindings and native `PersistentMessage` registrations |
 | `SCHEMAS` | JSON schemas for DTL support |
 | `REMOTE_SETTINGS` | Remote IRIS connection settings |
 
@@ -111,7 +111,8 @@ CLASSES = {
 ## Standalone Bindings
 
 Use `CLASSES` when you need to create an IRIS proxy class without putting the
-component in a Python `Production` graph:
+component in a Python `Production` graph, usually for standalone bindings or
+legacy migration files:
 
 ```python
 from bo import FileOperation
@@ -230,7 +231,9 @@ iop --bindings --unused
 ## Python Shell Utilities
 
 The Python utility functions remain available for scripting standalone
-bindings. The migration-file workflow is preferred for normal projects.
+bindings and legacy/manual registration. The migration-file workflow with a
+`Production` object in `PRODUCTIONS` is preferred for normal projects, and it
+registers graph component classes automatically.
 
 ```python
 from iop import bind_component, register_component