facere 0.1.0__py3-none-any.whl

facere/__init__.py

@@ -0,0 +1,10 @@
+"""Facere, a build tool configured in plain Python. A fac.py imports it as `import facere as fac`.
+
+The user documentation ships as Markdown in this package's `doc/` directory, beside this file: read `doc/getting-started.md` first, then `doc/best-practices.md` before writing rules for a real project, and `doc/terminology.md` for any unfamiliar term.
+"""
+
+from facere._api import Input, Output, minimum_version, out, rule, task
+from facere._cli import main
+from facere._command import run
+
+__all__ = ["Input", "Output", "main", "minimum_version", "out", "rule", "run", "task"]

facere/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from facere._cli import console_main
+
+sys.exit(console_main())

facere/_api.py

@@ -0,0 +1,137 @@
+"""The decorators and helpers a fac.py calls to define rules and tasks."""
+
+import os
+import posixpath
+from collections.abc import Callable, Iterable
+from pathlib import PurePosixPath
+from typing import Annotated, Any, TypeVar, overload
+
+from facere._context import Declaration, Kind, find_context, get_context, normalize
+from facere._diagnostics import Diagnostic, FacereError, find_caller_location
+from facere._version import VERSION
+
+Input = Annotated[str, Kind.INPUT]
+Output = Annotated[str, Kind.OUTPUT]
+
+_F = TypeVar("_F", bound=Callable[..., object])
+
+
+@overload
+def rule(fn: _F, /) -> _F: ...
+
+
+@overload
+def rule(
+    *,
+    each: Iterable[tuple[Any, ...]] | None = None,
+    name: str | None = None,
+    default: bool = False,
+    **values: Any,
+) -> Callable[[_F], _F]: ...
+
+
+def rule(
+    fn: _F | None = None,
+    /,
+    *,
+    each: Iterable[tuple[Any, ...]] | None = None,
+    name: str | None = None,
+    default: bool = False,
+    **values: Any,
+) -> _F | Callable[[_F], _F]:
+    """Define rules from a function, returned unchanged.
+
+    The function's signature declares what each rule reads and writes: a parameter annotated `fac.Input` or `list[fac.Input]` holds the files or directories it reads, one annotated `fac.Output` or `list[fac.Output]` files or directories it writes, and any other parameter a value. `each=` takes an iterable of tuples, read once here, and defines one rule per tuple, filling the leading parameters in order. Keyword arguments fill the parameters they name in every rule, and defaults fill the rest. `name=` replaces the function's name, less one trailing underscore, on the command line, and `default=True` builds the rules when `fac` gets no targets.
+    """
+    rows = None if each is None else tuple(each)
+    return _declarator(fn, is_task=False, name=name, is_default=default, rows=rows, values=values)
+
+
+@overload
+def task(fn: _F, /) -> _F: ...
+
+
+@overload
+def task(
+    *, name: str | None = None, default: bool = False, **values: Any
+) -> Callable[[_F], _F]: ...
+
+
+def task(
+    fn: _F | None = None, /, *, name: str | None = None, default: bool = False, **values: Any
+) -> _F | Callable[[_F], _F]:
+    """Define a task from a function, returned unchanged.
+
+    A task takes inputs and values only, and executes whenever a target reaches it, after the rules that output its inputs, with its commands sharing Facere's standard streams. `name=`, `default=True`, and keyword arguments mean what they mean for `fac.rule`.
+    """
+    return _declarator(fn, is_task=True, name=name, is_default=default, rows=None, values=values)
+
+
+def out(path: str, suffix: str | None = None) -> str:
+    """Return the mirror of `path` inside the output directory, with its suffix swapped for `suffix` when given.
+
+    `fac.out("src/a.c", ".o")` is `build/src/a.o`, and `fac.out(".")` is the output directory itself. A path already inside the output directory keeps its place.
+    """
+    context = get_context("fac.out")
+    relative = normalize(path, context.root)
+    if relative == context.out_dir or relative.startswith(f"{context.out_dir}/"):
+        mirrored = relative
+    elif os.path.isabs(relative) or relative == ".." or relative.startswith("../"):
+        raise ValueError(f"fac.out takes a path under the root, not {path!r}")
+    else:
+        mirrored = posixpath.normpath(posixpath.join(context.out_dir, relative))
+    if suffix is None:
+        return mirrored
+    return PurePosixPath(mirrored).with_suffix(suffix).as_posix()
+
+
+def minimum_version(version: str) -> None:
+    """Fail collection unless the running Facere is `version` or newer, as in `fac.minimum_version("0.1")`."""
+    required = _parse_version(version)
+    running = _parse_version(VERSION)
+    width = max(len(required), len(running))
+    if running + (0,) * (width - len(running)) >= required + (0,) * (width - len(required)):
+        return
+    context = find_context()
+    location = find_caller_location(context.fac_py if context else None)
+    raise FacereError(
+        Diagnostic(
+            location,
+            f"this project needs Facere {version} or newer, and Facere {VERSION} is running: upgrade it with `uv tool upgrade facere`",
+        )
+    )
+
+
+def _parse_version(version: str) -> tuple[int, ...]:
+    parts = version.split(".")
+    if not all(part.isdecimal() for part in parts):
+        raise ValueError(f'fac.minimum_version takes a version such as "0.1", not {version!r}')
+    return tuple(int(part) for part in parts)
+
+
+def _declarator(
+    fn: _F | None,
+    *,
+    is_task: bool,
+    name: str | None,
+    is_default: bool,
+    rows: tuple[object, ...] | None,
+    values: dict[str, object],
+) -> _F | Callable[[_F], _F]:
+    def declare(fn: _F) -> _F:
+        context = get_context("@fac.task" if is_task else "@fac.rule")
+        location = find_caller_location(context.fac_py)
+        context.declarations.append(
+            Declaration(
+                is_task=is_task,
+                fn=fn,
+                name=name,
+                is_default=is_default,
+                rows=rows,
+                values=values,
+                location=location,
+            )
+        )
+        return fn
+
+    return declare if fn is None else declare(fn)

