pyfr-cli 0.11.0__py3-none-any.whl

pyfr_cli/__init__.py

@@ -0,0 +1,16 @@
+"""pyfr-cli: bring a project generated from PyFr up to a newer template version.
+
+`pyfr update` re-renders the template at the target version with the answers
+the project recorded, commits the result on the `template` branch, and merges
+that branch in (M8 design, section 4). `pyfr update-check` says whether a
+newer version exists.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pyfr-cli")
+except PackageNotFoundError:  # a checkout that was never installed
+    __version__ = "0.0.0"

pyfr_cli/__main__.py

@@ -0,0 +1,86 @@
+"""The `pyfr` command."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from pyfr_cli import __version__, update
+from pyfr_cli.errors import UpdateError
+
+TEMPLATE_HELP = (
+    "the template repository (default: _template in .pyfr-answers.yml; one "
+    "run only, the recorded value is kept) -- its hooks and migration scripts "
+    "run with your permissions, so it must be a repository you trust"
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pyfr",
+        description="Keep a project generated from PyFr up to date with the template.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    run = commands.add_parser(
+        "update", help="pull in a newer template version through a git merge"
+    )
+    run.add_argument(
+        "--to", metavar="VERSION", help="the version to update to (default: the newest)"
+    )
+    run.add_argument(
+        "--no-push",
+        action="store_true",
+        help="do not push the template branch to origin (the next run pushes "
+        "it, even one that finds nothing else to do)",
+    )
+    run.add_argument("--template", metavar="URL", help=TEMPLATE_HELP)
+
+    check = commands.add_parser(
+        "update-check", help="exit 1 when a newer template version exists"
+    )
+    check.add_argument(
+        "--json", action="store_true", help="print a JSON object instead of a sentence"
+    )
+    check.add_argument("--template", metavar="URL", help=TEMPLATE_HELP)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    project = Path.cwd()
+    try:
+        if args.command == "update":
+            options = update.Options(
+                to=args.to, push=not args.no_push, template=args.template
+            )
+            return update.update(project, options, sys.stdout)
+        options = update.Options(template=args.template)
+        return update.check(project, options, sys.stdout, as_json=args.json)
+    except UpdateError as exc:
+        if os.environ.get("PYFR_DEBUG"):
+            raise
+        print(f"error: {exc.cause}", file=sys.stderr)
+        print(f"  fix: {exc.fix}", file=sys.stderr)
+        return 2
+    except OSError as exc:
+        if os.environ.get("PYFR_DEBUG"):
+            raise
+        print(f"error: {exc}", file=sys.stderr)
+        print(
+            "  fix: check the paths and permissions the message names, then run again",
+            file=sys.stderr,
+        )
+        return 2
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyfr_cli/answers.py

