Metadata-Version: 2.1
Name: structlog
Version: 19.2.0
Summary: Structured Logging for Python
Home-page: https://www.structlog.org/
Author: Hynek Schlawack
Author-email: hs@ox.cx
Maintainer: Hynek Schlawack
Maintainer-email: hs@ox.cx
License: MIT or Apache License, Version 2.0
Keywords: logging,structured,structure,log
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/x-rst
Requires-Dist: six
Provides-Extra: azure-pipelines
Requires-Dist: coverage ; extra == 'azure-pipelines'
Requires-Dist: freezegun (>=0.2.8) ; extra == 'azure-pipelines'
Requires-Dist: pretend ; extra == 'azure-pipelines'
Requires-Dist: pytest (>=3.3.0) ; extra == 'azure-pipelines'
Requires-Dist: simplejson ; extra == 'azure-pipelines'
Requires-Dist: pytest-azurepipelines ; extra == 'azure-pipelines'
Requires-Dist: python-rapidjson ; (python_version >= "3.6") and extra == 'azure-pipelines'
Provides-Extra: dev
Requires-Dist: coverage ; extra == 'dev'
Requires-Dist: freezegun (>=0.2.8) ; extra == 'dev'
Requires-Dist: pretend ; extra == 'dev'
Requires-Dist: pytest (>=3.3.0) ; extra == 'dev'
Requires-Dist: simplejson ; extra == 'dev'
Requires-Dist: sphinx ; extra == 'dev'
Requires-Dist: twisted ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: python-rapidjson ; (python_version >= "3.6") and extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx ; extra == 'docs'
Requires-Dist: twisted ; extra == 'docs'
Provides-Extra: tests
Requires-Dist: coverage ; extra == 'tests'
Requires-Dist: freezegun (>=0.2.8) ; extra == 'tests'
Requires-Dist: pretend ; extra == 'tests'
Requires-Dist: pytest (>=3.3.0) ; extra == 'tests'
Requires-Dist: simplejson ; extra == 'tests'
Requires-Dist: python-rapidjson ; (python_version >= "3.6") and extra == 'tests'

.. image:: https://www.structlog.org/en/latest/_static/structlog_logo_small.png
   :alt: structlog Logo
   :width: 256px
   :target: https://www.structlog.org/

============================================
``structlog``: Structured Logging for Python
============================================

.. image:: https://img.shields.io/pypi/v/structlog.svg
   :target: https://pypi.org/project/structlog/
   :alt: PyPI

.. image:: https://readthedocs.org/projects/structlog/badge/?version=stable
   :target: https://www.structlog.org/en/stable/?badge=stable
   :alt: Documentation Status

.. image:: https://dev.azure.com/the-hynek/structlog/_apis/build/status/hynek.structlog?branchName=master
   :target: https://dev.azure.com/the-hynek/structlog/_build?definitionId=1
   :alt: CI Status

.. image:: https://codecov.io/github/hynek/structlog/branch/master/graph/badge.svg
   :target: https://codecov.io/github/hynek/structlog
   :alt: Test Coverage

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black
   :alt: Code style: black

.. -begin-short-

``structlog`` makes logging in Python less painful and more powerful by adding structure to your log entries.

It's up to you whether you want ``structlog`` to take care about the **output** of your log entries or whether you prefer to **forward** them to an existing logging system like the standard library's ``logging`` module.

.. -end-short-

Once you feel inspired to try it out, check out our friendly `Getting Started tutorial <https://www.structlog.org/en/stable/getting-started.html>`_ that also contains detailed installation instructions!

.. -begin-spiel-

If you prefer videos over reading, check out this DjangoCon Europe 2019 talk by `Markus Holtermann <https://twitter.com/m_holtermann>`_: "`Logging Rethought 2: The Actions of Frank Taylor Jr. <https://www.youtube.com/watch?v=Y5eyEgyHLLo>`_".


Easier Logging
==============

You can stop writing prose and start thinking in terms of an event that happens in the context of key/value pairs:

