api-24sea 2.2.0__tar.gz → 2.2.1__tar.gz

{api_24sea-2.2.0 → api_24sea-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: api-24sea
-Version: 2.2.0
+Version: 2.2.1
 Summary: Facilitate the users' interaction with the 24SEA API (https://api/24sea/eu) by providing pandas interfaces to the API endpoints.
 Author-email: Pietro D'Antuono <pietro.dantuono@24sea.eu>
 Maintainer-email: Pietro D'Antuono <pietro.dantuono@24sea.eu>
@@ -27,7 +27,7 @@ Requires-Dist: pydantic
 Requires-Dist: shorthand_datetime>=0.2.1,<1.0.0
 Requires-Dist: httpx>=0.28.0,<1.0.0
 Requires-Dist: tqdm>=4.65.0,<5.0.0
-Requires-Dist: api-24sea-ai>=0.1.0 ; extra == "ai"
+Requires-Dist: api-24sea-ai>=0.2.0 ; extra == "ai"
 Requires-Dist: py-fatigue>=2.0.0 ; extra == "fatigue" and ( python_version>='3.10')
 Requires-Dist: py-fatigue>=1.0.0,<2.0.0 ; extra == "fatigue" and ( python_version<'3.10')
 Requires-Dist: swifter>=1.4.0 ; extra == "fatigue"
@@ -219,6 +219,9 @@ both, the metrics, and timestamps.
 -   Timestamps: Timezone-aware datetime, strings in ISO 8601 format, or
     shorthand strings compatible with the [shorthand_datetime
     package](https://pypi.org/project/shorthand-datetime/).
+-   `method`: Optional HTTP method for the backend request. Default is
+    `GET`. Supported values are `GET`, `POST`, `PUT`, `PATCH`, and
+    `DELETE`.
 
 ``` python
 # %%
@@ -395,6 +398,9 @@ Therefore, the following combinations are possible:
 -   Star schema as `dict[str, dict[str, Any]]`:
     `outer_join_on_timestamp` is irrelevant `as_star_schema=True`, and
     `as_dict=True`.
+-   `method`: Optional HTTP method for the backend request. Default is
+    `GET`. Supported values are `GET`, `POST`, `PUT`, `PATCH`, and
+    `DELETE`.
 
 ``` python
 # %%

{api_24sea-2.2.0 → api_24sea-2.2.1}/README.md

@@ -179,6 +179,9 @@ both, the metrics, and timestamps.
 -   Timestamps: Timezone-aware datetime, strings in ISO 8601 format, or
     shorthand strings compatible with the [shorthand_datetime
     package](https://pypi.org/project/shorthand-datetime/).
+-   `method`: Optional HTTP method for the backend request. Default is
+    `GET`. Supported values are `GET`, `POST`, `PUT`, `PATCH`, and
+    `DELETE`.
 
 ``` python
 # %%
@@ -355,6 +358,9 @@ Therefore, the following combinations are possible:
 -   Star schema as `dict[str, dict[str, Any]]`:
     `outer_join_on_timestamp` is irrelevant `as_star_schema=True`, and
     `as_dict=True`.
+-   `method`: Optional HTTP method for the backend request. Default is
+    `GET`. Supported values are `GET`, `POST`, `PUT`, `PATCH`, and
+    `DELETE`.
 
 ``` python
 # %%

{api_24sea-2.2.0 → api_24sea-2.2.1}/api_24sea/datasignals/__init__.py

@@ -144,6 +144,7 @@ class DataSignals:
         end_timestamp: Union[str, datetime.datetime],
         location: Optional[Union[List[str], str]] = None,
         force_cache_miss: bool = False,
+        method: str = "GET",
     ):
         """Get the data signals from the 24SEA API.
 
@@ -184,6 +185,7 @@ class DataSignals:
             as_dict=False,
             location=location,
             force_cache_miss=force_cache_miss,
+            method=method,
         )
 
     def as_dict(
@@ -310,6 +312,7 @@ class DataSignals:
         end_timestamp: Union[str, datetime.datetime],
         location: Optional[Union[List, str]] = None,
         force_cache_miss: bool = False,
+        method: str = "GET",
     ) -> Optional[
         Union[
             pd.DataFrame,
@@ -354,4 +357,5 @@ class DataSignals:
             end_timestamp=end_timestamp,
             location=location,
             force_cache_miss=force_cache_miss,
+            method=method,
         )

{api_24sea-2.2.0 → api_24sea-2.2.1}/api_24sea/datasignals/core.py

@@ -7,7 +7,6 @@ import logging
 from typing import Any, Dict, List, Optional, Union
 from warnings import simplefilter
 
-import httpx
 import pandas as pd
 from pandas import __version__ as pd_version
 
@@ -86,14 +85,21 @@ class API(AuthABC):
         permissions_overview: Optional[pd.DataFrame] = None,
     ):
         """Authenticate with username/password"""
-        self._username = username
-        self._password = password
-        self._metrics_overview = (
-            permissions_overview
-            if permissions_overview is not None
-            else self._metrics_overview
+        had_credentials = (
+            self._username is not None or self._password is not None
         )
-        self._auth = httpx.BasicAuth(self._username, self._password)
+        credentials_changed = (username, password) != (
+            self._username,
+            self._password,
+        )
+        self._set_auth(username, password)
+        if permissions_overview is not None:
+            self._permissions_overview = permissions_overview
+            self._metrics_overview = permissions_overview
+        elif had_credentials and credentials_changed:
+            self._permissions_overview = None
+            self._metrics_overview = None
+        self._selected_metrics = None
 
         r_profile = U.handle_request(
             f"{self.base_url}profile/",
@@ -104,7 +110,7 @@ class API(AuthABC):
         if (
             r_profile.status_code == 200 or self._metrics_overview is not None
         ):  # noqa: E501
-            self._authenticated = True
+            self._authenticated: bool = True
         # fmt: off
         logging.info(f"\033[32;1m{username} has access to "
                         f"\033[4m{U.BASE_URL}.\033[0m")
@@ -249,6 +255,7 @@ class API(AuthABC):
         threads: Optional[int] = None,
         location: Optional[Union[List, str]] = None,
         force_cache_miss: bool = False,
+        method: str = "POST",
     ) -> Optional[
         Union[
             pd.DataFrame,
@@ -310,6 +317,8 @@ class API(AuthABC):
         force_cache_miss : bool, optional
             Whether to force a cache miss on the backend data endpoint.
             Default is False.
+        method : str, optional
+            HTTP method to use for the backend request. Default is ``"GET"``.
 
         Returns
         -------
@@ -336,6 +345,7 @@ class API(AuthABC):
             as_dict=as_dict,
             as_star_schema=as_star_schema,
             force_cache_miss=force_cache_miss,
+            method=method,
         )
         logging.info(
             f"\n\033[32;1mRequested time range:\033[0;34m "
@@ -373,6 +383,7 @@ class API(AuthABC):
                         self._auth,
                         timeout,
                         force_cache_miss=query.force_cache_miss,
+                        method=query.method,
                     ): site
                     for site, group in grouped_metrics
                 }
@@ -385,7 +396,8 @@ class API(AuthABC):
                     _get_group_locations(group),
                     query.start_timestamp, query.end_timestamp, query.headers,
                     group, self._auth, timeout,
-                    force_cache_miss=query.force_cache_miss))
+                    force_cache_miss=query.force_cache_miss,
+                    method=query.method))
                 )
         # fmt: on
         # data_frames.append(pd.DataFrame(r_.json()))
@@ -436,6 +448,7 @@ class API(AuthABC):
         timeout: int = 3600,
         threads: Optional[int] = None,
         location: Optional[Union[List, str]] = None,
+        method: str = "GET",
     ) -> Union[
         pd.DataFrame, Dict[str, Union[Dict[str, pd.DataFrame], Dict[str, Any]]]
     ]:
@@ -466,6 +479,8 @@ class API(AuthABC):
             The location name or List of location names. This is a legacy
             parameter, and it is deprecated. Please use the `locations`
             parameter instead.
+        method : str, optional
+            HTTP method to use for the backend request. Default is ``"GET"``.
 
         Returns
         -------
@@ -483,6 +498,7 @@ class API(AuthABC):
             location=location,
             metrics=metrics,
             headers=headers,
+            method=method,
         )
 
         logging.info(
@@ -516,6 +532,7 @@ class API(AuthABC):
                         group,
                         self._auth,
                         timeout,
+                        method=query.method,
                     ): site
                     for site, group in grouped_metrics
                 }
@@ -533,7 +550,8 @@ class API(AuthABC):
                                            query.start_timestamp,
                                            query.end_timestamp,
                                            query.headers, group,
-                                           self._auth, timeout)
+                                           self._auth, timeout,
+                                           method=query.method)
                 if isinstance(result, list):
                     stats_list.extend(result)
                 else:
@@ -564,6 +582,7 @@ class API(AuthABC):
         timeout: int = 3600,
         threads: Optional[int] = None,
         location: Optional[Union[List, str]] = None,
+        method: str = "GET",
     ) -> Union[
         pd.DataFrame, Dict[str, Union[Dict[str, pd.DataFrame], Dict[str, Any]]]
     ]:
@@ -594,6 +613,8 @@ class API(AuthABC):
             The location name or List of location names. This is a legacy
             parameter, and it is deprecated. Please use the `locations`
             parameter instead.
+        method : str, optional
+            HTTP method to use for the backend request. Default is ``"GET"``.
 
         Returns
         -------
@@ -611,6 +632,7 @@ class API(AuthABC):
             location=location,
             metrics=metrics,
             headers=headers,
+            method=method,
         )
 
         logging.info(
@@ -644,6 +666,7 @@ class API(AuthABC):
                         group,
                         self._auth,
                         timeout,
+                        method=query.method,
                     ): site
                     for site, group in grouped_metrics
                 }
@@ -661,7 +684,8 @@ class API(AuthABC):
                                            query.start_timestamp,
                                            query.end_timestamp,
                                            query.headers, group,
-                                           self._auth, timeout)
+                                           self._auth, timeout,
+                                           method=query.method)
                 if isinstance(result, list):
                     stats_list.extend(result)
                 else:
@@ -694,6 +718,7 @@ class API(AuthABC):
         timeout: int = 3600,
         threads: Optional[int] = None,
         location: Optional[Union[List, str]] = None,
+        method: str = "GET",
     ) -> Union[
         pd.DataFrame, Dict[str, Union[Dict[str, pd.DataFrame], Dict[str, Any]]]
     ]:
@@ -734,6 +759,8 @@ class API(AuthABC):
             The location name or List of location names. This is a legacy
             parameter, and it is deprecated. Please use the `locations`
             parameter instead.
+        method : str, optional
+            HTTP method to use for the backend request. Default is ``"GET"``.
 
         Returns
         -------
@@ -754,6 +781,7 @@ class API(AuthABC):
             sampling_interval_seconds=sampling_interval_seconds,
             as_dict=as_dict,
             headers=headers,
+            method=method,
         )
 
         logging.info(
@@ -789,6 +817,7 @@ class API(AuthABC):
                         group,
                         self._auth,
                         timeout,
+                        method=query.method,
                     ): site
                     for site, group in grouped_metrics
                 }
@@ -808,6 +837,7 @@ class API(AuthABC):
                     group,
                     self._auth,
                     timeout,
+                    method=query.method,
                 ))
         # fmt: on
         # av_list is a list of lists, I need to expand it to a single list
@@ -829,6 +859,7 @@ class API(AuthABC):
         self,
         sites: Union[str, List[str]],
         locations: Optional[Union[List[str], str]],
+        method: str = "GET",
     ) -> pd.DataFrame:
         """Get oldest timestamp for one or multiple sites (sync)."""
         all_dfs = []
@@ -836,38 +867,61 @@ class API(AuthABC):
             sites = [sites]
         import concurrent.futures
 
-        def fetch_oldest_timestamp_for_site(site):
-            query = S.GetOldestTimestampSchema(site=site, locations=locations)
+        queries = []
+        for site in sites:
+            query = S.GetOldestTimestampSchema(
+                site=site, locations=locations, method=method
+            )
             query_df = query.get_selected_locations(self._metrics_overview)
             query_locs = query_df.location.to_list()
-            query_site = str(query_df.site.iloc[0]).lower()
-            # fmt: off
-            params: Dict[str, Union[str, List[str]]] = {"project": query_site}
-            params["locations"] = ",".join(query_locs).lower()
-            r_ = U.handle_request(f"{self.base_url}oldest_timestamp/",
-                                  params, self._auth,
-                                  query.headers or {"accept": "application/json"})  # pylint: disable=C0301  # noqa: E501
-            # fmt: on
-            js = r_.json()
-            if js == []:
-                logging.warning(
-                    f"\033[33;1m⚠️ No data found for {query.site}.\033[0m"
+            queries.append(
+                (
+                    str(query_df.site.iloc[0]).lower(),
+                    ",".join(query_locs),
+                    query.headers or {"accept": "application/json"},
+                    query.method,
                 )
-            return pd.DataFrame(js)
+            )
 
         try:
             with concurrent.futures.ThreadPoolExecutor(
                 max_workers=len(sites), thread_name_prefix="24SEA"
             ) as executor:
                 future_to_site = {
-                    executor.submit(fetch_oldest_timestamp_for_site, site): site
-                    for site in sites
+                    executor.submit(
+                        U.fetch_oldest_timestamp_sync,
+                        f"{self.base_url}oldest_timestamp/",
+                        query_site,
+                        query_locations,
+                        query_headers,
+                        self._auth,
+                        3600,
+                        False,
+                        query_method,
+                    ): query_site
+                    for query_site, query_locations, query_headers, query_method in queries
                 }
             for future in concurrent.futures.as_completed(future_to_site):
                 all_dfs.append(future.result())
         except RuntimeError:
-            for site in sites:
-                all_dfs.append(fetch_oldest_timestamp_for_site(site))
+            for (
+                query_site,
+                query_locations,
+                query_headers,
+                query_method,
+            ) in queries:
+                all_dfs.append(
+                    U.fetch_oldest_timestamp_sync(
+                        f"{self.base_url}oldest_timestamp/",
+                        query_site,
+                        query_locations,
+                        query_headers,
+                        self._auth,
+                        3600,
+                        False,
+                        query_method,
+                    )
+                )
         return (
             pd.concat(all_dfs, ignore_index=True) if all_dfs else pd.DataFrame()
         )
@@ -883,6 +937,7 @@ class API(AuthABC):
         headers: Optional[Dict[str, str]] = None,
         timeout: int = 3600,
         threads: Optional[int] = None,
+        method: str = "GET",
     ) -> Dict[str, Any]:
         """
         Run get_stats for predefined intervals:
@@ -915,6 +970,7 @@ class API(AuthABC):
                 headers=headers,
                 timeout=timeout,
                 threads=threads,
+                method=method,
             )
         return results
 
@@ -973,6 +1029,7 @@ class AsyncAPI(API):
         timeout: int = 1800,
         location: Optional[Union[List, str]] = None,
         force_cache_miss: bool = False,
+        method: str = "POST",
     ) -> Optional[
         Union[
             pd.DataFrame,
@@ -1042,6 +1099,8 @@ class AsyncAPI(API):
         force_cache_miss : bool, optional
             Whether to force a cache miss on the backend data endpoint.
             Default is False.
+        method : str, optional
+            HTTP method to use for the backend request. Default is ``"GET"``.
 
         Returns
         -------
@@ -1066,6 +1125,7 @@ class AsyncAPI(API):
             as_dict=as_dict,
             as_star_schema=as_star_schema,
             force_cache_miss=force_cache_miss,
+            method=method,
         )
 
         metrics_overview = await self.get_metrics_overview()
@@ -1086,7 +1146,8 @@ class AsyncAPI(API):
                         query.start_timestamp, query.end_timestamp,
                         query.headers, group, self._auth, timeout,
                         max_retries,
-                        force_cache_miss=query.force_cache_miss)
+                        force_cache_miss=query.force_cache_miss,
+                        method=query.method)
              for site, group in grouped_metrics]
         chunk_size_dict = U.estimate_chunk_size(
             tasks,
@@ -1154,6 +1215,7 @@ class AsyncAPI(API):
         self,
         sites: Union[str, List[str]],
         locations: Optional[Union[List[str], str]],
+        method: str = "GET",
     ) -> pd.DataFrame:
         """Get oldest timestamp for one or multiple sites (async).
 
@@ -1175,7 +1237,9 @@ class AsyncAPI(API):
         if isinstance(sites, str):
             sites = [sites]
         for site in sites:
-            query = S.GetOldestTimestampSchema(site=site, locations=locations)
+            query = S.GetOldestTimestampSchema(
+                site=site, locations=locations, method=method
+            )
             query_df = query.get_selected_locations(self._metrics_overview)
             query_locs = query_df.location.to_list()
             query_site = str(query_df.site.iloc[0]).lower()
@@ -1189,6 +1253,7 @@ class AsyncAPI(API):
                     3600,
                     5,
                     False,
+                    query.method,
                 )
             )
         results = await asyncio.gather(*tasks)
@@ -1209,6 +1274,7 @@ class AsyncAPI(API):
         headers: Optional[Dict[str, str]] = None,
         timeout: int = 3600,
         location: Optional[Union[List, str]] = None,
+        method: str = "GET",
     ) -> Union[
         pd.DataFrame, Dict[str, Union[Dict[str, pd.DataFrame], Dict[str, Any]]]
     ]:
@@ -1254,6 +1320,7 @@ class AsyncAPI(API):
             location=location,
             metrics=metrics,
             headers=headers,
+            method=method,
         )
 
         logging.info(
@@ -1278,7 +1345,7 @@ class AsyncAPI(API):
                         _get_group_locations(group),
                         query.start_timestamp, query.end_timestamp,
                         query.headers, group, self._auth, timeout,
-                        5, True)
+                        5, True, method=query.method)
              for site, group in grouped_metrics]
         # fmt: on
         stats_list = await U.gather_in_chunks(
@@ -1310,6 +1377,7 @@ class AsyncAPI(API):
         headers: Optional[Dict[str, str]] = None,
         timeout: int = 3600,
         location: Optional[Union[List, str]] = None,
+        method: str = "GET",
     ) -> Union[
         pd.DataFrame, Dict[str, Union[Dict[str, pd.DataFrame], Dict[str, Any]]]
     ]:
@@ -1355,6 +1423,7 @@ class AsyncAPI(API):
             location=location,
             metrics=metrics,
             headers=headers,
+            method=method,
         )
 
         logging.info(
@@ -1380,7 +1449,7 @@ class AsyncAPI(API):
                                     _get_group_locations(group),
                                     query.start_timestamp, query.end_timestamp,
                                     query.headers, group, self._auth, timeout,
-                                    5, True)
+                                    5, True, method=query.method)
                  for site, group in grouped_metrics]
         # fmt: on
         stats_list = await U.gather_in_chunks(
@@ -1414,6 +1483,7 @@ class AsyncAPI(API):
         headers: Optional[Dict[str, str]] = None,
         timeout: int = 3600,
         location: Optional[Union[List, str]] = None,
+        method: str = "GET",
     ) -> Union[
         pd.DataFrame, Dict[str, Union[Dict[str, pd.DataFrame], Dict[str, Any]]]
     ]:
@@ -1472,6 +1542,7 @@ class AsyncAPI(API):
             sampling_interval_seconds=sampling_interval_seconds,
             as_dict=as_dict,
             headers=headers,
+            method=method,
         )
 
         logging.info(
@@ -1505,6 +1576,7 @@ class AsyncAPI(API):
                 self._auth,
                 timeout,
                 5,  # max_retries
+                query.method,
             )
             for site, group in grouped_metrics
         ]
@@ -1554,6 +1626,7 @@ class AsyncAPI(API):
         as_dict: bool = False,
         headers: Optional[Dict[str, str]] = None,
         timeout: int = 3600,
+        method: str = "GET",
     ) -> Dict[str, Any]:
         """
         Async version of get_stats_predefined_intervals.
