Loguru

https://loguru.readthedocs.io/en/stable
Admin
Loguru is a Python logging library that makes logging enjoyable and painless by providing a simple...
Tokens:58,134
Snippets:546
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Loguru

Source: https://loguru.readthedocs.io/en/stable/overview.html

Install Loguru using pip.

```bash
pip install loguru

```

--------------------------------

### Installing loguru-mypy

Source: https://loguru.readthedocs.io/en/stable/api/type_hints.html

Instructions for installing the `loguru-mypy` library, which provides additional type checking capabilities for Loguru.

```bash
pip install loguru-mypy

```

--------------------------------

### Install Pre-commit Hooks

Source: https://loguru.readthedocs.io/en/stable/project/contributing.html

Install pre-commit hooks to automatically check code quality before commits.

```bash
$ pre-commit install --install-hooks
```

--------------------------------

### Loguru start method (Deprecated)

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Deprecated method for adding a handler. Use `add()` instead. It will be removed in Loguru 1.0.0.

```python
def start(self, *args, **kwargs):
        """Add a handler sending log messages to a sink adequately configured.

        Deprecated function, use |add| instead.

        Warnings
        --------
        .. deprecated:: 0.2.2
          ``start()`` will be removed in Loguru 1.0.0, it is replaced by ``add()`` which is a less
          confusing name.
        """
        warnings.warn(
            "The 'start()' method is deprecated, please use 'add()' instead",
            DeprecationWarning,
            stacklevel=2,
        )
        return self.add(*args, **kwargs)
```

--------------------------------

### Install Loguru in Development Mode

Source: https://loguru.readthedocs.io/en/stable/project/contributing.html

Install Loguru using pip in editable mode, along with development dependencies.

```bash
$ pip install -e ".[dev]"
```

--------------------------------

### Logger Start and Stop Type Hints

Source: https://loguru.readthedocs.io/en/stable/api/type_hints_source.html

Specifies the type hints for the 'start' and 'stop' methods of the Logger object. 'start' returns an integer, while 'stop' returns None.

```python
def start(self, *args: Any, **kwargs: Any) -> int: ...
def stop(self, *args: Any, **kwargs: Any) -> None: ...
```

--------------------------------

### Basic Type Hinting Example

Source: https://loguru.readthedocs.io/en/stable/api/type_hints.html

Demonstrates how to use Loguru's type hints for sinks and filters. Requires `from __future__ import annotations` for postponed evaluation of annotations in Python 3.7+.

```python
from __future__ import annotations

import loguru
from loguru import logger

def good_sink(message: loguru.Message):
    print("My name is", message.record["name"])

def bad_filter(record: loguru.Record):
    return record["invalid"]

logger.add(good_sink, filter=bad_filter)

```

--------------------------------

### Loguru Logger Parse Method Example

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Demonstrates how to parse a log file using a regex pattern and extract log entries as dictionaries. Shows basic parsing and casting values to specific types.

```python
>>> reg = r"(?P<lvl>[0-9]+): (?P<msg>.*)"    # If log format is "{level.no} - {message}"
>>> for e in logger.parse("file.log", reg):  # A file line could be "10 - A debug message"
...     print(e)                             # => {'lvl': '10', 'msg': 'A debug message'}

>>> caster = dict(lvl=int)                   # Parse 'lvl' key as an integer
>>> for e in logger.parse("file.log", reg, cast=caster):
...     print(e)                             # => {'lvl': 10, 'msg': 'A debug message'}
```

```python
>>> def cast(groups):
...     if "date" in groups:
...         groups["date"] = datetime.strptime(groups["date"], "%Y-%m-%d %H:%M:%S")
...
>>> with open("file.log") as file:
...     for log in logger.parse(file, reg, cast=cast):
...         print(log["date"], log["something_else"])
```

--------------------------------

### Get and Print Logging Level Information

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Demonstrates how to retrieve information about an existing logging level and print its details. This is useful for inspecting predefined levels.

```python
>>> level = logger.level("ERROR")
>>> print(level)
Level(name='ERROR', no=40, color='<red><bold>', icon='❌')
```

--------------------------------

### Example usage of capture_logs with unittest

Source: https://loguru.readthedocs.io/en/stable/resources/migration.html

Demonstrates how to use the `capture_logs` context manager to test logged messages in unittest. It includes tests for both successful and error conditions.

```python
def do_something(val):
    if val < 0:
        logger.error("Invalid value")
        return 0
    return val * 2


class TestDoSomething(unittest.TestCase):
    def test_do_something_good(self):
        with capture_logs() as output:
            do_something(1)
        self.assertEqual(output, [])

    def test_do_something_bad(self):
        with capture_logs() as output:
            do_something(-1)
        self.assertEqual(len(output), 1)
        message = output[0]
        self.assertIn("Invalid value", message)
        self.assertEqual(message.record["level"].name, "ERROR")

```

--------------------------------

### Windows Multiprocessing with Loguru

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Example for Windows demonstrating Loguru usage in a child process. Requires explicit passing of the logger object and removing non-picklable default sinks. `enqueue=True` is crucial.

```python
# Windows implementation
import multiprocessing
from loguru import logger

def my_process(logger_):
    logger_.info("Executing function in child process")
    logger_.complete()

if __name__ == "__main__":
    logger.remove()  # Default "sys.stderr" sink is not picklable
    logger.add("file.log", enqueue=True)

    process = multiprocessing.Process(target=my_process, args=(logger, ))
    process.start()
    process.join()

    logger.info("Done")

```

