Tweak around docstring to make prettier sphinx autodocs.

[python_utils.git] / cached / weather_data.py

diff --git a/cached/weather_data.py b/cached/weather_data.py
index 8793bd315940b8ef16fb63d059b14b178fabc153..87c3260c0a5b90078f567f3a94bfcac8f03d5ea5 100644 (file)
--- a/cached/weather_data.py
+++ b/cached/weather_data.py
@@ -59,6 +59,13 @@ class WeatherData:
 @persistent.persistent_autoloaded_singleton()  # type: ignore
 class CachedWeatherData(persistent.Persistent):
     def __init__(self, weather_data: Dict[datetime.date, WeatherData] = None):
+        """C'tor.  Do not pass a dict except for testing purposes.
+
+        The @persistent_autoloaded_singleton decorator handles
+        invoking our load and save methods at construction time for
+        you.
+        """
+
         if weather_data is not None:
             self.weather_data = weather_data
             return
@@ -186,6 +193,15 @@ class CachedWeatherData(persistent.Persistent):
     @classmethod
     @overrides
     def load(cls) -> Any:
+
+        """Depending on whether we have fresh data persisted either uses that
+        data to instantiate the class or makes an HTTP request to fetch the
+        necessary data.
+
+        Note that because this is a subclass of Persistent this is taken
+        care of automatically.
+        """
+
         if persistent.was_file_written_within_n_seconds(
             config.config['weather_data_cachefile'],
             config.config['weather_data_stalest_acceptable'].total_seconds(),
@@ -199,6 +215,11 @@ class CachedWeatherData(persistent.Persistent):
 
     @overrides
     def save(self) -> bool:
+        """
+        Saves the current data to disk if required.  Again, because this is
+        a subclass of Persistent this is taken care of for you.
+        """
+
         import pickle
 
         with open(config.config['weather_data_cachefile'], 'wb') as wf: