Skip to content

xtr_recipes.exception

Every error this library raises.

All of them derive from :class:RecipesError, so one except catches anything applying a recipe can go wrong with, and a narrower one handles a single cause. Each carries the data a caller needs as typed attributes rather than forcing a message to be parsed.

BundlesNotEditableError

BundlesNotEditableError(path: Path, reason: str, entries: tuple[str, ...])

Bases: RecipesError

A bundles.py is shaped in a way its reader cannot edit in place.

The bundle list is read and rewritten mechanically; a file that builds its mapping some other way — a key that is not an imported name, non-literal flags, or no single BUNDLES assignment — cannot be changed without risking what it already holds. Rather than guess, the error reports the entries to add by hand so the application owner stays in control.

Attributes:

  • path (Path) –

    The bundles.py that could not be rewritten.

  • reason (str) –

    Why it could not be rewritten.

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

    The bundle targets ("module:Class") to add by hand.

Record the file, why it is not editable, and what to add by hand.

InvalidManifestError

InvalidManifestError(package: str, key: str, reason: str)

Bases: RecipesError, ValueError

A recipe manifest holds something its reader cannot make sense of.

Raised where the manifest is parsed rather than letting an unknown table, an unknown key or a mistyped value through: a recipe that would configure an application wrongly should fail at load time, not halfway through a sync. The same error reports a template that names a placeholder the renderer was never given.

Also a :class:ValueError, so code that already guards parsing with except ValueError keeps working without learning a new exception.

Attributes:

  • package (str) –

    The distribution whose recipe could not be read.

  • key (str) –

    The table, key, value or template path at fault.

  • reason (str) –

    What about it could not be read.

Record which recipe, which key, and why it could not be read.

MarkedBlockError

MarkedBlockError(path_or_name: Path | str, reason: str)

Bases: RecipesError, ValueError

A recipe's block is opened in a file and never closed.

The markers are the whole reason a recipe can be undone: everything between them belongs to the recipe, everything outside belongs to the application owner. An opening marker with no closing one leaves that line undrawn, and rewriting or removing the block would then swallow whatever follows it — so the file is reported rather than guessed at.

Also a :class:ValueError, so code that already guards parsing with except ValueError keeps working without learning a new exception.

Attributes:

  • path_or_name (Path | str) –

    The file whose block is unclosed, or the package the block belongs to when the text was handed over without a path.

  • reason (str) –

    What about the block could not be read.

Record which file or package, and why its block could not be read.

ProjectNotFoundError

ProjectNotFoundError(directory: Path, reason: str)

Bases: RecipesError

The project, or the application package inside it, is not where expected.

Raised when no pyproject.toml lies at or above the directory searched, and when not exactly one package under src/ or the project root holds a kernel.py — the file that marks the application package.

Attributes:

  • directory (Path) –

    The directory that was searched.

  • reason (str) –

    What was looked for and not found.

Record where the search ran and what failed.

RecipeNotInstalledError

RecipeNotInstalledError(package: str)

Bases: RecipesError

One package was named to configure, and it is not one that can be.

A full sync works from what is installed, so it has nothing to report about a package that is not. Naming one explicitly is different: the answer must be an error rather than a silent plan of nothing, because the cause is usually a package the application does not depend on, or one installed without the recipe that configures it.

Attributes:

  • package (str) –

    The distribution that was named.

Record the distribution that has no recipe to apply.

RecipesError

Bases: Exception

Base class for every error raised by this library.

Catch this to handle anything applying a recipe can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them, so a handler reads the fields rather than parsing the text.

UnreadableFileError

UnreadableFileError(path: Path, reason: str)

Bases: RecipesError

A file the tool must read holds bytes it cannot decode.

Raised where xtr.lock or a pyproject.toml is read: a truncated JSON lock, a manifest that is not valid TOML, or either saved in an encoding other than UTF-8 would otherwise surface as a bare decode error with no hint which file was at fault. The file is named so the fix is obvious.

Attributes:

  • path (Path) –

    The file that could not be read.

  • reason (str) –

    What about its bytes could not be decoded.

Record which file could not be read, and why.

UnsafePathError

UnsafePathError(path: Path | str, reason: str)

Bases: RecipesError

A recipe path escapes the project or points at a symbolic link.

A recipe records and resolves paths relative to the project directory, so one that resolves outside it — through .. or an absolute spelling, in a manifest or in a tampered xtr.lock — would let a recipe write or delete anywhere on disk. A write target that is a symbolic link would follow the link out of the project just the same. Both are refused before anything is touched.

Attributes:

  • path (str) –

    The path that could not be made safe, as it reads in the plan or the lock.

  • reason (str) –

    Why it was refused.

Record the offending path and why it was refused.