feat: enhance target setting handling and validation across components, update documentation, and add related tests

bot · bot · commit d2f2ada0c89b · 2026-06-26T12:03:54.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,9 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.0.1] - unreleased
 ### Added
 - Add default target support to `target(...)`, allowing `target("OperationName")` to populate the generated setting initial expression, production Host setting, and graph edge once the named target item exists.
+- Allow `ComponentRef.connect(...)` to accept class-declared `target()` descriptors, supporting static-friendly calls such as `rest.connect(Rest.Output, operation)`.
+- Add package typing metadata with `py.typed` and explicit `ComponentRef` return annotations for production factory methods.
 
 ### Fixed
 - Expose declared and manual target settings through `dir(ComponentRef)` so `rest.my_target` style graph handles are discoverable by runtime autocomplete.
+- Validate target setting values that reference missing production items.
+- Render generated instance-style Python routes with `component.connect(...)`.
 - Refactor business process and operation message dispatch around normalized message keys for `@handler`, typed methods, legacy `DISPATCH`, and native IRIS requests.
 
 ## [4.0.0] - 2026-06-21
diff --git a/README.md b/README.md
@@ -44,7 +44,7 @@ class HelloOperation(BusinessOperation):
 prod = Production("HelloWorld.Production", testing_enabled=True)
 service = prod.service("HelloService", HelloService)
 operation = prod.operation("HelloOperation", HelloOperation)
-prod.connect(service.Output, operation)
+service.connect(HelloService.Output, operation)
 
 PRODUCTIONS = [prod]
 ```
diff --git a/docs/cookbooks/add-business-operation.md b/docs/cookbooks/add-business-operation.md
@@ -93,7 +93,8 @@ If another component sends to the operation, declare a `target()` setting on the
 sender and connect it:
 
 ```python
-prod.connect(process.Orders, operation)
+process = prod.process("OrderProcess", OrderProcess)
+process.connect(OrderProcess.Orders, operation)
 ```
 
 ## Migration Command
diff --git a/docs/cookbooks/add-business-process.md b/docs/cookbooks/add-business-process.md
@@ -85,8 +85,8 @@ process = prod.process("OrderProcess", OrderProcess)
 accepted = prod.operation("AcceptedOperation", AcceptedOperation)
 rejected = prod.operation("RejectedOperation", RejectedOperation)
 
-prod.connect(process.Accepted, accepted)
-prod.connect(process.Rejected, rejected)
+process.connect(OrderProcess.Accepted, accepted)
+process.connect(OrderProcess.Rejected, rejected)
 ```
 
 ## Migration Command
@@ -113,4 +113,3 @@ iop --migrate settings.py
   intended precedence explicit.
 - Calling a downstream component directly instead of sending a production
   message through a target.
-
diff --git a/docs/cookbooks/add-polling-service.md b/docs/cookbooks/add-polling-service.md
@@ -55,7 +55,7 @@ In `settings.py`:
 ```python
 service = prod.service("FilePollService", FilePollService)
 operation = prod.operation("TargetOperation", TargetOperation)
-prod.connect(service.Output, operation)
+service.connect(FilePollService.Output, operation)
 ```
 
 ## Migration Command
diff --git a/docs/cookbooks/hello-world-production.md b/docs/cookbooks/hello-world-production.md
@@ -74,7 +74,7 @@ prod = Production("HelloWorld.Production", testing_enabled=True)
 
 service = prod.service("HelloService", HelloService)
 operation = prod.operation("HelloOperation", HelloOperation)
-prod.connect(service.Output, operation)
+service.connect(HelloService.Output, operation)
 
 PRODUCTIONS = [prod]
 ```
diff --git a/docs/cookbooks/production-settings-and-targets.md b/docs/cookbooks/production-settings-and-targets.md
@@ -24,7 +24,7 @@ Implementation requirements:
 - Add services with prod.service(...), processes with prod.process(...), and
   operations with prod.operation(...).
 - Use target() attributes on component classes for outbound routing.
-- Use prod.connect(source.TargetName, destination) for graph edges.
+- Use component.connect(ComponentClass.TargetName, destination) for graph edges.
 - Keep PRODUCTIONS = [prod] as the migration entrypoint.
 - Do not add raw CLASSES entries for components already declared in the
   Production graph.
@@ -51,8 +51,8 @@ process = prod.process("RouteProcess", RouteProcess)
 accepted = prod.operation("AcceptedOperation", AcceptedOperation)
 rejected = prod.operation("RejectedOperation", RejectedOperation)
 
-prod.connect(process.Accepted, accepted)
-prod.connect(process.Rejected, rejected)
+process.connect(RouteProcess.Accepted, accepted)
+process.connect(RouteProcess.Rejected, rejected)
 ```
 
 When a route should have a conventional default, pass the target item name to
