Metadata-Version: 2.1
Name: airbrake
Version: 2.1.2
Summary: Python SDK for airbrake.io
Home-page: https://github.com/airbrake/airbrake-python
Author: BK Box, Sam Stavinoha
Author-email: samuel.stavinoha@rackspace.com
License: Apache License, Version 2.0
Keywords: airbrake exceptions airbrake.io 4c595398
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: requests (>=2.20.0)

airbrake-python
===============

*Note*. Python 3.4+ are advised to use new `Airbrake Python
notifier <https://github.com/airbrake/pybrake>`__ which supports async
API and code hunks. Python 2.7 users should continue to use this
notifier.

`Airbrake <https://airbrake.io/>`__ integration for python that quickly
and easily plugs into your existing code.

.. code:: python

   import airbrake

   logger = airbrake.getLogger()

   try:
       1/0
   except Exception:
       logger.exception("Bad math.")

airbrake-python is used most effectively through its
`logging <http://docs.python.org/2/library/logging.html>`__ handler, and
uses the `Airbrake V3 API <https://airbrake.io/docs/api/>`__ for error
reporting.

install
~~~~~~~

To install airbrake-python, run:

.. code:: bash

   $ pip install -U airbrake

setup
~~~~~

The easiest way to get set up is with a few environment variables:

.. code:: bash

   export AIRBRAKE_API_KEY=*****
   export AIRBRAKE_PROJECT_ID=12345
   export AIRBRAKE_ENVIRONMENT=dev

and you’re done!

Otherwise, you can instantiate your ``AirbrakeHandler`` by passing these
values as arguments to the ``getLogger()`` helper:

.. code:: python

   import airbrake

   logger = airbrake.getLogger(api_key=*****, project_id=12345)

   try:
       1/0
   except Exception:
       logger.exception("Bad math.")

By default, airbrake will catch and send uncaught exceptions. To avoid
this behvaiour, use the send_uncaught_exc option:
``logger = airbrake.getLogger(api_key=*****, project_id=12345, send_uncaught_exc=False)``

setup for Airbrake On-Premise and other compatible back-ends (e.g. Errbit)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Airbrake `Enterprise <https://airbrake.io/enterprise>`__ and self-hosted
alternatives, such as `Errbit <https://github.com/errbit/errbit>`__,
provide a compatible API.

You can configure a different endpoint than the default
(``https://api.airbrake.io``) by either:

-  Setting an environment variable:

.. code:: bash

   export AIRBRAKE_HOST=https://self-hosted.errbit.example.com/

-  Or passing a ``host`` argument to the ``getLogger()`` helper:

.. code:: python

   import airbrake

   logger = airbrake.getLogger(api_key=*****, project_id=12345, host="https://self-hosted.errbit.example.com/")

adding the AirbrakeHandler to your existing logger
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: python

   import logging

   import airbrake

   yourlogger = logging.getLogger(__name__)
   yourlogger.addHandler(airbrake.AirbrakeHandler())

*by default, the ``AirbrakeHandler`` only handles logs level ERROR (40)
and above*

Additional Options
^^^^^^^^^^^^^^^^^^

More options are available to configure this library.

For example, you can set the environment to add more context to your
errors. One way is by setting the AIRBRAKE_ENVIRONMENT env var.

::

   export AIRBRAKE_ENVIRONMENT=staging

Or you can set it more explicitly when you instantiate the logger.

.. code:: python

   import airbrake

   logger = airbrake.getLogger(api_key=*****, project_id=12345, environment='production')

The available options are: - environment, defaults to env var
``AIRBRAKE_ENVIRONMENT`` - host, defaults to env var ``AIRBRAKE_HOST``
or https://api.airbrake.io - root_directory, defaults to None - timeout,
defaults to 5. (Number of seconds before each request times out) -
send_uncaught_exc, defaults to True (Whether or not to send uncaught
exceptions)

giving your exceptions more context
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: python

   import airbrake

   logger = airbrake.getLogger()

   def bake(**goods):
       try:
           temp = goods['temperature']
       except KeyError as exc:
           logger.error("No temperature defined!", extra=goods)

Setting severity
^^^^^^^^^^^^^^^^

[Severity][what-is-severity] allows categorizing how severe an error is.
By default, it’s set to ``error``. To redefine severity, simply
``build_notice`` with the needed severity value. For example:

.. code:: python

   notice = airbrake.build_notice(exception, severity="critical")
   airbrake.notify(notice)

Using this library without a logger
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can create an instance of the notifier directly, and send errors
inside exception blocks.

.. code:: python

   from airbrake.notifier import Airbrake

   ab = Airbrake(project_id=1234, api_key='fake')

   try:
       amazing_code()
   except ValueError as e:
       ab.notify(e)
   except:
       # capture all other errors
       ab.capture()

Running Tests Manually
^^^^^^^^^^^^^^^^^^^^^^

Create your environment and install the test requirements

::

   virtualenv venv
   source venv/bin/activate
   pip install .
   python setup.py test

To run via nose (unit/integration tests):

::

   source venv/bin/activate
   pip install -r ./test-requirements.txt
   source venv/bin/activate
   nosetests

Run all tests, including multi-env syntax, and coverage tests.

::

   pip install tox
   tox -v --recreate

It’s suggested to make sure tox will pass, as CI runs this. tox needs to
pass before any PRs are merged.

--------------

The `airbrake.io <https://airbrake.io/>`__ api docs used to implement
airbrake-python are here: https://airbrake.io/docs/api/

[[what-is-severity]:
https://airbrake.io/docs/airbrake-faq/what-is-severity/]


