[Python-modules-commits] [python-structlog] 02/07: New upstream release.
Vincent Bernat
bernat at moszumanska.debian.org
Sat Oct 14 15:54:46 UTC 2017
This is an automated email from the git hooks/post-receive script.
bernat pushed a commit to branch debian/master
in repository python-structlog.
commit 15200570b167c055bc9df2048c44b9783db68bf3
Author: Vincent Bernat <bernat at debian.org>
Date: Sat Oct 14 17:26:18 2017 +0200
New upstream release.
---
.travis.yml | 18 +-
AUTHORS.rst | 2 +
CHANGELOG.rst | 82 +++++++++
CONTRIBUTING.rst | 161 ++++++++++++++--
MANIFEST.in | 2 +-
PKG-INFO | 145 ++++++++++++---
README.rst | 108 +++++++++--
conftest.py | 31 ++++
docs/_static/structlog_logo.png | Bin 0 -> 98810 bytes
docs/_static/structlog_logo_small.png | Bin 0 -> 49112 bytes
docs/api.rst | 85 ++++++---
docs/code_examples/flask_/__init__.py | 0
docs/code_examples/flask_/webapp.py | 16 +-
docs/conf.py | 3 +
docs/custom-wrappers.rst | 13 ++
docs/examples.rst | 8 +-
docs/faq.rst | 49 -----
docs/getting-started.rst | 16 +-
docs/index.rst | 53 ++----
docs/performance.rst | 2 +-
docs/processors.rst | 12 ++
docs/standard-library.rst | 188 +++++++++++++++++--
docs/thread-local.rst | 17 +-
docs/why.rst | 9 +-
setup.cfg | 5 +-
setup.py | 2 +
src/structlog.egg-info/PKG-INFO | 145 ++++++++++++---
src/structlog.egg-info/SOURCES.txt | 5 +-
src/structlog/__init__.py | 2 +-
src/structlog/_config.py | 17 +-
src/structlog/_generic.py | 2 +-
src/structlog/dev.py | 140 ++++++++++----
src/structlog/processors.py | 51 +++--
src/structlog/stdlib.py | 138 +++++++++++++-
src/structlog/threadlocal.py | 10 -
src/structlog/twisted.py | 14 +-
tests/test_base.py | 10 +-
tests/test_config.py | 3 +-
tests/test_dev.py | 178 +++++++++++-------
tests/test_processors.py | 49 +++--
tests/test_stdlib.py | 338 +++++++++++++++++++++++++++++++++-
tests/test_twisted.py | 31 +++-
tox.ini | 23 +--
43 files changed, 1738 insertions(+), 445 deletions(-)
diff --git a/.travis.yml b/.travis.yml
index 52b93e0..072276b 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -20,22 +20,28 @@ matrix:
env: TOXENV=py35-threads
- python: "3.5"
env: TOXENV=py35-greenlets
- - python: "3.5"
- env: TOXENV=py35-nocolorama
+ - python: "3.6"
+ env: TOXENV=py36-threads
+ - python: "3.6"
+ env: TOXENV=py36-greenlets
- python: "pypy"
env: TOXENV=pypy-threads
- python: "pypy"
env: TOXENV=pypy-greenlets
+ - python: "2.7"
+ env: TOXENV=py27-colorama
+ - python: "3.6"
+ env: TOXENV=py36-colorama
# Meta
- - python: "3.5"
+ - python: "3.6"
env: TOXENV=flake8
- - python: "3.5"
+ - python: "3.6"
env: TOXENV=manifest
- - python: "3.5"
+ - python: "3.6"
env: TOXENV=docs
- - python: "3.5"
+ - python: "3.6"
env: TOXENV=readme
diff --git a/AUTHORS.rst b/AUTHORS.rst
index 06cee70..a9b577b 100644
--- a/AUTHORS.rst
+++ b/AUTHORS.rst
@@ -8,3 +8,5 @@ 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>`_.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 5f4471c..4d67b50 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -5,6 +5,88 @@ Versions are year-based with a strict backward compatibility policy.
The third digit is only for regressions.
+17.2.0 (2017-05-15)
+-------------------
+
+
+Backward-incompatible changes:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*none*
+
+
+Deprecations:
+^^^^^^^^^^^^^
+
+*none*
+
+
+Changes:
+^^^^^^^^
+
+- ``structlog.stdlib.ProcessorFormatter`` now accepts *keep_exc_info* and *keep_stack_info* arguments to control what to do with this information on log records.
+ Most likely you want them both to be ``False`` therefore it's the default.
+ `#109 <https://github.com/hynek/structlog/issues/109>`_
+- ``structlog.stdlib.add_logger_name()`` now works in ``structlog.stdlib.ProcessorFormatter``'s ``foreign_pre_chain``.
+ `#112 <https://github.com/hynek/structlog/issues/112>`_
+- Clear log record args in ``structlog.stdlib.ProcessorFormatter`` after rendering.
+ This fix is for you if you tried to use it and got ``TypeError: not all arguments converted during string formatting`` exceptions.
+ `#116 <https://github.com/hynek/structlog/issues/116>`_
+ `#117 <https://github.com/hynek/structlog/issues/117>`_
+
+
+----
+
+
+17.1.0 (2017-04-24)
+-------------------
+
+The main features of this release are massive improvements in standard library's ``logging`` integration.
+Have a look at the updated `standard library chapter <http://www.structlog.org/en/stable/standard-library.html>`_ on how to use them!
+Special thanks go to
+`Fabian Büchler <https://github.com/fabianbuechler>`_,
+`Gilbert Gilb's <https://github.com/gilbsgilbs>`_,
+`Iva Kaneva <https://github.com/if-fi>`_,
+`insolite <https://github.com/insolite>`_,
+and `sky-code <https://github.com/sky-code>`_,
+that made them possible.
+
+
+Backward-incompatible changes:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- The default renderer now is ``structlog.dev.ConsoleRenderer`` if you don't configure ``structlog``.
+ Colors are used if available and human-friendly timestamps are prepended.
+ This is in line with our backward `compatibility policy <http://www.structlog.org/en/stable/backward-compatibility.html>`_ that explicitly excludes default settings.
+
+
+Changes:
+^^^^^^^^
+
+- Added ``structlog.stdlib.render_to_log_kwargs()``.
+ This allows you to use ``logging``-based formatters to take care of rendering your entries.
+ `#98 <https://github.com/hynek/structlog/issues/98>`_
+- Added ``structlog.stdlib.ProcessorFormatter`` which does the opposite:
+ This allows you to run ``structlog`` processors on arbitrary ``logging.LogRecords``.
+ `#79 <https://github.com/hynek/structlog/issues/79>`_
+ `#105 <https://github.com/hynek/structlog/issues/105>`_
+- UNIX epoch timestamps from ``structlog.processors.TimeStamper`` are more precise now.
+- Added *repr_native_str* to ``structlog.processors.KeyValueRenderer`` and ``structlog.dev.ConsoleRenderer``.
+ This allows for human-readable non-ASCII output on Python 2 (``repr()`` on Python 2 behaves like ``ascii()`` on Python 3 in that regard).
+ As per compatibility policy, it's on (original behavior) in ``KeyValueRenderer`` and off (humand-friendly behavior) in ``ConsoleRenderer``.
+ `#94 <https://github.com/hynek/structlog/issues/94>`_
+- Added *colors* argument to ``structlog.dev.ConsoleRenderer`` and made it the default renderer.
+ `#78 <https://github.com/hynek/structlog/pull/78>`_
+- Fixed bug with Python 3 and ``structlog.stdlib.BoundLogger.log()``.
+ Error log level was not reproductible and was logged as exception one time out of two.
+ `#92 <https://github.com/hynek/structlog/pull/92>`_
+- Positional arguments are now removed even if they are empty.
+ `#82 <https://github.com/hynek/structlog/pull/82>`_
+
+
+----
+
+
16.1.0 (2016-05-24)
-------------------
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index e858a96..096dd23 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,32 +1,151 @@
How To Contribute
=================
-Every open source project lives from the generous help by contributors that sacrifice their time and ``structlog`` is no different.
+First off, thank you for considering contributing to ``structlog``!
+It's people like *you* who make it is such a great tool for everyone.
-Here are a few guidelines to get you started:
+This document is mainly to help you to get started by codifying tribal knowledge and expectations and make it more accessible to everyone.
+But don't be afraid to open half-finished PRs and ask questions if something is unclear!
-- Try to limit each pull request to one change only.
-- To run the test suite, all you need is a recent tox_.
- It will ensure the test suite runs with all dependencies against all Python versions just as it will on `Travis CI`_.
- If you lack some Python version, you can can always limit the environments like ``tox -e py27,py35`` (in that case you may want to look into pyenv_ that makes it very easy to install many different Python versions in parallel).
-- Make sure your changes pass our CI.
+
+Workflow
+--------
+
+- No contribution is too small!
+ Please submit as many fixes for typos and grammar bloopers as you can!
+- Try to limit each pull request to *one* change only.
+- *Always* add tests and docs for your code.
+ This is a hard rule; patches with missing tests or documentation can't be accepted.
+- Make sure your changes pass our CI_.
You won't get any feedback until it's green unless you ask for it.
-- If your change is noteworthy, add an entry to the changelog_.
- Use present tense, semantic newlines, and add link to your pull request.
-- No contribution is too small; please submit as many fixes for typos and grammar bloopers as you can!
+- Once you've addressed review feedback, make sure to bump the pull request with a short note.
+ Maintainers don’t receive notifications when you push new commits.
- Don’t break `backward compatibility`_.
-- *Always* add tests and docs for your code.
- This is a hard rule; patches with missing tests or documentation won’t be merged.
-- Write `good test docstrings`_.
+
+
+Code
+----
+
- Obey `PEP 8`_ and `PEP 257`_.
-- If you address review feedback, make sure to bump the pull request.
- Maintainers don’t receive notifications if you push new commits.
+ We use the ``"""``\ -on-separate-lines style for docstrings:
+
+ .. code-block:: python
+
+ def func(x):
+ """
+ Do something.
+
+ :param str x: A very important parameter.
+
+ :rtype: str
+ """
+- If you add or change public APIs, tag the docstring using ``.. versionadded:: 16.0.0 WHAT`` or ``.. versionchanged:: 17.1.0 WHAT``.
+- Prefer double quotes (``"``) over single quotes (``'``) unless the string contains double quotes itself.
+
+
+Tests
+-----
+
+- Write your asserts as ``expected == actual`` to line them up nicely:
+
+ .. code-block:: python
+
+ x = f()
+
+ assert 42 == x.some_attribute
+ assert "foo" == x._a_private_attribute
+
+- To run the test suite, all you need is a recent tox_.
+ It will ensure the test suite runs with all dependencies against all Python versions just as it will on Travis CI.
+ If you lack some Python versions, you can can always limit the environments like ``tox -e py27,py35`` (in that case you may want to look into pyenv_, which makes it very easy to install many different Python versions in parallel).
+- Write `good test docstrings`_.
+
+
+Documentation
+-------------
+
+- Use `semantic newlines`_ in reStructuredText_ files (files ending in ``.rst``):
+
+ .. code-block:: rst
+
+ This is a sentence.
+ This is another sentence.
+
+- If you start a new section, add two blank lines before and one blank line after the header except if two headers follow immediately after each other:
+
+ .. code-block:: rst
+
+ Last line of previous section.
+
+
+ Header of New Top Section
+ -------------------------
+
+ Header of New Section
+ ^^^^^^^^^^^^^^^^^^^^^
+
+ First line of new section.
+- If your change is noteworthy, add an entry to the changelog_.
+ Use `semantic newlines`_, and add a link to your pull request:
+
+ .. code-block:: rst
+
+ - Added ``structlog.func()`` that does foo.
+ It's pretty cool.
+ [`#1 <https://github.com/hynek/structlog/pull/1>`_]
+ - ``structlog.func()`` now doesn't crash the Large Hadron Collider anymore.
+ That was a nasty bug!
+ [`#2 <https://github.com/hynek/structlog/pull/2>`_]
+
+
+Local Development Environment
+-----------------------------
+
+You can (and should) run our test suite using tox_ however you’ll probably want a more traditional environment too.
+We highly recommend to develop using the latest Python 3 release because you're more likely to catch certain bugs earlier.
+
+First create a `virtual environment <https://virtualenv.pypa.io/>`_.
+It’s out of scope for this document to list all the ways to manage virtual environments in Python but if you don’t have already a pet way, take some time to look at tools like `pew <https://github.com/berdario/pew>`_, `virtualfish <http://virtualfish.readthedocs.io/>`_, and `virtualenvwrapper <http://virtualenvwrapper.readthedocs.io/>`_.
+
+Next get an up to date checkout of the ``structlog`` repository:
+
+.. code-block:: bash
+
+ git checkout git at github.com:hynek/structlog.git
+
+Change into the newly created directory and **after activating your virtual environment** install an editable version of ``structlog``:
+
+.. code-block:: bash
+
+ cd structlog
+ pip install -e .
+
+If you run the virtual environment’s Python and try to ``import structlog`` it should work!
+
+To run the test suite, you'll need our development dependencies which can be installed using
+
+.. code-block:: bash
+
+ pip install -r dev-requirements.txt
+
+At this point
+
+.. code-block:: bash
+
+ python -m pytest
+
+should work and pass!
+
+****
+
+Again, this list is mainly to help you to get started by codifying tribal knowledge and expectations.
+If something is unclear, feel free to ask for help!
Please note that this project is released with a Contributor `Code of Conduct`_.
By participating in this project you agree to abide by its terms.
Please report any harm to `Hynek Schlawack`_ in any way you find appropriate.
-Thank you for considering to contribute to ``structlog``!
+Thank you for considering contributing to ``structlog``!
.. _`Hynek Schlawack`: https://hynek.me/about/
@@ -35,7 +154,9 @@ Thank you for considering to contribute to ``structlog``!
.. _`good test docstrings`: https://jml.io/pages/test-docstrings.html
.. _`Code of Conduct`: https://github.com/hynek/structlog/blob/master/CODE_OF_CONDUCT.rst
.. _changelog: https://github.com/hynek/structlog/blob/master/CHANGELOG.rst
-.. _`backward compatibility`: http://www.structlog.org/en/latest/backward-compatibility.html
-.. _`tox`: https://testrun.org/tox/
-.. _`Travis CI`: https://travis-ci.org/
-.. _pyenv: https://github.com/yyuu/pyenv
+.. _`backward compatibility`: https://structlog.readthedocs.io/en/latest/backward-compatibility.html
+.. _tox: https://tox.readthedocs.io/
+.. _pyenv: https://github.com/pyenv/pyenv
+.. _reStructuredText: http://sphinx-doc.org/rest.html
+.. _semantic newlines: http://rhodesmill.org/brandon/2012/one-sentence-per-line/
+.. _CI: https://travis-ci.org/hynek/structlog/
diff --git a/MANIFEST.in b/MANIFEST.in
index 20cc4b2..81c5a1f 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,4 +1,4 @@
-include LICENSE LICENSE.apache2 LICENSE.mit .coveragerc
+include LICENSE LICENSE.apache2 LICENSE.mit .coveragerc conftest.py
include *.rst
include *.txt
include .travis.yml
diff --git a/PKG-INFO b/PKG-INFO
index ed44c56..ab65f4c 100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@ -1,41 +1,127 @@
Metadata-Version: 1.1
Name: structlog
-Version: 16.1.0
+Version: 17.2.0
Summary: Structured Logging for Python
Home-page: http://www.structlog.org/
Author: Hynek Schlawack
Author-email: hs at ox.cx
License: MIT or Apache License, Version 2.0
-Description: ========================================
+Description: .. image:: http://www.structlog.org/en/latest/_static/structlog_logo_small.png
+ :alt: structlog Logo
+ :width: 256px
+ :target: http://www.structlog.org/
+
+ ========================================
structlog: Structured Logging for Python
========================================
+ .. image:: https://readthedocs.org/projects/structlog/badge/?version=stable
+ :target: https://structlog.readthedocs.io/en/stable/?badge=stable
+ :alt: Documentation Status
+
.. image:: https://travis-ci.org/hynek/structlog.svg?branch=master
:target: https://travis-ci.org/hynek/structlog
- .. image:: https://codecov.io/github/hynek/structlog/coverage.svg?branch=master
- :target: https://codecov.io/github/hynek/structlog?branch=master
+ .. image:: https://codecov.io/github/hynek/structlog/branch/master/graph/badge.svg
+ :target: https://codecov.io/github/hynek/structlog
+ :alt: Test Coverage
.. image:: https://www.irccloud.com/invite-svg?channel=%23structlog&hostname=irc.freenode.net&port=6697&ssl=1
:target: https://www.irccloud.com/invite?channel=%23structlog&hostname=irc.freenode.net&port=6697&ssl=1
- ``structlog`` makes structured logging in Python easy by *augmenting* your *existing* logger.
- It allows you to split your log entries up into key/value pairs and build them incrementally without annoying boilerplate code.
+ .. begin
+
+ ``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.
+ *No* `monkey patching <https://en.wikipedia.org/wiki/Monkey_patch>`_ involved in either case.
+
+
+ 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)
- out_of_the_box=True effort=0 event='key_value_logging'
- >>> log = log.bind(user='anonymous', some_key=23)
- >>> log = log.bind(user='hynek', another_key=42)
- >>> log.info('user.logged_in', happy=True)
- some_key=23 user='hynek' another_key=42 happy=True event='user.logged_in'
+ 2016-04-20 16:20.13 key_value_logging effort=0 out_of_the_box=True
- .. begin
+ 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 <http://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
- It's dual-licensed under `Apache License, version 2 <http://choosealicense.com/licenses/apache/>`_ and `MIT <http://choosealicense.com/licenses/mit/>`_, available from `PyPI <https://pypi.python.org/pypi/structlog/>`_, the source code can be found on `GitHub <https://github.com/hynek/structlog>`_, the documentation at http://www.structlog.org/.
+ There are `plenty of processors <http://www.structlog.org/en/stable/api.html#module-structlog.processors>`_ for most common tasks coming with ``structlog``:
+
+ - Collectors of `call stack information <http://www.structlog.org/en/stable/api.html#structlog.processors.StackInfoRenderer>`_ ("How did this log entry happen?"),
+ - …and `exceptions <http://www.structlog.org/en/stable/api.html#structlog.processors.format_exc_info>`_ ("What happened‽").
+ - Unicode encoders/decoders.
+ - Flexible `timestamping <http://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 <http://www.structlog.org/en/stable/development.html>`_,
+ - `JSON <http://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-
+
+
+ Project Information
+ ===================
+
+ ``structlog`` is dual-licensed under `Apache License, version 2 <http://choosealicense.com/licenses/apache/>`_ and `MIT <http://choosealicense.com/licenses/mit/>`_, available from `PyPI <https://pypi.python.org/pypi/structlog/>`_, the source code can be found on `GitHub <https://github.com/hynek/structlog>`_, the documentation at http://www.structlog.org/.
``structlog`` targets Python 2.7, 3.4 and newer, and PyPy.
@@ -45,30 +131,34 @@ Description: ========================================
Release Information
===================
- 16.1.0 (2016-05-24)
+ 17.2.0 (2017-05-15)
-------------------
+
Backward-incompatible changes:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- - Python 3.3 and 2.6 aren't supported anymore.
- They may work by chance but any effort to keep them working has ceased.
+ *none*
+
- The last Python 2.6 release was on October 29, 2013 and isn't supported by the CPython core team anymore.
- Major Python packages like Django and Twisted dropped Python 2.6 a while ago already.
+ Deprecations:
+ ^^^^^^^^^^^^^
+
+ *none*
- Python 3.3 never had a significant user base and wasn't part of any distribution's LTS release.
Changes:
^^^^^^^^
- - Add a ``drop_missing`` argument to ``KeyValueRenderer``.
- If ``key_order`` is used and a key is missing a value, it's not rendered at all instead of being rendered as ``None``.
- `#67 <https://github.com/hynek/structlog/pull/67>`_
- - Exceptions without a ``__traceback__`` are now also rendered on Python 3.
- - Don't cache loggers in lazy proxies returned from ``get_logger()``.
- This lead to in-place mutation of them if used before configuration which in turn lead to the problem that configuration was applied only partially to them later.
- `#72 <https://github.com/hynek/structlog/pull/72>`_
+ - ``structlog.stdlib.ProcessorFormatter`` now accepts *keep_exc_info* and *keep_stack_info* arguments to control what to do with this information on log records.
+ Most likely you want them both to be ``False`` therefore it's the default.
+ `#109 <https://github.com/hynek/structlog/issues/109>`_
+ - ``structlog.stdlib.add_logger_name()`` now works in ``structlog.stdlib.ProcessorFormatter``'s ``foreign_pre_chain``.
+ `#112 <https://github.com/hynek/structlog/issues/112>`_
+ - Clear log record args in ``structlog.stdlib.ProcessorFormatter`` after rendering.
+ This fix is for you if you tried to use it and got ``TypeError: not all arguments converted during string formatting`` exceptions.
+ `#116 <https://github.com/hynek/structlog/issues/116>`_
+ `#117 <https://github.com/hynek/structlog/issues/117>`_
`Full changelog <http://www.structlog.org/en/stable/changelog.html>`_.
@@ -83,6 +173,8 @@ Description: ========================================
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>`_.
+
Keywords: logging,structured,structure,log
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
@@ -96,6 +188,7 @@ 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 :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Python
diff --git a/README.rst b/README.rst
index 23b0576..90a1f78 100644
--- a/README.rst
+++ b/README.rst
@@ -1,33 +1,119 @@
+.. image:: http://www.structlog.org/en/latest/_static/structlog_logo_small.png
+ :alt: structlog Logo
+ :width: 256px
+ :target: http://www.structlog.org/
+
========================================
structlog: Structured Logging for Python
========================================
+.. image:: https://readthedocs.org/projects/structlog/badge/?version=stable
+ :target: https://structlog.readthedocs.io/en/stable/?badge=stable
+ :alt: Documentation Status
+
.. image:: https://travis-ci.org/hynek/structlog.svg?branch=master
:target: https://travis-ci.org/hynek/structlog
-.. image:: https://codecov.io/github/hynek/structlog/coverage.svg?branch=master
- :target: https://codecov.io/github/hynek/structlog?branch=master
+.. image:: https://codecov.io/github/hynek/structlog/branch/master/graph/badge.svg
+ :target: https://codecov.io/github/hynek/structlog
+ :alt: Test Coverage
.. image:: https://www.irccloud.com/invite-svg?channel=%23structlog&hostname=irc.freenode.net&port=6697&ssl=1
:target: https://www.irccloud.com/invite?channel=%23structlog&hostname=irc.freenode.net&port=6697&ssl=1
-``structlog`` makes structured logging in Python easy by *augmenting* your *existing* logger.
-It allows you to split your log entries up into key/value pairs and build them incrementally without annoying boilerplate code.
+.. begin
+
+``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.
+*No* `monkey patching <https://en.wikipedia.org/wiki/Monkey_patch>`_ involved in either case.
+
+
+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)
- out_of_the_box=True effort=0 event='key_value_logging'
- >>> log = log.bind(user='anonymous', some_key=23)
- >>> log = log.bind(user='hynek', another_key=42)
- >>> log.info('user.logged_in', happy=True)
- some_key=23 user='hynek' another_key=42 happy=True event='user.logged_in'
+ 2016-04-20 16:20.13 key_value_logging effort=0 out_of_the_box=True
-.. begin
+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 <http://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 <http://www.structlog.org/en/stable/api.html#module-structlog.processors>`_ for most common tasks coming with ``structlog``:
+
+- Collectors of `call stack information <http://www.structlog.org/en/stable/api.html#structlog.processors.StackInfoRenderer>`_ ("How did this log entry happen?"),
+- …and `exceptions <http://www.structlog.org/en/stable/api.html#structlog.processors.format_exc_info>`_ ("What happened‽").
+- Unicode encoders/decoders.
+- Flexible `timestamping <http://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 <http://www.structlog.org/en/stable/development.html>`_,
+- `JSON <http://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-
+
+
+Project Information
+===================
-It's dual-licensed under `Apache License, version 2 <http://choosealicense.com/licenses/apache/>`_ and `MIT <http://choosealicense.com/licenses/mit/>`_, available from `PyPI <https://pypi.python.org/pypi/structlog/>`_, the source code can be found on `GitHub <https://github.com/hynek/structlog>`_, the documentation at http://www.structlog.org/.
+``structlog`` is dual-licensed under `Apache License, version 2 <http://choosealicense.com/licenses/apache/>`_ and `MIT <http://choosealicense.com/licenses/mit/>`_, available from `PyPI <https://pypi.python.org/pypi/structlog/>`_, the source code can be found on `GitHub <https://github.com/hynek/structlog>`_, the documentation at http://www.structlog.org/.
``structlog`` targets Python 2.7, 3.4 and newer, and PyPy.
diff --git a/conftest.py b/conftest.py
new file mode 100644
index 0000000..26b319c
--- /dev/null
+++ b/conftest.py
@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+# This file is dual licensed under the terms of the Apache License, Version
+# 2.0, and the MIT License. See the LICENSE file in the root of this
+# repository for complete details.
+
+from __future__ import absolute_import, division, print_function
+
+import pytest
+
+from six.moves import cStringIO as StringIO
+
+
+ at pytest.fixture
+def sio():
+ """
+ A StringIO instance.
+ """
+ return StringIO()
+
+
+ at pytest.fixture
+def event_dict():
+ """
+ An example event dictionary with multiple value types w/o the event itself.
+ """
+ class A(object):
+ def __repr__(self):
+ return "<A(\o/)>"
+
+ return {"a": A(), "b": [3, 4], "x": 7, "y": "test", "z": (1, 2)}
diff --git a/docs/_static/structlog_logo.png b/docs/_static/structlog_logo.png
new file mode 100644
index 0000000..c3165fb
Binary files /dev/null and b/docs/_static/structlog_logo.png differ
diff --git a/docs/_static/structlog_logo_small.png b/docs/_static/structlog_logo_small.png
new file mode 100644
index 0000000..381dd90
Binary files /dev/null and b/docs/_static/structlog_logo_small.png differ
diff --git a/docs/api.rst b/docs/api.rst
index f9e73c5..b8f3cba 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -3,6 +3,24 @@
API Reference
=============
+.. note::
+ The examples here use a very simplified configuration using the minimalistic :class:`structlog.processors.KeyValueRenderer` for brewity and to enable doctests.
+ The output is going to be different (nicer!) with default configuration.
+
+
+.. testsetup:: *
+
+ import structlog
+ structlog.configure(
+ processors=[structlog.processors.KeyValueRenderer()],
+ )
+
+.. testcleanup:: *
+
+ import structlog
+ structlog.reset_defaults()
+
+
.. module:: structlog
:mod:`structlog` Package
@@ -56,6 +74,17 @@ API Reference
.. autofunction:: tmp_bind(logger, **tmp_values)
+ >>> from structlog import wrap_logger, PrintLogger
+ >>> from structlog.threadlocal import tmp_bind, wrap_dict
+ >>> logger = wrap_logger(PrintLogger(), context_class=wrap_dict(dict))
+ >>> with tmp_bind(logger, x=5) as tmp_logger:
+ ... logger = logger.bind(y=3)
+ ... tmp_logger.msg("event")
+ x=5 y=3 event='event'
+ >>> logger.msg("event")
+ event='event'
+
+
.. autofunction:: as_immutable
@@ -68,6 +97,32 @@ API Reference
.. autoclass:: JSONRenderer
+ .. doctest::
+
+ >>> from structlog.processors import JSONRenderer
+ >>> JSONRenderer(sort_keys=True)(None, None, {'a': 42, 'b': [1, 2, 3]})
+ '{"a": 42, "b": [1, 2, 3]}'
+
+ Bound objects are attempted to be serialize using a ``__structlog__`` method.
+ If none is defined, ``repr()`` is used:
+
+ .. doctest::
+
+ >>> class C1(object):
+ ... def __structlog__(self):
+ ... return ['C1!']
+ ... def __repr__(self):
+ ... return '__structlog__ took precedence'
+ >>> class C2(object):
+ ... def __repr__(self):
+ ... return 'No __structlog__, so this is used.'
+ >>> from structlog.processors import JSONRenderer
+ >>> JSONRenderer(sort_keys=True)(None, None, {'c1': C1(), 'c2': C2()})
+ '{"c1": ["C1!"], "c2": "No __structlog__, so this is used."}'
+
+ Please note that additionally to strings, you can also return any type the standard library JSON module knows about -- like in this example a list.
+
+
.. autoclass:: KeyValueRenderer
.. doctest::
@@ -123,6 +178,8 @@ API Reference
.. autoclass:: LoggerFactory
:members: __call__
+.. autofunction:: render_to_log_kwargs
+
.. autofunction:: filter_by_level
.. autofunction:: add_log_level
@@ -131,6 +188,9 @@ API Reference
.. autoclass:: PositionalArgumentsFormatter
+.. autoclass:: ProcessorFormatter
+ :members: wrap_for_formatter
+
:mod:`twisted` Module
---------------------
@@ -147,31 +207,6 @@ API Reference
.. autoclass:: JSONRenderer
- .. doctest::
-
- >>> from structlog.processors import JSONRenderer
- >>> JSONRenderer(sort_keys=True)(None, None, {'a': 42, 'b': [1, 2, 3]})
- '{"a": 42, "b": [1, 2, 3]}'
-
- Bound objects are attempted to be serialize using a ``__structlog__`` method.
- If none is defined, ``repr()`` is used:
-
- .. doctest::
-
- >>> class C1(object):
- ... def __structlog__(self):
- ... return ['C1!']
- ... def __repr__(self):
- ... return '__structlog__ took precedence'
- >>> class C2(object):
- ... def __repr__(self):
- ... return 'No __structlog__, so this is used.'
- >>> from structlog.processors import JSONRenderer
- >>> JSONRenderer(sort_keys=True)(None, None, {'c1': C1(), 'c2': C2()})
- '{"c1": ["C1!"], "c2": "No __structlog__, so this is used."}'
-
- Please note that additionally to strings, you can also return any type the standard library JSON module knows about -- like in this example a list.
-
.. autofunction:: plainJSONStdOutLogger
.. autofunction:: JSONLogObserverWrapper
diff --git a/docs/code_examples/flask_/__init__.py b/docs/code_examples/flask_/__init__.py
deleted file mode 100644
index e69de29..0000000
diff --git a/docs/code_examples/flask_/webapp.py b/docs/code_examples/flask_/webapp.py
index 4001282..594c84b 100644
--- a/docs/code_examples/flask_/webapp.py
+++ b/docs/code_examples/flask_/webapp.py
@@ -1,34 +1,42 @@
+import logging
+import sys
import uuid
import flask
import structlog
-from .some_module import some_function
+from some_module import some_function
logger = structlog.get_logger()
app = flask.Flask(__name__)
- at app.route('/login', methods=['POST', 'GET'])
+ at app.route("/login", methods=["POST", "GET"])
def some_route():
log = logger.new(
request_id=str(uuid.uuid4()),
)
# do something
# ...
- log.info('user logged in', user='test-user')
+ log.info("user logged in", user="test-user")
# gives you:
# event='user logged in' request_id='ffcdc44f-b952-4b5f-95e6-0f1f3a9ee5fd' user='test-user'
# ...
some_function()
# ...
+ return "logged in!"
if __name__ == "__main__":
+ logging.basicConfig(
+ format="%(message)s",
+ stream=sys.stdout,
+ level=logging.INFO,
+ )
structlog.configure(
processors=[
structlog.processors.KeyValueRenderer(
- key_order=['event', 'request_id'],
+ key_order=["event", "request_id"],
),
],
context_class=structlog.threadlocal.wrap_dict(dict),
diff --git a/docs/conf.py b/docs/conf.py
index 8b8b3bd..c82d14f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,6 +25,9 @@ except ImportError:
here = os.path.abspath(os.path.dirname(__file__))
+# We want an image in the README and include the README in the docs.
+suppress_warnings = ['image.nonlocal_uri']
+
def read(*parts):
return codecs.open(os.path.join(here, *parts), 'r').read()
diff --git a/docs/custom-wrappers.rst b/docs/custom-wrappers.rst
index 92d0bbe..ca26603 100644
--- a/docs/custom-wrappers.rst
+++ b/docs/custom-wrappers.rst
@@ -1,6 +1,19 @@
Custom Wrappers
===============
+.. testsetup:: *
+
+ import structlog
+ structlog.configure(
+ processors=[structlog.processors.KeyValueRenderer()],
+ )
+
+.. testcleanup:: *
+
+ import structlog
+ structlog.reset_defaults()
+
+
``structlog`` comes with a generic bound logger called :class:`structlog.BoundLogger` that can be used to wrap any logger class you fancy.
... 2431 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/python-structlog.git
More information about the Python-modules-commits
mailing list