plesty.server.services.jobs
===========================

.. py:module:: plesty.server.services.jobs

.. autoapi-nested-parse::

   Runs commands as jobs: a detached process whose record and log a :class:`JobStore` keeps.

   The store (:mod:`plesty.server.model.job`) knows nothing about processes; this
   service supplies the two facts it lacks — whether a pid is alive and what
   exit code the launcher left — and the launch itself. An install, an update, a
   field test or ``plesty check`` in a device's environment all go through
   :meth:`JobRunner.start`; what differs is only the command line and the
   ``kind`` on the record.



Classes
-------

.. autoapisummary::

   plesty.server.services.jobs.JobRunner


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

.. py:class:: JobRunner(home: plesty.server.model.home.Home, store: plesty.server.model.job.JobStore | None = None)

   Start, observe and cancel jobs under a :class:`Home`.

   Bind to a home.

   :param home: The bench home.
   :param store: The record store; a fresh one on *home* by default.


   .. py:attribute:: home


   .. py:attribute:: store


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

      Where the launcher records the exit code of *job_id*.



   .. py:method:: start(name: str, kind: str, command: list[str], cwd: str | os.PathLike[str], env: collections.abc.Mapping[str, str] | None = None, detail: collections.abc.Mapping[str, Any] | None = None) -> plesty.server.model.job.Job

      Launch *command* as a job and return its record.

      :param name: Device instance the job belongs to.
      :param kind: Job kind, part of the id.
      :param command: The command line.
      :param cwd: Working directory.
      :param env: Environment on top of the bench's own.
      :param detail: Kind-specific data stored on the record.

      :raises JobError: When the command cannot be launched.



   .. py:method:: get(job_id: str) -> plesty.server.model.job.Job | None

      The job *job_id* with its state brought up to date, or ``None``.



   .. py:method:: require(job_id: str) -> plesty.server.model.job.Job

      Like :meth:`get` but raises :class:`JobError` when unknown.



   .. py:method:: list(name: str | None = None, kind: str | None = None) -> list[plesty.server.model.job.Job]

      Jobs on record, newest first, brought up to date.



   .. py:method:: wait(job_id: str, timeout: float | None = None, poll: float = 0.25) -> plesty.server.model.job.Job

      Block until the job finishes (or *timeout* seconds pass); returns it.



   .. py:method:: cancel(job_id: str) -> bool

      Kill a running job (its whole process tree); ``True`` when it was running.