Skip to content

Commit

Permalink
Improve wording slightly to reduce some ambiguities
Browse files Browse the repository at this point in the history
  • Loading branch information
Delgan committed Dec 9, 2018
1 parent 5b53209 commit 81c1839
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 17 deletions.
23 changes: 13 additions & 10 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
</p>
<p align="center">
<a href="https://pypi.python.org/pypi/loguru"><img alt="Pypi version" src="https://img.shields.io/pypi/v/loguru.svg"></a>
<a href="https://travis-ci.org/Delgan/loguru"><img alt="Build status" src="https://img.shields.io/travis/Delgan/loguru.svg"></a>
<a href="https://loguru.readthedocs.io/en/stable/index.html"><img alt="Documentation" src="https://img.shields.io/readthedocs/loguru.svg"></a>
<a href="https://travis-ci.org/Delgan/loguru"><img alt="Build status" src="https://img.shields.io/travis/Delgan/loguru.svg"></a>
<a href="https://coveralls.io/github/Delgan/loguru"><img alt="Coverage" src="https://img.shields.io/coveralls/Delgan/loguru.svg"></a>
<a href="https://www.codacy.com/app/delgan-py/loguru/dashboard"><img alt="Code quality" src="https://img.shields.io/codacy/grade/4d97edb1bb734a0d9a684a700a84f555.svg"></a>
<a href="https://github.com/Delgan/loguru/blob/master/.travis.yml"><img alt="Python versions" src="https://img.shields.io/badge/python-3.6%20%7C%203.7-blue.svg"></a>
Expand Down Expand Up @@ -201,7 +201,7 @@ Pretty logging with colors
Asynchronous, Thread-safe, Multiprocess-safe
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

All sinks added to the |logger|_ are thread-safe by default. If you want async logging or need to use the same sink through different multiprocesses, you just have to ``enqueue`` the messages.
All sinks added to the |logger|_ are thread-safe by default. They are not multiprocess-safe, but you can ``enqueue`` the messages to ensure logs integrity. This same argument can also be used if you want async logging.

::

Expand Down Expand Up @@ -281,9 +281,9 @@ Sometime you would like to log verbose information without performance penalty i
logger.opt(lazy=True).debug("If sink level <= DEBUG: {x}", x=lambda: expensive_function(2**64))

# By the way, "opt()" serves many usages
logger.opt(exception=True).info("Exception with an "INFO" level")
logger.opt(exception=True).info("Error stacktrace added to the log message")
logger.opt(ansi=True).info("Per message <blue>colors</blue>")
logger.opt(record=True).info("Log record attributes (eg. {record[thread].id})")
logger.opt(record=True).info("Display values from the record (eg. {record[thread].id})")
logger.opt(raw=True).info("Bypass sink formatting\n")
logger.opt(depth=1).info("Use parent stack context (useful within wrapped functions)")

Expand Down Expand Up @@ -312,16 +312,19 @@ The standard logging is bloated with arguments like ``datefmt`` or ``msecs``, ``
Suitable for scripts and libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using the logger in your scripts is easy, and you can |configure|_ it at start. To use `Loguru` from inside a libary, remember to never call |start|_ but use |disable|_ instead so logging functions become no-op. If an user want to see your library's logs, he can |enable|_ it again.
Using the logger in your scripts is easy, and you can |configure|_ it at start. To use `Loguru` from inside a libary, remember to never call |start|_ but use |disable|_ instead so logging functions become no-op. If a developer wishes to see your library's logs, he can |enable|_ it again.

::

# For scripts
my_logging_config = dict(
handlers=[{'sink': sys.stdout, 'colorize': False, format="{time} - {message}"}],
extra={"user": "someone"}
)
logger.configure(**my_logging_config)
config = {
"handlers": [
{"sink": sys.stdout, format="{time} - {message}"},
{"sink": "file.log", "serialize": True},
],
"extra": {"user": "someone"}
}
logger.configure(**config)

# For libraries
logger.disable("my_library")
Expand Down
16 changes: 9 additions & 7 deletions loguru/_logger.py
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@ def start(
catch : |bool|, optional
Whether or not errors occuring while sink handles logs messages should be caught or not.
If ``True``, an exception message is displayed on |sys.stderr| but the exception is not
propagated to the caller, preventing sink from stopping working.
propagated to the caller, preventing your app to crash.
**kwargs
Additional parameters that will be passed to the sink while creating it or while
logging messages (the exact behavior depends on the sink type).
Expand Down Expand Up @@ -276,11 +276,13 @@ def start(
.. rubric:: The record dict
The record is just a Python dict, accessible from sinks by ``message.record``, and usable
for formatting as ``"{key}"``. Some record's values are objects with two or more attibutes,
those can be formatted with ``"{key.attr}"`` (``"{key}"`` would display one by default).
Formatting directives like ``"{key: >3}"`` also works and is specially useful for time (see
bellow).
The record is just a Python dict, accessible from sinks by ``message.record``. It contains
all contextual information of the logging call (time, function, file, line, level, etc.).
Each of its key can be used in the handler's ``format`` so the corresponding value is
properly displayed in the logged message (eg. ``"{level}"`` -> ``"INFO"``). Some record's
values are objects with two or more attibutes, those can be formatted with ``"{key.attr}"``
(``"{key}"`` would display one by default). Formatting directives like ``"{key: >3}"`` also
works and is particularly useful for time (see bellow).
+------------+---------------------------------+----------------------------+
| Key | Description | Attributes |
Expand All @@ -292,7 +294,7 @@ def start(
| | ``None`` otherwise | ``traceback`` |
+------------+---------------------------------+----------------------------+
| extra | The dict of attributes | None |
| | bound by the user | |
| | bound by the user (see |bind|) | |
+------------+---------------------------------+----------------------------+
| file | The file where the logging call | ``name`` (default), |
| | was made | ``path`` |
Expand Down

0 comments on commit 81c1839

Please sign in to comment.