flake8-pyi

25.5.0 · active · verified Wed Apr 15

flake8-pyi is a plugin for Flake8 that specializes in linting `.pyi` stub files. It enforces type-hinting best practices and adheres to the typeshed style guide, providing specific warnings (codes starting with Y0). The library is actively maintained, with frequent releases that often introduce new error codes and adapt to changes in Python's typing ecosystem. The current version is 25.5.0.

Warnings

breaking Support for Python 3.8 was dropped in version 24.9.0. Users on Python 3.8 or older must upgrade their Python version to use recent `flake8-pyi` releases.
Fix: Upgrade your Python environment to 3.9 or newer.
gotcha When using `flake8-pyi` alongside other `flake8` plugins, there's a risk of false positives or inappropriate errors for `.pyi` files (e.g., regarding missing docstrings). It is recommended to run `flake8-pyi` in a dedicated CI environment if such conflicts arise.
Fix: Run `flake8-pyi` in a dedicated environment (e.g., a separate CI job or virtual environment) to avoid conflicts with other `flake8` plugins that might not be `.pyi` file-aware.
gotcha The `Y090` error code, which warns about `tuple[Type]` instead of `tuple[Type, ...]` (e.g., `tuple[int]` meaning a 1-element tuple vs. `tuple[int, ...]` meaning an arbitrary length tuple of ints), is disabled by default. It must be explicitly enabled using `--extend-select=Y090` in your `flake8` configuration.
Fix: Add `extend-select = Y090` to your `flake8` configuration file (e.g., `pyproject.toml`, `setup.cfg`).
breaking With version 24.1.0, `Y023` was updated to ban more imports from `typing_extensions` due to typeshed dropping support for Python 3.7. This might cause new linting errors if your `.pyi` files relied on specific `typing_extensions` imports that are now disallowed.
Fix: Review and update `typing_extensions` imports in `.pyi` files, preferring `typing` where available and compatible with the target Python versions.
gotcha New error codes are frequently introduced across releases. Users should regularly review their `flake8` configuration (`extend-select` and `extend-ignore`) after upgrading `flake8-pyi` to ensure desired checks are active and to prevent unexpected new linting failures.
Fix: Periodically review the changelog for new error codes and adjust `flake8` configuration (e.g., `pyproject.toml`) accordingly.

Install

pip install flake8 flake8-pyi Install with pip

Quickstart

To use flake8-pyi, first install both `flake8` and `flake8-pyi`. Then, you can run `flake8` directly on your `.pyi` files or your project directory. flake8-pyi automatically applies its checks to `.pyi` files. Configuration, such as enabling disabled error codes or ignoring others, can be managed in a `pyproject.toml` (under `[tool.flake8]`), `setup.cfg`, `tox.ini`, or `.flake8` file.

import os

# example.pyi
# def foo(x: int) -> str:
#     ...

# Configure flake8 to use flake8-pyi (e.g., in pyproject.toml):
# [tool.flake8]
# max-line-length = 88
# extend-ignore = E203, W503
# extend-select = Y090 # Example: enable Y090 which is disabled by default

# To run flake8 with flake8-pyi:
# flake8 example.pyi
# or for an entire project:
# flake8 .

view raw JSON →