docs(indicator): add docstrings to indicator models

esiosapy/models/indicator/geo_agg.py

@@ -2,5 +2,21 @@
 
 
 class GeoAgg(Enum):
+    """
+    Enum representing the types of geographical aggregation methods.
+
+    This enum defines the methods that can be used to aggregate geographical data,
+    such as summing values or calculating their average.
+
+    :cvar SUM: Represents the aggregation method that sums up the values.
+    :vartype SUM: str
+    :cvar AVERAGE: Represents the aggregation method that calculates
+                   the average of the values.
+    :vartype AVERAGE: str
+    """
+
     SUM = "sum"
+    """Represents the aggregation method that sums up the values."""
+
     AVERAGE = "average"
+    """Represents the aggregation method that calculates the average of the values."""

esiosapy/models/indicator/geo_trunc.py

@@ -2,10 +2,50 @@
 
 
 class GeoTrunc(Enum):
+    """
+    Enum representing the types of geographical truncation levels.
+
+    This enum defines various levels of geographical regions that can be used to
+    truncate or categorize data, ranging from broad areas like countries to more
+    specific regions like towns or drainage basins.
+
+    :cvar COUNTRY: Represents the country level of geographical truncation.
+    :vartype COUNTRY: str
+    :cvar ELECTRIC_SYSTEM: Represents the electric system level
+                           of geographical truncation.
+    :vartype ELECTRIC_SYSTEM: str
+    :cvar AUTONOMOUS_COMMUNITY: Represents the autonomous community
+                                level of geographical truncation.
+    :vartype AUTONOMOUS_COMMUNITY: str
+    :cvar PROVINCE: Represents the province level of geographical truncation.
+    :vartype PROVINCE: str
+    :cvar ELECTRIC_SUBSYSTEM: Represents the electric subsystem level
+                              of geographical truncation.
+    :vartype ELECTRIC_SUBSYSTEM: str
+    :cvar TOWN: Represents the town level of geographical truncation.
+    :vartype TOWN: str
+    :cvar DRAINAGE_BASIN: Represents the drainage basin level
+                          of geographical truncation.
+    :vartype DRAINAGE_BASIN: str
+    """
+
     COUNTRY = "country"
+    """Represents the country level of geographical truncation."""
+
     ELECTRIC_SYSTEM = "electric_system"
+    """Represents the electric system level of geographical truncation."""
+
     AUTONOMOUS_COMMUNITY = "autonomous_community"
+    """Represents the autonomous community level of geographical truncation."""
+
     PROVINCE = "province"
+    """Represents the province level of geographical truncation."""
+
     ELECTRIC_SUBSYSTEM = "electric_subsystem"
+    """Represents the electric subsystem level of geographical truncation."""
+
     TOWN = "town"
+    """Represents the town level of geographical truncation."""
+
     DRAINAGE_BASIN = "drainage_basin"
+    """Represents the drainage basin level of geographical truncation."""

esiosapy/models/indicator/indicator.py

@@ -11,19 +11,75 @@
 
 
 class Indicator(BaseModel):
+    """
+    Represents an indicator with associated metadata and methods to retrieve
+    and process its data.
+
+    This class models an indicator object, which includes various attributes
+    such as its ID, name,
+    description, and raw data. It also provides methods to prettify
+    the description and to fetch
+    the indicator's data over specified date ranges with optional
+    geographical and time-based
+    aggregations and truncations.
+    """
+
     id: int
+    """The unique identifier for the indicator.
+
+    :type: int
+    """
+
     name: str
+    """The name of the indicator.
+
+    :type: str
+    """
+
     short_name: str
+    """The short name of the indicator.
+
+    :type: str
+    """
+
     description: str
+    """A detailed description of the indicator.
+
+    :type: str
+    """
+
     raw: Dict[str, Any]
+    """The raw dictionary containing the original data of the indicator.
+
+    :type: Dict[str, Any]
+    """
 
     _request_helper: RequestHelper
+    """An instance of RequestHelper used to make API requests.
+
+    :type: RequestHelper
+    """
 
     def __init__(self, **data: Any):
+        """
+        Initializes the Indicator class with the provided data.
+
+        :param data: The data used to initialize the indicator, including the
+                     request helper and other attributes.
+        :type data: Any
+        """
         super().__init__(**data)
         self._request_helper = data["_request_helper"]
 
     def prettify_description(self) -> str:
+        """
+        Converts the HTML description of the indicator into a plain text format
+        with better readability.
+
+        :raises ImportError: If `beautifulsoup4` is not installed.
+        :return: The prettified description as a plain text string.
+        :rtype: str
+        """
         try:
             from bs4 import BeautifulSoup  # type: ignore
         except ImportError:
@@ -49,6 +105,30 @@ def get_data(
         time_trunc: Optional[TimeTrunc] = None,
         all_raw_data: bool = False,
     ) -> Any:
+        """
+        Retrieves the data for the indicator based on the specified parameters.
+
+        :param target_dt_start: The start date and time for data retrieval.
+        :type target_dt_start: Union[datetime, str]
+        :param target_dt_end: The end date and time for data retrieval.
+        :type target_dt_end: Union[datetime, str]
+        :param geo_ids: A list of geographical identifiers
+                        to filter data, defaults to None.
+        :type geo_ids: Optional[List[str]], optional
+        :param geo_agg: The geographical aggregation method, defaults to None.
+        :type geo_agg: Optional[GeoAgg], optional
+        :param geo_trunc: The geographical truncation level, defaults to None.
+        :type geo_trunc: Optional[GeoTrunc], optional
+        :param time_agg: The time aggregation method, defaults to None.
+        :type time_agg: Optional[TimeAgg], optional
+        :param time_trunc: The time truncation level, defaults to None.
+        :type time_trunc: Optional[TimeTrunc], optional
+        :param all_raw_data: Whether to return all raw data or just
+                             the indicator values, defaults to False.
+        :type all_raw_data: bool, optional
+        :return: The retrieved indicator data, either as raw JSON or processed values.
+        :rtype: Any
+        """
         if isinstance(target_dt_start, datetime):
             target_dt_start = target_dt_start.strftime("%Y-%m-%dT%H:%M:%S.%f%z")
         if isinstance(target_dt_end, datetime):

esiosapy/models/indicator/time_agg.py

@@ -2,5 +2,21 @@
 
 
 class TimeAgg(Enum):
+    """
+    Enum representing the types of temporal aggregation methods.
+
+    This enum defines the methods that can be used to aggregate data over time,
+    such as summing values or calculating their average.
+
+    :cvar SUM: Represents the aggregation method that sums up the values over time.
+    :vartype SUM: str
+    :cvar AVERAGE: Represents the aggregation method that calculates
+                   the average of the values over time.
+    :vartype AVERAGE: str
+    """
+
     SUM = "sum"
+    """Represents the aggregation method that sums up the values."""
+
     AVERAGE = "average"
+    """Represents the aggregation method that calculates the avg of the values."""

esiosapy/models/indicator/time_trunc.py

@@ -2,10 +2,45 @@
 
 
 class TimeTrunc(Enum):
+    """
+    Enum representing the types of temporal truncation levels.
+
+    This enum defines various levels of time intervals that can be used to truncate or
+    categorize data, ranging from five minutes to a full year.
+
+    :cvar FIVE_MINUTES: Represents the five-minute level of temporal truncation.
+    :vartype FIVE_MINUTES: str
+    :cvar TEN_MINUTES: Represents the ten-minute level of temporal truncation.
+    :vartype TEN_MINUTES: str
+    :cvar FIFTHEEN_MINUTES: Represents the fifteen-minute level of temporal truncation.
+    :vartype FIFTHEEN_MINUTES: str
+    :cvar HOUR: Represents the hourly level of temporal truncation.
+    :vartype HOUR: str
+    :cvar DAY: Represents the daily level of temporal truncation.
+    :vartype DAY: str
+    :cvar MONTH: Represents the monthly level of temporal truncation.
+    :vartype MONTH: str
+    :cvar YEAR: Represents the yearly level of temporal truncation.
+    :vartype YEAR: str
+    """
+
     FIVE_MINUTES = "five_minutes"
+    """Represents the five-minute level of temporal truncation."""
+
     TEN_MINUTES = "ten_minutes"
+    """Represents the ten-minute level of temporal truncation."""
+
     FIFTHEEN_MINUTES = "fiftheen_minutes"
+    """Represents the fifteen-minute level of temporal truncation."""
+
     HOUR = "hour"
+    """Represents the hourly level of temporal truncation."""
+
     DAY = "day"
+    """Represents the daily level of temporal truncation."""
+
     MONTH = "month"
+    """Represents the monthly level of temporal truncation."""
+
     YEAR = "year"
+    """Represents the yearly level of temporal truncation."""