Skip to content

workspace

workspace #

The ambient live directory a body runs in, and the scratch's answer to T.new().

ScratchWorkspace is the Workspace the type system asks for fresh files and tool runs: inside a memoized call they go to the call's live directory, outside one to a live directory the value alone holds. Importing this module provides it.

active_workspace = ContextVar('cg_active_workspace', default=None) module-attribute #

The live directory of the call running in this context, if any.

ScratchWorkspace #

Bases: Workspace

Fresh files in the running call's live directory, or in one the value alone holds.

Source code in capturegraph-lib/capturegraph/scratch/values/workspace.py
class ScratchWorkspace(Workspace):
    """Fresh files in the running call's live directory, or in one the value alone holds."""

    def allocate[T: Path](self, cls: type[T], suffix: str) -> T:
        """A ``cls`` value at a fresh path in the ambient live directory.

        Outside any call, a live directory is opened for this value alone and
        held by it.
        """
        workspace = active_workspace.get()
        hold = None
        if workspace is None:
            workspace = hold = active_scratch().live_dir()
        value = cls(workspace.path / f"{uuid.uuid4().hex}{suffix}")
        if hold is not None:
            pin(value, hold)
        return value

    def run(
        self,
        owner: object,
        argv: Sequence[str | os.PathLike[str]],
        *,
        cwd: os.PathLike[str],
        env: Mapping[str, str] | None,
        timeout: float | None,
        check: bool,
        capture_output: bool,
    ) -> subprocess.CompletedProcess[bytes]:
        """``run_tool`` with the child's output streaming into ``owner``'s ``exec.log``."""
        return run_tool(
            argv,
            cwd=cwd,
            env=env,
            timeout=timeout,
            check=check,
            capture_output=capture_output,
            log=exec_log(owner),
        )

allocate(cls, suffix) #

A cls value at a fresh path in the ambient live directory.

Outside any call, a live directory is opened for this value alone and held by it.

Source code in capturegraph-lib/capturegraph/scratch/values/workspace.py
def allocate[T: Path](self, cls: type[T], suffix: str) -> T:
    """A ``cls`` value at a fresh path in the ambient live directory.

    Outside any call, a live directory is opened for this value alone and
    held by it.
    """
    workspace = active_workspace.get()
    hold = None
    if workspace is None:
        workspace = hold = active_scratch().live_dir()
    value = cls(workspace.path / f"{uuid.uuid4().hex}{suffix}")
    if hold is not None:
        pin(value, hold)
    return value

run(owner, argv, *, cwd, env, timeout, check, capture_output) #

run_tool with the child's output streaming into owner's exec.log.

Source code in capturegraph-lib/capturegraph/scratch/values/workspace.py
def run(
    self,
    owner: object,
    argv: Sequence[str | os.PathLike[str]],
    *,
    cwd: os.PathLike[str],
    env: Mapping[str, str] | None,
    timeout: float | None,
    check: bool,
    capture_output: bool,
) -> subprocess.CompletedProcess[bytes]:
    """``run_tool`` with the child's output streaming into ``owner``'s ``exec.log``."""
    return run_tool(
        argv,
        cwd=cwd,
        env=env,
        timeout=timeout,
        check=check,
        capture_output=capture_output,
        log=exec_log(owner),
    )

computing(scratch, identity, label) #

A fresh live directory to compute a call in, ambient and logged as a scope named label.

The block seals the directory or loses it: on any exception it is released, and the exception carries the tail of its exec.log as a note.

Yields:

Type Description
LiveDir

The live directory the block computes in.

Source code in capturegraph-lib/capturegraph/scratch/values/workspace.py
@contextmanager
def computing(
    scratch: Scratch,
    identity: str,
    label: str,
) -> Iterator[LiveDir]:
    """A fresh live directory to compute a call in, ambient and logged as a scope named ``label``.

    The block seals the directory or loses it: on any exception it is released,
    and the exception carries the tail of its ``exec.log`` as a note.

    Yields:
        The live directory the block computes in.
    """
    workspace = scratch.live_dir()
    with info(label, identity=identity):
        workspace_token = active_workspace.set(workspace)
        try:
            yield workspace
        except BaseException as error:
            tail = log_tail(workspace.path)
            if tail is not None:
                error.add_note(tail)
            workspace.release()
            raise
        finally:
            active_workspace.reset(workspace_token)

exec_log(value) #

Where a tool run by value logs, or None outside every live directory.

The ambient live directory's log, else that of the one value holds.

Source code in capturegraph-lib/capturegraph/scratch/values/workspace.py
def exec_log(value: object) -> Path | None:
    """Where a tool run by ``value`` logs, or ``None`` outside every live directory.

    The ambient live directory's log, else that of the one ``value`` holds.
    """
    workspace = active_workspace.get()
    if workspace is None:
        hold = hold_of(value)
        workspace = hold if isinstance(hold, LiveDir) else None
    return workspace.log if workspace is not None else None