[Python-Dev] Experiences with Creating PEP 484 Stub Files

[Phil Thompson]

I've been adding support to the SIP wrapper generator for automatically generating PEP 484 compatible stub files so that future versions of PyQt can be shipped with them. By way of feedback I thought I'd share my experience, confusions and suggestions.

There are a number of things I'd like to express but cannot find a way to do so...

- objects that implement the buffer protocol
- type objects
- slice objects
- capsules
- sequences of fixed size (ie. specified in the same way as Tuple)
- distinguishing between instance and class attributes.

The documentation is incomplete - there is no mention of Set or Tuple for example.

I found the documentation confusing regarding Optional. Intuitively it seems to be the way to specify arguments with default values. However it is explained in terms of (for example) Union[str, None] and I (intuitively but incorrectly) read that as meaning "a str or None" as opposed to "a str or nothing".

bytes can be used as shorthand for bytes, bytearray and memoryview - but what about objects that really only support bytes? Shouldn't the shorthand be called something like AnyBytes?

Is there any recommended way to test the validity and completeness of stub files? What's the recommended way to parse them?

Phil