--------------------------------

### Formatted Exception Output with `stackprinter`

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Example of how exceptions are formatted when using the `stackprinter` library with a custom Loguru formatter.

```text
2019-11-15T10:46:18.059964+0100 Oups...
File foo.py, line 17, in inverse
    15   def inverse(x):
    16       try:
--> 17           1 / x
    18       except ZeroDivisionError:
    ..................................................
    x = 0
    ..................................................

ZeroDivisionError: division by zero
```

--------------------------------

### Mypy Output for Type Hinting Example

Source: https://loguru.readthedocs.io/en/stable/api/type_hints.html

Shows the typical output from the `mypy` type checker when an error is found in code using Loguru's type hints.

```bash
$ mypy test.py
test.py:8: error: TypedDict "Record" has no key 'invalid'
Found 1 error in 1 file (checked 1 source file)

```

--------------------------------

### Loguru Filter Configuration: String-Based Filtering

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Illustrates the setup for string-based filtering in Loguru, where logs are filtered based on a module name prefix.

```python
parent = filter + "."
length = len(parent)
filter_func = functools.partial(_filters.filter_by_name, parent=parent, length=length)
```

--------------------------------

### Linux Multiprocessing with Loguru

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Example demonstrating Loguru usage in a child process on Linux using `multiprocessing.Process`. The `enqueue=True` argument is recommended for avoiding concurrent access to sinks.

```python
# Linux implementation
import multiprocessing
from loguru import logger

def my_process():
    logger.info("Executing function in child process")
    logger.complete()

if __name__ == "__main__":
    logger.add("file.log", enqueue=True)

    process = multiprocessing.Process(target=my_process)
    process.start()
    process.join()

    logger.info("Done")

```

--------------------------------

### Create and Checkout New Branch

Source: https://loguru.readthedocs.io/en/stable/project/contributing.html

Create a new branch for your bug fix or feature implementation, starting from the master branch.

```bash
$ git checkout master
$ git branch fix_bug
$ git checkout fix_bug
```

--------------------------------

### Set Loguru Formatting via Environment Variables

Source: https://loguru.readthedocs.io/en/stable/overview.html

Customize Loguru's default format and colors using environment variables. This example shows Linux/OSX and Windows syntax.

```bash
# Linux / OSX
export LOGURU_FORMAT="{time} | <lvl>{message}</lvl>"

# Windows
setx LOGURU_DEBUG_COLOR "<green>"

```

--------------------------------

### Example pytest test function with caplog

Source: https://loguru.readthedocs.io/en/stable/resources/migration.html

A basic pytest test function that uses the `caplog` fixture to check for logged warning messages. This example will fail without the Loguru-compatible `caplog` fixture override.

```python
from loguru import logger

def some_func(a, b):
    if a < 0:
        logger.warning("Oh no!")
    return a + b

def test_some_func(caplog):
    assert some_func(-1, 3) == 2
    assert "Oh no!" in caplog.text

```

--------------------------------

### Log message with Warning severity

Source: https://loguru.readthedocs.io/en/stable/resources/migration.html

Example of logging a warning message using Loguru. This shows how to log messages with different severity levels.

```python
logger.warning("Danger!")
```

--------------------------------

### Patching Log Records from Network Data

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Provides an example of patching log records received from a network source, deserializing them, and then logging them with the patched information.

```python
>>> def recv_record_from_network(pipe):
...     record = pickle.loads(pipe.read())
...     level, message = record["level"], record["message"]
...     logger.patch(lambda r: r.update(record)).log(level, message)
```

--------------------------------

### Illustrative Example of Closed File Error

Source: https://loguru.readthedocs.io/en/stable/resources/troubleshooting.html

This example demonstrates how a logger can inadvertently be configured with a wrapped stream that is later closed, leading to the 'ValueError'. It uses a context manager to redirect stdout and shows the error occurring when attempting to log after the stream is closed.

```python
from contextlib import contextmanager
import sys
import io
from loguru import logger


@contextmanager
def redirect_stdout(new_target):
    old_target, sys.stdout = sys.stdout, new_target
    try:
        yield new_target
    finally:
        sys.stdout = old_target
        new_target.close()


if __name__ == "__main__":
    logger.remove()
    f = io.StringIO()

    with redirect_stdout(f):
        logger.add(sys.stdout)  # Logger is inadvertently configured with wrapped stream.
        logger.info("Hello")
        output = f.getvalue()

    print(f"Captured output: {output}")

    # ValueError: I/O operation on closed file.
    logger.info("World")

```

--------------------------------

### Log Exceptions with Traceback

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Log exceptions using `logger.exception()` to automatically include the traceback. This example demonstrates logging a `ZeroDivisionError`.

```python
def inverse(x):
    try:
        1 / x
    except ZeroDivisionError:
        logger.exception("Oups...")

if __name__ == "__main__":
    inverse(0)
```

--------------------------------

### Format Log Messages with Call Stack

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

This example demonstrates a custom formatter that prefixes log messages with the full call stack. It filters out Loguru's internal frames for cleaner output.

