core-https 1.1.7__py3-none-any.whl → 2.0.1__py3-none-any.whl

core_https/__init__.py

@@ -1,10 +1,23 @@
 # -*- coding: utf-8 -*-
 
+from core_mixins import StrEnum
+
 try:
-    from enum import StrEnum
+    from http import HTTPStatus as _HTTPStatus
 
 except ImportError:
-    from core_mixins.compatibility import StrEnum
+    from .utils import HTTPStatus as _HTTPStatus  # type: ignore
+
+
+__all__ = [
+    "HTTPStatus",
+    "StatusInfo"
+]
+
+
+# Type alias that works with both standard library
+# and the custom HTTPStatus...
+HTTPStatus = _HTTPStatus
 
 
 class StatusInfo(StrEnum):

core_https/exceptions.py

@@ -1,47 +1,121 @@
 # -*- coding: utf-8 -*-
 
+"""
+HTTP client exception hierarchy for the core_https library.
+
+This module provides a comprehensive set of exception classes for handling
+HTTP-related errors in a structured and consistent manner. The exception
+hierarchy is designed to allow for fine-grained error handling while
+maintaining compatibility with standard HTTP status codes.
+
+Exception Hierarchy:
+    Exception
+    └── InternalServerError (base for all HTTP errors)
+        ├── ServiceException (handled service errors)
+        │   ├── AuthenticationException (401 Unauthorized)
+        │   ├── AuthorizationException (403 Forbidden)
+        │   └── RateLimitException (429 Too Many Requests)
+        └── RetryableException (errors that should trigger retries)
+
+Usage Example:
+    Basic exception handling::
+
+        from core_https.exceptions import AuthenticationException, RateLimitException
+
+        try:
+            response = requester.request(url="https://api.example.com")
+        except AuthenticationException as e:
+            logger.error(f"Authentication failed: {e.details}")
+            # Handle authentication error
+        except RateLimitException as e:
+            logger.warning(f"Rate limited: {e.details}")
+            # Implement backoff strategy
+        except ServiceException as e:
+            logger.error(f"Service error {e.status_code}: {e.details}")
+            # Handle other service errors
+
+    Error information extraction::
+
+        try:
+            # HTTP request that fails
+            pass
+        except InternalServerError as e:
+            error_info = e.get_error_info()
+            # {'type': 'AuthenticationException', 'details': 'Invalid API key'}
+
+See Also:
+    - core_https.requesters.base.IRequester: Base requester that raises these exceptions
+    - HTTP status codes: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
+"""
+
 from typing import Dict
 
 
 class InternalServerError(Exception):
-    """ Base class for exceptions on the project and unhandled errors """
+    """
+    Base class for all HTTP-related exceptions in the core_https library.
+
+    This exception serves as the root of the HTTP exception hierarchy and handles
+    unhandled errors that occur during HTTP operations. It provides structured
+    error information including HTTP status codes and detailed error messages.
+
+    Attributes:
+        status_code: HTTP status code associated with the error
+        details: Detailed error message or description
+    """
 
-    def __init__(self, status_code: int, details: str, *args):
-        super(InternalServerError, self).__init__(*args)
+    def __init__(
+        self,
+        status_code: int,
+        details: str,
+        *args,
+    ) -> None:
+        super().__init__(*args)
         self.status_code = status_code
         self.details = details
 
-    def get_error_info(self) -> Dict:
+    def get_error_info(self) -> Dict[str, str]:
+        """
+        Get structured error information for logging or serialization.
+        :returns: Dictionary containing error type and details.
+        """
+
         return {
             "type": self.__class__.__name__,
-            "details": self.details
+            "details": self.details,
         }
 
 
 class ServiceException(InternalServerError):
-    """ Exception caused for handled errors within the service """
+    """Exception caused for handled errors within the service"""
 
 
 class AuthenticationException(ServiceException):
-    """ Exception caused for authentication [401] issues """
+    """Exception caused for authentication [401] issues"""
 
     def __init__(
         self,
         status_code: int = 401,
-        details: str = "Unauthorized"
+        details: str = "Unauthorized",
     ) -> None:
-        super().__init__(status_code=status_code, details=details)
+        super().__init__(
+            status_code=status_code,
+            details=details,
+        )
 
 
 class AuthorizationException(ServiceException):
-    """ Exception caused for authorization [403] issues """
+    """Exception caused for authorization [403] issues"""
 
     def __init__(
         self,
         status_code: int = 403,
-        details: str = "Forbidden"
+        details: str = "Forbidden",
     ) -> None:
-        super().__init__(status_code=status_code, details=details)
+        super().__init__(
+            status_code=status_code,
+            details=details,
+        )
 
 
 class RateLimitException(ServiceException):
