oops 0.2.0

Dependencies

• Python 3.8+

• pytz (http://pypi.python.org/pypi/pytz/)

Testing Dependencies

• subunit (http://pypi.python.org/pypi/python-subunit) (optional)

• testtools (http://pypi.python.org/pypi/testtools)

Usage

In Python, OOPS reports are dicts with some well known keys, but extensible simply by adding as many additional keys asneeded. The only constraint is that the resulting dict must be bson serializable : this is the standard to which new serializers are held. Some existing serializers cannot handle this degree of extensability and will ignore additional keys, and/or raise an error on keys they expect but which contain unexpected data.

Typical usage:

• When initializing your script/app/server, create a Config object:

  >>> from oops import Config
  >>> config = Config()

• New reports will be based on the template report:

  >>> config.template
  {}

• You can edit the template report (which like all reports is just a dict):

  >>> config.template['branch_nick'] = 'mybranch'
  >>> config.template['appname'] = 'demo'

• You can supply a callback (for instance, to capture your process memory usage

when the oops is created, or to override / tweak the information gathered by an earlier callback):

>>> mycallback = lambda report, context: None
>>> config.on_create.append(mycallback)

The context parameter is also just dict, and is passed to all the on_create callbacks similarly to the report. This is used to support passing information to the on_create hooks. For instance, the exc_info key is used to pass in information about the exception being logged (if one was caught).

• Later on, when something has gone wrong and you want to create an OOPS report:

  >>> report = config.create(context=dict(exc_info=sys.exc_info()))
  >>> report
  {'appname': 'demo', 'branch_nick': 'mybranch'}

• And then send it off for storage:

  >>> config.publish(report)
  []

• Note that publish returns a list - each item in the list is the id allocated by the particular repository that recieved the report. (Id allocation is up to the repository). Publishers should try to use report[‘id’] for the id, if it is set. This is automatically set to the id returned by the previous publisher.

If publish returns None, then the report was filtered and not passed to any publisher (see the api docs for more information).

>>> 'id' in report
False
>>> def demo_publish(report):
...    return ['id 1']
>>> config.publisher = demo_publish
>>> config.publish(report)
['id 1']
>>> report['id']
'id 1'

• The pprint_to_stream publisher will print out reports to a stream after pprinting them. This can be very helpful for interactive use.

• The related project oops_datedir_repo contains a local disk based repository which can be used as a publisher.

More coming soon.

Installation

python-oops can be installed into an existing Python environment in the usual way using pip, or it can be installed as a standalone package. To install it as a standalone package, run make to create a suitable virtual environment.

Development

Upstream development takes place at https://launchpad.net/python-oops.

To run this project’s tests, use tox <https://tox.readthedocs.io/en/latest/>.

For example, run:

$ tox

Or:

$ tox -e py38