Recommend a consistent naming scheme for stub-only packages

[coloursofnoise]

As per PEP 561 [1]:

The name of the stub package MUST follow the scheme foopkg-stubs for type stubs for the package named foopkg.

This is already correctly stated in libraries.rst [2]:

The name of the stub package should be the name of the runtime package suffixed with -stubs.

---

[1] https://peps.python.org/pep-0561/
[2] https://github.com/python/typing/blob/master/docs/source/libraries.rst#companion-type-stub-package

[ghost]

All commit authors signed the Contributor License Agreement.

[srittau]

Please note the PEP 561 talk about Python package names, i.e. what gets installed. This needs to end in -stubs, otherwise type checkers won't be able to find the stubs. The section above talks about distribution names (even if it calls it "package"), i.e. what gets distributed on PyPI. At least typeshed names its distribution packages types-. In theory any name can be chosen.

I'm not super happy with how this section is worded at the moment, since I would prefer if typeshed could "reserve" the types- prefix for security/name squatting reasons. (See also the discussion in pypi/warehouse#4164). But that discussion is outside the scope of our documentation.

[coloursofnoise]

Thanks for the clarification on this, I think it would be especially helpful to have both use-cases on a single page to reduce confusion. After looking around the only resource I could find that (in my opinion) clearly explains the difference between a distribution and a package is the packaging guide glossary [1].

---

[1] https://packaging.python.org/en/latest/glossary/