plesty.server.model.device_manager

What is installed on this bench: device modules, several versions side by side.

A fleet file says which package an instance wants; the installer puts a version of it on disk; this module remembers the outcome. Every (package, version) pair has its own environment under <home>/packages/<package>/<version>/ and a record next to it, so two instances pinned to the same release share one environment, a newer release is installed beside the old one, and rolling back is pointing the instance at the version that is still there.

The manager only keeps the books — creating or deleting the environments is the installer’s job, which calls DeviceManager.record() when an install finished and DeviceManager.forget() when it removed one.

Attributes

`SOURCE_PYPI`
`SOURCE_GIT`

Exceptions

DeviceManagerError

An installed-version record is missing or inconsistent.

Classes

`InstalledVersion`	One version of one device module present on the bench.
`PackageInfo`	What the bench knows about a module as a project — independent of any install.
`InstalledPackage`	All installed versions of one device module.
`DeviceManager`	The installed-module inventory under a `Home`.

Functions

`version_order`(→ tuple[int, Ellipsis])	version as numbers, so `0.10.0` sorts above `0.9.0`.
`install_order`(→ tuple[str, tuple[int, Ellipsis]])	Order installs by when they happened, then by version.
`_now`(→ str)

Module Contents

plesty.server.model.device_manager.SOURCE_PYPI = 'pypi'

plesty.server.model.device_manager.SOURCE_GIT = 'git'

exception plesty.server.model.device_manager.DeviceManagerError

Bases: ValueError

An installed-version record is missing or inconsistent.

Initialize self. See help(type(self)) for accurate signature.

class plesty.server.model.device_manager.InstalledVersion

One version of one device module present on the bench.

Variables:

package – PyPI distribution name, e.g. plesty-pm100d.
version – The installed release as reported by the environment.
source – SOURCE_PYPI or SOURCE_GIT.
git – Repository URL for a git source, else None.
ref – Branch, tag or commit that was requested for a git source.
commit – The commit actually checked out for a git source.
installed_utc – ISO timestamp of the install.
python – Version of the interpreter in the environment.
job_id – The install job that produced it, when known.
path – Where the environment lives when it is not the default <home>/packages/<package>/<version>/ — a git checkout, whose .venv is the environment.

package: str

version: str

source: str = 'pypi'

git: str | None = None

ref: str | None = None

commit: str | None = None

installed_utc: str = ''

python: str = ''

job_id: str | None = None

path: str = ''

__post_init__() → None

Validate the record.

Return type:: None

property slot: str

the version for a release, git-<ref> for a checkout.

A checkout moves — its version changes with every pull — so it is kept by the ref it tracks, and two checkouts at the same commit (two refs) never share a record.

Type:: What identifies the environment within the package
Return type:: str

property key: tuple[str, str]

(package, slot) — what identifies the environment.

Return type:: tuple[str, str]

satisfies(spec: plesty.server.model.device.DeviceSpec) → bool

Whether this install is what spec asks for.

A PyPI spec is satisfied by the pinned version (or any PyPI version when unpinned); a git spec by an install from the same repository at the same ref (or v<version>), a commit hash matching by prefix.

Parameters:: spec (plesty.server.model.device.DeviceSpec)
Return type:: bool

to_dict() → dict[str, Any]

JSON form.

Return type:: dict[str, Any]

classmethod from_dict(data: collections.abc.Mapping[str, Any]) → InstalledVersion

Rebuild a record from to_dict() output (extra keys ignored).

Parameters:: data (collections.abc.Mapping[str, Any])
Return type:: InstalledVersion

class plesty.server.model.device_manager.PackageInfo

What the bench knows about a module as a project — independent of any install.

Learned from the catalogue (adopt) or from a git install, kept in <home>/packages/<package>/package.json and never asked again: the repository a module comes from, its project page, its latest release.

Variables:

package – Distribution name.
repo_url – Clone URL of the module’s repository.
web_url – Project page (GitLab), "" when unknown.
latest_tag – Latest release tag seen (v0.2.1), "" when none.
version – Latest release version seen, "" when none.
vendor – Hub vendor group, "" when unknown.
description – One line, "" when unknown.

package: str

repo_url: str = ''

web_url: str = ''

latest_tag: str = ''

version: str = ''

vendor: str = ''

description: str = ''

to_dict() → dict[str, Any]

JSON form.

Return type:: dict[str, Any]

classmethod from_dict(data: collections.abc.Mapping[str, Any]) → PackageInfo

Rebuild from to_dict() output (extra keys ignored).