.. code-block:: pycon

   >>> from structlog import get_logger
   >>> log = get_logger()
   >>> log.info("key_value_logging", out_of_the_box=True, effort=0)
   2016-04-20 16:20.13 key_value_logging              effort=0 out_of_the_box=True

Each log entry is a meaningful dictionary instead of an opaque string now!


Data Binding
============

Since log entries are dictionaries, you can start binding and re-binding key/value pairs to your loggers to ensure they are present in every following logging call:

.. code-block:: pycon

   >>> log = log.bind(user="anonymous", some_key=23)
   >>> log = log.bind(user="hynek", another_key=42)
   >>> log.info("user.logged_in", happy=True)
   2016-04-20 16:20.13 user.logged_in                 another_key=42 happy=True some_key=23 user='hynek'


Powerful Pipelines
==================

Each log entry goes through a `processor pipeline <https://www.structlog.org/en/stable/processors.html>`_ that is just a chain of functions that receive a dictionary and return a new dictionary that gets fed into the next function.
That allows for simple but powerful data manipulation:

.. code-block:: python

   def timestamper(logger, log_method, event_dict):
       """Add a timestamp to each log entry."""
       event_dict["timestamp"] = time.time()
       return event_dict

There are `plenty of processors <https://www.structlog.org/en/stable/api.html#module-structlog.processors>`_ for most common tasks coming with ``structlog``:

- Collectors of `call stack information <https://www.structlog.org/en/stable/api.html#structlog.processors.StackInfoRenderer>`_ ("How did this log entry happen?"),
- …and `exceptions <https://www.structlog.org/en/stable/api.html#structlog.processors.format_exc_info>`_ ("What happened‽").
- Unicode encoders/decoders.
- Flexible `timestamping <https://www.structlog.org/en/stable/api.html#structlog.processors.TimeStamper>`_.



Formatting
==========

``structlog`` is completely flexible about *how* the resulting log entry is emitted.
Since each log entry is a dictionary, it can be formatted to **any** format:

- A colorful key/value format for `local development <https://www.structlog.org/en/stable/development.html>`_,
- `JSON <https://www.structlog.org/en/stable/api.html#structlog.processors.JSONRenderer>`_ for easy parsing,
- or some standard format you have parsers for like nginx or Apache httpd.

Internally, formatters are processors whose return value (usually a string) is passed into loggers that are responsible for the output of your message.
``structlog`` comes with multiple useful formatters out-of-the-box.


Output
======

``structlog`` is also very flexible with the final output of your log entries:

- A **built-in** lightweight printer like in the examples above.
  Easy to use and fast.
- Use the **standard library**'s or **Twisted**'s logging modules for compatibility.
  In this case ``structlog`` works like a wrapper that formats a string and passes them off into existing systems that won't ever know that ``structlog`` even exists.
  Or the other way round: ``structlog`` comes with a ``logging`` formatter that allows for processing third party log records.
- Don't format it to a string at all!
  ``structlog`` passes you a dictionary and you can do with it whatever you want.
  Reported uses cases are sending them out via network or saving them in a database.

.. -end-spiel-

.. -begin-meta-

Getting Help
============

Please use the ``structlog`` tag on `StackOverflow <https://stackoverflow.com/questions/tagged/structlog>`_ to get help.

Answering questions of your fellow developers is also great way to help the project!


Project Information
===================

``structlog`` is dual-licensed under `Apache License, version 2 <https://choosealicense.com/licenses/apache/>`_ and `MIT <https://choosealicense.com/licenses/mit/>`_, available from `PyPI <https://pypi.org/project/structlog/>`_, the source code can be found on `GitHub <https://github.com/hynek/structlog>`_, the documentation at https://www.structlog.org/.

We collect useful third party extension in `our wiki <https://github.com/hynek/structlog/wiki/Third-party-Extensions>`_.

``structlog`` targets Python 2.7, 3.5 and newer, and PyPy.


Release Information
===================

19.2.0 (2019-10-16)
-------------------


