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:
filterwarnings()
to create the warnings filter. Becausefilterwarnings()
wraps Python’swarnings.filterwarnings()
, it may be used as a drop-in replacement for creation of any warnings filter.
warn()
orwarn_explicit()
. Again, these are drop-in replacements for Python’swarnings.warn()
andwarnings.warn_explicit()
that additionally check the onceperfamily filters.
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