@@ -0,0 +1,118 @@
+""".pyfr-answers.yml: what the generator recorded, what an update rewrites."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from pyfr_cli.errors import UpdateError
+from pyfr_cli.versions import Version
+
+FILE = ".pyfr-answers.yml"
+GUIDE = "docs/guides/update-from-template.md"
+
+
+@dataclass(frozen=True)
+class Answers:
+    path: Path
+    template: str
+    version: Version
+    # Every key, every value as a string: cookiecutter's extra_context
+    # takes strings, and the generator wrote the file from strings.
+    values: dict[str, str]
+
+
+def load(project: Path) -> Answers:
+    path = project / FILE
+    if not path.is_file():
+        raise UpdateError(
+            f"{FILE} not found in {project}",
+            "run from the project root; a project generated before PyFr "
+            f"v0.7.0 has no answers file -- {GUIDE} shows how to write one",
+        )
+    try:
+        data = yaml.safe_load(path.read_text())
+    except yaml.YAMLError as exc:
+        raise UpdateError(
+            f"{FILE} is not valid YAML: {exc}", f"fix the file; see {GUIDE}"
+        ) from exc
+    if not isinstance(data, dict):
+        raise UpdateError(f"{FILE} is not a mapping", f"fix the file; see {GUIDE}")
+    values = {str(key): str(value) for key, value in data.items()}
+    for key in ("_template", "_template_version"):
+        if key not in values:
+            raise UpdateError(f"{FILE} has no {key}", f"add it; see {GUIDE}")
+    try:
+        version = Version.parse(values["_template_version"])
+    except ValueError as exc:
+        raise UpdateError(
+            f"{FILE}: _template_version {exc}",
+            f"set it to the version the project was generated from; see {GUIDE}",
+        ) from exc
+    return Answers(path, values["_template"], version, values)
+
+
+def context(
+    answers: Answers, prompts: Iterable[str]
+) -> tuple[dict[str, str], list[str]]:
+    """cookiecutter's extra_context for a render at a template declaring
+    `prompts`, and the names of the prompts that will take their default.
+
+    A prompt the target added since the project was generated has no
+    recorded value; a recorded answer the target no longer declares is
+    left out (spec section 4.4).
+    """
+    wanted = [prompt for prompt in prompts if not prompt.startswith("_")]
+    recorded = {p: answers.values[p] for p in wanted if p in answers.values}
+    defaulted = [p for p in wanted if p not in answers.values]
+    return recorded, defaulted
+
+
+# The `_template:` line of an answers file, wherever it is in the file.
+TEMPLATE_LINE = re.compile(r"^_template:[^\n]*$", re.MULTILINE)
+
+
+def install(rendered_project: Path, project: Path, template: str) -> None:
+    """Step 10: the render's answers file -- the recorded answers, the new
+    prompts' defaults, the target version -- becomes the project's.
+
+    Except for `_template`: the render carries the URL the template body
+    hard-codes, upstream's, and `template` -- the URL the project
+    recorded -- wins over it, so a fork stays pointed at itself. Only
+    that line is rewritten; every other byte of the render's file is
+    kept. (--template is a one-off override and is never recorded.)
+    """
+    text = (rendered_project / FILE).read_text()
+    if _value_in(text, "_template") != template:
+        # yaml decides the quoting, for a URL that needs any.
+        line = yaml.safe_dump({"_template": template}).rstrip("\n")
+        text, found = TEMPLATE_LINE.subn(lambda _match: line, text, count=1)
+        if not found:
+            text += line + "\n"
+    (project / FILE).write_text(text)
+
+
+def version_in(text: str) -> Version | None:
+    """The _template_version an answers file's text records, if any."""
+    value = _value_in(text, "_template_version")
+    if value is None:
+        return None
+    try:
+        return Version.parse(value)
+    except ValueError:
+        return None
+
+
+def _value_in(text: str, key: str) -> str | None:
+    """The value of `key` in an answers file's text, as a string, if any."""
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError:
+        return None
+    if not isinstance(data, dict) or key not in data:
+        return None
+    return str(data[key])

pyfr_cli/changelog.py

