intersect-sdk 0.8.0__tar.gz → 0.8.2__tar.gz

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: intersect-sdk
-Version: 0.8.0
+Version: 0.8.2
 Summary: Python SDK to interact with INTERSECT
 Keywords: intersect
 Author-Email: Lance Drane <dranelt@ornl.gov>, Marshall McDonnell <mcdonnellmt@ornl.gov>, Seth Hitefield <hitefieldsd@ornl.gov>, Andrew Ayres <ayresaf@ornl.gov>, Gregory Cage <cagege@ornl.gov>, Jesse McGaha <mcgahajr@ornl.gov>, Robert Smith <smithrw@ornl.gov>, Gavin Wiggins <wigginsg@ornl.gov>, Michael Brim <brimmj@ornl.gov>, Rick Archibald <archibaldrk@ornl.gov>, Addi Malviya Thakur <malviyaa@ornl.gov>
@@ -21,13 +21,19 @@ Requires-Dist: paho-mqtt<2.0.0,>=1.6.1
 Requires-Dist: minio>=7.2.3
 Requires-Dist: jsonschema[format-nongpl]>=4.21.1
 Requires-Dist: eval-type-backport>=0.1.3; python_version < "3.10"
+Provides-Extra: amqp
 Requires-Dist: pika<2.0.0,>=1.3.2; extra == "amqp"
+Provides-Extra: docs
 Requires-Dist: sphinx>=5.3.0; extra == "docs"
 Requires-Dist: furo>=2023.3.27; extra == "docs"
-Provides-Extra: amqp
-Provides-Extra: docs
 Description-Content-Type: text/markdown
 