diff --git a/docs/getting-started/first-steps.md b/docs/getting-started/first-steps.md
@@ -126,7 +126,7 @@ prod = Production("HelloWorld.Production", testing_enabled=True)
 
 service = prod.service("HelloService", HelloService)
 operation = prod.operation("HelloOperation", HelloOperation)
-prod.connect(service.Output, operation)
+service.connect(HelloService.Output, operation)
 
 PRODUCTIONS = [prod]
 ```
@@ -136,7 +136,7 @@ In this production:
 - `Production("HelloWorld.Production")` declares the IRIS production class.
 - `prod.service("HelloService", HelloService)` adds one service item.
 - `prod.operation("HelloOperation", HelloOperation)` adds one operation item.
-- `prod.connect(service.Output, operation)` sets the service `Output` target to `HelloOperation` and records the production graph edge.
+- `service.connect(HelloService.Output, operation)` sets the service `Output` target to `HelloOperation` and records the production graph edge.
 - `PRODUCTIONS = [prod]` tells IoP what to migrate.
 
 You do not need a separate `CLASSES` dictionary for these production components. IoP registers Python component classes from the `Production` graph during migration.
diff --git a/docs/getting-started/register-component.md b/docs/getting-started/register-component.md
@@ -40,7 +40,7 @@ class OrderOperation(BusinessOperation):
 prod = Production("Demo.Production", testing_enabled=True)
 file = prod.service("FileInput", FileService)
 orders = prod.operation("OrderOperation", OrderOperation)
-prod.connect(file.Output, orders)
+file.connect(FileService.Output, orders)
 
 PRODUCTIONS = [prod]
 ```
@@ -55,7 +55,7 @@ Migration registers the generated IRIS proxy classes for `FileService` and
 `OrderOperation`, then saves `Demo.Production`.
 
 `target()` declares a configurable outbound target setting on the component
-class. `prod.connect(file.Output, orders)` sets that setting to the destination
+class. `file.connect(FileService.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`.
diff --git a/docs/index.md b/docs/index.md
@@ -8,51 +8,61 @@
 
 Welcome to the **Interoperability On Python (IoP)** proof of concept! This project demonstrates how the **IRIS Interoperability Framework** can be utilized with a **Python-first approach**.
 