```python
import traceback
from itertools import takewhile

def tracing_formatter(record):
    # Filter out frames coming from Loguru internals
    frames = takewhile(lambda f: "/loguru/" not in f.filename, traceback.extract_stack())
    stack = " > ".join("{}:{}:{}".format(f.filename, f.name, f.lineno) for f in frames)
    record["extra"]["stack"] = stack
    return "{level} | {extra[stack]} - {message}\n{exception}"

def foo():
    logger.info("Deep call")

def bar():
    foo()

logger.remove()
logger.add(sys.stderr, format=tracing_formatter)

bar()
# Output: "INFO | script.py:<module>:23 > script.py:bar:18 > script.py:foo:15 - Deep call"

```

--------------------------------

### Integrate Loguru with tqdm Progress Bars

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Use `tqdm.write()` to log messages within `tqdm` iterations without disturbing the progress bar. This example removes default handlers and adds a handler that writes to `tqdm.write()`.

```python
import time

from loguru import logger
from tqdm import tqdm

logger.remove()
logger.add(lambda msg: tqdm.write(msg, end=""), colorize=True)

logger.info("Initializing")

for x in tqdm(range(100)):
    logger.info("Iterating #{}", x)
    time.sleep(0.1)
```

--------------------------------

### Attaching Sinks to Named Loggers

Source: https://loguru.readthedocs.io/en/stable/resources/migration.html

This example demonstrates how to attach separate log files to specific named loggers using lambda functions as filters. The logger.bind() method is used to create loggers associated with particular names.

```python
# Only write messages from "a" logger
logger.add("a.log", filter=lambda record: record["extra"].get("name") == "a")
# Only write messages from "b" logger
logger.add("b.log", filter=lambda record: record["extra"].get("name") == "b")

logger_a = logger.bind(name="a")
logger_b = logger.bind(name="b")

logger_a.info("Message A")
logger_b.info("Message B")
```

--------------------------------

### Configure Loguru Logger Globally

Source: https://loguru.readthedocs.io/en/stable/api/logger.html

The `logger.configure()` method allows for comprehensive global setup of Loguru. It can define handlers, levels, default extra data, a message patcher function, and control the activation state of specific loggers. This is the recommended way to set up shared default values.

```python
>>> logger.configure(
...     handlers=[
...         dict(sink=sys.stderr, format="[{time}] {message}"),
...         dict(sink="file.log", enqueue=True, serialize=True),
...     ],
...     levels=[dict(name="NEW", no=13, icon="¤", color="")],
...     extra={"common_to_all": "default"},
...     patcher=lambda record: record["extra"].update(some_value=42),
...     activation=[("my_module.secret", False), ("another_library.module", True)],
... )
[1, 2]
```

```python
>>> # Set a default "extra" dict to logger across all modules, without "bind()"
>>> extra = {"context": "foo"}
>>> logger.configure(extra=extra)
>>> logger.add(sys.stderr, format="{extra[context]} - {message}")
>>> logger.info("Context without bind")
>>> # => "foo - Context without bind"
>>> logger.bind(context="bar").info("Suppress global context")
>>> # => "bar - Suppress global context"
```

--------------------------------

### Basic Loguru Formatting with Arguments

Source: https://loguru.readthedocs.io/en/stable/resources/troubleshooting.html

Demonstrates how Loguru integrates positional or keyword arguments into the log message using a format string.

```python
logger.info("My name is {name}", name="John")
```

--------------------------------

### Pytest Example of Closed File Error

Source: https://loguru.readthedocs.io/en/stable/resources/troubleshooting.html

This example shows how the 'ValueError' can occur in a Pytest environment when using the 'capsys' fixture. The 'sys.stderr' is mocked and closed by Pytest after a test, but the Loguru handler is not removed, leading to an error in a subsequent test.

```python
import sys
from loguru import logger

logger.remove()

def test_1(capsys):
    # Here, "sys.stderr" is actually a mock object due to usage of "capsys" fixture.
    logger.add(sys.stderr, catch=False)
    logger.info("Test 1")


def test_2():
    # After execution of the previous test, the mocked "sys.stderr" was closed by Pytest.
    # However, the handler was not removed from the Loguru logger. It'll raise a "ValueError" here.
    logger.info("Test 2", catch=False)

```

--------------------------------

### Standard Sink Initialization

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Initializes a sink using a standard `logging.Handler`.

```python
elif isinstance(sink, logging.Handler):
            name = repr(sink)

            if colorize is None:
                colorize = False

            wrapped_sink = StandardSink(sink)
            encoding = getattr(sink, "encoding", None)
            terminator = ""
            exception_prefix = "\n"
```

--------------------------------

### Set File Permissions with Custom Opener

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Illustrates how to set specific file permissions for log files using the `opener` argument. This allows fine-grained control over file access, such as read/write only for the owner.

```python
import os

def opener(file, flags):
    return os.open(file, flags, 0o600)  # read/write by owner only

logger.add("foo.log", rotation="100 kB", opener=opener)

```

--------------------------------

### Example UnicodeEncodeError in Python

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Demonstrates a typical UnicodeEncodeError when trying to print a non-ASCII character to a terminal with an incompatible encoding.

```python
print("天")
# UnicodeEncodeError: 'charmap' codec can't encode character '\u5929' in position 0: character maps to <undefined>
```

--------------------------------

### File Sink Initialization

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Initializes a file sink, handling path, colorization, encoding, and terminator.