@@ -1579,6 +1652,7 @@ class AsyncAPI(API):
                 as_dict=as_dict,
                 headers=headers,
                 timeout=timeout,
+                method=method,
             )
 
         tasks = {name: _run(s, e) for name, (s, e) in intervals.items()}

{api_24sea-2.2.0 → api_24sea-2.2.1}/api_24sea/datasignals/schemas.py

@@ -31,6 +31,7 @@ class BaseDataSignalSchema(U.BaseModel):
     as_dict: Optional[bool] = False
     as_star_schema: Optional[bool] = False
     headers: Optional[Dict[str, str]] = {"accept": "application/json"}
+    method: str = "GET"
 
     def __init__(self, **data):
         data = self._normalize_deprecated_location_input(data)
@@ -116,6 +117,11 @@ class BaseDataSignalSchema(U.BaseModel):
             return {"accept": "application/json"}
         return v
 
+    @U.field_validator("method", mode="before")
+    def validate_method(cls, v: str) -> str:
+        """Validate and normalize request method input."""
+        return U.normalize_http_method(v)
+
     @property
     def query_str(self) -> str:
         """Build a query string based on self."""
@@ -144,10 +150,13 @@ class BaseDataSignalSchema(U.BaseModel):
             site=lambda x: x["site"].str.lower(),
             location=lambda x: x["location"].str.upper(),
         )
