Python typing: do stubs take precedence over library sources?

Question

I'm splitting my code into multiple packages, which are installable via PyPI. Then these packages are used in a child package, where I want type information from "library" packages to be fully used. In order to have complete type checking, I'd like to use pyright / pylance, locally and in CI.

What is the recommended way to document types for a python library? I'm currently partially annotating types in the source code. Do I have to provide stubs? When using my library in other project, I get warnings like Stub file not found in vscode.

Specific questions:

1. Is having stubs a must for a python library if I want users to have access to typing?
2. Do stubs take precedence over source code of library if both have types?

Answer 1

I have an answer for 1.; you don't have to have a stub file. If your library includes a file named exactly py.typed, then everything in the same folder and it's children is proclaimed to be typed.

References:

1. https://peps.python.org/pep-0561/
2. https://blog.whtsky.me/tech/2021/dont-forget-py.typed-for-your-typed-python-package/

Answer 2

1. Is having stubs a must for a python library if I want users to have access to typing?

The Python typing documentation (How to provide type annotations?) states:

PEP 561 documents several ways type information can be provided for a library:

• inline type annotations (preferred)
• type stub files included in the package
• a separate companion type stub package
• type stubs in the typeshed repository

...

We recommend using the inline type annotations approach

So actually, using inline type annotations is the preferred way to go over type stubs.

As @yodogawa-mikio noted, you must add a marker file named py.typed to the packages you want to declare as typed.

---

2. Do stubs take precedence over source code of library if both have types?

For the resolution order, this is described in the Python Typing documentation: Distributing type information > Import resolution ordering.

The following is the order in which type checkers supporting this specification SHOULD resolve modules containing type information:

1. Stubs or Python source manually put in the beginning of the path. Type checkers SHOULD provide this to allow the user complete control of which stubs to use, and to patch broken stubs or inline types from packages. In mypy the $MYPYPATH environment variable can be used for this.
2. User code - the files the type checker is running on.
3. Typeshed stubs for the standard library. These will usually be vendored by type checkers, but type checkers SHOULD provide an option for users to provide a path to a directory containing a custom or modified version of typeshed; if this option is provided, type checkers SHOULD use this as the canonical source for standard-library types in this step.
4. Stub packages - these packages SHOULD supersede any installed inline package. They can be found in directories named foopkg-stubs for package foopkg.
5. Packages with a py.typed marker file - if there is nothing overriding the installed package, and it opts into type checking, the types bundled with the package SHOULD be used (be they in .pyi type stub files or inline in .py files).
6. If the type checker chooses to additionally vendor any third-party stubs (from typeshed or elsewhere), these SHOULD come last in the module resolution order.

Also, just above it is noted that:

type checkers MUST maintain the normal resolution order of checking *.pyi before *.py files.

So to sum it up:

• any external stub package will override the typing information of the package itself (be they stubs or inline annotations)
• inside the package itself, type stubs (.pyi files) will indeed take precedence over inline type annotations (inside .py files).