@@ -53,15 +127,26 @@ class RateLimitException(ServiceException):
     def __init__(
         self,
         status_code: int = 429,
-        details: str = "Too Many Requests"
+        details: str = "Too Many Requests",
     ) -> None:
-        super().__init__(status_code=status_code, details=details)
+        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.
+    Exception for HTTP errors that should trigger retry mechanisms.
+
+    This exception represents temporary failures that are likely to succeed
+    if retried after a short delay. Common retryable status codes include:
+    - 429 Too Many Requests (rate limiting)
+    - 502 Bad Gateway (temporary server issue)
+    - 503 Service Unavailable (server overload)
+    - 504 Gateway Timeout (temporary timeout)
+
+    Example:
+        raise RetryableException(status_code=503, details="Service temporarily unavailable")
+        raise RetryableException(status_code=502, details="Bad gateway from upstream")
     """

core_https/requesters/aiohttp_.py

@@ -7,18 +7,6 @@ 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,
@@ -26,13 +14,31 @@ from aiohttp import (
     ClientTimeout,
     TCPConnector,
 )
+from core_mixins import Self
 
+from .base import HTTPMethod
 from .base import IRequester
 
 
 class AioHttpRequester(IRequester):
     """
-    It uses `aiohttp` to make the requests.
+    Asynchronous HTTP requester implementation using aiohttp.
+
+    This class provides an async HTTP client interface using the aiohttp library.
+    It supports automatic session management, configurable retry logic with exponential
+    backoff, connection pooling, and comprehensive error handling.
+
+    The requester can work with externally provided ClientSession objects or create
+    and manage its own session internally. It implements the async context manager
+    protocol for convenient resource cleanup.
+
+    Features:
+        - Automatic session creation and management
+        - Configurable retry logic with exponential backoff
+        - Connection pooling with configurable limits
+        - Comprehensive HTTP exception mapping
+        - Support for custom timeouts per request
+        - Context manager support for resource cleanup
 
     .. code-block:: python
 
@@ -72,11 +78,29 @@ class AioHttpRequester(IRequester):
         self,
         session: Optional[ClientSession] = None,
         retries: Optional[int] = 3,
-        **kwargs
+        **kwargs,
     ) -> None:
         """
-        :param session: The session to use for requests.
-        :param retries: Retry strategy to apply. Pass zero (0) to avoid retries.
+        Initialize the AioHttpRequester.
+
+        Args:
+            session: Optional pre-configured aiohttp ClientSession to use for requests.
+                If not provided, a new session will be created automatically with
+                the configured timeout and connection limits. When providing a custom
+                session, you are responsible for closing it.
+
+            retries: Number of retry attempts for failed requests. Defaults to 3.
+                Set to 0 to disable retries completely. Only applies to retryable
+                errors like network timeouts and server errors (5xx status codes).
+
+            **kwargs: Additional arguments passed to the base IRequester class,
+                including encoding, raise_for_status, backoff_factor, timeout,
+                connector_limit, and connector_limit_per_host.
+
+        Note:
+            The timeout specified in kwargs becomes the default session timeout.
+            Individual requests can override this using the timeout parameter
+            in the request() method.
         """
 
         super().__init__(**kwargs)
@@ -99,7 +123,25 @@ class AioHttpRequester(IRequester):
         return "aiohttp"
 
     async def _ensure_session(self) -> ClientSession:
-        """ If the session doesn't exist, it creates it """
+        """
+        Ensure a ClientSession exists, creating one if necessary.
+
+        This method implements a thread-safe lazy initialization pattern using
+        double-checked locking to ensure only one session is created even when
+        called concurrently from multiple coroutines.
+
+        Returns:
+            ClientSession: The active aiohttp ClientSession instance.
+
+        Note:
+            If a session was provided in the constructor, it will be returned as-is.
+            If no session was provided, a new one will be created with the configured
+            timeout and connection limits.
+
+        Thread Safety:
+            This method is safe to call concurrently from multiple coroutines.
+            The double-check locking pattern ensures only one session is created.
+        """
 
         if self._session is None:
             async with self._session_lock:
@@ -108,8 +150,9 @@ class AioHttpRequester(IRequester):
                         timeout=self._timeout,
                         connector=TCPConnector(
                             limit=self.connector_limit,
-                            limit_per_host=self.connector_limit_per_host
-                        ))
+                            limit_per_host=self.connector_limit_per_host,
+                        ),
+                    )
 
                     self._owns_session = True
 
@@ -119,19 +162,69 @@ class AioHttpRequester(IRequester):
         self,
         url: str,
         method: HTTPMethod = HTTPMethod.GET,
