Currently, Altair only has a few type hints to help IDEs provide better autocompletion suggestions. More type hints would further help IDEs provide a better development experience as well as static type checkers to catch potential errors before they appear at runtime. Especially applications (e.g. a company-internal web application) and frameworks (e.g. Streamlit, Great Expectations) which want to tightly integrate with Altair could greatly profit from this.

I'd suggest the following approach for Altair which is in line with Using mypy with an existing codebase. Very open for inputs!

Should happen before the v5 release

• Type hints: Improve for encoding channel attributes #2949 Improvements in here could wait until after v5 but it also fixes some wrong type hints

v5 or minor release

I think it's preferable to have the following items more or less bundled into one release from which on Altair is declared as a library supporting type checks. This could be a minor release (5.1?) as it should not affect any runtime behaviour. Goal is to have as much as possible of the "public API" of Altair typed and then incrementally do the rest later on if we see value in it.

• Type hints: Add static type checker mypy #2950 after Type hints: Improve for encoding channel attributes #2949 is merged. This is a prerequisite for the following tasks so that mypy can tell us if the type hints are reasonable. We're in a fortunate position that we have many example charts in the tests folder which mypy can use for this.
• With mypy added in the previous step, we should aim to type as much as possible of the "public API" of Altair so users can get the most benefit out of this exercise. "internal" code can follow later. How about the following prioritization:
  • schemapi.py: Type hint schemapi.py #3142
  • altair/vegalite/v5/api.py: Type hint api.py #3143
  • Parts of folders "vegalite", "v5", and "utils": Type hints: Parts of folders "vegalite", "v5", and "utils" #2976
  • For the autogenerated files, we should infer types from the VL schema, see infer argument types from vegalite schema #2854: Type hints: Infer types from vegalite schema for autogenerated code #3208
  • Remaining files in utils: mimebundle.py, save.py: Type hint utils/save.py and utils/mimebundle.py #3248
  • Finishing touches Type hints: Finish type hints and mark package as typed #3263
    • Type hint Undefined as UndefinedType. Search for # Remove "ignore" statement once Undefined is no longer typed as Any in code which was introduced in Type hints: Add static type checker mypy #2950 to make mypy pass.
    • Go through current code and search for # type: ignore and see if any of those mentions can now be removed or better type hinted
    • Some types might still be marked as private as they start with an _. Search for _[A-Z] to find them and convert to public types if they are used in public parts of the codebase. This way, others can use the types themselves for code that depends on Altair. This was discussed in this issue.
      • Do we need better naming conventions for these types? Are the names clearly representing the intention/meaning of the types?
    • Declare Altair a library which supports type hints (probably by adding py.typed) as mentioned in the mypy docs (also note the mention of zip_safe and including the file in wheels and sdist, test this) → This allows mypy to use it when imported in other projects. Once Pylance shows non-public exports in completion suggestions microsoft/pylance-release#4059 is fixed we can also finish Restrict top-level autocompletion for VS Code (PyLance) #2927

@mattijn @joelostblom Would you be open to this? Input on the release cycle? I could review PRs related to this topic and create some myself.