plesty.server.model.purge ========================= .. py:module:: plesty.server.model.purge .. autoapi-nested-parse:: 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 :func:`remove`'s caller's problem, and the uninstaller stops the servers first. Attributes ---------- .. autoapisummary:: plesty.server.model.purge.GROUPS Classes ------- .. autoapisummary:: plesty.server.model.purge.Removable Functions --------- .. autoapisummary:: plesty.server.model.purge.removables plesty.server.model.purge._entries plesty.server.model.purge.items plesty.server.model.purge._remembered_fleet plesty.server.model.purge.by_key plesty.server.model.purge.remove plesty.server.model.purge.remove_home Module Contents --------------- .. py:class:: Removable One thing an uninstall can be asked to remove. :ivar key: Stable name, used on the command line and in a wizard. :ivar label: Short name for a check box. :ivar detail: What losing it costs, in a sentence an operator can decide on. :ivar paths: Where it lives; missing paths are simply nothing to remove. :ivar keep_dir: Empty the directory but keep it, rather than removing it. :ivar group: The part of :func:`removables` an item of :func:`items` is in; empty for a part itself. .. py:attribute:: key :type: str .. py:attribute:: label :type: str .. py:attribute:: detail :type: str .. py:attribute:: paths :type: tuple[pathlib.Path, Ellipsis] .. py:attribute:: keep_dir :type: bool :value: False .. py:attribute:: group :type: str :value: '' .. py:method:: 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. .. py:method:: 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. .. py:function:: 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. :param home: The bench home. :returns: The removable items, whether or not they exist on disk. .. py:data:: GROUPS :type: tuple[tuple[str, str], Ellipsis] :value: (('logs', 'Logs and job records'), ('state', 'Process state'), ('tools', 'Tools the bench... .. py:function:: _entries(directory: pathlib.Path) -> list[pathlib.Path] The entries of *directory* by name; none when it is missing or unreadable. .. py:function:: items(home: plesty.server.model.home.Home) -> list[Removable] Everything an uninstall may remove from *home*, one item per thing (#34). Where :func:`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 :data:`GROUPS` order. :param home: The bench home. :returns: The items present in *home*. .. py:function:: _remembered_fleet(home: plesty.server.model.home.Home) -> pathlib.Path | None The fleet the console used last, or ``None`` when it remembers none. .. py:function:: by_key(home: plesty.server.model.home.Home, keys: collections.abc.Iterable[str]) -> list[Removable] Select what to remove by key: a part of :func:`removables` or an item of :func:`items`. :param home: The bench home. :param keys: 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 :func:`removables` defines, then the selected items in the order :func:`items` lists them. :raises ValueError: If a key names nothing. .. py:function:: 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. :param items: What to remove. :returns: ``(path, reason)`` for each path that survived. .. py:function:: remove_home(home: plesty.server.model.home.Home) -> list[tuple[pathlib.Path, str]] Remove the bench home entirely. :param home: The bench home. :returns: ``(path, reason)`` if it could not be removed, else an empty list.