xtr-cli 4.0.2__py3-none-any.whl

xtr_cli/command_support.py

@@ -0,0 +1,189 @@
+"""What the commands share: the questions, the scaffolder, and how a run is reported.
+
+``project:new`` and ``project:init`` differ only in where the project goes, so
+both hand their options to :func:`scaffold`. It sits beside the
+:mod:`xtr_cli.command` package rather than in it, so a command module can
+import it without the package being imported back.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from typing import TYPE_CHECKING
+
+from xtr_console import ExitCode, escape
+
+from . import __version__
+from .add_on_catalog import AddOnCatalog
+from .exception import CliError, UnsupportedPythonError
+from .project_name import ProjectName
+from .project_questions import ProjectQuestions
+from .project_settings import ProjectSettings
+from .scaffolder import Scaffolder
+from .subprocess_runner import SubprocessRunner
+from .template_catalog import TemplateCatalog
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from xtr_console import ConsoleStyle
+
+    from .process_runner_interface import ProcessRunnerInterface
+    from .scaffold_plan import ScaffoldPlan
+
+__all__ = ["build_runner", "build_scaffolder", "default_python", "scaffold"]
+
+_PYTHON = re.compile(r"^3\.(?P<minor>\d+)$")
+_OLDEST_MINOR = 11
+
+
+def build_runner() -> ProcessRunnerInterface:
+    """Return what the commands start ``uv``, ``git`` and a server through.
+
+    The one seam between a command and a real process: a test replaces this
+    with a recorder.
+    """
+    return SubprocessRunner()
+
+
+def build_scaffolder() -> Scaffolder:
+    """Return the scaffolder a command makes its project with.
+
+    The one seam between a command and the processes it starts: a test
+    replaces this with a scaffolder over a recorder, so a project is planned
+    and written without installing anything.
+    """
+    return Scaffolder(build_runner(), __version__)
+
+
+def default_python() -> str:
+    """Return the ``3.<minor>`` of the interpreter this tool runs on."""
+    return f"{sys.version_info.major}.{sys.version_info.minor}"
+
+
+def scaffold(  # noqa: PLR0913 — one keyword per option the two commands share.
+    io: ConsoleStyle,
+    *,
+    command: str,
+    directory: Path | None,
+    template: str | None,
+    name: str | None,
+    add_ons: str | None,
+    python: str | None,
+    git: bool,
+    dry_run: bool,
+    local_packages: Path | None,
+) -> int:
+    """Settle the project from the options and the answers, then plan it and make it.
+
+    Returns:
+        Success once the project is made, or printed for a dry run;
+        :attr:`~xtr_console.ExitCode.INVALID` when no directory was given;
+        :attr:`~xtr_console.ExitCode.FAILURE` when a setting is refused or a
+        step fails.
+    """
+    questions = ProjectQuestions(io, TemplateCatalog.default(), AddOnCatalog.default())
+    try:
+        target = questions.directory(directory)
+        if target is None:
+            io.error("Give the directory to create the project in: xtr new <directory>")
+            return ExitCode.INVALID
+        settings = _settings(
+            questions,
+            command=command,
+            directory=target.expanduser().resolve(),
+            template=template,
+            name=name,
+            add_ons=add_ons,
+            python=python if python is not None else default_python(),
+            git=git,
+            local_packages=local_packages,
+        )
+        scaffolder = build_scaffolder()
+        plan = scaffolder.plan(settings)
+    except CliError as error:
+        io.error(escape(str(error)))
+        return ExitCode.FAILURE
+    _summarise(io, settings)
+    if dry_run:
+        for line in plan.render():
+            io.text(escape(line))
+        return ExitCode.SUCCESS
+    if not questions.confirm():
+        io.warning("Nothing was written.")
+        return ExitCode.SUCCESS
+    try:
+        scaffolder.apply(plan, lambda line: io.text(escape(line)))
+    except CliError as error:
+        io.error(escape(str(error)))
+        return ExitCode.FAILURE
+    _finish(io, settings, plan)
+    return ExitCode.SUCCESS
+
+
+def _settings(  # noqa: PLR0913 — the settings, one keyword each.
+    questions: ProjectQuestions,
+    *,
+    command: str,
+    directory: Path,
+    template: str | None,
+    name: str | None,
+    add_ons: str | None,
+    python: str,
+    git: bool,
+    local_packages: Path | None,
+) -> ProjectSettings:
+    """Settle every setting, asking for what is missing, refusing what cannot be used."""
+    Scaffolder.check_directory(directory)
+    project_name = ProjectName.parse(name if name is not None else directory.name)
+    version = _PYTHON.match(python)
+    if version is None or int(version.group("minor")) < _OLDEST_MINOR:
+        raise UnsupportedPythonError(python)
+    source = questions.template(template)
+    chosen = TemplateCatalog.default().load(source)
+    return ProjectSettings(
+        command=command,
+        directory=directory,
+        name=project_name,
+        template=chosen,
+        template_source=source,
+        add_ons=questions.add_ons(add_ons, chosen.name),
+        python=python,
+        name_given=name is not None,
+        git=git,
+        local_packages=local_packages.expanduser().resolve() if local_packages else None,
+    )
+
+
+def _summarise(io: ConsoleStyle, settings: ProjectSettings) -> None:
+    """Print what is about to be made, and the command that makes it with no question."""
+    add_ons = ", ".join(
+        f"{choice.add_on.name} ({', '.join(choice.variants)})"
+        if choice.variants
+        else choice.add_on.name
+        for choice in settings.add_ons
+    )
+    io.section(escape(f"{settings.name.distribution} — the {settings.template.name} template"))
+    io.listing(
+        escape(line)
+        for line in (
+            f"directory: {settings.directory}",
+            f"add-ons:   {add_ons or 'none'}",
+            f"python:    {settings.python}",
+        )
+    )
+    io.text("The same, with no question asked:")
+    io.text(escape(f"  {settings.command_line()}"))
+    io.newline()
+
+
+def _finish(io: ConsoleStyle, settings: ProjectSettings, plan: ScaffoldPlan) -> None:
+    """Say the project is ready, and what to run first."""
+    io.success(escape(f"{settings.name.distribution} is ready in {settings.directory}"))
+    steps = plan.next_steps
+    if settings.command == "new":
+        steps = (f"cd {settings.directory}", *steps)
+    if steps:
+        io.section("Next steps")
+        io.listing(escape(step) for step in steps)

xtr_cli/exception/__init__.py

@@ -0,0 +1,34 @@
+"""Every error this library raises.
+
+All of them derive from :class:`CliError`, so one ``except`` catches anything
+scaffolding a project can go wrong with, and a narrower one handles a single
+cause.
+"""
+
+from __future__ import annotations
+
+from .ambiguous_web_entry_point_error import AmbiguousWebEntryPointError
+from .cli_error import CliError
+from .directory_not_empty_error import DirectoryNotEmptyError
+from .invalid_project_name_error import InvalidProjectNameError
+from .invalid_template_error import InvalidTemplateError
+from .project_not_found_error import ProjectNotFoundError
+from .step_failed_error import StepFailedError
+from .unknown_add_on_error import UnknownAddOnError
+from .unknown_template_error import UnknownTemplateError
+from .unsupported_python_error import UnsupportedPythonError
+from .web_entry_point_not_found_error import WebEntryPointNotFoundError
+
+__all__ = [
+    "AmbiguousWebEntryPointError",
+    "CliError",
+    "DirectoryNotEmptyError",
+    "InvalidProjectNameError",
+    "InvalidTemplateError",
+    "ProjectNotFoundError",
+    "StepFailedError",
+    "UnknownAddOnError",
+    "UnknownTemplateError",
+    "UnsupportedPythonError",
+    "WebEntryPointNotFoundError",
+]

xtr_cli/exception/ambiguous_web_entry_point_error.py

@@ -0,0 +1,27 @@
+"""A project with several web entry points, and no way to ask which one to serve."""
+
+from __future__ import annotations
+
+from typing import final
+
+from .cli_error import CliError
+
+__all__ = ["AmbiguousWebEntryPointError"]
+
+
+@final
+class AmbiguousWebEntryPointError(CliError):
+    """Several web entry points were found and questions are off.
+
+    Attributes:
+        candidates: The entry points found, as ``--entrypoint`` takes them.
+    """
+
+    candidates: tuple[str, ...]
+
+    def __init__(self, candidates: tuple[str, ...]) -> None:
+        """Record what could have been served."""
+        self.candidates = candidates
+        super().__init__(
+            f"several web entry points ({', '.join(candidates)}): pass --entrypoint to choose one"
+        )

xtr_cli/exception/cli_error.py

@@ -0,0 +1,14 @@
+"""The root every error in this library derives from."""
+
+from __future__ import annotations
+
+__all__ = ["CliError"]
+
+
+class CliError(Exception):
+    """Base class for every error raised by this library.
+
+    Catch this to handle anything scaffolding a project can go wrong with; catch
+    a subclass to handle one cause. Every subclass carries what went wrong as
+    typed attributes and composes its own message from them.
+    """

xtr_cli/exception/directory_not_empty_error.py

@@ -0,0 +1,35 @@
+"""A project directory that already holds something a project would clash with."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from .cli_error import CliError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+__all__ = ["DirectoryNotEmptyError"]
+
+
+@final
+class DirectoryNotEmptyError(CliError):
+    """The directory to scaffold into is a file, or already holds files.
+
+    Nothing is ever written over: a project starts in a directory that is
+    missing or holds nothing but version-control and editor metadata.
+
+    Attributes:
+        directory: The directory asked for.
+        found: The entries that are in the way, sorted.
+    """
+
+    directory: Path
+    found: tuple[str, ...]
+
+    def __init__(self, directory: Path, found: tuple[str, ...]) -> None:
+        """Record the directory and what is already in it."""
+        self.directory = directory
+        self.found = found
+        listed = ", ".join(found[:5]) + (", …" if len(found) > 5 else "")  # noqa: PLR2004 — a preview.
+        super().__init__(f"{directory} is not empty ({listed}): choose a new directory")