+        groupby_key: Union[str, List[str]] = (
+            groupby_columns[0] if len(groupby_columns) == 1 else groupby_columns
+        )
         if self.metrics in (["all"], "all"):
             group_base = normalized[["site", "location"]].drop_duplicates()
-            return group_base.assign(metric="all").groupby(groupby_columns)
-        return normalized.groupby(groupby_columns)
+            return group_base.assign(metric="all").groupby(groupby_key)
+        return normalized.groupby(groupby_key)
 
     # @lru_cache
     def group_metrics(self, df: Optional[pd.DataFrame]) -> DataFrameGroupBy:
@@ -175,6 +184,7 @@ class GetOldestTimestampSchema(U.BaseModel):
     site: str  # renamed from 'sites' to match caller
     locations: Optional[Union[str, List[str]]] = None
     headers: Optional[Dict[str, str]] = {"accept": "application/json"}
+    method: str = "GET"
 
     @U.field_validator("locations", mode="before")
     def validate_locations(cls, v) -> Optional[str]:
@@ -202,6 +212,11 @@ class GetOldestTimestampSchema(U.BaseModel):
             return v
         raise TypeError("headers must be a dictionary")
 
+    @U.field_validator("method", mode="before")
+    def validate_method(cls, v: str) -> str:
+        """Validate and normalize request method input."""
+        return U.normalize_http_method(v)
+
     @property
     def query_str(self) -> str:
         # fmt: off