@@ -0,0 +1,67 @@
+"""The template's CHANGELOG.md: Commitizen's `## vX.Y.Z (date)` sections.
+
+The sections between the recorded version and the target become the merge
+commit's body, and from there the weekly pull request's (spec section 4.9).
+"""
+
+from __future__ import annotations
+
+import re
+
+from pyfr_cli.versions import Version
+
+HEADING = re.compile(r"^## v?(?P<version>\d+\.\d+\.\d+)(?P<rest>.*)$")
+# An scp-like ssh clone URL: `[user@]host:path`, no scheme in front. The
+# negative lookahead keeps a real URL (`https://host:port/path`) from
+# matching -- that also has a `:` before the first `/`. The host needs at
+# least two characters so a Windows drive path (`C:\...`, `C:/...`) is not
+# mistaken for one -- no real ssh host is a single letter.
+SCP_LIKE_URL = re.compile(
+    r"^(?![A-Za-z][A-Za-z0-9+.-]*://)(?:[^@/]+@)?(?P<host>[^:/]{2,}):(?P<path>.+)$"
+)
+# An ssh:// clone URL, any user, with an optional port that has no https
+# equivalent -- the web UI lives on 443 whatever port ssh uses.
+SSH_SCHEME_URL = re.compile(
+    r"^ssh://(?:[^@/]+@)?(?P<host>[^:/]+)(?::\d+)?/(?P<path>.+)$"
+)
+
+
+def sections(text: str) -> list[tuple[Version, str, str]]:
+    """(version, the rest of the heading line, body) for each section, in
+    file order -- Commitizen writes the newest first."""
+    found: list[tuple[Version, str, list[str]]] = []
+    for line in text.splitlines():
+        heading = HEADING.match(line)
+        if heading is not None:
+            found.append((Version.parse(heading["version"]), heading["rest"], []))
+        elif found:
+            found[-1][2].append(line)
+    return [(version, rest, "\n".join(body).strip()) for version, rest, body in found]
+
+
+def _https_base(template: str) -> str:
+    """`template` as an https URL: an scp-like or `ssh://` clone URL is
+    rewritten; anything else (https, http, a local path) is unchanged."""
+    match = SCP_LIKE_URL.match(template) or SSH_SCHEME_URL.match(template)
+    if match is None:
+        return template
+    return f"https://{match['host']}/{match['path']}"
+
+
+def release_url(template: str, version: Version) -> str:
+    """The release page for `version` at `template`, as an https URL --
+    an ssh clone URL is turned into its https form first."""
+    base = _https_base(template)
+    base = base.rstrip("/").removesuffix(".git")
+    return f"{base}/releases/tag/{version}"
+
+
+def entries(text: str, after: Version, up_to: Version, template: str) -> str:
+    """The sections with after < version <= up_to, newest first, each
+    heading linking to its release. Empty when there are none."""
+    parts = [
+        f"## [{version}]({release_url(template, version)}){rest}\n\n{body}\n"
+        for version, rest, body in sections(text)
+        if after < version <= up_to
+    ]
+    return "\n".join(parts)

pyfr_cli/errors.py

@@ -0,0 +1,12 @@
+"""The one error the command reports: a cause and a fix, one line each."""
+
+from __future__ import annotations
+
+
+class UpdateError(Exception):
+    """Stops the run. `__main__` prints `cause` and `fix` and exits 2."""
+
+    def __init__(self, cause: str, fix: str) -> None:
+        super().__init__(cause)
+        self.cause = cause
+        self.fix = fix

pyfr_cli/git.py

