Skip to content

xtr_logging.exception

Every error this library raises.

All of them derive from :class:LoggingError, so one except catches anything logging 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.

:class:LoggingError and :class:InvalidLevelError belong to the contract, and are imported from xtr_logging_contracts.

CaptureConflictError

CaptureConflictError(handler: str)

Bases: LoggingError

Capture is on while a stdlib handler sends records back into the standard library.

While capture owns the standard library's output, a record handed to it arrives at the capture — which drops it, rather than send it round again — and nothing else is left to write it. The record would be lost, so the combination is refused.

Record the handler that conflicts with capture.

CircularHandlerReferenceError

CircularHandlerReferenceError(path: tuple[str, ...])

Bases: LoggingError

Handlers nest each other in a loop, so none of them can be built first.

Record the loop, starting and ending on the same handler.

EmptyStackError

EmptyStackError(owner: str, stack: str)

Bases: LoggingError

Something was popped off a stack that holds nothing.

Raised by pop_handler and pop_processor. Popping more than was pushed is always a bug in the code doing it, so it is refused rather than answered with None.

Record what was popped from, and which of its stacks was empty.

InvalidConfigurationError

InvalidConfigurationError(detail: str)

Bases: LoggingError

Configuration data — parsed from a file or an environment — does not fit the schema.

detail names what is wrong and where, as a JSON path: an unknown key, a value of the wrong type, a level that does not exist.

Record what is wrong, and where.

InvalidOptionError

InvalidOptionError(option: str, value: str, reason: str)

Bases: LoggingError, ValueError

An option was given a value it cannot work with.

Raised where the value is given — a constructor or a configuration entry — rather than on the first record that would have exposed it.

Record the option, the value it was given, and why that is refused.

MixedChannelFilterError

MixedChannelFilterError(channels: tuple[str, ...])

Bases: LoggingError, ValueError

A handler's channel list mixes included (foo) and excluded (!foo) channels.

"Only foo" and "all but bar" cannot both be true, and guessing which was meant routes records wrongly. A :class:ValueError too, so a configuration parser reports where it is.

Record the list that mixes both forms.

NotProcessableHandlerError

NotProcessableHandlerError(handler: str)

Bases: LoggingError

A processor targets a handler that runs no processors of its own.

Record the handler that cannot take a processor.

UnknownChannelError

UnknownChannelError(channel: str, known: tuple[str, ...])

Bases: LoggingError

A logger was asked for on a channel the configuration does not declare.

Refused rather than created on the fly: a channel nobody declared has no handlers routed to it by name, so its records would go wherever the catch-all handlers send them — usually not where the caller expected.

Record the channel asked for, and those that exist.

UnknownHandlerError

UnknownHandlerError(name: str, referenced_by: str, known: tuple[str, ...])

Bases: LoggingError

A handler was named that the configuration does not define.

Raised as the configuration is made — for a wrapper whose nested handler or member is missing, or a processor targeting one — and by a factory asked for a handler by a name it never built.

Record the missing name, who asked for it, and what is defined.

UnknownServiceError

UnknownServiceError(kind: str, service_id: str, known: tuple[str, ...])

Bases: LoggingError

Configuration names a service that was not supplied.

A service is an object handed to the factory by id: a handler, formatter, processor or activation strategy.

Record what kind of service, its id, and the ids supplied for that kind.