API

install(indentation=' ', deepest_indentation='..', max_level=5, handlers=None, logger=None, logging_classes=(logging.Logger,), logging_functions=())

Wraps formatters of each handler of the logger with the special IndentingFormatter.

If logger is None (default), root logger will be used. If logger doesn't have any handlers added, an instance of logging.StreamHandler will be created and added.

Handlers to be wrapped can be also provided through handlers argument. In this case loigger argument is not taken into consideration.

If your application writes logs by calling custom logging functions, these functions should be registered in logging_functions. Alternatively, if they are methods of a class, this class can be registered in logging_classes. There is no need of registering classes that derive from logging.Logger.

Indentation is created as indentation * indentation_level, where indentation_level is calculated from current location in the call stack. indentation_level can be limited by max_level, or unlimited when max_level is None. Whenever indentation_level exceeds the limit, indentation is created as indentation * (max_level - 1) + deepest_indentation.

Parameters:

Name Type Description Default
indentation str

String concatenated with the message to create a single-level indentation.

 ' '
deepest_indentation str

String preceeding the message in case when indentation level exceeds the limit.

 '..'
max_level Optional[int]

Limit of the indentation level. Use None for disabling the limit.

 5
handlers Optional[Iterable[logging.Handler]]

Logging handlers, formatters of which are wrapped by IndentingFormatter.

 None
logger Optional[logging.Logger]

Logger, handlers of which are explored to have their formatters wrapped.

 None
logging_classes Iterable[Type]

Collection of classes, methods of which are considered as logging functions.

 (logging.Logger,)
logging_functions Iterable[Callable]

Collection of logging functions.

 ()
Source code in indentedlogs/formatters.py 
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 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
115
116
117
118
119
120
121
122
123
 
def install(
    indentation: str = '  ',
    deepest_indentation: str = '..',
    max_level: Optional[int] = 5,
    handlers: Optional[Iterable[logging.Handler]] = None,
    logger: Optional[logging.Logger] = None,
    logging_classes: Iterable[Type] = DefaultLogger(),
    logging_functions: Iterable[Callable] = ()
) -> None:
    """Wraps formatters of each handler of the `logger` with the special
    `IndentingFormatter`.

    If `logger` is `None` (default), root logger will be used. If `logger`
    doesn't have any handlers added, an instance of `logging.StreamHandler`
    will be created and added.

    Handlers to be wrapped can be also provided through `handlers` argument.
    In this case `loigger` argument is not taken into consideration.

    If your application writes logs by calling custom logging functions, these
    functions should be registered in `logging_functions`. Alternatively, if
    they are methods of a class, this class can be registered in
    `logging_classes`. There is no need of registering classes that derive from
    `logging.Logger`.

    Indentation is created as `indentation * indentation_level`, where
    `indentation_level` is calculated from current location in the call stack.
    `indentation_level` can be limited by `max_level`, or unlimited when
    `max_level` is `None`. Whenever `indentation_level` exceeds the limit,
    indentation is created as
    `indentation * (max_level - 1) + deepest_indentation`.

    Arguments:
        indentation: String concatenated with the message to create a
            single-level indentation.
        deepest_indentation: String preceeding the message in case when
            indentation level exceeds the limit.
        max_level: Limit of the indentation level. Use `None` for disabling the
            limit.
        handlers: Logging handlers, formatters of which are wrapped by
            `IndentingFormatter`.
        logger: Logger, handlers of which are explored to have their formatters
            wrapped.
        logging_classes: Collection of classes, methods of which are considered
            as logging functions.
        logging_functions: Collection of logging functions.
    """

    if isinstance(logging_classes, DefaultLogger):
        logging_classes = DefaultLogger.value

    monitor = StackMonitor(logging_classes, logging_functions)

    if handlers is None:
        if logger is None:
            logger = logging.getLogger()
        if not logger.handlers:
            # Default handler (`logging.lastResort`) could be used here,
            # but it is not part of the official API
            logger.addHandler(logging.StreamHandler())
        handlers = logger.handlers

    for handler in handlers:
        ind_fmt = IndentingFormatter(monitor, indentation, deepest_indentation,
                                     max_level)
        if handler.formatter is None:
            handler.setFormatter(ind_fmt)
        else:
            stk_fmt = StackedFormatter(handler.formatter, ind_fmt)
            handler.setFormatter(stk_fmt)