flake8-logging 1.0.1

A Flake8 plugin to improve logging.

A Flake8 plugin to improve logging.

Requirements

Python 3.8 to 3.12 supported.

Installation

First, install with pip:

python -m pip install flake8-logging

Second, if you define Flake8’s select setting, add the L prefix to it. Otherwise, the plugin should be active by default.

---

Linting a Django project? Check out my book Boost Your Django DX which covers Flake8 and many other code quality tools.

---

Rules

L001: use logging.getLogger() to instantiate loggers

The Logger Objects documentation section starts:

Note that Loggers should NEVER be instantiated directly, but always through the module-level function logging.getLogger(name).

Directly instantiated loggers are not added into the logger tree, so their messages are discarded. This means you’ll never see any messages on such loggers. Use getLogger() to correctly instantiate loggers.

This rule detects any module-level calls to Logger().

Failing example:

import logging

logger = logging.Logger(__name__)

Corrected:

import logging

logger = logging.getLogger(__name__)

L002: use __name__ with getLogger()

The logging documentation recommends this pattern:

logging.getLogger(__name__)

__name__ is the fully qualified module name, such as camelot.spam, which is the intended format for logger names.

This rule detects probably-mistaken usage of similar module-level dunder constants:

• __cached__ - the pathname of the module’s compiled versio˜, such as camelot/__pycache__/spam.cpython-311.pyc.

• __file__ - the pathname of the module, such as camelot/spam.py.

Failing example:

import logging

logger = logging.getLogger(__file__)

Corrected:

import logging

logger = logging.getLogger(__name__)

L003: extra key '<key>' clashes with LogRecord attribute

The extra documentation states:

The keys in the dictionary passed in extra should not clash with the keys used by the logging system.

Such clashes crash at runtime with an error like:

KeyError: "Attempt to overwrite 'msg' in LogRecord"

Unfortunately, this error is only raised if the message is not filtered out by level. Tests may therefore not encounter the check, if they run with a limited logging configuration.

This rule detects such clashes by checking for keys matching the LogRecord attributes.

Failing example:

import logging
logger = logging.getLogger(__name__)

response = acme_api()
logger.info("ACME Response", extra={"msg": response.msg})

Corrected:

import logging
logger = logging.getLogger(__name__)

response = acme_api()
logger.info("ACME Response", extra={"response_msg": response.msg})

L004: avoid logger.exception() outside of except clauses

The exception() documentation states:

This function should only be called from an exception handler.

Calling exception() outside of an exception handler attaches None exception information, leading to confusing messages:

>>> logging.exception("example")
ERROR:root:example
NoneType: None

Use error() instead. To log a caught exception, pass it in the exc_info argument.

This rule detects exception() calls outside of exception handlers.

Failing example:

import logging

response = acme_api()
if response is None:
    logging.exception("ACME failed")

Correct example:

import logging

response = acme_api()
if response is None:
    logging.error("ACME failed")