facere/_build.py

@@ -0,0 +1,226 @@
+"""Building targets: deciding which rules are stale, and executing recipes one at a time in dependency order."""
+
+import hashlib
+import os
+import posixpath
+import shlex
+import subprocess
+import sys
+import traceback
+from dataclasses import dataclass
+
+from facere import _state
+from facere._collect import Definition, Project
+from facere._command import write_output
+from facere._context import Context, Running, normalize
+from facere._diagnostics import Diagnostic, FacereError, Note, print_error
+from facere._hash import feed, hash_path
+
+
+class RecipeFailure(Exception):
+    def __init__(
+        self, definition: Definition, *, error: BaseException | None = None, reason: str = ""
+    ) -> None:
+        super().__init__(definition.label)
+        self.definition = definition
+        self.error = error
+        self.reason = reason
+
+
+@dataclass(slots=True)
+class Summary:
+    executed: int = 0
+    up_to_date: int = 0
+
+
+def resolve_targets(project: Project, root: str, targets: list[str]) -> list[Definition]:
+    """Return the definitions `targets` resolve to, in order, or the defaults when `targets` is empty."""
+    names_note = Note(None, f"names: {', '.join(sorted(project.by_name))}")
+    if not targets:
+        defaults = [definition for definition in project.definitions if definition.is_default]
+        if not defaults:
+            raise FacereError(
+                Diagnostic(
+                    None,
+                    "fac.py declares no default, so name a target, or pass default=True to fac.rule or fac.task",
+                    (names_note,),
+                )
+            )
+        return defaults
+    resolved: list[Definition] = []
+    unknown: list[str] = []
+    for target in targets:
+        if "/" in target or "\\" in target:
+            rule = project.producers.get(normalize(target.replace("\\", "/"), root))
+            found = [rule] if rule else []
+        else:
+            found = project.by_name.get(target, [])
+        resolved.extend(found)
+        if not found:
+            unknown.append(target)
+    if unknown:
+        listed = ", ".join(repr(target) for target in unknown)
+        raise FacereError(
+            Diagnostic(
+                None,
+                f"unknown target {listed}: name a rule or task, or give the path a rule outputs, relative to the root",
+                (names_note,),
+            )
+        )
+    return resolved
+
+
+def build(context: Context, project: Project, targets: list[Definition]) -> Summary:
+    """Build `targets` in order, raising RecipeFailure on the first failure."""
+    state_path = posixpath.join(context.state_dir, "state.db")
+    records = _state.load(state_path)
+    declared = {
+        _state.calc_key(definition.outputs)
+        for definition in project.definitions
+        if not definition.is_task
+    }
+    _state.remove(state_path, [key for key in records if key not in declared])
+    builder = _Builder(context, project, records, state_path)
+    for target in targets:
+        builder.build(target)
+    return builder.summary
+
+
+def report_failure(failure: RecipeFailure, start_dir: str) -> None:
+    """Print the failing command or exception, with the command's captured stderr and stdout, then name the rule or task."""
+    error = failure.error
+    if isinstance(error, subprocess.CalledProcessError | subprocess.TimeoutExpired):
+        if isinstance(error, subprocess.TimeoutExpired):
+            status = f"timed out after {error.timeout:g} seconds"
+        elif error.returncode < 0:
+            status = f"was killed by signal {-error.returncode}"
+        else:
+            status = f"exited with status {error.returncode}"
+        command = (
+            shlex.join(str(arg) for arg in error.cmd)
+            if isinstance(error.cmd, list | tuple)
+            else str(error.cmd)
+        )
+        print(f"fac: command {status}: {command}", file=sys.stderr, flush=True)
+        write_output(_to_bytes(error.stderr), _to_bytes(error.output))
+    elif error is not None:
+        print(_format_exception(error), end="", file=sys.stderr, flush=True)
+    message = f"{failure.definition.label} failed" + (
+        f": {failure.reason}" if failure.reason else ""
+    )
+    print_error(FacereError(Diagnostic(failure.definition.location, message)), start_dir)
+
+
+def _to_bytes(data: bytes | str | None) -> bytes:
+    if data is None:
+        return b""
+    return data if isinstance(data, bytes) else data.encode("utf-8", "surrogateescape")
+
+
+def _format_exception(error: BaseException) -> str:
+    package_dir = os.path.dirname(__file__)
+    report = traceback.TracebackException.from_exception(error)
+    report.stack = traceback.StackSummary.from_list(
+        [frame for frame in report.stack if os.path.dirname(frame.filename) != package_dir]
+    )
+    return "".join(report.format())
+
+
+class _Builder:
+    def __init__(
+        self,
+        context: Context,
+        project: Project,
+        records: dict[tuple[str, ...], _state.Record],
+        state_path: str,
+    ) -> None:
+        self.context = context
+        self.project = project
+        self.records = records
+        self.state_path = state_path
+        self.checked: set[Definition] = set()
+        self.summary = Summary()
+
+    def build(self, target: Definition) -> None:
+        for rule in self._order(target):
+            try:
+                self._ensure_up_to_date(rule)
+            except OSError as error:
+                raise RecipeFailure(
+                    rule, reason=f"{error}: fix the path or its permissions"
+                ) from error
+        if target.is_task:
+            self._execute(target)
+            self.summary.executed += 1
+            self.checked.clear()
+
+    def _order(self, target: Definition) -> list[Definition]:
+        """Return the rules `target` needs that this batch hasn't checked, each after the rules that output its inputs."""
+        if target in self.checked:
+            return []
+        order = []
+        seen = {*self.checked, target}
+        stack = [(target, iter(target.inputs))]
+        while stack:
+            definition, inputs = stack[-1]
+            path = next(inputs, None)
+            if path is None:
+                stack.pop()
+                if not definition.is_task:
+                    order.append(definition)
+                continue
+            rule = self.project.producers.get(path)
+            if rule is not None and rule not in seen:
+                seen.add(rule)
+                stack.append((rule, iter(rule.inputs)))
+        return order
+
+    def _ensure_up_to_date(self, rule: Definition) -> None:
+        self.checked.add(rule)
+        fingerprint = self._calc_fingerprint(rule)
+        key = _state.calc_key(rule.outputs)
+        record = self.records.get(key)
+        if record is not None:
+            if record == (fingerprint, tuple(hash_path(output) for output in key)):
+                self.summary.up_to_date += 1
+                return
+            _state.remove(self.state_path, [key])
+        for output in rule.outputs:
+            os.makedirs(os.path.dirname(output) or ".", exist_ok=True)
+        self._execute(rule)
+        output_hashes = {output: hash_path(output) for output in key}
+        missing = [output for output, content in output_hashes.items() if content is None]
+        if missing:
+            raise RecipeFailure(
+                rule,
+                reason=f"its recipe succeeded without writing {', '.join(missing)}: write every declared output, or fix the path",
+            )
+        record = self.records[key] = _state.Record(
+            fingerprint, tuple(content for content in output_hashes.values() if content is not None)
+        )
+        _state.save(self.state_path, key, record)
+        self.summary.executed += 1
+
+    def _calc_fingerprint(self, rule: Definition) -> str:
+        digest = hashlib.sha256(self.project.code_digests[rule])
+        for path in rule.inputs:
+            content = hash_path(path)
+            if content is None:
+                raise RecipeFailure(
+                    rule,
+                    reason=f"its input {path} is missing: restore it, or fix the rule that outputs it",
+                )
+            feed(digest, b"path", path.encode("utf-8", "surrogateescape"))
+            feed(digest, b"content", content.encode())
+        return digest.hexdigest()
+
+    def _execute(self, definition: Definition) -> None:
+        self.context.running = Running.TASK if definition.is_task else Running.RULE
+        try:
+            definition.fn(*definition.args, **definition.kwargs)
+        except KeyboardInterrupt:
+            raise
+        except BaseException as error:
+            raise RecipeFailure(definition, error=error) from error
+        finally:
+            self.context.running = None