xtr_cli/exception/invalid_project_name_error.py

@@ -0,0 +1,33 @@
+"""A project name that cannot name both a distribution and an import package."""
+
+from __future__ import annotations
+
+from typing import final
+
+from .cli_error import CliError
+
+__all__ = ["InvalidProjectNameError"]
+
+
+@final
+class InvalidProjectNameError(CliError):
+    """The name asked for, or the directory it was read from, cannot name the project.
+
+    The name becomes the distribution, the console script and — dashes turned
+    into underscores — the import package under ``src/``. A name that is not a
+    valid identifier once turned, is a keyword, or would shadow a module of the
+    standard library would leave an application that cannot import itself.
+
+    Attributes:
+        name: The name as it was given.
+        reason: Why it cannot be used.
+    """
+
+    name: str
+    reason: str
+
+    def __init__(self, name: str, reason: str) -> None:
+        """Record the name and why it was refused."""
+        self.name = name
+        self.reason = reason
+        super().__init__(f"{name!r} cannot name a project: {reason}; pass --name to choose another")

xtr_cli/exception/invalid_template_error.py

@@ -0,0 +1,28 @@
+"""A template whose ``template.toml`` cannot be read as one."""
+
+from __future__ import annotations
+
+from typing import final
+
+from .cli_error import CliError
+
+__all__ = ["InvalidTemplateError"]
+
+
+@final
+class InvalidTemplateError(CliError):
+    """A ``template.toml`` that does not parse, or holds a key or value it may not.
+
+    Attributes:
+        template: The template's name — its directory's name.
+        reason: What is wrong, naming the key at fault.
+    """
+
+    template: str
+    reason: str
+
+    def __init__(self, template: str, reason: str) -> None:
+        """Record the template and what is wrong with it."""
+        self.template = template
+        self.reason = reason
+        super().__init__(f"template {template!r}: {reason}")

