From 885c586d77cb2e1392620c343484fb50521f9dcf Mon Sep 17 00:00:00 2001
From: Aki <please@ignore.pl>
Date: Thu, 6 Oct 2022 21:36:18 +0200
Subject: Documented point forecast module

---
 windy/point_forecast.py | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

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):
-- 
cgit v1.1