+[![Static Badge](https://img.shields.io/badge/DOI-10.11578%2Fdc.20240927.1-blue)](https://doi.org/10.11578/dc.20240927.1)
+[![CI](https://github.com/INTERSECT-SDK/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/INTERSECT-SDK/python-sdk/actions/workflows/ci.yml)
+[![Release to PyPi](https://github.com/INTERSECT-SDK/python-sdk/actions/workflows/publish.yml/badge.svg)](https://github.com/INTERSECT-SDK/python-sdk/actions/workflows/publish.yml)
+[![PyPI version](https://badge.fury.io/py/intersect-sdk.svg)](https://badge.fury.io/py/intersect-sdk)
+[![ReadTheDocs](https://readthedocs.org/projects/intersect-python-sdk/badge/?version=latest)](https://intersect-python-sdk.readthedocs.io/en/latest/)
+
 # INTERSECT-SDK
 
 The INTERSECT-SDK is a framework for microservices to integrate themselves into the wider Interconnected Science Ecosystem (INTERSECT).
@@ -37,6 +43,8 @@ Please note that this README is currently a work in progress.
 ## What is INTERSECT?
 [INTERSECT](https://www.ornl.gov/intersect) was designed as a specific usecase - as an open federated hardware/software architecture for the laboratory of the future, which connects scientific instruments, robot-controlled laboratories and edge/center computing/data resources to enable autonomous experiments, self-driving laboratories, smart manufacturing, and AI-driven design, discovery and evaluation.
 
+For a high-level overview, please see [the architecture website.](https://intersect-architecture.readthedocs.io/en/latest/)
+
 ## What are the core design philosophies of the SDK?
 
 - Event-driven architecture

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/README.md

@@ -1,3 +1,9 @@
+[![Static Badge](https://img.shields.io/badge/DOI-10.11578%2Fdc.20240927.1-blue)](https://doi.org/10.11578/dc.20240927.1)
+[![CI](https://github.com/INTERSECT-SDK/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/INTERSECT-SDK/python-sdk/actions/workflows/ci.yml)
+[![Release to PyPi](https://github.com/INTERSECT-SDK/python-sdk/actions/workflows/publish.yml/badge.svg)](https://github.com/INTERSECT-SDK/python-sdk/actions/workflows/publish.yml)
+[![PyPI version](https://badge.fury.io/py/intersect-sdk.svg)](https://badge.fury.io/py/intersect-sdk)
+[![ReadTheDocs](https://readthedocs.org/projects/intersect-python-sdk/badge/?version=latest)](https://intersect-python-sdk.readthedocs.io/en/latest/)
+
 # INTERSECT-SDK
 
 The INTERSECT-SDK is a framework for microservices to integrate themselves into the wider Interconnected Science Ecosystem (INTERSECT).
@@ -7,6 +13,8 @@ Please note that this README is currently a work in progress.
 ## What is INTERSECT?
 [INTERSECT](https://www.ornl.gov/intersect) was designed as a specific usecase - as an open federated hardware/software architecture for the laboratory of the future, which connects scientific instruments, robot-controlled laboratories and edge/center computing/data resources to enable autonomous experiments, self-driving laboratories, smart manufacturing, and AI-driven design, discovery and evaluation.
 
+For a high-level overview, please see [the architecture website.](https://intersect-architecture.readthedocs.io/en/latest/)
+
 ## What are the core design philosophies of the SDK?
 
 - Event-driven architecture

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
     "jsonschema[format-nongpl]>=4.21.1",
     "eval-type-backport>=0.1.3;python_version<'3.10'",
 ]
-version = "0.8.0"
+version = "0.8.2"
 
 [project.license]
 text = "BSD-3-Clause"
@@ -55,42 +55,6 @@ docs = [
     "furo>=2023.3.27",
 ]
 
-[tool.pdm.dev-dependencies]
-lint = [
-    "pre-commit>=3.3.1",
-    "ruff==0.5.7",
-    "mypy>=1.10.0",
-    "types-paho-mqtt>=1.6.0.20240106",
-]
-test = [
-    "pytest>=7.3.2",
-    "pytest-cov>=4.1.0",
-    "httpretty>=1.1.4",
-]
-
-[tool.pdm.scripts]
-test-all = "pytest tests/ --cov=src/intersect_sdk/ --cov-fail-under=80 --cov-report=html:reports/htmlcov/ --cov-report=xml:reports/coverage_report.xml --junitxml=reports/junit.xml"
-test-all-debug = "pytest tests/ --cov=src/intersect_sdk/ --cov-fail-under=80 --cov-report=html:reports/htmlcov/ --cov-report=xml:reports/coverage_report.xml --junitxml=reports/junit.xml -s"
-test-unit = "pytest tests/unit --cov=src/intersect_sdk/"
-test-e2e = "pytest tests/e2e --cov=src/intersect_sdk/"
-lint-format = "ruff format"
-lint-ruff = "ruff check --fix"
-lint-mypy = "mypy src/intersect_sdk/"
-
-[tool.pdm.scripts.lint]
-composite = [
-    "lint-format",
-    "lint-ruff",
-    "lint-mypy",
-]
-
-[tool.pdm.build]
-package-dir = "src"
-
-[tool.pdm.version]
-source = "file"
-path = "src/intersect_sdk/version.py"
-
 [tool.ruff]
 line-length = 100
 
@@ -144,8 +108,6 @@ ignore = [
     "COM812",
     "ISC001",
     "SIM105",
-    "ANN101",
-    "ANN102",
     "ANN401",
     "PLR2004",
 ]
@@ -231,6 +193,51 @@ exclude_also = [
     "except.* ImportError",
 ]
 
+[tool.pdm.dev-dependencies]
+lint = [
+    "pre-commit>=3.3.1",
+    "ruff==0.9.4",
+    "mypy>=1.10.0",
+    "types-paho-mqtt>=1.6.0.20240106",
+    "codespell>=2.3.0",
+]
+test = [
+    "pytest>=7.3.2",
+    "pytest-cov>=4.1.0",
+    "httpretty>=1.1.4",
+]
+
+[tool.pdm.scripts]
+test-all = "pytest tests/ --cov=src/intersect_sdk/ --cov-fail-under=80 --cov-report=html:reports/htmlcov/ --cov-report=xml:reports/coverage_report.xml --junitxml=reports/junit.xml"
+test-all-debug = "pytest tests/ --cov=src/intersect_sdk/ --cov-fail-under=80 --cov-report=html:reports/htmlcov/ --cov-report=xml:reports/coverage_report.xml --junitxml=reports/junit.xml -s"
+test-unit = "pytest tests/unit --cov=src/intersect_sdk/"
+test-e2e = "pytest tests/e2e --cov=src/intersect_sdk/"
+lint-docs = "sphinx-build -W --keep-going docs docs/_build"
+lint-format = "ruff format"
+lint-ruff = "ruff check --fix"
+lint-mypy = "mypy src/intersect_sdk/"
+lint-spelling = "codespell -w docs examples src tests *.md -S docs/_build"
+
+[tool.pdm.scripts.lint]
+composite = [
+    "lint-format",
+    "lint-ruff",
+    "lint-mypy",
+    "lint-spelling",
+    "lint-docs",
+]
+
+[tool.pdm.build]
+package-dir = "src"
+
+[tool.pdm.version]
+source = "file"
+path = "src/intersect_sdk/version.py"
+
+[tool.codespell]
+skip = ".git*,*.lock,.venv,.*cache/*,./docs/_build/*"
+check-hidden = true
+
 [build-system]
 requires = [
     "pdm-backend",

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/_internal/control_plane/brokers/amqp_client.py

@@ -254,7 +254,7 @@ class AMQPClient(BrokerClient):
         if self._should_disconnect:
             connection.ioloop.stop()
         else:
-            logger.warn('Connection closed, reopening in 5 seconds: %s', reason)
+            logger.warning('Connection closed, reopening in 5 seconds: %s', reason)
             connection.ioloop.call_later(5, connection.ioloop.stop)
         self._channel_flags.unset_all()
         self._channel_out = None

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/_internal/control_plane/brokers/mqtt_client.py

@@ -113,7 +113,7 @@ class MQTTClient(BrokerClient):
             topic: The topic on which to publish the message as a string.
             payload: The message to publish, as raw bytes.
             persist: Determine if the message should live until queue consumers or available (True), or
-              if it should be removed immediatedly (False)
+              if it should be removed immediately (False)
         """
         # NOTE: RabbitMQ only works with QOS of 1 and 0, and seems to convert QOS2 to QOS1
         self._connection.publish(topic, payload, qos=2 if persist else 0)

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/_internal/data_plane/data_plane_manager.py

@@ -32,7 +32,7 @@ class DataPlaneManager:
 
         # warn users about missing data plane
         if not self._minio_providers:
-            logger.warn('WARNING: This service cannot support any MINIO instances')
+            logger.warning('WARNING: This service cannot support any MINIO instances')
 
     def incoming_message_data_handler(self, message: UserspaceMessage | EventMessage) -> bytes:
         """Get data from the request data provider.

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/_internal/event_metadata.py

@@ -42,7 +42,7 @@ def definition_metadata_differences(
 ) -> list[tuple[str, str, str]]:
     """Return a list of differences between 'definition' and 'metadata'.
 
-    First tuple value = defintion key
+    First tuple value = definition key
     Second tuple value = second value
     Third tuple value = already cached value
     """

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/_internal/interfaces.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
-from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Protocol
 
 if TYPE_CHECKING:
     from uuid import UUID
 
+    from ..client_callback_definitions import INTERSECT_CLIENT_EVENT_CALLBACK_TYPE
+    from ..config.shared import HierarchyConfig
     from ..service_callback_definitions import (
         INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,
     )
@@ -14,13 +15,12 @@ if TYPE_CHECKING:
     )
 
 
-class IntersectEventObserver(ABC):
+class IntersectEventObserver(Protocol):
     """Abstract definition of an entity which observes an INTERSECT event (i.e. IntersectService).
 
     Used as the common interface for event emitters (i.e. CapabilityImplementations).
     """
 
-    @abstractmethod
     def _on_observe_event(self, event_name: str, event_value: Any, operation: str) -> None:
         """How to react to an event being fired.
 
@@ -31,17 +31,16 @@ class IntersectEventObserver(ABC):
         """
         ...
 
-    @abstractmethod
     def create_external_request(
         self,
         request: IntersectDirectMessageParams,
         response_handler: INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None = None,
         timeout: float = 300.0,
     ) -> UUID:
-        """Observed entity (capabilitiy) tells observer (i.e. service) to send an external request.
+        """Observed entity (capability) tells observer (i.e. service) to send an external request.
 
         Params:
-          - request: the request we want to send out, encapsulated as an IntersectClientMessageParams object
+          - request: the request we want to send out, encapsulated as an IntersectDirectMessageParams object
           - response_handler: optional callback for how we want to handle the response from this request.
           - timeout: optional value for how long we should wait on the request, in seconds (default: 300 seconds)
 
@@ -49,3 +48,18 @@ class IntersectEventObserver(ABC):
           - generated RequestID associated with your request
         """
         ...
+
+    def register_event(
+        self,
+        service: HierarchyConfig,
+        event_name: str,
+        response_handler: INTERSECT_CLIENT_EVENT_CALLBACK_TYPE,
+    ) -> None:
+        """Observed entity (capability) tells observer (i.e. service) to subscribe to a specific event.
+
+        Params:
+          - service: HierarchyConfig of the service we want to talk to
+          - event_name: name of event to subscribe to
+          - response_handler: callback for how to handle the reception of an event
+        """
+        ...

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/_internal/messages/userspace.py

@@ -25,13 +25,13 @@ from typing import Any, Union
 from pydantic import AwareDatetime, Field, TypeAdapter
 from typing_extensions import Annotated, TypedDict
 
-from ...constants import SYSTEM_OF_SYSTEM_REGEX  # noqa: TCH001 (this is runtime checked)
-from ...core_definitions import (  # noqa: TCH001 (this is runtime checked)
+from ...constants import SYSTEM_OF_SYSTEM_REGEX
+from ...core_definitions import (
     IntersectDataHandler,
     IntersectMimeType,
 )
 from ...version import version_string
-from ..data_plane.minio_utils import MinioPayload  # noqa: TCH001 (this is runtime checked)
+from ..data_plane.minio_utils import MinioPayload  # noqa: TC001 (this is runtime checked)
 
 
 class UserspaceMessageHeader(TypedDict):

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/_internal/schema.py

@@ -143,9 +143,9 @@ def _get_functions(
         logger.warning(
             f"Class '{capability.__name__}' has no function annotated with the @intersect_status() decorator. No status information will be provided when sending status messages."
         )
-    if not intersect_messages and not intersect_events:
+    if not intersect_messages and not intersect_events and not intersect_status:
         die(
-            f"No intersect annotations detected on class '{capability.__name__}'. Please annotate at least one entrypoint with '@intersect_message()', or one event-emitting function with '@intersect_event()' ."
+            f"No intersect annotations detected on class '{capability.__name__}'. Please annotate at least one entrypoint with '@intersect_message()', or one event-emitting function with '@intersect_event()', or create an '@intersect_status' function."
         )
     return intersect_status, intersect_messages, intersect_events
 
@@ -557,7 +557,7 @@ def get_schema_and_functions_from_capability_implementations(
         if cap_status_fn_name and cap_status_schema and cap_status_type_adapter:
             if status_function_name is not None:
                 # TODO may want to change this later
-                die('Only one capabilitiy may have an @intersect_status function')
+                die('Only one capability may have an @intersect_status function')
             status_function_cap = capability_type
             status_function_name = cap_status_fn_name
             status_function_schema = cap_status_schema

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/app_lifecycle.py

@@ -82,7 +82,7 @@ class SignalHandler:
         ----------
         signal (int): signal code.
         """
-        logger.warning('shutting down and handling signal %d' % signal)
+        logger.warning('shutting down and handling signal %s', signal)
         if self._cleanup_callback:
             self._cleanup_callback(signal)
         self._exit.set()

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/capability/base.py

@@ -14,6 +14,8 @@ if TYPE_CHECKING:
     from uuid import UUID
 
     from .._internal.interfaces import IntersectEventObserver
+    from ..client_callback_definitions import INTERSECT_CLIENT_EVENT_CALLBACK_TYPE
+    from ..config.shared import HierarchyConfig
     from ..service_callback_definitions import (
         INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,
     )
@@ -66,6 +68,8 @@ class IntersectBaseCapabilityImplementation:
             is not IntersectBaseCapabilityImplementation.intersect_sdk_emit_event
             or cls.intersect_sdk_call_service
             is not IntersectBaseCapabilityImplementation.intersect_sdk_call_service
+            or cls.intersect_sdk_listen_for_service_event
+            is not IntersectBaseCapabilityImplementation.intersect_sdk_listen_for_service_event
         ):
             msg = f"{cls.__name__}: Attempted to override a reserved INTERSECT-SDK function (don't start your function names with '_intersect_sdk_' or 'intersect_sdk_')"
             raise RuntimeError(msg)
@@ -137,8 +141,10 @@ class IntersectBaseCapabilityImplementation:
     ) -> list[UUID]:
         """Create an external request that we'll send to a different Service.
 
+        Note: You should generally NOT call this function until after you have initialized the IntersectService class.
+
         Params:
-          - request: the request we want to send out, encapsulated as an IntersectClientMessageParams object
+          - request: the request we want to send out, encapsulated as an IntersectDirectMessageParams object
           - response_handler: optional callback for how we want to handle the response from this request.
           - timeout: optional value for how long we should wait on the request, in seconds (default: 300 seconds)
 
@@ -153,3 +159,27 @@ class IntersectBaseCapabilityImplementation:
             observer.create_external_request(request, response_handler, timeout)
             for observer in self.__intersect_sdk_observers__
         ]
+
+    @final
+    def intersect_sdk_listen_for_service_event(
+        self,
+        service: HierarchyConfig,
+        event_name: str,
+        response_handler: INTERSECT_CLIENT_EVENT_CALLBACK_TYPE,
+    ) -> None:
+        """Start listening to events from a specific Service.
+
+        Note: You should generally NOT call this function until after you have initialized the IntersectService class.
+
+        Params:
+          - service: The system-of-system hierarchy which points to the specific service
+          - event_name: The name of the event we want to listen for
+          - response_handler: callback for how to handle the reception of an event
+            The callback submits these parameters:
+            1) message source
+            2) name of operation
+            3) name of event
+            4) payload
+        """
+        for observer in self.__intersect_sdk_observers__:
+            observer.register_event(service, event_name, response_handler)

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/client.py

@@ -129,7 +129,7 @@ class IntersectClient:
             if user_callback:
                 # Do not persist, as we use the temporary client information to build this.
                 self._control_plane_manager.add_subscription_channel(
-                    f"{self._hierarchy.hierarchy_string('/')}/response",
+                    f'{self._hierarchy.hierarchy_string("/")}/response',
                     {self._handle_userspace_message_raw},
                     persist=False,
                 )
@@ -140,7 +140,7 @@ class IntersectClient:
                     service
                 ) in config.initial_message_event_config.services_to_start_listening_for_events:
                     self._control_plane_manager.add_subscription_channel(
-                        f"{service.replace('.', '/')}/events",
+                        f'{service.replace(".", "/")}/events',
                         {self._handle_event_message_raw},
                         persist=False,
                     )
@@ -390,13 +390,13 @@ class IntersectClient:
         if self._event_callback:
             for add_event in validated_result.services_to_start_listening_for_events:
                 self._control_plane_manager.add_subscription_channel(
-                    f"{add_event.replace('.', '/')}/events",
+                    f'{add_event.replace(".", "/")}/events',
                     {self._handle_event_message_raw},
                     persist=False,
                 )
             for remove_event in validated_result.services_to_stop_listening_for_events:
                 self._control_plane_manager.remove_subscription_channel(
-                    f"{remove_event.replace('.', '/')}/events"
+                    f'{remove_event.replace(".", "/")}/events'
                 )
 
         # sending userspace messages without the callback is okay, we just won't get the response
@@ -431,7 +431,7 @@ class IntersectClient:
             payload=out_payload,
         )
         logger.debug(f'Send userspace message:\n{msg}')
-        channel = f"{params.destination.replace('.', '/')}/request"
+        channel = f'{params.destination.replace(".", "/")}/request'
         # WARNING: If both the Service and the Client drop, the Service will execute the command
         # but cannot communicate the response to the Client.
         # in experiment controllers or production, you'll want to set persist to True

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/config/shared.py

@@ -28,7 +28,7 @@ ControlProvider = Literal['mqtt3.1.1', 'amqp0.9.1']
 
 
 class HierarchyConfig(BaseModel):
-    """Configuration for registring this service in a system-of-system architecture."""
+    """Configuration for registering this service in a system-of-system architecture."""
 
     service: Annotated[str, Field(pattern=HIERARCHY_REGEX)]
     """

{intersect_sdk-0.8.0 → intersect_sdk-0.8.2}/src/intersect_sdk/schema.py

@@ -48,11 +48,11 @@ def get_schema_from_capability_implementations(
 
     The generated schema is currently not a complete replica of the AsyncAPI spec. See https://www.asyncapi.com/docs/reference/specification/v2.6.0 for the complete specification.
     Some key differences:
-      - We utilize three custom fields: "capabilities", "events", and "status".
-      - "capabilities" contains a dictionary: the keys of this dictionary are capability names. The values are dictionaries with the "description" property being a string which describes the capability,
-        and a "channels" property which more closely follows the AsyncAPI specification of the top-level value "channels".
-      - "events" is a key-value dictionary: the keys represent the event name, the values represent the associated schema of the event type. Events are currently shared across all capabilities.
-      - "status" will have a value of the status schema - if no status has been defined, a null schema is used.
+    - We utilize three custom fields: "capabilities", "events", and "status".
+    - "capabilities" contains a dictionary: the keys of this dictionary are capability names. The values are dictionaries with the "description" property being a string which describes the capability,
+    and a "channels" property which more closely follows the AsyncAPI specification of the top-level value "channels".
+    - "events" is a key-value dictionary: the keys represent the event name, the values represent the associated schema of the event type. Events are currently shared across all capabilities.
+    - "status" will have a value of the status schema - if no status has been defined, a null schema is used.
 
     Params:
       - capability_types - list of classes (not objects) of capabilities. We do not require capabilities to be instantiated here, in case the instantiation of a capability has external dependencies.