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 ¶
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 ¶
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 ¶
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:
Record the name and why it was refused.
InvalidTemplateError ¶
ProjectNotFoundError ¶
StepFailedError ¶
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 ¶
UnsupportedPythonError ¶
WebEntryPointNotFoundError ¶
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 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
¶
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
¶
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,
neworinit. -
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 ¶
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 ¶
Return the plan as the lines a dry run prints: one per file, one per command.
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.
Run commands through runner; pin the xtr requirements to version's major.
check_directory
staticmethod
¶
Refuse a directory that is a file, or holds anything but metadata.
Raises:
-
DirectoryNotEmptyError–When
directoryis in the way.
plan ¶
Work the project out in full, writing nothing.
Raises:
-
InvalidTemplateError–When the template cannot be rendered.
apply ¶
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 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
¶
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 ¶
Return every file this template writes, as (path, text), with values in.
Raises:
-
InvalidTemplateError–When a destination or a file holds a placeholder
valuesdoes not have, or a destination leaves the project directory.
steps ¶
Return the next steps with values in.
Raises:
-
InvalidTemplateError–When a step holds a placeholder
valuesdoes not have.
TemplateCatalog ¶
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
¶
Return the catalog of the templates this tool ships.
load ¶
Return the shipped template called template.
Raises:
-
UnknownTemplateError–When no template ships under that name.
-
InvalidTemplateError–When the template cannot be read.
WebEntryPoint
dataclass
¶
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.
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:
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
¶
Return the nearest directory at or above start holding a pyproject.toml.
Raises:
-
ProjectNotFoundError–When there is none.
find ¶
Return every web entry point of the project, the scripts first and alone if any.
resolve
staticmethod
¶
Return the entry point --entrypoint names: a script, or module:attribute.
Raises:
-
WebEntryPointNotFoundError–When
givenis neither one of the project's scripts nor amodule:attribute.