plesty.server.cli.main

The plesty-server command group.

Every command opens the Bench for the --home/-f given (or found) and calls one presenter method. Long work (install, update, field test) is started as a job and the job log is streamed unless --no-wait is given; the hidden _job group is what those jobs execute in the foreground.

Attributes

`pass_context`
`EXPECTED`

Classes

Context

What every command receives: how to open the bench, and how loud to be.

Functions

`app`(→ None)	Install, launch and supervise PLESTY device servers on this bench.
`_run`(→ T)	Call action, turning every expected failure into a one-line CLI error.
`_follow_job`(→ int)	Stream a job's log until it ends; returns its exit code.
`_finish_job`(→ None)
`declare`(→ None)	Add device NAME running PACKAGE to the fleet file.
`_parse_env`(→ dict[str, str])
`install`(→ None)	Install the environment NAME declares (as a job).
`update`(→ None)	Pull and re-sync (git) or reinstall (PyPI) the environment of NAME.
`uninstall`(→ None)	Stop NAME and remove its environment (unless another device uses it).
`module`(→ None)	The device modules on this bench — what the fleet declares instances of.
`module_install`(→ None)	Put PACKAGE on this bench (as a job); no device is declared.
`module_list`(→ None)	List the modules installed on this bench.
`list_devices`(→ None)	Show every declared device: source, installed version, state.
`start`(→ None)	Start the device server NAME (installing first when needed).
`stop`(→ None)	Stop the device server NAME.
`restart`(→ None)	Stop (if running) and start the device server NAME.
`status`(→ None)	Show the state of NAMES (default: every declared device).
`log`(→ None)	Print the tail of the server log of NAME.
`field_test`(→ None)	Run the field test of NAME on this bench (as a job). EXTRA goes to the script.
`_field_test_run`(→ plesty.server.model.FieldTestRun)
`reports`(→ None)	List the published field-test reports of NAME.
`jobs`(→ None)	Long-running work on the bench: installs, updates, field tests.
`jobs_list`(→ None)	List jobs, newest first.
`jobs_log`(→ None)	Print the log of JOB_ID (from --offset; --json for a tailing client).
`jobs_cancel`(→ None)	Kill a running job.
`fleet`(→ None)	Operate every device declared in fleet.yaml at once.
`fleet_init`(→ None)	Write an annotated example fleet.yaml to PATH.
`fleet_up`(→ None)	Install and start the autostart devices (or NAMES).
`fleet_down`(→ None)	Stop the declared devices (or NAMES).
`fleet_run`(→ None)	Bring the fleet up and keep it up until interrupted (headless bench mode).
`fleet_status`(→ None)	Show the state of every declared device.
`agent`(→ None)	Serve plesty-bench clients: run plesty-server commands for them on this bench.
`gui`(→ None)	Open the Qt console (needs the 'gui' extra).
`job_group`(→ None)	Foreground twins of the job commands (run by the launcher, not by people).
`job_install`(→ None)	Install NAME in the foreground.
`job_module_install`(→ None)	Install the module PACKAGE in the foreground.
`job_update`(→ None)	Update NAME in the foreground.
`job_field_test`(→ None)	Run the field test of NAME in the foreground.
`launch_waiter`(→ None)	Run the detached launcher (spec as JSON on stdin); used by the PyInstaller bundle.
`_device_dict`(→ dict[str, object])
`_report_dict`(→ dict[str, object])
`_table`(→ list[str])
`_status_table`(→ list[str])
`_echo_status`(→ None)
`main`(→ None)	Console-script entry point.
`_printable_output`(→ None)	Never let the console's codepage turn output into a crash.
`gui_main`(→ None)	GUI-script entry point (`plesty-server-gui`): the console window, no terminal.

Module Contents

class plesty.server.cli.main.Context(home: str | None, fleet: str | None, quiet: bool)

What every command receives: how to open the bench, and how loud to be.

Remember the global options.

Parameters:

home (str | None)
fleet (str | None)
quiet (bool)

home_arg

fleet_arg

quiet

_bench: plesty.server.presenter.Bench | None = None

bench() → plesty.server.presenter.Bench

The bench (opened once per invocation).

Return type:: plesty.server.presenter.Bench

say(line: str) → None

