xtr-cli 4.0.2__py3-none-any.whl

xtr_cli/project_questions.py

@@ -0,0 +1,108 @@
+"""ProjectQuestions: what the command line left out, asked of whoever is at the terminal."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Final, final
+
+from xtr_console import escape
+
+from .exception import UnknownAddOnError
+
+if TYPE_CHECKING:
+    from xtr_console import ConsoleStyle
+
+    from .add_on import AddOn
+    from .add_on_catalog import AddOnCatalog
+    from .add_on_choice import AddOnChoice
+    from .template_catalog import TemplateCatalog
+
+__all__ = ["DEFAULT_TEMPLATE", "ProjectQuestions"]
+
+DEFAULT_TEMPLATE: Final = "cli"
+"""The template a project gets when none is asked for and no question may be asked."""
+
+
+@final
+class ProjectQuestions:
+    """Asks only for what was not given, and never when questions are off.
+
+    Every question has an option that answers it, and an option given is never
+    asked again. With ``-n`` every question takes its default unasked — the
+    ``cli`` template and no add-ons — so a script or a CI job never waits on a
+    prompt. A wrong answer is reported and the question asked again.
+    """
+
+    __slots__ = ("_add_ons", "_io", "_templates")
+
+    def __init__(self, io: ConsoleStyle, templates: TemplateCatalog, add_ons: AddOnCatalog) -> None:
+        """Ask through ``io``, offering what ``templates`` and ``add_ons`` hold."""
+        self._io = io
+        self._templates = templates
+        self._add_ons = add_ons
+
+    def directory(self, given: Path | None) -> Path | None:
+        """Return the directory given, or the one answered; ``None`` when there is neither."""
+        if given is not None:
+            return given
+        answer = self._io.ask("Project directory").strip()
+        return Path(answer) if answer else None
+
+    def template(self, given: str | None) -> str:
+        """Return the template given, or the shipped one chosen."""
+        if given is not None:
+            return given
+        names = self._templates.names()
+        if self._io.interactive:
+            self._io.listing(
+                escape(f"{name} — {self._templates.load(name).summary}") for name in names
+            )
+        default = DEFAULT_TEMPLATE if DEFAULT_TEMPLATE in names else names[0]
+        return self._io.ask("Template", default, choices=names)
+
+    def add_ons(self, given: str | None, template: str) -> tuple[AddOnChoice, ...]:
+        """Return the add-ons given, or the ones chosen, variants asked for each that has them.
+
+        Raises:
+            UnknownAddOnError: When ``given`` names an add-on that cannot be
+                added; a wrong answer is asked again instead.
+        """
+        if given is not None:
+            return self._add_ons.parse(given, template)
+        available = self._add_ons.available(template)
+        if not self._io.interactive or not available:
+            return ()
+        self._io.listing(escape(f"{add_on.name} — {add_on.summary}") for add_on in available)
+        while True:
+            answer = self._io.ask("Add-ons, comma-separated (empty for none)")
+            try:
+                chosen = self._add_ons.parse(answer, template)
+            except UnknownAddOnError as error:
+                self._io.error(escape(str(error)))
+                continue
+            spelled = {
+                token.partition(":")[0].strip() for token in answer.split(",") if ":" in token
+            }
+            return tuple(
+                choice
+                if not choice.add_on.variants or choice.add_on.name in spelled
+                else self._variants(choice.add_on)
+                for choice in chosen
+            )
+
+    def confirm(self) -> bool:
+        """Ask whether to go ahead; yes when questions are off."""
+        return self._io.confirm("Create it?", default=True)
+
+    def _variants(self, add_on: AddOn) -> AddOnChoice:
+        """Ask which of ``add_on``'s variants to install, until the answer is one it offers."""
+        question = (
+            f"{add_on.variant_label.capitalize()} for {add_on.name} — "
+            f"{', '.join(add_on.variants)}, joined with +"
+        )
+        while True:
+            answer = self._io.ask(question, "+".join(add_on.default_variants))
+            try:
+                return self._add_ons.choose(add_on, answer)
+            except UnknownAddOnError as error:
+                self._io.error(escape(str(error)))

