plesty.server.model.device

One device server as fleet.yaml declares it.

Attributes

_RESERVED

_NAME_CHARS

Classes

DeviceSpec

One device server as the fleet declares it.

Functions

check_name(→ None)

Raise FleetError unless name is usable as a file name on any bench.

check_data_dir(→ None)

Raise FleetError unless data_dir stays under the bench data path.

module_for(→ str)

The import path served by python -m for a PLESTY distribution.

Module Contents

plesty.server.model.device._RESERVED
plesty.server.model.device._NAME_CHARS
plesty.server.model.device.check_name(name: str) → None

Raise FleetError unless name is usable as a file name on any bench.

The name of a device is not only a label: it names its virtual environment, its log, its run directory and its state file. A name that a Windows bench cannot open (com3) or that reaches out of its directory (../x) would declare fine on a developer machine and fail on the instrument.

Parameters:

name (str) – The key the fleet file gives the device.

Raises:

FleetError – When the name cannot be a file name everywhere.

Return type:

None

plesty.server.model.device.check_data_dir(name: str, data_dir: str) → None

Raise FleetError unless data_dir stays under the bench data path.

The fleet names a device’s folder relative to the bench data path, which each bench spells its own way; an absolute path or one climbing out with .. would write where no other machine looks.

Parameters:

  • name (str) – The device, for the message.

  • data_dir (str) – Its data_dir as the fleet file writes it.

Raises:

FleetError – When it is absolute, or leaves the data path.

Return type:

None

plesty.server.model.device.module_for(package: str) → str

The import path served by python -m for a PLESTY distribution.

Parameters:

package (str) – PyPI distribution name, e.g. plesty-pm100d.

Returns:

plesty.pm100d — the platform’s flat namespace convention.

Return type:

str

class plesty.server.model.device.DeviceSpec

One device server as the fleet declares it.

Variables:

  • name – Instance name — the venv, log and state key; unique per bench.

  • package – PyPI distribution of the device module.

  • version – Pinned release, or None for the newest one at install time.

  • git – Repository URL to install from instead of PyPI, or None.

  • ref – Branch, tag or commit for a git source; None = v<version> when a version is given, else the default branch.

  • module – Import path served with python -m; derived from package.

  • args – Arguments appended to python -m <module>.

  • env – Environment set for the server process on top of the bench’s own.

  • port – TCP port the server binds; probed for liveness.

  • autostart – Whether fleet up/fleet run start it.

  • host_name – The bench the server runs on, as an experiment’s setup.yaml names it; the run’s <DEVICE>_ADDRESS is built from that bench and the port (plesty.lib.experiment.setup).

  • path – A local repository to run instead of an install — the folder Hub ▸ Load from… loaded. Only a declaration naming it runs it.

  • data_dir – Where the device writes, relative to its bench’s data path (Server ▸ Configure…) — pol-pl for a spectrometer saving frames there. Started by the bench, the device is given that folder as DEVICE_DATA_PATH; None gives it tmp/<name>. Never absolute and never above the data path.

name: str
package: str
version: str | None = None
git: str | None = None
ref: str | None = None
module: str = ''
args: tuple[str, Ellipsis] = ()
env: collections.abc.Mapping[str, str]
port: int = 0
autostart: bool = True
host_name: str | None = None
path: str | None = None
data_dir: str | None = None
__post_init__() → None

Fill the derived fields and validate the declaration.

Return type:

None

property port_is_explicit: bool

Whether this device asked for its port rather than taking the default.

True once the bench has allocated one and written it down, so the port a client connected to yesterday is the port it finds today.

Return type:

bool

property launch_args: tuple[str, Ellipsis]

The arguments python -m <module> is started with.

port is what the supervisor probes; unless the args already name a port, it is also handed to the server as --tcp-port, so what is probed and what is bound cannot drift. An environment value (*_TCP_PORT — often 5555 straight from a module’s .env.example) is deliberately not trusted here: an explicit flag beats the environment in every hub module, and the bench owns the ports.

Return type:

tuple[str, Ellipsis]

property git_ref: str | None

The ref a git install checks out (ref, else v<version>, else None).

Return type:

str | None

property requirement: str

The pip requirement string.

plesty-pm100d==0.2.1 for a PyPI source; plesty-pm100d @ git+<url>@v0.2.1 for a git source.

Return type:

str

classmethod from_mapping(name: str, raw: collections.abc.Mapping[str, Any]) → DeviceSpec

Build a spec from one devices: entry of a fleet file.

Parameters:

  • name (str) – The mapping key.

  • raw (collections.abc.Mapping[str, Any]) – The entry’s fields.

Raises:

FleetError – On unknown keys or wrong value types.

Return type:

DeviceSpec

to_mapping() → dict[str, Any]

The fleet-file form of this spec (derived defaults omitted).

Return type:

dict[str, Any]