Dealing with untyped packages/libraries

[omar-abdelgawad]

Context

• I am using VSCode with Pylance and recently turned on Type Checking Mode to basic.
• Although I am familiar with type checkers from using mypy, I am new to Pyright.
• I am working on adding type information to an untyped codebase that uses wxPython, which is written in C and lacks type stubs.
• I aim to keep type hinting as minimal as possible.

The Problem

Since all functions in wx are untyped, I often encounter snippets like:

myEVT_SLIDER_CHANGED = wx.NewEventType()

Pyright identifies the type as Unknown:

so I just search the docs of the function and find that the return type is always an int so I annotate it as int:

myEVT_SLIDER_CHANGED: int = wx.NewEventType()

However, the variable’s type is still Unknown | int:

(Note: I have added the temporary variable for demonstration purposes only.)

This behavior differs from mypy:

myEVT_SLIDER_CHANGED: int = wx.NewEventType()
reveal_type(myEVT_SLIDER_CHANGED)  # mypy: int

I can't even change it by hinting the variable before the assignment:

or after it:

From my small search, I found no way whatsoever to convince pyright that the untyped wx.NewEventType() returns int which is frustrating for anyone using an old untyped package. The two commonly recommended methods to deal with this are explicit casting using int() or type casting using cast:

from typing import cast

var1 = int(wx.NewEventType())
reveal_type(var1)  # pyright: int
var2 = cast(int, wx.NewEventType())
reveal_type(var2)  # pyright: int

However, I don't like the first method because it not only changes functionality but also implies that wx.NewEventType() doesn’t return an int. The second method is better in my opinion but still seems forced and implies that the function's return type is cast to int because it is not initially an int.

My question is What is the best way to deal with untyped libraries like wxPython? given the above example.

[erictraut]

The best way to deal with untyped libraries is to create type stubs for the library in question. For details, refer to this documentation. You can provide type information for the subset of the library that you use and leave the remaining unannotated. If you create a full type stub, it would be great if you could contribute it back to the maintainers of the library so they can include the stub in their distribution. This would save other users of the library the hassle of duplicating the work in creating a type stub.

If you don't want to create a type stub file, you can still use the the library with pyright. However, you won't get the full benefits of type checking because pyright will need to assume that any symbols imported from the library have the type Unknown (which is pyright's name for an "implicit" Any).

I wouldn't recommend using an explicit cast call for the reasons you mention above. It makes your code less readable and doesn't provide any additional type safety — and arguably even reduces type safety in some cases.

One other point of clarification... You mentioned that you annotated myEVT_SLIDER_CHANGED with the type int. That tells pyright that this variable accepts only variables that are type compatible with int. If you attempt to assign a value that is incompatible with int, pyright will generate an error. If you assign a value whose type is compatible with int but is narrower than int (such Literal[2]), the pyright will further narrow the type of the variable after the assignment.

x: int
x = 3
reveal_type(x) # Literal[3]
x = 2
reveal_type(x) # Literal[2]
x = returns_int()
reveal_type(x) # int

If you assign a value whose type is Unknown, pyright narrows the type to int | Unknown.

x = returns_unknown()
reveal_type(x) # int | Unknown

This behavior allows strict-mode checks to detect when you've assigned an Unknown value to the variable — a condition that can mask type errors. To avoid this "typing hole", you need to eliminate the sources of Unknown types, which is why type stubs are so important when dealing with libraries that are written in languages other than Python.

[omar-abdelgawad]

Thank you very much for your detailed answer! I believe I have a much better grasp of the problem now.

I was going to ask if I can give an incomplete type stubs and leave the rest but I noticed that it is true after reading your answer again. It was really informative, thanks for your time.

[omar-abdelgawad]

Hey! I wanted to ask a follow-up question for writing stubs for 3rd party packages such as wxPython.

The thing about wxPython is that it comes with both .py and .pyi stub files which gives basic untyped definitions for autocompletion and shows the interface used (since it is a wrapper around a C library I guess). The stubs are of course untyped which is the problem I am trying to fix.

I wanted to write stubs for both mypy and better LSP support (Pylance which uses Pyright) so I want to satisfy two things:
1- Running mypy should infer types from the stubs I am writing.
2- I want the LSP support, autocompletion to be the same as it was and to even include types for function signatures, variables and so on.

Now when I just created a stubs/wx/init.pyi to start type hinting some stuff I lost all of the current LSP support and definitions for the .pyi files shipped with the package itself. This is a problem since I want to just type hint the used part of the package but I still want to have the rest of the package seen by the LSP at least for anyone else going to use wx in the future.

The question is Can I make pyright use two stubs for the same package in such a way that types are in one of them but it is incomplete and the other stub is complete but with no types?

[erictraut]

Running mypy should infer types from the stubs I am writing

Type inference should not be needed if you provide complete type declarations. Inference is used only in cases where annotations are missing.

Can I make pyright use two stubs for the same package

You cannot use two stubs for the same module, but you can provide your own "override" stubs for specific modules in the package.

I don't know enough about this particular package, but it might be easiest to simply copy all of the ".pyi" files out of the package and then augment the type information in the specific parts of the library that you care about.

If you make progress in improving the stubs, consider contributing them back to the maintainers of this package so others benefit from your work.

[omar-abdelgawad]

I don't know enough about this particular package, but it might be easiest to simply copy all of the ".pyi" files out of the package and then augment the type information in the specific parts of the library that you care about.

I think I will do that for now.