flake8-pyi

library25.5.0pypypiunverified

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.

testing type-stubs

pip install flake8 flake8-pyi

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · FLAKE8-PYI

flake8-pyi

testingpythonv25.5.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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 .

Debug

Known issues

breakingSupport 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.

affects: >=24.9.0

gotchaWhen 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.

affects: All

gotchaThe `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`).

affects: >=23.10.0

breakingWith 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.

affects: >=24.1.0

gotchaNew 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.

affects: All

Errors

Common errors & fixes

Y001 Names of TypeVars, ParamSpecs and TypeVarTuples in stubs should usually start with _.

Type variable names in stub files are expected to start with an underscore (`_`) to indicate they are internal to the stub and prevent accidental exposure.

fix

Rename your `TypeVar`, `ParamSpec`, or `TypeVarTuple` to begin with an underscore, for example, `_T = TypeVar('_T')`.

Y009 Empty body should contain ..., not pass.

In stub (.pyi) files, empty function or class bodies should explicitly use an ellipsis (`...`) instead of the `pass` keyword, as it is the conventional style for typeshed and type checkers.

fix

Replace `pass` with `...` in empty function or class bodies within your `.pyi` file.

Y010 Function body must contain only ....

Stub files define interfaces, not implementations; therefore, function bodies in `.pyi` files should only contain an ellipsis (`...`) and no executable code.

fix

Ensure that the body of any function in a stub file contains only `...`.

Y037 Use PEP 604 syntax instead of typing.Union and typing.Optional.

The stub file is using older `typing.Union` or `typing.Optional` syntax, while `flake8-pyi` encourages the more modern, concise PEP 604 syntax (e.g., `str | int` instead of `Union[str, int]`).

fix

Replace `typing.Union[A, B]` with `A | B` and `typing.Optional[A]` with `A | None`.

Y020 Quoted annotations should never be used in stubs.

Stub files inherently support forward references, making stringified (quoted) type annotations unnecessary and non-idiomatic, as they are not needed for runtime evaluation.

fix

Remove quotes from type annotations in your `.pyi` file (e.g., change `'ClassName'` to `ClassName`).

Upgrade

Version history

25.5.0latest on PyPI · released May 25, 2025

Audit

Dependencies

flake8requiredflake8-pyi is a plugin for Flake8 and requires it to run.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/PyCQA/flake8-pyi ↗

packagehttps://pypi.org/project/flake8-pyi/ ↗

changeloghttps://github.com/PyCQA/flake8-pyi/blob/main/CHANGELOG.md ↗