plesty.server.model.purge

What an uninstall may remove, itemised — so it is a choice and not a guess.

Uninstalling the application and wiping the bench are different acts. A module author reinstalling a build wants their fleet, their .env files and their installed device modules left alone; someone decommissioning a lab PC wants the whole thing gone. The uninstaller could only ever do the first, so the second was done by hand, in a directory whose layout nobody remembers.

This describes the parts and what each one costs to lose, so a wizard can ask and a command can act, and neither has to know the directory layout. The descriptions are what an operator reads before ticking a box: each says what goes and what it means, not which folder it is.

Nothing here deletes anything a running bench needs to keep working — that is remove()’s caller’s problem, and the uninstaller stops the servers first.

Attributes

GROUPS

Classes

Removable

One thing an uninstall can be asked to remove.

Functions

`removables`(→ list[Removable])	Describe everything an uninstall may be asked to remove from home.
`_entries`(→ list[pathlib.Path])	The entries of directory by name; none when it is missing or unreadable.
`items`(→ list[Removable])	Everything an uninstall may remove from home, one item per thing (#34).
`_remembered_fleet`(→ pathlib.Path \| None)	The fleet the console used last, or `None` when it remembers none.
`by_key`(→ list[Removable])	Select what to remove by key: a part of `removables()` or an item of `items()`.
`remove`(→ list[tuple[pathlib.Path, str]])	Delete every path of every item, reporting what could not go.
`remove_home`(→ list[tuple[pathlib.Path, str]])	Remove the bench home entirely.

Module Contents

class plesty.server.model.purge.Removable

One thing an uninstall can be asked to remove.

Variables:

key – Stable name, used on the command line and in a wizard.
label – Short name for a check box.
detail – What losing it costs, in a sentence an operator can decide on.
paths – Where it lives; missing paths are simply nothing to remove.
keep_dir – Empty the directory but keep it, rather than removing it.
group – The part of removables() an item of items() is in; empty for a part itself.

key: str

label: str

detail: str

paths: tuple[pathlib.Path, Ellipsis]

keep_dir: bool = False

group: str = ''

size() → int

Return how many bytes this item currently occupies.

Returns:: The total size of every file under its paths; 0 when none of them exists.
Return type:: int

present() → bool

Whether there is anything here worth removing.

An existing but empty directory is not: a bench creates its whole layout on first use, so logs/ exists from the start — and holds an empty logs/jobs/ besides, which is why this counts files and not entries. A wizard offering to remove an empty tree is offering nothing, and teaches an operator to distrust the rest of what it says.

Returns:: Whether any path is a file, or a directory containing one.
Return type:: bool

plesty.server.model.purge.removables(home: plesty.server.model.home.Home) → list[Removable]

Describe everything an uninstall may be asked to remove from home.

Ordered by how much it hurts to lose, cheapest first, because that is the order someone works down a list of check boxes.

Parameters:: home (plesty.server.model.home.Home) – The bench home.
Returns:: The removable items, whether or not they exist on disk.
Return type:: list[Removable]

plesty.server.model.purge.GROUPS: tuple[tuple[str, str], Ellipsis] = (('logs', 'Logs and job records'), ('state', 'Process state'), ('tools', 'Tools the bench...

plesty.server.model.purge._entries(directory: pathlib.Path) → list[pathlib.Path]

The entries of directory by name; none when it is missing or unreadable.

Parameters:: directory (pathlib.Path)
Return type:: list[pathlib.Path]

plesty.server.model.purge.items(home: plesty.server.model.home.Home) → list[Removable]

Everything an uninstall may remove from home, one item per thing (#34).

Where removables() offers five parts, this names what is in them — each installed module, each fleet, each device’s configuration, each experiment’s runs kept in the home — so an operator can keep the one fleet and drop the rest. Only what is on disk is listed. Each item’s group is its part, and the list is in GROUPS order.

Parameters:: home (plesty.server.model.home.Home) – The bench home.
Returns:: The items present in home.
Return type:: list[Removable]

plesty.server.model.purge._remembered_fleet(home: plesty.server.model.home.Home) → pathlib.Path | None

The fleet the console used last, or None when it remembers none.

Parameters:: home (plesty.server.model.home.Home)
Return type:: pathlib.Path | None

plesty.server.model.purge.by_key(home: plesty.server.model.home.Home, keys: collections.abc.Iterable[str]) → list[Removable]

Select what to remove by key: a part of removables() or an item of items().

Parameters:

home (plesty.server.model.home.Home) – The bench home.
keys (collections.abc.Iterable[str]) – Keys to select; unknown ones are refused rather than ignored, because a typo in an uninstall command must not silently keep data the operator asked to be rid of.

Returns:

The selected parts, in the order removables() defines, then the selected items in the order items() lists them.

Raises:

ValueError – If a key names nothing.

Return type:

list[Removable]

plesty.server.model.purge.remove(items: collections.abc.Sequence[Removable]) → list[tuple[pathlib.Path, str]]

Delete every path of every item, reporting what could not go.

A path that will not delete — a file another process holds open is the usual reason on Windows — is collected and reported rather than raised on: an uninstall that stops at the first locked file leaves more behind than one that carries on and says what it could not take.

Parameters:: items (collections.abc.Sequence[Removable]) – What to remove.
Returns:: (path, reason) for each path that survived.
Return type:: list[tuple[pathlib.Path, str]]

plesty.server.model.purge.remove_home(home: plesty.server.model.home.Home) → list[tuple[pathlib.Path, str]]

Remove the bench home entirely.

Parameters:: home (plesty.server.model.home.Home) – The bench home.
Returns:: (path, reason) if it could not be removed, else an empty list.
Return type:: list[tuple[pathlib.Path, str]]