+Documentation can be found [here](https://grongierisc.github.io/interoperability-embedded-python/).
+For prompt-driven workflows, see [AI-assisted coding with IoP](https://grongierisc.github.io/interoperability-embedded-python/ai-coding/).
+For task-oriented examples, see the [IoP cookbooks](https://grongierisc.github.io/interoperability-embedded-python/cookbooks/).
+For application repositories, start from the [reusable AGENTS.md template](https://grongierisc.github.io/interoperability-embedded-python/agents-template/).
+
 ## 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
 
-## Installation
 
-To start using this proof of concept, install it using pip:
+@dataclass
+class HelloRequest(Message):
+    text: str = "Hello World"
 
-```bash
-pip install iris-pex-embedded-python
-```
 
-with zpm/ipm:
+class HelloService(PollingBusinessService):
+    Output = target()
 
-install zpm : 
+    def on_poll(self):
+        self.send_request_async(self.Output, HelloRequest())
 
-```objectscript
-set r = ##class(%Net.HttpRequest).%New(),r.Server="pm.community.intersystems.com",r.SSLConfiguration="ISC.FeatureTracker.SSL.Config" d r.Get("/packages/zpm/0.9.0/installer"),$system.OBJ.LoadStream(r.HttpResponse.Data,"c") 
-```
 
-Then install the package:
+class HelloOperation(BusinessOperation):
+    def on_message(self, request: HelloRequest):
+        self.log_info(request.text)
+        return request
+
 
-```objectscript
-zpm "install pex-embbeded-python"
+prod = Production("HelloWorld.Production", testing_enabled=True)
+service = prod.service("HelloService", HelloService)
+operation = prod.operation("HelloOperation", HelloOperation)
+service.connect(HelloService.Output, operation)
+
+PRODUCTIONS = [prod]
 ```
 
+## Installation
 
-## Getting Started
+To start using this proof of concept, install it using pip:
 
-If you're new to this proof of concept, begin by reading the [installation guide](getting-started/installation.md). Then, follow the [first steps](getting-started/first-steps.md) to create your first Python-authored production.
+```bash
+pip install iris-pex-embedded-python
+```
+
+## Getting Started
 
-If you are using an AI coding assistant, start with [AI-assisted coding with IoP](ai-coding.md).
-For concrete workflows, use the [IoP cookbooks](cookbooks/index.md).
-For application repositories, copy the [reusable AGENTS.md template](agents-template.md).
-For healthcare productions, also see [Healthcare AI-assisted coding](healthcare-ai-coding.md).
+If you're new to this project, begin by reading the [installation guide](https://grongierisc.github.io/interoperability-embedded-python/getting-started/installation). Then, follow the [first steps](https://grongierisc.github.io/interoperability-embedded-python/getting-started/first-steps) to create your first Python-authored production.
 
-For the Pythonic production graph model, see [Production Graph](production-graph.md).
-For safe changes to existing IRIS productions, see the [production change workflow](production-change-workflow.md).
+If you are using an AI coding assistant, start with [AI-assisted coding with IoP](https://grongierisc.github.io/interoperability-embedded-python/ai-coding/).
+For concrete workflows, use the [IoP cookbooks](https://grongierisc.github.io/interoperability-embedded-python/cookbooks/).
+For healthcare productions, also see [Healthcare AI-assisted coding](https://grongierisc.github.io/interoperability-embedded-python/healthcare-ai-coding/).
 
 Happy coding!
diff --git a/docs/production-graph.md b/docs/production-graph.md
@@ -145,9 +145,25 @@ Python-authored components use Python classes:
 prod = Production("Demo.Production")
 file = prod.service("FileInput", FileService)
 orders = prod.operation(OrderOperation)
-prod.connect(file.Output, orders)
+file.connect(FileService.Output, orders)
 ```
 
+For static autocomplete, bind through the component ref and pass the descriptor
+from the component class:
+
+```python
+first = prod.service("FirstInput", FileService)
+second = prod.service("SecondInput", FileService)
+orders = prod.operation(OrderOperation)
+
+first.connect(FileService.Output, orders)
+second.connect(FileService.Output, orders)
+```
+
+The left-side `ComponentRef` selects the production item instance, so both
+connections bind the same class-declared target setting to different configured
+items.
+
 For a conventional route, the target can be defaulted on the component class:
 
 ```python
diff --git a/docs/python-api.md b/docs/python-api.md
@@ -504,7 +504,7 @@ class OrderOperation(BusinessOperation):
 prod = Production("Demo.Production")
 file = prod.service("FileInput", FileService)
 orders = prod.operation(OrderOperation)
-prod.connect(file.Output, orders)
+file.connect(FileService.Output, orders)
 ```
 
 The same topology can be declared as a production subclass. Instantiating the
@@ -561,7 +561,7 @@ class FileProduction(Production):
 `target()` declares a configurable outbound target setting on `FileService`.
 `Route(FileService.Output, ORDER_OPERATION)` wires that setting to a production
 item. This separation mirrors the instance-style form:
-`prod.connect(file.Output, orders)`.
+`file.connect(FileService.Output, orders)`.
 
 For Python component classes, prefer passing the descriptor
 (`FileService.Output`) to `Route`. For built-in IRIS or ObjectScript classes,
@@ -615,6 +615,19 @@ file = (
 )
 ```
 
+For Python components, `ComponentRef.connect(...)` also accepts the `target()`
+descriptor from the component class. This keeps the left-side production item
+instance explicit while giving static tools autocomplete on the class:
+
+```python
+first = prod.service("FirstInput", FileService)
+second = prod.service("SecondInput", FileService)
+orders = prod.operation(OrderOperation)
+
+first.connect(FileService.Output, orders)
+second.connect(FileService.Output, orders)
+```
+
 For ObjectScript or built-in IRIS components, use manual target setting names:
 
 ```python
@@ -642,7 +655,9 @@ instead of shadowing those attributes.
 
 Declared target settings are available as dynamic `ComponentRef` attributes,
 such as `rest.my_target`, and are exposed through `dir(rest)` for runtime
-autocomplete.
+autocomplete. For Pylance, mypy, and other static tools, prefer
+`rest.connect(Rest.my_target, operation)` because completion happens on the
+component class.
 
 Python `Production` is the source of truth for Python-authored topology. IRIS
 remains the runtime source of truth. Imported graphs are operational
diff --git a/docs/settings.md b/docs/settings.md
@@ -41,7 +41,7 @@ class HelloOperation(BusinessOperation):
 prod = Production("Demo.Production", testing_enabled=True)
 service = prod.service("HelloService", HelloService)
 operation = prod.operation("HelloOperation", HelloOperation)
-prod.connect(service.Output, operation)
+service.connect(HelloService.Output, operation)
 
 PRODUCTIONS = [prod]
 ```
@@ -201,13 +201,13 @@ class OrderOperation(BusinessOperation):
 prod = Production("Demo.Production", testing_enabled=True)
 file = prod.service("FileInput", FileService)
 orders = prod.operation(OrderOperation)
-prod.connect(file.Output, orders)
+file.connect(FileService.Output, orders)
 
 PRODUCTIONS = [prod]
 ```
 
 `target()` declares an outbound target setting on the component class.
-`prod.connect()` sets that setting to the destination component and
+`component.connect(ComponentClass.Target, destination)` sets that setting to the destination component and
 records graph edges available to Python.
 
 Pass a production item name as the first `target()` argument when a route should
@@ -310,7 +310,7 @@ PRODUCTIONS = [FileProduction()]
 
 `target()` declares the outbound target setting on the Python component class.
 `Route(FileService.Output, ORDER_OPERATION)` wires that setting to a production
-item. This is the class-style equivalent of `prod.connect(file.Output, orders)`.
+item. This is the class-style equivalent of `file.connect(FileService.Output, orders)`.
 
 For Python component classes, prefer the descriptor form
 `Route(FileService.Output, ...)`. For existing IRIS classes, use the IRIS
@@ -617,7 +617,7 @@ feed = (
     .host_setting("Limit", int(os.environ.get("REDDIT_LIMIT", "10")))
 )
 exporter = prod.operation("FileExporter", FileOperation)
-prod.connect(feed.Output, exporter)
+feed.connect(RedditService.Output, exporter)
 
 PRODUCTIONS = [prod]
 ```
diff --git a/pyproject.toml b/pyproject.toml
@@ -53,6 +53,7 @@ exclude = ["tests*"]
 
 [tool.setuptools.package-data]
 "*" = ["*.cls", "cls/**/*.cls"]
+"iop" = ["py.typed"]
 
 [tool.pytest.ini_options]
 asyncio_default_fixture_loop_scope = "class"
diff --git a/src/iop/production/component.py b/src/iop/production/component.py
@@ -168,7 +168,7 @@ def other_setting(
 
     def connect(
         self,
-        target_setting: str | TargetSettingRef,
+        target_setting: str | TargetSetting | TargetSettingRef,
         target_component: ComponentRef | str | None = None,
         **kwargs: Any,
     ) -> ComponentRef:
@@ -178,7 +178,7 @@ def connect(
 
     def _coerce_target_setting_ref(
         self,
-        target_setting: str | TargetSettingRef,
+        target_setting: str | TargetSetting | TargetSettingRef,
     ) -> TargetSettingRef:
         if isinstance(target_setting, TargetSettingRef):
             if target_setting.production is not self.production:
@@ -190,6 +190,28 @@ def _coerce_target_setting_ref(
                     "source target setting belongs to a different component"
                 )
             return target_setting
+        if isinstance(target_setting, TargetSetting):
+            owner = target_setting.owner
+            if owner is None or not target_setting.name:
+                raise ValueError(
+                    "target setting must be declared on a component class"
+                )
+            if self.component_class is None or not issubclass(
+                self.component_class,
+                owner,
+            ):
+                owner_name = f"{owner.__module__}.{owner.__qualname__}"
+                component_name = (
+                    f"{self.component_class.__module__}."
+                    f"{self.component_class.__qualname__}"
+                    if self.component_class is not None
+                    else self.class_name
+                )
+                raise ValueError(
+                    f"target setting {target_setting.name!r} belongs to "
+                    f"{owner_name}, not {component_name}"
+                )
+            return self.target_setting(target_setting.name)
         return self.target_setting(str(target_setting))
 
     def inspect(self, *, refresh: bool = True) -> dict[str, Any]:
diff --git a/src/iop/production/model.py b/src/iop/production/model.py
diff --git a/src/iop/production/rendering.py b/src/iop/production/rendering.py
diff --git a/src/iop/production/types.py b/src/iop/production/types.py
diff --git a/src/iop/production/validation.py b/src/iop/production/validation.py
diff --git a/src/iop/py.typed b/src/iop/py.typed
diff --git a/src/tests/unit/test_production.py b/src/tests/unit/test_production.py