```python
if isinstance(sink, (str, PathLike)):
            path = sink
            name = "'" + path + "'"

            if colorize is None:
                colorize = False

            wrapped_sink = FileSink(path, **kwargs)
            kwargs = {}
            encoding = wrapped_sink.encoding
            terminator = "\n"
            exception_prefix = ""
```

--------------------------------

### Activate Virtual Environment

Source: https://loguru.readthedocs.io/en/stable/project/contributing.html

Create and activate a virtual environment for development. This isolates project dependencies.

```bash
$ python -m venv env
$ source env/bin/activate
```

--------------------------------

### Log message with Debug severity

Source: https://loguru.readthedocs.io/en/stable/resources/migration.html

Example of logging a debug message using Loguru. This demonstrates the basic usage of the logger object.

```python
logger.debug("Dev message")
```

--------------------------------

### Clone Loguru Repository

Source: https://loguru.readthedocs.io/en/stable/project/contributing.html

Clone the Loguru project repository locally to begin development.

```bash
$ git clone git@github.com:your_name_here/loguru.git
$ cd loguru
```

--------------------------------

### level method overloads

Source: https://loguru.readthedocs.io/en/stable/api/type_hints_source.html

The `level` method can be used to get a level object by name or to define a new level with specific properties.

```APIDOC
## level method overloads

### Description

This method can be used to either retrieve a `Level` object by its name or to define a new logging level with a specified name, number, color, and icon.

### Method Signatures

**Overload 1 (Get Level):**
```python
def level(self, name: str) -> Level: ...
```

**Overload 2 (Define Level):**
```python
def level(
    self,
    name: str,
    no: int = ..., 
    color: Optional[str] = ..., 
    icon: Optional[str] = ...
) -> Level: ...
```

**Overload 3 (Define Level with Optional `no`):**
```python
def level(
    self,
    name: str,
    no: Optional[int] = ..., 
    color: Optional[str] = ..., 
    icon: Optional[str] = ...,
) -> Level: ...
```

### Parameters

*   **name**: The name of the logging level.
*   **no**: The numerical value of the logging level.
*   **color**: The color associated with the logging level.
*   **icon**: An icon associated with the logging level.

### Returns

A `Level` object.
```

--------------------------------

### configure method

Source: https://loguru.readthedocs.io/en/stable/api/type_hints_source.html

The `configure` method allows for comprehensive configuration of the logger, including handlers, levels, and patchers.

```APIDOC
## configure method

### Description

Configures the logger with a set of handlers, levels, and other settings. This method allows for a centralized way to set up the logger's behavior.

### Method

`configure`

### Parameters

*   **handlers** (Optional[Sequence[HandlerConfig]]): A sequence of handler configurations.
*   **levels** (Optional[Sequence[LevelConfig]]): A sequence of level configurations.
*   **extra** (Optional[Dict[Any, Any]]): Extra data to be added to the logger's context.
*   **patcher** (Optional[PatcherFunction]): A patcher function to modify log records.
*   **activation** (Optional[Sequence[ActivationConfig]]): A sequence of activation configurations for handlers.

### Returns

A list of integer IDs for the configured handlers.
```

--------------------------------

### Stream Sink Initialization

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Initializes a stream sink, determining colorization based on the stream and wrapping it if necessary.

```python
elif hasattr(sink, "write") and callable(sink.write):
            name = getattr(sink, "name", None) or repr(sink)

            if colorize is None:
                colorize = _colorama.should_colorize(sink)

            if colorize is True and _colorama.should_wrap(sink):
                stream = _colorama.wrap(sink)
            else:
                stream = sink

            wrapped_sink = StreamSink(stream)
            encoding = getattr(sink, "encoding", None)
            terminator = "\n"
            exception_prefix = ""
```

--------------------------------

### Access Log Record Context with opt()

Source: https://loguru.readthedocs.io/en/stable/api/logger.html

Enable access to the record dictionary for message formatting by setting `opt(record=True)`. This allows using placeholders like `{record[key]}` in your log messages.

```python
logger.opt(record=True).info("Current line is: {record[line]}")
```

--------------------------------

### Test Loguru Logs with Logot

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Use this snippet to test Loguru log messages within your pytest test functions. Ensure logot is installed and configured.

```python
from logot import Logot, logged

def test_something(logot: Logot) -> None:
    do_something()
    logot.assert_logged(logged.info("Something was done"))

```

--------------------------------

### Replace exc_info=True with opt(exception=True)

Source: https://loguru.readthedocs.io/en/stable/resources/migration.html

To include stack traces in log messages, use `logger.opt(exception=True)` instead of the `exc_info=True` argument.

```python
logger.debug("Debug error:", exc_info=True)  # Standard logging
logger.opt(exception=True).debug("Debug error:")  # Loguru
```

--------------------------------

### Catching Exceptions with Decorator

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Use the @logger.catch decorator to automatically catch and log exceptions raised within a function. The example shows how a ZeroDivisionError is caught and logged.

```python
>>> @logger.catch
... def f(x):
...     100 / x
...
>>> def g():
...     f(10)
...     f(0)
...
>>> g()
ERROR - An error has been caught in function 'g', process 'Main' (367), thread 'ch1' (1398):
Traceback (most recent call last):
  File "program.py", line 12, in <module>
    g()
    └ <function g at 0x7f225fe2bc80>
> File "program.py", line 10, in g
    f(0)
    └ <function f at 0x7f225fe2b9d8>
  File "program.py", line 6, in f
    100 / x
          └ 0
ZeroDivisionError: division by zero
```