Parameters:: data (collections.abc.Mapping[str, Any])
Return type:: PackageInfo

merged(**fields: str) → PackageInfo

A copy with the non-empty fields replacing the current values.

Parameters:: fields (str)
Return type:: PackageInfo

class plesty.server.model.device_manager.InstalledPackage

All installed versions of one device module.

Variables:

package – Distribution name.
versions – Records keyed by slot (version, or git-<ref>), oldest install first.

package: str

versions: collections.abc.Mapping[str, InstalledVersion]

__iter__() → collections.abc.Iterator[InstalledVersion]

Iterate over the versions, oldest install first.

Return type:: collections.abc.Iterator[InstalledVersion]

__len__() → int

Number of installed versions.

Return type:: int

__contains__(version: object) → bool

Whether version (a slot, or a release version) is installed.

Parameters:: version (object)
Return type:: bool

property latest: InstalledVersion | None

The most recently installed version, or None when empty.

Return type:: InstalledVersion | None

plesty.server.model.device_manager.version_order(version: str) → tuple[int, Ellipsis]

version as numbers, so 0.10.0 sorts above 0.9.0.

Parameters:: version (str)
Return type:: tuple[int, Ellipsis]

plesty.server.model.device_manager.install_order(installed: InstalledVersion) → tuple[str, tuple[int, Ellipsis]]

Order installs by when they happened, then by version.

installed_utc is stamped to the second, so two installs of the same package in one second tie — and a bare max/sorted then falls back to the order the records happened to be read in. That order is the filesystem’s, so “the latest version” was whichever the host listed last and differed between a Windows bench and a POSIX machine. The version breaks the tie.

Parameters:: installed (InstalledVersion)
Return type:: tuple[str, tuple[int, Ellipsis]]

class plesty.server.model.device_manager.DeviceManager(home: plesty.server.model.home.Home)

The installed-module inventory under a Home.

Bind to a home.

Parameters:: home (plesty.server.model.home.Home) – The bench home.

home

Write down that package version is installed; returns the record.

Parameters:

package (str) – Distribution name.
version (str) – Installed release.
source (str) – SOURCE_PYPI or SOURCE_GIT.
git (str | None) – Repository URL for a git source.
ref (str | None) – Requested ref for a git source.
commit (str | None) – Checked-out commit for a git source.
python (str) – Interpreter version of the environment.
job_id (str | None) – The install job.
path (str | os.PathLike[str] | None) – Environment location when not the default package dir.

Return type:

InstalledVersion

save(installed: InstalledVersion) → pathlib.Path

Write installed to its record file; returns the path.

Parameters:: installed (InstalledVersion)
Return type:: pathlib.Path

get(package: str, slot: str) → InstalledVersion | None

The record of package at slot (a version, or git-<ref>), or None.

Parameters:

package (str)
slot (str)

Return type:

InstalledVersion | None

require(package: str, slot: str) → InstalledVersion

Like get() but raises DeviceManagerError when absent.

Parameters:

package (str)
slot (str)

Return type:

InstalledVersion

package(package: str) → InstalledPackage

Every installed version of package (empty when none).

Parameters:: package (str)
Return type:: InstalledPackage

list() → list[InstalledPackage]

Every package with at least one installed version, by name.

Return type:: list[InstalledPackage]

info(package: str) → PackageInfo

The package-level record of package (empty fields when nothing is known).

Parameters:: package (str)
Return type:: PackageInfo

remember(package: str, **fields: str) → PackageInfo

Merge non-empty fields into the package-level record; returns it.

Parameters:

package (str)
fields (str)

Return type:

PackageInfo

env_dir(installed: InstalledVersion) → pathlib.Path

The environment directory of installed (its path, else the package dir).

Parameters:: installed (InstalledVersion)
Return type:: pathlib.Path

resolve(spec: plesty.server.model.device.DeviceSpec) → InstalledVersion | None

The installed version that serves spec, or None when one must be installed.

The most recent install among those that InstalledVersion.satisfies() the spec wins — for an unpinned PyPI spec that is the newest install, for a git branch the last pull.

Parameters:: spec (plesty.server.model.device.DeviceSpec)
Return type:: InstalledVersion | None

forget(package: str, slot: str, remove_env: bool = False) → bool

Drop the record of package at slot; True when it existed.

Parameters:

package (str) – Distribution name.
slot (str) – Version (release) or git-<ref> (checkout).
remove_env (bool) – Also delete a release’s environment directory.

Return type:

bool

plesty.server.model.device_manager._now() → str

Return type:: str