the-datagarden 0.1.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

the_datagarden/__init__.py

@@ -0,0 +1,8 @@
+from .api.authentication.environment import TheDatagardenLocalEnvironment
+from .api.base import TheDataGardenAPI, TheDatagardenProductionEnvironment
+
+__all__ = [
+    "TheDataGardenAPI",
+    "TheDatagardenProductionEnvironment",
+    "TheDatagardenLocalEnvironment",
+]

the_datagarden/abc/__init__.py

@@ -0,0 +1,3 @@
+from .authentication import BaseDataGardenCredentials, DatagardenEnvironment
+
+__all__ = ["DatagardenEnvironment", "BaseDataGardenCredentials"]

the_datagarden/abc/api.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+
+from requests import Response
+
+from the_datagarden.abc.authentication import DatagardenEnvironment
+
+
+class BaseApi(ABC):
+    @abstractmethod
+    def __init__(self, environment: type[DatagardenEnvironment] | None = None): ...
+
+    @abstractmethod
+    def retrieve_from_api(
+        self,
+        url_extension: str,
+        method: str = "GET",
+        payload: dict | None = None,
+        params: dict | None = None,
+    ) -> Response | None: ...

the_datagarden/abc/authentication.py

@@ -0,0 +1,42 @@
+from abc import ABC, abstractmethod
+from typing import TypedDict
+
+
+class TheDatagardenCredentialsDict(TypedDict):
+    email: str
+    password: str
+
+
+class BaseDataGardenCredentials(ABC):
+    """Protocol for the datagarden credentials"""
+
+    @classmethod
+    @abstractmethod
+    def credentials(
+        cls, the_datagarden_api_url: str, email: str | None = None, password: str | None = None
+    ) -> TheDatagardenCredentialsDict: ...
+
+
+class DatagardenEnvironment(ABC):
+    """Protocol for the datagarden environment"""
+
+    CREDENTIALS: type[BaseDataGardenCredentials]
+    THE_DATAGARDEN_URL: str
+    ECHO_INIT: bool = True
+
+    def __init__(self):
+        if self.ECHO_INIT:
+            print("Initializing :", self.__class__.__name__)
+            print("At :", self.the_datagarden_url)
+
+    def credentials(
+        self, email: str | None = None, password: str | None = None
+    ) -> TheDatagardenCredentialsDict:
+        return self.CREDENTIALS.credentials(self.the_datagarden_url, email, password)
+
+    @property
+    def the_datagarden_url(self) -> str:
+        url = self.THE_DATAGARDEN_URL
+        if url[-1] != "/":
+            return url + "/"
+        return url

the_datagarden/api/__init__.py

@@ -0,0 +1,5 @@
+from .authentication import AccessToken
+from .authentication.environment import TheDatagardenProductionEnvironment
+from .base import TheDataGardenAPI
+
+__all__ = ["AccessToken", "TheDatagardenProductionEnvironment", "TheDataGardenAPI"]

the_datagarden/api/authentication/__init__.py

@@ -0,0 +1,112 @@
+import json
+from datetime import UTC, datetime, timedelta
+
+import jwt
+import requests
+from requests import Response
+
+from ...abc.authentication import DatagardenEnvironment
+from .settings import (
+    BEARER_KEY,
+    DEFAULT_HEADER,
+    REFRESH_TOKEN_URL_EXTENSION,
+    REQ_TOKEN_URL_EXTENSION,
+)
+
+
+class AccessToken:
+    _instance = None
+    _tokens: dict = {}
+    TOKEN_LIFE_TIME_MARGIN: int = 20
+    ACCESS_TOKEN_KEY = "access"
+    REFRESH_TOKEN_KEY = "refresh"
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(
+        self,
+        environment: type[DatagardenEnvironment],
+        email: str | None = None,
+        password: str | None = None,
+    ) -> None:
+        self._environment = environment()
+        self._token_payload = self._environment.credentials(email, password)
+        self._token_header = DEFAULT_HEADER.copy()
+
+    @property
+    def _token_url(self) -> str:
+        return self._the_datagarden_url + REQ_TOKEN_URL_EXTENSION
+
+    @property
+    def _refresh_token_url(self) -> str:
+        return self._the_datagarden_url + REFRESH_TOKEN_URL_EXTENSION
+
+    @property
+    def _the_datagarden_url(self) -> str:
+        return self._environment.the_datagarden_url
+
+    def _access_token_expired(self) -> bool:
+        if self._token_expiry_time:
+            return datetime.now(tz=UTC) + timedelta(seconds=5) > self._token_expiry_time
+        return True
+
+    @property
+    def _access_token(self) -> str:
+        if not self._tokens:
+            self._request_tokens()
+        elif self._access_token_expired():
+            self._get_refresh_token()
+        return self._tokens.get(self.ACCESS_TOKEN_KEY, "")
+
+    @property
+    def header_with_access_token(self) -> dict[str, str]:
+        header = DEFAULT_HEADER.copy()
+        header["Authorization"] = BEARER_KEY + self._access_token
+        return header
+
+    def _request_tokens(self):
+        response = requests.request(
+            method="POST",
+            url=self._token_url,
+            headers=self._token_header,
+            data=json.dumps(self._token_payload),
+        )
+        if not response.status_code == 200:
+            print("Token request failed and returned error(s): ")
+            print("    Errorr : ", response.json().get("detail", "No error details provided"))
+            quit()
+
+        self._tokens = self._get_response_data(response)
+        self._set_token_expiry_time()
+
+    def _get_refresh_token(self):
+        response = requests.request(
+            method="POST",
+            url=self._refresh_token_url,
+            headers=self._token_header,
+            data=json.dumps(self._refresh_payload()),
+        )
+        if not response.status_code == 200:
+            raise ValueError("Token request failed and returned error: " f"{response.text}")
+        self._tokens = self._get_response_data(response)
+        self._set_token_expiry_time()
+
+    def _refresh_payload(self) -> dict:
+        refresh_token = self._tokens.get(self.REFRESH_TOKEN_KEY, "")
+        return {"refresh": refresh_token}
+
+    def _set_token_expiry_time(self):
+        if not self._tokens:
+            return
+        access_token = self._tokens.get(self.ACCESS_TOKEN_KEY, "")
+        if not access_token:
+            raise ValueError("Access token not found in response")
+        decoded_token = jwt.decode(access_token, options={"verify_signature": False})
+        exp_time_stamp = decoded_token["exp"]
+        self._token_expiry_time = datetime.fromtimestamp(timestamp=exp_time_stamp, tz=UTC)
+
+    def _get_response_data(self, response: Response) -> dict[str, str]:
+        return json.loads(response.text)

the_datagarden/api/authentication/credentials/__init__.py

@@ -0,0 +1,120 @@
+import requests
+from decouple import config
+
+from the_datagarden.abc.authentication import BaseDataGardenCredentials, TheDatagardenCredentialsDict
+from the_datagarden.api.authentication.settings import REGISTRATION_URL_EXTENSION
+
+
+class CredentialsFromUserInput:
+    def get_missing_credentials(self, the_datagarden_api_url: str) -> TheDatagardenCredentialsDict:
+        print()
+        print("Welcome to The Data Garden API.")
+        print()
+        print("  You can start using the API with an account from The-Datagarden.io.")
+        print("  Please provide your credentials or create a new account.")
+        print("  Check www.the-datagarden.io for more information.")
+        print()
+        choice = input(
+            "Do you want to (1) create a new account or (2) provide existing credentials? " "Enter 1 or 2: "
+        )
+
+        if choice == "1":
+            credentials = self.enroll_to_api(the_datagarden_api_url)
+            if not credentials:
+                quit()
+            return credentials
+
+        elif choice == "2":
+            return self.provide_existing_credentials()
+        else:
+            print("Invalid choice. Please enter 1 or 2.")
+            return self.get_missing_credentials(the_datagarden_api_url)
+
+    def enroll_to_api(self, the_datagarden_api_url: str) -> TheDatagardenCredentialsDict | None:
+        print("Enrolling in The Data Garden API...")
+        print()
+        email = input("  Enter your email: ")
+        password = self.get_confirmed_password()
+        print()
+
+        data = {"email": email, "password": password}
+        registration_url = the_datagarden_api_url + REGISTRATION_URL_EXTENSION
+        response = requests.post(registration_url, data=data)
+        if response.status_code == 201:
+            print("Successfully enrolled in The Data Garden API.")
+            return TheDatagardenCredentialsDict(
+                email=email,
+                password=password,
+            )
+        else:
+            print("Enrollment failed with error(s):")
+            for field, message_list in response.json().items():
+                print(f"    {field}: {message_list[0]}")
+
+        return None
+
+    def get_confirmed_password(self) -> str:
+        while True:
+            password = input("  Enter your password: ")
+            confirm_password = input("  Confirm your password: ")
+
+            if password == confirm_password:
+                return password
+            else:
+                print("Passwords do not match. Please try again.")
+
+    def provide_existing_credentials(self) -> TheDatagardenCredentialsDict:
+        print("Please provide your existing credentials...")
+        print()
+        email = input("  Enter your email: ")
+        password = input("  Enter your password: ")
+        return TheDatagardenCredentialsDict(
+            email=email,
+            password=password,
+        )
+
+    def credentials(self, the_datagarden_api_url: str) -> TheDatagardenCredentialsDict:
+        return self.get_missing_credentials(the_datagarden_api_url)
+
+
+class TheDataGardenCredentials(BaseDataGardenCredentials):
+    """
+    Manages credentials for The Data Garden API in a production environment.
+
+    This class handles the retrieval of user credentials (email and password) for
+    authenticating with The Data Garden API. It first attempts to fetch credentials
+    from environment variables. If not found, it prompts the user for input.
+
+    Attributes:
+        ENV_EMAIL_KEY (str): Environment variable key for the user's email.
+        ENV_PASSWORD_KEY (str): Environment variable key for the user's password.
+        CREDENTIALS_FROM_USER_INPUT (CredentialsFromUserInput):
+                Instance to handle user input for credentials.
+
+    Methods:
+        credentials(): Retrieves and returns the user's credentials.
+    """
+
+    ENV_EMAIL_KEY: str = "THE_DATAGARDEN_USER_EMAIL"
+    ENV_PASSWORD_KEY: str = "THE_DATAGARDEN_USER_PASSWORD"
+    CREDENTIALS_FROM_USER_INPUT = CredentialsFromUserInput()
+
+    @classmethod
+    def credentials(
+        cls, the_datagarden_api_url: str, email: str | None = None, password: str | None = None
+    ) -> TheDatagardenCredentialsDict:
+        if email and password:
+            return TheDatagardenCredentialsDict(
+                email=email,
+                password=password,
+            )
+
+        datagarden_user_email = str(config(cls.ENV_EMAIL_KEY, default="", cast=str))
+        datagarden_user_password = str(config(cls.ENV_PASSWORD_KEY, default="", cast=str))
+        if datagarden_user_email and datagarden_user_password:
+            return TheDatagardenCredentialsDict(
+                email=datagarden_user_email,
+                password=datagarden_user_password,
+            )
+
+        return cls.CREDENTIALS_FROM_USER_INPUT.credentials(the_datagarden_api_url)

the_datagarden/api/authentication/environment/__init__.py

@@ -0,0 +1,13 @@
+from the_datagarden.abc import DatagardenEnvironment
+
+from ..credentials import TheDataGardenCredentials
+
+
+class TheDatagardenProductionEnvironment(DatagardenEnvironment):
+    CREDENTIALS = TheDataGardenCredentials
+    THE_DATAGARDEN_URL = "https://api.the-datagarden.io"
+
+
+class TheDatagardenLocalEnvironment(DatagardenEnvironment):
+    CREDENTIALS = TheDataGardenCredentials
+    THE_DATAGARDEN_URL = "http://127.0.0.1:8000"

the_datagarden/api/authentication/settings.py

@@ -0,0 +1,54 @@
+"""
+Authentication settings for The DataGarden API.
+
+This module contains constants and default values used for authentication
+and API communication with The DataGarden service.
+
+Constants:
+    REQ_TOKEN_URL_EXTENSION (str): URL extension for requesting a token.
+    REFRESH_TOKEN_URL_EXTENSION (str): URL extension for refreshing a token.
+    HTTPS_PREFIX (str): Prefix for HTTPS URLs.
+    BEARER_KEY (str): Prefix for Bearer token authentication.
+    API_EXTENSION (str): Extension for API endpoints (currently empty).
+    DEFAULT_HEADER (dict): Default headers for API requests.
+
+"""
+
+from decouple import config
+
+from the_datagarden.version import __version__
+
+INCLUDE_STATISTIC_PARAM = {"include_statistics": "y"}
+
+STATISTICS_URL_EXTENSION = "statistics/"
+
+SHOW_REQ_DETAIL = config("SHOW_REQ_DETAIL", default=False, cast=bool)
+REQ_TOKEN_URL_EXTENSION = "user/token/"
+REFRESH_TOKEN_URL_EXTENSION = "user/token/refresh/"
+
+REGISTRATION_URL_EXTENSION = "user/enroll/"
+
+HTTPS_PREFIX = "https://"
+BEARER_KEY = "Bearer "
+API_EXTENSION = ""
+
+DEFAULT_HEADER: dict[str, str] = {
+    "accept": "application/json",
+    "accept-language": "en,nl-NL;q=0.9,nl;q=0.8,sv;q=0.7",
+    "content-type": "application/json",
+    "X-The-Datagarden-Version": "The_datagarden_pypi_package_version__" + __version__,
+}
+
+
+class URLExtension:
+    WORLD = "world/"
+    WORLD_DATA = "world/regional_data/"
+    CONTINENTS = "continent/"
+    CONTINENT = "continent/"
+    COUNTRIES = "country/"
+    COUNTRY = "country/"
+
+
+class DynamicEndpointCategories:
+    CONTINENTS = "continents"
+    COUNTRIES = "countries"

the_datagarden/api/base/__init__.py

