{"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":"en","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,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}