packing_packages.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 packing_packages.logging.catch_all_handler#

Bases: object

Context manager to temporarily suppress all logging handlers.

This context manager temporarily removes all handlers from the library’s root logger when entering the context, and restores them when exiting. Unlike catch_default_handler, this affects all handlers, including any custom handlers that have been added.

This is useful for: - Completely suppressing all logging output during specific operations - Testing code paths without any logging interference - Temporary isolation of logging behavior

Examples

>>> from packing_packages.logging import get_child_logger, catch_all_handler
>>> logger = get_child_logger(__name__)
>>>
>>> logger.addHandler(custom_handler)  # Custom handler added
>>> logger.info("This will be logged by all handlers")
>>> with catch_all_handler():
...     logger.info("No handlers active - this won't be logged")
...     logger.error("Errors are also suppressed")
>>> logger.info("All handlers restored - this will be logged again")

class packing_packages.logging.catch_default_handler#

Bases: object

Context manager to temporarily suppress the default logging handler.

This context manager allows you to temporarily disable the default handler for the library’s root logger. When entering the context, the default handler is removed, suppressing all logging output. When exiting (even if an exception occurs), the handler is automatically restored.

This is particularly useful for: - Suppressing logs during test execution - Creating cleaner output in specific code sections - Temporarily redirecting all logging to custom handlers

Examples

>>> from packing_packages.logging import get_child_logger, catch_default_handler
>>> logger = get_child_logger(__name__)
>>>
>>> logger.info("This will be logged")
>>> with catch_default_handler():
...     logger.info("This message will not be logged")
...     logger.debug("Neither will this")
>>> logger.info("This will be logged again")

null_handler = <NullHandler (NOTSET)>#

packing_packages.logging.disable_default_handler() → None#

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

This function removes the default stream handler from the root logger, effectively suppressing all logging output from the library. The handler is not deleted and can be re-attached later using enable_default_handler().

This is useful for: - Temporarily suppressing output during testing - Allowing users to configure their own handlers without interference - Reducing noise in specific execution contexts

Return type:: None

See also

disable_default_handler: Remove the default handler.
catch_default_handler: Context manager to temporarily disable the handler.

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

Get a child logger for a specific module.

This function creates and returns a child logger under the library’s root logger hierarchy. The logger name is derived from the module name, allowing for organized and hierarchical logging within the package.

The name parameter should typically be set to __name__ to automatically generate the correct logger name based on the module’s full path.

Parameters:

name (str) – The module name, typically __name__. Must be either: - A name within the library’s namespace (e.g., ‘packing_packages.module’) - The string ‘__main__’ for scripts executed directly
propagate (bool, optional) – Whether log messages should propagate to parent loggers. If True, messages will also be handled by parent loggers. Default is True.

Returns:

A configured child logger instance with the specified propagation setting.

Return type:

Logger

Raises:

ValueError – If the provided name does not belong to the library’s namespace and is not ‘__main__’. This prevents accidentally creating loggers outside the intended hierarchy.

Examples

>>> # In a module: packing_packages/utils.py
>>> logger = get_child_logger(__name__)
>>> logger.info("Module loaded")
packing_packages.utils - INFO - Module loaded

>>> # In __main__ script
>>> logger = get_child_logger(__name__)
>>> logger.debug("Debug message")

packing_packages.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 provides a convenient way to configure logging handlers by setting both the formatter and log level in a single call. If no formatter is specified, an appropriate default formatter will be automatically selected based on the handler type:

For file-based handlers (FileHandler, RotatingFileHandler, etc.),
a plain formatter without color codes is used.
For stream handlers (StreamHandler, etc.), color is used if
the environment supports it.

Parameters:

handler (HandlerType) – The log handler instance to configure (e.g., StreamHandler, FileHandler). The handler will be modified in place.
formatter (Optional[Formatter], optional) – The formatter to apply to the handler. If None, an appropriate default formatter is used based on the handler type (see create_default_formatter). Default is None.
level (int, optional) – The logging level threshold for the handler. Only messages at or above this level will be processed. Use constants from the logging module (e.g., logging.DEBUG, logging.INFO, logging.WARNING). Default is logging.NOTSET.

Returns:

The configured handler instance (same object as the input handler).

Return type:

HandlerType

Examples

>>> from logging import StreamHandler, FileHandler, INFO
>>> # Stream handler - may use color if supported
>>> stream_handler = get_handler(StreamHandler(), level=INFO)
>>> logger.addHandler(stream_handler)
>>>
>>> # File handler - always uses plain formatter (no color)
>>> file_handler = get_handler(FileHandler('app.log'), level=INFO)
>>> logger.addHandler(file_handler)

packing_packages.logging.get_library_root_logger() → Logger#

Get the root logger for this library package.

This function returns the root logger for the library, ensuring it is properly configured with a default handler and logging level. The logger name corresponds to the top-level package name (e.g., ‘packing_packages’).

The logger is automatically configured on first access with: - Default stream handler (with color support if available) - Logging level set to INFO - Propagation disabled

Returns:: The configured root logger instance for the library package.
Return type:: Logger

Examples

>>> logger = get_library_root_logger()
>>> logger.info("Library initialized")
packing_packages - INFO - Library initialized

packing_packages.logging package

Contents

packing_packages.logging package#