Skip to content

livery.toolroom.store._home

livery.toolroom.store._home

The store's home: one directory per machine, shared by every checkout.

Under the home: store/, the strongroom store with the tools and urls namespaces; tools/<name>@<version>/, the views of the tools' trees a shell runs from; uv/ and npm/, the delegated kinds' directories; locks/, one file per tool version, which a supply holds so that one process at a time supplies that version. Nothing here reads an environment variable: the caller passes the home, toolroom's machinery its data directory, hse its own.

Reach for livery.toolroom.store.Home and its open_store.

Classes:

Name Description
Home

The store's directories under one root.

Attributes:

Name Type Description
TOOLS

The namespace of installed tools: tools/<name>@<version> names the

URLS

The namespace of URL-keyed downloads, the convention strongroom

NAMESPACES

The store's namespaces. tools/<name>@<version> names the tree a

TOOLS module-attribute

TOOLS = 'tools'

The namespace of installed tools: tools/<name>@<version> names the extracted archive's tree; write-once, so a version never changes under a checkout that pinned it. tools/index/<name> names the tree the catalogue last read for the tool, so a sweep keeps the records, the versions and the surfaces a read fetched.

URLS module-attribute

URLS = 'urls'

The namespace of URL-keyed downloads, the convention strongroom publishes; volatile.

NAMESPACES module-attribute

NAMESPACES = (Namespace(TOOLS, 'volatile'), Namespace(URLS, 'volatile'))

The store's namespaces. tools/<name>@<version> names the tree a version runs from and moves by compare-and-swap when the record's layout for the version changes; the deployment that produced the tree is recorded beside the ref. The artifact never changes under a version, since landing verifies its bytes.

Home dataclass

Home(root: Path)

The store's directories under one root.

Attributes:

Name Type Description
root Path

The home: Home.under(data_dir) for the machinery, under the runner's data directory; whatever the consumer passes otherwise.

Methods:

Name Description
under

The store's home under a runner's data directory, toolroom in it.

tool_dir

The view of name at version.

lock

The file a supply of name at version holds while it works.

open_store

Open the home's strongroom store, creating it on first use.

root instance-attribute

root: Path

store property

store: Path

The strongroom store.

tools property

tools: Path

Where each tool version's view lives, tools/<name>@<version>.

uv property

uv: Path

The uv tool installs, one directory per <name>@<version>, and pythons.

npm property

npm: Path

The npm installs, one directory per <name>@<version>, by either runtime.

dotnet property

dotnet: Path

The dotnet tool installs, one directory per <name>@<version>.

locks property

locks: Path

The supply locks, one file per <name>@<version>.lock.

under classmethod

under(data_dir: Path) -> Home

The store's home under a runner's data directory, toolroom in it.

Source code in packages/toolroom-store/src/livery/toolroom/store/_home.py
@classmethod
def under(cls, data_dir: Path) -> Home:
    """The store's home under a runner's data directory, `toolroom` in it."""
    return cls(data_dir / "toolroom")

tool_dir

tool_dir(name: str, version: str) -> Path

The view of name at version.

Source code in packages/toolroom-store/src/livery/toolroom/store/_home.py
def tool_dir(self, name: str, version: str) -> Path:
    """The view of *name* at *version*."""
    return self.tools / f"{name}@{version}"

lock

lock(name: str, version: str) -> Path

The file a supply of name at version holds while it works.

Source code in packages/toolroom-store/src/livery/toolroom/store/_home.py
def lock(self, name: str, version: str) -> Path:
    """The file a supply of *name* at *version* holds while it works."""
    return self.locks / f"{name}@{version}.lock"

open_store

open_store(*, sources: Iterable[Source] = (), offline: bool = False) -> Store

Open the home's strongroom store, creating it on first use.

A store that exists is opened with the same namespaces it was created with; a directory that holds another layout refuses as strongroom refuses it. sources are the tiers the store consults for an object it lacks, and offline keeps it from every origin.

Source code in packages/toolroom-store/src/livery/toolroom/store/_home.py
def open_store(
    self, *, sources: Iterable[Source] = (), offline: bool = False
) -> Store:
    """Open the home's strongroom store, creating it on first use.

    A store that exists is opened with the same namespaces it was
    created with; a directory that holds another layout refuses
    as strongroom refuses it. *sources* are the tiers the store
    consults for an object it lacks, and *offline* keeps it from
    every origin.
    """
    if (self.store / "strongroom.json").is_file():
        return Store.open(
            self.store, namespaces=NAMESPACES, sources=sources, offline=offline
        )
    self.root.mkdir(parents=True, exist_ok=True)
    return Store.create(
        self.store, namespaces=NAMESPACES, sources=sources, offline=offline
    )