xtr_cli/exception/project_not_found_error.py

@@ -0,0 +1,28 @@
+"""No project at or above the directory a command was run from."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from .cli_error import CliError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+__all__ = ["ProjectNotFoundError"]
+
+
+@final
+class ProjectNotFoundError(CliError):
+    """No ``pyproject.toml`` lies at or above the directory searched.
+
+    Attributes:
+        directory: Where the search started.
+    """
+
+    directory: Path
+
+    def __init__(self, directory: Path) -> None:
+        """Record where the search started."""
+        self.directory = directory
+        super().__init__(f"no pyproject.toml in {directory} or above it: pass --project-dir")

xtr_cli/exception/step_failed_error.py

@@ -0,0 +1,38 @@
+"""A command the scaffold runs — ``uv`` or ``git`` — that exited with a failure."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from .cli_error import CliError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+__all__ = ["StepFailedError"]
+
+
+@final
+class StepFailedError(CliError):
+    """One of the commands that finish a project failed; the rest were not run.
+
+    The command has already said why on its own streams. What it left behind is
+    kept: the files written so far are the project, and running the remaining
+    commands by hand — or deleting the directory — is the way on.
+
+    Attributes:
+        argv: The command that failed, program and all.
+        cwd: Where it ran.
+        code: The exit code it ended with.
+    """
+
+    argv: tuple[str, ...]
+    cwd: Path
+    code: int
+
+    def __init__(self, argv: tuple[str, ...], cwd: Path, code: int) -> None:
+        """Record the command, where it ran, and how it ended."""
+        self.argv = argv
+        self.cwd = cwd
+        self.code = code
+        super().__init__(f"`{' '.join(argv)}` exited with {code} in {cwd}")

