Skip to content

configure

configure #

The active scratch: a process-wide default, or one scoped to the current context.

Every process on a machine shares one scratch unless told otherwise: default_root is CG_SCRATCH when set, else ~/.cache/capturegraph. configure installs the default every thread shares (an explicit path, else default_root); temporary overrides it for one with block in the calling thread or task only, so a throwaway scratch in one worker never redirects another.

scoped_scratch = ContextVar('cg_scoped_scratch', default=None) module-attribute #

The scratch overriding the default in the current context, if any.

active_scratch() #

The scratch in effect: the context's override, else the default, opened on first use.

Source code in capturegraph-lib/capturegraph/scratch/configure.py
def active_scratch() -> Scratch:
    """The scratch in effect: the context's override, else the default, opened on first use."""
    scoped = scoped_scratch.get()
    if scoped is not None:
        return scoped
    if _default is None:
        configure()
    assert _default is not None
    return _default

configure(path=None, *, max_size_gb=None, free_space_ratio=None) #

Open (or initialize) the process-wide default scratch.

Parameters:

Name Type Description Default
path str | Path | None

The scratch root. Defaults to default_root(), which every process on the machine shares.

None
max_size_gb float | None

Hard cap on the cache's byte budget, in gigabytes.

None
free_space_ratio float | None

Fraction of releasable disk the cache may claim.

None

Returns:

Type Description
Path

The configured scratch's root directory.

Source code in capturegraph-lib/capturegraph/scratch/configure.py
def configure(
    path: str | Path | None = None,
    *,
    max_size_gb: float | None = None,
    free_space_ratio: float | None = None,
) -> Path:
    """Open (or initialize) the process-wide default scratch.

    Args:
        path: The scratch root. Defaults to ``default_root()``, which every
            process on the machine shares.
        max_size_gb: Hard cap on the cache's byte budget, in gigabytes.
        free_space_ratio: Fraction of releasable disk the cache may claim.

    Returns:
        The configured scratch's root directory.
    """
    global _default
    _default = Scratch(
        Path(path) if path is not None else default_root(),
        max_size_gb=max_size_gb,
        free_space_ratio=free_space_ratio,
    )
    return _default.root

current_scratch() #

The scratch in effect without configuring one; None if unset.

Source code in capturegraph-lib/capturegraph/scratch/configure.py
def current_scratch() -> Scratch | None:
    """The scratch in effect without configuring one; ``None`` if unset."""
    return scoped_scratch.get() or _default

default_root() #

The scratch every process shares: CG_SCRATCH when set, else ~/.cache/capturegraph.

Source code in capturegraph-lib/capturegraph/scratch/configure.py
def default_root() -> Path:
    """The scratch every process shares: ``CG_SCRATCH`` when set, else ``~/.cache/capturegraph``."""
    return Path(os.environ.get(SCRATCH_ENV) or DEFAULT_ROOT).expanduser()

unconfigure() #

Forget the process-wide default, as if configure had never run.

Source code in capturegraph-lib/capturegraph/scratch/configure.py
def unconfigure() -> None:
    """Forget the process-wide default, as if ``configure`` had never run."""
    global _default
    _default = None