plesty.server.model.fleet
=========================

.. py:module:: plesty.server.model.fleet

.. autoapi-nested-parse::

   The ``fleet.yaml`` model — which device servers this bench runs, and how.

   A fleet file declares the devices once; ``plesty-server fleet up`` installs
   and starts them, ``fleet run`` keeps them up headless. The same file is what
   the GUI reads and writes.

   .. code-block:: yaml

       version: 1
       home: ~/.plesty/server            # optional
       index_url: https://hub.plesty.net/api/modules/   # optional
       devices:
         pm100d:                         # instance name → venv, log and state key
           package: plesty-pm100d        # PyPI distribution
           version: 0.2.1                # pinned; omit for the newest release
           # git: https://gitlab.com/plesty/hub/devices/thorlab/plesty-pm100d.git
           # ref: exp                    # branch/tag/sha; default tag v<version>
           args: [--tcp-port, "5555", -a, "USB0::0x1313::0x8078::P0000000::INSTR"]
           env:                          # process environment; plesty-lib reads it
             PLESTY_REPORT_ARCHIVE: /shares/plesty/reports
           autostart: true

   A ``git:`` URL installs from the repository instead of PyPI — the form
   hub-registry advertises for modules without a release; ``ref`` names the
   branch, tag or commit and defaults to the tag ``v<version>`` when a version
   is given, else the default branch.

   Precedence for the probed TCP port: an explicit ``port`` key, then
   ``--tcp-port``/``-tp`` in ``args``, then a ``*_TCP_PORT`` value in ``env``,
   then plesty-lib's default 5555 (see :mod:`plesty.server.model.ports`).



Attributes
----------

.. autoapisummary::

   plesty.server.model.fleet.FLEET_VERSION
   plesty.server.model.fleet.FLEET_FILENAME


Classes
-------

.. autoapisummary::

   plesty.server.model.fleet.Fleet


Functions
---------

.. autoapisummary::

   plesty.server.model.fleet.load_fleet
   plesty.server.model.fleet.save_fleet
   plesty.server.model.fleet.find_fleet


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

.. py:data:: FLEET_VERSION
   :value: 1


.. py:data:: FLEET_FILENAME
   :value: 'fleet.yaml'


.. py:class:: Fleet

   A parsed fleet file.

   :ivar devices: Specs keyed by device name, in file order.
   :ivar home: ``home:`` from the file, or ``None``.
   :ivar index_url: ``index_url:`` from the file, or ``None``.
   :ivar path: Where it was read from, or ``None`` for an in-memory fleet.



   .. py:attribute:: devices
      :type:  collections.abc.Mapping[str, plesty.server.model.device.DeviceSpec]


   .. py:attribute:: home
      :type:  pathlib.Path | None
      :value: None



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



   .. py:attribute:: path
      :type:  pathlib.Path | None
      :value: None



   .. py:method:: __getitem__(name: str) -> plesty.server.model.device.DeviceSpec

      The spec of device *name*; :class:`KeyError` when undeclared.



   .. py:method:: __contains__(name: object) -> bool

      Whether *name* is a declared device.



   .. py:method:: __iter__() -> Any

      Iterate over the specs in file order.



   .. py:method:: __len__() -> int

      Number of declared devices.



   .. py:property:: autostart
      :type: list[plesty.server.model.device.DeviceSpec]


      The specs ``fleet up`` starts.


   .. py:method:: from_mapping(raw: collections.abc.Mapping[str, Any], path: pathlib.Path | None = None) -> Fleet
      :classmethod:


      Build a fleet from a parsed YAML document.

      :param raw: The document.
      :param path: Where it came from, for error messages and :attr:`path`.

      :raises FleetError: On a wrong schema version or malformed entries.



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

      The YAML document form of this fleet.



   .. py:method:: with_device(spec: plesty.server.model.device.DeviceSpec) -> Fleet

      A copy with *spec* added or replaced under its name.



   .. py:method:: without_device(name: str) -> Fleet

      A copy without device *name* (no error when absent).



.. py:function:: load_fleet(path: str | os.PathLike[str]) -> Fleet

   Read and validate a fleet file.

   :param path: The YAML file.

   :raises FleetError: When the file is missing or malformed.


.. py:function:: save_fleet(fleet: Fleet, path: str | os.PathLike[str]) -> pathlib.Path

   Write a fleet file.

   :param fleet: The fleet to serialize.
   :param path: Destination file; parents are created.

   :returns: The written path.


.. py:function:: find_fleet(explicit: str | os.PathLike[str] | None, home: pathlib.Path) -> pathlib.Path | None

   Locate the fleet file a command should consult.

   :param explicit: A path the user gave (``-f``); returned as-is when set.
   :param home: The bench home, whose ``fleet.yaml`` is the last resort after
                the working directory's.

   :returns: The first existing candidate, or ``None`` when no fleet file exists.