Progress to stderr unless --quiet.

Parameters:: line (str)
Return type:: None

plesty.server.cli.main.pass_context

plesty.server.cli.main.app(ctx: click.Context, home_arg: str | None, fleet_arg: str | None, quiet: bool) → None

Install, launch and supervise PLESTY device servers on this bench.

Parameters:

ctx (click.Context)
home_arg (str | None)
fleet_arg (str | None)
quiet (bool)

Return type:

None

plesty.server.cli.main.EXPECTED

plesty.server.cli.main._run[T](ctx: Context, action: collections.abc.Callable[[], T]) → T

Call action, turning every expected failure into a one-line CLI error.

Parameters:

ctx (Context)
action (collections.abc.Callable[[], T])

Return type:

T

plesty.server.cli.main._follow_job(ctx: Context, job: plesty.server.model.Job) → int

Stream a job’s log until it ends; returns its exit code.

Parameters:

ctx (Context)
job (plesty.server.model.Job)

Return type:

int

plesty.server.cli.main._finish_job(ctx: Context, job: plesty.server.model.Job, wait: bool) → None

Parameters:

ctx (Context)
job (plesty.server.model.Job)
wait (bool)

Return type:

None

plesty.server.cli.main.declare(ctx: Context, name: str, package: str, version: str | None, git_url: str | None, ref: str | None, args: tuple[str, Ellipsis], env: tuple[str, Ellipsis], no_autostart: bool) → None

Add device NAME running PACKAGE to the fleet file.

Parameters:

ctx (Context)
name (str)
package (str)
version (str | None)
git_url (str | None)
ref (str | None)
args (tuple[str, Ellipsis])
env (tuple[str, Ellipsis])
no_autostart (bool)

Return type:

None

plesty.server.cli.main._parse_env(pairs: tuple[str, Ellipsis]) → dict[str, str]

Parameters:: pairs (tuple[str, Ellipsis])
Return type:: dict[str, str]

plesty.server.cli.main.install(ctx: Context, name: str, force: bool, no_wait: bool) → None

Install the environment NAME declares (as a job).

Parameters:

ctx (Context)
name (str)
force (bool)
no_wait (bool)

Return type:

None

plesty.server.cli.main.update(ctx: Context, name: str, ref: str | None, no_wait: bool) → None

Pull and re-sync (git) or reinstall (PyPI) the environment of NAME.

Parameters:

ctx (Context)
name (str)
ref (str | None)
no_wait (bool)

Return type:

None

plesty.server.cli.main.uninstall(ctx: Context, name: str) → None

Stop NAME and remove its environment (unless another device uses it).

Parameters:

ctx (Context)
name (str)

Return type:

None

plesty.server.cli.main.module() → None

The device modules on this bench — what the fleet declares instances of.

Return type:: None

plesty.server.cli.main.module_install(ctx: Context, package: str, version: str | None, git_url: str | None, ref: str | None, force: bool, no_wait: bool) → None

Put PACKAGE on this bench (as a job); no device is declared.

Parameters:

ctx (Context)
package (str)
version (str | None)
git_url (str | None)
ref (str | None)
force (bool)
no_wait (bool)

Return type:

None

plesty.server.cli.main.module_list(ctx: Context, as_json: bool) → None

List the modules installed on this bench.

Parameters:

ctx (Context)
as_json (bool)

Return type:

None

plesty.server.cli.main.list_devices(ctx: Context, no_probe: bool, as_json: bool) → None

Show every declared device: source, installed version, state.

Parameters:

ctx (Context)
no_probe (bool)
as_json (bool)

Return type:

None

plesty.server.cli.main.start(ctx: Context, name: str, no_wait: bool, timeout: float | None) → None

Start the device server NAME (installing first when needed).

Parameters:

ctx (Context)
name (str)
no_wait (bool)
timeout (float | None)

Return type:

None

plesty.server.cli.main.stop(ctx: Context, name: str, timeout: float | None) → None

Stop the device server NAME.

Parameters:

ctx (Context)
name (str)
timeout (float | None)

Return type:

None

plesty.server.cli.main.restart(ctx: Context, name: str, no_wait: bool) → None

Stop (if running) and start the device server NAME.

Parameters:

