plesty.lib.traffic
==================

.. py:module:: plesty.lib.traffic

.. autoapi-nested-parse::

   Abstract traffic manager base class and common interface for Plesty devices.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /reference/plesty/lib/traffic/apt/index
   /reference/plesty/lib/traffic/apt_protocol/index
   /reference/plesty/lib/traffic/serial/index
   /reference/plesty/lib/traffic/serial_ports/index
   /reference/plesty/lib/traffic/tcp_ip/index
   /reference/plesty/lib/traffic/usb_utils/index
   /reference/plesty/lib/traffic/utils/index
   /reference/plesty/lib/traffic/visa/index


Classes
-------

.. autoapisummary::

   plesty.lib.traffic.TrafficManager


Functions
---------

.. autoapisummary::

   plesty.lib.traffic.handle_error


Package Contents
----------------

.. py:function:: handle_error(err: Any, error_msg: str | None = None, silent: bool = False, func_name: str = 'Unknown Function') -> None

   Handle a caught error by logging and optionally re-raising it.


.. py:class:: TrafficManager(address: str, timeout: int = 5)

   Bases: :py:obj:`abc.ABC`


   Abstract base class for managing communication with device resources.

   Defines common interface for opening, closing, and sending commands. The
   private methods (_open, _send_command, _close) are implemented by subclasses
   while the public methods (open, send_command, close) provide consistent
   resource management and error handling.

   Initialize the TrafficManager with the given address and timeout.

   :param address: The address of the resource.
   :type address: str
   :param timeout: The timeout for operations in seconds. Defaults to 5.
   :type timeout: int, optional


   .. py:attribute:: _resource_in_use
      :type:  dict[str, Any]


   .. py:attribute:: address


   .. py:attribute:: timeout
      :value: 5



   .. py:attribute:: inst
      :value: None



   .. py:attribute:: command_log_level
      :type:  int
      :value: 20



   .. py:attribute:: timeout_cap
      :type:  int | None
      :value: None



   .. py:property:: is_open
      :type: bool


      Return True if the connection is currently open.


   .. py:method:: _open(*args, **kwargs)
      :abstractmethod:


      Open the connection to the resource.

      This method should be implemented by subclasses to handle the specific
      details of opening the connection.

      :param args: Positional arguments for the specific implementation.
      :param kwargs: Keyword arguments for the specific implementation.



   .. py:method:: open(*args, **kwargs) -> bool

      Open the connection, delegating to _open and registering the resource.



   .. py:method:: _explain_open_error(exc: BaseException) -> str | None

      Return guidance for an open failure the user cannot read off *exc*.

      The base class knows nothing about transports, so it returns ``None``
      and :meth:`open` reports the bare failure. A subclass whose backend
      reports the wrong port and a held port with the same exception type
      overrides this to say which one it was and what to do about it; the
      text is appended to the raised message, not buried in the cause chain.

      :param exc: The exception :meth:`_open` raised.



   .. py:method:: _send_command(command: str, timeout=None, *args, **kwargs) -> Any
      :abstractmethod:


      Send a command to the resource and return the response.

      :param command: The command to send.
      :param timeout: Timeout in seconds; defaults to the instance's timeout.
      :param \*args: Additional positional arguments for subclass implementations.
      :param \*\*kwargs: Additional keyword arguments for subclass implementations.

      :returns: The response from the resource, or False if the command failed.
      :rtype: Any



   .. py:method:: orphan(command: str) -> bool

      Transmit *command* and never read what comes back.

      Not a write. A write is a command that sets something, and plenty of
      instruments acknowledge one — those replies are read, and must be, or
      the acknowledgement becomes the stale answer handed to the next
      command. This reads nothing whatever the command means, which is the
      one thing :meth:`send_command` cannot express and exactly the
      condition the buffer-drain gate has to create: a reply left in the
      instrument's buffer, as a timed-out query leaves one.

      Deliberately narrow. Racing a timeout is the alternative and it is not
      a lever on every driver — NI-VISA does not enforce short timeouts on
      some instruments, so the gate silently tested nothing there.

      :returns: ``True`` when the command was transmitted, ``False`` when this
                transport cannot transmit without reading — in which case the
                drain gate skips and says so rather than reporting a pass.



   .. py:method:: send_command(command: str, timeout=None, *args, **kwargs) -> Any

      Send a command, delegating to _send_command with error handling.



   .. py:method:: _close()
      :abstractmethod:


      Close the connection to the resource.

      Subclasses must implement this to handle the specific close logic.



   .. py:method:: close() -> bool

      Close the connection, unregister the resource, and return success status.

      The resource is unregistered even when ``_close`` fails. Otherwise a
      transport that throws on the way out — a clear refused by an
      unresponsive instrument, a close on a dead handle — leaves the address
      registered for the life of the process, and every later ``open`` is
      rejected with "already in use" against a resource nothing is holding.



   .. py:method:: __enter__()

      Open the resource connection when entering the context manager.



   .. py:method:: __exit__(exc_type, exc_val, exc_tb)

      Close the resource connection when exiting the context manager.