xtr-cli 4.0.2__py3-none-any.whl

xtr_cli/__init__.py

@@ -0,0 +1,79 @@
+"""Creates a new application on the xtr packages, ready to run, in one command.
+
+``xtr new <directory>`` asks for what it was not told — the template, the
+add-ons — writes the few files no package's recipe can (the project manifest,
+the kernel and the entry points), installs the packages with ``uv``, and lets
+each package's recipe configure itself with ``xtr-recipes recipes:sync``. The
+project it leaves boots, and is already in the state a recipe check expects.
+
+This module exposes the pieces that plan and make a project; the commands that
+drive them live in :mod:`xtr_cli.command`, behind the ``xtr`` console script.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .add_on import AddOn
+from .add_on_catalog import AddOnCatalog
+from .add_on_choice import AddOnChoice
+from .exception import (
+    AmbiguousWebEntryPointError,
+    CliError,
+    DirectoryNotEmptyError,
+    InvalidProjectNameError,
+    InvalidTemplateError,
+    ProjectNotFoundError,
+    StepFailedError,
+    UnknownAddOnError,
+    UnknownTemplateError,
+    UnsupportedPythonError,
+    WebEntryPointNotFoundError,
+)
+from .process_runner_interface import ProcessRunnerInterface
+from .project_name import ProjectName
+from .project_questions import ProjectQuestions
+from .project_settings import ProjectSettings
+from .scaffold_plan import ScaffoldPlan
+from .scaffolder import Scaffolder
+from .subprocess_runner import SubprocessRunner
+from .template import Template
+from .template_catalog import TemplateCatalog
+from .web_entry_point import WebEntryPoint
+from .web_entry_point_finder import WebEntryPointFinder
+
+try:
+    __version__ = version("xtr-cli")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree with no installed metadata to read. Having no
+    # version is better than refusing to import.
+    __version__ = "0+unknown"
+
+__all__ = [
+    "AddOn",
+    "AddOnCatalog",
+    "AddOnChoice",
+    "AmbiguousWebEntryPointError",
+    "CliError",
+    "DirectoryNotEmptyError",
+    "InvalidProjectNameError",
+    "InvalidTemplateError",
+    "ProcessRunnerInterface",
+    "ProjectName",
+    "ProjectNotFoundError",
+    "ProjectQuestions",
+    "ProjectSettings",
+    "ScaffoldPlan",
+    "Scaffolder",
+    "StepFailedError",
+    "SubprocessRunner",
+    "Template",
+    "TemplateCatalog",
+    "UnknownAddOnError",
+    "UnknownTemplateError",
+    "UnsupportedPythonError",
+    "WebEntryPoint",
+    "WebEntryPointFinder",
+    "WebEntryPointNotFoundError",
+    "__version__",
+]

xtr_cli/__main__.py

@@ -0,0 +1,28 @@
+"""The console entry point: ``uvx xtr-cli <command>``, or ``xtr <command>`` once installed.
+
+A console of its own, not an application's kernel: it runs before there is an
+application to boot.
+"""
+
+from __future__ import annotations
+
+from xtr_console import Application
+
+from . import (
+    __version__,
+    command,  # noqa: F401  # pyright: ignore[reportUnusedImport] — declares the commands
+)
+
+__all__ = ["main"]
+
+_DESCRIPTION = "Creates a new xtr application — a console or a web application — and serves it."
+
+
+def main() -> None:
+    """Build the console application and run it, exiting with its code."""
+    application = Application(name="xtr", version=__version__, description=_DESCRIPTION)
+    raise SystemExit(application.run())
+
+
+if __name__ == "__main__":
+    main()

xtr_cli/add_on.py

@@ -0,0 +1,52 @@
+"""AddOn: a package a new project can start with, beyond what its template brings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, final
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = ["AddOn"]
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class AddOn:
+    """One entry of the add-on table: a short name standing for a requirement.
+
+    Choosing an add-on only adds its requirement; the recipe the package ships
+    does the rest of the configuring, the way it would for a package added later.
+
+    Attributes:
+        name: What ``--with`` calls it.
+        summary: One line on what it brings, shown when the add-ons are offered.
+        distribution: The package it installs.
+        extras: The extras always installed with it — its bundle's among them.
+        variants: The further extras a project picks between, such as database
+            drivers; written after the name as ``orm:sqlite+postgres``.
+        default_variants: The variants chosen when the name is given alone.
+        variant_label: What the variants are, for the question that offers them.
+        templates: The templates it fits; empty when it fits every one.
+    """
+
+    name: str
+    summary: str
+    distribution: str
+    extras: tuple[str, ...] = ()
+    variants: tuple[str, ...] = ()
+    default_variants: tuple[str, ...] = ()
+    variant_label: str = "extras"
+    templates: tuple[str, ...] = ()
+
+    def requirement(self, variants: Sequence[str]) -> str:
+        """Return the requirement installing this add-on with ``variants``."""
+        extras = (*self.extras, *variants)
+        if not extras:
+            return self.distribution
+        return f"{self.distribution}[{','.join(extras)}]"
+
+    def fits(self, template: str) -> bool:
+        """Report whether a project made from ``template`` can take this add-on."""
+        return not self.templates or template in self.templates

