xtr-cli 4.0.2__py3-none-any.whl

xtr_cli/template_catalog.py

@@ -0,0 +1,62 @@
+"""TemplateCatalog: the templates shipped with this tool, and any directory holding one."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+from typing import TYPE_CHECKING, final
+
+from .exception import UnknownTemplateError
+from .template import MANIFEST, Template
+
+if TYPE_CHECKING:
+    from importlib.resources.abc import Traversable
+
+__all__ = ["TemplateCatalog"]
+
+_SHIPPED = "xtr_cli.templates"
+
+
+@final
+class TemplateCatalog:
+    """Finds a template by the name it ships under, or by a directory on disk.
+
+    The shipped templates live inside this package, so they are the ones
+    written for the packages of the same release.
+    """
+
+    __slots__ = ("_root",)
+
+    def __init__(self, root: Traversable) -> None:
+        """Offer the templates in the subdirectories of ``root``."""
+        self._root = root
+
+    @classmethod
+    def default(cls) -> TemplateCatalog:
+        """Return the catalog of the templates this tool ships."""
+        return cls(files(_SHIPPED))
+
+    def names(self) -> tuple[str, ...]:
+        """Return the names of the shipped templates, sorted."""
+        return tuple(
+            sorted(
+                entry.name
+                for entry in self._root.iterdir()
+                if entry.is_dir() and entry.joinpath(MANIFEST).is_file()
+            )
+        )
+
+    def load(self, template: str) -> Template:
+        """Return the shipped template called ``template``, or the one in that directory.
+
+        Raises:
+            UnknownTemplateError: When ``template`` is neither a shipped name
+                nor a directory holding a ``template.toml``.
+            InvalidTemplateError: When the template found cannot be read.
+        """
+        if template in self.names():
+            return Template.load(self._root / template, template)
+        directory = Path(template).expanduser()
+        if directory.joinpath(MANIFEST).is_file():
+            return Template.load(directory, directory.resolve().name)
+        raise UnknownTemplateError(template, self.names())

xtr_cli/templates/__init__.py

@@ -0,0 +1,10 @@
+"""The templates this tool ships, one directory each, read as package data.
+
+A real package so the build carries every ``template.toml`` and ``*.tmpl``
+file beside it in the wheel. Nothing here is imported or run: the files are
+templates, named ``*.tmpl`` so they are never linted or type-checked as code.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_cli/templates/cli/files/README.md.tmpl

@@ -0,0 +1,44 @@
+# ${name}
+
+A console application on the xtr packages.
+
+## Run
+
+```sh
+uv run ${name}                  # every command
+uv run ${name} app:hello Ada    # the example command
+uv run ${name} debug:bundles    # the bundles and whether each is active
+```
+
+The environment is read from `.env`, then `.env.local`, then `.env.<APP_ENV>` and
+`.env.<APP_ENV>.local`; a variable set in the shell wins. Keep machine-specific values in
+`.env.local`, which is not committed.
+
+## Layout
+
+```
+src/${app}/
+├── __main__.py        the console entry point
+├── kernel.py          the kernel every entry point builds, and the environment loader
+├── bundles.py         the active bundles — written by xtr-recipes
+└── command/           the console commands
+```
+
+## Add a package
+
+```sh
+uv run xtr-recipes recipes:add "xtr-messenger[di,console]"
+```
+
+It installs the package and applies its recipe — the bundle, its configuration file, its
+environment variables — and prints any step left to do by hand. `xtr.lock` records what was
+applied; commit it.
+
+## Check
+
+```sh
+uv run pytest
+uv run ruff check && uv run ruff format --check
+uv run basedpyright && uv run ty check
+uv run xtr-recipes recipes:sync --check
+```

xtr_cli/templates/cli/files/app/__init__.py.tmpl

@@ -0,0 +1,5 @@
+"""${name}: a console application on the xtr packages."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_cli/templates/cli/files/app/__main__.py.tmpl

@@ -0,0 +1,23 @@
+"""The console entry point: ``uv run ${name} <command>`` or ``python -m ${app} <command>``.
+
+``*.__main__`` modules are never scanned by the kernel, so importing the application never
+runs it.
+"""
+
+from __future__ import annotations
+
+from xtr_console.bundle import console
+
+from ${app}.kernel import kernel, load_environment
+
+__all__ = ["main"]
+
+
+def main() -> None:
+    """Load the environment, then boot, run the console, shut down and exit with its code."""
+    load_environment()
+    raise SystemExit(kernel.run(console))
+
+
+if __name__ == "__main__":
+    main()

xtr_cli/templates/cli/files/app/command/__init__.py.tmpl

@@ -0,0 +1,5 @@
+"""The console commands: every module here is scanned, and each ``@as_command`` registered."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_cli/templates/cli/files/app/command/hello_command.py.tmpl

