api-24sea 0.1.0__py3-none-any.whl

api_24sea/__init__.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""The `api_24sea` package contains modules that are aimed at helping a user
+interact with the 24SEA API.
+
+The modules are:
+
+- :mod:`api_24sea.datasignals`: Contains the :class:`DataSignals` class, which
+    is an accessor for transforming data signals from the 24SEA API into
+    pandas DataFrames.
+
+Besides the modules, the package also contains the :mod:`api_24sea.version`
+module, which contains the version number of the package.
+"""
+
+from . import datasignals
+
+__all__ = ["datasignals"]

api_24sea/datasignals/__init__.py

@@ -0,0 +1,319 @@
+# -*- coding: utf-8 -*-
+"""The module :mod:`py_fatigue.damage.crack_growth` contains all the
+damage models related to the crack growth approach.
+"""
+import datetime
+import logging
+
+import pandas as pd
+import requests as req
+from pydantic import validate_call
+
+# Local imports
+from .. import utils as U
+from . import schemas as S
+
+try:
+    # delete the accessor to avoid warning
+    del pd.DataFrame.datasignals
+except AttributeError:
+    pass
+
+BASE_URL = "https://api.24sea.eu/routes/v1/"
+
+
+logging.basicConfig(format="%(message)s", level=logging.INFO)
+
+
+def check_authentication(func):
+    """Check authentication before making the request to the 24SEA API."""
+
+    def wrapper(self, *args, **kwargs):
+        """Wrapper function to check authentication."""
+        # fmt: off
+        if not isinstance(self.auth, req.auth.HTTPBasicAuth) or not self.authenticated:
+            raise U.AuthenticationError(
+                "\033[31;1mAuthentication needed before querying the metrics.\n"
+                "\033[0mUse the \033[34;1mdatasignals.\033[0mauthenticate("
+                "\033[32;1m<username>\033[0m, \033[32;1m<password>\033[0m) "
+                "method."
+            )
+        return func(self, *args, **kwargs)
+        # fmt: on
+
+    return wrapper
+
+
+@pd.api.extensions.register_dataframe_accessor("datasignals")
+class DataSignals:
+    """Accessor for working with data signals coming from the 24SEA API."""
+
+    def __init__(self, pandasdata: pd.DataFrame):
+        self.data = pandasdata
+        self.base_url: str = f"{BASE_URL}datasignals/"
+        self.username: str | None = None
+        self.password: str | None = None
+        self.auth: req.auth.HTTPBasicAuth | None = None
+        self.authenticated: bool = False
+        self.metrics_overview: pd.DataFrame | None = None
+        self.selected_metrics: pd.DataFrame | None = None
+
+    @validate_call
+    def authenticate(self, username: str, password: str) -> None:
+        """Authenticate the user with the 24SEA API. Additionally, define
+        the ``metrics_overview`` dataframe.
+
+        Parameters
+        ----------
+        username : str
+            The username to authenticate.
+        password : str
+            The password to authenticate.
+        """
+        # -- Step 1: Authenticate and check the credentials
+        self.username = username
+        self.password = password
+        self.auth = req.auth.HTTPBasicAuth(self.username, self.password)
+        # fmt: off
+        try:
+            r_profile = U.handle_request(
+                f"{self.base_url}profile",
+                {"username": self.username},
+                self.auth,
+                {"accept": "application/json"},
+            )
+            self.authenticated = True
+            logging.info("\033[32;1mThis dataframe has now access to https://api.24sea.eu/.\033[0m")  # noqa: E501  # pylint: disable=C0301
+        except req.exceptions.HTTPError:
+            raise U.AuthenticationError("\033[31;1mThe username and/or password are incorrect.\033[0m")  # noqa: E501  # pylint: disable=C0301
+        # fmt: on
+        # -- Step 2: Define the metrics_overview dataframe
+        if self.metrics_overview is not None:
+            return None
+        logging.info("Now getting your metrics_overview table...")
+        r_metrics = U.handle_request(
+            f"{self.base_url}metrics",
+            {"project": None, "locations": None, "metrics": None},
+            self.auth,
+            {"accept": "application/json"},
+        )
+        # fmt: off
+        if not isinstance(r_metrics, type(None)):
+            try:
+                m_ = pd.DataFrame(r_metrics.json())
+            except Exception:
+                raise U.ProfileError(f"\033[31;1mThe metrics overview is empty. This is your profile information:"  # noqa: E501  # pylint: disable=C0301
+                                     f"\n {r_profile.json()}")
+        if m_.empty:
+            raise U.ProfileError(f"\033[31;1mThe metrics overview is empty. This is your profile information:"  # noqa: E501  # pylint: disable=C0301
+                                 f"\n {r_profile.json()}")
+        try:
+            s_ = m_.apply(lambda x: x["metric"]
+                        .replace(x["statistic"], "")
+                        .replace(x["short_hand"], "")
+                        .strip(), axis=1).str.strip("_").str.split("_", expand=True)   # noqa: E501  # pylint: disable=C0301
+            s_.columns = ["site_id", "location_id"]
+        # fmt: on
+        except Exception:
+            self.metrics_overview = m_
+        self.metrics_overview = pd.concat([m_, s_], axis=1)
+        return
+
+    @check_authentication
+    @validate_call
+    def get_metrics(
+        self,
+        site: str | None = None,
+        locations: str | list[str] | None = None,
+        metrics: str | list[str] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> list[dict[str, str | None]] | None:
+        """Get the metrics names for a site, provided the following parameters.
+
+        Parameters
+        ----------
+        site : str | None
+            The site name. If None, the queryable metrics for all sites
+            will be returned, and the locations and metrics parameters will be
+            ignored.
+        locations : list[str] | None
+            The locations for which to get the metrics. If None, all locations
+            will be considered.
+        metrics : list[str] | None
+            The metrics to get. They can be specified as regular expressions.
+            If None, all metrics will be considered.
+            For example:
+            * metrics=["^ACC", "^DEM"] will return all the metrics that start
+              with ACC or DEM,
+            * Similarly, metrics=["windspeed$", "winddirection$"] will return
+              all the metrics that end with windspeed and winddirection,
+            * and metrics=[".*WF_A01.*",".*WF_A02.*"] will return all metrics
+              that contain WF_A01 or WF_A02.
+
+        Returns
+        -------
+        list[dict[str, str | None]] | None
+            The metrics names for the given site, locations and metrics.
+
+        .. note::
+            This class method is legacy because it does not add functionality to
+            the DataSignals pandas accessor.
+
+        """
+        url = f"{self.base_url}metrics"
+        # fmt: on
+        if headers is None:
+            headers = {"accept": "application/json"}
+        if site is None:
+            params = {}
+        if isinstance(locations, list):
+            locations = ",".join(locations)
+        if isinstance(metrics, list):
+            metrics = ",".join(metrics)
+        params = {
+            "project": site,
+            "locations": locations,
+            "metrics": metrics,
+        }
+
+        r_ = U.handle_request(url, params, self.auth, headers)
+
+        # Set the return type of the get_metrics method to the Metrics schema
+        return r_.json()  # type: ignore
+
+    @check_authentication
+    @validate_call
+    def get_data(
+        self,
+        sites: list | str | None,
+        locations: list | str | None,
+        metrics: list | str | None,
+        start_timestamp: str | datetime.datetime,
+        end_timestamp: str | datetime.datetime,
+        outer_join_on_timestamp: bool = False,
+        headers: dict[str, str] | None = None,
+    ):
+        """Get the data signals from the 24SEA API.
+
+        Parameters
+        ----------
+        filters : dict
+            The filters to apply when querying the data signals.
+
+        Returns
+        -------
+        pd.DataFrame
+            The DataFrame containing the data signals.
+        """
+        # Clean the DataFrame
+        self.data = pd.DataFrame()
+        # -- Step 1: Build the query object from GetData
+        query = S.GetData(
+            start_timestamp=start_timestamp,
+            end_timestamp=end_timestamp,
+            sites=sites,
+            locations=locations,
+            metrics=metrics,
+            headers=headers,
+            outer_join_on_timestamp=outer_join_on_timestamp,
+        )
+
+        match query.sites, query.locations:
+            case None, None:
+                query_str = "metric.str.contains(@query.metrics, case=False, regex=True)"
+            case None, _:
+                query_str = (
+                    "(location.str.lower() == @query.locations or location_id.str.lower() == @query.locations) "
+                    "and metric.str.contains(@query.metrics, case=False, regex=True)"
+                )
+            case _, None:
+                query_str = (
+                    "(site.str.lower() == @query.sites or site_id.str.lower() == @query.sites) "
+                    "and metric.str.contains(@query.metrics, case=False, regex=True)"
+                )
+            case _, _:
+                query_str = (
+                    "(site_id.str.lower() == @query.sites or site.str.lower() == @query.sites) "
+                    "and (location.str.lower() == @query.locations or location_id.str.lower() == @query.locations) "
+                    "and metric.str.contains(@query.metrics, case=False, regex=True)"
+                )
+
+        logging.info(
+            f"\033[30;1mQuery:\033[0;34m {query_str.replace(" and ", "\n       and ")}\n"
+        )
+        self.selected_metrics = self.metrics_overview.query(query_str).pipe(  # type: ignore  # noqa: E501  # pylint: disable=E501
+            lambda df: df.sort_values(
+                ["site", "location", "data_group", "short_hand", "statistic"],
+                ascending=[True, True, False, True, True],
+            )
+        )
+        logging.info("\033[32;1mMetrics selected for the query:\033[0m\n")
+        # fmt: off
+        logging.info(self.selected_metrics[["metric", "unit_str", "data_group",
+                                            "location", "site"]]
+                                          .reset_index(drop=True))
+        # fmt: on
+        data_frames = []
+        grouped_metrics = self.selected_metrics.groupby(["site", "location"])
+
+        # return grouped_metrics
+        logging.info(
+            f"\n\033[32;1mRequested time range:\033[0;33m "
+            f"From {str(query.start_timestamp)[:-4].replace("T", " ")} "
+            f"To {str(query.end_timestamp)[:-4].replace("T", " ")}\n\033[0m"
+        )
+        import concurrent.futures
+
+        def fetch_data(site, location, group):
+            # fmt: off
+            s_ = "• " + ",".join(group["metric"].tolist()).replace(",", "\n           • ")  # noqa: E501  # pylint: disable=C0301
+            logging.info(f"\033[32;1m\033[32;1m⏳ Getting data for {site} - "
+                         f"{location}...\n  Metrics: \033[0;33m{s_}\n\033[0m")
+            # fmt: on
+            r_ = U.handle_request(
+                f"{self.base_url}data",
+                {
+                    "start_timestamp": query.start_timestamp,
+                    "end_timestamp": query.end_timestamp,
+                    "project": [site],
+                    "location": [location],
+                    "metrics": ",".join(group["metric"].tolist()),
+                },
+                self.auth,
+                query.headers,
+            )
+            return pd.DataFrame(r_.json())
+
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            # fmt: off
+            future_to_data = {
+                executor.submit(fetch_data,
+                                site,
+                                location,
+                                group): (site, location)
+                for (site, location), group in grouped_metrics
+            }
+            # fmt: on
+            for future in concurrent.futures.as_completed(future_to_data):
+                data_frames.append(future.result())
+            # data_frames.append(pd.DataFrame(r_.json()))
+
+        # if left_join_on_timestamp is True, lose the location and site columns
+        # and join on timestamp
+        if outer_join_on_timestamp:
+            for i, df in enumerate(data_frames):
+                data_frames[i] = df.set_index("timestamp")
+                # drop site and location
+                data_frames[i].drop(["site", "location"], axis=1, inplace=True)
+            self.data = pd.concat(
+                [self.data] + data_frames, axis=1, join="outer"
+            )
+        else:
+            self.data = pd.concat([self.data] + data_frames, ignore_index=True)
+        # To access the data, use the .data attribute of the datasignals accessor
+        logging.info("\033[32;1m✔️ Data successfully retrieved.\033[0m")
+        print(
+            "To access the data, use the \033[30;1m.data\033[0m attribute "
+            "of the \033[30;1m.datasignals\033[0m accessor."
+        )
+        return self.data

api_24sea/datasignals/schemas.py

@@ -0,0 +1,103 @@
+# -*- coding: utf-8 -*-
+"""Data signals types."""
+
+import datetime
+
+from pydantic import BaseModel, ValidationInfo, field_validator
+
+
+class Metric(BaseModel):
+    """A pydantic schema for the metrics names."""
+
+    start_timestamp: str
+    end_timestamp: str
+    site: str
+    location: str
+    data_group: str | None
+    metric: str
+    statistic: str | None
+    short_hand: str | None
+    unit_str: str | None
+    print_str: str | None
+    description: str | None
+    crud_privileges: str | None
+
+
+class Metrics(BaseModel):
+    """A pydantic schema for the metrics names."""
+
+    metrics: list[Metric]
+
+
+class GetData(BaseModel):
+    """A pydantic schema for the data signals."""
+
+    start_timestamp: str | datetime.datetime
+    end_timestamp: str | datetime.datetime
+    sites: str | list[str] | None
+    locations: str | list[str] | None
+    metrics: str | list[str] | None
+    outer_join_on_timestamp: bool | None
+    headers: dict[str, str] | None
+
+    @field_validator("start_timestamp", "end_timestamp", mode="before")
+    def validate_timestamp(cls, v: str | datetime.datetime) -> str:
+        """Validate the timestamps."""
+        if isinstance(v, str):
+            try:
+                datetime.datetime.strptime(v, "%Y-%m-%dT%H:%M:%SZ")
+            except ValueError:
+                raise ValueError(
+                    "Incorrect start timestamp format, expected ISO 8601."
+                )
+
+        if isinstance(v, datetime.datetime):
+            # Enforce timezone UTC as well
+            return v.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        return v
+
+    @field_validator("end_timestamp")
+    def validate_end_timestamp(cls, v, info: ValidationInfo):
+        """Validate the end timestamp."""
+        if "start_timestamp" in info.data and v < info.data["start_timestamp"]:
+            raise ValueError(
+                "End timestamp must be greater than start timestamp."
+            )
+        return v
+
+    @field_validator("sites", "locations", mode="before")
+    def validate_sites_locations(cls, v):
+        """Validate and normalize sites and locations."""
+        if isinstance(v, str):
+            v = [v]
+        if isinstance(v, list):
+            v = [item.lower() for item in v]
+        return v
+
+    @field_validator("metrics", mode="before")
+    def validate_metrics(cls, v):
+        """Validate and normalize metrics."""
+        if isinstance(v, str):
+            v = [v]
+        if isinstance(v, list):
+            # fmt: off
+            v = [item.replace(" ", ".*")
+                     .replace("_", ".*")
+                     .replace("-", ".*") for item in v]
+            # fmt: on
+        return "|".join(v)
+
+    @field_validator("outer_join_on_timestamp", mode="before")
+    def validate_outer_join_on_timestamp(cls, v):
+        """Validate the outer join on timestamp."""
+        if v is None:
+            return False
+        return v
+
+    @field_validator("headers", mode="before")
+    def validate_headers(cls, v):
+        """Validate the headers."""
+        if v is None:
+            return {"accept": "application/json"}
+        return v

api_24sea/utils.py

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+"""Utility functions and classes."""
+
+import requests as req
+
+
+class AuthenticationError(Exception):
+    """An exception to raise when the user is not authenticated."""
+
+    pass
+
+
+class ProfileError(Exception):
+    """An exception to raise when the user is authenticated, but its profile
+    is not properly configured."""
+
+    pass
+
+
+def handle_request(
+    url: str, params: dict, auth: req.auth.HTTPBasicAuth, headers: dict
+) -> req.models.Response:
+    """Handle the request to the 24SEA API and manage errors.
+
+    Parameters
+    ----------
+    url : str
+        The URL to which to send the request.
+    params : dict
+        The parameters to send with the request.
+    auth : requests.auth.HTTPBasicAuth
+        The authentication object.
+    headers : dict
+        The headers to send with the request.
+
+    Returns
+    -------
+    requests.models.Response
+        The response object if the request was successful, otherwise error.
+    """
+    try:
+        r_ = req.get(url, params=params, auth=auth, headers=headers)
+
+        if r_.status_code in [400, 401, 403, 404, 502, 503, 504]:
+            print(f"Request failed because: \033[31;1m{r_.text}\033[0m")
+            r_.raise_for_status()
+        # this will handle all other errors
+        elif r_.status_code == 500:
+            # fmt: off
+            print("\033[31;1mInternal server error. You will need to contact "
+                  "support at \033[32;1;4msupport.api@24sea.eu\033[0m")
+            # fmt: on
+            r_.raise_for_status()
+        elif r_.status_code > 400:
+            # fmt: off
+            print("Request failed with status code: "
+                  f"\033[31;1m{r_.status_code}\033[0m")
+            # fmt: on
+            r_.raise_for_status()
+    except (req.exceptions.ConnectionError, req.exceptions.Timeout) as exc:
+        print(f" Request failed because: \033[31;1m{exc}\033[0m")
+        raise exc
+    return r_

api_24sea/version.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+"""
+This module exposes the current version of the package
+so the version can be retreived directly within other code
+files. The version assumes the semver notation (major.minor.patch-release.num).
+
+Example:
+    Import the version as constant, dict or tuple:
+
+    >>> from api_24sea.version import __version__
+
+    >>> from api_24sea.version import parse_version
+    >>> parse_version(__version__)
+
+Attributes:
+    __version__ (str): Current api_24sea version.
+
+"""
+import re
+from typing import NamedTuple, Optional
+
+__version__: str = "0.1.0"
+
+_REGEX = "".join(
+    [
+        r"(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)",
+        r"(?:\-(?P<release>.*)\.(?P<num>\d+))?",
+    ]
+)
+
+
+class Version(NamedTuple):
+    """Convenience structure for interpreting the version information"""
+
+    major: int
+    minor: int
+    patch: int
+    release: Optional[str] = None
+    num: Optional[int] = None
+
+
+def parse_version(version: str) -> Version:
+    """Converts the given version string to a named tuple per the semantic
+    version guidelines"""
+    match = re.search(_REGEX, version)
+    if not match:
+        raise ValueError(
+            f"Version '{version}' does not comply with the semantic"
+            "versioning naming scheme"
+        )
+
+    major = int(match.group("major"))
+    minor = int(match.group("minor"))
+    patch = int(match.group("patch"))
+    release = match.group("release")
+
+    num = None  # type: Optional[int]
+    try:
+        num = int(match.group("num"))
+    except TypeError:
+        pass
+
+    return Version(
+        major=major,
+        minor=minor,
+        patch=patch,
+        release=release,
+        num=num,
+    )