ni.measurementlink.sessionmanagement.v1.client 0.1.0.dev0__py3-none-any.whl

ni/measurementlink/sessionmanagement/v1/client/__init__.py

@@ -0,0 +1,107 @@
+"""Public API for accessing the measurement plug-in management service."""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+from deprecation import DeprecatedWarning
+
+from ni.measurementlink.sessionmanagement.v1.client._client import (
+    SessionManagementClient,
+)
+from ni.measurementlink.sessionmanagement.v1.client._constants import (
+    GRPC_SERVICE_CLASS,
+    GRPC_SERVICE_INTERFACE_NAME,
+    INSTRUMENT_TYPE_NI_DAQMX,
+    INSTRUMENT_TYPE_NI_DCPOWER,
+    INSTRUMENT_TYPE_NI_DIGITAL_PATTERN,
+    INSTRUMENT_TYPE_NI_DMM,
+    INSTRUMENT_TYPE_NI_FGEN,
+    INSTRUMENT_TYPE_NI_HSDIO,
+    INSTRUMENT_TYPE_NI_MODEL_BASED_INSTRUMENT,
+    INSTRUMENT_TYPE_NI_RELAY_DRIVER,
+    INSTRUMENT_TYPE_NI_RFMX,
+    INSTRUMENT_TYPE_NI_RFPM,
+    INSTRUMENT_TYPE_NI_RFSA,
+    INSTRUMENT_TYPE_NI_RFSG,
+    INSTRUMENT_TYPE_NI_SCOPE,
+    INSTRUMENT_TYPE_NI_SWITCH_EXECUTIVE_VIRTUAL_DEVICE,
+    INSTRUMENT_TYPE_NONE,
+    SITE_SYSTEM_PINS,
+)
+from ni.measurementlink.sessionmanagement.v1.client._reservation import (
+    BaseReservation,
+    MultiplexerSessionContainer,
+    MultiSessionReservation,
+    SingleSessionReservation,
+)
+from ni.measurementlink.sessionmanagement.v1.client._types import (
+    ChannelMapping,
+    Connection,
+    MultiplexerSessionInformation,
+    PinMapContext,
+    SessionInformation,
+    SessionInitializationBehavior,
+    TypedConnection,
+    TypedConnectionWithMultiplexer,
+    TypedMultiplexerSessionInformation,
+    TypedSessionInformation,
+)
+
+__all__ = [
+    "BaseReservation",
+    "ChannelMapping",
+    "Client",
+    "Connection",
+    "GRPC_SERVICE_CLASS",
+    "GRPC_SERVICE_INTERFACE_NAME",
+    "INSTRUMENT_TYPE_NI_DAQMX",
+    "INSTRUMENT_TYPE_NI_DCPOWER",
+    "INSTRUMENT_TYPE_NI_DIGITAL_PATTERN",
+    "INSTRUMENT_TYPE_NI_DMM",
+    "INSTRUMENT_TYPE_NI_FGEN",
+    "INSTRUMENT_TYPE_NI_HSDIO",
+    "INSTRUMENT_TYPE_NI_MODEL_BASED_INSTRUMENT",
+    "INSTRUMENT_TYPE_NI_RELAY_DRIVER",
+    "INSTRUMENT_TYPE_NI_RFMX",
+    "INSTRUMENT_TYPE_NI_RFPM",
+    "INSTRUMENT_TYPE_NI_RFSA",
+    "INSTRUMENT_TYPE_NI_RFSG",
+    "INSTRUMENT_TYPE_NI_SCOPE",
+    "INSTRUMENT_TYPE_NI_SWITCH_EXECUTIVE_VIRTUAL_DEVICE",
+    "INSTRUMENT_TYPE_NONE",
+    "MultiSessionReservation",
+    "PinMapContext",
+    "MultiplexerSessionContainer",
+    "MultiplexerSessionInformation",
+    "SessionInformation",
+    "SessionInitializationBehavior",
+    "SessionManagementClient",
+    "SingleSessionReservation",
+    "SITE_SYSTEM_PINS",
+    "TypedConnection",
+    "TypedConnectionWithMultiplexer",
+    "TypedMultiplexerSessionInformation",
+    "TypedSessionInformation",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "Reservation":
+        warnings.warn(
+            DeprecatedWarning(
+                name,
+                deprecated_in="1.1.0",
+                removed_in=None,
+                details="Use MultiSessionReservation instead.",
+            ),
+            stacklevel=2,
+        )
+        return MultiSessionReservation
+    else:
+        raise AttributeError(f"module {__name__} has no attribute {name}")
+
+
+Client = SessionManagementClient
+"""Alias for compatibility with code that uses session_management.Client."""

ni/measurementlink/sessionmanagement/v1/client/_client.py

@@ -0,0 +1,405 @@
+"""Session management client class."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import warnings
+from collections.abc import Iterable, Mapping
+
+import google.protobuf.internal.containers
+import grpc
+import ni.measurementlink.sessionmanagement.v1.session_management_service_pb2 as session_management_service_pb2
+import ni.measurementlink.sessionmanagement.v1.session_management_service_pb2_grpc as session_management_service_pb2_grpc
+from ni.measurementlink.discovery.v1.client import DiscoveryClient
+from ni_grpc_extensions.channelpool import GrpcChannelPool
+
+from ni.measurementlink.sessionmanagement.v1.client._constants import (
+    GRPC_SERVICE_CLASS,
+    GRPC_SERVICE_INTERFACE_NAME,
+)
+from ni.measurementlink.sessionmanagement.v1.client._reservation import (
+    MultiplexerSessionContainer,
+    MultiSessionReservation,
+    SingleSessionReservation,
+)
+from ni.measurementlink.sessionmanagement.v1.client._types import (
+    MultiplexerSessionInformation,
+    PinMapContext,
+    SessionInformation,
+)
+
+_logger = logging.getLogger(__name__)
+
+
+class SessionManagementClient:
+    """Client for accessing the measurement plug-in session management service."""
+
+    def __init__(
+        self,
+        *,
+        discovery_client: DiscoveryClient | None = None,
+        grpc_channel: grpc.Channel | None = None,
+        grpc_channel_pool: GrpcChannelPool | None = None,
+    ) -> None:
+        """Initialize session management client.
+
+        Args:
+            discovery_client: An optional discovery client (recommended).
+
+            grpc_channel: An optional session management gRPC channel.
+
+            grpc_channel_pool: An optional gRPC channel pool (recommended).
+        """
+        self._initialization_lock = threading.Lock()
+        self._discovery_client = discovery_client
+        self._grpc_channel_pool = grpc_channel_pool
+        self._stub: session_management_service_pb2_grpc.SessionManagementServiceStub | None = None
+
+        if grpc_channel is not None:
+            self._stub = session_management_service_pb2_grpc.SessionManagementServiceStub(
+                grpc_channel
+            )
+
+    def _get_stub(self) -> session_management_service_pb2_grpc.SessionManagementServiceStub:
+        if self._stub is None:
+            with self._initialization_lock:
+                if self._grpc_channel_pool is None:
+                    _logger.debug("Creating unshared GrpcChannelPool.")
+                    self._grpc_channel_pool = GrpcChannelPool()
+                if self._discovery_client is None:
+                    _logger.debug("Creating unshared DiscoveryClient.")
+                    self._discovery_client = DiscoveryClient(
+                        grpc_channel_pool=self._grpc_channel_pool
+                    )
+                if self._stub is None:
+                    compute_nodes = self._discovery_client.enumerate_compute_nodes()
+                    remote_compute_nodes = [node for node in compute_nodes if not node.is_local]
+                    # Use remote node URL as deployment target if only one remote node is found.
+                    # If more than one remote node exists, use empty string for deployment target.
+                    first_remote_node_url = (
+                        remote_compute_nodes[0].url if len(remote_compute_nodes) == 1 else ""
+                    )
+                    service_location = self._discovery_client.resolve_service(
+                        provided_interface=GRPC_SERVICE_INTERFACE_NAME,
+                        deployment_target=first_remote_node_url,
+                        service_class=GRPC_SERVICE_CLASS,
+                    )
+                    channel = self._grpc_channel_pool.get_channel(service_location.insecure_address)
+                    self._stub = session_management_service_pb2_grpc.SessionManagementServiceStub(
+                        channel
+                    )
+        return self._stub
+
+    def reserve_session(
+        self,
+        context: PinMapContext,
+        pin_or_relay_names: str | Iterable[str] | None = None,
+        instrument_type_id: str | None = None,
+        timeout: float | None = 0.0,
+    ) -> SingleSessionReservation:
+        """Reserve a single session.
+
+        Reserve the session matching the given pins, sites, and instrument type ID and return the
+        information needed to create or access the session.
+
+        Args:
+            context: Includes the pin map ID for the pin map in the Pin Map Service,
+                as well as the list of sites for the measurement.
+
+            pin_or_relay_names: One or multiple pins, pin groups, relays, or relay groups to use
+                for the measurement.
+
+                If unspecified, reserve sessions for all pins and relays in the registered pin map
+                resource.
+
+            instrument_type_id: Instrument type ID for the measurement.
+
+                If unspecified, this method reserve sessions for all instrument types connected
+                in the registered pin map resource.
+
+                For NI instruments, use instrument type id constants, such as
+                :py:const:`INSTRUMENT_TYPE_NI_DCPOWER` or :py:const:`INSTRUMENT_TYPE_NI_DMM`.
+
+                For custom instruments, use the instrument type id defined in the pin map file.
+
+            timeout: Timeout in seconds.
+
+                Allowed values: 0 (non-blocking, fails immediately if resources cannot be
+                reserved), -1 (infinite timeout), or any other positive numeric value (wait for
+                that number of seconds)
+
+        Returns:
+            A reservation object with which you can query information about the session and
+            unreserve it.
+        """
+        response = self._reserve_sessions(context, pin_or_relay_names, instrument_type_id, timeout)
+        if len(response.sessions) == 0:
+            raise ValueError("No sessions reserved. Expected single session, got 0 sessions.")
+        elif len(response.sessions) > 1:
+            self._unreserve_sessions(response.sessions)
+            raise ValueError(
+                "Too many sessions reserved. Expected single session, got "
+                f"{len(response.sessions)} sessions."
+            )
+        else:
+            return SingleSessionReservation(
+                session_management_client=self,
+                session_info=response.sessions,
+                multiplexer_session_info=response.multiplexer_sessions,
+                pin_or_relay_group_mappings=_to_group_mappings_dict(response.group_mappings),
+                reserved_pin_or_relay_names=pin_or_relay_names,
+                reserved_sites=context.sites,
+            )
+
+    def reserve_sessions(
+        self,
+        context: PinMapContext,
+        pin_or_relay_names: str | Iterable[str] | None = None,
+        instrument_type_id: str | None = None,
+        timeout: float | None = 0.0,
+    ) -> MultiSessionReservation:
+        """Reserve multiple sessions.
+
+        Reserve sessions matching the given pins, sites, and instrument type ID and return the
+        information needed to create or access the sessions.
+
+        Args:
+            context: Includes the pin map ID for the pin map in the Pin Map Service,
+                as well as the list of sites for the measurement.
+
+            pin_or_relay_names: One or multiple pins, pin groups, relays, or relay groups to use
+                for the measurement.
+
+                If unspecified, reserve sessions for all pins and relays in the registered pin map
+                resource.
+
+            instrument_type_id: Instrument type ID for the measurement.
+
+                If unspecified, this method reserves sessions for all instrument types connected
+                in the registered pin map resource.
+
+                For NI instruments, use instrument type id constants, such as
+                :py:const:`INSTRUMENT_TYPE_NI_DCPOWER` or :py:const:`INSTRUMENT_TYPE_NI_DMM`.
+
+                For custom instruments, use the instrument type id defined in the pin map file.
+
+            timeout: Timeout in seconds.
+
+                Allowed values: 0 (non-blocking, fails immediately if resources cannot be
+                reserved), -1 (infinite timeout), or any other positive numeric value (wait for
+                that number of seconds)
+
+        Returns:
+            A reservation object with which you can query information about the sessions and
+            unreserve them.
+        """
+        response = self._reserve_sessions(context, pin_or_relay_names, instrument_type_id, timeout)
+        return MultiSessionReservation(
+            session_management_client=self,
+            session_info=response.sessions,
+            multiplexer_session_info=response.multiplexer_sessions,
+            pin_or_relay_group_mappings=_to_group_mappings_dict(response.group_mappings),
+            reserved_pin_or_relay_names=pin_or_relay_names,
+            reserved_sites=context.sites,
+        )
+
+    def _reserve_sessions(
+        self,
+        context: PinMapContext,
+        pin_or_relay_names: str | Iterable[str] | None = None,
+        instrument_type_id: str | None = None,
+        timeout: float | None = 0.0,
+    ) -> session_management_service_pb2.ReserveSessionsResponse:
+        request = session_management_service_pb2.ReserveSessionsRequest(
+            pin_map_context=context._to_grpc(),
+            timeout_in_milliseconds=_timeout_to_milliseconds(timeout),
+        )
+        if instrument_type_id is not None:
+            request.instrument_type_id = instrument_type_id
+        if isinstance(pin_or_relay_names, str):
+            request.pin_or_relay_names.append(pin_or_relay_names)
+        elif pin_or_relay_names is not None:
+            request.pin_or_relay_names.extend(pin_or_relay_names)
+
+        return self._get_stub().ReserveSessions(request)
+
+    def _unreserve_sessions(
+        self, session_info: Iterable[session_management_service_pb2.SessionInformation]
+    ) -> None:
+        """Unreserves sessions so they can be accessed by other clients."""
+        request = session_management_service_pb2.UnreserveSessionsRequest(sessions=session_info)
+        self._get_stub().UnreserveSessions(request)
+
+    def register_sessions(self, session_info: Iterable[SessionInformation]) -> None:
+        """Register sessions with the session management service.
+
+        Indicates that the sessions are open and will need to be closed later.
+
+        Args:
+            session_info: Sessions to register.
+        """
+        request = session_management_service_pb2.RegisterSessionsRequest(
+            sessions=(info._to_grpc_v1() for info in session_info),
+        )
+        self._get_stub().RegisterSessions(request)
+
+    def unregister_sessions(self, session_info: Iterable[SessionInformation]) -> None:
+        """Unregisters sessions from the session management service.
+
+        Indicates that the sessions have been closed and will need to be reopened before they can be
+        used again.
+
+        Args:
+            session_info: Sessions to unregister.
+        """
+        request = session_management_service_pb2.UnregisterSessionsRequest(
+            sessions=(info._to_grpc_v1() for info in session_info),
+        )
+        self._get_stub().UnregisterSessions(request)
+
+    def reserve_all_registered_sessions(
+        self, instrument_type_id: str | None = None, timeout: float | None = 10.0
+    ) -> MultiSessionReservation:
+        """Reserve all sessions currently registered with the session management service.
+
+        Args:
+            instrument_type_id: Instrument type ID for the measurement.
+
+                If unspecified, reserve sessions for all instrument types connected in the
+                registered pin map resource.
+
+                For NI instruments, use instrument type id constants, such as
+                :py:const:`INSTRUMENT_TYPE_NI_DCPOWER` or :py:const:`INSTRUMENT_TYPE_NI_DMM`.
+
+                For custom instruments, use the instrument type id defined in the pin map file.
+
+            timeout: Timeout in seconds.
+
+                An arbitrary timeout to wait for the measurement to complete or be canceled.
+
+                Allowed values: 0 (non-blocking, fails immediately if resources cannot be
+                reserved), -1 (infinite timeout), or any other positive numeric value (wait for
+                that number of seconds)
+
+        Returns:
+            A reservation object with which you can query information about the sessions and
+            unreserve them.
+        """
+        request = session_management_service_pb2.ReserveAllRegisteredSessionsRequest(
+            timeout_in_milliseconds=_timeout_to_milliseconds(timeout)
+        )
+        if instrument_type_id is not None:
+            request.instrument_type_id = instrument_type_id
+
+        response = self._get_stub().ReserveAllRegisteredSessions(request)
+        return MultiSessionReservation(
+            session_management_client=self, session_info=response.sessions
+        )
+
+    def register_multiplexer_sessions(
+        self, multiplexer_session_info: Iterable[MultiplexerSessionInformation]
+    ) -> None:
+        """Register multiplexer sessions with the session management service.
+
+        Indicates that the sessions are open and will need to be closed later.
+
+        Args:
+            multiplexer_session_info: Sessions to register.
+        """
+        request = session_management_service_pb2.RegisterMultiplexerSessionsRequest(
+            multiplexer_sessions=(info._to_grpc_v1() for info in multiplexer_session_info),
+        )
+        self._get_stub().RegisterMultiplexerSessions(request)
+
+    def unregister_multiplexer_sessions(
+        self, multiplexer_session_info: Iterable[MultiplexerSessionInformation]
+    ) -> None:
+        """Unregisters multiplexer sessions from the session management service.
+
+        Indicates that the sessions have been closed and will need to be reopened before they can be
+        used again.
+
+        Args:
+            multiplexer_session_info: Sessions to unregister.
+        """
+        request = session_management_service_pb2.UnregisterMultiplexerSessionsRequest(
+            multiplexer_sessions=(info._to_grpc_v1() for info in multiplexer_session_info),
+        )
+        self._get_stub().UnregisterMultiplexerSessions(request)
+
+    def get_multiplexer_sessions(
+        self, pin_map_context: PinMapContext, multiplexer_type_id: str | None = None
+    ) -> MultiplexerSessionContainer:
+        """Get all multiplexer session infos matching the specified criteria.
+
+        Returns the information needed to create or access the multiplexer sessions
+        without reserving the connected instruments.
+
+        Args:
+            pin_map_context: Includes the pin map ID for the pin map in the pin map service,
+                as well as the list of sites for the measurement.
+
+            multiplexer_type_id: User-defined identifier for the multiplexer
+                type in the pin map editor. If not specified, the multiplexer
+                type id is ignored when matching multiplexer sessions.
+
+        Returns:
+            The multiplexer session container with the matching session infos.
+        """
+        request = session_management_service_pb2.GetMultiplexerSessionsRequest(
+            pin_map_context=pin_map_context._to_grpc()
+        )
+        if multiplexer_type_id is not None:
+            request.multiplexer_type_id = multiplexer_type_id
+
+        response = self._get_stub().GetMultiplexerSessions(request)
+        session_infos = [session for session in response.multiplexer_sessions]
+        return MultiplexerSessionContainer(self, session_infos)
+
+    def get_all_registered_multiplexer_sessions(
+        self, multiplexer_type_id: str | None = None
+    ) -> MultiplexerSessionContainer:
+        """Get all multiplexer session infos registered with the session management service.
+
+        Args:
+            multiplexer_type_id: User-defined identifier for the multiplexer
+                type in the pin map editor. If not specified, the multiplexer
+                type id is ignored when matching multiplexer sessions.
+
+        Returns:
+            The multiplexer session container with the matching session infos registered
+            with the session management service.
+        """
+        request = session_management_service_pb2.GetAllRegisteredMultiplexerSessionsRequest()
+        if multiplexer_type_id is not None:
+            request.multiplexer_type_id = multiplexer_type_id
+
+        response = self._get_stub().GetAllRegisteredMultiplexerSessions(request)
+        session_infos = [session for session in response.multiplexer_sessions]
+        return MultiplexerSessionContainer(self, session_infos)
+
+
+def _timeout_to_milliseconds(timeout: float | None) -> int:
+    if timeout is None:
+        return 0
+    elif timeout == -1:
+        return -1
+    elif timeout < 0:
+        warnings.warn("Specify -1 for an infinite timeout.", RuntimeWarning)
+        return -1
+    else:
+        return round(timeout * 1000)
+
+
+def _to_group_mappings_dict(
+    mappings: google.protobuf.internal.containers.MessageMap[
+        str, session_management_service_pb2.ResolvedPinsOrRelays
+    ],
+) -> Mapping[str, Iterable[str]]:
+    group_mappings: dict[str, Iterable[str]] = {}
+    if mappings is not None:
+        for key, value in mappings.items():
+            group_mappings[key] = value.pin_or_relay_names
+
+    return group_mappings

ni/measurementlink/sessionmanagement/v1/client/_constants.py

@@ -0,0 +1,32 @@
+"""Session management constants."""
+
+GRPC_SERVICE_INTERFACE_NAME = "ni.measurementlink.sessionmanagement.v1.SessionManagementService"
+GRPC_SERVICE_CLASS = "ni.measurementlink.sessionmanagement.v1.SessionManagementService"
+
+
+# Constants for instrument_type_id parameters
+INSTRUMENT_TYPE_NONE = ""
+INSTRUMENT_TYPE_NI_DCPOWER = "niDCPower"
+INSTRUMENT_TYPE_NI_HSDIO = "niHSDIO"
+INSTRUMENT_TYPE_NI_RFSA = "niRFSA"
+INSTRUMENT_TYPE_NI_RFMX = "niRFmx"
+INSTRUMENT_TYPE_NI_RFSG = "niRFSG"
+INSTRUMENT_TYPE_NI_RFPM = "niRFPM"
+INSTRUMENT_TYPE_NI_DMM = "niDMM"
+INSTRUMENT_TYPE_NI_DIGITAL_PATTERN = "niDigitalPattern"
+INSTRUMENT_TYPE_NI_SCOPE = "niScope"
+INSTRUMENT_TYPE_NI_FGEN = "niFGen"
+INSTRUMENT_TYPE_NI_DAQMX = "niDAQmx"
+INSTRUMENT_TYPE_NI_RELAY_DRIVER = "niRelayDriver"
+INSTRUMENT_TYPE_NI_MODEL_BASED_INSTRUMENT = "niModelBasedInstrument"
+INSTRUMENT_TYPE_NI_SWITCH_EXECUTIVE_VIRTUAL_DEVICE = "niSwitchExecutiveVirtualDevice"
+
+SITE_SYSTEM_PINS = -1
+"""Site number used to identify and filter by system pins.
+
+Pins that have a site number of ``SITE_SYSTEM_PINS`` are system pins and do not
+belong to a specific site.
+
+When querying connections, you can specify a site number of ``SITE_SYSTEM_PINS``
+to restrict the query to return only system pins.
+"""

ni/measurementlink/sessionmanagement/v1/client/_drivers/__init__.py

@@ -0,0 +1,46 @@
+"""Shared code for interfacing with driver APIs."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import ContextManager, TypeVar
+
+from ni.measurementlink.sessionmanagement.v1.client._types import (
+    SessionInitializationBehavior,
+)
+
+TSession = TypeVar("TSession")
+
+_EXISTING_BEHAVIORS = [
+    SessionInitializationBehavior.AUTO,
+    SessionInitializationBehavior.ATTACH_TO_SERVER_SESSION,
+    SessionInitializationBehavior.INITIALIZE_SERVER_SESSION,
+]
+
+
+def closing_session_with_ts_code_module_support(
+    initialization_behavior: SessionInitializationBehavior,
+    session: TSession,
+) -> ContextManager[TSession]:
+    """Create a context manager that closes the session.
+
+    Emulates the behavior of INITIALIZE_SESSION_THEN_DETACH and ATTACH_TO_SESSION_THEN_CLOSE.
+    """
+    if not hasattr(session, "close"):
+        raise TypeError("Session must have a close() method.")
+
+    if initialization_behavior in _EXISTING_BEHAVIORS:
+        return closing_session(session)
+    elif initialization_behavior == SessionInitializationBehavior.INITIALIZE_SESSION_THEN_DETACH:
+        return contextlib.nullcontext(session)
+    elif initialization_behavior == SessionInitializationBehavior.ATTACH_TO_SESSION_THEN_CLOSE:
+        return contextlib.closing(session)  # pyright: ignore[reportArgumentType]
+    else:
+        raise ValueError(f"Invalid initialization behavior: '{initialization_behavior}'.")
+
+
+def closing_session(session: TSession) -> ContextManager[TSession]:
+    """A context manager that yields the session and closes it."""
+    if not isinstance(session, contextlib.AbstractContextManager):
+        raise TypeError("Session must be a context manager.")
+    return session