TimeSample: resolved TODO on restricted selection of values for sampling

added first documentation to classes and their methods

toargridding/metadata.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass
 import numpy as np
 import pandas as pd
 
-from toargridding.toarstats_constants import STATISTICS_LIST
+from toargridding.toarstats_constants import STATISTICS_LIST, ALLOWED_SAMPLING_VALUES
 from toargridding.static_metadata import global_cf_attributes, TOARVariable
 
 date_created = datetime.utcnow().strftime("%Y-%m-dT%H:%M:%SZ")
@@ -21,26 +21,57 @@ Variables = Enum("Variables", [*DATA_VARIABLES, *COORDINATE_VARIABLES])
 TIME_FREQUENCIES = {"daily": "D", "monthly": "M", "yearly": "Y"}  # TODO test
 
 
-# TODO allow only valid sampling strings
 @dataclass
 class TimeSample:
+    """Sampling in time
+
+    provides conversion into different formats
+    """
+
     start: datetime
     end: datetime
     sampling: str
     
-    def as_datetime_index(self):
+    @property
+    def sampling(self) -> str: # TODO make better
+        """sampling for data request
+
+        Sampling, i.e. the period used for the calculation of a parameters within the TOAD DB
+        Allows only a limited number of supported sampling durations see toargridding.toarstats_constants.ALLOWED_SAMPLING_VALUES
+        """
+        return self._sampling
+    
+    @sampling.setter
+    def sampling(self, sampling : str):
+        if sampling not in ALLOWED_SAMPLING_VALUES:
+            raise ValueError(f"sampling: {sampling} is not in the list of supported samplings for toargridding.")
+        self._sampling = sampling
+
+    def as_datetime_index(self) -> pd.DatetimeIndex:
+        """Conversion to array with all sampled time points
+        """
         return pd.period_range(self.start, self.end, freq=self.frequency).to_timestamp()
 
     @property
-    def daterange_option(self):
+    def daterange_option(self) -> str:
+        """Conversion of range to a string
+
+        Range is given as start<=incuded days < end
+        """
         end_with_padding = self.end + timedelta(1)
         return f"{self.start.isoformat()},{end_with_padding.isoformat()}"
 
     @property
-    def frequency(self):
+    def frequency(self) -> str:
+        """Converts sampling argument from TOAR to Pandas 
+        """
         return TIME_FREQUENCIES[self.sampling]
 
-    def as_cf_index(self):
+    def as_cf_index(self) -> np.array:
+        """conversion to netCDF Climate and Forecast (CF) Metadata Convertions
+        
+        Calculates the duration in days relative to start time point.
+        """
         n_days = (self.end - self.start).days
         return np.arange(n_days + 1)
 

toargridding/toar_rest_client.py

@@ -32,6 +32,9 @@ class QueryOptions:
 
     @staticmethod
     def from_metadata(metadata: Metadata):
+        """Creation from Metadata object 
+
+        """
         return QueryOptions(
             daterange=metadata.time.daterange_option,
             variable_id=str(metadata.variable.toar_id),
@@ -41,6 +44,8 @@ class QueryOptions:
 
     @property
     def cache_key(self):
+        """creation to identify the request in the cache of known request.
+        """
         return "".join(asdict(self).values())