@@ -0,0 +1,215 @@
+"""
+Base module for The Data Garden API.
+
+This module provides the foundation for interacting with The Data Garden API.
+It includes the base class for API interactions and imports necessary
+authentication components.
+
+Classes:
+    TheDataGardenAPI: Base class for interacting with The Data Garden API.
+
+Imports:
+    DatagardenEnvironment: Abstract base class for environment authentication.
+    TheDatagardenProductionEnvironment: Concrete implementation of the production
+                                                                        environment.
+    URLExtension: Class for handling URL extensions.
+"""
+
+from collections import defaultdict
+from typing import Iterator
+
+import requests
+from requests import Response
+
+from the_datagarden.abc.api import BaseApi
+from the_datagarden.abc.authentication import DatagardenEnvironment
+from the_datagarden.api.authentication import AccessToken
+from the_datagarden.api.authentication.environment import TheDatagardenProductionEnvironment
+from the_datagarden.api.authentication.settings import (
+    SHOW_REQ_DETAIL,
+    DynamicEndpointCategories,
+    URLExtension,
+)
+from the_datagarden.api.regions import Continent
+from the_datagarden.api.regions.country import Country
+
+
+class BaseDataGardenAPI(BaseApi):
+    """
+    Base class for interacting with The Data Garden API.
+    """
+
+    ACCESS_TOKEN: type[AccessToken] = AccessToken
+    DYNAMIC_ENDPOINTS: dict = defaultdict(dict)
+
+    def __init__(
+        self,
+        environment: type[DatagardenEnvironment] | None = None,
+        email: str | None = None,
+        password: str | None = None,
+    ):
+        self._environment = environment or TheDatagardenProductionEnvironment
+        self._tokens = self.ACCESS_TOKEN(self._environment, email, password)
+        self._base_url = self._environment().the_datagarden_url
+
+    def _generate_url(self, url_extension: str) -> str:
+        url = self._base_url + url_extension
+        if url[-1] != "/":
+            url += "/"
+        return url
+
+    def retrieve_from_api(
+        self,
+        url_extension: str,
+        method: str = "GET",
+        payload: dict | None = None,
+        params: dict | None = None,
+    ) -> Response | None:
+        url = self._generate_url(url_extension)
+        headers = self._tokens.header_with_access_token
+        if SHOW_REQ_DETAIL:
+            print(f"Request URL: {url}")
+            print(f"Request headers: {headers}")
+            print(f"Request method: {method}")
+            print(f"Request payload: {payload}")
+            print(f"Request params: {params}")
+        match method:
+            case "GET":
+                response = requests.get(url, params=params, headers=headers)
+            case "POST":
+                response = requests.post(url, json=payload, headers=headers)
+            case _:
+                raise ValueError(f"Invalid method: {method}")
+
+        return self._response_handler(response)
+
+    def _response_handler(self, response: requests.Response) -> Response | None:
+        if response.status_code == 200:
+            return response
+        else:
+            response_dict = response.json()
+            for k, v in response_dict.items():
+                print(k)
+                print(v)
+            return None
+
+    def _get_next_page(self, response: requests.Response) -> requests.Response | None:
+        next_url = response.json().get("next")
+        if not next_url:
+            return None
+
+        # Determine the original request method
+        original_method = response.request.method
+
+        headers = self._tokens.header_with_access_token
+
+        if original_method == "GET":
+            return requests.get(next_url, headers=headers)
+        elif original_method == "POST":
+            # For POST requests, we need to preserve the original payload
+            original_payload = response.request.body
+            return requests.post(next_url, data=original_payload, headers=headers)
+        else:
+            raise ValueError(f"Unsupported method for pagination: {original_method}")
+
+    def _records_from_paginated_api_response(self, response: requests.Response | None) -> Iterator[dict]:
+        while response:
+            for record in response.json()["results"]:
+                yield record
+            response = self._get_next_page(response)
+
+    def _create_url_extension(self, url_extensions: list[str]) -> str:
+        url = "/".join(url_extensions).lower().replace(" ", "-")
+        if url_extensions[-1] == "/":
+            return url
+        return url + "/"
+
+
+class TheDataGardenAPI(BaseDataGardenAPI):
+    _instance = None
+    _initialized = False
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(
+        self,
+        environment: type[DatagardenEnvironment] | None = None,
+        email: str | None = None,
+        password: str | None = None,
+    ):
+        if not self._initialized:
+            super().__init__(environment, email, password)
+            self._setup_continents()
+            self._setup_countries()
+            self.__class__._initialized = True
+
+    def __getattr__(self, attr: str):
+        for _, endpoints in self.DYNAMIC_ENDPOINTS.items():
+            if attr.lower() in endpoints:
+                return endpoints[attr.lower()]
+
+        raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{attr}'")
+
+    def world(self):
+        response = self.retrieve_from_api(URLExtension.WORLD)
+        return response.json()
+
+    def continents(self, include_details: bool = False) -> list[str] | dict:
+        continents = (
+            self.DYNAMIC_ENDPOINTS.get(DynamicEndpointCategories.CONTINENTS, None) or self._setup_continents()
+        )
+        if not include_details:
+            return continents.keys()
+        return continents
+
+    def countries(self, include_details: bool = False) -> list[str] | dict:
+        countries = (
+            self.DYNAMIC_ENDPOINTS.get(DynamicEndpointCategories.COUNTRIES, None) or self._setup_countries()
+        )
+        if not include_details:
+            return countries.keys()
+        return countries
+
+    def _setup_continents(self):
+        if not self.DYNAMIC_ENDPOINTS.get(DynamicEndpointCategories.CONTINENTS, None):
+            continents = self.retrieve_from_api(URLExtension.CONTINENTS)
+            for continent in self._records_from_paginated_api_response(continents):
+                continent_method_name = continent["name"].lower().replace(" ", "_")
+                self.DYNAMIC_ENDPOINTS[DynamicEndpointCategories.CONTINENTS].update(
+                    {
+                        continent_method_name: Continent(
+                            url=self._create_url_extension([URLExtension.CONTINENT + continent["name"]]),
+                            api=self,
+                            name=continent["name"].lower(),
+                        ),
+                    }
+                )
+
+        return self.DYNAMIC_ENDPOINTS[DynamicEndpointCategories.CONTINENTS]
+
+    def _setup_countries(self):
+        if not self.DYNAMIC_ENDPOINTS.get(DynamicEndpointCategories.COUNTRIES, None):
+            countries = self.retrieve_from_api(URLExtension.COUNTRIES)
+            if not countries:
+                return None
+            for country in self._records_from_paginated_api_response(countries):
+                country_method_name = country["name"].lower().replace(" ", "_")
+                country_code = country["iso_cc_2"].lower()
+                continent = country["parent_region"].lower()
+                country = Country(
+                    url=self._create_url_extension([URLExtension.COUNTRY + country["name"]]),
+                    api=self,
+                    name=country["name"],
+                    continent=continent,
+                )
+                self.DYNAMIC_ENDPOINTS[DynamicEndpointCategories.COUNTRIES].update(
+                    {
+                        country_method_name: country,
+                        country_code: country,
+                    }
+                )
+
+        return self.DYNAMIC_ENDPOINTS[DynamicEndpointCategories.COUNTRIES]

the_datagarden/api/regions/__init__.py

@@ -0,0 +1,4 @@
+from .continent import Continent
+from .country import Country
+
+__all__ = ["Continent", "Country"]