Published types aren't complete enough for Pyright/Pylance

It seems a bit unfair to file this as a “bug,” when really what’s going on is that the Python community is trying to figure out what a “typed” Python library looks like. In this case, what looks like perfectly reasonable code is, in another light, not explicit enough to allow tools to determine types.

(For clarity’s sake: Pylance is Microsoft’s new language-analysis extension for Python in VS Code. Pylance is closed source, but wraps the open source type engine Pyright.)

Expected Result

I have a repo at https://github.com/fluggo/pylance-test that demonstrates this issue. Pylance 2021.5.3 now knows to bypass the stub libraries when the installed library uses py.typed to declare itself typed, and so it should be able to see that this call to encode is wrong:

import jwt

# This should be an error because payload expects Dict[str, Any]
jwt.encode(payload='subsandwich')

Actual Result

Unfortunately it doesn’t, because according to Pyright, the type is unknown:

This is because Pyright has decided to play it safe with type inferences. The problematic code is at the bottom of api_jwt.py:

_jwt_global_obj = PyJWT()
encode = _jwt_global_obj.encode
decode_complete = _jwt_global_obj.decode_complete
decode = _jwt_global_obj.decode

These assignments look cut and dry—PyJWT is just creating a module-level alias for these functions. But it only looks that way to a programmer—putting our language lawyer hats on, these are variables, not constants, and they can be reassigned. Since that’s the case, what are the other valid values for these variables? Pyright can’t know, and can’t assume they will be constrained to the type of their first assignment.

There’s also the issue that, if an assignment like this requires any type inference at all, the results could be different from one analysis tool to the next. This is different from the situation in TypeScript, because in TypeScript, there’s only the one implementation of type inference, whereas Python doesn’t yet have a standard for inferring types.

In Pyright’s analysis, these variables need their own type annotations, and they recommend so in their Typing Guidance for Python Libraries.

The discussion on what to do here is still ongoing in microsoft/pyright#1846, but as things sit now, this is something library implementors will have to wrestle with. There’s also a bit more background in microsoft/pylance-release#1197.

Reproduction Steps

Grab my repo above and look at it with Pylance under VS Code. Apologies to anyone not using Poetry; I’m not well versed with the Python package managers.

System Information

$ python -m jwt.help

{
  "cryptography": {
    "version": "3.4.7"
  },
  "implementation": {
    "name": "CPython",
    "version": "3.9.4"
  },
  "platform": {
    "release": "19.6.0",
    "system": "Darwin"
  },
  "pyjwt": {
    "version": "2.1.0"
  }
}

[Tinche]

Looks fine to me in the latest VS Code.

The bigger problem is the annotations seem to be wrong, key isn’t just a string.

[kkirsche]

Stale doesn’t mean addressed