ctx (Context)
name (str)
no_wait (bool)

Return type:

None

plesty.server.cli.main.status(ctx: Context, names: tuple[str, Ellipsis], no_probe: bool, as_json: bool) → None

Show the state of NAMES (default: every declared device).

Parameters:

ctx (Context)
names (tuple[str, Ellipsis])
no_probe (bool)
as_json (bool)

Return type:

None

plesty.server.cli.main.log(ctx: Context, name: str, lines: int) → None

Print the tail of the server log of NAME.

Parameters:

ctx (Context)
name (str)
lines (int)

Return type:

None

plesty.server.cli.main.field_test(ctx: Context, name: str, extra: tuple[str, Ellipsis], tier: str, address: str | None, gates: str | None, repetitions: int | None, keep_going: bool, keep_server: bool, no_wait: bool) → None

Run the field test of NAME on this bench (as a job). EXTRA goes to the script.

Parameters:

ctx (Context)
name (str)
extra (tuple[str, Ellipsis])
tier (str)
address (str | None)
gates (str | None)
repetitions (int | None)
keep_going (bool)
keep_server (bool)
no_wait (bool)

Return type:

None

plesty.server.cli.main._field_test_run(tier: str, address: str | None, gates: str | None, repetitions: int | None, keep_going: bool, keep_server: bool, extra: tuple[str, Ellipsis]) → plesty.server.model.FieldTestRun

Parameters:

tier (str)
address (str | None)
gates (str | None)
repetitions (int | None)
keep_going (bool)
keep_server (bool)
extra (tuple[str, Ellipsis])

Return type:

plesty.server.model.FieldTestRun

plesty.server.cli.main.reports(ctx: Context, name: str, as_json: bool) → None

List the published field-test reports of NAME.

Parameters:

ctx (Context)
name (str)
as_json (bool)

Return type:

None

plesty.server.cli.main.jobs() → None

Long-running work on the bench: installs, updates, field tests.

Return type:: None

plesty.server.cli.main.jobs_list(ctx: Context, name: str | None, kind: str | None, as_json: bool) → None

List jobs, newest first.

Parameters:

ctx (Context)
name (str | None)
kind (str | None)
as_json (bool)

Return type:

None

plesty.server.cli.main.jobs_log(ctx: Context, job_id: str, follow: bool, offset: int, as_json: bool) → None

Print the log of JOB_ID (from –offset; –json for a tailing client).

Parameters:

ctx (Context)
job_id (str)
follow (bool)
offset (int)
as_json (bool)

Return type:

None

plesty.server.cli.main.jobs_cancel(ctx: Context, job_id: str) → None

Kill a running job.

Parameters:

ctx (Context)
job_id (str)

Return type:

None

plesty.server.cli.main.fleet() → None

Operate every device declared in fleet.yaml at once.

Return type:: None

plesty.server.cli.main.fleet_init(path: str, force: bool) → None

Write an annotated example fleet.yaml to PATH.

Parameters:

path (str)
force (bool)

Return type:

None

plesty.server.cli.main.fleet_up(ctx: Context, names: tuple[str, Ellipsis], no_install: bool, no_wait: bool) → None

Install and start the autostart devices (or NAMES).

Parameters:

ctx (Context)
names (tuple[str, Ellipsis])
no_install (bool)
no_wait (bool)

Return type:

None

plesty.server.cli.main.fleet_down(ctx: Context, names: tuple[str, Ellipsis]) → None

Stop the declared devices (or NAMES).

Parameters:

ctx (Context)
names (tuple[str, Ellipsis])

Return type:

None

plesty.server.cli.main.fleet_run(ctx: Context, names: tuple[str, Ellipsis], interval: float, with_agent: bool, bind: str | None, token: str | None, leave_running: bool, sweeps: int | None) → None

Bring the fleet up and keep it up until interrupted (headless bench mode).

Parameters:

ctx (Context)
names (tuple[str, Ellipsis])
interval (float)
with_agent (bool)
bind (str | None)
token (str | None)
leave_running (bool)
sweeps (int | None)

Return type:

None

plesty.server.cli.main.fleet_status(ctx: Context, no_probe: bool) → None

Show the state of every declared device.

Parameters:

ctx (Context)
no_probe (bool)

