core-https 1.1.5__tar.gz → 1.1.7__tar.gz

{core_https-1.1.5 → core_https-1.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-https
-Version: 1.1.5
+Version: 1.1.7
 Summary: This project/library contains common elements related to HTTP & API services...
 Author-email: Alejandro Cora González <alek.cora.glez@gmail.com>
 Maintainer: Alejandro Cora González
@@ -16,22 +16,25 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.7
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: core-mixins>=1.1.2
+Requires-Dist: aiohttp>=3.12.0; python_version >= "3.9"
+Requires-Dist: aiohttp>=3.8.0; python_version >= "3.7" and python_version < "3.9"
+Requires-Dist: core-mixins>=2.0.3
 Requires-Dist: core-tests>=1.1.0
-Requires-Dist: urllib3>=2.2.3; python_version >= "3.8"
-Requires-Dist: urllib3>=1.26.20; python_version >= "3.7" and python_version < "3.8"
+Requires-Dist: requests>=2.32.3; python_version >= "3.8"
+Requires-Dist: requests>=2.20.0; python_version >= "3.7" and python_version < "3.8"
 Requires-Dist: typing-extensions>=4.8.0; python_version >= "3.8" and python_version < "3.11"
 Requires-Dist: typing-extensions>=4.2.0; python_version >= "3.7" and python_version < "3.8"
+Requires-Dist: urllib3>=2.2.3; python_version >= "3.8"
+Requires-Dist: urllib3>=1.26.20; python_version >= "3.7" and python_version < "3.8"
 Provides-Extra: docs
 Requires-Dist: pydata-sphinx-theme==0.16.1; extra == "docs"
 Requires-Dist: Sphinx==8.2.3; extra == "docs"

{core_https-1.1.5 → core_https-1.1.7}/core_https/exceptions.py

@@ -27,7 +27,7 @@ class AuthenticationException(ServiceException):
 
     def __init__(
         self,
-        status_code: int = 403,
+        status_code: int = 401,
         details: str = "Unauthorized"
     ) -> None:
         super().__init__(status_code=status_code, details=details)
@@ -56,3 +56,12 @@ class RateLimitException(ServiceException):
         details: str = "Too Many Requests"
     ) -> None:
         super().__init__(status_code=status_code, details=details)
+
+
+class RetryableException(InternalServerError):
+    """
+    Special case for exceptions that are considered retryable
+    like: 429, 502, 503 or 504. It's useful when a retry mechanism
+    is used, and you want to capture one type of error to trigger
+    the retry.
+    """

core_https-1.1.7/core_https/requesters/aiohttp_.py

@@ -0,0 +1,178 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+from typing import Dict
+from typing import Optional
+
+try:
+    from typing import Self
+
+except ImportError:
+    from typing_extensions import Self
+
+try:
+    from http import HTTPMethod
+
+except ImportError:
+    from core_https.utils import HTTPMethod
+
+from aiohttp import (
+    ClientResponse,
+    ClientResponseError,
+    ClientSession,
+    ClientTimeout,
+    TCPConnector,
+)
+
+from .base import IRequester
+
+
+class AioHttpRequester(IRequester):
+    """
+    It uses `aiohttp` to make the requests.
+
+    .. code-block:: python
+
+        import aiohttp
+        from core_https.requesters.aiohttp_ import AioHttpRequester
+        from core_https.utils import HTTPMethod
+
+        requester: AioHttpRequester = AioHttpRequester(raise_for_status=True)
+
+        async def get():
+            # This is optional as the client creates one session for you if not provided.
+            session = aiohttp.ClientSession()
+
+            try:
+                response = await requester.request(
+                    method=HTTPMethod.GET,
+                    session=session,
+                    url=url,
+                    params={
+                        "x-api-key": "..."
+                    })
+
+                return await response.text()
+
+            except Exception as error:
+                pass
+
+            finally:
+                await session.close()
+
+        res = asyncio.run(get())
+        print(res)
+    ..
+    """
+
+    def __init__(
+        self,
+        session: Optional[ClientSession] = None,
+        retries: Optional[int] = 3,
+        **kwargs
+    ) -> None:
+        """
+        :param session: The session to use for requests.
+        :param retries: Retry strategy to apply. Pass zero (0) to avoid retries.
+        """
+
+        super().__init__(**kwargs)
+
+        self._session = session
+        self._session_lock = asyncio.Lock()
+        self._owns_session = session is None
+        self._timeout = ClientTimeout(total=self.timeout)
+        self.retries = retries
+
+    async def __aenter__(self) -> Self:
+        await self._ensure_session()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()
+
+    @classmethod
+    def engine(cls) -> str:
+        return "aiohttp"
+
+    async def _ensure_session(self) -> ClientSession:
+        """ If the session doesn't exist, it creates it """
+
+        if self._session is None:
+            async with self._session_lock:
+                if self._session is None:  # Double-check after acquiring lock...
+                    self._session = ClientSession(
+                        timeout=self._timeout,
+                        connector=TCPConnector(
+                            limit=self.connector_limit,
+                            limit_per_host=self.connector_limit_per_host
+                        ))
+
+                    self._owns_session = True
+
+        return self._session
+
+    async def request(
+        self,
+        url: str,
+        method: HTTPMethod = HTTPMethod.GET,
+        session: Optional[ClientSession] = None,
+        headers: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        retries: Optional[int] = None,
+        backoff_factor: Optional[int] = None,
+        **kwargs
+    ) -> ClientResponse:
+        """
+        It makes the request using the session (externally provided or created
+        if required) and return the response...
+
+        :returns: `aiohttp.ClientResponse` object.
+        """
+
+        session_ = session or await self._ensure_session()
+        kwargs_ = kwargs.copy()
+
+        if timeout is not None:
+            kwargs_["timeout"] = ClientTimeout(total=timeout)
+
+        retries = retries if retries is not None else self.retries
+        attempts = 0
+
+        backoff_factor = (
+            backoff_factor
+            if backoff_factor is not None
+            else self.backoff_factor if self.backoff_factor is not None
+            else 0.5
+        )
+
+        while True:
+            attempts += 1
+
+            try:
+                response = await session_.request(
+                    method=str(method),
+                    url=url,
+                    headers=headers,
+                    params=params,
+                    **kwargs_)
+
+                if self.raise_for_status:
+                    response.raise_for_status()
+
+                return response
+
+            except ClientResponseError as error:
+                if attempts > retries:
+                    self.raise_custom_exception(error.status, error.message)
+
+                await asyncio.sleep(backoff_factor * attempts)
+
+    async def close(self):
+        if self._session and self._owns_session:
+            await self._session.close()
+            self._session = None

core_https-1.1.7/core_https/requesters/base.py

@@ -0,0 +1,161 @@
+# -*- coding: utf-8 -*-
+
+import re
+from abc import ABC
+from abc import abstractmethod
+from typing import Any, Dict, Optional
+
+from core_mixins.interfaces.factory import IFactory
+
+from core_https.exceptions import (
+    AuthenticationException,
+    AuthorizationException,
+    InternalServerError,
+    RateLimitException,
+    RetryableException,
+    ServiceException,
+)
+
+try:
+    from http import HTTPMethod
+
+except ImportError:
+    from core_https.utils import HTTPMethod
+
+
+class IRequester(IFactory, ABC):
+    """ Base interface for all type of HTTP requesters """
+
+    def __init__(
+        self,
+        encoding: str = "utf-8",
+        raise_for_status: bool = False,
+        retries: Optional[Any] = None,
+        backoff_factor: Optional[int] = None,
+        connector_limit: int = 100,
+        connector_limit_per_host: int = 30,
+        timeout: int = 10,
+    ) -> None:
+        """
+        :param encoding: The encoding to use when decoding.
+        :param raise_for_status: If True, `raise_for_status` will be executed.
+        :param connector_limit: Maximum number of connections in pool.
+        :param connector_limit_per_host: Maximum connections per host.
+        :param timeout: How many seconds to wait for the server to send data.
+        :param retries: Retry strategy to apply. Provide it here, to avoid passing it to each request.
+        :param backoff_factor: Delay between successive retry attempts.
+        """
+
+        if timeout <= 0:
+            raise ValueError("`timeout` must be positive!")
+
+        if connector_limit <= 0:
+            raise ValueError("`connector_limit` must be positive!")
+
+        if connector_limit_per_host <= 0:
+            raise ValueError("`connector_limit_per_host` must be positive!")
+
+        if connector_limit_per_host > connector_limit:
+            raise ValueError("`connector_limit_per_host` cannot exceed `connector_limit`!")
+
+        self.backoff_factor = backoff_factor
+        self.retries = retries
+
+        self.encoding = encoding
+        self.raise_for_status = raise_for_status
+        self.timeout = timeout
+
+        self.connector_limit = connector_limit
+        self.connector_limit_per_host = connector_limit_per_host
+
+    @classmethod
+    def registration_key(cls) -> str:
+        return cls.engine()
+
+    @classmethod
+    @abstractmethod
+    def engine(cls) -> str:
+        """ Must return the engine name like: `requests` or `urllib3` """
+
+    @abstractmethod
+    def request(
+        self,
+        url: str,
+        method: HTTPMethod,
+        headers: Optional[Dict[str, str]] = None,
+        retries: Optional[Any] = None,
+        backoff_factor: Optional[int] = None,
+        **kwargs  # Each `engine`have its own attributes...
+    ) -> Any:
+        """
+        Makes the request and returns the response.
+
+        :param url: The url for the request.
+        :param method: The method (verb) for the request.
+        :param headers: The headers to add.
+
+        :param retries:
+            It defines the retry strategy. Pass `False` if you don't want to use a
+            retry at all, otherwise a default one will be provided.
+
+        :param backoff_factor: Delay between successive retry attempts.
+
+        :param kwargs:
+            Each concrete implementation will have its own attributes. Depending on
+            the requester you are using, you can pass different attributes.
+        """
+
+    def _get_response_encoding(
+        self,
+        headers: Dict[str, str],
+        default="utf-8",
+    ) -> str:
+        headers_ = {
+            k.lower(): v
+            for k, v in headers.items()
+        }
+
+        # First trying "charset" header directly (rare)...
+        charset = headers_.get("charset")
+        if charset:
+            return charset.strip()
+
+        # Then checking `Content-Type` for "charset="
+        content_type = headers_.get("content-type", "")
+        match = re.search(r"charset=([^\s;]+)", content_type, re.IGNORECASE)
+        if match:
+            return match.group(1).strip()
+
+        return self.encoding or default
+
+    @staticmethod
+    def raise_custom_exception(status_code: int, details: str):
+        """
+        :raises: `ServiceException` for other 4XX status_code.
+        :raises: `AuthenticationException` for status_code == 401.
+        :raises: `AuthorizationException` for status_code == 403.
+        :raises: `RateLimitException` for status_code == 429.
+        :raises: `InternalServerError` for status_code >= 500.
+        """
+
+        error_cls = ServiceException
+
+        if status_code == 401:
+            error_cls = AuthenticationException
+
+        elif status_code == 403:
+            error_cls = AuthorizationException
+
+        elif status_code == 429:
+            error_cls = RateLimitException
+
+        elif status_code in (429, 502, 503, 504):
+            error_cls = RetryableException
+
+        elif status_code >= 500:
+            error_cls = InternalServerError
+
+        raise error_cls(
+            status_code=status_code,
+            details=details,
+        )

core_https-1.1.7/core_https/requesters/requests_.py

@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+
+from typing import Dict, Optional
+
+import requests
+import urllib3
+from requests.adapters import HTTPAdapter
+
+from core_https.requesters.base import IRequester
+from core_https.utils import HTTPMethod
+
+
+class RequestsRequester(IRequester):
+    """
+    It uses `requests` to make the requests.
+
+    .. code-block:: python
+
+        from core_https.requesters.requests_ import RequestsRequester
+        from core_https.utils import HTTPMethod
+
+        requester: RequestsRequester = RequestsRequester()
+
+        response = requester.request(
+            method=HTTPMethod.GET,
+            url=url,
+            params={
+                "x-api-key": "..."
+            })
+
+        print(response.json())
+    ..
+    """
+
+    def __init__(
+        self,
+        session: Optional[requests.Session] = None,
+        retries: Optional[urllib3.Retry] = None,
+        backoff_factor: Optional[int] = None,
+        **kwargs
+    ) -> None:
+        """
+        :param session: Session to use for the requests.
+        :param retries: Retry strategy to apply. Pass zero (0) to avoid retries.
+        """
+
+        super().__init__(**kwargs)
+        self.retries = retries
+
+        backoff_factor = (
+            backoff_factor
+            if backoff_factor is not None
+            else self.backoff_factor if self.backoff_factor is not None
+            else 0.5
+        )
+
+        if self.retries is None:
+            self.retries = urllib3.Retry(
+                status_forcelist=[429, 502, 503, 504],
+                backoff_factor=backoff_factor,
+                total=3)
+
+        adapter = HTTPAdapter(
+            pool_connections=self.connector_limit,
+            pool_maxsize=self.connector_limit_per_host,
+            max_retries=self.retries)
+
+        if session is None:
+            session = requests.Session()
+            session.mount("https://", adapter)
+            session.mount("http://", adapter)
+
+        self._session = session
+
+    @classmethod
+    def engine(cls) -> str:
+        return "requests"
+
+    def request(
+        self,
+        url: str,
+        method: HTTPMethod = HTTPMethod.GET,
+        session: Optional[requests.Session] = None,
+        headers: Optional[Dict] = None,
+        params: Optional[Dict] = None,
+        timeout: Optional[float] = None,
+        **kwargs
+    ) -> requests.Response:
+        """
+        It makes the request using the session (externally provided or created
+        if required) and return the response...
+
+        :returns: `requests.Response` object.
+        """
+
+        session_ = session or self._session
+        if params is None:
+            params = {}
+
+        response = session_.request(
+            method=method.value,
+            url=url,
+            headers=headers,
+            params=params,
+            timeout=timeout,
+            **kwargs)
+
+        try:
+            if self.raise_for_status:
+                response.raise_for_status()
+
+        except requests.exceptions.HTTPError:
+            status_code, info = response.status_code, response.text
+            self.raise_custom_exception(status_code, info)
+
+        return response