xtr_cli/project_settings.py

@@ -0,0 +1,89 @@
+"""ProjectSettings: everything decided about a new project before anything is written."""
+
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, final
+
+if TYPE_CHECKING:
+    from .add_on_choice import AddOnChoice
+    from .project_name import ProjectName
+    from .template import Template
+
+__all__ = ["ProjectSettings"]
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class ProjectSettings:
+    """The answers a project is made from — from the command line, the questions, or both.
+
+    Attributes:
+        command: The command that makes it, ``new`` or ``init``, for :meth:`command_line`.
+        directory: Where the project is made, absolute.
+        name: The project's name.
+        template: The template it is made from.
+        template_source: The template as it was asked for: a shipped name or a directory.
+        add_ons: The add-ons it starts with.
+        python: The ``3.<minor>`` version it is pinned to.
+        name_given: Whether the name was asked for rather than read off the directory.
+        git: Whether a git repository is initialised in it.
+        local_packages: A directory of xtr package sources to install from, editable,
+            instead of the package index.
+    """
+
+    command: str
+    directory: Path
+    name: ProjectName
+    template: Template
+    template_source: str
+    add_ons: tuple[AddOnChoice, ...]
+    python: str
+    name_given: bool = False
+    git: bool = True
+    local_packages: Path | None = None
+
+    def values(self) -> dict[str, str]:
+        """Return what the template's placeholders are filled with.
+
+        ``minor`` is the part of the Python version after ``3.``, so a tool
+        naming versions as ``py313`` can be given ``py3${minor}``.
+        """
+        return {
+            "name": self.name.distribution,
+            "app": self.name.app,
+            "python": self.python,
+            "minor": self.python.partition(".")[2],
+        }
+
+    def command_line(self) -> str:
+        """Return the command making this same project with no question asked.
+
+        Printed before anything is written, so an answered run can be repeated
+        in a script or a CI job, or pasted into documentation.
+        """
+        parts = ["uvx", "xtr-cli", self.command]
+        if self.command == "new":
+            parts.append(_shown(self.directory))
+        parts.append(f"--template={self.template_source}")
+        if self.name_given:
+            parts.append(f"--name={self.name.distribution}")
+        if self.add_ons:
+            parts.append(f"--with={','.join(choice.spelling for choice in self.add_ons)}")
+        parts.append(f"--python={self.python}")
+        if not self.git:
+            parts.append("--no-git")
+        if self.local_packages is not None:
+            parts.append(f"--local-packages={self.local_packages}")
+        parts.append("-n")
+        return shlex.join(parts)
+
+
+def _shown(directory: Path) -> str:
+    """Return ``directory`` relative to the working directory when it lies under it."""
+    try:
+        return str(directory.relative_to(Path.cwd()))
+    except ValueError:
+        return str(directory)

xtr_cli/scaffold_plan.py

@@ -0,0 +1,41 @@
+"""ScaffoldPlan: the files a new project gets and the commands that finish it."""
+
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, final
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+__all__ = ["ScaffoldPlan"]
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class ScaffoldPlan:
+    """A project worked out in full and not yet made.
+
+    Planning everything first means a dry run and a real one share one code
+    path, and a template that cannot be rendered fails before the directory is
+    touched.
+
+    Attributes:
+        directory: Where the project is made.
+        files: Each path in the project, ``/``-separated, with the text written there.
+        commands: The commands run in the project once its files are written, in order.
+        next_steps: What to try once it is made.
+    """
+
+    directory: Path
+    files: tuple[tuple[str, str], ...]
+    commands: tuple[tuple[str, ...], ...]
+    next_steps: tuple[str, ...]
+
+    def render(self) -> tuple[str, ...]:
+        """Return the plan as the lines a dry run prints: one per file, one per command."""
+        return (
+            *(f"write {path}" for path, _ in self.files),
+            *(f"run   {shlex.join(argv)}" for argv in self.commands),
+        )

