User Defined Exceptions¶

pcapkit.utilities.exceptions refined built-in exceptions. Make it possible to show only user error stack information [*], when exception raised on user’s operation.

Loud and Quiet Errors¶

Raising a BaseError is, by default, a loud act: the error is logged once at logging.CRITICAL on the logger logger, and outside development mode sys.tracebacklimit is set to 0, which suppresses the traceback frames entirely so the user sees the exception line rather than a walk through pcapkit’s internals.

quiet=True marks an error that pcapkit raises as internal control flow and expects to catch itself – the MissingKeyError behind MultiDict.get is the archetype. Such an error emits nothing on any channel and touches no process-global state. It is still an ordinary exception carrying its message, so except clauses and repr() are unaffected.

Attention

Up to and including v1.4.1, quiet=True meant “log at ERROR instead of CRITICAL” rather than “do not log”, and sys.tracebacklimit was set on both paths. A single MultiDict.get() miss therefore produced an ERROR record – one per frame when parsing a capture containing unfragmented IPv6 with reassembly enabled – and truncated the tracebacks of unrelated exceptions for the remainder of the process. A consumer who was watching for those ERROR records will no longer see them; they never corresponded to a fault. Anything that genuinely wants to observe internal lookup misses should catch the exception rather than read the log.

exception pcapkit.utilities.exceptions.BaseError(*args, quiet=False, **kwargs)[source]¶

Bases: Exception

Base error class of all kinds.

A loud error – the default – is reported once, at logging.CRITICAL level, on the logger logger. Outside development mode it also sets sys.tracebacklimit to 0, which suppresses the traceback frames entirely, so a user sees the exception line rather than a walk through pcapkit’s internals.

A quiet error (quiet=True) is one pcapkit raises as internal control flow and expects to catch itself, such as the MissingKeyError behind MultiDict.get. It is therefore silent and free of side effects: nothing is logged, and sys.tracebacklimit is left alone. It is still a perfectly ordinary exception, carrying its message for whoever catches it.

Important

sys.tracebacklimit is process-global, so it is only set for a loud error – a quiet one used as control flow must not truncate the tracebacks of unrelated exceptions for the rest of the process.
The stacklevel of the log record is the relative level stacklevel() computes, so the record is attributed to the caller whose operation failed rather than to this module. It used to be negated, which logging.Logger.findCaller() reads as “do not walk out at all” and which therefore blamed logging itself for every error pcapkit raised.

`TypeError` Category¶

exception pcapkit.utilities.exceptions.DigitError(*args, quiet=False, **kwargs)[source]¶

User Defined Exceptions¶

Loud and Quiet Errors¶

TypeError Category¶

AttributeError Category¶

IOError Category¶

FileExistsError Category¶

FileNotFoundError Category¶

IndexError Category¶

ValueError Category¶

NotImplementedError Category¶

struct.error Category¶

EOFError Category¶

KeyError Category¶

ModuleNotFoundError Category¶

io.UnsupportedOperation Category¶

`TypeError` Category¶

`AttributeError` Category¶

`IOError` Category¶

`FileExistsError` Category¶

`FileNotFoundError` Category¶

`IndexError` Category¶

`ValueError` Category¶

`NotImplementedError` Category¶

`struct.error` Category¶

`EOFError` Category¶

`KeyError` Category¶

`ModuleNotFoundError` Category¶

`io.UnsupportedOperation` Category¶