drybag 0.7.1__py3-none-any.whl

drybag/__init__.py

@@ -0,0 +1,9 @@
+"""drybag: private layers for coding agents."""
+
+__version__ = "0.7.1"
+
+# The public repository, spelled once — the install hints derive from it. `scripts/release.py
+# check` reads `__version__` through a regex anchored on that name alone, and does not see these
+# two lines.
+REPOSITORY_SLUG = "dry-bag/drybag"
+REPOSITORY_URL = f"https://github.com/{REPOSITORY_SLUG}"

drybag/__main__.py

@@ -0,0 +1,3 @@
+from drybag.cli import main
+
+raise SystemExit(main())

drybag/areas.py

@@ -0,0 +1,114 @@
+"""Areas discovered by name: the half `drybag.cli`, `drybag.hooks.registry` and
+`drybag.doctor.registry` share.
+
+Three submodules are discovered, each by the module that reads it: an area's `commands.py` gives
+it a CLI group, its `hooks.py` hook handlers, and its `doctor.py` rows in `drybag doctor`'s
+report. The CLI frame and the hook registry import through `area_modules`, so an area that
+fails to import fails them; the report imports through `area_imports`, which hands that failure
+over in the area's place, because the report must outlive any one area's broken code.
+
+A leaf module on purpose. `cli.py` imports every area through this discovery, so an area that
+imported back into `cli.py` would constrain what the frame may ever import; the aliases and
+the loop live here instead, and `cli` re-exports the aliases.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import pkgutil
+from collections.abc import Callable
+from pathlib import Path
+from types import ModuleType
+from typing import TYPE_CHECKING
+
+import drybag
+
+if TYPE_CHECKING:
+    SubParsers = argparse._SubParsersAction[argparse.ArgumentParser]
+else:
+    # Generic only in typeshed: subscripting the class at runtime raises TypeError.
+    SubParsers = argparse._SubParsersAction
+
+Registrar = Callable[[SubParsers], None]
+
+# The sides, by the first part of a module's path under `src/drybag/`; a module neither side
+# lists is the core's. CONTRIBUTING.md, "Areas", says what each holds and the rules between them,
+# and `tests/boundaries/test_delivery.py` holds those rules. They read code, so they cannot see
+# `templates/overlay/`, data only the `overlay` area reads, which sits in the core.
+DELIVERY_AREAS: frozenset[str] = frozenset(
+    {
+        "attach",
+        "hints",
+        "memory",
+        "overlay",
+        "setup",
+        "sync",
+    }
+)
+PACK_PACKAGES: frozenset[str] = frozenset(
+    {
+        "docs",
+        "guards",
+    }
+)
+CORE_AREAS: frozenset[str] = frozenset(
+    {
+        "doctor",
+        "hooks",
+    }
+)
+
+
+def _has_submodule(area: str, submodule: str) -> bool:
+    """A filesystem probe: it imports only the `<area>.<submodule>` modules that exist, instead
+    of importing every area package merely to test whether one of them does.
+
+    That saving is latent rather than realised on today's frame: `main()` runs
+    `discover_registrars()` to build the full argparse parser before argparse can dispatch to
+    `hook`, and building that parser already imports `drybag.config`, `drybag.config.schema`,
+    `drybag.presets`, `drybag.release` and `drybag.release.pins` — so by the time this
+    probe runs for `hooks`, those packages are already loaded. The probe would only pay off if
+    discovery ever registered just the area named on the command line instead of the full set.
+    """
+    for root in drybag.__path__:
+        directory = Path(root) / area
+        if (directory / f"{submodule}.py").is_file():
+            return True
+        if (directory / submodule / "__init__.py").is_file():
+            return True
+    return False
+
+
+def _qualified(submodule: str) -> list[str]:
+    """The qualified name of each `drybag.<area>.<submodule>` that exists, in area-name
+    order: the one probe both importers below read."""
+    return [
+        f"drybag.{entry.name}.{submodule}"
+        for entry in sorted(pkgutil.iter_modules(drybag.__path__), key=lambda m: m.name)
+        if entry.ispkg and _has_submodule(entry.name, submodule)
+    ]
+
+
+def area_modules(submodule: str) -> list[ModuleType]:
+    """Every `drybag.<area>.<submodule>` that exists, in area-name order, no shared registry."""
+    return [importlib.import_module(name) for name in _qualified(submodule)]
+
+
+def area_imports(submodule: str) -> list[tuple[str, ModuleType | Exception]]:
+    """Every `drybag.<area>.<submodule>` that exists, in area-name order, each under its
+    qualified name with the module, or with the exception its import raised in the module's place.
+
+    For a reader that must outlive an area's broken code: `doctor`'s report, which is what a user
+    has left when everything else is broken, so one area's `doctor.py` that raises on import must
+    cost that area's rows and not the report. The failure is handed over rather than judged here,
+    because what it costs is the reader's to say. `Exception` and not `BaseException`, as for a
+    check that raises: a `KeyboardInterrupt` during discovery stops the command.
+    """
+    found: list[tuple[str, ModuleType | Exception]] = []
+    for name in _qualified(submodule):
+        try:
+            found.append((name, importlib.import_module(name)))
+        except Exception as exc:  # an area's broken import is handed over, never raised here
+            found.append((name, exc))
+    return found

drybag/attach/__init__.py

@@ -0,0 +1,18 @@
+"""Bind a repository to the machine owner's private overlay, and take back what binding wrote.
+
+An area, discovered by name: `commands.py` gives it the `attach` and `detach` groups and
+`api.py` is what another area may import. `detach` takes back what `attach` wrote and leaves the
+overlay's record of the binding, `projects/<name>/project.toml`, where it is. It writes nothing
+a repository chose — the overlay root comes from the machine file, the store is that overlay's
+own directory for this project, and what the overlay grants is shown on one screen rather than
+asked about.
+"""
+
+# The command that binds this checkout to its share of the overlay, which every remedy of this area
+# names, so a reader is never sent to two spellings of one command. No `--store`: the store is
+# derived from the machine-recorded overlay, and a placeholder an agent runs as written exits 2.
+# Here and not in `doctor.py` because `hooks.py` names it too, and discovery imports `hooks.py`
+# unguarded for every hook: an edge to the report's module would let a defect there stop every
+# hook, and load the report on each one. Not annotated `Final`: an area's `__init__.py` imports
+# nothing, `typing` included (`tests/test_surfaces.py`).
+ATTACH_COMMAND = "drybag attach"

drybag/attach/api.py

@@ -0,0 +1,75 @@
+"""The attach area's import surface: everything another area may import from it.
+
+The list is chosen from what consumers outside this area actually reach for, and every name on
+it carries the reason beside it — a surface that survives a trim with no explanation is what
+made the trim necessary. An area that needs something absent from this list grows it
+deliberately, in a commit that says which area and why — it does not import a private module of
+this area.
+
+No module under `src/` outside this area imports from here. `doctor` was the one consuming area,
+and its `attached` row is now this area's own (`attach/doctor.py`), which reaches this area's
+modules directly. What is left is what the suite
+reads from outside the area:
+
+- the ledger (`ledger`) and `AttachLedger`, because `ledger` returns it: a return
+  type absent from this list is a value a consumer can hold and cannot declare, and
+  `tests/test_surfaces.py` derives that rule rather than restating it; `Rendered`, the type of
+  its `render`, for the same rule;
+- the binding (`read_binding`, `Binding`). `Binding.state` is one of `memory.api`'s
+  `BINDING_STATES`: the vocabulary and the one classifier that decides between its members are
+  the memory area's, so this area publishes neither a copy of the set nor its own members;
+- the file an earlier release merged the overlay's hook entries into (`LOCAL_SETTINGS`), which
+  the doctor area's tests write those entries into;
+- `attach` and `Attached`, which `setup --restore` runs on each checkout the overlay's projects
+  file lists (`setup.restore`), and the type it returns, with `Carried`, the type of two of its
+  fields (`added` and `removed`), which `tests/test_surfaces.py` derives that a surface carries.
+
+**Trimmed when the `attached` row moved into this area: `overlay_entries`.** It was published for
+`doctor`'s provenance column, and went once `attach` merged no hook entry.
+
+**`setup` was not a consumer of `check`, and still is not.** This docstring used to say "`setup`
+runs `attach --check` and reads the same `Result`"; `setup` imports nothing of `check`, and
+`attach --check` is this area's own command module calling its own `attach.check`. (`setup
+--restore` does import `attach` itself, which is the bullet above.) The
+permission-diff half of the area — `check`, `diff_permissions` and the `PermissionDiff` it
+returns — was published on the strength of that sentence and left when the sentence did.
+
+**Trimmed once, and back for `setup --restore`: `attach` and `Attached`; `detach` and
+`Detached` are trimmed again since the `uninstall` that ran `detach` was deleted.** They were
+published against a second sentence of the same kind — "`tests/test_install_path.py`, the
+walkthrough that runs the four packages in the order a person does, is the other consumer, and it
+drives `attach` and
+`detach`, whose returns are `Attached` and `Detached`". That walkthrough drives the argument
+parser: `step("attach", "--store", ..., "--machine", ...)`, which is the point of it, because the
+commands' argv wiring is what it exists to exercise. It imports two surfaces,
+`drybag.doctor.api` and `drybag.memory.api`, and reaches no name on this list. The two verbs
+are this area's own command module's, and their results are read where they are returned.
+
+The claim is the same shape as the one this docstring corrected two paragraphs up, and as the
+one `setup/api.py` corrected about its own `setup` and `SetupReport` — three of them now, all
+naming a test that runs a command rather than a module that imports a name. A published surface
+argued from prose is a surface nobody measured: the first count of this list's importers
+covered `src/`, `scripts/` and `tests/` and never read the sentence, and the sentence is what
+kept the names.
+
+The ledger's place is the core's (`binding.LEDGER_FILE`, beside the binding id), because `doctor`
+reads it too; nothing outside delivery imports this area but through the crossings pinned in
+`tests/boundaries/test_delivery.py`.
+"""
+
+from drybag.attach.binding import Binding, read_binding
+from drybag.attach.permissions import LOCAL_SETTINGS
+from drybag.attach.render import Rendered
+from drybag.attach.write import Attached, AttachLedger, Carried, attach, ledger
+
+__all__ = [
+    "LOCAL_SETTINGS",
+    "AttachLedger",
+    "Attached",
+    "Binding",
+    "Carried",
+    "Rendered",
+    "attach",
+    "ledger",
+    "read_binding",
+]