Install & Compatibility
Where this runs
tested against v1.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.012s · 19.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.010s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
options
✓ from flake8_polyfill import options
✗ parser.add_option(..., parse_from_config=True)
Directly using parser.add_option() with Flake8 3.x specific arguments like `parse_from_config` will break on Flake8 2.x. Use `options.register` for cross-version compatibility.
stdin
✓ from flake8_polyfill import stdin
✗ import pep8; stdin_value = pep8.get_stdin_value()
Flake8 2.6 changed from `pep8` to `pycodestyle` for stdin handling, and Flake8 3.0 removed monkey-patching altogether, making direct `pep8` or `pycodestyle` imports inconsistent. Use `stdin.monkey_patch()` for reliable cross-version stdin access.
version
✓ from flake8_polyfill import version
✗ import flake8; flake8.__version__
Flake8 2.x provides version as a string, while 3.x introduced `__version_info__` as a tuple for easier comparison. `flake8_polyfill.version.version_info` normalizes this for consistent version checks.
This quickstart demonstrates how to use `flake8-polyfill` to register options, handle Flake8 version comparisons, and hints at standard input handling within a custom Flake8 plugin, ensuring compatibility across Flake8 2.x and 3.x. The option registration uses `options.register` to handle differences in `add_option` arguments. Version checks use `version.version_info` for consistent tuple-based comparison. Standard input is shown commented out as it's typically set up globally for a plugin.
from flake8_polyfill import options, stdin, version
class MyFlake8Plugin:
name = 'my_plugin'
version = '1.0.0'
@classmethod
def add_options(cls, parser):
options.register(
parser,
'--my-custom-option',
default='default_value',
parse_from_config=True,
help='A custom option for my plugin.',
)
@classmethod
def parse_options(cls, values):
cls.my_custom_option = values.my_custom_option
def __init__(self, tree, filename):
self.tree = tree
self.filename = filename
# Example of stdin usage (though not typically in __init__)
# For actual use, call stdin.monkey_patch() once at plugin load.
# stdin.monkey_patch('all')
# self.stdin_value = stdin.get_stdin_value()
def run(self):
# Example of version comparison
if (3, 0) <= version.version_info < (4, 0):
# Logic specific to Flake8 3.x
pass
elif version.version_info < (3, 0):
# Logic specific to Flake8 2.x
pass
# Your linting logic here
yield (1, 0, 'MYP001 This is a custom check.', type(self))
Debug
Known issues
breakingFlake8 3.0 changed the `add_option` method, introducing new parameters like `parse_from_config`, `comma_separated_list`, and `normalize_paths` that are not present in Flake8 2.x. Directly using these in `parser.add_option()` will cause `TypeError` on older Flake8 versions.fixUse `from flake8_polyfill import options` and then `options.register(parser, ...)` instead of `parser.add_option(...)`. The `options.register` function handles the compatibility layer, making your code work on both versions.
affects: Flake8 2.x when trying to use 3.x option features directly.
breakingBetween Flake8 2.5 and 3.0, the way standard input (stdin) is retrieved by plugins changed significantly. Flake8 2.5 monkey-patched `pep8`, 2.6 switched to `pycodestyle`, and 3.0 no longer monkey-patches either, requiring plugins to manage stdin retrieval themselves or use Flake8's internal mechanisms.fixUse `from flake8_polyfill import stdin` and call `stdin.monkey_patch('all')`, `stdin.monkey_patch('pep8')`, or `stdin.monkey_patch('pycodestyle')` early in your plugin's lifecycle. Then, use `stdin.get_stdin_value()` to retrieve the content reliably across versions. affects: Flake8 2.5, 2.6, and 3.x when handling standard input.
gotchaFlake8 2.x represented its version as a string (`flake8.__version__`), while Flake8 3.x introduced `flake8.__version_info__` as a tuple for structured version comparison. Direct string comparisons can be error-prone or impossible for complex version logic.fixImport `version` from `flake8_polyfill` and use `version.version_info` for all version comparisons. This attribute provides a consistent tuple format `(major, minor, patch)` regardless of the underlying Flake8 version.
affects: Flake8 2.x and 3.x when performing version comparisons.
deprecatedThe `flake8-polyfill` library itself appears to be in an inactive maintenance state, with the last release in late 2017. While it addresses critical compatibility issues between older Flake8 versions (2.x and 3.x), its continued relevance might diminish as Flake8 evolves and older versions become less common.fixFor new plugins targeting recent Flake8 versions (e.g., 4.x, 5.x, 6.x, 7.x), directly consult the official Flake8 plugin developer guide for the most current best practices and APIs. `flake8-polyfill` is specifically designed for cross-compatibility between Flake8 2.x and 3.x.
affects: All versions of `flake8-polyfill`.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flake8_polyfill'
A Flake8 plugin being used requires 'flake8-polyfill' as a dependency for compatibility with different Flake8 versions, but the 'flake8-polyfill' package is not installed in the current environment.
fixInstall the 'flake8-polyfill' package using pip: `pip install flake8-polyfill`
AttributeError: 'module' object has no attribute 'normalize_paths'
An older version of Flake8 or one of its underlying dependencies (like `pep8`) is being used, which lacks the `normalize_paths` attribute. 'flake8-polyfill' was designed to provide a compatibility layer for such discrepancies between Flake8 2.x and 3.x.
fixEnsure `flake8-polyfill` is installed and that any custom plugin code utilizes `flake8_polyfill.options.register` for option handling, as it wraps `add_option` calls to manage version differences. Alternatively, update `flake8` and its dependencies to a more recent, compatible version if `flake8-polyfill` is not strictly required for other plugins.
AttributeError: 'OptionManager' object has no attribute 'config_options'
This error typically occurs when a Flake8 plugin, potentially expecting Flake8 2.x behavior, tries to directly access `parser.config_options` to register an option, but it is running with Flake8 3.x or later where the option parsing mechanism has changed, or `config_options` is not directly exposed this way. `flake8-polyfill` aims to abstract these differences.
fixEnsure the plugin uses `from flake8_polyfill import options` and then calls `options.register(parser, ...)` instead of directly manipulating the parser's attributes like `config_options`. This polyfill handles the correct registration method based on the underlying Flake8 version.
Upgrade
Version history
1.0.2latest on PyPI · released Dec 30, 2017
Audit
Dependencies
flake8requiredProvides compatibility helpers for Flake8 plugins.