Type hint api.py

[binste]

See #2951 for an overview of the type hinting efforts.

To dos:

• Make sure that UndefinedType always comes last in Unions.
• Parameter class is missing default values for attributes such as empty. See Add missing arguments to Parameter and add type hints #3173
• Add Altair core classes to type hints as well. E.g. if a string for the protection type is accepted then probably also ProtectionType is accepted? E.g. FieldName in transform_ methods? Can see which classes are accepted by looking at what the underlying classes accept, e.g. for transform_density, check what DensitiyTransform accepts
  • These places might also accept dictionaries, e.g. if they just pass it through to another Altair core classes.
• Need to add type hints for expressions expr (type hint as expr.core.Expression? How does it relate to ExprRef?) support for parameters which accept it such as projection. This is also not properly handled in the docstrings. Can view the underlying VL classes to see what they accept
  • If a string is accepted: Union[str, core.Expr, expr.core.Expression, UndefinedType]
  • If ExprRef: Union[core.ExprRef, UndefinedType]
• Where are Parameter accepted?
  • value parameters possibly everywhere where we also accept ExprRef as a to_dict call produces the same output. E.g. mark_circle(opacity=alt.Parameter(...)).
  • selection parameters in e.g. transform_filter

[mattijn]

One question @binste.

I notice this will introduce things like type: Union[str, UndefinedType] = Undefined, for .project() arguments.

But in an example as such:

import altair as alt
from vega_datasets import data

source = alt.topo_feature(data.world_110m.url, 'countries')

input_dropdown = alt.binding_select(options=[
    "albers",
    "albersUsa",
    "azimuthalEqualArea",
    "azimuthalEquidistant",
    "conicEqualArea",
    "conicEquidistant",
    "equalEarth",
    "equirectangular",
    "gnomonic",
    "mercator",
    "naturalEarth1",
    "orthographic",
    "stereographic",
    "transverseMercator"
], name='Projection ')
param_projection = alt.param(value="equalEarth", bind=input_dropdown)

alt.Chart(source, width=500, height=300).mark_geoshape(
    fill='lightgray',
    stroke='gray'
).project(
    type=alt.expr(param_projection.name)
).add_params(param_projection)

The type argument is alt.expr(param_projection.name), which is not of type str but of type ExprRef, will that be fine with the approach in this PR?

[binste]

Thanks for having a look @mattijn! Indeed, that is an outstanding item that I still need to tackle. I also need to add the acceptable Altair classes. For example core.ProjectionType for the type argument.

To make it more transparent what I still need to do, I moved the notes I had into the PR description.

[mattijn]

Thanks for adding the notes. I understand this is hard to do correctly. Thank you for the clarification!

[binste]

This is now ready to be reviewed. See the PR description for some more info on rules I tried to follow, etc. In general, I focused on public methods and functions and skipped some of the private ones as they would have been too much work for now.

I think these type hints will be very useful to users as they give a much more complete picture of what can be passed to various functions and methods, I definitely learned a lot doing this. However, I for sure have missed some types which would be accepted or maybe some hints are wrong. Given that it's so much code to cover, this is unavoidable but I think that's ok as it won't break working code and we can improve based on the feedback of users. Of course, if anyone already has inputs now, feel free to leave comments!

[mattijn]

Thanks for all this work @binste! I noticed some of the functions within api.py will not contain type hints after this PR, like:

• _consolidate_data
• _prepare_data
• _repr_mimebundle_
• serve
• _combine_subchart_data
• remove_data
• _needs_name
• _prepare_to_lift
• _remove_duplicate_params
• _combine_subchart_params
• _get_repeat_strings
• _extend_view_name
• _repeat_names
• _remove_layer_props
• remove_prop

Is this intended? Can a library be a typed library if not all functions contain type hints?

[binste]

Thank you @mattijn for having a look! That is indeed intended. My goal right now 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.

A library can be declared "typed" at any point in time, even if it would not have any type hints. It just signals to type checkers such as mypy that they can use any type hints that they might discover in the project. In general, type hinting in Python can be done gradually. The more hints you have, the more useful a type checker is, but it's perfectly fine to leave stuff out if it's too complicated/not worth the effort :)

[mattijn]

Thanks for the clarifications @binste. I'm approving with one little suggested change to place UndefinedType in the end as is done elsewhere.

[binste]

Thank you @mattijn for the review! Merging 🥳