xtr_cli/add_on_catalog.py

@@ -0,0 +1,167 @@
+"""AddOnCatalog: the add-ons a new project can start with, and how ``--with`` names them."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from .add_on import AddOn
+from .add_on_choice import AddOnChoice
+from .exception import UnknownAddOnError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+__all__ = ["AddOnCatalog"]
+
+_WEBAPP = ("webapp",)
+
+_SHIPPED = (
+    AddOn(
+        "orm",
+        "Database engines, sessions per unit of work and versioned migrations.",
+        "xtr-orm",
+        ("di", "console"),
+        ("sqlite", "postgres", "mysql"),
+        ("sqlite",),
+        "database drivers",
+    ),
+    AddOn(
+        "messenger",
+        "A message bus: handlers, middleware, transports and consumers.",
+        "xtr-messenger",
+        ("di", "console"),
+        ("amqp", "taskiq", "pydantic"),
+        (),
+        "transports and serializers",
+    ),
+    AddOn(
+        "scheduler",
+        "Recurring messages on the bus: cron and intervals.",
+        "xtr-scheduler",
+        ("di", "console", "cron"),
+    ),
+    AddOn(
+        "event-dispatcher",
+        "Events dispatched to listeners and subscribers by priority.",
+        "xtr-event-dispatcher",
+        ("di", "console"),
+    ),
+    AddOn(
+        "cache",
+        "Cache pools in memory, in files or in Redis.",
+        "xtr-cache",
+        ("di", "console"),
+        ("redis",),
+        (),
+        "backends",
+    ),
+    AddOn("lock", "Locks around shared resources.", "xtr-lock", ("di",), ("redis",), (), "stores"),
+    AddOn(
+        "rate-limiter",
+        "Limits on how often anything may happen.",
+        "xtr-rate-limiter",
+        ("di", "cache", "lock"),
+        ("redis",),
+        (),
+        "stores",
+    ),
+    AddOn(
+        "storage",
+        "Files on local disk, in memory or in object stores.",
+        "xtr-storage",
+        ("di",),
+        ("s3", "gcs"),
+        (),
+        "object stores",
+    ),
+    AddOn(
+        "security",
+        "Firewalls, authenticators, voters and password hashing.",
+        "xtr-security",
+        ("console",),
+        templates=_WEBAPP,
+    ),
+    AddOn(
+        "jwt",
+        "Self-issued JSON Web Tokens: a token manager and a firewall authenticator.",
+        "xtr-security-jwt",
+        ("console",),
+        templates=_WEBAPP,
+    ),
+)
+
+
+@final
+class AddOnCatalog:
+    """The add-ons on offer, looked up and parsed by name.
+
+    ``--with`` is a comma-separated list of names, each optionally followed by
+    ``:`` and its variants joined with ``+`` — ``orm:sqlite+postgres,messenger``.
+    A name given alone takes the add-on's default variants.
+    """
+
+    __slots__ = ("_add_ons",)
+
+    def __init__(self, add_ons: Iterable[AddOn]) -> None:
+        """Offer ``add_ons``, in the order given."""
+        self._add_ons: dict[str, AddOn] = {add_on.name: add_on for add_on in add_ons}
+
+    @classmethod
+    def default(cls) -> AddOnCatalog:
+        """Return the catalog of the add-ons this tool ships."""
+        return cls(_SHIPPED)
+
+    def available(self, template: str) -> tuple[AddOn, ...]:
+        """Return the add-ons a project made from ``template`` can take, in catalog order."""
+        return tuple(add_on for add_on in self._add_ons.values() if add_on.fits(template))
+
+    def get(self, name: str, template: str) -> AddOn:
+        """Return the add-on called ``name``, for a project made from ``template``.
+
+        Raises:
+            UnknownAddOnError: When no add-on has that name, or it does not fit
+                the template.
+        """
+        add_on = self._add_ons.get(name)
+        if add_on is None or not add_on.fits(template):
+            names = ", ".join(each.name for each in self.available(template))
+            raise UnknownAddOnError(name, f"a {template} project can take {names}")
+        return add_on
+
+    def choose(self, add_on: AddOn, variants: str | None) -> AddOnChoice:
+        """Return ``add_on`` with the ``+``-separated ``variants`` picked.
+
+        ``None`` takes the add-on's defaults; an empty string picks none.
+
+        Raises:
+            UnknownAddOnError: When a variant is not one the add-on offers.
+        """
+        if variants is None:
+            return AddOnChoice(add_on, add_on.default_variants)
+        picked = {variant.strip() for variant in variants.split("+") if variant.strip()}
+        unknown = sorted(picked - set(add_on.variants))
+        if unknown:
+            offered = ", ".join(add_on.variants) or "none"
+            raise UnknownAddOnError(
+                f"{add_on.name}:{variants}",
+                f"{', '.join(unknown)} is not one of its {add_on.variant_label} ({offered})",
+            )
+        return AddOnChoice(add_on, tuple(each for each in add_on.variants if each in picked))
+
+    def parse(self, text: str, template: str) -> tuple[AddOnChoice, ...]:
+        """Read a ``--with`` value into the add-ons it chooses, in the order written.
+
+        Raises:
+            UnknownAddOnError: When a name is unknown, does not fit the
+                template, is given twice, or names a variant its add-on lacks.
+        """
+        chosen: dict[str, AddOnChoice] = {}
+        for token in (each.strip() for each in text.split(",")):
+            if not token:
+                continue
+            name, separator, variants = token.partition(":")
+            add_on = self.get(name.strip(), template)
+            if add_on.name in chosen:
+                raise UnknownAddOnError(token, "it is chosen twice")
+            chosen[add_on.name] = self.choose(add_on, variants if separator else None)
+        return tuple(chosen.values())

xtr_cli/add_on_choice.py

@@ -0,0 +1,40 @@
+"""AddOnChoice: an add-on as a project chose it, variants and all."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, final
+
+if TYPE_CHECKING:
+    from .add_on import AddOn
+
+__all__ = ["AddOnChoice"]
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class AddOnChoice:
+    """An add-on and the variants picked for it.
+
+    Attributes:
+        add_on: The add-on chosen.
+        variants: The variants picked, in the order the add-on lists them.
+    """
+
+    add_on: AddOn
+    variants: tuple[str, ...]
+
+    @property
+    def requirement(self) -> str:
+        """The requirement ``uv add`` is given for this choice."""
+        return self.add_on.requirement(self.variants)
+
+    @property
+    def spelling(self) -> str:
+        """How ``--with`` writes this choice, so a command line can repeat it.
+
+        The bare name when the variants are the defaults, which it stands for.
+        """
+        if self.variants == self.add_on.default_variants:
+            return self.add_on.name
+        return f"{self.add_on.name}:{'+'.join(self.variants)}"