@@ -0,0 +1,107 @@
+"""Every git call the tool makes goes through `Git.run`."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from pyfr_cli.errors import UpdateError
+
+
+class GitError(UpdateError):
+    """A git command the tool expected to succeed did not."""
+
+
+@dataclass(frozen=True)
+class Git:
+    """git, run in one directory.
+
+    Arguments are always fixed literals or paths the tool computed, never
+    input typed by a user.
+    """
+
+    cwd: Path
+
+    def run(self, *args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+        result = subprocess.run(
+            ["git", *args], cwd=self.cwd, capture_output=True, text=True
+        )
+        if check and result.returncode != 0:
+            detail = result.stderr.strip() or result.stdout.strip()
+            raise GitError(
+                f"git {' '.join(args)} failed in {self.cwd}: {detail}",
+                "the git message above says what went wrong",
+            )
+        return result
+
+    def out(self, *args: str) -> str:
+        return self.run(*args).stdout.strip()
+
+    def ok(self, *args: str) -> bool:
+        return self.run(*args, check=False).returncode == 0
+
+    def toplevel(self) -> Path:
+        return Path(self.out("rev-parse", "--show-toplevel")).resolve()
+
+    def git_dir(self) -> Path:
+        # Relative for the main worktree (".git"), absolute for a linked
+        # worktree; resolved against cwd either way.
+        return (self.cwd / self.out("rev-parse", "--git-dir")).resolve()
+
+    def current_branch(self) -> str | None:
+        name = self.out("rev-parse", "--abbrev-ref", "HEAD")
+        return None if name == "HEAD" else name
+
+    def has_tracked_changes(self) -> bool:
+        return bool(self.out("status", "--porcelain", "--untracked-files=no"))
+
+    def has_staged_changes(self) -> bool:
+        return not self.ok("diff", "--cached", "--quiet")
+
+    def operation_in_progress(self) -> str | None:
+        git_dir = self.git_dir()
+        if (git_dir / "MERGE_HEAD").exists():
+            return "merge"
+        if (git_dir / "rebase-merge").exists() or (git_dir / "rebase-apply").exists():
+            return "rebase"
+        if (git_dir / "CHERRY_PICK_HEAD").exists():
+            return "cherry-pick"
+        return None
+
+    def root_commits(self) -> list[str]:
+        return self.out("rev-list", "--max-parents=0", "HEAD").split()
+
+    def has_identity(self) -> bool:
+        return self.ok("config", "user.name") and self.ok("config", "user.email")
+
+    def branch_exists(self, name: str) -> bool:
+        return self.ok("show-ref", "--verify", "--quiet", f"refs/heads/{name}")
+
+    def remote_exists(self, name: str) -> bool:
+        return self.ok("remote", "get-url", name)
+
+    def commit(self, message: str, *, allow_empty: bool = False) -> str:
+        """Commit what is staged and return the sha.
+
+        `--no-verify`: the tool's commits are mechanical, and the template
+        worktree shares .git/hooks with the project, where the generator
+        installed pre-commit. CI runs the gates on the pull request.
+        """
+        args = ["commit", "--quiet", "--no-verify", "--message", message]
+        if allow_empty:
+            args.append("--allow-empty")
+        self.run(*args)
+        return self.out("rev-parse", "HEAD")
+
+    def subject(self, rev: str) -> str:
+        return self.out("show", "--no-patch", "--format=%s", rev)
+
+
+def require_tools(*names: str) -> None:
+    for name in names:
+        if shutil.which(name) is None:
+            raise UpdateError(
+                f"{name} is not on PATH", f"install {name}, then run again"
+            )

pyfr_cli/ignore.py

@@ -0,0 +1,103 @@
+""".pyfr-update-ignore: the paths an update leaves exactly as the project has them.
+
+gitignore syntax, matched with pathspec. A project generated before the
+template shipped the file uses the built-in default below, rendered for its
+answers (spec section 5.2 and decision M8-5).
+"""
+
+from __future__ import annotations
+
+import shutil
+from collections.abc import Iterable
+from pathlib import Path
+
+from pathspec import GitIgnoreSpec
+
+from pyfr_cli.answers import Answers
+
+FILE = ".pyfr-update-ignore"
+
+HEADER = """\
+# Paths `just update` leaves exactly as this project has them: yours from
+# the first day, or artifacts of your code. Add paths as you diverge --
+# one gitignore pattern per line, comments on their own lines.
+# Everything not listed is template-owned and receives fixes by default.
+
+# Written by the update itself.
+/.pyfr-answers.yml
+# This file.
+/.pyfr-update-ignore
+/README.md
+/CHANGELOG.md
+# Resolver output; run `uv lock` after an update that touched pyproject.toml.
+/uv.lock
+"""
+SCHEMA = """\
+# Your schema.
+/migrations/
+/schema.sql
+"""
+FOOTER = """\
+# Artifacts of your code: the contract, and the baseline your release promotes.
+/openapi.json
+/openapi.baseline.json
+# Your decisions.
+/docs/adr/
+# The example slice, then your business model.
+/src/{package}/domain/
+/src/{package}/services/
+/src/{package}/api/v1/
+"""
+
+
+def default_text(package: str, database: str) -> str:
+    """The built-in default, as the template body ships it for these answers.
+
+    The schema lines exist only when the project has a database: the
+    generator prunes migrations/ and schema.sql otherwise.
+    """
+    schema = SCHEMA if database == "postgres" else ""
+    return HEADER + schema + FOOTER.format(package=package)
+
+
+class Ignore:
+    def __init__(self, lines: Iterable[str]) -> None:
+        self._spec = GitIgnoreSpec.from_lines(lines)
+
+    @classmethod
+    def from_text(cls, text: str) -> Ignore:
+        return cls(text.splitlines())
+
+    def matches(self, relative: str) -> bool:
+        """Whether a path (POSIX, relative to the project root) is left alone."""
+        return bool(self._spec.match_file(relative))
+
+
+def load(project: Path, recorded: Answers) -> tuple[Ignore, bool]:
+    """The project's ignore file, or the default rendered for its answers.
+
+    Returns the spec and whether the file existed, so the caller can say
+    which one applied.
+    """
+    file = project / FILE
+    if file.is_file():
+        return Ignore.from_text(file.read_text()), True
+    package = recorded.values.get("package_name", "")
+    database = recorded.values.get("database", "none")
+    return Ignore.from_text(default_text(package, database)), False
+
+
+def install(rendered_project: Path, project: Path) -> bool:
+    """Give a project that has no ignore file the render's, if the render
+    has one; say whether that happened.
+
+    The built-in default ignores the file itself, so the sync never puts
+    it on the template branch and the merge can never deliver it. This
+    is how a project generated before the template shipped the file
+    receives it with the update (spec section 5.2).
+    """
+    source, target = rendered_project / FILE, project / FILE
+    if not source.is_file() or target.exists():
+        return False
+    shutil.copyfile(source, target)
+    return True

pyfr_cli/migrate.py

@@ -0,0 +1,114 @@
+"""Migration scripts: updates/<version>/before.py and after.py in the template.
+
+Some template changes cannot be expressed as a merge -- a file that moves,
+a setting that changes shape. For each version in (recorded, target] the
+template may ship a `before.py`, run on the project's tree before the
+merge, and an `after.py`, run after it (spec section 6; updates/README.md
+is the contract for the scripts' authors).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TextIO
+
+from pyfr_cli.errors import UpdateError
+from pyfr_cli.versions import Version
+
+
+@dataclass(frozen=True)
+class Migration:
+    version: Version
+    before: Path | None
+    after: Path | None
+
+
+def discover(clone: Path, after: Version, up_to: Version) -> list[Migration]:
+    """The migrations for versions in (after, up_to], oldest first."""
+    updates = clone / "updates"
+    if not updates.is_dir():
+        return []
+    found: list[Migration] = []
+    for entry in updates.iterdir():
+        if not entry.is_dir():
+            continue
+        try:
+            version = Version.parse(entry.name)
+        except ValueError:
+            continue
+        # Exactly vX.Y.Z: the v is required, and no zero padding.
+        if entry.name != str(version) or not after < version <= up_to:
+            continue
+        before, after_script = entry / "before.py", entry / "after.py"
+        found.append(
+            Migration(
+                version,
+                before if before.is_file() else None,
+                after_script if after_script.is_file() else None,
+            )
+        )
+    return sorted(found, key=lambda migration: migration.version)
+
+
+def run_script(
+    script: Path,
+    project: Path,
+    from_version: Version,
+    to_version: Version,
+    out: TextIO,
+) -> None:
+    """One script, in the project root, with the update's versions in the
+    environment. `--no-project`: scripts are standard-library only, and a
+    project sync here would be slow and would fail in a fresh checkout."""
+    label = f"{script.parent.name}/{script.name}"
+    out.write(f"migrations: {label}\n")
+    env = {
+        **os.environ,
+        "PYFR_UPDATE_FROM": str(from_version),
+        "PYFR_UPDATE_TO": str(to_version),
+    }
+    result = subprocess.run(
+        ["uv", "run", "--no-project", "python", str(script)],
+        cwd=project,
+        env=env,
+        capture_output=True,
+        text=True,
+    )
+    if result.stdout:
+        out.write(result.stdout)
+    if result.returncode != 0:
+        raise UpdateError(
+            f"{label} failed (exit {result.returncode}): {result.stderr.strip()}",
+            "fix what it reports; `git reset --hard HEAD` reverts what it "
+            "changed, then run pyfr update again",
+        )
+    # A warning the script printed is worth seeing when it succeeds too.
+    if result.stderr:
+        out.write(result.stderr)
+
+
+def run_before(
+    migrations: list[Migration],
+    project: Path,
+    from_version: Version,
+    to_version: Version,
+    out: TextIO,
+) -> None:
+    for migration in migrations:
+        if migration.before is not None:
+            run_script(migration.before, project, from_version, to_version, out)
+
+
+def run_after(
+    migrations: list[Migration],
+    project: Path,
+    from_version: Version,
+    to_version: Version,
+    out: TextIO,
+) -> None:
+    for migration in migrations:
+        if migration.after is not None:
+            run_script(migration.after, project, from_version, to_version, out)