xtr_cli/scaffolder.py

@@ -0,0 +1,159 @@
+"""Scaffolder: plans a new project from its settings, then makes it."""
+
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from typing import TYPE_CHECKING, final
+
+from .exception import DirectoryNotEmptyError, StepFailedError
+from .scaffold_plan import ScaffoldPlan
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+    from pathlib import Path
+
+    from .process_runner_interface import ProcessRunnerInterface
+    from .project_settings import ProjectSettings
+
+__all__ = ["Scaffolder"]
+
+_PYPROJECT = "pyproject.toml"
+_RECIPES = "xtr-recipes"
+# Metadata a directory may already hold and still count as empty.
+_IGNORED = frozenset({".git", ".hg", ".idea", ".vscode", ".DS_Store"})
+# A release version: what the xtr requirements are pinned to the major of.
+_RELEASE = re.compile(r"^(?P<major>\d+)\.\d+\.\d+$")
+# A requirement already carrying a version, a URL or a marker is left as written.
+_SPECIFIED = re.compile(r"[<>=!~@;]")
+_NAME_END = re.compile(r"[\s\[<>=!~@;]")
+
+
+@final
+class Scaffolder:
+    """Turns settings into a plan, and a plan into a project.
+
+    Making a project is writing the template's files, then handing over to
+    ``uv``: ``uv add`` installs the requirements and locks them, and the
+    project's own ``xtr-recipes recipes:sync`` applies each installed
+    package's recipe — the bundle list, the ``.env`` and ignore blocks — with
+    the versions the project actually installed.
+
+    Every xtr package moves with one shared version, so an unversioned xtr
+    requirement is pinned to this tool's major version: a template is always
+    installed with the packages it was written for.
+    """
+
+    __slots__ = ("_runner", "_version")
+
+    def __init__(self, runner: ProcessRunnerInterface, version: str) -> None:
+        """Run commands through ``runner``; pin the xtr requirements to ``version``'s major."""
+        self._runner = runner
+        self._version = version
+
+    @staticmethod
+    def check_directory(directory: Path) -> None:
+        """Refuse a directory that is a file, or holds anything but metadata.
+
+        Raises:
+            DirectoryNotEmptyError: When ``directory`` is in the way.
+        """
+        if not directory.exists():
+            return
+        if not directory.is_dir():
+            raise DirectoryNotEmptyError(directory, (directory.name,))
+        found = tuple(sorted(entry.name for entry in directory.iterdir()))
+        in_the_way = tuple(name for name in found if name not in _IGNORED)
+        if in_the_way:
+            raise DirectoryNotEmptyError(directory, in_the_way)
+
+    def plan(self, settings: ProjectSettings) -> ScaffoldPlan:
+        """Work the project out in full, writing nothing.
+
+        Raises:
+            InvalidTemplateError: When the template cannot be rendered.
+        """
+        values = settings.values()
+        template = settings.template
+        files = template.render(values)
+        if settings.local_packages is not None:
+            sources = _sources(settings.local_packages)
+            files = tuple(
+                (path, text + sources if path == _PYPROJECT else text) for path, text in files
+            )
+        dependencies = self._pinned(
+            (*template.dependencies, *(choice.requirement for choice in settings.add_ons))
+        )
+        dev_dependencies = self._pinned(template.dev_dependencies)
+        commands: list[tuple[str, ...]] = []
+        if dependencies:
+            commands.append(("uv", "add", "--", *dependencies))
+        if dev_dependencies:
+            commands.append(("uv", "add", "--dev", "--", *dev_dependencies))
+        if _RECIPES in {_name(each) for each in (*dependencies, *dev_dependencies)}:
+            commands.append(("uv", "run", _RECIPES, "recipes:sync"))
+        if settings.git and not (settings.directory / ".git").exists():
+            commands.append(("git", "init", "--quiet"))
+        return ScaffoldPlan(
+            directory=settings.directory,
+            files=files,
+            commands=tuple(commands),
+            next_steps=template.steps(values),
+        )
+
+    def apply(self, plan: ScaffoldPlan, report: Callable[[str], None]) -> None:
+        """Make the project ``plan`` describes, reporting each step as it starts.
+
+        Raises:
+            DirectoryNotEmptyError: When the directory filled up since it was
+                checked.
+            StepFailedError: When a command fails; the commands after it are
+                not run, and what was made so far is left in place.
+        """
+        self.check_directory(plan.directory)
+        for path, text in plan.files:
+            report(f"write {path}")
+            target = plan.directory.joinpath(*path.split("/"))
+            target.parent.mkdir(parents=True, exist_ok=True)
+            _ = target.write_text(text, encoding="utf-8")
+        for argv in plan.commands:
+            report(f"run   {shlex.join(argv)}")
+            code = self._runner.run(argv, plan.directory)
+            if code != 0:
+                raise StepFailedError(argv, plan.directory, code)
+
+    def _pinned(self, requirements: Iterable[str]) -> tuple[str, ...]:
+        """Pin each unversioned xtr requirement to this tool's major version."""
+        release = _RELEASE.match(self._version)
+        if release is None:
+            return tuple(requirements)
+        major = int(release.group("major"))
+        return tuple(
+            f"{requirement}>={major}.0,<{major + 1}"
+            if _name(requirement).startswith("xtr-") and not _SPECIFIED.search(requirement)
+            else requirement
+            for requirement in requirements
+        )
+
+
+def _name(requirement: str) -> str:
+    """Return the distribution a requirement names, without extras or version."""
+    stripped = requirement.strip()
+    end = _NAME_END.search(stripped)
+    return (stripped[: end.start()] if end is not None else stripped).lower()
+
+
+def _sources(local_packages: Path) -> str:
+    """Return a ``[tool.uv.sources]`` table installing every package found there, editable.
+
+    Every package is listed, not only the ones the project names: a source in
+    the project's own manifest applies to the packages it pulls in as well,
+    so a sibling that is not yet published still resolves.
+    """
+    root = local_packages.expanduser().resolve()
+    lines: list[str] = []
+    for manifest in sorted(root.glob(f"xtr-*/{_PYPROJECT}")):
+        path = json.dumps(manifest.parent.as_posix())
+        lines.append(f"{manifest.parent.name} = {{ path = {path}, editable = true }}")
+    return "\n[tool.uv.sources]\n" + "".join(f"{line}\n" for line in lines)

