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!

[wholmgren]

Cross reference to a usage issue that would have been avoided with type hints but did not require that pvlib explicitly support type hints: #2320 (reply in thread)

[PhilBrk8]

I would really like to see type hints in pvlib.
Since type hints would be implemented completely from zero (I assume they are not present anywhere yet?) I would propose to clarify some conventions beforehand.

Like using the +3.10 syntax for example:
int | float -- instead of -- Union[int, float]
float | None = None -- instead of -- Optional[float]
etc.

I came across this 'Coordinate'-type from pydantic and believe it would be beneficial for pvlib since it would be used in a lot of places.
Here an example of type hint implementations in the sunposition.py file:

from pydantic_extra_types.coordinate import Latitude, Longitude, Coordinate
#Coordinate = Tuple[Latitude, Longitude]


def get_solarposition(
    time: pd.DatetimeIndex | dt.datetime, # | pl.Series,
    coordinates: Coordinate,
    # or, to prevent breaking changes:
    #latitude: Latitude,
    #longitude: Longitude,
    altitude: float | None = None,
    pressure: float | None = None,
    method: Literal[
        "nrel_c", "nrel_numba", "nrel_numpy", "pyephem", "ephemeris"
    ] = "nrel_numpy",
    temperature: float = 12.0,
    **kwargs: Any,
) -> pd.DataFrame:

[markusr]

Another option is to use pandera for the DataFrames.

See DataFrame Models or DataFrame Schemas

import pandas as pd
import pandera as pa
from pandera.typing import Index, DataFrame, Series

class SolarPositionOutputSchema(pa.DataFrameModel):
    azimuth: Series[float]
    apparent_zenith: Series[float]
    apparent_elevation: Series[float]
    elevation: Series[float]
    zenith: Series[float] = pa.Field(ge=0, le=360, coerce=True) # or pa.Field(ge=-180, le=180, coerce=True)


@pa.check_types
def get_solarposition(
    time: pd.DatetimeIndex | dt.datetime, # | pl.Series,
    coordinates: Coordinate,
    # or, to prevent breaking changes:
    #latitude: Latitude,
    #longitude: Longitude,
    altitude: float | None = None,
    pressure: float | None = None,
    method: Literal[
        "nrel_c", "nrel_numba", "nrel_numpy", "pyephem", "ephemeris"
    ] = "nrel_numpy",
    temperature: float = 12.0,
    **kwargs: Any,
) -> DataFrame[SolarPositionOutputSchema]:
    <function code here>
    return   pd.DataFrame(...)