--------------------------------

### Set Up Apprise Notifications for Loguru Errors

Source: https://loguru.readthedocs.io/en/stable/overview.html

Integrate the `apprise` library with Loguru to send notifications (e.g., Discord) when errors occur. Avoids recursive calls from apprise itself.

```python
import apprise

# Define the configuration constants.
WEBHOOK_ID = "123456790"
WEBHOOK_TOKEN = "abc123def456"

# Prepare the object to send Discord notifications.
notifier = apprise.Apprise()
notifier.add(f"discord://{WEBHOOK_ID}/{WEBHOOK_TOKEN}")

# Install a handler to be alerted on each error.
# You can filter out logs from "apprise" itself to avoid recursive calls.
logger.add(notifier.notify, level="ERROR", filter={"apprise": False})

```

--------------------------------

### Contextual Logging with Context Manager

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Shows how to use a context manager to bind attributes to the context-local `extra` dict. Values are unique to each thread and async task and are restored upon exiting the context.

```python
>>> logger.add(sys.stderr, format="{message} | {extra}")
1
>>> def task():
...     logger.info("Processing!")
...
>>> with logger.contextualize(task_id=123):
...     task()
...
Processing! | {'task_id': 123}
>>> logger.info("Done.")
Done. | {}
```

--------------------------------

### Preserve opt() parameter for module-wide coloring

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Set logger.opt(colors=True) once at the module's start to color all subsequent messages. Note that chaining opt() calls resets options.

```python
logger = logger.opt(colors=True)

logger.info("It <green>works</>")

```

--------------------------------

### Securely Sending and Receiving Log Messages with Pickle

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Demonstrates how to use pickle for serializing log messages and HMAC for ensuring data integrity during transmission. Ensure the data source is trusted or signed before deserialization to prevent malicious code execution.

```python
import hashlib
import hmac
import pickle

def client(connection):
    data = pickle.dumps("Log message")
    digest =  hmac.digest(b"secret-shared-key", data, hashlib.sha1)
    connection.send(digest + b" " + data)

def server(connection):
    expected_digest, data = connection.read().split(b" ", 1)
    data_digest = hmac.digest(b"secret-shared-key", data, hashlib.sha1)
    if not hmac.compare_digest(data_digest, expected_digest):
        print("Integrity error")
    else:
        message = pickle.loads(data)
        logger.info(message)
```

--------------------------------

### Log Message with Missing Source Information

Source: https://loguru.readthedocs.io/en/stable/resources/troubleshooting.html

Example of a log message where source information (module, filename, function) is missing or unknown. This can occur when using Loguru with Dask or Cython.

```log
2024-12-01 16:23:21.769 | INFO     | None:<unknown>:0 - Message from unknown source.

```

--------------------------------

### RGB Color Tags Usage

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Demonstrates how to specify foreground and background colors using RGB values.

```python
logger.info("<fg 0,95,0>This is foreground RGB color (0,95,0).</fg 0,95,0>")
logger.info("<bg 72,119,65>This is background RGB color (72,119,65).</bg 72,119,65>")
```

--------------------------------

### File Logging with Rotation, Retention, and Compression

Source: https://loguru.readthedocs.io/en/stable/overview.html

Configure file logging with automatic rotation based on size or time, log retention policies, and compression.

```python
logger.add("file_1.log", rotation="500 MB")    # Automatically rotate too big file
logger.add("file_2.log", rotation="12:00")     # New file is created each day at noon
logger.add("file_3.log", rotation="1 week")    # Once the file is too old, it's rotated

logger.add("file_X.log", retention="10 days")  # Cleanup after some time

logger.add("file_Y.log", compression="zip")    # Save some loved space

```

--------------------------------

### Customizing Exception Handling with onerror

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Configure the @logger.catch decorator with an 'onerror' callback to execute custom logic when an exception is caught. This example uses sys.exit(1) to set a non-zero exit code.

```python
>>> # Use 'onerror' to prevent the program exit code to be 0 (if 'reraise=False') while
>>> # also avoiding the stacktrace to be duplicated on stderr (if 'reraise=True').
>>> @logger.catch(onerror=lambda _: sys.exit(1))
... def main():
...     1 / 0
```

--------------------------------

### Importing Loguru logger

Source: https://loguru.readthedocs.io/en/stable/resources/migration.html

This snippet shows the Loguru way to import the logger, which is sufficient for use without explicit instantiation or naming.

```python
from loguru import logger
```

--------------------------------

### Basic Logging

Source: https://loguru.readthedocs.io/en/stable/overview.html

Loguru provides a single logger instance that is ready to use out of the box, outputting to stderr.

```python
from loguru import logger

logger.debug("That's it, beautiful and simple logging!")

```

--------------------------------

### Add Handlers with Mutually Exclusive Filters

Source: https://loguru.readthedocs.io/en/stable/resources/troubleshooting.html

To avoid duplication when adding multiple handlers to the same sink, ensure their `filter` functions are mutually exclusive. This example shows how to filter DEBUG messages separately from INFO messages.

