Flake8 String Format Checker

0.3.0 · maintenance · verified Thu Apr 16

An extension for Flake8 that enforces best practices for `str.format` usage. It identifies various issues such as unindexed parameters, insufficient arguments in format calls, mixed implicit and explicit indexing, and unused arguments. The current version, 0.3.0, was released in February 2020, indicating a maintenance release cadence focusing on stability rather than frequent updates.

Common errors

```
flake8: command not found
```
cause The `flake8` command-line tool is not installed or not in your system's PATH.

fix Install Flake8 and its plugins: `pip install flake8 flake8-string-format`.
```
my_file.py:1:1: P101 format string does contain unindexed parameters
```
cause The plugin detected a string format call using unindexed (positional) parameters without explicit numbering, which it flags as an error.

fix Either explicitly number your parameters (e.g., `'Hello {0}'.format('World')`) or if this is intentional, ignore the specific error code for that line or project-wide: `flake8 --ignore P101 my_file.py` or add `ignore = P101` to your `.flake8` config.
```
my_file.py:5:1: P201 format call uses too large index (INDEX)
```
cause A format string attempts to access an index that is out of bounds for the provided arguments.

fix Review the format string and the arguments provided to ensure all indexes are valid and correspond to an available argument. For example, `'{} {}'.format('a')` would trigger this as it expects two arguments but only one is given.
```
AttributeError: 'module' object has no attribute 'flake8_string_format'
```
cause You are attempting to import `flake8_string_format` directly into your Python code. It is a Flake8 plugin and is not designed for direct programmatic import and usage within application code.

fix Remove the `import flake8_string_format` statement. The plugin is automatically loaded by the `flake8` command-line tool when installed.

Warnings

breaking Version 0.3.0 removed support for running `flake8-string-format` as a standalone tool. It must now be used exclusively as a plugin for Flake8.
Fix: Ensure `flake8` is installed and run the checks using the `flake8` command-line tool.
gotcha Python 2.6 support is partial. The plugin may not detect implicit parameters as errors (P1XX) on Python 2.6, but might still report P301 if variable arguments are unused.
Fix: For full compatibility checks and consistent behavior, use Python 2.7+ or Python 3. For Python 2.6, be aware of the limitations regarding implicit parameter detection.
gotcha Error codes P102 ('docstring does contain unindexed parameters') and P103 ('other string does contain unindexed parameters') are prone to false positives and are generally recommended only for Python 2.6 projects where unindexed parameters are strictly forbidden.
Fix: Consider ignoring P102 and P103 by default using `--ignore P102,P103` in your `flake8` configuration, unless your project specifically targets Python 2.6 with a strict no-unindexed-parameters policy for all strings.

Install

pip install flake8 flake8-string-format Install with pip

Imports

flake8-string-format
```
No direct import is typically needed. Flake8 plugins are automatically discovered upon installation.
```
Users do not import this library directly into their Python code. It extends the functionality of the 'flake8' command-line tool.

Quickstart

After installation, `flake8-string-format` automatically integrates with Flake8. Simply run `flake8` on your project. The plugin will report errors using codes like P101 (unindexed parameters), P201 (missing arguments), and P301 (unused arguments). Errors can be ignored using the `--ignore` flag or by configuring your `.flake8` file.

# my_module.py
def example_function():
    message = 'Hello {}'.format('World') # P101: format string does contain unindexed parameters
    data = {'name': 'Alice'}
    greeting = 'Hello {name}'.format(**data)
    # The plugin checks string formatting. To run:
    # flake8 my_module.py
    # To ignore a specific error:
    # flake8 --ignore P101 my_module.py

view raw JSON →