summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--windy/point_forecast.py42
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):