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

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

.. autoapi-nested-parse::

   Explain why a serial port refused to open.

   pyserial reports every open failure as ``SerialException``, and the two that
   matter most look alike in a log line: a port that does not exist and a port
   that exists but is held. The second one costs sessions — the user re-checks
   drivers and port names while Thorlabs Kinesis, a serial terminal, or a stray
   interpreter still owns the device.



Attributes
----------

.. autoapisummary::

   plesty.lib.traffic.serial_ports._WINDOWS_OSERROR
   plesty.lib.traffic.serial_ports._HELD_HINT
   plesty.lib.traffic.serial_ports._DIALOUT_HINT


Functions
---------

.. autoapisummary::

   plesty.lib.traffic.serial_ports._open_errno
   plesty.lib.traffic.serial_ports.describe_port
   plesty.lib.traffic.serial_ports.explain_serial_open_error


Module Contents
---------------

.. py:data:: _WINDOWS_OSERROR

.. py:data:: _HELD_HINT
   :value: 'The port exists but is open in another process. Close Thorlabs Kinesis/APT (a loaded stage...


.. py:data:: _DIALOUT_HINT
   :value: 'Not permitted to open the port. Add the user to the serial group (`sudo usermod -aG dialout...


.. py:function:: _open_errno(exc: BaseException) -> int | None

   Return the OS error number behind a serial open failure, if any.


.. py:function:: describe_port(port: str) -> str

   Return ``device: description, hwid`` for *port*, or ``""`` when unlisted.

   :param port: A port name as passed to :class:`serial.Serial`.


.. py:function:: explain_serial_open_error(exc: BaseException, port: str, platform: str | None = None) -> str | None

   Return one sentence of guidance for a serial open failure, or ``None``.

   Only EACCES and EBUSY are explained — they are the two a user cannot tell
   apart from a wrong port name, and the two whose remedy is not on the
   device side. Everything else (``ENOENT``, timeouts) is left to speak for
   itself.

   :param exc: The exception :class:`serial.Serial` raised.
   :param port: The port that was being opened, for the ``list_ports`` line.
   :param platform: ``sys.platform`` override for tests; ``None`` reads it.