```python
def is_debug(record):
    return record["level"].no <= 10

logger.add(sys.stderr, level="DEBUG", format="{time} - {name} - {message}", filter=is_debug)
logger.add(sys.stderr, level="INFO", format="{message}", filter=lambda r: not is_debug(r))
```

--------------------------------

### logger.start

Source: https://loguru.readthedocs.io/en/stable/api/logger.html

Adds a handler to send log messages to a sink. This is a deprecated function and `add()` should be used instead.

```APIDOC
## logger.start

### Description
Adds a handler sending log messages to a sink adequately configured. Deprecated function, use `add()` instead.

### Warning
Deprecated since version 0.2.2: `start()` will be removed in Loguru 1.0.0, it is replaced by `add()` which is a less confusing name.

### Parameters

* **args** – Arguments for configuring the sink.
* **kwargs** – Keyword arguments for configuring the sink.

### Example

```python
# Note: Use logger.add() instead of logger.start()
# logger.start("file.log") # Deprecated usage
```
```

--------------------------------

### Handling Callable Sinks in Loguru

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Demonstrates the logic for wrapping standard callable sinks in Loguru. This ensures that regular functions or methods are correctly integrated as log sinks.

```python
name = getattr(sink, "__name__", None) or repr(sink)

if colorize is None:
    colorize = False

wrapped_sink = CallableSink(sink)
encoding = "utf8"
terminator = "\n"
exception_prefix = ""
```

--------------------------------

### Custom Formatter for Same-Line Logging

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Use a custom formatter with `bind()` and `opt()` to temporarily log messages on a continuous line. This is useful for illustrating step-by-step processes.

```python
def formatter(record):
    end = record["extra"].get("end", "\n")
    return "[{time}] {message}" + end + "{exception}"

logger.add(sys.stderr, format=formatter)
logger.add("foo.log", mode="w")

logger.bind(end="").debug("Progress: ")

for _ in range(5):
    logger.opt(raw=True).debug(".")

logger.opt(raw=True).debug("\n")

logger.info("Done")

```

--------------------------------

### Send Raw Messages with opt()

Source: https://loguru.readthedocs.io/en/stable/api/logger.html

Use `opt(raw=True)` to bypass sink formatting and send the message directly. This is useful when the sink expects unformatted data.

```python
logger.opt(raw=True).debug("No formatting\n")
```

--------------------------------

### Add, Commit, and Push Changes

Source: https://loguru.readthedocs.io/en/stable/project/contributing.html

Stage all changes, commit them with a descriptive message, and push the new branch to your remote repository.

```bash
$ git add .
$ git commit -m 'Add succinct explanation of what changed'
$ git push origin fix_bug
```

--------------------------------

### 8-bit Color Tags Usage

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Shows how to apply 8-bit (256-color) codes for foreground and background colors.

```python
logger.info("<fg 86>This is foreground color 86.</fg 86>")
logger.info("<bg 42>This is background color 42.</bg 42>")
```

--------------------------------

### Loguru Filter Configuration: None and Empty String

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Shows how Loguru handles `None` or an empty string for the filter parameter, resulting in no filtering or a default filter function.

```python
if filter is None:
    filter_func = None
elif filter == "":
    filter_func = _filters.filter_none
```

--------------------------------

### Equivalent to str.format()

Source: https://loguru.readthedocs.io/en/stable/resources/troubleshooting.html

Shows that Loguru's argument integration is similar to Python's built-in `str.format()` method.

```python
message = "My name is {name}".format(name="John")
logger.info(message)
```

--------------------------------

### Multiprocessing Pool with Worker Class (Windows)

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Main script demonstrating the use of `multiprocessing.Pool` with a worker class on Windows. It configures the logger and initializes worker processes with the logger instance.

```python
# main.py
from multiprocessing import Pool
from loguru import logger
import workers_a
import workers_b

if __name__ == "__main__":
    logger.remove()
    logger.add("file.log", enqueue=True)

    worker = workers_a.Worker()
    with Pool(4, initializer=worker.set_logger, initargs=(logger, )) as pool:
        results = pool.map(worker.work, [1, 10, 100])

    with Pool(4, initializer=workers_b.set_logger, initargs=(logger, )) as pool:
        results = pool.map(workers_b.work, [1, 10, 100])

    logger.info("Done")

```

--------------------------------

### Various Usages of opt() Method

Source: https://loguru.readthedocs.io/en/stable/overview.html

The `opt()` method provides several options for customizing log message behavior, including adding exceptions, enabling colors, displaying record values, bypassing formatting, using parent stack context, and controlling keyword argument capture.

```python
logger.opt(exception=True).info("Error stacktrace added to the log message (tuple accepted too)")
logger.opt(colors=True).info("Per message <blue>colors</blue>")
logger.opt(record=True).info("Display values from the record (eg. {record[thread]})")
logger.opt(raw=True).info("Bypass sink formatting\n")
logger.opt(depth=1).info("Use parent stack context (useful within wrapped functions)")
logger.opt(capture=False).info("Keyword arguments not added to {dest} dict", dest="extra")

```

--------------------------------

### Correct Formatting with Loguru

Source: https://loguru.readthedocs.io/en/stable/resources/troubleshooting.html

Shows the recommended way to include complex data structures like dictionaries in log messages by letting Loguru handle the formatting.

