User Guide

Base Workflow

All functionality is accessed via the IndentLogger class:

from logindent import IndentLogger

Use the class constructor to create an IndentLogger for a given logging stream:

logger = IndentLogger("my-logger")

You can use the logger to log messages via the debug, info, warning, error, and critical methods:

logger.debug("Some debug message")
logger.info("Some info message")
logger.warning("Some warning message")
logger.error("Some error message")
logger.critical("Some critical message")

DEBUG    - my-logger - Some debug message
INFO     - my-logger - Some info message
WARNING  - my-logger - Some warning message
ERROR    - my-logger - Some error message
CRITICAL - my-logger - Some critical message

Managing Indentation

There are two strategies for managing message indentation: via context managers, or via managed loggers.

Context Manager

You can use the indent method to manage indentation levels via a context manager. When called in a with block, the method will increase the indentation level by 1:

logger.info("Running task A")
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")
logging.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

Managed Loggers

Alternatively, you can use the indented method to return a new IndentLogger object whose indent level has been incremented by 1. This can be useful if you want to manage indentation levels without requiring a context block:

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

Customizing Indentation

By default, a new IndentLogger is initialized with an indent level of 0. You can use the indent_level to change the starting indentation. This can be useful when creating a logger for a process that is already running. For example:

logger = IndentLogger('my-logger', indent_level=1)
logger.info("Starting a task in a running process")
with logger.indent():
    logger.info("Running step 1")
    logger.info("Running step 2")

INFO  - my-logger -    Starting a task in a running process
DEBUG - my-logger -         Running step 1
DEBUG - my-logger -         Running step 2

By default, the indentation string is set to 4 spaces. Use indent_string to use a different value instead:

logger = IndentLogger("my-logger", indent_string="..")

logger.info("Running task A")
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")
logging.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