configure

def active_scratch() -> Scratch:
    """The scratch in effect: the context's override, else the default.

    The default is configured from ``CG_SCRATCH`` on first use.

    Raises:
        ScratchNotConfigured: If none is configured and ``CG_SCRATCH`` is unset.
    """
    scoped = scoped_scratch.get()
    if scoped is not None:
        return scoped
    if _default is None:
        configure()
    assert _default is not None
    return _default

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 ``CG_SCRATCH`` when omitted.
        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.

    Raises:
        ScratchNotConfigured: If no ``path`` is given and ``CG_SCRATCH`` is unset.
    """
    global _default
    resolved = path if path is not None else os.environ.get(SCRATCH_ENV)
    if resolved is None:
        raise ScratchNotConfigured(
            "No CaptureGraph scratch is configured. Set one with "
            "cg.scratch.configure(path), scope a throwaway one with "
            "cg.scratch.temporary(), or export the CG_SCRATCH environment variable."
        )
    _default = Scratch(
        Path(resolved),
        max_size_gb=max_size_gb,
        free_space_ratio=free_space_ratio,
    )
    return _default.root

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

def unconfigure() -> None:
    """Forget the process-wide default, as if ``configure`` had never run."""
    global _default
    _default = None