lammps_utils.logging package

This module provides a set of utilities for logging in Python.

It includes functions to configure logging behavior, such as enabling or disabling the default handler, retrieving a child logger, and accessing the root logger. Additionally, this module defines constants for various logging levels to be used in logging configurations.

class lammps_utils.logging.catch_default_handler

Bases: object

Context manager to temporarily disable the default handler.

When entering the context, the library’s default log handler is removed from the root logger to suppress output. When exiting, the handler is re-attached.

Examples

>>> logger = get_child_logger(__name__)
>>> with catch_default_handler():
...     logger.info("This message will not be logged.")
>>> logger.info("This message will be logged.")
lammps_utils.logging.disable_default_handler() → None

Disable the default handler for the library’s root logger.

Detaches the default handler from the root logger to suppress logging output.

Return type:

None

lammps_utils.logging.enable_default_handler() → None

Enable the default handler for the library’s root logger.

Re-attaches the default handler to the root logger if it has been previously removed.

Return type:

None

lammps_utils.logging.get_child_logger(name: str, propagate: bool = True) → Logger

Retrieve a child logger associated with the given module name.

This function returns a child logger derived from the library’s root logger. The name argument should typically be set to __name__ to ensure that the logger is correctly nested under the library’s namespace. If the name does not match the expected pattern, a ValueError is raised.

Parameters:

  • name (str) – The module name, typically set to __name__.

  • propagate (bool, optional) – Whether log messages should propagate to the parent logger. Default is True.

Returns:

A configured child logger instance.

Return type:

Logger

Raises:

ValueError – If the provided name does not belong to the library’s namespace and is not ‘__main__’.

lammps_utils.logging.get_handler(handler: HandlerType, formatter: Formatter | None = None, level: int = 0) → HandlerType

Configure a log handler with a formatter and log level.

This function simplifies handler configuration by allowing optional specification of a formatter and log level. If no formatter is provided, a default one will be used.

Parameters:

  • handler (HandlerType) – The log handler to configure.

  • formatter (Optional[Formatter], optional) – The formatter to apply to the handler. If None, a default formatter is used. Default is None.

  • level (int, optional) – The logging level to set for the handler (e.g., logging.DEBUG, logging.INFO). Default is logging.NOTSET.

Returns:

The configured log handler.

Return type:

HandlerType

lammps_utils.logging.get_root_logger() → Logger

Retrieve the root logger for this library package.

Ensures that the logger is properly configured with a default handler and logging level before returning it.

Returns:

The root logger instance for the current package.

Return type:

Logger