plesty.server.model.device
==========================

.. py:module:: plesty.server.model.device

.. autoapi-nested-parse::

   One device server as ``fleet.yaml`` declares it.



Attributes
----------

.. autoapisummary::

   plesty.server.model.device._RESERVED
   plesty.server.model.device._NAME_CHARS


Classes
-------

.. autoapisummary::

   plesty.server.model.device.DeviceSpec


Functions
---------

.. autoapisummary::

   plesty.server.model.device.check_name
   plesty.server.model.device.module_for


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

.. py:data:: _RESERVED

.. py:data:: _NAME_CHARS

.. py:function:: check_name(name: str) -> None

   Raise :exc:`FleetError` unless *name* is usable as a file name on any bench.

   The name of a device is not only a label: it names its virtual environment,
   its log, its run directory and its state file. A name that a Windows bench
   cannot open (``com3``) or that reaches out of its directory (``../x``)
   would declare fine on a developer machine and fail on the instrument.

   :param name: The key the fleet file gives the device.

   :raises FleetError: When the name cannot be a file name everywhere.


.. py:function:: module_for(package: str) -> str

   The import path served by ``python -m`` for a PLESTY distribution.

   :param package: PyPI distribution name, e.g. ``plesty-pm100d``.

   :returns: ``plesty.pm100d`` — the platform's flat namespace convention.


.. py:class:: DeviceSpec

   One device server as the fleet declares it.

   :ivar name: Instance name — the venv, log and state key; unique per bench.
   :ivar package: PyPI distribution of the device module.
   :ivar version: Pinned release, or ``None`` for the newest one at install time.
   :ivar git: Repository URL to install from instead of PyPI, or ``None``.
   :ivar ref: Branch, tag or commit for a git source; ``None`` = ``v<version>``
              when a version is given, else the default branch.
   :ivar module: Import path served with ``python -m``; derived from *package*.
   :ivar args: Arguments appended to ``python -m <module>``.
   :ivar env: Environment set for the server process on top of the bench's own.
   :ivar port: TCP port the server binds; probed for liveness.
   :ivar autostart: Whether ``fleet up``/``fleet run`` start it.



   .. py:attribute:: name
      :type:  str


   .. py:attribute:: package
      :type:  str


   .. py:attribute:: version
      :type:  str | None
      :value: None



   .. py:attribute:: git
      :type:  str | None
      :value: None



   .. py:attribute:: ref
      :type:  str | None
      :value: None



   .. py:attribute:: module
      :type:  str
      :value: ''



   .. py:attribute:: args
      :type:  tuple[str, Ellipsis]
      :value: ()



   .. py:attribute:: env
      :type:  collections.abc.Mapping[str, str]


   .. py:attribute:: port
      :type:  int
      :value: 0



   .. py:attribute:: autostart
      :type:  bool
      :value: True



   .. py:method:: __post_init__() -> None

      Fill the derived fields and validate the declaration.



   .. py:property:: port_is_explicit
      :type: bool


      Whether this device asked for its port rather than taking the default.

      True once the bench has allocated one and written it down, so the port
      a client connected to yesterday is the port it finds today.


   .. py:property:: launch_args
      :type: tuple[str, Ellipsis]


      The arguments ``python -m <module>`` is started with.

      :attr:`port` is what the supervisor probes; unless the *args* already
      name a port, it is also handed to the server as ``--tcp-port``, so
      what is probed and what is bound cannot drift. An environment value
      (``*_TCP_PORT`` — often ``5555`` straight from a module's
      ``.env.example``) is deliberately not trusted here: an explicit flag
      beats the environment in every hub module, and the bench owns the
      ports.


   .. py:property:: git_ref
      :type: str | None


      The ref a git install checks out (``ref``, else ``v<version>``, else ``None``).


   .. py:property:: requirement
      :type: str


      The pip requirement string.

      ``plesty-pm100d==0.2.1`` for a PyPI source; ``plesty-pm100d @
      git+<url>@v0.2.1`` for a git source.


   .. py:method:: from_mapping(name: str, raw: collections.abc.Mapping[str, Any]) -> DeviceSpec
      :classmethod:


      Build a spec from one ``devices:`` entry of a fleet file.

      :param name: The mapping key.
      :param raw: The entry's fields.

      :raises FleetError: On unknown keys or wrong value types.



   .. py:method:: to_mapping() -> dict[str, Any]

      The fleet-file form of this spec (derived defaults omitted).