API Reference¶

def check(self, root: Path, folders: dict[str, str]) -> None:
    """Raise :class:`Skip` when the guard is not satisfied.

    Args:
        root: Repository root.
        folders: Resolved folder settings, e.g. ``{"source_folder": "src"}``.

    Raises:
        Skip: When the tool is absent, or the file is missing, or the folder is
            missing, or the folder holds no file matching ``glob``.

    Examples:
        A satisfied guard returns nothing, which is the whole of its success case:

        >>> import tempfile
        >>> from pathlib import Path
        >>> tmp = tempfile.TemporaryDirectory()
        >>> root = Path(tmp.name)
        >>> (root / "src").mkdir()
        >>> folders = {"source_folder": "src", "tests_folder": "tests"}
        >>> Guard("source_folder").check(root, folders)

        Each way of not being satisfied raises :class:`Skip` carrying the line the
        runner prints, and ``folder`` is resolved through *folders* -- so the guard
        names a setting and never a path:

        >>> for guard in (
        ...     Guard("tests_folder"),
        ...     Guard("source_folder", glob="test_*.py"),
        ...     Guard(file="Cargo.toml"),
        ...     Guard(tool="a-tool-nobody-has"),
        ... ):
        ...     try:
        ...         guard.check(root, folders)
        ...     except Skip as exc:
        ...         print(exc)
        tests_folder 'tests' not found
        no test_*.py below 'src'
        no Cargo.toml
        a-tool-nobody-has not found

        ``reason`` replaces the generated message wherever a task has something more
        useful to say:

        >>> try:
        ...     Guard("tests_folder", glob="test_*.py", reason="no test files found").check(root, folders)
        ... except Skip as exc:
        ...     print(exc)
        no test files found
        >>> tmp.cleanup()
    """
    # The first unmet precondition wins, so `reason` overrides whichever message that
    # clause generated -- see the note above the class for why the clauses live in a
    # module-level generator rather than in this body or in a second method.
    for unmet, message in _clauses(self, root, folders):
        if unmet:
            raise Skip(self.reason or message)

def __post_init__(self) -> None:
    """Normalise the list fields, then validate the enumerated and numeric ones.

    Each step is a helper, so this method's own branch count is zero and the ceiling the
    history above describes no longer applies to it. A new validated setting adds a call
    here and its branches to its own helper -- which is what makes "one branch per
    validated setting" stop being an open-ended growth rule.

    Raises:
        ValueError: When ``typechecker`` is not one of ty, mypy, both,
            ``coverage_fail_under`` is outside 0-100, ``complexity_max`` is below 1,
            ``layers`` names a layer that does not exist, :attr:`root` is not an
            existing directory, or a ``*_folder`` escapes it. Each helper below raises
            for its own settings and documents the message it uses.
    """
    self._coerce_sequence_fields()
    self._validate_layers()
    self._validate_typechecker()
    self._validate_coverage()
    self._validate_complexity_max()
    # Order matters, and only between these two: `_validate_folders` asks whether a
    # setting escapes the root, which presupposes there is a root to escape.
    self._validate_root()
    self._validate_folders()

@staticmethod
def field_for(name: str) -> str:
    """Normalise a make-style variable name to a field name.

    Public because the spelling rule is not private to the layer readers below: the
    ``print`` command has to answer for ``SOURCE_FOLDER`` exactly as ``.rhiza/.env``
    does, and a second normaliser written against the same rule is a second thing to
    keep in step. A caller outside this module asking "which field is this?" is asking
    :class:`Config`, so it is spelled as a question :class:`Config` can be asked.

    The ``RHIZA_`` prefix is optional, so it is stripped -- but only when what remains
    is actually a field. Stripping unconditionally made ``RHIZA_CHECKS`` resolve to
    the unknown field ``checks``, so the setting was silently dropped and
    ``rhiza_checks`` was reachable from the environment only as ``RHIZA_RHIZA_CHECKS``.
    Trying the whole name as a fallback fixes that without disturbing the fields whose
    prefix *is* redundant: ``RHIZA_CI_OS_MATRIX`` still resolves to ``ci_os_matrix``,
    and the doubled spelling keeps working for anyone who found it.

    Args:
        name: e.g. ``RHIZA_CI_OS_MATRIX``, ``SOURCE_FOLDER`` or ``rhiza-checks``.

    Returns:
        e.g. ``ci_os_matrix``, ``source_folder``, ``rhiza_checks``.

    Examples:
        >>> Config.field_for("SOURCE_FOLDER"), Config.field_for("rhiza-checks")
        ('source_folder', 'rhiza_checks')
    """
    lowered = name.lower().replace("-", "_")
    stripped = lowered.removeprefix("rhiza_")
    if stripped in _FIELD_NAMES or lowered not in _FIELD_NAMES:
        return stripped
    return lowered