xtr_cli/command/__init__.py

@@ -0,0 +1,14 @@
+"""The commands: two that create a project, and one that serves it.
+
+Importing this package declares all of them: ``@as_command`` writes to the
+console's registry as each module is read, which is why the entry point imports
+this and nothing else.
+"""
+
+from __future__ import annotations
+
+from .init_command import InitCommand
+from .new_command import NewCommand
+from .serve_command import ServeCommand
+
+__all__ = ["InitCommand", "NewCommand", "ServeCommand"]

xtr_cli/command/init_command.py

@@ -0,0 +1,69 @@
+"""``project:init``: create an application in the current directory."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, final
+
+from xtr_console import ConsoleStyle, Option, as_command
+
+from xtr_cli import command_support
+
+__all__ = ["InitCommand"]
+
+
+@as_command("project:init", aliases="init")
+@final
+class InitCommand:
+    """Create a new application, from a template, in the current directory.
+
+    The directory must hold nothing but version-control or editor metadata;
+    an existing git repository is kept rather than initialised again.
+    """
+
+    async def __call__(  # noqa: PLR0913 — one parameter per option.
+        self,
+        io: ConsoleStyle,
+        *,
+        template: str | None = None,
+        name: str | None = None,
+        add_ons: Annotated[
+            str | None,
+            Option(
+                name="--with",
+                help="More packages to start with, comma-separated: orm:sqlite+postgres,messenger.",
+            ),
+        ] = None,
+        python: str | None = None,
+        no_git: bool = False,
+        dry_run: bool = False,
+        local_packages: Path | None = None,
+    ) -> int:
+        """Create a new application, from a template, in the current directory.
+
+        Args:
+            io: Where the questions are asked and the steps reported.
+            template: cli or webapp, or a directory holding a template.toml.
+            name: The project's name; the directory's name by default.
+            add_ons: The ``--with`` add-ons.
+            python: The 3.<minor> version to pin; the one running this tool by default.
+            no_git: Do not initialise a git repository.
+            dry_run: Print the files and commands, and write nothing.
+            local_packages: Install the xtr packages from this directory of
+                sources, editable, instead of the package index.
+
+        Returns:
+            The exit code.
+        """
+        return command_support.scaffold(
+            io,
+            command="init",
+            directory=Path.cwd(),
+            template=template,
+            name=name,
+            add_ons=add_ons,
+            python=python,
+            git=not no_git,
+            dry_run=dry_run,
+            local_packages=local_packages,
+        )

xtr_cli/command/new_command.py

@@ -0,0 +1,72 @@
+"""``project:new``: create an application in a new directory."""
+
+from __future__ import annotations
+
+from pathlib import Path  # noqa: TC003 — the console reads annotations at runtime.
+from typing import Annotated, final
+
+from xtr_console import ConsoleStyle, Option, as_command
+
+from xtr_cli import command_support
+
+__all__ = ["NewCommand"]
+
+
+@as_command("project:new", aliases="new")
+@final
+class NewCommand:
+    """Create a new application, from a template, in a new directory.
+
+    What is not given is asked for; with ``-n`` nothing is asked and the
+    defaults are taken. The packages are installed with ``uv``, and each one's
+    recipe is applied, before the command ends.
+    """
+
+    async def __call__(  # noqa: PLR0913 — one parameter per option.
+        self,
+        io: ConsoleStyle,
+        directory: Path | None = None,
+        *,
+        template: str | None = None,
+        name: str | None = None,
+        add_ons: Annotated[
+            str | None,
+            Option(
+                name="--with",
+                help="More packages to start with, comma-separated: orm:sqlite+postgres,messenger.",
+            ),
+        ] = None,
+        python: str | None = None,
+        no_git: bool = False,
+        dry_run: bool = False,
+        local_packages: Path | None = None,
+    ) -> int:
+        """Create a new application, from a template, in a new directory.
+
+        Args:
+            io: Where the questions are asked and the steps reported.
+            directory: Where to create it; it must be missing or empty.
+            template: cli or webapp, or a directory holding a template.toml.
+            name: The project's name; the directory's name by default.
+            add_ons: The ``--with`` add-ons.
+            python: The 3.<minor> version to pin; the one running this tool by default.
+            no_git: Do not initialise a git repository.
+            dry_run: Print the files and commands, and write nothing.
+            local_packages: Install the xtr packages from this directory of
+                sources, editable, instead of the package index.
+
+        Returns:
+            The exit code.
+        """
+        return command_support.scaffold(
+            io,
+            command="new",
+            directory=directory,
+            template=template,
+            name=name,
+            add_ons=add_ons,
+            python=python,
+            git=not no_git,
+            dry_run=dry_run,
+            local_packages=local_packages,
+        )

xtr_cli/command/serve_command.py

@@ -0,0 +1,114 @@
+"""``server:start``: serve the application the current directory belongs to."""
+
+from __future__ import annotations
+
+import shlex
+from pathlib import Path  # noqa: TC003 — the console reads annotations at runtime.
+from typing import TYPE_CHECKING, Annotated, final
+
+from xtr_console import ConsoleStyle, ExitCode, Option, Range, as_command, escape
+
+from xtr_cli import command_support
+from xtr_cli.exception import AmbiguousWebEntryPointError, CliError, WebEntryPointNotFoundError
+from xtr_cli.subprocess_runner import NOT_FOUND
+from xtr_cli.web_entry_point_finder import WebEntryPointFinder
+
+if TYPE_CHECKING:
+    from xtr_cli.web_entry_point import WebEntryPoint
+
+__all__ = ["ServeCommand"]
+
+_NONE_FOUND = (
+    "no console script imports a server or is named *-web, and no module defines a "
+    "FastAPI(), Starlette() or Litestar() application; pass --entrypoint"
+)
+
+
+@as_command("server:start", aliases="serve")
+@final
+class ServeCommand:
+    """Serve the application the current directory belongs to.
+
+    The web entry point is found in the project — its web console script, or
+    else a module-level ASGI application — and run in the project's own
+    environment with ``uv run``. The server restarts on every source change
+    unless ``--no-reload`` is given. Ctrl-C stops the server, and waits for the
+    application to shut down.
+    """
+
+    async def __call__(  # noqa: PLR0913 — one parameter per option.
+        self,
+        io: ConsoleStyle,
+        *,
+        project_dir: Path | None = None,
+        entrypoint: str | None = None,
+        host: str | None = None,
+        port: Annotated[
+            int | None,
+            Option(
+                validator=Range(gte=1, lte=65535),
+                help="The port to listen on; the entry point's own default when left out.",
+            ),
+        ] = None,
+        reload: Annotated[
+            bool,
+            Option(
+                negative="--no-reload",
+                help="Restart the server when a source file changes; --no-reload turns it off.",
+            ),
+        ] = True,
+        dry_run: bool = False,
+    ) -> int:
+        """Serve the application the current directory belongs to.
+
+        Args:
+            io: Where the choice is asked and the command reported.
+            project_dir: The project to serve; the nearest one at or above the
+                current directory by default.
+            entrypoint: What to serve: a console script, or a module:attribute
+                ASGI application. Found in the project when left out.
+            host: Where to listen; the entry point's own default when left out.
+            port: The port to listen on.
+            reload: Restart the server when a source file changes; on by default,
+                --no-reload turns it off.
+            dry_run: Print the command, and run nothing.
+
+        Returns:
+            The server's exit code, or a failure when there is nothing to serve.
+        """
+        finder = WebEntryPointFinder()
+        try:
+            directory = finder.project_dir(project_dir)
+            chosen = (
+                finder.resolve(directory, entrypoint)
+                if entrypoint is not None
+                else _choose(io, finder.find(directory), directory)
+            )
+        except CliError as error:
+            io.error(escape(str(error)))
+            return ExitCode.FAILURE
+        argv, environment = chosen.command(host, port, reload=reload)
+        assignments = [f"{key}={shlex.quote(value)}" for key, value in environment.items()]
+        io.text(escape(f"Serving {chosen.label} from {directory}"))
+        io.text(escape("  " + " ".join((*assignments, shlex.join(argv)))))
+        if dry_run:
+            return ExitCode.SUCCESS
+        code = command_support.build_runner().run(argv, directory, environment)
+        if code == NOT_FOUND:
+            io.error("uv is not on the PATH: install it from https://docs.astral.sh/uv/")
+        return code
+
+
+def _choose(
+    io: ConsoleStyle, candidates: tuple[WebEntryPoint, ...], directory: Path
+) -> WebEntryPoint:
+    """Return the one candidate, or the one picked; with no question possible, refuse."""
+    if not candidates:
+        raise WebEntryPointNotFoundError(directory, _NONE_FOUND)
+    if len(candidates) == 1:
+        return candidates[0]
+    labels = tuple(candidate.label for candidate in candidates)
+    if not io.interactive:
+        raise AmbiguousWebEntryPointError(labels)
+    picked = io.ask("Web entry point", labels[0], choices=labels)
+    return candidates[labels.index(picked)]