{api_24sea-2.2.0 → api_24sea-2.2.1}/api_24sea/utils.py

@@ -9,7 +9,16 @@ import time
 import warnings
 from collections import defaultdict
 from types import CoroutineType
-from typing import Any, DefaultDict, Dict, Iterable, List, Optional, Union
+from typing import (
+    Any,
+    DefaultDict,
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Tuple,
+    Union,
+)
 
 import httpx
 import pandas as pd
@@ -94,6 +103,8 @@ def run_tqdm(
 
 
 BASE_URL = "https://api.24sea.eu/routes/v1/"
+SUPPORTED_HTTP_METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE")
+SPECIAL_QUERY_PARAM_KEYS = ("include_cyclecount", "on_conflict")
 PYDANTIC_V2 = version.parse_version(pydantic_version.VERSION).major >= 2
 
 if PYDANTIC_V2:
@@ -131,6 +142,121 @@ else:
         return decorator
 
 
+def normalize_http_method(method: str) -> str:
+    """Normalize and validate an HTTP method.
+
+    Parameters
+    ----------
+    method : str
+        HTTP verb to normalize.
+
+    Returns
+    -------
+    str
+        Upper-case HTTP method.
+
+    Raises
+    ------
+    ValueError
+        If the provided method is not supported.
+    """
+    normalized_method = method.upper()
+    if normalized_method not in SUPPORTED_HTTP_METHODS:
+        raise ValueError(
+            "Unsupported HTTP method: "
+            f"{method}. Supported methods are: "
+            f"{', '.join(SUPPORTED_HTTP_METHODS)}"
+        )
+    return normalized_method
+
+
+def build_json_request_payload(
+    params: Optional[Dict],
+    json: Optional[Dict] = None,
+) -> Optional[Dict]:
+    """Normalize a non-GET payload to the backend JSON contract.
+
+    Parameters
+    ----------
+    params : dict, optional
+        Request parameters produced by the caller.
+    json : dict, optional
+        Explicit JSON payload fallback.
+
+    Returns
+    -------
+    dict or None
+        Normalized JSON payload.
+    """
+    source_payload = params if params else json
+    if source_payload is None:
+        return None
+
+    payload = dict(source_payload)
+    for key in SPECIAL_QUERY_PARAM_KEYS:
+        payload.pop(key, None)
+
+    project = payload.get("project")
+    if isinstance(project, list) and len(project) == 1:
+        payload["project"] = project[0]
+
+    locations = payload.get("locations")
+    location = payload.pop("location", None)
+    if locations is None and location is not None:
+        payload["locations"] = (
+            location if isinstance(location, list) else [location]
+        )
+    elif isinstance(locations, str):
+        payload["locations"] = [item for item in locations.split(",") if item]
+
+    for key in ("metrics", "predictions"):
+        value = payload.get(key)
+        if isinstance(value, str):
+            payload[key] = [item for item in value.split(",") if item]
+
+    return {key: value for key, value in payload.items() if value is not None}
+
+
+def build_httpx_request_kwargs(
+    method: str,
+    params: Dict,
+    json: Optional[Dict] = None,
+) -> Tuple[Optional[Dict], Optional[Dict]]:
+    """Build ``httpx`` request kwargs based on the HTTP method.
+
+    GET requests keep using query-string parameters. Non-GET requests build
+    the request payload from ``params`` and only fall back to ``json`` when
+    ``params`` is empty.
+
+    Parameters
+    ----------
+    method : str
+        Normalized HTTP method.
+    params : dict
+        Parameters provided by the caller.
+    json : dict, optional
+        Explicit JSON payload fallback.
+
+    Returns
+    -------
+    Tuple[Optional[Dict], Optional[Dict]]
+        ``params`` and ``json`` values to forward to ``httpx.request``.
+    """
+    if method == "GET":
+        return params, json
+
+    payload = build_json_request_payload(params, json)
+    if method not in {"PATCH", "PUT"}:
+        return None, payload
+
+    out_params = {
+        key: params[key]
+        for key in SPECIAL_QUERY_PARAM_KEYS
+        if key in params and params[key] is not None
+    }
+    return out_params or None, payload
+
+
 def handle_request(
     url: str,
     params: Dict,
@@ -138,6 +264,8 @@ def handle_request(
     headers: Optional[Dict[str, str]] = {"accept": "application/json"},
     max_retries: int = 10,
     timeout: int = 3600,
+    method: str = "GET",
+    json: Optional[Dict] = None,
 ) -> httpx.Response:
     """Handle the request to the 24SEA API and manage errors using httpx.
 
@@ -161,6 +289,10 @@ def handle_request(
     httpx.Response
         The response object if the request was successful, otherwise error.
     """
+    method = normalize_http_method(method)
+    request_params, request_json = build_httpx_request_kwargs(
+        method, params, json
+    )
     if auth is None:
         auth = httpx.BasicAuth("", "")
     retry_count = 0
@@ -168,8 +300,9 @@ def handle_request(
     while True:
         try:
             # fmt: off
-            r_ = httpx.get(url, params=params, auth=auth, headers=headers,
-                           timeout=timeout)
+            r_ = httpx.request(method, url, auth=auth, headers=headers,
+                               timeout=timeout, params=request_params,
+                               json=request_json)
             # fmt: on
             if r_.status_code != 502 or retry_count >= max_retries:
                 break
@@ -196,23 +329,22 @@ async def handle_request_async(
     json: Optional[Dict] = None,
 ) -> httpx.Response:
     """Asynchronously handle the request to the 24SEA API using httpx's
-    AsyncClient. Supports GET, POST, PUT, DELETE methods."""
+    AsyncClient. Supports GET, POST, PUT, PATCH, DELETE methods."""
+    method = normalize_http_method(method)
+    request_params, request_json = build_httpx_request_kwargs(
+        method, params, json
+    )
+    if auth is None:
+        auth = httpx.BasicAuth("", "")
     retry_count = 0
     async with httpx.AsyncClient(
         auth=auth, headers=headers, timeout=timeout
     ) as client:
         while True:
             try:
-                if method.upper() == "GET":
-                    r_ = await client.get(url, params=params)
-                elif method.upper() == "POST":
-                    r_ = await client.post(url, params=params, json=json)
-                elif method.upper() == "PUT":
-                    r_ = await client.put(url, params=params, json=json)
-                elif method.upper() == "DELETE":
-                    r_ = await client.delete(url, params=params)
-                else:
-                    raise ValueError(f"Unsupported HTTP method: {method}")
+                r_ = await client.request(
+                    method, url, params=request_params, json=request_json
+                )
                 if r_.status_code != 502 or retry_count >= max_retries:
                     break
                 retry_count += 1
@@ -360,6 +492,7 @@ def parse_timestamp(
             series = df["timestamp"]
     if series is None:
         raise E.DataSignalsError(d_e)
+
     try:
         # Try parsing with different formats
         for fmt in formats:
@@ -551,7 +684,7 @@ async def gather_in_chunks(
 def fetch_data_sync(
     url,
     site: str,
-    locations: Union[str, List[str], None],
+    locations: Union[str, List[str]],
     start_timestamp: Union[datetime.datetime, str],
     end_timestamp: Union[datetime.datetime, str],
     headers: Optional[Dict[str, str]],
@@ -560,6 +693,7 @@ def fetch_data_sync(
     timeout: int,
     target: str = "metric",
     force_cache_miss: bool = False,
+    method: str = "GET",
 ) -> Any:
     """Syncronously fetch metrics data for the datasignals API app."""
     group_values = normalize_group_values(group[target].tolist())
@@ -567,11 +701,15 @@ def fetch_data_sync(
     s_ = "• " + ",".join(group_values).replace(
         ",", f"\n {len(target) + 1}    • "
     )
-    locations_list : Optional[List[str]] = locations.split(",") if isinstance(locations, str) else locations or None
+    locations_list : List[str] = locations.split(",") if isinstance(locations, str) else locations or []
     logging.info(f"\033[32;1m⏳ Getting data for {site} - "
                     f"{locations_list}...\n📊 \033[35;1m{target.capitalize()}s: "
                     f"\033[0;34m{s_}\n\033[0m")
     # fmt: on
+    if not locations_list:
+        raise E.DataSignalsError(
+            "Locations must be provided as a string or list of strings."
+        )
     r_ = handle_request(
         url,
         {
@@ -579,12 +717,14 @@ def fetch_data_sync(
             "end_timestamp": end_timestamp,
             "project": [site],
             "locations": locations_list,
+            "location": locations_list[0],
             f"{target}s": ",".join(group_values),
             "force_cache_miss": force_cache_miss,
         },
         auth,
         headers,
         timeout=timeout,
+        method=method,
     )
     # Warn if empty
     result_json = flatten_api_response(r_.json())
@@ -599,7 +739,7 @@ def fetch_data_sync(
 def fetch_availability_sync(
     url,
     site: str,
-    locations: Union[str, List[str], None],
+    locations: Union[str, List[str]],
     start_timestamp: Union[datetime.datetime, str],
     end_timestamp: Union[datetime.datetime, str],
     granularity: Union[str, int],
@@ -608,6 +748,7 @@ def fetch_availability_sync(
     group: pd.DataFrame,
     auth: Optional[httpx.BasicAuth],
     timeout: int,
+    method: str = "GET",
 ) -> Any:
     """Syncronously fetch metrics data for the datasignals API app."""
     metrics_values = normalize_group_values(group["metric"].tolist())
@@ -637,7 +778,9 @@ def fetch_availability_sync(
         params["bucket_seconds"] = granularity
     params["sampling_interval_seconds"] = sampling_interval_seconds
 
-    r_ = handle_request(url, params, auth, headers, timeout=timeout)
+    r_ = handle_request(
+        url, params, auth, headers, timeout=timeout, method=method
+    )
     # Warn if empty
     result_json = flatten_api_response(r_.json())
     if result_json == []:
@@ -661,6 +804,7 @@ async def fetch_availability_async(
     auth: Optional[httpx.BasicAuth],
     timeout: int,
     max_retries: int,
+    method: str = "GET",
 ) -> Any:
     """Asynchronously fetch availability data for a site/location."""
     metrics_values = normalize_group_values(group["metric"].tolist())
@@ -689,7 +833,13 @@ async def fetch_availability_async(
         params["bucket_seconds"] = granularity
     params["sampling_interval_seconds"] = sampling_interval_seconds
     r_ = await handle_request_async(
-        url, params, auth, headers, max_retries=max_retries, timeout=timeout
+        url,
+        params,
+        auth,
+        headers,
+        max_retries=max_retries,
+        timeout=timeout,
+        method=method,
     )
     result_json = flatten_api_response(r_.json())
     if result_json == []:
@@ -702,7 +852,7 @@ async def fetch_availability_async(
 async def fetch_data_async(
     url,
     site: str,
-    locations: Union[str, List[str], None],
+    locations: Union[str, List[str]],
     start_timestamp: Union[datetime.datetime, str],
     end_timestamp: Union[datetime.datetime, str],
     headers: Optional[Dict[str, str]],
@@ -713,34 +863,39 @@ async def fetch_data_async(
     as_dict: bool = False,
     target: str = "metric",
     force_cache_miss: bool = False,
+    method: str = "GET",
 ) -> Union[pd.DataFrame, Dict[str, Any]]:
     """Asyncronously fetch metrics data for the datasignals API app."""
     tgt_str = "data" if target == "metric" else "predictions"
     group_values = normalize_group_values(group[target].tolist())
-    locations_list: Optional[List[str]] = (
-        locations.split(",")
-        if isinstance(locations, str)
-        else locations or None
+    locations_list: List[str] = (
+        locations.split(",") if isinstance(locations, str) else locations or []
     )
     s_ = "• " + ",".join(group_values).replace(",", "\n            • ")
     logging.info(
         f"\033[32;1m⏳ Getting {tgt_str} for {site} - {locations_list}..."
         f"\n📊 \033[35;1m{target.capitalize()}s: \033[0;34m{s_}\n\033[0m"
     )
+    payload = {
+        "start_timestamp": start_timestamp,
+        "end_timestamp": end_timestamp,
+        "project": [site],
+        f"{target}s": ",".join(group_values),
+        "force_cache_miss": force_cache_miss,
+    }
+    if len(locations_list) == 1:
+        payload["location"] = locations_list[0]
+    elif locations_list:
+        payload["locations"] = locations_list
+
     r_ = await handle_request_async(
         url,
-        {
-            "start_timestamp": start_timestamp,
-            "end_timestamp": end_timestamp,
-            "project": [site],
-            "locations": locations_list,
-            f"{target}s": ",".join(group_values),
-            "force_cache_miss": force_cache_miss,
-        },
+        payload,
         auth,
         headers,
         max_retries=max_retries,
         timeout=timeout,
+        method=method,
     )
     result_json = flatten_api_response(r_.json())
     if result_json == []:
@@ -752,6 +907,47 @@ async def fetch_data_async(
     return pd.DataFrame(result_json)
 
 
+def fetch_oldest_timestamp_sync(
+    url: str,
+    site: str,
+    locations: Optional[str],
+    headers: Dict[str, str],
+    auth: Optional[httpx.BasicAuth],
+    timeout: int,
+    as_dict: bool = False,
+    method: str = "GET",
+) -> Union[pd.DataFrame, Dict[str, Any]]:
+    """Synchronously fetch oldest timestamp data for a site/location."""
+    if locations:
+        formatted_locations = "   • " + "\n   • ".join(locations.split(","))
+        logging.info(
+            f"\033[32;1m⏳ Getting oldest timestamps for {site} at the "
+            f"following locations:\n{formatted_locations}\n\033[0m"
+        )
+    else:
+        logging.info(
+            f"\033[32;1m⏳ Getting oldest timestamps for {site}\n\033[0m"
+        )
+    r_ = handle_request(
+        url,
+        (
+            {"project": site, "locations": locations}
+            if locations
+            else {"project": site}
+        ),
+        auth,
+        headers,
+        timeout=timeout,
+        method=method,
+    )
+    result_json = r_.json()
+    if result_json == []:
+        logging.warning(f"\033[33;1m⚠️ No data found for {site}.\033[0m")
+    if as_dict:
+        return result_json
+    return pd.DataFrame(result_json)
+
+
 async def fetch_oldest_timestamp_async(
     url,
     site: str,
@@ -761,6 +957,7 @@ async def fetch_oldest_timestamp_async(
     timeout: int,
     max_retries: int,
     as_dict: bool = False,
+    method: str = "GET",
 ) -> Union[pd.DataFrame, Dict[str, Any]]:
     # Format locations with bullets and newlines
     if locations:
@@ -784,6 +981,7 @@ async def fetch_oldest_timestamp_async(
         headers,
         max_retries=max_retries,
         timeout=timeout,
+        method=method,
     )
     result_json = r_.json()
     if result_json == []:
@@ -1056,7 +1254,7 @@ def series_to_type(
     if dtype in ("float", float, "int", int):
         return pd.to_numeric(series, errors="coerce").astype(dtype)  # type: ignore  # pylint: disable=C301  # noqa: E501
     if dtype in ("str", "string", str):
-        return series.astype(str)
+        return series.astype(str).astype(object)
     return series
 
 
@@ -1199,7 +1397,10 @@ def calendar_monthly_availability(
     if isinstance(idx_out, pd.DatetimeIndex):
         if idx_out.tz is not None:
             idx_out = idx_out.tz_convert(None)
-        idx_out = pd.DatetimeIndex(idx_out.to_numpy(), name=idx_out.name)
+        idx_out = pd.DatetimeIndex(
+            pd.to_datetime(idx_out.astype(str)),
+            name=idx_out.name,
+        )
         df_monthly.index = idx_out
 
     return df_monthly

{api_24sea-2.2.0 → api_24sea-2.2.1}/api_24sea/version.py

@@ -19,7 +19,7 @@ Attributes:
 import re
 from typing import NamedTuple, Optional
 
-__version__: str = "2.2.0"
+__version__: str = "2.2.1"
 
 _REGEX = "".join(
     [

{api_24sea-2.2.0 → api_24sea-2.2.1}/pyproject.toml

@@ -60,7 +60,7 @@ fatigue = [
     "py-fatigue>=1.0.0,<2.0.0; python_version<'3.10'",
     "swifter>=1.4.0"
 ]
-ai = ["api-24sea-ai>=0.1.0"]
+ai = ["api-24sea-ai>=0.2.0"]
 
 # -- Project dependency groups
 [dependency-groups]