Skip to content

Logging Module Documentation

This module provides functions for logging.

Functions:

Name Description
setup_logging

Configures logging for the CoMPAS navlib library.

Set up logging with configurable options.

Parameters:

Name Type Description Default
level int

Logging level. The options are: 0: CRITICAL 1: DEBUG 2: INFO 3: WARNING 4: ERROR 5: NOTSET

 2
app_name str

Name of the application for log formatting

 'navlib'
logger_name Optional[str]

Name of the logger to configure. If None, configures root logger

 None
handler Optional[Handler]

Custom handler. If None, uses StreamHandler

 None
formatter Optional[Formatter]

Custom formatter. If None, uses NavlibFormatter

 None
clear_existing bool

Whether to clear existing handlers

 True

Returns:

Type Description
Logger

logging.Logger: Configured logger instance

Raises:

Type Description
ValueError

If the logging level is invalid or not an integer.
TypeError

If the logger_name is not a string.
TypeError

If the handler is not a logging.Handler instance.
TypeError

If the formatter is not a logging.Formatter instance.

Examples:

>>> logger = setup_logging(level=2, app_name="my_app")
>>> logger.info("This is an info message.")
[INFO][2023/10/01 12:00:00][my_app][root]: This is an info message.
Source code in navlib/logging/logging.py 
 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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def setup_logging(
    level: int = 2,
    app_name: str = "navlib",
    logger_name: Optional[str] = None,
    handler: Optional[logging.Handler] = None,
    formatter: Optional[logging.Formatter] = None,
    clear_existing: bool = True,
) -> logging.Logger:
    """
    Set up logging with configurable options.

    Args:
        level: Logging level. The options are:
            0: CRITICAL
            1: DEBUG
            2: INFO
            3: WARNING
            4: ERROR
            5: NOTSET
        app_name: Name of the application for log formatting
        logger_name: Name of the logger to configure. If None, configures root logger
        handler: Custom handler. If None, uses StreamHandler
        formatter: Custom formatter. If None, uses NavlibFormatter
        clear_existing: Whether to clear existing handlers

    Returns:
        logging.Logger: Configured logger instance

    Raises:
        ValueError: If the logging level is invalid or not an integer.
        TypeError: If the logger_name is not a string.
        TypeError: If the handler is not a logging.Handler instance.
        TypeError: If the formatter is not a logging.Formatter instance.

    Examples:
        >>> logger = setup_logging(level=2, app_name="my_app")
        >>> logger.info("This is an info message.")
        [INFO][2023/10/01 12:00:00][my_app][root]: This is an info message.
    """
    # Map logging level
    if not isinstance(level, int):
        raise ValueError("Logging level must be an integer.")

    level_map = {
        0: logging.CRITICAL,
        1: logging.DEBUG,
        2: logging.INFO,
        3: logging.WARNING,
        4: logging.ERROR,
        5: logging.NOTSET,
    }

    level = level_map.get(level)
    if level is None:
        raise ValueError(
            "Invalid logging level. Use 0-5 for CRITICAL, DEBUG, INFO, WARNING, ERROR, NOTSET respectively."
        )

    # Get the logger
    logger = logging.getLogger(logger_name)

    # Clear existing handlers if requested
    if clear_existing:
        logger.handlers.clear()

    # Create handler if not provided
    if handler is None:
        handler = logging.StreamHandler()

    # Create formatter if not provided
    if formatter is None:
        formatter = _NavlibFormatter(app_name=app_name)

    # Configure handler
    handler.setFormatter(formatter)

    # Add handler to logger
    logger.addHandler(handler)

    # Set the logger level
    logger.setLevel(level)

    return logger