Python Standard Library logging module

Warnings

• breaking Installing `pip install logging` (PyPI package version 0.4.9.6) can conflict with the standard library `logging` module in modern Python environments (Python 2.3+). This legacy PyPI package was intended for very old Python versions (< 2.3) and can break tools like Pipenv if incorrectly installed.
  Fix: Do not install a package named 'logging' from PyPI. The standard library `logging` module is always available without installation. If encountered, uninstall the PyPI package (`pip uninstall logging`).
• gotcha If `logging.basicConfig()` is not called, the default log level for the root logger is `WARNING`. This means `DEBUG` and `INFO` messages will be silently ignored and not appear in output unless the logger's level is explicitly set lower.
  Fix: Always call `logging.basicConfig(level=logging.DEBUG)` (or `INFO`, etc.) at the start of your application to ensure all desired message levels are processed.
• gotcha Using global functions like `logging.debug()` directly operates on the *root logger*. For structured applications, it's recommended to create and configure named loggers using `logging.getLogger(__name__)` for better modularity and control. Libraries should never configure the root logger directly.
  Fix: For application code, prefer `logger = logging.getLogger(__name__)` and then `logger.info(...)`. For library code, defer configuration to the application using your library, usually by adding only a `NullHandler`.
• gotcha Libraries should generally avoid adding handlers to their loggers other than `logging.NullHandler`. This allows the application using the library to fully control where and how the library's logs are processed, preventing unexpected output or conflicts with the application's logging configuration.
  Fix: When developing a library, add `logging.getLogger(__name__).addHandler(logging.NullHandler())` to prevent emitting messages if no other configuration is present, and avoid adding any other handlers.
• gotcha Logging from asynchronous code using blocking network or file handlers can stall the event loop, impacting performance. Standard `StreamHandler` or `FileHandler` can be blocking operations.
  Fix: For async applications, consider using `logging.handlers.QueueHandler` and `logging.handlers.QueueListener` to offload actual logging I/O to a separate thread, preventing the main event loop from blocking.
• gotcha Log formatters can be vulnerable to log injection if raw newlines or other control characters within log messages are not properly handled (e.g., quoted or sanitized). This can lead to misinterpretation of logs by parsers or security tools.
  Fix: Consider using structured logging (e.g., JSON output with `python-json-logger`) where messages are explicitly contained within a field, or ensure custom formatters properly escape or sanitize potentially disruptive characters from user-provided input.

Imports

• logging

  import logging

• getLogger

  from logging import getLogger

  getLogger is a function directly within the logging module, not a submodule.
• basicConfig

  from logging import basicConfig

  basicConfig is a function directly within the logging module, not a submodule.

Quickstart

This quickstart demonstrates both basic `basicConfig` usage for simple scripts and a more robust application-level setup using a named logger with a `FileHandler` and custom formatter. It also shows how to prevent propagation to avoid duplicate messages.

import logging
import os

# Basic configuration for quick scripts (logs to console, INFO level and above)
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Recommended for applications: get a named logger
logger = logging.getLogger(__name__)

# Configure a file handler for a more complex setup
log_file_path = os.environ.get('LOG_FILE', 'application.log')
file_handler = logging.FileHandler(log_file_path)
file_handler.setLevel(logging.DEBUG)
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)')
file_handler.setFormatter(formatter)
logger.addHandler(file_handler)

# Prevent messages from propagating to the root logger handlers (often console) if file is primary
logger.propagate = False

# Example log messages
logger.debug('This is a debug message - will only go to file handler.')
logger.info('This is an info message.')
logger.warning('This is a warning message!')
logger.error('This is an error message!')
logger.critical('This is a critical message!', exc_info=True)

print(f"\nCheck '{log_file_path}' for detailed logs.")