Type hints in pvlib functional code

[echedey-ls]

Cross-referencing @kandersolar comment.

I'd like to propose using type hinting in pvlib's code. I feel like it makes sense to have some parameters type-hinted; it also helps IDEs to suggest code both to the user and the developer (I usually remove the hints before submitting a PR).
I'm against using it in "numeric" or "array-like" parameters (per docs definition), since what goes inside them is both easy to deduce and more flexible than we may think, for example when using polars probably.

Examples of (my) where to use:
#2039 (originally I put "str" type cause I forgot to remove it)

def get_standard_spectrum(
    wavelengths=None, *, reference: Literal["ASTM G173-03"] = "ASTM G173-03"
) -> pd.DataFrame:

vs

def get_standard_spectrum(wavelengths=None, *, standard="ASTM G173-03"):

#2046

def nonuniform_irradiance_deline_power_loss(
    rmad,
    model: Literal[
        "fixed-tilt", "single-axis-tracking"
    ] = "single-axis-tracking",
    fillfactor_ratio: float = None,
):

vs

def nonuniform_irradiance_deline_power_loss(
    rmad,
    model = "single-axis-tracking",
    fillfactor_ratio = None,
):

I really like these examples since it shows a parameter that can only take two values, else the function would fail. Saves some time looking up the docs and copy-pasting. Note the first function is designed to return always a dataframe.

Python package typing also defines other datatypes like Optional[...] which is an Union[..., None]. I prefer being short in words than explaining too much in a docstring. The signature fillfactor_ratio: float = None already shows it is optional (by convention).

What are your thoughts on using type hinting like this?

As a sidenote I dislike, defining the numeric or array-like datatypes is possible:

Numeric = Union[float, np.array, pd.Series]

then using

def my_func(input: Numeric):

[markcampanelli]

I think pvlib would indeed benefit from an improved mechanism to define and communicate the configuration options for function/method arguments. I myself would like to see numerics included here, but I sense that the numerics typing would probably the hardest (esp. to keep concise and unencumbering) because it’s the most expansive.

A bit of a rant here, but this is where I think “modern” Python is going a bit off the rails. IMHO, the language could really use builtin (immutable) constants and enum’s that are well thought out and integrated into the language, like Rust’s.

https://m.youtube.com/watch?v=z-0-bbc80JM&pp=ygUYTm8gYm9pbGVycGxhdGUgcnVzdCBlbnVt

[wholmgren]

#765 has a lot of relevant discussion (from 2 - 5 years ago). I suspect that numpy 2.0 brings new opportunities for typing in the pydata world but I have not kept up with it.

I am generally +1 on type hints in python but unsure for pvlib. That's mostly because I don't trust myself to make a good judgement on if type hints make it easier or harder for relative newcomers to pvlib to read or use the source code.

[adriesse]

easier or harder for relative newcomers to pvlib to read or use the source code.

...or indeed for existing users!