-        session: Optional[ClientSession] = None,
         headers: Optional[Dict[str, Any]] = None,
+        retries: Optional[int] = None,
+        backoff_factor: Optional[float] = None,
+        session: Optional[ClientSession] = None,
         params: Optional[Dict[str, Any]] = None,
         timeout: Optional[float] = None,
-        retries: Optional[int] = None,
-        backoff_factor: Optional[int] = None,
-        **kwargs
+        **kwargs,
     ) -> ClientResponse:
         """
-        It makes the request using the session (externally provided or created
-        if required) and return the response...
+        Make an asynchronous HTTP request with retry logic.
+
+        This method performs HTTP requests with automatic retry functionality,
+        exponential backoff, and comprehensive error handling. Failed requests
+        are retried based on the configured retry policy.
+
+        Args:
+            url: The target URL for the HTTP request.
 
-        :returns: `aiohttp.ClientResponse` object.
+            method: HTTP method to use. Defaults to GET. Supports all standard
+                HTTP methods (GET, POST, PUT, DELETE, etc.).
+
+            headers: Optional HTTP headers to include in the request. These will
+                be merged with any session-level headers.
+
+            retries: Number of retry attempts for this specific request.
+                If not provided, uses the instance-level retry setting.
+                Set to 0 to disable retries for this request.
+
+            backoff_factor: Multiplier for exponential backoff between retries.
+                The actual delay is calculated as: backoff_factor * attempt_number.
+                If not provided, uses the instance-level setting or defaults to 0.5.
+
+            session: Optional ClientSession to use for this request.
+                If not provided, uses the requester's session (creating one if necessary).
+                Useful for per-request session customization.
+
+            params: URL query parameters to include in the request.
+                Will be properly URL-encoded and appended to the URL.
+
+            timeout: Request timeout in seconds for this specific request.
+                Overrides the instance-level timeout setting.
+                Set to None to use the default timeout.
+
+            **kwargs: Additional parameters passed to aiohttp's request method.
+                Common options include: json, data, cookies, ssl, proxy, etc.
+                See aiohttp.ClientSession.request documentation for full list.
+
+        Returns:
+            ClientResponse: The aiohttp response object. Use methods like
+                .json(), .text(), .read() to extract the response content.
+
+        Raises:
+            AuthenticationException: For 401 Unauthorized responses.
+            AuthorizationException: For 403 Forbidden responses.
+            RateLimitException: For 429 Too Many Requests (when retries exhausted).
+            RetryableException: For 502/503/504 server errors (when retries exhausted).
+            ServiceException: For other 4xx client errors.
+            InternalServerError: For 5xx server errors (when retries exhausted).
+
+        Note:
+            The retry logic only applies to network errors and server errors (5xx).
+            Client errors (4xx) are not retried, except for 429 (rate limit)
+            which may be retried based on the configured policy.
         """
 
         session_ = session or await self._ensure_session()
@@ -141,15 +234,19 @@ class AioHttpRequester(IRequester):
             kwargs_["timeout"] = ClientTimeout(total=timeout)
 
         retries = retries if retries is not None else self.retries
-        attempts = 0
+        if retries is None:
+            retries = 3
 
         backoff_factor = (
             backoff_factor
             if backoff_factor is not None
-            else self.backoff_factor if self.backoff_factor is not None
+            else self.backoff_factor
+            if self.backoff_factor is not None
             else 0.5
         )
 
+        attempts = 0
+
         while True:
             attempts += 1
 
@@ -159,7 +256,8 @@ class AioHttpRequester(IRequester):
                     url=url,
                     headers=headers,
                     params=params,
-                    **kwargs_)
+                    **kwargs_,
+                )
 
                 if self.raise_for_status:
                     response.raise_for_status()
@@ -172,7 +270,24 @@ class AioHttpRequester(IRequester):
 
                 await asyncio.sleep(backoff_factor * attempts)
 
-    async def close(self):
+    async def close(self) -> None:
+        """
+        Close the internal session if it was created by this requester.
+
+        This method performs cleanup of the internal ClientSession, but only
+        if the session was created internally. If a custom session was provided
+        in the constructor, it will not be closed as the caller is responsible
+        for managing its lifecycle.
+
+        The session reference is always cleared after calling this method,
+        regardless of whether it was closed or not.
+
+        Note:
+            This method is automatically called when using the async context
+            manager protocol (__aexit__). Manual calling is only necessary
+            when not using the context manager pattern.
+        """
+
         if self._session and self._owns_session:
             await self._session.close()
-            self._session = None
+        self._session = None