xtr_cli/subprocess_runner.py

@@ -0,0 +1,47 @@
+"""SubprocessRunner: the commands this tool runs, as real processes."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import TYPE_CHECKING, Final, final
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+
+__all__ = ["NOT_FOUND", "SubprocessRunner"]
+
+NOT_FOUND: Final = 127
+"""The code a command that is not on the ``PATH`` ends with, as a shell reports it."""
+
+
+@final
+class SubprocessRunner:
+    """Starts each command as a child process, attached to this one's terminal.
+
+    ``VIRTUAL_ENV`` is left out of the child's environment: the new project
+    always works in its own ``.venv``, and an environment active in the shell
+    — the one this tool runs from, say — would only make ``uv`` warn that it
+    is being ignored.
+
+    Ctrl-C reaches the child as well as this process, since both share the
+    terminal. The child is then waited for rather than killed, so a server
+    finishes shutting down — its application's shutdown hooks included — before
+    this process ends; a second Ctrl-C stops waiting.
+    """
+
+    __slots__ = ()
+
+    def run(self, argv: Sequence[str], cwd: Path, env: Mapping[str, str] | None = None) -> int:
+        """Run ``argv`` in ``cwd`` and return its exit code; ``127`` when it is not found."""
+        environment = {key: value for key, value in os.environ.items() if key != "VIRTUAL_ENV"}
+        environment.update(env or {})
+        try:
+            process = subprocess.Popen(list(argv), cwd=cwd, env=environment)  # noqa: S603 — argv is built by a command.
+        except FileNotFoundError:
+            return NOT_FOUND
+        try:
+            return process.wait()
+        except KeyboardInterrupt:
+            return process.wait()

xtr_cli/template.py

@@ -0,0 +1,178 @@
+"""Template: the files a project starts with, and the packages it is made of."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+from string import Template as Placeholders
+from typing import TYPE_CHECKING, final
+
+from .exception import InvalidTemplateError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from importlib.resources.abc import Traversable
+
+__all__ = ["MANIFEST", "Template"]
+
+MANIFEST = "template.toml"
+"""The file that makes a directory a template."""
+
+_TABLES = frozenset({"summary", "dependencies", "files", "notes"})
+_DEPENDENCY_KEYS = frozenset({"packages", "dev"})
+_NOTE_KEYS = frozenset({"next"})
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Template:
+    """A project template, read from a directory holding a ``template.toml``.
+
+    A template writes only what no package's recipe can write: the project's
+    manifest, its kernel and its entry points. The bundle list, the ``.env``
+    file and the ignore lines are left to the recipes of the packages it names,
+    applied once they are installed — so a new project is already in the state
+    ``recipes:sync --check`` expects.
+
+    The manifest::
+
+        summary = "A console application."
+
+        [dependencies]
+        packages = ["xtr-console[di]"]   # installed with `uv add`
+        dev = ["xtr-recipes"]            # installed with `uv add --dev`
+
+        [files]
+        # destination in the project = template under this directory
+        "src/${app}/kernel.py" = "files/kernel.py.tmpl"
+
+        [notes]
+        next = ["uv run ${name} list"]   # printed once the project is made
+
+    Destinations, file contents and notes substitute ``${name}`` (the
+    distribution), ``${app}`` (the import name), ``${python}`` (``3.13``) and
+    ``${minor}`` (``13``) with :meth:`string.Template.substitute`; a literal
+    ``$`` is written ``$$``.
+
+    Attributes:
+        name: The template's name — the name of its directory.
+        summary: One line on what it makes.
+        dependencies: The requirements every project made from it starts with.
+        dev_dependencies: The development requirements it starts with.
+        files: Each destination pattern mapped to the template text written there.
+        next_steps: Commands to try once the project is made.
+    """
+
+    name: str
+    summary: str
+    dependencies: tuple[str, ...]
+    dev_dependencies: tuple[str, ...]
+    files: tuple[tuple[str, str], ...]
+    next_steps: tuple[str, ...]
+
+    @classmethod
+    def load(cls, root: Traversable, name: str) -> Template:
+        """Read the template in ``root``, called ``name``.
+
+        Raises:
+            InvalidTemplateError: When the manifest does not parse, holds an
+                unknown table or key or a value of the wrong type, or names a
+                template file that is not there.
+        """
+        try:
+            data = tomllib.loads((root / MANIFEST).read_text(encoding="utf-8"))
+        except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError) as error:
+            raise InvalidTemplateError(name, f"{MANIFEST} cannot be read: {error}") from error
+        _only(name, "the manifest", data, _TABLES)
+        summary = data.get("summary", "")
+        if not isinstance(summary, str):
+            raise InvalidTemplateError(name, "summary must be a string")
+        dependencies = _table(name, data, "dependencies", _DEPENDENCY_KEYS)
+        notes = _table(name, data, "notes", _NOTE_KEYS)
+        return cls(
+            name=name,
+            summary=summary,
+            dependencies=_strings(name, dependencies, "dependencies.packages"),
+            dev_dependencies=_strings(name, dependencies, "dependencies.dev"),
+            files=_files(name, root, data),
+            next_steps=_strings(name, notes, "notes.next"),
+        )
+
+    def render(self, values: Mapping[str, str]) -> tuple[tuple[str, str], ...]:
+        """Return every file this template writes, as ``(path, text)``, with ``values`` in.
+
+        Raises:
+            InvalidTemplateError: When a destination or a file holds a
+                placeholder ``values`` does not have, or a destination leaves
+                the project directory.
+        """
+        rendered: list[tuple[str, str]] = []
+        for pattern, text in self.files:
+            destination = self._substitute(pattern, values, f"destination {pattern!r}")
+            path = PurePosixPath(destination)
+            if path.is_absolute() or ".." in path.parts:
+                raise InvalidTemplateError(self.name, f"{destination!r} leaves the project")
+            rendered.append((str(path), self._substitute(text, values, f"file {pattern!r}")))
+        return tuple(rendered)
+
+    def steps(self, values: Mapping[str, str]) -> tuple[str, ...]:
+        """Return the next steps with ``values`` in.
+
+        Raises:
+            InvalidTemplateError: When a step holds a placeholder ``values``
+                does not have.
+        """
+        return tuple(self._substitute(step, values, "notes.next") for step in self.next_steps)
+
+    def _substitute(self, text: str, values: Mapping[str, str], where: str) -> str:
+        try:
+            return Placeholders(text).substitute(values)
+        except KeyError as error:
+            raise InvalidTemplateError(
+                self.name, f"{where}: unknown placeholder {error}"
+            ) from error
+        except ValueError as error:
+            raise InvalidTemplateError(self.name, f"{where}: {error}") from error
+
+
+def _only(name: str, where: str, data: Mapping[str, object], allowed: frozenset[str]) -> None:
+    """Refuse a key ``allowed`` does not hold, so a typo is not silently ignored."""
+    unknown = sorted(set(data) - allowed)
+    if unknown:
+        raise InvalidTemplateError(name, f"unknown key {unknown[0]!r} in {where}")
+
+
+def _table(
+    name: str, data: Mapping[str, object], key: str, allowed: frozenset[str]
+) -> Mapping[str, object]:
+    """Return the table ``key``, empty when absent, holding nothing but ``allowed``."""
+    table = data.get(key, {})
+    if not isinstance(table, dict):
+        raise InvalidTemplateError(name, f"{key} must be a table")
+    _only(name, f"[{key}]", table, allowed)
+    return table
+
+
+def _strings(name: str, table: Mapping[str, object], dotted: str) -> tuple[str, ...]:
+    """Return the list of strings at ``dotted``'s last part, empty when absent."""
+    value = table.get(dotted.rpartition(".")[2], [])
+    if not isinstance(value, list) or not all(isinstance(each, str) for each in value):
+        raise InvalidTemplateError(name, f"{dotted} must be a list of strings")
+    return tuple(value)
+
+
+def _files(name: str, root: Traversable, data: Mapping[str, object]) -> tuple[tuple[str, str], ...]:
+    """Return each destination mapped to the text of the template file it names."""
+    table = data.get("files", {})
+    if not isinstance(table, dict):
+        raise InvalidTemplateError(name, "files must be a table")
+    files: list[tuple[str, str]] = []
+    for destination, source in table.items():
+        if not isinstance(source, str):
+            raise InvalidTemplateError(name, f"files.{destination!r} must name a file")
+        found = root.joinpath(*PurePosixPath(source).parts)
+        if ".." in PurePosixPath(source).parts or not found.is_file():
+            raise InvalidTemplateError(name, f"files.{destination!r}: no file {source!r}")
+        files.append((destination, found.read_text(encoding="utf-8")))
+    return tuple(files)