Skip to content

xtr_cli.exception

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.

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.