@@ -0,0 +1,19 @@
+"""``app:hello``: the example command — replace it with your own."""
+
+from __future__ import annotations
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+__all__ = ["hello"]
+
+
+@as_command("app:hello")
+async def hello(io: ConsoleStyle, name: str = "world") -> int:
+    """Greet someone.
+
+    Args:
+        io: Where the command writes.
+        name: Who to greet.
+    """
+    io.success(f"Hello, {escape(name)}!")
+    return ExitCode.SUCCESS

xtr_cli/templates/cli/files/app/kernel.py.tmpl

@@ -0,0 +1,34 @@
+"""The kernel every entry point builds, and the environment it is built for.
+
+``Kernel(...)`` stores a recipe and does no work; ``build()``, ``boot()`` and ``run()`` do,
+each time afresh, so every entry point builds its own container from the same line.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Final
+
+from xtr_dependency_injection import Kernel, exclude
+from xtr_dotenv import Dotenv
+
+__all__ = ["PROJECT_DIR", "kernel", "load_environment"]
+
+PROJECT_DIR: Final = Path(__file__).resolve().parents[2]
+"""The directory holding ``pyproject.toml`` and the ``.env`` files."""
+
+kernel: Final = Kernel(
+    "${app}",
+    # The bundles are read from ${app}.bundles.BUNDLES; the environment from APP_ENV.
+    allowed_envs=("dev", "test", "prod"),
+)
+
+
+@exclude
+def load_environment() -> None:
+    """Load the layered ``.env`` files into the environment, before the kernel is built.
+
+    ``@exclude`` keeps this helper out of the container: it is an entry point's concern,
+    never a service.
+    """
+    _ = Dotenv().boot_env(str(PROJECT_DIR / ".env"))

xtr_cli/templates/cli/files/gitignore.tmpl

@@ -0,0 +1,14 @@
+# Python
+__pycache__/
+*.py[cod]
+/.venv/
+/dist/
+/build/
+
+# Tools
+/.pytest_cache/
+/.ruff_cache/
+/.coverage
+
+# What the application writes while it runs
+/var/

xtr_cli/templates/cli/files/pyproject.toml.tmpl

@@ -0,0 +1,59 @@
+[project]
+name = "${name}"
+version = "0.1.0"
+description = "A console application on the xtr packages."
+readme = "README.md"
+requires-python = ">=${python}"
+dependencies = []
+
+[project.scripts]
+${name} = "${app}.__main__:main"
+
+[dependency-groups]
+dev = []
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.basedpyright]
+typeCheckingMode = "all"
+pythonVersion = "${python}"
+include = ["src", "tests"]
+exclude = ["**/__pycache__", "**/.venv", "var"]
+reportUnusedCallResult = "warning"
+
+[tool.ruff]
+target-version = "py3${minor}"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # Formatter conflicts.
+    "COM812",
+    "ISC001",
+    # Mutually exclusive docstring conventions; keep the modern one.
+    "D203",
+    "D213",
+    "CPY001",
+    # The container and the console read annotations at runtime: an import used only in
+    # an annotation is still needed at runtime, so none may move under TYPE_CHECKING.
+    "TC001",
+    "TC002",
+    "TC003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-config", "--strict-markers"]

xtr_cli/templates/cli/files/python-version.tmpl

@@ -0,0 +1 @@
+${python}

xtr_cli/templates/cli/files/tests/test_kernel.py.tmpl

@@ -0,0 +1,9 @@
+"""The application's kernel builds, with every listed bundle."""
+
+from __future__ import annotations
+
+from ${app}.kernel import kernel
+
+
+def test_the_kernel_builds_in_the_test_environment() -> None:
+    _ = kernel.with_env("test").build()

xtr_cli/templates/cli/template.toml

@@ -0,0 +1,34 @@
+# A console application: the kernel, the console entry point and one command.
+summary = "A console application: a kernel, its commands, the layered .env files and logging."
+
+[dependencies]
+packages = [
+    "xtr-dependency-injection",
+    "xtr-console[di]",
+    "xtr-dotenv[di,console]",
+    "xtr-logging[di]",
+]
+dev = ["xtr-recipes", "pytest", "ruff", "basedpyright", "ty"]
+
+# Only what no package's recipe writes. The bundle list, .env and the ignore
+# blocks are the recipes' to write, once the packages are installed.
+[files]
+"pyproject.toml" = "files/pyproject.toml.tmpl"
+".python-version" = "files/python-version.tmpl"
+".gitignore" = "files/gitignore.tmpl"
+"README.md" = "files/README.md.tmpl"
+"src/${app}/__init__.py" = "files/app/__init__.py.tmpl"
+"src/${app}/__main__.py" = "files/app/__main__.py.tmpl"
+"src/${app}/kernel.py" = "files/app/kernel.py.tmpl"
+"src/${app}/py.typed" = "files/app/py.typed.tmpl"
+"src/${app}/command/__init__.py" = "files/app/command/__init__.py.tmpl"
+"src/${app}/command/hello_command.py" = "files/app/command/hello_command.py.tmpl"
+"tests/__init__.py" = "files/tests/__init__.py.tmpl"
+"tests/test_kernel.py" = "files/tests/test_kernel.py.tmpl"
+
+[notes]
+next = [
+    "uv run ${name} app:hello",
+    "uv run ${name} debug:bundles",
+    "uv run pytest",
+]

xtr_cli/templates/webapp/files/README.md.tmpl

@@ -0,0 +1,49 @@
+# ${name}
+
+A web application on the xtr packages: FastAPI, served from the same kernel as its console.
+
+## Run
+
+```sh
+uv run ${name}-web              # serve on WEB_HOST:WEB_PORT, 127.0.0.1:8000 by default
+uv run ${name}                  # every console command
+uv run ${name} debug:router     # the routes
+uv run ${name} debug:bundles    # the bundles and whether each is active
+```
+
+The environment is read from `.env`, then `.env.local`, then `.env.<APP_ENV>` and
+`.env.<APP_ENV>.local`; a variable set in the shell wins. Keep machine-specific values in
+`.env.local`, which is not committed.
+
+## Layout
+
+```
+src/${app}/
+├── __main__.py        the console entry point
+├── kernel.py          the kernel every entry point builds, and the environment loader
+├── bundles.py         the active bundles — written by xtr-recipes
+├── command/           the console commands
+└── web/
+    ├── __main__.py    the web entry point
+    ├── app.py         the FastAPI application, served from the kernel
+    └── routes.py      the routes
+```
+
+## Add a package
+
+```sh
+uv run xtr-recipes recipes:add "xtr-messenger[di,console]"
+```
+
+It installs the package and applies its recipe — the bundle, its configuration file, its
+environment variables — and prints any step left to do by hand. `xtr.lock` records what was
+applied; commit it.
+
+## Check
+
+```sh
+uv run pytest
+uv run ruff check && uv run ruff format --check
+uv run basedpyright && uv run ty check
+uv run xtr-recipes recipes:sync --check
+```

xtr_cli/templates/webapp/files/app/__init__.py.tmpl

@@ -0,0 +1,5 @@
+"""${name}: a web application on the xtr packages."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_cli/templates/webapp/files/app/__main__.py.tmpl

@@ -0,0 +1,23 @@
+"""The console entry point: ``uv run ${name} <command>`` or ``python -m ${app} <command>``.
+
+``*.__main__`` modules are never scanned by the kernel, so importing the application never
+runs it.
+"""
+
+from __future__ import annotations
+
+from xtr_console.bundle import console
+
+from ${app}.kernel import kernel, load_environment
+
+__all__ = ["main"]
+
+
+def main() -> None:
+    """Load the environment, then boot, run the console, shut down and exit with its code."""
+    load_environment()
+    raise SystemExit(kernel.run(console))
+
+
+if __name__ == "__main__":
+    main()

xtr_cli/templates/webapp/files/app/command/__init__.py.tmpl

@@ -0,0 +1,5 @@
+"""The console commands: every module here is scanned, and each ``@as_command`` registered."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_cli/templates/webapp/files/app/command/hello_command.py.tmpl

@@ -0,0 +1,19 @@
+"""``app:hello``: the example command — replace it with your own."""
+
+from __future__ import annotations
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+__all__ = ["hello"]
+
+
+@as_command("app:hello")
+async def hello(io: ConsoleStyle, name: str = "world") -> int:
+    """Greet someone.
+
+    Args:
+        io: Where the command writes.
+        name: Who to greet.
+    """
+    io.success(f"Hello, {escape(name)}!")
+    return ExitCode.SUCCESS

xtr_cli/templates/webapp/files/app/config/__init__.py.tmpl

@@ -0,0 +1,5 @@
+"""The application's bundle configuration: one ``@configure`` function per bundle it changes."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_cli/templates/webapp/files/app/config/http_kernel.py.tmpl

@@ -0,0 +1,19 @@
+"""The request lifecycle: which application the router commands read.
+
+Everything else is the bundle's default. ``app`` is the one thing only the application knows:
+``${name} debug:router`` and ``${name} router:match PATH`` import it from here, so neither
+needs ``--app``.
+"""
+
+from __future__ import annotations
+
+from xtr_dependency_injection import configure
+from xtr_http_kernel.bundle import HttpKernelConfig
+
+__all__ = ["http_kernel"]
+
+
+@configure
+def http_kernel() -> HttpKernelConfig:
+    """Name the application the console reports on; nothing is imported until it does."""
+    return HttpKernelConfig(app="${app}.web.app:app")

xtr_cli/templates/webapp/files/app/kernel.py.tmpl

@@ -0,0 +1,37 @@
+"""The kernel every entry point builds, and the environment it is built for.
+
+``Kernel(...)`` stores a recipe and does no work; ``build()``, ``boot()`` and ``run()`` do,
+each time afresh, so every entry point builds its own container from the same line.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Final
+
+from xtr_dependency_injection import DEFAULT_EXCLUDES, Kernel, exclude
+from xtr_dotenv import Dotenv
+
+__all__ = ["PROJECT_DIR", "kernel", "load_environment"]
+
+PROJECT_DIR: Final = Path(__file__).resolve().parents[2]
+"""The directory holding ``pyproject.toml`` and the ``.env`` files."""
+
+kernel: Final = Kernel(
+    "${app}",
+    # The bundles are read from ${app}.bundles.BUNDLES; the environment from APP_ENV.
+    allowed_envs=("dev", "test", "prod"),
+    # ${app}.web.app builds the web application as it is imported, and that application is
+    # served from this very kernel: scanning it would import it while the kernel builds.
+    exclude=(*DEFAULT_EXCLUDES, "${app}.web.app"),
+)
+
+
+@exclude
+def load_environment() -> None:
+    """Load the layered ``.env`` files into the environment, before the kernel is built.
+
+    ``@exclude`` keeps this helper out of the container: it is an entry point's concern,
+    never a service.
+    """
+    _ = Dotenv().boot_env(str(PROJECT_DIR / ".env"))

xtr_cli/templates/webapp/files/app/web/__init__.py.tmpl

@@ -0,0 +1,5 @@
+"""The web side of the application: the FastAPI application and its routes."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_cli/templates/webapp/files/app/web/__main__.py.tmpl

@@ -0,0 +1,42 @@
+"""The web entry point: ``uv run ${name}-web`` or ``python -m ${app}.web``.
+
+The environment is loaded before anything reads it, then the server runs the application on
+``WEB_HOST`` / ``WEB_PORT``, restarting it on every source change when ``WEB_RELOAD=1`` —
+``xtr serve --reload`` sets it. Ctrl-C or SIGTERM stops it: the application's lifespan ends and
+the kernel shuts down with it.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Final
+
+import uvicorn
+
+from ${app}.kernel import PROJECT_DIR, load_environment
+
+__all__ = ["main"]
+
+_HOST: Final = "127.0.0.1"
+_PORT: Final = 8000
+# An import string, not the object: reloading imports the application afresh in a new process,
+# which inherits the environment loaded here.
+_APP: Final = "${app}.web.app:app"
+
+
+def main() -> None:
+    """Load the environment, then serve the application where the variables say."""
+    load_environment()
+    uvicorn.run(
+        _APP,
+        host=os.environ.get("WEB_HOST", _HOST),
+        port=int(os.environ.get("WEB_PORT", str(_PORT))),
+        reload=os.environ.get("WEB_RELOAD") == "1",
+        # The application's own sources, not the whole project: the virtual environment
+        # under it would only slow every scan down.
+        reload_dirs=[str(PROJECT_DIR / "src")],
+    )
+
+
+if __name__ == "__main__":
+    main()

xtr_cli/templates/webapp/files/app/web/app.py.tmpl

@@ -0,0 +1,23 @@
+"""The web application: FastAPI, as the framework documents it, served from the kernel.
+
+``setup(app, kernel)`` is the whole of serving it from the kernel: every life of the
+application builds and boots its own kernel and shuts it down again, and every request runs
+through the lifecycle the http_kernel bundle contributes. Left out of the kernel's scan
+(see ``exclude`` in :mod:`${app}.kernel`): importing this module builds the application.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from xtr_http_kernel import setup
+
+from ${app}.kernel import kernel
+
+from .routes import router
+
+__all__ = ["app"]
+
+app = FastAPI(title="${name}")
+app.include_router(router)
+
+setup(app, kernel)

xtr_cli/templates/webapp/files/app/web/routes.py.tmpl

@@ -0,0 +1,15 @@
+"""The routes — replace the example with your own."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+__all__ = ["router"]
+
+router = APIRouter()
+
+
+@router.get("/")
+async def home() -> dict[str, str]:
+    """Answer that the application is up."""
+    return {"status": "ok"}

xtr_cli/templates/webapp/files/gitignore.tmpl

@@ -0,0 +1,14 @@
+# Python
+__pycache__/
+*.py[cod]
+/.venv/
+/dist/
+/build/
+
+# Tools
+/.pytest_cache/
+/.ruff_cache/
+/.coverage
+
+# What the application writes while it runs
+/var/