```python
logger.info("Processing '{data}'", data=data)
```

--------------------------------

### Logger Method Type Hints

Source: https://loguru.readthedocs.io/en/stable/api/type_hints_source.html

Shows the type hints for standard logging methods like trace, debug, info, success, warning, error, critical, and exception. Includes overloads for string messages with arguments and any type of message.

```python
def trace(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
@overload
def trace(__self, __message: Any) -> None: ...  # noqa: N805
@overload
def debug(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
@overload
def debug(__self, __message: Any) -> None: ...  # noqa: N805
@overload
def info(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
@overload
def info(__self, __message: Any) -> None: ...  # noqa: N805
@overload
def success(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
@overload
def success(__self, __message: Any) -> None: ...  # noqa: N805
@overload
def warning(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
@overload
def warning(__self, __message: Any) -> None: ...  # noqa: N805
@overload
def error(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
@overload
def error(__self, __message: Any) -> None: ...  # noqa: N805
@overload
def critical(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
@overload
def critical(__self, __message: Any) -> None: ...  # noqa: N805
@overload
def exception(__self, __message: str, *args: Any, **kwargs: Any) -> None: ...  # noqa: N805
@overload
def exception(__self, __message: Any) -> None: ...  # noqa: N805
```

--------------------------------

### Add a Sink with Custom Format and Filter

Source: https://loguru.readthedocs.io/en/stable/overview.html

Use the add() function to register sinks with custom formatting, filtering, and log levels.

```python
logger.add(sys.stderr, format="{time} {level} {message}", filter="my_module", level="INFO")

```

--------------------------------

### Loguru Sinks for Basic and Advanced Message Handling

Source: https://loguru.readthedocs.io/en/stable/resources/migration.html

Demonstrates two sink functions: `simple_sink` for basic message printing and `advanced_sink` for accessing record details like file path and level for conditional output.

```python
def simple_sink(message):
    # A simple sink can use "message" as a basic string and ignore the "record" attribute.
    print(message, end="")
```

```python
def advanced_sink(message):
    # An advanced sink can use the "record" attribute to access contextual information.
    record = message.record

    if record["level"].no >= 50:
        file_path = record["file"].path
        print(f"Critical error in {file_path}", end="", file=sys.stderr)
    else:
        print(message, end="")
```

```python
logger.add(simple_sink)
logger.add(advanced_sink)
```

--------------------------------

### opt method

Source: https://loguru.readthedocs.io/en/stable/api/type_hints_source.html

The `opt` method returns a logger instance with specific options configured for exception handling and message formatting.

```APIDOC
## opt method

### Description

Returns a logger instance with specific options configured. This is useful for creating specialized loggers for different purposes, particularly for exception-related logging.

### Method

`opt`

### Parameters

*   **exception**: If `True`, enables exception capturing. Can also be an `ExcInfo` object or a `BaseException` instance for specific capture.
*   **record**: If `True`, enables recording of log messages.
*   **lazy**: If `True`, enables lazy evaluation of log message arguments.
*   **colors**: If `True`, enables ANSI color codes in the output.
*   **raw**: If `True`, disables formatting and outputs raw messages.
*   **capture**: If `True`, enables capture of exceptions.
*   **depth**: The depth of the stack trace to capture.
*   **ansi**: If `True`, enables ANSI escape codes in the output.

### Returns

A configured `Logger` instance.
```

--------------------------------

### Configuring Loguru with Multiprocessing Context

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

This snippet shows how to add a Loguru handler with `enqueue=True` and explicitly specify the multiprocessing context to avoid issues when using different contexts in parent and child processes.

```python
import multiprocessing
from loguru import logger
import workers_a

if __name__ == "__main__":
    context = multiprocessing.get_context("spawn")

    logger.remove()
    logger.add("file.log", enqueue=True, context=context)

    worker = workers_a.Worker()
    with context.Pool(4, initializer=worker.set_logger, initargs=(logger, )) as pool:
        results = pool.map(worker.work, [1, 10, 100])

```

--------------------------------

### Light Color Tags Usage

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Demonstrates the use of light color variants for foreground and background text.

```python
logger.info("<light-blue>This is light blue text.</light-blue>")
logger.info("<LIGHT-CYAN>This is light cyan background.</LIGHT-CYAN>")
```

--------------------------------

### Asynchronous Sink Initialization

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Initializes an asynchronous sink, handling event loop retrieval for enqueued operations.

```python
elif iscoroutinefunction(sink) or iscoroutinefunction(
            getattr(sink, "__call__", None)  # noqa: B004
        ):
            name = getattr(sink, "__name__", None) or repr(sink)

            if colorize is None:
                colorize = False

            loop = kwargs.pop("loop", None)

            if enqueue and loop is None:
                try:
                    loop = _asyncio_loop.get_running_loop()
                except RuntimeError as e:
                    raise ValueError(
                        "An event loop is required to add a coroutine sink with `enqueue=True`, "
                        "but none has been passed as argument and none is currently running."
                    ) from e
```

--------------------------------

### Stylizing Text in Loguru

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Shows how to apply various text styles like bold, underline, and strike-through to log messages.

```python
logger.info("<bold>This text is bold.</bold>")
logger.info("<b>This text is also bold.</b>")
logger.info("<underline>This text is underlined.</underline>")
logger.info("<u>This text is also underlined.</u>")
logger.info("<strike>This text is struck through.</strike>")
```

