plastid.util.services.exceptions module

This module contains custom exception and warning classes, implements a custom warning filter action, called “onceperfamily”, and monkey-patches warning output to improve legibility.

Contents:

The onceperfamily action

onceperfamily groups warning messages by families regular expressions, and only prints the first warning instance that matches a given family’s regular expression. In contrast, Python’s native once action prints any string literal once, even if it matches the same regex as another warning already given.

To use this action, use the following two functions:

For convenience, there are also functions that both issue a warning, and create a onceperfamily filter for it if one doesn’t already exist:

Exception types

MalformedFileError

Raised when a file cannot be parsed as expected, and execution must halt

Warning types

ArgumentWarning

Warning for command-line arguments that:

  • are nonsenical, but recoverable

  • together might cause very slow execution (e.g. run would be optimized by other combinations)

FileFormatWarning

Warning for slightly malformed but usable files

DataWarning

Warning raised when:

  • data has unexpected attributes

  • data has nonsensical, but recoverable values for attributes

  • when values are out of the domain of a given operation, but skipping the operation or estimating the value is permissible

See also

warnings

Warnings module

exception plastid.util.services.exceptions.ArgumentWarning[source]

Bases: Warning

Warning for nonsensical but recoverable combinations of command-line arguments, or arguments that risk slow program execution

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args
exception plastid.util.services.exceptions.DataWarning[source]

Bases: Warning

Warning for unexpected attributes of data. Raised when:

  • data has unexpected attributes

  • data has nonsensical, but recoverable values

  • values are out of the domain of a given operation, but execution can continue if the value is estimated or the operation skipped

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args
exception plastid.util.services.exceptions.FileFormatWarning[source]

Bases: Warning

Warning for slightly malformed but usable files

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args
exception plastid.util.services.exceptions.MalformedFileError(filename, message, line_num=None)[source]

Bases: Exception

Exception class for when files cannot be parsed as they should be

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args
plastid.util.services.exceptions.filterwarnings(action, message='', category=<class 'Warning'>, module='', lineno=0, append=0)[source]

Insert an entry into the warnings filter. Behaviors are as in warnings.filterwarnings(), except the additional action ‘onceperfamily’ can be used to allow one warning per family of messages, specified by a regex.

This allows individual warnings to give more detailed information, without each being regarded as its own warning by Python’s warning system (the defualt behavior of ‘once’).

Parameters
actionstr

How the warning should be filtered. Accceptable values are “error”, “ignore”, “always”, “default”, ‘module”, “once”, and “onceperfamily”

messagestr, optional

str that can be compiled to a regex, used to detect warnings. If “onceperfamily” is chosen, only the first warning to give a string that matches the regex will be shown. For other actions, behaviors are as described in warnings. (Default: “”, match any message)

categoryWarning or subclass, optional

Type of warning. (Default: Warning)

modulestr, optional

str that can be compiled to a regex, limiting the warning behavior to modules that match that regex. (Default: “”, match all modules)

linenoint, optional

integer line used to specify warning in source code. If 0 (default), match all warnings regardless of line number.

appendint, optional

If 1, add warning to end of filter list. If 0 (default), insert warning at beginning of filters list.

See also

warnings.filterwarnings

Python’s warnings filter

plastid.util.services.exceptions.formatwarning(message, category, filename, lineno, file=None, line=None)[source]

Wrapper to colorize warnings for readability. Overrides warnings.formatwarning()

Parameters
messagestr

Warning message

categoryWarning

Class (not instance) of warning

filenamestr

Name of file calling warning

linenoint

Line in file calling warning

filesomething implementing a write method

File to which output is written. Default: sys.stderr

linestr

Text of line in file calling warning. If None, line is taken to be line number lineno of filename

Returns
str

Pretty-printed warning message

plastid.util.services.exceptions.warn(message, category=None, stacklevel=1)[source]

Issue a non-essential warning to users, allowing plastid-specific warnings filters

Parameters
messagestr

Message

category:class:Warning, or subclass, optional

Type of warning

stacklevelint

Ignored

See also

plastid.util.services.exceptions.filterwarnings

plastid-specific warnings filters

warnings.warn

Python’s warning system, which this wraps

plastid.util.services.exceptions.warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None)[source]

Low-level interface to issue warnings, allowing plastid-specific warnings filters

Parameters
messagestr

Message

category:class:Warning, or subclass, optional

Type of warning

filenamestr

Name of module from which warning is issued

linenoint, optional

Line in module at which warning is called

modulestr, optional

Module name

registrydict, optional

Registry of ignore filters (see source code for warnings.warn_explicit()

module_globalsdict, optional

Dictionary of module-level variables

See also

plastid.util.services.exceptions.filterwarnings

plastid-specific warnings filters

warnings.warn_explicit

Python’s warning system, which this wraps

plastid.util.services.exceptions.warn_explicit_onceperfamily(message, category, filename, lineno, pattern=None, module=None, registry=None, module_globals=None)[source]

Low-level interface to issue warnings, allowing plastid-specific warnings filters

Parameters
messagestr

Message

patternstr or None, optional

If not None, override message when generating warnings filter

category:class:Warning, or subclass, optional

Type of warning

filenamestr

Name of module from which warning is issued

linenoint, optional

Line in module at which warning is called

modulestr, optional

Module name

registrydict, optional

Registry of ignore filters (see source code for warnings.warn_explicit()

module_globalsdict, optional

Dictionary of module-level variables

See also

plastid.util.services.exceptions.filterwarnings

plastid-specific warnings filters

warnings.warn_explicit

Python’s warning system, which this wraps

plastid.util.services.exceptions.warn_onceperfamily(message, pattern=None, category=None, stacklevel=1)[source]

Issue a warning and create a warning filter for that warning if it does not already exist

Parameters
messagestr

Message of warning. Can be a string that compiles to a regex. Printed as warning text and used to create warning filter if pattern is None.

patternstr or None, optional

If not None, override message when generating warnings filter

category:class:Warning, or subclass, optional

Type of warning

stacklevelint

Ignored

See also

plastid.util.services.exceptions.filterwarnings

plastid-specific warnings filters

warnings.warn

Python’s warning system, which this wraps

plastid.util.services.exceptions.pl_filters = []

Plastid’s own warnings filters, which allow additional actions compared to Python’s

plastid.util.services.exceptions.pl_once_registry = {}

Registry of onceperfamily warnings that have been seen in the current execution context