-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Types that don't exist under their inspected name #24
Comments
Thanks for that detailed summary! Yes, we definitely have a lot of "hidden" types that, nonetheless, need to be exposed in the .pyi of a module. So far, the standard strategy seems to be to add a leading underscore and a comment, e.g. in _codecs.pyi:
I wonder whether PEP 484 should have some special syntax to hide things more explicitly. A class decorator, perhaps. But on the other hand, Python already has a convention (prefix "_") for marking things as private, and there's no really good reason for reinventing the wheel. I vote for always clearly marking them as "not exposed", though, to avoid confusion. Also, I'm not against sticking these special types into a file of their own ( |
For manually written stubs that are only used by checkers, the underscore rule makes sense. But remember I like the decorator approach - perhaps |
I'm quite surprised to find no return type declared for |
I think there's nothing actionable here at this point. We've been handling types like this by using leading underscores and I don't think that has caused problems. As we develop tools like https://github.com/JelleZijlstra/stubcheck, we'll be able to find any types that don't exist at runtime but that have crept into the stubs. |
Some classes don't exist under their inspected name. I define inspected name as
__module__.__qualname__
, but only if__qualname__
ends with__name__
, else__module__.__name__
.There are several (overlapping) cases:
types
..<locals>.
in__qualname__
), and may be created more than once.In some cases, later python versions do add a name for the type, but since we need to support all of them, we can't rely on that.
Note that
_builtin()
means either__builtin__
orbuiltins
, and_collections_abc
means either_collections_abc
,collections.abc
, or_abccoll
depending on Python version.Here is my initial mapping, based on importing every module (except test modules and dummy implementations, and being careful with a few modules that can't be imported in the wrong order) in the standard library (for CPython 2.7 and 3.2 though 3.5), checking every module for top-level attributes, and then finally checking
object.__subclasses__
. This is actually quite fast, just a few seconds.Notes:
.__class__
, that means that there is a single canonical instance.''
and there is a comment, see it.''
otherwise, I could not locate a canonical location for the class.My thought is to add a
stubtool.types
module similar totypes
and ask people to use it where appropriate. I think we do need to supply classes likebytearray_iterator
, even if most stubs will just useIterator[int]
(though we do need to do something about__length_hint__()
in general).Feedback?
The text was updated successfully, but these errors were encountered: