Flake8 Polyfill

Warnings

• breaking Flake8 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.
  Fix: Use `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.
• breaking Between 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.
  Fix: Use `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.
• gotcha Flake8 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.
  Fix: Import `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.
• deprecated The `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.
  Fix: For 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.

Install

• pip install flake8-polyfill Install latest version

Imports

• options

  from flake8_polyfill import options

  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

  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

  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.

Quickstart

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))