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: exceptions.Warning

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

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

Bases: exceptions.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
args
message
exception plastid.util.services.exceptions.FileFormatWarning[source]

Bases: exceptions.Warning

Warning for slightly malformed but usable files

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

Bases: exceptions.Exception

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

args
message
plastid.util.services.exceptions.filterwarnings(action, message='', category=<type 'exceptions.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:
action : str

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

message : str, 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)

category : Warning or subclass, optional

Type of warning. (Default: Warning)

module : str, optional

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

lineno : int, optional

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

append : int, 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:
message : str

Warning message

category : Warning

Class (not instance) of warning

filename : str

Name of file calling warning

lineno : int

Line in file calling warning

file : something implementing a write method

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

line : str

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:
message : str

Message

category: :class:`Warning`, or subclass, optional

Type of warning

stacklevel : int

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:
message : str

Message

category: :class:`Warning`, or subclass, optional

Type of warning

filename : str

Name of module from which warning is issued

lineno : int, optional

Line in module at which warning is called

module : str, optional

Module name

registry : dict, optional

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

module_globals : dict, 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:
message : str

Message

pattern : str or None, optional

If not None, override message when generating warnings filter

category: :class:`Warning`, or subclass, optional

Type of warning

filename : str

Name of module from which warning is issued

lineno : int, optional

Line in module at which warning is called

module : str, optional

Module name

registry : dict, optional

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

module_globals : dict, 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:
message : str

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.

pattern : str or None, optional

If not None, override message when generating warnings filter

category: :class:`Warning`, or subclass, optional

Type of warning

stacklevel : int

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