--------------------------------

### Binding Extra Data to Log Records

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Demonstrates how to bind extra attributes to log records for specific instances, allowing for contextual logging. This is useful for differentiating logs from various sources or components.

```python
>>> logger.add(sys.stderr, format="{extra[ip]} - {message}")
>>> class Server:
...     def __init__(self, ip):
...         self.ip = ip
...         self.logger = logger.bind(ip=ip)
...     def call(self, message):
...         self.logger.info(message)
...
>>> instance_1 = Server("192.168.0.200")
>>> instance_2 = Server("127.0.0.1")
>>> instance_1.call("First instance")
192.168.0.200 - First instance
>>> instance_2.call("Second instance")
127.0.0.1 - Second instance
```

--------------------------------

### Log Descriptive Exceptions with Full Traceback

Source: https://loguru.readthedocs.io/en/stable/overview.html

Enable `backtrace=True` and `diagnose=True` to log exceptions with variable values and a full stack trace. Caution: `diagnose=True` may leak sensitive data in production.

```python
# Caution, "diagnose=True" is the default and may leak sensitive data in prod
logger.add("out.log", backtrace=True, diagnose=True)

def func(a, b):
    return a / b

def nested(c):
    try:
        func(5, c)
    except ZeroDivisionError:
        logger.exception("What?!")

nested(0)

```

--------------------------------

### Run Unit Tests with Tox

Source: https://loguru.readthedocs.io/en/stable/project/contributing.html

Execute the unit tests using Tox to ensure code changes do not introduce regressions. This command runs tests against the 'tests' environment.

```bash
$ tox -e tests
```

--------------------------------

### Print Logger Configuration

Source: https://loguru.readthedocs.io/en/stable/resources/troubleshooting.html

View the current sink configuration of the logger. Ensure at least one sink is added.

```python
print(logger)
# Output: <loguru.logger handlers=[(id=0, level=10, sink=<stderr>)]>
```

--------------------------------

### Define and Use Custom Log Levels

Source: https://loguru.readthedocs.io/en/stable/overview.html

Create custom log levels using `logger.level()` by specifying a name, number, color, and icon. Then, use `logger.log()` with the custom level name.

```python
new_level = logger.level("SNAKY", no=38, color="<yellow>", icon="🐍")

logger.log("SNAKY", "Here we go!")

```

--------------------------------

### enable method

Source: https://loguru.readthedocs.io/en/stable/api/type_hints_source.html

The `enable` method is used to enable logging for a specific logger name.

```APIDOC
## enable method

### Description

Enables logging for a logger identified by its name. This is the counterpart to the `disable` method.

### Method

`enable`

### Parameters

*   **name** (Optional[str]): The name of the logger to enable. If `None`, all loggers are enabled.

### Returns

`None`
```

--------------------------------

### Add Custom Logging Level

Source: https://loguru.readthedocs.io/en/stable/_modules/loguru/_logger.html

Shows how to define and add a new custom logging level with a specific severity number, color, and icon. This allows for more granular logging control.

```python
>>> logger.level("CUSTOM", no=15, color="<blue>", icon="@")
Level(name='CUSTOM', no=15, color='<blue>', icon='@')
```

--------------------------------

### Specify Stack Depth for Context with opt()

Source: https://loguru.readthedocs.io/en/stable/api/logger.html

Use `opt(depth=1)` to specify which stack trace level to use for contextualizing log messages. This is helpful when logging from within wrapper functions.

```python
def wrapped():
    logger.opt(depth=1).info("Get parent context")

def func():
    wrapped()

func()
```

--------------------------------

### Log Exception Details with opt()

Source: https://loguru.readthedocs.io/en/stable/api/logger.html

Use `opt(exception=True)` to format and include exception information in the log message. This is useful for debugging when an error occurs.

```python
try:
    1 / 0
except ZeroDivisionError:
   logger.opt(exception=True).debug("Exception logged with debug level:")
```

--------------------------------

### Log Function Execution Time with Decorator

Source: https://loguru.readthedocs.io/en/stable/resources/recipes.html

Create a decorator to measure and log the execution time of a function. This helps in identifying performance bottlenecks.

```python
import time
from loguru import logger

def timeit(func):

    def wrapped(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs)
        end = time.time()
        logger.debug("Function '{}' executed in {:f} s", func.__name__, end - start)
        return result

    return wrapped

```

--------------------------------

### Forcing Color Output with colorize=True

Source: https://loguru.readthedocs.io/en/stable/resources/troubleshooting.html

Explicitly enable ANSI color sequences in the output by setting the 'colorize' argument to True when adding a sink.

```python
logger.add(sys.stderr, colorize=True)  # Force ANSI sequences in output.
```

--------------------------------

### bind method

Source: https://loguru.readthedocs.io/en/stable/api/type_hints_source.html

The `bind` method allows adding arbitrary key-value pairs to the logger's context, which will be included in all subsequent log messages.

```APIDOC
## bind method

### Description

Binds arbitrary key-value pairs to the logger's context. These bound variables will be included in all subsequent log messages generated by this logger instance.

### Method

`bind`

### Parameters

*   **kwargs**: Arbitrary keyword arguments to bind to the logger's context.

### Returns

A new `Logger` instance with the bound context.
```
Tokens:
Raw