Skip to content

xtr_cli

Creates a new application on the xtr packages, ready to run, in one command.

xtr new <directory> asks nothing: it makes a console application, or a web application with --webapp. It 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.

AmbiguousWebEntryPointError

AmbiguousWebEntryPointError(candidates: tuple[str, ...])

Bases: CliError

Several web entry points were found and questions are off.

Attributes:

  • candidates (tuple[str, ...]) –

    The entry points found, as --entrypoint takes them.

Record what could have been served.

CliError

Bases: 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.

DirectoryNotEmptyError

DirectoryNotEmptyError(directory: Path, found: tuple[str, ...])

Bases: 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 (Path) –

    The directory asked for.

  • found (tuple[str, ...]) –

    The entries that are in the way, sorted.

Record the directory and what is already in it.

InvalidProjectNameError

InvalidProjectNameError(name: str, reason: str)

Bases: 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 (str) –

    The name as it was given.

  • reason (str) –

    Why it cannot be used.

Record the name and why it was refused.

InvalidTemplateError

InvalidTemplateError(template: str, reason: str)

Bases: CliError

A template.toml that does not parse, or holds a key or value it may not.

Attributes:

  • template (str) –

    The template's name — its directory's name.

  • reason (str) –

    What is wrong, naming the key at fault.

Record the template and what is wrong with it.

ProjectNotFoundError

ProjectNotFoundError(directory: Path)

Bases: CliError

No pyproject.toml lies at or above the directory searched.

Attributes:

  • directory (Path) –

    Where the search started.

Record where the search started.

StepFailedError

StepFailedError(argv: tuple[str, ...], cwd: Path, code: int)

Bases: 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 (tuple[str, ...]) –

    The command that failed, program and all.

  • cwd (Path) –

    Where it ran.

  • code (int) –

    The exit code it ended with.

Record the command, where it ran, and how it ended.

UnknownTemplateError

UnknownTemplateError(template: str, available: tuple[str, ...])

Bases: CliError

No template ships under the name asked for.

Attributes:

  • template (str) –

    The name asked for.

  • available (tuple[str, ...]) –

    The names of the templates that ship with this tool.

Record the name and what could have been chosen instead.

UnsupportedPythonError

UnsupportedPythonError(python: str)

Bases: CliError

--python is not a 3.<minor> version the packages support.

Every xtr package requires Python 3.14 or later, so a project pinned below that could install none of them.

Attributes:

  • python (str) –

    The version as it was given.

Record the version that was refused.

WebEntryPointNotFoundError

WebEntryPointNotFoundError(project_dir: Path, reason: str)

Bases: CliError

Nothing in the project can be served, or --entrypoint names nothing it has.

Attributes:

  • project_dir (Path) –

    The project searched.

  • reason (str) –

    What was looked for and not found.

Record the project and what it lacks.

ProcessRunnerInterface

Bases: 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.

run

run(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.

ProjectName dataclass

ProjectName(distribution: str, app: str)

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 (str) –

    The lowercase, dash-separated name in [project].name.

  • app (str) –

    The import name: the distribution with its dashes as underscores.

parse classmethod

parse(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.

ProjectSettings dataclass

ProjectSettings(command: str, directory: Path, name: ProjectName, template: Template, python: str, git: bool = True, local_packages: Path | None = None)

Everything a project is made from, settled from the command line.

Attributes:

  • command (str) –

    The command that makes it, new or init.

  • directory (Path) –

    Where the project is made, absolute.

  • name (ProjectName) –

    The project's name.

  • template (Template) –

    The template it is made from.

  • python (str) –

    The 3.<minor> version it is pinned to.

  • git (bool) –

    Whether a git repository is initialised in it.

  • local_packages (Path | None) –

    A directory of xtr package sources to install from, editable, instead of the package index.

values

values() -> 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 py314 can be given py3${minor}; requires_python is the oldest release of that minor the packages install on.

ScaffoldPlan dataclass

ScaffoldPlan(directory: Path, files: tuple[tuple[str, str], ...], commands: tuple[tuple[str, ...], ...], next_steps: tuple[str, ...])

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 (Path) –

    Where the project is made.

  • files (tuple[tuple[str, str], ...]) –

    Each path in the project, /-separated, with the text written there.

  • commands (tuple[tuple[str, ...], ...]) –

    The commands run in the project once its files are written, in order.

  • next_steps (tuple[str, ...]) –

    What to try once it is made.

render

render() -> tuple[str, ...]

Return the plan as the lines a dry run prints: one per file, one per command.

Scaffolder

Scaffolder(runner: ProcessRunnerInterface, version: str)

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.

Run commands through runner; pin the xtr requirements to version's major.

check_directory staticmethod

check_directory(directory: Path) -> None

Refuse a directory that is a file, or holds anything but metadata.

Raises:

plan

plan(settings: ProjectSettings) -> ScaffoldPlan

Work the project out in full, writing nothing.

Raises:

apply

apply(plan: ScaffoldPlan, report: Callable[[str], None]) -> None

Make the project plan describes, reporting each step as it starts.

A file written under bin/ is made executable: git tracks the mode, so the scaffolded repository keeps the wrapper runnable.

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.

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.

run

run(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.

Template dataclass

Template(name: str, summary: str, dependencies: tuple[str, ...], dev_dependencies: tuple[str, ...], files: tuple[tuple[str, str], ...], next_steps: tuple[str, ...])

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"]   # 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.14), ${minor} (14) and ${requires_python} (3.14.4) with :meth:string.Template.substitute; a literal $ is written $$.

Attributes:

  • name (str) –

    The template's name — the name of its directory.

  • summary (str) –

    One line on what it makes.

  • dependencies (tuple[str, ...]) –

    The requirements every project made from it starts with.

  • dev_dependencies (tuple[str, ...]) –

    The development requirements it starts with.

  • files (tuple[tuple[str, str], ...]) –

    Each destination pattern mapped to the template text written there.

  • next_steps (tuple[str, ...]) –

    Commands to try once the project is made.

load classmethod

load(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.

render

render(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.

steps

steps(values: Mapping[str, str]) -> tuple[str, ...]

Return the next steps with values in.

Raises:

TemplateCatalog

TemplateCatalog(root: Traversable)

Finds a template by the name it ships under.

The shipped templates live inside this package, so they are the ones written for the packages of the same release.

Offer the templates in the subdirectories of root.

default classmethod

default() -> TemplateCatalog

Return the catalog of the templates this tool ships.

names

names() -> tuple[str, ...]

Return the names of the shipped templates, sorted.

load

load(template: str) -> Template

Return the shipped template called template.

Raises:

WebEntryPoint dataclass

WebEntryPoint(kind: Literal['script', 'asgi'], target: str)

One way to serve an application: a console script, or an ASGI object.

A script is the application's own web entry point, run as it is — whatever it does before serving, loading its .env files among it, still happens. It is told the host, the port and whether to reload through WEB_HOST, WEB_PORT and WEB_RELOAD, the variables the webapp template's entry point reads; a script that reads none of them serves where it always does.

An ASGI object — a module-level FastAPI(), Starlette() or Litestar() — is handed to uvicorn directly, which then has to be installed in the project. Nothing runs before it is imported, so the application's own environment loading does not either. It is served with each request started in a context of its own, where the installed server knows how; a script decides that for itself.

Attributes:

  • kind (Literal['script', 'asgi']) –

    "script" or "asgi".

  • target (str) –

    The script's name, or the ASGI object as module:attribute.

label property

label: str

The entry point as --entrypoint takes it.

command

command(host: str | None, port: int | None, *, reload: bool) -> tuple[tuple[str, ...], dict[str, str]]

Return the command serving this entry point, and the variables set for it.

Parameters:

  • host (str | None) –

    Where to listen, or None for the entry point's default.

  • port (int | None) –

    The port to listen on, or None for the entry point's default.

  • reload (bool) –

    Whether to restart the server when a source file changes.

WebEntryPointFinder

Finds what serves a project, reading its files and running nothing.

A web console script comes first: it is the application's own way of serving, environment loading included. A script counts when its module imports a server — uvicorn, hypercorn or granian — or its name ends in -web or -server. Only a project with no such script is searched for a module-level ASGI object instead. Every module is read with :mod:ast, never imported.

project_dir staticmethod

project_dir(start: Path | None = None) -> Path

Return the nearest directory at or above start holding a pyproject.toml.

Raises:

find

find(project_dir: Path) -> tuple[WebEntryPoint, ...]

Return every web entry point of the project, the scripts first and alone if any.

resolve staticmethod

resolve(project_dir: Path, given: str) -> WebEntryPoint

Return the entry point --entrypoint names: a script, or module:attribute.

Raises: