Skip to content

wend.errors

Exception hierarchy.

Every error raised deliberately by wend derives from WendError. Errors that signal an unacceptable value also derive from ValueError, so callers that already handle pathlib's ValueError keep working. Misused arguments raise TypeError or ValueError, as Python's own functions do; the private helpers at the end hold the argument rules that several entry points share.

WendError

Bases: Exception

Base class for all wend errors.

MissingBindingError 

MissingBindingError(missing: set[str])

Bases: WendError, ValueError

Resolution was attempted without values for some parameters.

missing instance-attribute 

missing = frozenset(missing)

InvalidBindingError

Bases: WendError, ValueError

A bound value is not acceptable at the position where it is used.

Raised when a value would silently change the segment structure of the expression (a separator inside a segment, an empty segment, .), escape upwards (..), or violate a declared type, kind or set of choices.

PathOperationError

Bases: WendError, ValueError

A path operation is invalid for this expression (mirrors pathlib's ValueError).

NotStaticError

Bases: WendError

The requested information depends on parameter values that are not bound.

NotInvertibleError

Bases: WendError

The expression contains a construct that match cannot invert.

AmbiguousMatchError 

AmbiguousMatchError(path: str, candidates: Sequence[Mapping[str, Any]])

Bases: WendError, ValueError

A concrete path matches the expression with more than one set of bindings.

path instance-attribute 

path = path

candidates instance-attribute 

candidates = list(candidates)

ParamConflictError

Bases: WendError, ValueError

Two different parameter declarations share a name within one expression.

ConditionError 

ConditionError(path: str, condition: Any, message: str)

Bases: WendError

A declared condition does not hold for a rendered path (§10).

path is the rendered path and condition the condition that failed. Subclasses also derive from the builtin exception that describes the same failure, so except FileNotFoundError keeps working.

path instance-attribute 

path = path

condition instance-attribute 

condition = condition

IndeterminateError 

IndeterminateError(path: str, condition: Any, message: str)

Bases: ConditionError

Whether a condition holds could not be determined (§10).

The filesystem could not say: the path could not be examined (no permission to look, a symlink loop, a failed request), or the backend cannot report the capability without exercising it (whether an object store would accept a write). It is not a known failure, which is a CapabilityError, MissingPathError, PathExistsError or WrongKindError.

MissingPathError 

MissingPathError(path: str, condition: Any, message: str)

Bases: ConditionError, FileNotFoundError

A path required to exist does not.

PathExistsError 

PathExistsError(path: str, condition: Any, message: str)

Bases: ConditionError, FileExistsError

A path required to be absent exists (possibly as a broken symlink).

WrongKindError 

WrongKindError(path: str, condition: Any, message: str)

Bases: ConditionError

A path exists but is not the declared kind (a file, or a directory).

CapabilityError 

CapabilityError(path: str, condition: Any, message: str)

Bases: ConditionError, PermissionError

A path cannot be used as declared: read, written, created or listed.

ContainmentError 

ContainmentError(path: str, condition: Any, message: str)

Bases: ConditionError, InvalidBindingError

A path is not under the base it was declared to be under.

Raised by render when the bindings take the path lexically outside the base, and by check when it resolves outside it through symlinks.

NoAlternativeError 

NoAlternativeError(tried: list[tuple[str, ConditionError]])

Bases: ConditionError, FileNotFoundError

No alternative of a union exists (or meets its preconditions).

tried lists each rendered alternative with the condition error that ruled it out, in order.

tried instance-attribute 

tried = tried

path instance-attribute 

path = tried[0][0] if tried else ''

condition instance-attribute 

condition = None

show 

show(value: Any) -> str

repr(value) for an error message, which never raises.

Some values have no repr: an int beyond the digit limit for conversion to text, or an object whose __repr__ fails. A message about such a value must not replace the error it describes.