Add structlog.stdlib.recreate_defaults

CHANGELOG.md

@@ -50,6 +50,9 @@ So please make sure to **always** properly configure your applications.
 - Added structured logging of tracebacks via the `structlog.tracebacks` module,
   and most notably the `structlog.tracebacks.ExceptionDictTransformer` which can be used with the new `structlog.processors.ExceptionRenderer` to render JSON tracebacks.
   [#407](https://github.com/hynek/structlog/pull/407)
+- `structlog.stdlib.recreate_defaults(log_level=logging.NOTSET)` that recreates `structlog`'s defaults on top of standard library's `logging`.
+  It optionally also configures `logging` to log to standard out at the passed log level.
+  [#428](https://github.com/hynek/structlog/pull/428)
 
 
 ### Changed

docs/api.rst

@@ -270,6 +270,8 @@ API Reference
 
 .. automodule:: structlog.stdlib
 
+.. autofunction:: recreate_defaults
+
 .. autofunction:: get_logger
 
 .. autoclass:: BoundLogger

docs/getting-started.rst

@@ -62,10 +62,13 @@ Using the defaults, as above, is equivalent to::
    log = structlog.get_logger()
 
 .. note::
-   For brevity and to enable doctests, all further examples in ``structlog``'s documentation use the more simplistic `structlog.processors.KeyValueRenderer()` without timestamps.
 
-   `structlog.make_filtering_bound_logger()` (re-)uses `logging`'s log levels, but doesn't use it at all.
-   The exposed API is `FilteringBoundLogger`.
+   - `structlog.stdlib.recreate_defaults()` allows you to switch ``structlog`` to using standard library's `logging` module for output for better interoperability with just one function call.
+
+   - `structlog.make_filtering_bound_logger()` (re-)uses `logging`'s log levels, but doesn't use it at all.
+     The exposed API is `FilteringBoundLogger`.
+
+   - For brevity and to enable doctests, all further examples in ``structlog``'s documentation use the more simplistic `structlog.processors.KeyValueRenderer()` without timestamps.
 
 There you go, structured logging!
 However, this alone wouldn't warrant its own package.

docs/standard-library.rst

@@ -7,6 +7,10 @@ In other words, you should be able to replace your call to `logging.getLogger` b
 If you run into incompatibilities, it is a *bug* so please take the time to `report it <https://github.com/hynek/structlog/issues>`_!
 If you're a heavy `logging` user, your `help <https://github.com/hynek/structlog/issues?q=is%3Aopen+is%3Aissue+label%3Astdlib>`_ to ensure a better compatibility would be highly appreciated!
 
+.. note::
+
+   The quickest way to get started with ``structlog`` and `logging` is `structlog.stdlib.recreate_defaults()` that will recreate the default configuration on top of `logging` and optionally configure `logging` for you.
+
 
 Just Enough ``logging``
 -----------------------

src/structlog/_config.py

@@ -30,9 +30,10 @@
 
 
 """
-.. note::
+   Any changes to these defaults must be reflected in:
 
-   Any changes to these defaults must be reflected in `getting-started`.
+   - `getting-started`.
+   - structlog.stdlib.recreate_defaults()'s docstring.
 """
 _BUILTIN_DEFAULT_PROCESSORS: Sequence[Processor] = [
     add_log_level,