i2.errors

Error objects

Functions

log_and_return(msg[, logger])

Pass msg to logger (print by default) and return it.

Classes

HandleExceptions([on_error])	A context manager that catches and (specifically) handles specific exceptions.
ModuleNotFoundIgnore()	Context manager meant to ignore import errors.

Exceptions

AuthorizationError	Base class for errors about what the caller is allowed to do.
DataError	Base class for errors about the data itself.
DuplicateRecordError	A DataError for a record that already exists.
ForbiddenError	An AuthorizationError for an operation that is not allowed.
InputError	Raised for invalid input.
InterruptWithBlock	Raise inside a with block to leave it early; pair with HandleExceptions.
NotFoundError	A DataError for a record that does not exist.
OverwritesNotAllowed(*args[, forbidden_keys])	To raise when writes are only allowed if the item doesn't already exist

exception i2.errors.AuthorizationError

Bases: Exception

Base class for errors about what the caller is allowed to do.

exception i2.errors.DataError

Bases: Exception

Base class for errors about the data itself.

exception i2.errors.DuplicateRecordError

Bases: DataError

A DataError for a record that already exists.

exception i2.errors.ForbiddenError

Bases: AuthorizationError

An AuthorizationError for an operation that is not allowed.

class i2.errors.HandleExceptions(on_error=<factory>)

Bases: AbstractContextManager

A context manager that catches and (specifically) handles specific exceptions.

It takes one argument: A dict (or mapping) of exception type keys and callback values. If within a with block, the particular (listed) exception happens, the callback is called and it’s returned value is assigned to the HandleExceptions instance’s .exit_value attribute. That attribute will only exist if the with block existed with an exception caught by HandleExceptions.

A callback is an argument-less function. If you need to specify arguments, you can envoke the command pattern, using functools.partial to make a argument-less function. See in the example below how we ask HandleExceptions to print a specific string if a ZeroDivisionError happens:

>>> from functools import partial
>>> def print_and_return(msg):
...     print(msg)
...     return msg
>>> with HandleExceptions({
...     ZeroDivisionError: partial(print_and_return, "You interrupted me"),
...     KeyboardInterrupt: lambda: 'imagine this is code to notify someone'
... }) as he:
...     print('This works')
...     0 / 0
...
This works
You interrupted me

You can check if the context exited with a handled exception, and if so, what the callback returned value was.

>>> he.exited_with_handled_exception()
True
>>> he.exit_value
'You interrupted me'

Also available, whether the exception was a handled one or not: The exception instance itself:

>>> he.exited_with_exception
ZeroDivisionError('division by zero')

If all you want to do though is print a string (and have the same string available in the exit_value attribute, we got you covered! Just specify a string and we’ll make that printer callaback for you!

>>> from functools import partial
>>>
>>> with HandleExceptions({ZeroDivisionError: "You interrupted me again!"}):
...     print('This also works')
...     0 / 0
This also works
You interrupted me again!

Note that specifying partial(print, "some message") will work as a “printing callback”, but the string won’t be available in .exit_value since print returns None.

A few recipes now…

You can also use your own custom exception types to do things like interrupt a with block early given some condition(s).

>>> with HandleExceptions(
...     {InterruptWithBlock: "The with block was interrupted early."}
... ):
...     print('before condition')
...     x = 5 % 2
...     if x:
...         raise InterruptWithBlock()
...     print('after condition')
...
...
before condition
The with block was interrupted early.

Tip

If you need to do stuff with an exception, but reraise it, you can still do that in your callback. Just say raise at the end of the callback!

>>> def print_and_raise(msg):
...     print(msg)
...     raise
>>>
>>> with HandleExceptions({
...     ZeroDivisionError: partial(print_and_raise, "That again!"),
... }):
...     print('This also works')
...     0 / 0
This also works
That again!
Traceback (most recent call last):
    ...
ZeroDivisionError: division by zero

exited_with_handled_exception()

Whether the last with block ended on an exception listed in on_error.

initialize()

Forget the outcome of a previous with block (done on every __enter__).

exception i2.errors.InputError

Bases: Exception

Raised for invalid input.

exception i2.errors.InterruptWithBlock

Bases: BaseException

Raise inside a with block to leave it early; pair with HandleExceptions.

>>> with HandleExceptions({InterruptWithBlock: "stopped early"}) as h:
...     raise InterruptWithBlock()
...     print("never printed")
stopped early
>>> h.exit_value
'stopped early'

class i2.errors.ModuleNotFoundIgnore

Bases: object

Context manager meant to ignore import errors. The use case in mind is when we want to condition some code on the existence of some package.

exception i2.errors.NotFoundError

Bases: DataError

A DataError for a record that does not exist.

exception i2.errors.OverwritesNotAllowed(*args, forbidden_keys=None, **kwargs)

Bases: AuthorizationError

To raise when writes are only allowed if the item doesn’t already exist

i2.errors.log_and_return(msg, logger=<built-in function print>)

Pass msg to logger (print by default) and return it.