Designing the interface provided by the weather client

[shsms]

Installing the client

For now, we have to add the api package as a dependency

pip install "frequenz-api-weather @ git+https://github.com/frequenz-floss/[email protected]"

or once there's a release,

pip install "frequenz-api-weather == 0.1.0"

Import

from frequenz.client import weather

Initialization

import grpc.aio as grpcaio

client = weather.Client(
    grpcaio.insecure_channel(target),  # or secure channel with credentials
    target,
)

Live data streaming method

The stream_live_forecasts method starts a task which,

• calls the streaming grpc method ReceiveLiveWeatherForecast
• wrap the received data in a Forecast objects and puts them into a channel
• when the connection to the stream is lost, tries to automatically reconnect

Subsequent calls to stream_live_forecasts with the same arguments
would just reuse the or

weather_forecast_rx = client.stream_live_forecasts(
    locations=[
        weather.Location(lat1, long1), 
        weather.Location(lat2, long2),
        weather.Location(lat3, long3),
        weather.Location(lat4, long4),
    ],
    features=[
        weather.Feature.U_WIND_COMPONENT_100_METRE,
        weather.Feature.V_WIND_COMPONENT_100_METRE,
    ],
)

Using the streamed forecasts

Objects on the stream are opaque, and we can reach the data only
through methods.

to_ndarray_vlf for example would return a 3d numpy array, with
dimensions in this order:

• validity time
• location
• feature

This method can take optional filters for each of these dimensions

async for forecast in weather_forecast_rx:
    array = forecast.to_ndarray_vlf(
        validity_times=[1],
        features=[weather.Feature.U_WIND_COMPONENT_100_METRE],
    )

[shsms]

@cwasicki does this correspond somewhat to what we discussed? And does this interface look usable?

[cwasicki]

Yes it does! Is there a reason for not supporting specifying the validity_times also as an argument to the stream_live_forecasts method?

[shsms]

as discussed, I will make an issue to add a max_validity_time parameter to the grpc API.

[shsms]

Also @llucax and @matthias-wende-frequenz, maybe you have some comments as well, I will use experience from this design when presenting the client interface to everyone on Monday.

[llucax]

Nothing major, it looks clean and simple.

client = weather.Client(
    grpcaio.insecure_channel(target),  # or secure channel with credentials
    target,
)

IIRC the target is the IP:port or something like that, and we need to pass it twice because we can't get it from the grpcaio.insecure_channel, right? Also, it is only used to print log messages, right?

This is the only thing that doesn't look great IMHO, ideally we should not need to pass the same variable sort of twice.