Skip to content

Commit

Permalink
Unindent docstring >>> to avoid ugly PyPI render
Browse files Browse the repository at this point in the history
If doctest prompts are indented, then RST thinks that they are inside of
a <blockquote>, which PyPI now renders with a thick ugly line alongside.
  • Loading branch information
brandon-rhodes committed May 3, 2024
1 parent d2121d6 commit cc2a316
Showing 1 changed file with 54 additions and 54 deletions.
108 changes: 54 additions & 54 deletions logging_tree/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,31 +7,31 @@
The simplest way to use this package is to call ``printout()`` to see
the loggers, filters, and handlers that your application has configured:
>>> import logging
>>> a = logging.getLogger('a')
>>> b = logging.getLogger('a.b').setLevel(logging.DEBUG)
>>> c = logging.getLogger('x.c')
>>> import sys
>>> h = logging.StreamHandler(sys.stdout)
>>> logging.getLogger().addHandler(h)
>>> from logging_tree import printout
>>> printout()
<--""
Level WARNING
Handler Stream <sys.stdout>
>>> import logging
>>> a = logging.getLogger('a')
>>> b = logging.getLogger('a.b').setLevel(logging.DEBUG)
>>> c = logging.getLogger('x.c')
>>> import sys
>>> h = logging.StreamHandler(sys.stdout)
>>> logging.getLogger().addHandler(h)
>>> from logging_tree import printout
>>> printout()
<--""
Level WARNING
Handler Stream <sys.stdout>
|
o<--"a"
| Level NOTSET so inherits level WARNING
| |
| o<--"a.b"
| Level DEBUG
|
o<--[x]
|
o<--"a"
| Level NOTSET so inherits level WARNING
| |
| o<--"a.b"
| Level DEBUG
|
o<--[x]
|
o<--"x.c"
Level NOTSET so inherits level WARNING
o<--"x.c"
Level NOTSET so inherits level WARNING
If you instead want to write the tree diagram to a file, stream, or
other file-like object, use::
Expand All @@ -54,56 +54,56 @@
directly to the root, but also messages that propagate up from a child
like ``a.b``.
>>> logging.getLogger().warning('message sent to the root')
message sent to the root
>>> logging.getLogger('a.b').warning('message sent to a.b')
message sent to a.b
>>> logging.getLogger().warning('message sent to the root')
message sent to the root
>>> logging.getLogger('a.b').warning('message sent to a.b')
message sent to a.b
But messages are *not* subjected to filtering as they propagate. So a
debug-level message, which our root node will discard because the root's
level is set to ``WARNING``, will be accepted by the ``a.b`` node and
will be allowed to propagate up to the root handler.
>>> logging.getLogger().debug('this message is ignored')
>>> logging.getLogger('a.b').debug('but this message prints!')
but this message prints!
>>> logging.getLogger().debug('this message is ignored')
>>> logging.getLogger('a.b').debug('but this message prints!')
but this message prints!
If both the root node and ``a.b`` have a handler attached, then a
message accepted by ``a.b`` will be printed twice, once by its own node,
and then a second time when the message propagates up to the root.
>>> logging.getLogger('a.b').addHandler(h)
>>> logging.getLogger('a.b').warning('this message prints twice')
this message prints twice
this message prints twice
>>> logging.getLogger('a.b').addHandler(h)
>>> logging.getLogger('a.b').warning('this message prints twice')
this message prints twice
this message prints twice
But you can stop a node from propagating messages to its parent by
setting its ``propagate`` attribute to ``False``.
>>> logging.getLogger('a.b').propagate = False
>>> logging.getLogger('a.b').warning('does not propagate')
does not propagate
>>> logging.getLogger('a.b').propagate = False
>>> logging.getLogger('a.b').warning('does not propagate')
does not propagate
The logging tree will indicate that propagate is turned off by no longer
drawing the arrow ``<--`` that points from the node to its parent:
>>> printout()
<--""
Level WARNING
Handler Stream <sys.stdout>
|
o<--"a"
| Level NOTSET so inherits level WARNING
| |
| o "a.b"
| Level DEBUG
| Propagate OFF
| Handler Stream <sys.stdout>
>>> printout()
<--""
Level WARNING
Handler Stream <sys.stdout>
|
o<--"a"
| Level NOTSET so inherits level WARNING
| |
| o "a.b"
| Level DEBUG
| Propagate OFF
| Handler Stream <sys.stdout>
|
o<--[x]
|
o<--[x]
|
o<--"x.c"
Level NOTSET so inherits level WARNING
o<--"x.c"
Level NOTSET so inherits level WARNING
You can turn propagate back on again by setting the attribute ``True``.
Expand Down

0 comments on commit cc2a316

Please sign in to comment.