core_https-1.1.7/core_https/requesters/urllib3_.py

@@ -0,0 +1,117 @@
+# -*- coding: utf-8 -*-
+
+import json
+from contextlib import suppress
+from typing import Dict, Optional
+
+try:
+    from http import HTTPMethod
+
+except ImportError:
+    from core_https.utils import HTTPMethod
+
+from urllib3 import BaseHTTPResponse
+from urllib3 import PoolManager
+from urllib3 import Retry
+
+from .base import IRequester
+
+
+class Urllib3Requester(IRequester):
+    """
+    It uses `urllib3` to make the requests.
+
+    .. code-block:: python
+
+        from core_https.requesters.urllib3_ import Urllib3Requester
+        from core_https.utils import HTTPMethod
+
+        requester: Urllib3Requester = IRequester.get_class(Urllib3Requester.engine())()
+        response = requester.request(method=HTTPMethod.GET, url="https://google.com")
+        print(response.data.decode())
+    ..
+    """
+
+    def __init__(
+        self,
+        pool_manager: Optional[PoolManager] = None,
+        retries: Optional[Retry] = None,
+        **kwargs
+    ) -> None:
+        """
+        :param pool_manager: The pool manager to use or one will be created.
+        :param retries: Retry strategy to apply. Pass zero (0) to avoid retries.
+        """
+
+        super().__init__(**kwargs)
+
+        if not pool_manager:
+            pool_manager = PoolManager()
+
+        self._http: PoolManager = pool_manager
+        self.retries = retries
+
+    @classmethod
+    def engine(cls):
+        return "urllib3"
+
+    def request(
+        self,
+        url: str,
+        method: HTTPMethod = HTTPMethod.GET,
+        headers: Optional[Dict] = None,
+        fields: Optional[Dict] = None,
+        retries: Optional[Retry] = None,
+        backoff_factor: Optional[int] = None,
+        timeout: Optional[float] = None,
+        **kwargs
+    ) -> BaseHTTPResponse:
+        """
+        :raises: `ServiceException` for other 4XX status_code.
+        :raises: `AuthenticationException` for status_code == 401.
+        :raises: `AuthorizationException` for status_code == 403.
+        :raises: `InternalServerError` for status_code >= 500.
+
+        :returns: `HTTPResponse` object.
+        """
+
+        backoff_factor = (
+            backoff_factor
+            if backoff_factor is not None
+            else self.backoff_factor if self.backoff_factor is not None
+            else 0.5
+        )
+
+        retries_ = retries or self.retries
+        if retries_ is None:
+            retries_ = Retry(
+                status_forcelist=[429, 502, 503, 504],
+                backoff_factor=backoff_factor,
+                total=3)
+
+        response = self._http.request(
+            method=str(method),
+            url=url,
+            headers=headers,
+            fields=fields,
+            timeout=timeout or self.timeout,
+            retries=retries_,
+            **kwargs)
+
+        status_code = response.status
+
+        if status_code >= 400 and self.raise_for_status:
+            info = response.data.decode(self._get_response_encoding(response.headers))
+            headers_ = {k.lower(): v for k, v in response.headers.items()}
+
+            if "application/json" in headers_.get("content-type", ""):
+                if hasattr(response, "json"):
+                    info = response.json()
+
+                else:
+                    with suppress(json.JSONDecodeError):
+                        info = json.loads(info)
+
+            self.raise_custom_exception(status_code, info)
+
+        return response