Skip to main content

A plugin for flake8 to enable linting .pyi files.

Project description

A plugin for Flake8 that provides specializations for type hinting stub files, especially interesting for linting typeshed.


  1. Adds the .pyi extension to the default value of the --filename command-line argument to Flake8. This means stubs are linted by default with this plugin enabled, without needing to explicitly list every file.
  2. Modifies PyFlakes runs for .pyi files to defer checking type annotation expressions after the entire file has been read. This enables support for first-class forward references that stub files use.

The latter should ideally be merged into flake8 as the integration is currently pretty brittle (might break with future versions of pyflakes, flake8, or due to interactions with other overly clever plugins).

List of warnings

This plugin reserves codes starting with Y0. The following warnings are currently emitted:

  • Y001: Names of TypeVars in stubs should start with _. This makes sure you don’t accidentally expose names internal to the stub.
  • Y002: If test must be a simple comparison against sys.platform or sys.version_info. Stub files support simple conditionals to indicate differences between Python versions or platforms, but type checkers only understand a limited subset of Python syntax, and this warning triggers on conditionals that type checkers will probably not understand.
  • Y003: Unrecognized sys.version_info check. Similar, but triggers on some comparisons involving version checks.
  • Y004: Version comparison must use only major and minor version. Type checkers like mypy don’t know about patch versions of Python (e.g. 3.4.3 versus 3.4.4), only major and minor versions (3.3 versus 3.4). Therefore, version checks in stubs should only use the major and minor versions. If new functionality was introduced in a patch version, pretend that it was there all along.
  • Y005: Version comparison must be against a length-n tuple.
  • Y006: Use only < and >= for version comparisons. Comparisons involving > and <= may produce unintuitive results when tools do use the full sys.version_info tuple.
  • Y007: Unrecognized sys.platform check. Platform checks should be simple string comparisons.
  • Y008: Unrecognized platform. To prevent you from typos, we warn if you use a platform name outside a small set of known platforms (e.g. “linux” and “win32”).
  • Y009: Empty body should contain “…”, not “pass”. This is just a stylistic choice, but it’s the one typeshed made.
  • Y010: Function body must contain only “…”. Stub files should not contain code, so function bodies should be empty. Currently, we make exceptions for raise statements and for assignments in __init__ methods.
  • Y011: All default values for typed function arguments must be “…”. Type checkers ignore the default value, so the default value is not useful information in a stub file.
  • Y012: Class body must not contain “pass”.
  • Y013: Non-empty class body must not contain “…”.
  • Y014: All default values for arguments must be “…”. A stronger version of Y011 that includes arguments without type annotations.
  • Y015: Attribute must not have a default value other than “…”.

The following warnings are disabled by default:

  • Y090: Use explicit attributes instead of assignments in __init__. This is a stricter version of Y010. Instead of:

    class Thing:
        def __init__(self, x: str) -> None:
            self.x = x

    you should write:

    class Thing:
        x: str
        def __init__(self, x: str) -> None: ...
  • Y091: Function body must not contain “raise”.

  • Y092: Top-level attribute must not have a default value.




Just run:

python3.6 test

Or if you prefer:


Note: tests require 3.6+ due to testing variable annotations.

Change Log


  • support flake8 3.8.0
  • introduce Y091 (function body must not contain “raise”)
  • introduce Y015 (attribute must not have a default value other than “…”)
  • introduce Y092 (top-level attribute must not have a default value)


  • update pyflakes dependency


  • support Python 3.7
  • add a check for non-ellipsis, non-typed arguments
  • add checks for checking empty classes
  • use –stdin-display-name as the filename when reading from stdin


  • introduce Y011


  • (release herp derp, don’t use)


  • introduce Y001 - Y010
  • introduce optional Y090


  • handle del statements in stub files


  • handle annotated assignments in 3.6+ with forward reference support


  • handle forward references during subclassing on module level
  • handle forward references during type aliasing assignments on module level


  • first published version
  • date-versioned


Glued together by Łukasz Langa and Jelle Zijlstra.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for flake8-pyi, version 20.5.0
Filename, size File type Python version Upload date Hashes
Filename, size flake8_pyi-20.5.0-py36-none-any.whl (9.6 kB) File type Wheel Python version py36 Upload date Hashes View
Filename, size flake8-pyi-20.5.0.tar.gz (13.9 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page