Metadata-Version: 2.4
Name: logindent
Version: 1.0.1
Summary: Utility class for indenting log messages
Keywords: logging,indent
Author: Jonathan King
Author-email: Jonathan King <jonking93@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Maintainer: Jonathan King
Maintainer-email: Jonathan King <jonking93@gmail.com>
Requires-Python: >=3.11, <4
Project-URL: Repository, https://github.com/JonKing93/logindent
Project-URL: Documentation, https://logindent.readthedocs.io
Description-Content-Type: text/markdown

# logindent

[![Documentation](https://img.shields.io/badge/Documentation-Click%20Here!-blue)](https://logindent.readthedocs.io)
[![Python](https://img.shields.io/badge/Python-3.11+-blue)](https://www.python.org/downloads)
[![PyPI](https://img.shields.io/pypi/v/logindent.svg?color=green)](https://pypi.org/project/logindent/)
[![Build Status](https://github.com/JonKing93/logindent/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/JonKing93/logindent/actions/workflows/build.yml?query=branch%3Amain)
[![Coverage](https://coveralls.io/repos/github/JonKing93/logindent/badge.svg?branch=main)](https://coveralls.io/github/JonKing93/logindent?branch=main)
[![License](https://img.shields.io/badge/License-MIT-blue)](https://opensource.org/license/mit)


Lightweight utility class for structurally indenting log messages.


## About

Indenting log messages is a simple way to make log messages more human readable. In particular, indenting can help distinguish messages for high-level tasks from messages for their subtasks. For example, in the following indented log:

```
Starting task 1
    Running step 1
    Running step 2
    Running step 3
Completed task
Starting a second task
    Querying server
    Parsing response
    Updating database
Completed second task
```

it is immediately clear where tasks 1 and 2 begin, and which sub-steps belong to each task.

The `logindent` package provides the lightweight `IndentLogger` class to help implement this functionality. The class provides routines to track indenting levels and record log messages to standard logging streams. When logging messages, the correct amount of indentation will be prepended to the log message automatically. Users can manage the indentation level using either context blocks, or via managed `IndentLogger` objects.


## Examples

Indented logging using context blocks:

```python
from logindent import IndentLogger

logger = IndentLogger("my-logger")
logger.info("Starting task 1")
with logger.indent():
    logger.debug("Running step 1")
    logger.debug("Running step 2")
    logger.debug("Running step 3")
    with logger.indent():
        logger.debug("Ran sub-step A")
        logger.debug("Ran sub-step B")
logger.info("Completed task 1")
```
```
INFO  - Starting task 1
DEBUG -     Running step 1
DEBUG -     Running step 2
DEBUG -     Running step 3
DEBUG -         Ran sub-step A
DEBUG -         Ran sub-step B
INFO  - Completed task 1
```

Indented logging using managed loggers:
```python
logger.info("Starting task 1")

task_logger = logger.indented()
task_logger.debug("Running step 1")
task_logger.debug("Running step 2")
task_logger.debug("Running step 3")

step3_logger = task_logger.indented()
step3_logger.debug("Ran sub-step A")
step3_logger.debug("Ran sub-step B")

logger.info("Completed task 1")
```
```
INFO  - Starting task 1
DEBUG -     Running step 1
DEBUG -     Running step 2
DEBUG -     Running step 3
DEBUG -         Ran sub-step A
DEBUG -         Ran sub-step B
INFO  - Completed task 1
```

Customize indent level and string:
```python
logger = IndentLogger('my-logger', indent_level=2, indent_string="..")

logger.info("Starting task 1 in some running process")
with logger.indent():
    logger.debug("Running step 1")
    logger.debug("Running step 2")
    logger.debug("Running step 3")
```
```
INFO  - ....Starting task 1 in some running process
DEBUG - ......Running step 1
DEBUG - ......Running step 2
DEBUG - ......Running step 3
```

## When to use IndentLogger

The `IndentLogger` class is best used when you want a lightweight, text-based solution to make logs more human-readable. In particular, `IndentLogger` works well for both console and file logs. By contrast, other solutions for human-readable logs (such as colorized messages or [rich trees](https://rich.readthedocs.io/en/stable/tree.html)) can sometimes render poorly when logged to file.

Finally, if you want logs that are *machine* readable (rather than human readable), then consider using structured logging instead of `IndentLogger`.
