diff options
| -rw-r--r-- | windy/point_forecast.py | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/windy/point_forecast.py b/windy/point_forecast.py index 4c269fe..558c03d 100644 --- a/windy/point_forecast.py +++ b/windy/point_forecast.py @@ -1,3 +1,7 @@ +""" +Module provides tools to deal with Windy's point forecast API. +""" + from dataclasses import dataclass from datetime import datetime from enum import Enum @@ -23,6 +27,9 @@ class _StrEnum(Enum): class Model(_StrEnum): + """ + Numerical models available for use with point forecast API. + """ AROME = "arome" GEOS5 = "geos5" GFS = "gfs" @@ -34,6 +41,9 @@ class Model(_StrEnum): class Level(_StrEnum): + """ + Selectable levels for some of the input parameters that support them. + """ SURFACE = "surface" H1000 = "1000h" H950 = "950h" @@ -52,6 +62,9 @@ class Level(_StrEnum): @dataclass class Request: + """ + Wraps raw JSON request expected by Windy's API. + """ key: str lat: float lon: float @@ -73,6 +86,10 @@ class Request: class EntryView: + """ + Allows to iterate over samples in Response in a zip-like manner, where all parameters for a given time point are + available via item access. + """ def __init__(self, response, index=0): self._response = response self._index = index @@ -94,6 +111,9 @@ class EntryView: @property def timestamp(self): + """ + Datetime object representing timestamp of the current entry. + """ return self._response.timestamps[self._index] def __getitem__(self, key): @@ -101,6 +121,17 @@ class EntryView: class Response: + """ + Wraps raw JSON response from the Windy's API to allow for easier access, converts all values to pint's + Quantities, and converts all timestamps into datetime objects. + + Can be used in a for-loop to access all samples via EntryView: + + >>> for entry in response: + >>> print(entry.timestamp, entry['temp-surface']) + + Otherwise, timestamps list and samples dictionary are available for direct access. + """ _INTERNAL_FIELDS = ('ts', 'units', 'warning') def __init__(self, registry, raw): @@ -114,9 +145,15 @@ class Response: return len(self.timestamps) def parameters(self) -> tuple: + """ + All of the available output parameters. + """ return tuple(self.samples.keys()) def entries(self) -> EntryView: + """ + Helper iterator to go over all of the samples in a zip-like manner. + """ return EntryView(self) def __iter__(self): @@ -125,6 +162,11 @@ class Response: @dataclass class PointForecast: + """ + Represents the point forecast endpoint bound to *path*. Once created it can be called with Request object or + with the same arguments that would be used to initialize the Request. The request is made using the passed + *ctx*, which is usually a Windy instance. + """ path: str def __call__(self, ctx, *args, **kwargs): |