{"id":6638,"library":"flake8-pyi","title":"flake8-pyi","description":"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.","status":"active","version":"25.5.0","language":"python","source_language":"en","source_url":"https://github.com/PyCQA/flake8-pyi","tags":["flake8","linting","type hints","pyi","stub files","code quality"],"install":[{"cmd":"pip install flake8 flake8-pyi","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"flake8-pyi is a plugin for Flake8 and requires it to run.","package":"flake8"}],"imports":[],"quickstart":{"code":"import os\n\n# example.pyi\n# def foo(x: int) -> str:\n#     ...\n\n# Configure flake8 to use flake8-pyi (e.g., in pyproject.toml):\n# [tool.flake8]\n# max-line-length = 88\n# extend-ignore = E203, W503\n# extend-select = Y090 # Example: enable Y090 which is disabled by default\n\n# To run flake8 with flake8-pyi:\n# flake8 example.pyi\n# or for an entire project:\n# flake8 .","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer.","message":"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.","severity":"breaking","affected_versions":">=24.9.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Add `extend-select = Y090` to your `flake8` configuration file (e.g., `pyproject.toml`, `setup.cfg`).","message":"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.","severity":"gotcha","affected_versions":">=23.10.0"},{"fix":"Review and update `typing_extensions` imports in `.pyi` files, preferring `typing` where available and compatible with the target Python versions.","message":"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.","severity":"breaking","affected_versions":">=24.1.0"},{"fix":"Periodically review the changelog for new error codes and adjust `flake8` configuration (e.g., `pyproject.toml`) accordingly.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'25.5.0':67 'activ':43 'adapt':55 'adher':27 'best':24 'chang':57 'code':36,53,75 'current':64 'ecosystem':62 'enforc':20 'error':52 'file':18,74 'flake8':2,5,11,68 'flake8-pyi':1,4 'frequent':46 'guid':32 'hint':23,71 'introduc':50 'librari':41 'lint':15,69 'maintain':44 'new':51 'often':49 'plugin':9 'practic':25 'provid':33 'pyi':3,6,16,72 'python':59 'qualiti':76 'releas':47 'special':13 'specif':34 'start':37 'stub':17,73 'style':31 'type':22,61,70 'type-hint':21 'typesh':30 'version':65 'warn':35 'y0':39","created_at":"2026-04-15T18:36:30.635783+00:00","updated_at":"2026-04-16T15:04:52.052200+00:00","problems":[{"fix":"Rename your `TypeVar`, `ParamSpec`, or `TypeVarTuple` to begin with an underscore, for example, `_T = TypeVar('_T')`.","cause":"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.","error":"Y001 Names of TypeVars, ParamSpecs and TypeVarTuples in stubs should usually start with _."},{"fix":"Replace `pass` with `...` in empty function or class bodies within your `.pyi` file.","cause":"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.","error":"Y009 Empty body should contain ..., not pass."},{"fix":"Ensure that the body of any function in a stub file contains only `...`.","cause":"Stub files define interfaces, not implementations; therefore, function bodies in `.pyi` files should only contain an ellipsis (`...`) and no executable code.","error":"Y010 Function body must contain only ...."},{"fix":"Replace `typing.Union[A, B]` with `A | B` and `typing.Optional[A]` with `A | None`.","cause":"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]`).","error":"Y037 Use PEP 604 syntax instead of typing.Union and typing.Optional."},{"fix":"Remove quotes from type annotations in your `.pyi` file (e.g., change `'ClassName'` to `ClassName`).","cause":"Stub files inherently support forward references, making stringified (quoted) type annotations unnecessary and non-idiomatic, as they are not needed for runtime evaluation.","error":"Y020 Quoted annotations should never be used in stubs."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/PyCQA/flake8-pyi","docs":null,"changelog":"https://github.com/PyCQA/flake8-pyi/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/flake8-pyi/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing","type-stubs"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-15","next_check":"2026-07-14","install_tag":null}}