xtr_cli/exception/unknown_add_on_error.py

@@ -0,0 +1,28 @@
+"""An add-on this tool does not know, or one the chosen template cannot take."""
+
+from __future__ import annotations
+
+from typing import final
+
+from .cli_error import CliError
+
+__all__ = ["UnknownAddOnError"]
+
+
+@final
+class UnknownAddOnError(CliError):
+    """``--with`` names an add-on, or a variant of one, that cannot be added.
+
+    Attributes:
+        add_on: The add-on as it was spelled.
+        reason: Why it cannot be added, naming what could be chosen instead.
+    """
+
+    add_on: str
+    reason: str
+
+    def __init__(self, add_on: str, reason: str) -> None:
+        """Record the add-on and why it was refused."""
+        self.add_on = add_on
+        self.reason = reason
+        super().__init__(f"cannot add {add_on!r}: {reason}")

xtr_cli/exception/unknown_template_error.py

@@ -0,0 +1,29 @@
+"""A template that is neither shipped nor a directory holding one."""
+
+from __future__ import annotations
+
+from typing import final
+
+from .cli_error import CliError
+
+__all__ = ["UnknownTemplateError"]
+
+
+@final
+class UnknownTemplateError(CliError):
+    """``--template`` names no shipped template and no directory with a ``template.toml``.
+
+    Attributes:
+        template: The value given.
+        available: The names of the templates that ship with this tool.
+    """
+
+    template: str
+    available: tuple[str, ...]
+
+    def __init__(self, template: str, available: tuple[str, ...]) -> None:
+        """Record the value and what could have been chosen instead."""
+        self.template = template
+        self.available = available
+        choices = ", ".join(available)
+        super().__init__(f"no template {template!r}: choose {choices}, or a template directory")

xtr_cli/exception/unsupported_python_error.py

