plesty.server.model.home
========================

.. py:module:: plesty.server.model.home

.. autoapi-nested-parse::

   The bench's ``plesty-server`` home directory: venvs, logs and process state.

   Everything ``plesty-server`` writes lives under one directory so a bench can be
   wiped or moved as a whole. Resolution order for its location: an explicit
   ``--home``, ``home:`` in ``fleet.yaml``, ``PLESTY_SERVER_HOME``, then the
   packaged default (``~/.plesty/server`` — beside ``~/.plesty/ui`` where
   plesty-lib keeps its window layouts).



Attributes
----------

.. autoapisummary::

   plesty.server.model.home.HOME_ENV


Classes
-------

.. autoapisummary::

   plesty.server.model.home.Home


Functions
---------

.. autoapisummary::

   plesty.server.model.home.default_home


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

.. py:data:: HOME_ENV
   :value: 'PLESTY_SERVER_HOME'


.. py:function:: default_home() -> pathlib.Path

   The home directory the environment or the packaged config designates.

   :returns: ``$PLESTY_SERVER_HOME`` when set, else ``running.home`` from
             ``config.yaml`` with ``~`` expanded.


.. py:class:: Home

   Layout of the plesty-server home directory.

   :ivar root: The directory everything lives under.



   .. py:attribute:: root
      :type:  pathlib.Path


   .. py:method:: resolve(root: str | os.PathLike[str] | None = None) -> Home
      :classmethod:


      Build a home from an explicit path or the environment default.

      :param root: Directory to use; ``None`` selects :func:`default_home`.



   .. py:property:: venvs
      :type: pathlib.Path


      One virtual environment per installed device, keyed by device name.


   .. py:property:: logs
      :type: pathlib.Path


      One append-only log per device server.


   .. py:property:: state
      :type: pathlib.Path


      One JSON record per running server (pid, port, start time).


   .. py:property:: run
      :type: pathlib.Path


      Working directories the servers run in; plesty-lib writes ``logs/`` there.


   .. py:property:: repos
      :type: pathlib.Path


      Git checkouts of device modules installed from a repository.


   .. py:property:: jobs
      :type: pathlib.Path


      One JSON record per long-running job (install, update, field test, command).


   .. py:property:: fleets
      :type: pathlib.Path


      Where the console keeps fleet files by default (``<home>/fleets/``).


   .. py:property:: tools
      :type: pathlib.Path


      Tools the bench installed for itself (the portable git on Windows).


   .. py:property:: packages
      :type: pathlib.Path


      one environment per (package, version), side by side.

      :type: Installed device modules


   .. py:method:: package_dir(package: str, version: str) -> pathlib.Path

      Environment of *package* at *version*.



   .. py:method:: package_record(package: str, version: str) -> pathlib.Path

      Record file of *package* at *version* (beside its environment).



   .. py:property:: last_fleet
      :type: pathlib.Path


      Pointer file naming the fleet the console used last (``<home>/last-fleet``).


   .. py:method:: package_info(package: str) -> pathlib.Path

      The package-level record of *package*: repository, project page, latest release.



   .. py:method:: checkout(package: str, ref: str | None) -> pathlib.Path

      Checkout directory of *package* at *ref* (git sources only).

      Refs may contain ``/`` (``feat/x``); the directory name flattens them.



   .. py:method:: job_file(job_id: str) -> pathlib.Path

      Record file of job *job_id*.



   .. py:method:: job_log(job_id: str) -> pathlib.Path

      Log file of job *job_id*.



   .. py:method:: venv(name: str) -> pathlib.Path

      Venv directory of the device *name*.



   .. py:method:: log(name: str) -> pathlib.Path

      Log file of the device *name*.



   .. py:method:: state_file(name: str) -> pathlib.Path

      Process-state file of the device *name*.



   .. py:method:: run_dir(name: str) -> pathlib.Path

      Working directory of the device *name*'s server process.



   .. py:method:: ensure() -> Home

      Create the directory tree; returns *self* for chaining.