clarify "should only check function signatures in stub files"

[JimJJewett]

Does that mean that

(1) Everything in the stub/interface file except function signatures signatures should be ignored?

or

(2) If there is a stub file, then annotations in the true source file should be ignored. This supports simpler annotations for documentation and more precise annotations for type-checking.

[gvanrossum]

I meant some approximation of (1). Classes and type aliases and a few other things should also be checked -- I really just meant that the checker should not insist on a return statement with an appropriately typed value, nor try to type-check any code in function bodies in stubs.

But (2) is also true -- the idea is that a type checker should entirely ignore the implementation if it has a stub. (Although at least Google wants to cross-check stubs with implementations too -- but that's outside the scope of the PEP.)

[vlasovskikh]

We discussed (2) with Jukka and Łukasz at PyCon and we agreed that for a *.pyi file a type checker should be allowed to read the definitions from the corresponding *.py file if it is necessary for the checker. There are two scenarios when this is helpful:

• The stub author wants to specify type hints / static method and class declarations only for some parts of the API of the module since others are not important / easy to analyze statically
• The *.pyi can't keep up to the changes to the *.py file so it's regularly out of date and misses some method definitions. Users of a type checker don't want to see false positive errors about new methods missing in *.pyi compared to *.py

[gvanrossum]

But isn't that a Quality of Implementation issue for the type checker? If not, do you have a specific suggestion for what the PEP needs to say?

[vlasovskikh]

@gvanrossum Yes, it should be up to the type checker. Maybe we could add something like "If there is a stub file for the *.py file available, then a type checker may ignore the corresponding *.py file or use it to extend the information in the stub."

[JimJJewett]

I like what vlasovskikh wrote, but just before that I would say something like:

The interface file is intended only to declare static type information, similar to what is provided by an inspect.Signature object. Therefore, this PEP does not standardize any meaning for the bodies of stub functions; notably, stub functions are not required to contain return statements, even when the function is documented with a returns annotation.

this PEP does

[vlasovskikh]

Actually, the typeshed docs might be a better place for documenting conventions for stub files, see issues #22 and #80.

[JimJJewett]

Is the PEP explicitly blessing typeshed as the standard 3rd party repository, analogous to PyPI?

Even if it is, it still might be useful to specify that PEP is not standardizing interpretation of anything in interface files beyond the typing module's own vocabulary and things that inspect.Signature cares about. (In other words, typeshed might or might not attribute meaning to function bodies or raise statements sometime Real Soon Now, but python itself isn't yet recognizing those meanings as standard.)

[gvanrossum]

The PEP is not explicitly blessing typeshed. I still believe the language in the PEP is all we need.