facere/_cli.py

@@ -0,0 +1,146 @@
+"""The command line, `fac [TARGET...]`, also run in-process through fac.main."""
+
+import argparse
+import contextlib
+import os
+import sys
+import types
+from collections.abc import Generator
+
+from facere import _build, _collect
+from facere._context import Context, activate, normalize
+from facere._diagnostics import Diagnostic, FacereError, Note, format_path, print_error
+from facere._version import VERSION
+
+
+def main(args: list[str]) -> int:
+    """Run the fac command line in-process with `args`, the arguments after the program name, and return its exit status."""
+    parser = argparse.ArgumentParser(
+        prog="fac",
+        description="Build the targets the fac.py in the root defines.",
+        allow_abbrev=False,
+    )
+    parser.add_argument(
+        "targets",
+        nargs="*",
+        metavar="TARGET",
+        help="a rule or task name, or a path a rule outputs relative to the root (default: the defaults fac.py declares)",
+    )
+    parser.add_argument(
+        "-C",
+        dest="directory",
+        metavar="DIR",
+        help="run as if started in DIR, which becomes the root",
+    )
+    parser.add_argument(
+        "--out",
+        default="build",
+        metavar="DIR",
+        help="output directory, relative to the root (default: build)",
+    )
+    parser.add_argument(
+        "-q", "--quiet", action="store_true", help="hide the output of every successful command"
+    )
+    parser.add_argument("--version", action="version", version=VERSION)
+    try:
+        options = parser.parse_intermixed_args(args)
+        if "" in (options.out, options.directory):
+            parser.error("-C and --out take a directory, not an empty string")
+    except SystemExit as exit_:
+        return exit_.code if isinstance(exit_.code, int) else 1
+    return _invoke(options.directory, options.out, options.quiet, options.targets)
+
+
+def console_main() -> int:
+    return main(sys.argv[1:])
+
+
+def _invoke(directory: str | None, out: str, is_quiet: bool, targets: list[str]) -> int:
+    start_dir = os.getcwd()
+    root = os.path.abspath(os.path.join(start_dir, directory)) if directory else start_dir
+    fac_py = os.path.join(root, "fac.py")
+    if not os.path.isfile(fac_py):
+        print_error(FacereError(_build_missing_root_error(root, start_dir)), start_dir)
+        return 1
+    context = Context(root=root, out_dir=normalize(out, root), fac_py=fac_py, is_quiet=is_quiet)
+    pycache_prefix = os.path.abspath(os.path.join(root, context.state_dir, "pycache"))
+    with _enter_root(root, pycache_prefix), activate(context):
+        return _run(context, targets, start_dir)
+
+
+@contextlib.contextmanager
+def _enter_root(root: str, pycache_prefix: str) -> Generator[None]:
+    """Run from `root`, importable and caching bytecode under `pycache_prefix`, then restore the interpreter and forget the modules imported from `root`."""
+    start_dir = os.getcwd()
+    saved_path = list(sys.path)
+    saved_prefix = sys.pycache_prefix
+    saved_modules = dict(sys.modules)
+    try:
+        os.chdir(root)
+        sys.path.append(root)
+        sys.pycache_prefix = pycache_prefix
+        yield
+    finally:
+        os.chdir(start_dir)
+        sys.path[:] = saved_path
+        sys.pycache_prefix = saved_prefix
+        _forget_modules(root, saved_modules)
+
+
+def _run(context: Context, targets: list[str], start_dir: str) -> int:
+    if sys.flags.optimize:
+        print(
+            "fac: warning: Python runs with assertions disabled, so no recipe's assert checks anything: drop -O and PYTHONOPTIMIZE",
+            file=sys.stderr,
+        )
+    try:
+        project = _collect.collect(context)
+        summary = _build.build(
+            context, project, _build.resolve_targets(project, context.root, targets)
+        )
+    except FacereError as error:
+        print_error(error, start_dir)
+        return 1
+    except _build.RecipeFailure as failure:
+        _build.report_failure(failure, start_dir)
+        return 1
+    except KeyboardInterrupt:
+        print("fac: interrupted", file=sys.stderr)
+        return 130
+    print(f"fac: {summary.executed} executed, {summary.up_to_date} up to date", file=sys.stderr)
+    return 0
+
+
+def _build_missing_root_error(root: str, start_dir: str) -> Diagnostic:
+    where = "the working directory" if root == start_dir else format_path(root, start_dir)
+    message = f"no fac.py in {where}: run fac in the directory holding the project's fac.py, or name that directory with -C"
+    ancestor = _find_ancestor_with_fac_py(root)
+    if ancestor is None:
+        return Diagnostic(None, message)
+    relative = format_path(ancestor, start_dir)
+    note = f"the nearest directory holding a fac.py is {relative}: run fac -C {relative}"
+    return Diagnostic(None, message, (Note(None, note),))
+
+
+def _find_ancestor_with_fac_py(directory: str) -> str | None:
+    while True:
+        parent = os.path.dirname(directory)
+        if parent == directory:
+            return None
+        directory = parent
+        if os.path.isfile(os.path.join(directory, "fac.py")):
+            return directory
+
+
+def _forget_modules(root: str, saved_modules: dict[str, types.ModuleType]) -> None:
+    prefix = os.path.join(root, "")
+    for name, module in list(sys.modules.items()):
+        if name in saved_modules:
+            continue
+        path = getattr(module, "__file__", None)
+        if name == _collect.MODULE_NAME or (
+            isinstance(path, str) and os.path.abspath(path).startswith(prefix)
+        ):
+            del sys.modules[name]
+    if _collect.MODULE_NAME in saved_modules:
+        sys.modules[_collect.MODULE_NAME] = saved_modules[_collect.MODULE_NAME]