Add return types to forcing methods

[sverhoeven]

In #261 the return types of the load(), load_foreign() and generate() methods in ewatercycle.forcing where removed due to using them in notebooks gave mypy errors. So when using these methods you fall back to dynamically typed code at runtime.

It would be nice if return types could be restored somehow so while coding you can autocomplete attributes of the forcing object without having to have forcing object at runtime.

[Peter9192]

Can we state the exact problem? Is it that all these methods generate model-specific <Model>Forcing objects? Somehow all forcing objects inherit from DefaultForcing, so if we could tell mypy that it should check the parent instead of the model-specific object, that might fix it, right?

[sverhoeven]

Yep, generate() returns an unknown sublclass of DefaultForcing while model constructor requires a specific DefaultForcing subcloass.

Also when mypy thinks forcing object is DefaultForcing, you can not use any of specialized attributes of a subclass without mypy complaining or performing casts.

For example:

import ewatercycle.forcing
import ewatercycle.models
from typing import cast

forcing = ewatercycle.forcing.generate(
    target_model='marrmot',
    dataset='ERA5',
    start_time='2010-01-01T00:00:00Z',
    end_time='2010-12-31T00:00:00Z',
    shape='Merrimack/Merrimack.shp'
) # :rtype DefaultForcing

forcing.forcing_file # does not work
marrmot_forcing = cast(MarrmotForcing, forcing)
marrmot_forcing.forcing_file # works

model = ewatercycle.models.MarrmotM14(version="2020.11", forcing: MarrmotForcing=marrmot_forcing)