Skip to content

Global context module

Module with routines to work with the global context.

This is the expected main entrypoint for users so let's try to keep it friendly to use and as simple as possible, but not simpler.

add_global_context(context, *, auto_init=True)

Add values to the global context to be attached to all the log messages.

The values will be removed from the global context once the context manager exists.

Parameters:

Name Type Description Default
context dict[str, Any]

A key/value mapping with the values to add to the global context.

 required
auto_init bool

Indicate if the global context should be automatically initialized if it isn't.

If True, the context will be also automatically shutdown before exiting.

If the global context is already initialized it'll do nothing.

Keyword-only argument.

 True

Returns:

Type Description
None

A context manager that manages the life of the values.
Source code in src/logging_with_context/global_context.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
@contextmanager
def add_global_context(
    context: dict[str, Any], *, auto_init: bool = True
) -> Generator[None, None, None]:
    """
    Add values to the global context to be attached to all the log messages.

    The values will be removed from the global context once the context manager exists.

    Parameters:
        context: A key/value mapping with the values to add to the global context.
        auto_init: Indicate if the global context should be automatically initialized
            if it isn't.

            If `True`, the context will be also automatically shutdown before exiting.

            If the global context is already initialized it'll do nothing.

            Keyword-only argument.

    Returns:
        A context manager that manages the life of the values.
    """
    auto_initialized = False
    if not __global_context_initialized.get() and auto_init:
        init_global_context()
        auto_initialized = True
    token = __global_context_var.set(__global_context_var.get() | context)
    try:
        yield
    finally:
        __global_context_var.reset(token)
        if auto_initialized:
            shutdown_global_context()

global_context_initialized(loggers=None)

Initiliaze the global context and manages its shutdown.

Parameters:

Name Type Description Default
loggers Optional[Sequence[Logger]]

The loggers to attach the global context; if not loggers are specified it will use the root logger.

 None

Returns:

Type Description
None

A context manager with the global context initialized.
Source code in src/logging_with_context/global_context.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
@contextmanager
def global_context_initialized(
    loggers: Optional[Sequence[Logger]] = None,
) -> Generator[None, None, None]:
    """
    Initiliaze the global context and manages its shutdown.

    Parameters:
        loggers: The loggers to attach the global context; if not loggers are specified
            it will use the root logger.

    Returns:
        A context manager with the global context initialized.
    """
    init_global_context(loggers)
    try:
        yield
    finally:
        shutdown_global_context(loggers)

init_global_context(loggers=None)

Initialize the application global context in the given loggers.

Parameters:

Name Type Description Default
loggers Optional[Sequence[Logger]]

The loggers to attach the global context; if not loggers are specified it will use the root logger.

 None
Source code in src/logging_with_context/global_context.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
def init_global_context(loggers: Optional[Sequence[Logger]] = None) -> None:
    """
    Initialize the application global context in the given loggers.

    Parameters:
        loggers: The loggers to attach the global context; if not loggers are specified
            it will use the root logger.
    """
    __global_context_initialized.set(True)
    filter_with_context = FilterWithContextVar(__global_context_var)
    for logger in _get_loggers_to_process(loggers):
        for handler in logger.handlers:
            handler.addFilter(filter_with_context)

shutdown_global_context(loggers=None)

Shutdown the application global context in the given loggers.

Parameters:

Name Type Description Default
loggers Optional[Sequence[Logger]]

The loggers that were used when calling init_global_context; by default the root logger.

 None
Source code in src/logging_with_context/global_context.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def shutdown_global_context(loggers: Optional[Sequence[Logger]] = None) -> None:
    """
    Shutdown the application global context in the given loggers.

    Parameters:
        loggers: The loggers that were used when calling `init_global_context`; by
            default the root logger.
    """
    __global_context_initialized.set(False)
    for logger in _get_loggers_to_process(loggers):
        for handler in logger.handlers:
            for filter_ in handler.filters:
                if not isinstance(filter_, FilterWithContextVar):
                    continue
                handler.removeFilter(filter_)