plesty.server.services.jobs

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

The store (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 JobRunner.start(); what differs is only the command line and the kind on the record.

Attributes

JOB_LOG_ENV

Classes

JobRunner

Start, observe and cancel jobs under a Home.

Functions

_banner_for(→ str)

How a job names itself at the head of its log.

Module Contents

plesty.server.services.jobs.JOB_LOG_ENV = 'PLESTY_JOB_LOG'

plesty.server.services.jobs._banner_for(job: plesty.server.model.job.Job, detail: collections.abc.Mapping[str, Any] | None) → str

How a job names itself at the head of its log.

A job id is <name>-<kind>-<timestamp>, which for an experiment reads exactly like a run id and is not one — someone comparing it with the run in the table finds two different numbers for what looks like one thing. So the id is labelled, and the run it is measuring is named beside it when the console chose that name. A run whose id the module generates is not known until it writes its journal, and is left unnamed rather than guessed.

Parameters:

job (plesty.server.model.job.Job) – The job being started.
detail (collections.abc.Mapping[str, Any] | None) – What the caller recorded on it.

Returns:

The banner’s label.

Return type:

str

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

Start, observe and cancel jobs under a Home.

Bind to a home.

Parameters:

home (plesty.server.model.home.Home) – The bench home.
store (plesty.server.model.job.JobStore | None) – The record store; a fresh one on home by default.

home

store

exit_file(job_id: str) → pathlib.Path

Where the launcher records the exit code of job_id.

Parameters:: job_id (str)
Return type:: pathlib.Path

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.

Parameters:

name (str) – Device instance the job belongs to.
kind (str) – Job kind, part of the id.
command (list[str]) – The command line.
cwd (str | os.PathLike[str]) – Working directory.
env (collections.abc.Mapping[str, str] | None) – Environment on top of the bench’s own.
detail (collections.abc.Mapping[str, Any] | None) – Kind-specific data stored on the record.

Raises: