tidyexc.Error
- exception tidyexc.Error(brief='', **kwargs)[source]
A base class for making exceptions that:
Provide direct access to any parameters that are relevant to the error.
Use bullet-points to clearly and comprehensively describe the error.
Example:
>>> from tidyexc import Error >>> class CheeseShopError(Error): ... pass ... >>> err = CheeseShopError( ... product_name="Red Leicester", ... num_requested=1, ... num_available=0, ... ) >>> err.brief = "insufficient inventory to process request" >>> err.info += "{num_requested} {product_name} requested" >>> err.blame += "{num_available} available" >>> raise err Traceback (most recent call last): ... tidyexc.exc.CheeseShopError: insufficient inventory to process request • 1 Red Leicester requested ✖ 0 available
Public Data Attributes:
info_bullet
The prefix to use for each
info
message in the formatted error.blame_bullet
The prefix to use for each
blame
message in the formatted error.hint_bullet
The prefix to use for each
hints
message in the formatted error.brief
A message template briefly describing the error.
brief_str
The
brief
message, with all parameter substitution performed.info
Message templates describing the context in which the error occurred.
info_strs
The
info
messages, with all parameter substitution performed.blame
Message templates describing the specific cause of the error.
blame_strs
The
blame
messages, with all parameter substitution performed.hints
Message templates suggesting how to fix the error.
hint_strs
The
hints
messages, with all parameter substitution performed.data
Parameters relevant to the error.
nested_data
A view providing access to all values defined for each parameter.
Inherited from
BaseException
args
Public Methods:
add_info
(*messages, **kwargs)Add the given
info
to any exceptions derived from this class that are instantiated inside a with-block.push_info
(*messages, **kwargs)Add the given
info
to any exceptions derived from this class that are subsequently instantiated.pop_info
()Stop adding the
info
that was most-recently "pushed" to exceptions derived from this class.clear_info
()Stop adding any
info
that was "pushed" to exceptions derived from this class.put_info
(*messages, **kwargs)__init__
([brief])Create a new exception.
__str__
()Return the formatted error message.
Inherited from
Exception
__init__
(*args, **kwargs)Inherited from
BaseException
__repr__
()Return repr(self).
__str__
()Return str(self).
__getattribute__
(name, /)Return getattr(self, name).
__setattr__
(name, value, /)Implement setattr(self, name, value).
__delattr__
(name, /)Implement delattr(self, name).
__init__
(*args, **kwargs)__reduce__
helper for pickle
__setstate__
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- __init__(brief='', **kwargs)[source]
Create a new exception.
You can specify a
brief
message template and any number of parameters (via keyword arguments) when constructing anError
instance. This may be enough for simple exceptions, but most of the time you would subsequently addinfo
andblame
message templates (which cannot be directly specified in the constructor).Any class-wide parameters and/or message templates specified using
add_info()
orpush_info()
are read and applied during the constructor. This means that these class-wide functions have no effect on exceptions that have already been instantiated.Example:
>>> raise Error("a: {a}", a=1) Traceback (most recent call last): ... tidyexc.exc.Error: a: 1
- __str__()[source]
Return the formatted error message.
All parameter substitutions are performed at this point, so any changes made to either the message templates or the data themselves will be reflected in the resulting error message.
- classmethod add_info(*messages, **kwargs)[source]
Add the given
info
to any exceptions derived from this class that are instantiated inside a with-block.A simple example:
>>> from tidyexc import Error >>> with Error.add_info('a: {a}', a=1): ... raise Error() ... Traceback (most recent call last): ... tidyexc.exc.Error: • a: 1
The purpose of this function is to make it easier to add contextual information to exceptions. This is easiest to illustrate with an example. The following function parses a list of (x, y) coordinates from a file. Each coordinate appears on its own line and must consist of exactly two whitespace-separated numbers. There are several different errors this function should detect, but all of the error messages should include the file path, and most should also include the offending line number:
from tidyexc import Error class ParseError(Error): pass def parse_xy_coords(path): with ParseError.add_info("path: {path}", path=path): lines = _lines_from_file(path) coords = [] for i, line in enumerate(lines, 1): with ParseError.add_info("line #{i}: {line}", i=i, line=line): coord = _coord_from_line(line) coords.append(coord) return coords def _lines_from_file(path): try: with open(path) as f: return f.readlines() except FileNotFoundError: err = ParseError("can't read file") err.hints += "Double-check that the given path actually exists." raise err from None def _coord_from_line(line): fields = line.split() if len(fields) != 2: raise ParseError( lambda e: f"expected 2 fields, found {len(e.fields)}", fields=fields, ) coord = [] for field in fields: try: coord.append(float(field)) except ValueError: raise ParseError("expected a number, not {field!r}", field=field) from None return tuple(coord)
Using
add_info()
simplifies the above code in two major ways:Each piece of contextual information is specified just once and used by multiple exceptions. There’s no way to accidentally raise an exception without this information.
The helper functions that actually raise the exceptions don’t need to have access to any of the contextual information. Without
add_info()
, it would either be necessary to pass extra arguments around or to catch and re-raise the exceptions.
It is possible to nest any number of these context managers. The
info
bullet points will appear in the order the context managers were invoked. It is considered good practice for the message templates to only make use of the kwargs parameters provided to the same context manager, but templates can access all previously defined parameters. They cannot access any subsequently defined parameters. If a parameter is defined multiple times, the most recent previous value will be used. For example:>>> # This template cannot use the `c` parameter, because it has >>> # not been defined yet. Note that the `b` parameter keeps its >>> # value, even though it is subsequently redefined. >>> with Error.add_info('a={a} b={b}', a=1, b=2): ... ... # The `a` parameter can be used in this template because ... # it was defined previously. The `b` parameter shadows the ... # previous value. ... raise Error('a={a} b={b} c={c}', b=3, c=4) ... Traceback (most recent call last): ... tidyexc.exc.Error: a=1 b=3 c=4 • a=1 b=2
Because templates cannot be affected by subsequent parameters, it is safe to use
add_info()
in recursive functions, where the same exact parameters might be specified multiple times with different values. Thedata
attribute provides access to the current value of each parameter. Thenested_data
attribute, in contrast, provides access to all values for each parameter.
- property blame
Message templates describing the specific cause of the error.
For example, imagine an error that was triggered because an unmatched brace was encountered when parsing a file. A good
blame
message for this exception would clearly state that an unmatched brace was the cause of the problem.See
info
for a description of message templates in general.Example:
>>> from tidyexc import Error >>> err = Error(a=1) >>> err.blame += "a: {a}" >>> raise err Traceback (most recent call last): ... tidyexc.exc.Error: ✖ a: 1
- property brief
A message template briefly describing the error.
The tidyverse style guide recommends using the verb “must” when the cause of the problem is pretty clear, and the verb “can’t” when it’s not. It’s common for this template to be a fixed string (i.e. no parameter substitution), and for the
info
andblame
templates to reference the parameters of the exception.See
info
for a description of message templates in general. Unlikeinfo
,blame
, andhints
, there can only be a singlebrief
message template. For this reason, use the assignment operator the set this template (as opposed to the in-place addition operator).Example:
>>> err = Error(a=1) >>> err.brief = "a: {a}" >>> raise err Traceback (most recent call last): ... tidyexc.exc.Error: a: 1
- classmethod clear_info()[source]
Stop adding any
info
that was “pushed” to exceptions derived from this class.
- property data
Parameters relevant to the error.
This attribute is a dictionary-like object that allows parameters to be accessed either as attributes or as dictionary elements:
>>> e = Error(a=1) >>> e.data.a 1 >>> e.data['a'] 1
If a parameter has been defined multiple times (e.g. with
add_info()
), the most recent value is the one that will be used:>>> with Error.add_info(a=1): ... e = Error(a=2) ... e.data.a 2
- property hints
Message templates suggesting how to fix the error.
For example, imagine an error that was triggered because some user input didn’t match any of the expected keywords. A good hint for this exception might suggest the expected keyword that was most similar to what the user inputted.
See
info
for a description of message templates in general.Example:
>>> from tidyexc import Error >>> err = Error(a=1) >>> err.hints += "a: {a}" >>> raise err Traceback (most recent call last): ... tidyexc.exc.Error: • a: 1
- property info
Message templates describing the context in which the error occurred.
For example, imagine an error that was triggered because an unmatched brace was encountered when parsing a file. A good
info
message for this exception might specify the file name and line number where the error occurred.A message template can either be a string or a callable:
str: When the error message is generated, the
str.format
method will be called on the string as follows:s.format(**self.data)
. This means that any parameters associated with the exception can be substituted into the message.callable: When the error message is generated, the callable will be invoked with
data
as the only argument. It should return a string or a list of strings, which will be taken as the message(s). A common use-case for callable template is to specify f-strings via lambda functions. This is a succinct way to format parameters using arbitrary expressions (see example below).
The
info
,blame
, andhints
attributes are all list-like objects containing message templates. Special syntax is added such that you can use the+=
operator to add message templates to any of these lists. You can also use any of the usual list methods to modify the list in-place, although you cannot overwrite these attributes altogether.The
info
attribute alone has an additional method calledlayers()
that returns each info template paired with the index that can be passed tonested_data.flatten()
to get the parameters associated with that particular template.Example:
>>> err = Error(a=1, b=[2,3]) >>> err.info += "a: {a}" >>> err.info += lambda e: f"b: {','.join(map(str, e.b))}" >>> raise err Traceback (most recent call last): ... tidyexc.exc.Error: • a: 1 • b: 2,3
- property nested_data
A view providing access to all values defined for each parameter.
This is useful when trying to extract information from an exception where some parameters may have been defined multiple times, e.g. if
add_info()
was used in a recursive function.The simplest way to use this view is to access a parameter name either as an attribute or a dictionary element. This will return a list of all the values associated with that parameter:
>>> with Error.add_info(a=1): ... e = Error(a=2) ... e.nested_data.a [1, 2]
The
[]
operator will also accept a tuple of parameter names, in which case it will return a list of those parameters in every context in which at least one of those parameters was defined. This is useful if you’re interested in parameters that are logically connected (e.g. line and column number) and you want to avoid the possibility of them getting out of sync:>>> with Error.add_info(a=1, b=2): ... with Error.add_info(a=3, b=4): ... e = Error(c=5) ... e.nested_data['a','b'] [(1, 2), (3, 4)]
Finally, the view also has a
flatten()
method that can be used to get all the values for each parameter defined at a particular point in time. The method accepts a single argument which will be used as an index into the internal list of contexts. Thedata.layers()
method can be used to get the index corresponding to any info message template.
- classmethod pop_info()[source]
Stop adding the
info
that was most-recently “pushed” to exceptions derived from this class.This is the opposite of
push_info()
.
- classmethod push_info(*messages, **kwargs)[source]
Add the given
info
to any exceptions derived from this class that are subsequently instantiated.See
add_info()
for more information. This function is similar, except that it is not a context manager. That means that you must manually callpop_info()
orclear_info()
after calling this function.Example:
>>> from tidyexc import Error >>> Error.push_info('a: {a}', a=1) >>> try: ... raise Error() ... finally: ... Error.pop_info() ... Traceback (most recent call last): ... tidyexc.exc.Error: • a: 1