madsci.node_module 0.7.0rc1__tar.gz → 0.8.0__tar.gz

madsci_node_module-0.7.0rc1/README.md → madsci_node_module-0.8.0/PKG-INFO

@@ -1,3 +1,16 @@
+Metadata-Version: 2.1
+Name: madsci.node_module
+Version: 0.8.0
+Summary: The Modular Autonomous Discovery for Science (MADSci) Node Module Helper Classes.
+Author-Email: Tobias Ginsburg <tginsburg@anl.gov>, "Ryan D. Lewis" <ryan.lewis@anl.gov>, Casey Stone <cstone@anl.gov>, Doga Ozgulbas <dozgulbas@anl.gov>
+License: MIT
+Project-URL: Homepage, https://github.com/AD-SDL/MADSci
+Requires-Python: >=3.10.0
+Requires-Dist: madsci.common
+Requires-Dist: madsci.client
+Requires-Dist: regex
+Description-Content-Type: text/markdown
+
 # MADSci Node Module
 
 Framework for creating laboratory instrument nodes that integrate with MADSci workcells via REST APIs.
@@ -105,8 +118,8 @@ module_version: 1.0.0
 # Run directly
 python my_instrument_node.py
 
-# Or with a pre-defined node
-python my_instrument_node.py --node_definition my_instrument.node.yaml
+# Configuration is provided via environment variables (NODE_NAME, NODE_URL, etc.)
+# or settings files (settings.yaml, .env)
 
 # Node will be available at http://localhost:2000/docs
 ```
@@ -1266,3 +1279,11 @@ def get_multiple_files(self) -> list[Path]:
 ```
 
 **Working examples**: See [example_lab/](../../examples/example_lab/) for a complete working laboratory with multiple integrated nodes.
+
+
+## Development Steps
+In order to ensure a MADSci module is up to standard and will run reliably, developers should:
+1. Document expected behavior for each action exposed by the Node, and then test it on the device to ensure it behaves as documented
+2. Ensure that the module folder contains no extraneous files unused by the code.
+3. Ensure that the code passes automated linting and code quality checks (we use [pre-commit](https://pre-commit.com/) and [ruff](https://astral.sh/ruff), for instance. See [our pre-commit config](../../.pre-commit-config.yaml) and [ruff config](../../ruff.toml).
+4. Where appropriate, write a Docker image for the module and ensure that it builds and runs.

madsci_node_module-0.7.0rc1/PKG-INFO → madsci_node_module-0.8.0/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.1
-Name: madsci.node_module
-Version: 0.7.0rc1
-Summary: The Modular Autonomous Discovery for Science (MADSci) Node Module Helper Classes.
-Author-Email: Tobias Ginsburg <tginsburg@anl.gov>, "Ryan D. Lewis" <ryan.lewis@anl.gov>, Casey Stone <cstone@anl.gov>, Doga Ozgulbas <dozgulbas@anl.gov>
-License: MIT
-Project-URL: Homepage, https://github.com/AD-SDL/MADSci
-Requires-Python: >=3.10.0
-Requires-Dist: madsci.common
-Requires-Dist: madsci.client
-Requires-Dist: regex
-Description-Content-Type: text/markdown
-
 # MADSci Node Module
 
 Framework for creating laboratory instrument nodes that integrate with MADSci workcells via REST APIs.
@@ -118,8 +105,8 @@ module_version: 1.0.0
 # Run directly
 python my_instrument_node.py
 
-# Or with a pre-defined node
-python my_instrument_node.py --node_definition my_instrument.node.yaml
+# Configuration is provided via environment variables (NODE_NAME, NODE_URL, etc.)
+# or settings files (settings.yaml, .env)
 
 # Node will be available at http://localhost:2000/docs
 ```
@@ -1279,3 +1266,11 @@ def get_multiple_files(self) -> list[Path]:
 ```
 
 **Working examples**: See [example_lab/](../../examples/example_lab/) for a complete working laboratory with multiple integrated nodes.
+
+
+## Development Steps
+In order to ensure a MADSci module is up to standard and will run reliably, developers should:
+1. Document expected behavior for each action exposed by the Node, and then test it on the device to ensure it behaves as documented
+2. Ensure that the module folder contains no extraneous files unused by the code.
+3. Ensure that the code passes automated linting and code quality checks (we use [pre-commit](https://pre-commit.com/) and [ruff](https://astral.sh/ruff), for instance. See [our pre-commit config](../../.pre-commit-config.yaml) and [ruff config](../../ruff.toml).
+4. Where appropriate, write a Docker image for the module and ensure that it builds and runs.

{madsci_node_module-0.7.0rc1 → madsci_node_module-0.8.0}/madsci/node_module/abstract_node_module.py

@@ -1,8 +1,11 @@
 """Base Node Module helper classes."""
 
+import atexit
 import contextlib
 import inspect
+import logging
 import threading
+import weakref
 from pathlib import Path
 from typing import (
     Annotated,
@@ -39,15 +42,20 @@ from madsci.common.types.action_types import (
     LocationArgumentDefinition,
 )
 from madsci.common.types.admin_command_types import AdminCommandResponse
+from madsci.common.types.auth_types import OwnershipInfo
 from madsci.common.types.base_types import Error
 from madsci.common.types.datapoint_types import DataPoint, FileDataPoint, ValueDataPoint
 from madsci.common.types.event_types import Event, EventType
+from madsci.common.types.location_types import LocationManagement
 from madsci.common.types.node_types import (
     AdminCommands,
     NodeCapabilities,
     NodeClientCapabilities,
     NodeConfig,
     NodeInfo,
+    NodeIntrinsicLocationDefinition,
+    NodeRepresentationTemplateDefinition,
+    NodeResourceTemplateDefinition,
     NodeSetConfigResponse,
     NodeStatus,
 )
@@ -96,6 +104,17 @@ class AbstractNode(MadsciClientMixin):
     _action_lock: ClassVar[threading.Lock] = threading.Lock()
     """Ensures only one blocking action can run at a time."""
 
+    resource_templates: ClassVar[list[NodeResourceTemplateDefinition]] = []
+    """Declarative resource template definitions to register on startup."""
+
+    location_representation_templates: ClassVar[
+        list[NodeRepresentationTemplateDefinition]
+    ] = []
+    """Declarative location representation template definitions to register on startup."""
+
+    intrinsic_locations: ClassVar[list[NodeIntrinsicLocationDefinition]] = []
+    """Intrinsic location definitions to register on startup."""
+
     def __init__(
         self,
         node_config: Optional[NodeConfig] = None,
@@ -115,6 +134,18 @@ class AbstractNode(MadsciClientMixin):
             module_name=module_name,
         )
 
+        # * Populate intrinsic location definitions from class variables
+        self.node_info.intrinsic_locations = list(self.__class__.intrinsic_locations)
+        self.node_info.location_representation_templates = list(
+            self.__class__.location_representation_templates
+        )
+
+        # Resolve stable identity from registry if enabled
+        self._resolver = None
+        self._atexit_registered = False
+        if self.config.enable_registry_resolution:
+            self._resolve_identity_from_registry()
+
         global_ownership_info.node_id = self.node_info.node_id
         self._configure_clients()
 
@@ -136,6 +167,23 @@ class AbstractNode(MadsciClientMixin):
     """Node Lifecycle and Public Methods"""
     """------------------------------------------------------------------------------------------------"""
 
+    def close(self) -> None:
+        """Release registry identity and clean up client resources.
+
+        This method is idempotent and safe to call multiple times.
+        Call this before reassigning a node variable to a new node
+        with the same name (e.g. in notebook cells) to avoid
+        ``RegistryLockError`` from lingering heartbeat threads.
+        """
+        self._release_registry_identity()
+        self._resolver = None
+        self.teardown_clients()
+
+    def __del__(self) -> None:
+        """Best-effort cleanup when the node is garbage-collected."""
+        with contextlib.suppress(Exception):
+            self.close()
+
     def start_node(self) -> None:
         """
         Called once to start the node.
@@ -164,12 +212,183 @@ class AbstractNode(MadsciClientMixin):
     def state_handler(self) -> None:
         """Called periodically to update the node state. Should set `self.node_state`"""
 
+    def template_handler(self) -> None:
+        """Register declarative templates with the resource and location managers.
+
+        Iterates over ``resource_templates`` and ``location_representation_templates``
+        class members. Each template is registered via the appropriate client API.
+        Errors are caught and logged per-template (with the template name and type
+        clearly identified) so that a single failed registration does not prevent the
+        node from starting.
+        """
+        # 1. Resource templates (via resource_client.init_template)
+        for defn in self.resource_templates:
+            try:
+                self.resource_client.init_template(
+                    resource=defn.resource,
+                    template_name=defn.template_name,
+                    description=defn.description,
+                    required_overrides=defn.required_overrides,
+                    tags=defn.tags,
+                    created_by=self.node_info.node_id,
+                    version=defn.version,
+                )
+                self.logger.info(
+                    "Registered resource template",
+                    event_type=EventType.LOG_INFO,
+                    template_name=defn.template_name,
+                    template_type="resource",
+                )
+            except Exception as e:
+                self.logger.warning(
+                    "Failed to register resource template",
+                    event_type=EventType.LOG_WARNING,
+                    template_name=defn.template_name,
+                    template_type="resource",
+                    error=str(e),
+                )
+
+        # 2. Location representation templates (via location_client.init_representation_template)
+        for defn in self.location_representation_templates:
+            try:
+                self.location_client.init_representation_template(
+                    template_name=defn.template_name,
+                    default_values=defn.default_values,
+                    schema_def=defn.schema_def,
+                    required_overrides=defn.required_overrides,
+                    tags=defn.tags,
+                    created_by=self.node_info.node_id,
+                    version=defn.version,
+                    description=defn.description,
+                )
+                self.logger.info(
+                    "Registered location representation template",
+                    event_type=EventType.LOG_INFO,
+                    template_name=defn.template_name,
+                    template_type="location_representation",
+                )
+            except Exception as e:
+                self.logger.warning(
+                    "Failed to register location representation template",
+                    event_type=EventType.LOG_WARNING,
+                    template_name=defn.template_name,
+                    template_type="location_representation",
+                    error=str(e),
+                )
+
+    def intrinsic_location_handler(self) -> None:
+        """Register intrinsic locations with the Location Manager.
+
+        Iterates over ``intrinsic_locations`` class variable. Each location is
+        registered via location_client.init_location() with automatic
+        '{node_name}.' prefix. Errors are caught per-location so a single
+        failure does not prevent the node from starting.
+        """
+        for defn in self.intrinsic_locations:
+            try:
+                location_name = f"{self.node_info.node_name}.{defn.location_name}"
+                representations = {
+                    self.node_info.node_name: defn.representation_overrides
+                }
+                owner = OwnershipInfo(node_id=self.node_info.node_id)
+
+                self.location_client.init_location(
+                    location_name=location_name,
+                    representations=representations,
+                    resource_template_name=defn.resource_template_name,
+                    resource_template_overrides=defn.resource_template_overrides,
+                    description=defn.description,
+                    allow_transfers=defn.allow_transfers,
+                    managed_by=LocationManagement.NODE,
+                    owner=owner,
+                )
+                self.logger.info(
+                    "Registered intrinsic location",
+                    event_type=EventType.LOG_INFO,
+                    location_name=location_name,
+                )
+            except Exception as e:
+                self.logger.warning(
+                    "Failed to register intrinsic location",
+                    event_type=EventType.LOG_WARNING,
+                    location_name=defn.location_name,
+                    error=str(e),
+                )
+
     def startup_handler(self) -> None:
         """Called to (re)initialize the node. Should be used to open connections to devices or initialize any other resources."""
 
     def shutdown_handler(self) -> None:
         """Called to shut down the node. Should be used to clean up any resources."""
 
+    def _resolve_identity_from_registry(self) -> None:
+        """Resolve node identity from the ID Registry.
+
+        Uses IdentityResolver to look up or create a stable ID for this
+        node.  The resolved ID is written back to ``self.node_info.node_id``.
+
+        A ``RegistryLockError`` (after retry exhaustion) is fatal — the
+        node cannot start without a stable identity.  Other errors
+        (e.g. missing registry file) are non-fatal: a warning is logged
+        and the generated ID is kept.
+        """
+        from madsci.common.registry.identity_resolver import (  # noqa: PLC0415
+            IdentityResolver,
+        )
+        from madsci.common.registry.lock_manager import (  # noqa: PLC0415
+            RegistryLockError,
+        )
+
+        try:
+            self._resolver = IdentityResolver(lab_url=self.config.lab_url)
+
+            node_name = self.node_info.node_name
+
+            result = self._resolver.resolve_with_info(
+                name=node_name,
+                component_type="node",
+                metadata={"module_name": self.node_info.module_name},
+                retry_timeout=self.config.registry_lock_timeout,
+            )
+
+            self.node_info.node_id = result.id
+
+            if not self._atexit_registered:
+                ref = weakref.ref(self)
+
+                def _release_on_exit(weak_ref: weakref.ref = ref) -> None:
+                    obj = weak_ref()
+                    if obj is not None:
+                        obj._release_registry_identity()
+
+                atexit.register(_release_on_exit)
+                self._atexit_registered = True
+
+        except RegistryLockError:
+            raise
+        except Exception:
+            logging.getLogger(__name__).warning(
+                "Registry identity resolution failed; using generated ID",
+                exc_info=True,
+            )
+
+    def _release_registry_identity(self) -> None:
+        """Release the registry lock for this node's identity.
+
+        Called via ``atexit`` to allow other instances to acquire the
+        same name.
+        """
+        if self._resolver is None:
+            return
+
+        try:
+            self._resolver.release(self.node_info.node_name)
+        except Exception:
+            logging.getLogger(__name__).warning(
+                "Failed to release registry identity",
+                exc_info=True,
+            )
+
     """------------------------------------------------------------------------------------------------"""
     """Interface Methods"""
     """------------------------------------------------------------------------------------------------"""
@@ -1254,6 +1473,8 @@ class AbstractNode(MadsciClientMixin):
             self.node_status.locked = False
             self.node_status.paused = False
             self.node_status.stopped = False
+            self.template_handler()
+            self.intrinsic_location_handler()
             self.startup_handler()
             # * Start status and state update loops
             repeat_on_interval(

{madsci_node_module-0.7.0rc1 → madsci_node_module-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "madsci.node_module"
-version = "0.7.0-rc.1"
+version = "0.8.0"
 description = "The Modular Autonomous Discovery for Science (MADSci) Node Module Helper Classes."
 authors = [
     { name = "Tobias Ginsburg", email = "tginsburg@anl.gov" },

{madsci_node_module-0.7.0rc1 → madsci_node_module-0.8.0}/tests/conftest.py

@@ -117,10 +117,13 @@ def test_node_factory() -> Generator[Callable[..., TestNode], None, None]:
             Configured TestNode instance
         """
         # Create base config with identity fields
+        # Disable registry resolution by default in tests to prevent
+        # lock contention and side effects from shared registry files.
         config_params = {
             "test_required_param": 1,
             "node_name": node_name,
             "module_name": module_name,
+            "enable_registry_resolution": False,
             **config_kwargs,
         }
         if config_overrides:

{madsci_node_module-0.7.0rc1 → madsci_node_module-0.8.0}/tests/test_argument_parsing.py

@@ -30,7 +30,7 @@ class TestArgumentParsingNode(RestNode):
     """Test node for argument parsing tests."""
 
     __test__ = False
-    config: TestConfig = TestConfig()
+    config: TestConfig = TestConfig(enable_registry_resolution=False)
     config_model = TestConfig
 
     def startup_handler(self) -> None: