Package: oops
**************************python-oops: Error reports**************************Copyright (c) 2011, Canonical LtdThis program is free software: you can redistribute it and/or modifyit under the terms of the GNU Lesser General Public License as published bythe Free Software Foundation, version 3 only.This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See theGNU Lesser General Public License for more details.You should have received a copy of the GNU Lesser General Public Licensealong with this program.  If not, see <http://www.gnu.org/licenses/>.GNU Lesser General Public License version 3 (see the file LICENSE).The oops project provides an in-memory model and basic serialisation,deserialisation and allocation of OOPS reports. An OOPS report is a reportabout something going wrong in a piece of software... thus, an 'oops' :)This core package is rarely used directly: most programs or services that wantto generate OOPS reports will do so via a framework specific adapter (e.g.python-oops_wsgi).Dependencies============* Python 2.6+ or 3.3+* 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 extensiblesimply by adding as many additional keys asneeded. The only constraint is thatthe resulting dict must be bson serializable : this is the standard to whichnew serializers are held. Some existing serializers cannot handle this degreeof extensability and will ignore additional keys, and/or raise an error on keysthey 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 usagewhen the oops is created, or to override / tweak the information gathered by anearlier 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_createcallbacks similarly to the report. This is used to support passing informationto the on_create hooks. For instance, the exc_info key is used to pass ininformation about the exception being logged (if one was caught).* Later on, when something has gone wrong and you want to create an OOPSreport::>>> 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 allocatedby the particular repository that recieved the report. (Id allocation is upto the repository). Publishers should try to use report['id'] for the id, if itis 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 anypublisher (see the api docs for more information).>>> 'id' in reportFalse>>> 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 afterpprinting them. This can be very helpful for interactive use.* The related project oops_datedir_repo contains a local disk based repository whichcan be used as a publisher.More coming soon.Installation============Either run setup.py in an environment with all the dependencies available, oradd the working directory to your PYTHONPATH.Development===========Upstream development takes place at https://launchpad.net/python-oops.To setup a working area for development, if the dependencies are notimmediately available, you can use ./bootstrap.py to create bin/buildout, thenbin/py to get a python interpreter with the dependencies available.To run the tests use the runner of your choice, the test suite isoops.tests.test_suite.For instance::$ bin/py -m testtools.run oops.tests.test_suiteAlternative you can use the testr command from testrepository::$ testr run