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

{iris_pex_embedded_python-4.0.0b15/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.0b15
+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.0b15 → 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.0b15 → 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.0b15 → 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.0b15 → 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.0b15 → 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.0b15 → 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.0b15 → 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.0b15 → 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.0b15 → 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.0b15 → 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.0b15 → 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.0b15 → 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.0b15 → 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.0b15"
+version = "4.0.1b1"
 description = "Iris Interoperability based on Embedded Python"
 readme = "README.md"
 requires-python = ">=3.10"

{iris_pex_embedded_python-4.0.0b15 → iris_pex_embedded_python-4.0.1b1}/src/iop/migration/utils.py

@@ -546,7 +546,19 @@ def _build_migration_manifest(
 
 
 def _load_settings(filename):
-    """Load settings module from file or default location.
+    """Load a migration settings module.
+
+    Purpose:
+        Resolve settings.py as a file-based module and keep imports local to the
+        settings file directory for this process.
+
+    Best practices:
+        Keep modules imported by settings.py in the same project/package rooted
+        near the settings file. Let IoP manage temporary import path setup.
+
+    Common mistakes:
+        Do not require users to set PYTHONPATH. Do not mutate environment
+        variables to force imports when module/package layout should be fixed.
 
     Returns:
         tuple: (settings_module, path_added_to_sys)
@@ -723,6 +735,20 @@ def _cleanup_sys_path(path):
 
 
 def import_module_from_path(module_name, file_path):
+    """Import one module from an absolute file path.
+
+    Purpose:
+        Execute a specific settings or component module by file location
+        without relying on global PYTHONPATH configuration.
+
+    Best practices:
+        Use absolute paths and stable module/package layout so imports resolve
+        from the project directory containing settings.py.
+
+    Common mistakes:
+        Do not patch PYTHONPATH or sys.path globally to make imports pass.
+        Keep import fixes in project structure and import statements.
+    """
     if not os.path.isabs(file_path):
         raise ValueError("The file path must be absolute")
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris_pex_embedded_python
-Version: 4.0.0b15
+Version: 4.0.1b1
 Summary: Iris Interoperability based on Embedded Python
 Author-email: grongier <guillaume.rongier@intersystems.com>
 License: MIT License