Skip to content

livery.workshop._influence

livery.workshop._influence

Which files a workspace step reads, and which of them a change touched.

A workspace step declares its inputs on its record (livery.workshop._steps.StepRecord inputs): the files it judges, whether it judges each changed one on its own or runs whole when any changed, and what widens it to every file it reads. The gate hands every step the paths changed since the tree it measures from, and livery.workshop._influence.select answers for one step: skip it, judge these files, or judge everything.

Two widenings hold for every step. A run that knows nothing of what changed (the whole gate) judges everything. A step whose own code changed judges everything, since its rule moved, not the files: the member package that ships it changed under its sources, or, for a step installed from an index, the lock moved.

Classes:

Name Description
Changes

What changed since the tree a gate measures from.

Inputs

The files a workspace step reads, as the affected engine asks.

Selection

What one step judges in a run.

Functions:

Name Description
reads

Whether inputs read path: a pattern of its reads names it, and no ignore.

provider_of

The member package whose sources ship extension, by its path; empty if none.

select

What a step with inputs judges for changes.

Attributes:

Name Type Description
LOCK
Patterns
WHOLE
SKIP

LOCK module-attribute

LOCK = 'uv.lock'

Patterns module-attribute

Patterns = tuple[str, ...] | Callable[[Path], tuple[str, ...]]

WHOLE module-attribute

WHOLE = Selection(whole=True)

SKIP module-attribute

SKIP = Selection(whole=False)

Changes dataclass

Changes(root: Path, paths: tuple[str, ...], before: str = '')

What changed since the tree a gate measures from.

Attributes:

Name Type Description
root Path

The workspace root.

paths tuple[str, ...]

The changed paths, root-relative posix, deleted ones included.

before str

The commit or tree the paths were taken from; empty when the caller named the paths itself.

Methods:

Name Description
removed

The changed paths the working tree no longer holds: deleted or moved.

text_before

path where the change is measured from; empty if unknown.

root instance-attribute

root: Path

paths instance-attribute

paths: tuple[str, ...]

before class-attribute instance-attribute

before: str = ''

removed

removed() -> tuple[str, ...]

The changed paths the working tree no longer holds: deleted or moved.

Source code in packages/workshop/src/livery/workshop/_influence.py
def removed(self) -> tuple[str, ...]:
    """The changed paths the working tree no longer holds: deleted or moved."""
    return tuple(path for path in self.paths if not (self.root / path).exists())

text_before

text_before(path: str) -> str

path where the change is measured from; empty if unknown.

Source code in packages/workshop/src/livery/workshop/_influence.py
def text_before(self, path: str) -> str:
    """*path* where the change is measured from; empty if unknown."""
    if not self.before:
        return ""

    return git.file_at(self.root, self.before, path)

Inputs dataclass

Inputs(reads: Patterns, per_file: bool = True, widens: Patterns = (), on_removal: bool = False, widen: Callable[[Changes], bool] | None = None, ignores: tuple[str, ...] = ())

The files a workspace step reads, as the affected engine asks.

Attributes:

Name Type Description
reads Patterns

The files the step judges.

per_file bool

Whether the step judges each changed file it reads on its own; otherwise a change to any of them runs it whole.

widens Patterns

Files the step does not judge whose change runs it over everything it reads: the contracts, for a step of what is composed from them.

on_removal bool

Whether a deleted or moved file anywhere runs it whole: a link checker's, since a link in an unchanged page may point at what went away.

widen Callable[[Changes], bool] | None

The step's own further reason to run whole, given the changes: a link checker's removed heading.

ignores tuple[str, ...]

Files that never count, though a pattern above names them: a package's readme beside its manifests.

reads instance-attribute

reads: Patterns

per_file class-attribute instance-attribute

per_file: bool = True

widens class-attribute instance-attribute

widens: Patterns = ()

on_removal class-attribute instance-attribute

on_removal: bool = False

widen class-attribute instance-attribute

widen: Callable[[Changes], bool] | None = None

ignores class-attribute instance-attribute

ignores: tuple[str, ...] = ()

Selection dataclass

Selection(whole: bool, files: tuple[str, ...] = ())

What one step judges in a run.

Attributes:

Name Type Description
whole bool

Whether it judges everything it reads.

files tuple[str, ...]

Otherwise, the changed files it judges; with whole false and no files, the step does not run.

whole instance-attribute

whole: bool

files class-attribute instance-attribute

files: tuple[str, ...] = ()

runs property

runs: bool

Whether the step runs at all.

reads

reads(inputs: Inputs, root: Path, path: str) -> bool

Whether inputs read path: a pattern of its reads names it, and no ignore.

Source code in packages/workshop/src/livery/workshop/_influence.py
def reads(inputs: Inputs, root: Path, path: str) -> bool:
    """Whether *inputs* read *path*: a pattern of its reads names it, and no ignore."""
    if _matched(inputs.ignores, (path,)):
        return False
    return bool(_matched(_patterns(inputs.reads, root), (path,)))

provider_of

provider_of(extension: str, packages: tuple[Package, ...]) -> str

The member package whose sources ship extension, by its path; empty if none.

An extension installed from an index has no member: its code moves with the lock instead.

Source code in packages/workshop/src/livery/workshop/_influence.py
def provider_of(extension: str, packages: tuple[Package, ...]) -> str:
    """The member package whose sources ship *extension*, by its path; empty if none.

    An extension installed from an index has no member: its code moves
    with the lock instead.
    """
    try:
        spec = importlib.util.find_spec(extension)
    except (ImportError, ValueError):
        return ""
    if spec is None:
        return ""
    places = [*(spec.submodule_search_locations or ())]
    if spec.origin:
        places.append(str(Path(spec.origin).parent))
    for place in places:
        resolved = Path(place).resolve()
        for package in packages:
            if resolved.is_relative_to(package.directory.resolve()):
                return package.path
    return ""

select

select(inputs: Inputs, changes: Changes | None, *, provider: str = '') -> Selection

What a step with inputs judges for changes.

Everything when nothing is known of what changed, when the step's own code changed (provider, the member that ships it, changed under src/; for a step with no member, the lock moved), or when a widening input changed; else the changed files it reads, each on its own, or everything when it does not judge per file; nothing when no file it reads changed.

Source code in packages/workshop/src/livery/workshop/_influence.py
def select(inputs: Inputs, changes: Changes | None, *, provider: str = "") -> Selection:
    """What a step with *inputs* judges for *changes*.

    Everything when nothing is known of what changed, when the step's
    own code changed (*provider*, the member that ships it, changed
    under ``src/``; for a step with no member, the lock moved), or
    when a widening input changed; else the changed files it reads,
    each on its own, or everything when it does not judge per file;
    nothing when no file it reads changed.
    """
    if changes is None:
        return WHOLE
    paths = tuple(
        path for path in changes.paths if not _matched(inputs.ignores, (path,))
    )
    if provider:
        if any(path.startswith(f"{provider}/src/") for path in paths):
            return WHOLE
    elif LOCK in paths:
        return WHOLE
    root = changes.root
    if _matched(_patterns(inputs.widens, root), paths):
        return WHOLE
    if inputs.on_removal and changes.removed():
        return WHOLE
    if inputs.widen is not None and inputs.widen(changes):
        return WHOLE
    touched = _matched(_patterns(inputs.reads, root), paths)
    if not touched:
        return SKIP
    return Selection(whole=False, files=touched) if inputs.per_file else WHOLE