Merge pull request #9 from M4RC0Sx/develop

Merge Develop

README.md

@@ -92,7 +92,7 @@ client = ESIOSAPYClient(
 indicators = client.indicators.list_all()
 
 # Get first file. here you should filter with your needed criteria
-#Usually, you are looking for a specific indicator
+# Usually, you are looking for a specific indicator
 indicator = indicators[0]
 
 # Get data between 2 dates, with time_trunc of 1 hour
@@ -106,7 +106,7 @@ To elaborate your filtering criteria, you can check out [the attributes of the I
 - [x] Archive model handling.
 - [x] Indicator model handling.
 - [x] OfferIndicator model handling.
-- [ ] Add docstrings to the entire project.
+- [x] Add docstrings to the entire project.
 - [ ] Archive JSON model handling.
 - [ ] Auction model handling.
 - [ ] Generate wiki with/and more elaborated docs.

esiosapy/client.py

@@ -12,7 +12,24 @@
 
 
 class ESIOSAPYClient:
+    """
+    A client for interacting with the ESIOS API.
+
+    This client provides access to various managers that handle specific
+    types of requests to the ESIOS API, such as archives, indicators, and
+    offer indicators. It simplifies the process of making requests by
+    managing authentication and constructing the necessary URLs.
+    """
+
     def __init__(self, token: str, base_url: str = ESIOS_API_URL):
+        """
+        Initializes the ESIOSAPYClient with an API token and a base URL.
+
+        :param token: The API token used for authentication.
+        :type token: str
+        :param base_url: The base URL for the ESIOS API. Defaults to ESIOS_API_URL.
+        :type base_url: str, optional
+        """
         self.token = token
         self.base_url = base_url
         self.request_helper = RequestHelper(base_url, token)
@@ -26,6 +43,22 @@ def __init__(self, token: str, base_url: str = ESIOS_API_URL):
     def raw_request(
         self, url: str, headers: Optional[Dict[str, str]] = None
     ) -> requests.Response:
+        """
+        Makes a raw GET request to a specified URL with optional headers.
+
+        This method allows for making a direct GET request to a specified URL.
+        It adds default headers to the request and handles URL construction
+        if the provided URL is relative.
+
+        :param url: The URL to which the GET request is made. If the URL is
+                    relative, it will be joined with the base URL.
+        :type url: str
+        :param headers: Optional headers to include in the request. If not provided,
+                        default headers will be added. Defaults to None.
+        :type headers: Optional[Dict[str, str]], optional
+        :return: The response object resulting from the GET request.
+        :rtype: requests.Response
+        """
         if headers is None:
             headers = {}
         headers = self.request_helper.add_default_headers(headers)

esiosapy/managers/archive_manager.py

@@ -7,13 +7,43 @@
 
 
 class ArchiveManager:
+    """
+    Manages archive-related operations for the ESIOS API.
+
+    This class provides methods to retrieve and filter archives from the ESIOS
+    API, such as listing all archives or filtering them by date or date range.
+    """
+
     def __init__(self, request_helper: RequestHelper) -> None:
+        """
+        Initializes the ArchiveManager with a RequestHelper.
+
+        :param request_helper: An instance of RequestHelper used to make API requests.
+        :type request_helper: RequestHelper
+        """
         self.request_helper = request_helper
 
     def _init_archive(self, archive: Dict[str, Union[str, int]]) -> Archive:
+        """
+        Initializes an Archive object from a dictionary of archive data.
+
+        :param archive: A dictionary containing archive data.
+        :type archive: Dict[str, Union[str, int]]
+        :return: An Archive object initialized with the provided data.
+        :rtype: Archive
+        """
         return Archive(**archive, raw=archive, _request_helper=self.request_helper)
 
     def list_all(self) -> List[Archive]:
+        """
+        Retrieves a list of all archives.
+
+        This method sends a GET request to the `/archives` endpoint and
+        returns a list of Archive objects representing all available archives.
+
+        :return: A list of Archive objects representing all archives.
+        :rtype: List[Archive]
+        """
         response = self.request_helper.get_request("/archives")
         return [self._init_archive(archive) for archive in response.json()["archives"]]
 
@@ -23,6 +53,24 @@ def list_by_date(
         date_type: Optional[ArchiveDateType] = None,
         taxonomy_terms: Optional[List[str]] = None,
     ) -> List[Archive]:
+        """
+        Retrieves a list of archives filtered by a specific date.
+
+        This method sends a GET request to the `/archives` endpoint with filters
+        based on the provided date, date type, and optional taxonomy terms.
+
+        :param target_dt: The target date for filtering archives. Can be a datetime
+                          object or an ISO 8601 formatted string.
+        :type target_dt: Union[datetime, str]
+        :param date_type: The type of date to filter by (e.g., publication date),
+                          defaults to None.
+        :type date_type: Optional[ArchiveDateType], optional
+        :param taxonomy_terms: A list of taxonomy terms to further filter the archives,
+                               defaults to None.
+        :type taxonomy_terms: Optional[List[str]], optional
+        :return: A list of Archive objects filtered by the specified date.
+        :rtype: List[Archive]
+        """
         if isinstance(target_dt, datetime):
             target_dt = target_dt.strftime("%Y-%m-%dT%H:%M:%S.%f%z")
 
@@ -42,6 +90,28 @@ def list_by_date_range(
         date_type: Optional[ArchiveDateType] = None,
         taxonomy_terms: Optional[List[str]] = None,
     ) -> List[Archive]:
+        """
+        Retrieves a list of archives filtered by a date range.
+
+        This method sends a GET request to the `/archives` endpoint with filters
+        based on the provided start and end dates, date type, and optional taxonomy
+        terms.
+
+        :param target_dt_start: The start date for filtering archives. Can be a datetime
+                                object or an ISO 8601 formatted string.
+        :type target_dt_start: Union[datetime, str]
+        :param target_dt_end: The end date for filtering archives. Can be a datetime
+                              object or an ISO 8601 formatted string.
+        :type target_dt_end: Union[datetime, str]
+        :param date_type: The type of date to filter by (e.g., publication date),
+                          defaults to None.
+        :type date_type: Optional[ArchiveDateType], optional
+        :param taxonomy_terms: A list of taxonomy terms to further filter the archives,
+                               defaults to None.
+        :type taxonomy_terms: Optional[List[str]], optional
+        :return: A list of Archive objects filtered by the specified date range.
+        :rtype: List[Archive]
+        """
         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/managers/indicator_manager.py

@@ -5,15 +5,50 @@
 
 
 class IndicatorManager:
+    """
+    Manages indicator-related operations for the ESIOS API.
+
+    This class provides methods to retrieve and search for indicators from the
+    ESIOS API, including listing all available indicators and searching for
+    indicators by name.
+    """
+
     def __init__(self, request_helper: RequestHelper) -> None:
+        """
+        Initializes the IndicatorManager with a RequestHelper.
+
+        :param request_helper: An instance of RequestHelper used to make API requests.
+        :type request_helper: RequestHelper
+        """
         self.request_helper = request_helper
 
     def _init_indicator(self, indicator: Dict[str, Union[str, int]]) -> Indicator:
+        """
+        Initializes an Indicator object from a dictionary of indicator data.
+
+        :param indicator: A dictionary containing indicator data.
+        :type indicator: Dict[str, Union[str, int]]
+        :return: An Indicator object initialized with the provided data.
+        :rtype: Indicator
+        """
         return Indicator(
             **indicator, raw=indicator, _request_helper=self.request_helper
         )
 
     def list_all(self, taxonomy_terms: Optional[List[str]] = None) -> List[Indicator]:
+        """
+        Retrieves a list of all indicators, optionally filtered by taxonomy terms.
+
+        This method sends a GET request to the `/indicators` endpoint and
+        returns a list of Indicator objects. If taxonomy terms are provided,
+        they are used to filter the indicators.
+
+        :param taxonomy_terms: A list of taxonomy terms to filter the indicators,
+                               defaults to None.
+        :type taxonomy_terms: Optional[List[str]], optional
+        :return: A list of Indicator objects representing all (or filtered) indicators.
+        :rtype: List[Indicator]
+        """
         params: Dict[str, Union[str, int, List[str]]] = {}
         if taxonomy_terms:
             params["taxonomy_terms[]"] = taxonomy_terms
@@ -25,6 +60,18 @@ def list_all(self, taxonomy_terms: Optional[List[str]] = None) -> List[Indicator
         ]
 
     def search(self, name: str) -> List[Indicator]:
+        """
+        Searches for indicators by name.
+
+        This method sends a GET request to the `/indicators` endpoint with a
+        search query, returning a list of Indicator objects that match the
+        specified name.
+
+        :param name: The name or part of the name to search for in indicators.
+        :type name: str
+        :return: A list of Indicator objects that match the search query.
+        :rtype: List[Indicator]
+        """
         response = self.request_helper.get_request("/indicators", params={"text": name})
         return [
             self._init_indicator(indicator)

esiosapy/managers/offer_indicator_manager.py

@@ -5,17 +5,53 @@
 
 
 class OfferIndicatorManager:
+    """
+    Manages offer indicator-related operations for the ESIOS API.
+
+    This class provides methods to retrieve offer indicators from the ESIOS API,
+    including listing all available offer indicators with optional filtering by
+    taxonomy terms.
+    """
+
     def __init__(self, request_helper: RequestHelper) -> None:
+        """
+        Initializes the OfferIndicatorManager with a RequestHelper.
+
+        :param request_helper: An instance of RequestHelper used to make API requests.
+        :type request_helper: RequestHelper
+        """
         self.request_helper = request_helper
 
     def _init_indicator(self, indicator: Dict[str, Union[str, int]]) -> OfferIndicator:
+        """
+        Initializes an OfferIndicator object from a dictionary of indicator data.
+
+        :param indicator: A dictionary containing offer indicator data.
+        :type indicator: Dict[str, Union[str, int]]
+        :return: An OfferIndicator object initialized with the provided data.
+        :rtype: OfferIndicator
+        """
         return OfferIndicator(
             **indicator, raw=indicator, _request_helper=self.request_helper
         )
 
     def list_all(
         self, taxonomy_terms: Optional[List[str]] = None
     ) -> List[OfferIndicator]:
+        """
+        Retrieves a list of all offer indicators, optionally filtered by taxonomy terms.
+
+        This method sends a GET request to the `/offer_indicators` endpoint and
+        returns a list of OfferIndicator objects. If taxonomy terms are provided,
+        they are used to filter the offer indicators.
+
+        :param taxonomy_terms: A list of taxonomy terms to filter the offer indicators,
+                               defaults to None.
+        :type taxonomy_terms: Optional[List[str]], optional
+        :return: A list of OfferIndicator objects representing all (or filtered)
+                 offer indicators.
+        :rtype: List[OfferIndicator]
+        """
         params: Dict[str, Union[str, int, List[str]]] = {}
         if taxonomy_terms:
             params["taxonomy_terms[]"] = taxonomy_terms