@classmethod
def load(cls, root: Path | None = None, **overrides: Any) -> Config:
    """Build a config by walking the six layers in order.

    Args:
        root: Repository root; defaults to the current directory.
        **overrides: Layer 5, the command-line flags. ``None`` values are ignored so
            an unset flag does not shadow a configured value.

    Returns:
        The resolved config.

    Examples:
        Layer 4 -- ``[tool.rhiza-task]`` in the manifest -- over the dataclass
        defaults, with an unset flag passed as ``None`` and correctly *not* shadowing
        what the manifest said:

        >>> import tempfile
        >>> from pathlib import Path
        >>> manifest = '''
        ... [tool.rhiza-task]
        ... source_folder = "lib"
        ... coverage_fail_under = 100
        ... uv_sync_args = "--group test"
        ... '''
        >>> with tempfile.TemporaryDirectory() as tmp:
        ...     root = Path(tmp)
        ...     _ = (root / "pyproject.toml").write_text(manifest)
        ...     cfg = Config.load(root, source_folder=None, typechecker="mypy")
        >>> cfg.source_folder, cfg.coverage_fail_under, cfg.typechecker
        ('lib', 100, 'mypy')

        A ``tuple[str, ...]`` field given as a string is split on whitespace rather
        than one character per argument, which is the make layer's own format and the
        bug ``__post_init__`` exists to prevent:

        >>> cfg.uv_sync_args
        ('--group', 'test')

        The manifest that carried the table is also what put the repository in a
        layer, and the check set follows from the layers rather than from a list
        anyone maintains:

        >>> cfg.layers
        ('python',)
        >>> cfg.rhiza_checks[-1]
        'pytest_rhiza.checks.test_docstrings'

        An unreadable setting fails here, before any tool is provisioned -- the shell
        ``case`` that used to validate it ran after:

        >>> with tempfile.TemporaryDirectory() as tmp:
        ...     Config.load(Path(tmp), typechecker="pyright")
        Traceback (most recent call last):
            ...
        ValueError: typechecker must be one of ty, mypy, both (got 'pyright')
    """
    root = (root or Path.cwd()).absolute()
    raw: dict[str, Any] = {}
    raw.update(_from_env_file(root / ".rhiza" / ".env"))
    raw.update(_from_rhiza_toml(root / "rhiza.toml"))
    # Cargo before pyproject, so a repo carrying both -- a Rust crate with a Python
    # binding package, say -- resolves to the same settings as the Python-only repo it
    # grew out of, rather than to whichever manifest happened to be read last.
    raw.update(_from_manifest(root / "Cargo.toml"))
    raw.update(_from_manifest(root / "pyproject.toml"))
    raw.update(_from_environ(os.environ))
    raw.update({k: v for k, v in overrides.items() if v is not None})

    # .python-version wins over a configured python_version for the reason python.mk
    # reads it: it is what uv itself honours, so a second source of truth could only
    # ever disagree.
    pv = root / ".python-version"
    if pv.is_file() and (text := pv.read_text().strip()):
        raw["python_version"] = text

    known = {f.name for f in fields(cls)} - {"root"}
    return cls(root=root, **{k: v for k, v in raw.items() if k in known})

def path(self, folder_field: str) -> Path:
    """Resolve a folder field to an absolute path.

    No containment check here: :meth:`_validate_folders` did it once at construction,
    so every field this resolves is already known to stay under ``root``.

    Args:
        folder_field: A field name such as ``source_folder``.

    Returns:
        The absolute path.
    """
    # The annotation is load-bearing under `mypy --strict`: `getattr` is typed to return
    # `Any`, `Path / Any` is `Any` too, and returning that from a `-> Path` function is
    # what `no-any-return` reports. Naming the type here is also the honest spelling --
    # every field this reaches ends in `_folder` and holds a `str`, which is the same
    # assumption `folders` above encodes in its `dict[str, str]`.
    value: str = getattr(self, folder_field)
    return self.root / value

def exit_code(self) -> int:
    """Return the aggregate exit status: 0 when nothing failed or was blocked, else non-zero.

    The first real failure's own code is propagated where there is one, so a caller can
    still distinguish e.g. pytest's 2 from a gate that merely exited 1. "First real"
    means the first :attr:`Status.FAILED` entry: a :attr:`Status.BLOCKED` dependent has
    no process of its own, and the failure that blocked it is recorded earlier in the
    list, so it is the one that speaks. Anything outside a shell's 1-255 range -- a
    code of 0, or the negative signal number ``subprocess`` reports for a killed child
    -- collapses to 1, since it cannot be handed to ``exit`` as-is.

    Returns:
        0 when nothing failed or was blocked; else the first failing task's exit status,
        or 1 when that status is unusable.

    Examples:
        An empty run, and a run whose only entry is a skip, both succeed -- a skip is
        an outcome, not a failure, and ``--strict`` is the switch that changes that:

        >>> state = Run()
        >>> state.exit_code()
        0
        >>> state.results.append(Result("fmt", Status.SKIPPED, "no .pre-commit-config.yaml"))
        >>> state.failed, state.exit_code()
        (False, 0)

        A failure, and the dependent it blocks, are both non-zero -- and pytest's own 2
        is what the run exits with, not a flattened 1:

        >>> state.results.append(Result("test", Status.FAILED, "tests failed", 2))
        >>> state.results.append(Result("book", Status.BLOCKED, "prerequisite failed: test"))
        >>> state.failed, state.exit_code()
        (True, 2)
        >>> state.status_of("book") is Status.BLOCKED
        True
        >>> state.status_of("todos") is None
        True

        A failure with no usable code of its own -- a guard's own verdict rather than a
        child process's, or a blocked dependent standing alone -- is 1:

        >>> Run([Result("doctor", Status.FAILED, "missing or outdated: uv")]).exit_code()
        1
        >>> Run([Result("book", Status.BLOCKED, "prerequisite failed: test")]).exit_code()
        1
    """
    if not self.failed:
        return 0
    code = next((r.code for r in self.results if r.status is Status.FAILED), 1)
    return code if 1 <= code <= 255 else 1

def status_of(self, name: str) -> Status | None:
    """Return the recorded status of a task, if it ran.

    Args:
        name: Task name.

    Returns:
        The status, or None when the task was not attempted.
    """
    return next((r.status for r in self.results if r.name == name), None)