Backward-incompatible changes:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Python 3.4 is not supported anymore.
  It has been unsupported by the Python core team for a while now and its PyPI downloads are negligible.

  It's very unlikely that ``structlog`` will break under 3.4 anytime soon, but we don't test it anymore.


Deprecations:
^^^^^^^^^^^^^

*none*


Changes:
^^^^^^^^

- Full Python 3.8 support for ``structlog.stdlib``.
- Added more pass-through properties to ``structlog.stdlib.BoundLogger``.
  To makes it easier to use it as a drop-in replacement for ``logging.Logger``.
  `#198 <https://github.com/hynek/structlog/issues/198>`_
- ``structlog.stdlib.ProcessorFormatter`` now takes a logger object as an optional keyword argument.
  This makes ``ProcessorFormatter`` work properly with ``stuctlog.stdlib.filter_by_level()``.
  `#219 <https://github.com/hynek/structlog/issues/219>`_
- ``structlog.dev.ConsoleRenderer`` now uses no colors by default, if ``colorama`` is not available.
  `#215 <https://github.com/hynek/structlog/issues/215>`_
- ``structlog.dev.ConsoleRenderer`` now initializes ``colorama`` lazily, to prevent accidental side-effects just by importing ``structlog``.
  `#210 <https://github.com/hynek/structlog/issues/210>`_
- Added new processor ``structlog.dev.set_exc_info()`` that will set ``exc_info=True`` if the method's name is `exception` and ``exc_info`` isn't set at all.
  *This is only necessary when the standard library integration is not used*.
  It fixes the problem that in the default configuration, ``structlog.get_logger().exception("hi")`` in an ``except`` block would not print the exception without passing ``exc_info=True`` to it explicitly.
  `#130 <https://github.com/hynek/structlog/issues/130>`_,
  `#173 <https://github.com/hynek/structlog/issues/173>`_,
  `#200 <https://github.com/hynek/structlog/issues/200>`_,
  `#204 <https://github.com/hynek/structlog/issues/204>`_
- A best effort has been made to make as much of ``structlog`` pickleable as possible to make it friendlier with ``multiprocessing`` and similar libraries.
  Some classes can only be pickled on Python 3 or using the `dill <https://pypi.org/project/dill/>`_ library though and that is very unlikely to change.

  So far, the configuration proxy, ``structlog.processor.TimeStamper``, ``structlog.BoundLogger``, ``structlog.PrintLogger`` and ``structlog.dev.ConsoleRenderer`` have been made pickelable.
  Please report if you need any another class fixed.
  `#126 <https://github.com/hynek/structlog/issues/126>`_
- Added a new thread-local API that allows binding values to a thread-local context explicitly without affecting the default behavior of ``bind()``.
  `#222 <https://github.com/hynek/structlog/issues/222>`_,
  `#225 <https://github.com/hynek/structlog/issues/225>`_
- Added ``pass_foreign_args`` argument to ``structlog.stdlib.ProcessorFormatter``.
  It allows to pass a foreign log record's ``args`` attribute to the event dictionary under the ``positional_args`` key.
  `#228 <https://github.com/hynek/structlog/issues/228>`_
- ``structlog.dev.ConsoleRenderer`` now calls ``str()`` on the event value.
  `#221 <https://github.com/hynek/structlog/issues/221>`_

`Full changelog <https://www.structlog.org/en/stable/changelog.html>`_.

Authors
=======

``structlog`` is written and maintained by `Hynek Schlawack <https://hynek.me/>`_.
It’s inspired by previous work done by `Jean-Paul Calderone <https://as.ynchrono.us/>`_ and `David Reid <https://dreid.org/>`_.

The development is kindly supported by `Variomedia AG <https://www.variomedia.de/>`_.

A full list of contributors can be found on GitHub’s `overview <https://github.com/hynek/structlog/graphs/contributors>`_.
Some of them disapprove of the addition of thread local context data. :)

The ``structlog`` logo has been contributed by `Russell Keith-Magee <https://github.com/freakboy3742>`_.