Return type:

None

plesty.server.cli.main.agent(ctx: Context, bind: str | None, token: str | None, workers: int, max_replies: int | None) → None

Serve plesty-bench clients: run plesty-server commands for them on this bench.

Parameters:

ctx (Context)
bind (str | None)
token (str | None)
workers (int)
max_replies (int | None)

Return type:

None

plesty.server.cli.main.gui(ctx: Context, title: str | None) → None

Open the Qt console (needs the ‘gui’ extra).

Parameters:

ctx (Context)
title (str | None)

Return type:

None

plesty.server.cli.main.job_group() → None

Foreground twins of the job commands (run by the launcher, not by people).

Return type:: None

plesty.server.cli.main.job_install(ctx: Context, name: str, force: bool) → None

Install NAME in the foreground.

Parameters:

ctx (Context)
name (str)
force (bool)

Return type:

None

plesty.server.cli.main.job_module_install(ctx: Context, package: str, version: str | None, git_url: str | None, ref: str | None, force: bool) → None

Install the module PACKAGE in the foreground.

Parameters:

ctx (Context)
package (str)
version (str | None)
git_url (str | None)
ref (str | None)
force (bool)

Return type:

None

plesty.server.cli.main.job_update(ctx: Context, name: str, ref: str | None) → None

Update NAME in the foreground.

Parameters:

ctx (Context)
name (str)
ref (str | None)

Return type:

None

plesty.server.cli.main.job_field_test(ctx: Context, name: str, extra: tuple[str, Ellipsis], tier: str, address: str | None, gates: str | None, repetitions: int | None, keep_going: bool, keep_server: bool) → None

Run the field test of NAME in the foreground.

Parameters:

ctx (Context)
name (str)
extra (tuple[str, Ellipsis])
tier (str)
address (str | None)
gates (str | None)
repetitions (int | None)
keep_going (bool)
keep_server (bool)

Return type:

None

plesty.server.cli.main.launch_waiter() → None

Run the detached launcher (spec as JSON on stdin); used by the PyInstaller bundle.

Return type:: None

plesty.server.cli.main._device_dict(view: plesty.server.presenter.DeviceView) → dict[str, object]

Parameters:: view (plesty.server.presenter.DeviceView)
Return type:: dict[str, object]

plesty.server.cli.main._report_dict(ctx: Context, report: plesty.server.model.FieldTestReport) → dict[str, object]

Parameters:

ctx (Context)
report (plesty.server.model.FieldTestReport)

Return type:

dict[str, object]

plesty.server.cli.main._table(header: collections.abc.Sequence[str], rows: collections.abc.Sequence[collections.abc.Sequence[str]]) → list[str]

Parameters:

header (collections.abc.Sequence[str])
rows (collections.abc.Sequence[collections.abc.Sequence[str]])

Return type:

list[str]

plesty.server.cli.main._status_table(statuses: collections.abc.Sequence[plesty.server.model.ProcessStatus]) → list[str]

Parameters:: statuses (collections.abc.Sequence[plesty.server.model.ProcessStatus])
Return type:: list[str]

plesty.server.cli.main._echo_status(status: plesty.server.model.ProcessStatus) → None

Parameters:: status (plesty.server.model.ProcessStatus)
Return type:: None

plesty.server.cli.main.main() → None

Console-script entry point.

Return type:: None

plesty.server.cli.main._printable_output() → None

Never let the console’s codepage turn output into a crash.

A job log holds whatever the tools wrote — uv draws its resolution errors

with box characters — and a Windows console is cp1252 by default, which cannot encode them. Echoing such a log raised UnicodeEncodeError and the operator got a traceback instead of the one-line error the log actually contained.

A console keeps its own encoding and loses what it cannot draw: a ? is a fair price for the message surviving. Anything redirected is a file this bench owns — a job log, read back later and sent to whoever is helping — so it is written as UTF-8 and keeps every character.

Return type:: None

plesty.server.cli.main.gui_main() → None

GUI-script entry point (plesty-server-gui): the console window, no terminal.

Installed as a gui-scripts entry so Windows starts it with pythonw — no black console box behind the window. Arguments are the group’s (--home, -f); _launch/_job pass through for re-execution.

Return type:: None