Skip to content

Commit

Permalink
Fix syntax
Browse files Browse the repository at this point in the history
  • Loading branch information
@kdeldycke
kdeldycke committed Jan 20, 2025
1 parent b131120 commit 2b15b95
Showing 1 changed file with 67 additions and 68 deletions.
135 changes: 67 additions & 68 deletions docs/logging.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -273,7 +273,7 @@ And see how logs messages are rendered with the custom format, whichever calling
"""
) in result.output
# XXX Reset root logger because ".. click:run::" directives are not isolated and custom config polute the next examples.
# XXX Reset root logger because "click:run" directives are not isolated and custom config polute the next examples.
extra_basic_config()
```

Expand All @@ -300,7 +300,7 @@ If you'd like to target another logger than the default `root` logger, you can p
from click import command, echo
from click_extra import extra_basic_config, verbosity_option
# Create a custom logger in the style of Click Extra, with our own format message.
# Create a custom logger in the style of Click Extra, with our own format message and name.
extra_basic_config(
logger_name="app_logger",
format="{levelname} | {name} | {message}",
Expand Down Expand Up @@ -330,91 +330,90 @@ You can now check that the ``--verbosity`` option influence the log level of you
"""
) in result.output
# XXX Reset root logger because ".. click:run::" directives are not isolated and custom config polute the next examples.
# XXX Reset root logger because "click:run" directives are not isolated and custom config polute the next examples.
extra_basic_config(logger_name="app_logger")
```

````{attention}
If the debug message of our custom logger is printed in the example above, you can right away notice an issue: it is displayed twice.
```{eval-rst}
.. attention::
That's because of a custom name, `app_logger` is created as a sub-logger of the `root` logger. And as such, its [messages are propagated to its parent](https://docs.python.org/3/library/logging.html#logging.Logger.propagate) by default.
If the debug message of our custom logger is printed in the example above as expected, you can right away notice an issue: it is **displayed twice**.
To fix this issue, you have to explicitely disable the upward propagation of messages of `app_logger` to `root`:
Because of a custom name, ``app_logger`` is created as a sub-logger of the ``root`` logger. And as such, its `messages are propagated to its parent <https://docs.python.org/3/library/logging.html#logging.Logger.propagate>`_ by default.
```{eval-rst}
.. click:example::
import logging
from click import command, echo
from click_extra import extra_basic_config, verbosity_option
To fix this issue, you have to explicitely disable the propagation of messages of ``app_logger`` to ``root``:
my_logger = extra_basic_config(
logger_name="app_logger",
format="{levelname} | {name} | {message}",
)
my_logger.propagate = False
.. click:example::
import logging
from click import command, echo
from click_extra import extra_basic_config, verbosity_option
@command
@verbosity_option(default_logger="app_logger")
def awesome_app():
echo("Awesome App started")
logger = logging.getLogger("app_logger")
logger.debug("Awesome App has started.")
my_logger = extra_basic_config(
logger_name="app_logger",
format="{levelname} | {name} | {message}",
)
my_logger.propagate = False
Which get rids of duplicate messages:
@command
@verbosity_option(default_logger="app_logger")
def awesome_app():
echo("Awesome App started")
logger = logging.getLogger("app_logger")
logger.debug("Awesome App has started.")
.. click:run::
from textwrap import dedent
result = invoke(awesome_app, args=["--verbosity", "DEBUG"])
assert dedent("""\
\x1b[34mdebug\x1b[0m: Set <Logger app_logger (DEBUG)> to DEBUG.
Awesome App started
\x1b[34mdebug\x1b[0m | app_logger | Awesome App has started.
\x1b[34mdebug\x1b[0m: Reset <Logger app_logger (DEBUG)> to WARNING.
"""
) in result.output
Which get rids of the duplicate messages:
# XXX Reset root logger because ".. click:run::" directives are not isolated and custom config polute the next examples.
extra_basic_config(logger_name="app_logger")
```
````
.. click:run::
from textwrap import dedent
result = invoke(awesome_app, args=["--verbosity", "DEBUG"])
assert dedent("""\
\x1b[34mdebug\x1b[0m: Set <Logger app_logger (DEBUG)> to DEBUG.
Awesome App started
\x1b[34mdebug\x1b[0m | app_logger | Awesome App has started.
\x1b[34mdebug\x1b[0m: Reset <Logger app_logger (DEBUG)> to WARNING.
"""
) in result.output
````{hint}
As an alternative, you can also pass the default logger object directly to the option:
# XXX Reset root logger because "click:run" directives are not isolated and custom config polute the next examples.
extra_basic_config(logger_name="app_logger")
```

```{eval-rst}
.. click:example::
import logging
from click import command, echo
from click_extra import extra_basic_config, verbosity_option
.. hint::
As an alternative, you can also pass the default logger object directly to the option:
my_logger = extra_basic_config(
logger_name="app_logger",
format="{levelname} | {name} | {message}",
)
my_logger.propagate = False
.. click:example::
import logging
from click import command, echo
from click_extra import extra_basic_config, verbosity_option
@command
@verbosity_option(default_logger=my_logger)
def awesome_app():
echo("Awesome App started")
logger = logging.getLogger("app_logger")
logger.debug("Awesome App has started.")
my_logger = extra_basic_config(
logger_name="app_logger",
format="{levelname} | {name} | {message}",
)
my_logger.propagate = False
.. click:run::
from textwrap import dedent
result = invoke(awesome_app, args=["--verbosity", "DEBUG"])
assert dedent("""\
\x1b[34mdebug\x1b[0m: Set <Logger app_logger (DEBUG)> to DEBUG.
Awesome App started
\x1b[34mdebug\x1b[0m | app_logger | Awesome App has started.
\x1b[34mdebug\x1b[0m: Reset <Logger app_logger (DEBUG)> to WARNING.
"""
) in result.output
@command
@verbosity_option(default_logger=my_logger)
def awesome_app():
echo("Awesome App started")
logger = logging.getLogger("app_logger")
logger.debug("Awesome App has started.")
# XXX Reset root logger because ".. click:run::" directives are not isolated and custom config polute the next examples.
extra_basic_config(logger_name="app_logger")
.. click:run::
from textwrap import dedent
result = invoke(awesome_app, args=["--verbosity", "DEBUG"])
assert dedent("""\
\x1b[34mdebug\x1b[0m: Set <Logger app_logger (DEBUG)> to DEBUG.
Awesome App started
\x1b[34mdebug\x1b[0m | app_logger | Awesome App has started.
\x1b[34mdebug\x1b[0m: Reset <Logger app_logger (DEBUG)> to WARNING.
"""
) in result.output
# XXX Reset root logger because "click:run" directives are not isolated and custom config polute the next examples.
extra_basic_config(logger_name="app_logger")
```
````

### Custom configuration

Expand Down

0 comments on commit 2b15b95

Please sign in to comment.