@@ -0,0 +1,28 @@
+"""A Python version the new project cannot be pinned to."""
+
+from __future__ import annotations
+
+from typing import final
+
+from .cli_error import CliError
+
+__all__ = ["UnsupportedPythonError"]
+
+
+@final
+class UnsupportedPythonError(CliError):
+    """``--python`` is not a ``3.<minor>`` version the packages support.
+
+    Every xtr package requires Python 3.11 or later, so a project pinned below
+    that could install none of them.
+
+    Attributes:
+        python: The version as it was given.
+    """
+
+    python: str
+
+    def __init__(self, python: str) -> None:
+        """Record the version that was refused."""
+        self.python = python
+        super().__init__(f"--python {python!r}: give a version 3.11 or later, such as 3.13")

xtr_cli/exception/web_entry_point_not_found_error.py

@@ -0,0 +1,31 @@
+"""A project with no web entry point to serve, or one named that it does not have."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from .cli_error import CliError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+__all__ = ["WebEntryPointNotFoundError"]
+
+
+@final
+class WebEntryPointNotFoundError(CliError):
+    """Nothing in the project can be served, or ``--entrypoint`` names nothing it has.
+
+    Attributes:
+        project_dir: The project searched.
+        reason: What was looked for and not found.
+    """
+
+    project_dir: Path
+    reason: str
+
+    def __init__(self, project_dir: Path, reason: str) -> None:
+        """Record the project and what it lacks."""
+        self.project_dir = project_dir
+        self.reason = reason
+        super().__init__(f"nothing to serve in {project_dir}: {reason}")

xtr_cli/process_runner_interface.py

@@ -0,0 +1,29 @@
+"""What the commands run ``uv``, ``git`` and an application's server through."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+
+__all__ = ["ProcessRunnerInterface"]
+
+
+@runtime_checkable
+class ProcessRunnerInterface(Protocol):
+    """Runs one command to completion and reports how it ended.
+
+    Structural on purpose: the default starts a real process, while a test
+    supplies a recorder, so a project can be planned and written without
+    installing anything.
+    """
+
+    def run(self, argv: Sequence[str], cwd: Path, env: Mapping[str, str] | None = None) -> int:
+        """Run ``argv`` in ``cwd``, its output going straight to the terminal; return its code.
+
+        ``env`` holds variables set for the command on top of this process's
+        own environment.
+        """
+        ...

xtr_cli/project_name.py

@@ -0,0 +1,55 @@
+"""ProjectName: the one name a project goes by, as a distribution and as a package."""
+
+from __future__ import annotations
+
+import keyword
+import re
+import sys
+from dataclasses import dataclass
+from typing import final
+
+from .exception import InvalidProjectNameError
+
+__all__ = ["ProjectName"]
+
+# Anything but a lowercase letter or a digit separates words; a run of them is one dash.
+_SEPARATORS = re.compile(r"[^a-z0-9]+")
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class ProjectName:
+    """A project's name, normalised once and used everywhere it appears.
+
+    The distribution name is also the console script, so ``uv run <name>``
+    reads as the project's own command; the import name is the package under
+    ``src/`` that the kernel scans.
+
+    Attributes:
+        distribution: The lowercase, dash-separated name in ``[project].name``.
+        app: The import name: the distribution with its dashes as underscores.
+    """
+
+    distribution: str
+    app: str
+
+    @classmethod
+    def parse(cls, text: str) -> ProjectName:
+        """Normalise ``text`` — a ``--name`` or a directory's name — into a project name.
+
+        Raises:
+            InvalidProjectNameError: When nothing is left once normalised, or the
+                import name it gives is not an identifier, is a keyword, or is
+                a module of the standard library the application would shadow.
+        """
+        distribution = _SEPARATORS.sub("-", text.strip().lower()).strip("-")
+        if not distribution:
+            raise InvalidProjectNameError(text, "it holds no letter or digit")
+        app = distribution.replace("-", "_")
+        if not app.isidentifier():
+            raise InvalidProjectNameError(text, f"{app!r} is not a valid import name")
+        if keyword.iskeyword(app):
+            raise InvalidProjectNameError(text, f"{app!r} is a Python keyword")
+        if app in sys.stdlib_module_names:
+            raise InvalidProjectNameError(text, f"{app!r} would shadow the standard library")
+        return cls(distribution=distribution, app=app)