atomhttp 1.0.0__py3-none-any.whl

atomhttp/core/request.py

@@ -0,0 +1,240 @@
+"""
+Request Handler Module
+----------------------
+Core request execution engine for AtomHTTP client.
+
+This module contains the RequestHandler class which orchestrates the entire
+request lifecycle including interceptor execution, request transformation,
+adapter selection, response transformation, and comprehensive error handling.
+"""
+
+import asyncio
+import aiohttp
+from typing import Optional, Any
+from .config import RequestConfig
+from .response import Response
+from .adapters import HTTPAdapter
+from ..transforms.request_transform import RequestTransformer
+from ..transforms.response_transform import ResponseTransformer
+from ..errors.http_errors import (
+    AtomHTTPRequestError, 
+    AtomHTTPTimeoutError, 
+    AtomHTTPNetworkError,
+    AtomHTTPError
+)
+
+
+class RequestHandler:
+    """
+    Core request handler that orchestrates the entire HTTP request lifecycle.
+    
+    This class is responsible for executing HTTP requests through a pipeline
+    of interceptors, transformers, and adapters. It manages the flow of
+    request execution from start to finish, applying all configured
+    middleware and transformations.
+    
+    The request flow follows this sequence:
+        1. Request interceptors are applied (can modify config)
+        2. Request data transformation is applied
+        3. URL validation is performed
+        4. HTTP adapter is selected and request is sent
+        5. Response transformation is applied
+        6. Response interceptors are applied
+        
+    Attributes:
+        defaults: Default configuration object for the client
+        interceptors (InterceptorManager): Manager for request/response interceptors
+        request_transformer (RequestTransformer): Handles request data transformation
+        response_transformer (ResponseTransformer): Handles response data transformation
+        default_adapter (HTTPAdapter): Default HTTP adapter for network requests
+    """
+    
+    def __init__(self, defaults, interceptor_manager):
+        """
+        Initialize the request handler with defaults and interceptors.
+        
+        Args:
+            defaults: Default configuration object containing base settings
+            interceptor_manager: Manager instance holding registered interceptors
+        """
+        self.defaults = defaults
+        self.interceptors = interceptor_manager
+        self.request_transformer = RequestTransformer()
+        self.response_transformer = ResponseTransformer()
+        self.default_adapter = HTTPAdapter()
+    
+    async def execute(self, config: RequestConfig) -> Response:
+        """
+        Execute a complete HTTP request through the full processing pipeline.
+        
+        This method orchestrates the entire request execution process:
+            1. Apply request interceptors (modify config before request)
+            2. Transform request data (serialization, auth headers, etc.)
+            3. Validate URL format
+            4. Select and execute HTTP adapter (network request)
+            5. Transform response data
+            6. Apply response interceptors (modify response after request)
+        
+        Args:
+            config (RequestConfig): Complete request configuration
+            
+        Returns:
+            Response: Final response after all transformations and interceptors
+            
+        Raises:
+            AtomHTTPRequestError: Invalid request or URL
+            AtomHTTPTimeoutError: Request timeout exceeded
+            AtomHTTPNetworkError: Network connectivity issues
+            AtomHTTPError: Base exception for all AtomHTTP errors
+        """
+        try:
+            # Step 1: Apply all registered request interceptors
+            # These can modify headers, add auth, log requests, etc.
+            modified_config = await self._apply_request_interceptors(config)
+            
+            # Step 2: Transform request data (JSON serialization, auth headers, etc.)
+            transformed_config = self.request_transformer.transform(modified_config)
+            
+            # Step 3: Validate that URL exists and has proper protocol
+            if not transformed_config.url:
+                raise AtomHTTPRequestError(
+                    "URL is required",
+                    request=transformed_config,
+                    config=transformed_config
+                )
+            
+            # Ensure URL uses HTTP or HTTPS protocol
+            if not (transformed_config.url.startswith('http://') or transformed_config.url.startswith('https://')):
+                raise AtomHTTPRequestError(
+                    f"Invalid URL: {transformed_config.url}. URL must start with http:// or https://",
+                    request=transformed_config,
+                    config=transformed_config
+                )
+            
+            # Step 4: Select adapter (custom or default) and execute request
+            adapter = transformed_config.adapter or self.default_adapter
+            response = await adapter.send(transformed_config)
+            
+            # Step 5: Transform response data (parse JSON, modify structure, etc.)
+            transformed_response = self.response_transformer.transform(response)
+            
+            # Step 6: Apply all registered response interceptors
+            final_response = await self._apply_response_interceptors(transformed_response)
+            
+            return final_response
+            
+        # Re-raise AtomHTTP errors without modification
+        except AtomHTTPError:
+            raise
+        
+        # Convert asyncio timeout to AtomHTTP timeout error
+        except asyncio.TimeoutError:
+            error = AtomHTTPTimeoutError(
+                f"Request timeout after {config.timeout}s",
+                config=config,
+                request=config
+            )
+            error.code = 'ECONNABORTED'
+            raise error
+        
+        # Convert aiohttp client errors to AtomHTTP network errors
+        except aiohttp.ClientError as e:
+            error = AtomHTTPNetworkError(str(e), config=config)
+            error.code = 'ERR_NETWORK'
+            raise error
+        
+        # Convert any other exception to AtomHTTP request error
+        except Exception as e:
+            if not isinstance(e, AtomHTTPError):
+                error = AtomHTTPRequestError(str(e), request=config, config=config)
+                error.code = 'ERR_BAD_REQUEST'
+                raise error
+            raise
+    
+    async def _apply_request_interceptors(self, config: RequestConfig) -> RequestConfig:
+        """
+        Apply all registered request interceptors in sequence.
+        
+        Request interceptors are executed in the order they were registered.
+        Each interceptor receives the current configuration and returns a
+        (potentially modified) configuration for the next interceptor.
+        
+        Args:
+            config (RequestConfig): Current request configuration
+            
+        Returns:
+            RequestConfig: Configuration after all interceptors have been applied
+            
+        Raises:
+            AtomHTTPRequestError: If any interceptor fails or returns invalid type
+        """
+        for idx, interceptor in enumerate(self.interceptors.request_interceptors):
+            try:
+                # Execute interceptor (supports both sync and async functions)
+                result = interceptor(config)
+                if asyncio.iscoroutine(result):
+                    config = await result
+                else:
+                    config = result
+                
+                # Validate interceptor return type
+                if not isinstance(config, RequestConfig):
+                    raise AtomHTTPRequestError(
+                        f"Request interceptor {idx} must return RequestConfig",
+                        request=config,
+                        config=config
+                    )
+            except AtomHTTPError:
+                raise
+            except Exception as e:
+                # Wrap any interceptor exception in AtomHTTP error
+                raise AtomHTTPRequestError(
+                    f"Request interceptor {idx} error: {str(e)}",
+                    request=config,
+                    config=config
+                )
+        return config
+    
+    async def _apply_response_interceptors(self, response: Response) -> Response:
+        """
+        Apply all registered response interceptors in sequence.
+        
+        Response interceptors are executed in the order they were registered.
+        Each interceptor receives the current response and returns a
+        (potentially modified) response for the next interceptor.
+        
+        Args:
+            response (Response): Current response object
+            
+        Returns:
+            Response: Response after all interceptors have been applied
+            
+        Raises:
+            AtomHTTPRequestError: If any interceptor fails or returns invalid type
+        """
+        for idx, interceptor in enumerate(self.interceptors.response_interceptors):
+            try:
+                # Execute interceptor (supports both sync and async functions)
+                result = interceptor(response)
+                if asyncio.iscoroutine(result):
+                    response = await result
+                else:
+                    response = result
+                
+                # Validate interceptor return type
+                if not isinstance(response, Response):
+                    raise AtomHTTPRequestError(
+                        f"Response interceptor {idx} must return Response",
+                        request=response.config,
+                        config=response.config
+                    )
+            except AtomHTTPError:
+                raise
+            except Exception as e:
+                # Wrap any interceptor exception in AtomHTTP error
+                raise AtomHTTPRequestError(
+                    f"Response interceptor {idx} error: {str(e)}",
+                    request=response.config,
+                    config=response.config
+                )
+        return response

atomhttp/core/response.py

@@ -0,0 +1,101 @@
+"""
+Response Module
+---------------
+HTTP response object for AtomHTTP client.
+
+This module provides the Response class that wraps HTTP responses with
+a consistent interface similar to axios responses. It includes response
+data, status code, headers, and references to the original request
+configuration.
+"""
+
+from typing import Any, Dict, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class Response:
+    """
+    HTTP response object similar to axios response interface.
+    
+    This class encapsulates all components of an HTTP response including
+    the parsed body, status information, headers, and the original request
+    configuration. It provides a clean, consistent interface for accessing
+    response data.
+    
+    The Response object is immutable by design (frozen dataclass semantics
+    are not enforced but should be treated as read-only after creation).
+    
+    Attributes:
+        data (Any): Parsed response body. Type depends on responseType:
+                   - 'json': dict or list
+                   - 'text': str
+                   - 'blob'/'arraybuffer': bytes
+                   - 'stream': aiohttp.StreamReader
+        status (int): HTTP status code (e.g., 200, 404, 500)
+        status_text (str): HTTP status message (e.g., "OK", "Not Found")
+        headers (Dict[str, str]): Response headers as a case-insensitive dict
+        config (Any): Original RequestConfig object used for the request
+        request (Any): Reference to the original request configuration
+                      (usually same as config, kept for axios compatibility)
+    
+    Properties:
+        ok (bool): True if status code is in the 200-299 range
+    
+    Example:
+        >>> response = Response(
+        ...     data={'id': 1, 'name': 'John'},
+        ...     status=200,
+        ...     status_text='OK',
+        ...     headers={'Content-Type': 'application/json'},
+        ...     config=original_config,
+        ...     request=original_config
+        ... )
+        >>> print(response.ok)
+        True
+        >>> print(response.status)
+        200
+    """
+    
+    data: Any
+    status: int
+    status_text: str
+    headers: Dict[str, str]
+    config: Any
+    request: Any
+    
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the response.
+        
+        Returns:
+            str: Formatted response string with status code and message
+        
+        Example:
+            >>> response = Response(data={}, status=200, status_text='OK', ...)
+            >>> print(repr(response))
+            '<Response [200] OK>'
+        """
+        return f"<Response [{self.status}] {self.status_text}>"
+    
+    @property
+    def ok(self) -> bool:
+        """
+        Check if the response status indicates success.
+        
+        A response is considered "ok" when the HTTP status code falls within
+        the 200-299 range (successful responses).
+        
+        Returns:
+            bool: True if status code is between 200 and 299 inclusive,
+                  False otherwise
+        
+        Example:
+            >>> response = Response(data={}, status=200, status_text='OK', ...)
+            >>> response.ok
+            True
+            >>> response = Response(data={}, status=404, status_text='Not Found', ...)
+            >>> response.ok
+            False
+        """
+        return 200 <= self.status < 300

atomhttp/errors/__init__.py

@@ -0,0 +1,13 @@
+from .http_errors import (
+    AtomHTTPError, 
+    AtomHTTPRequestError, 
+    AtomHTTPNetworkError, 
+    AtomHTTPTimeoutError
+)
+
+__all__ = [
+    'AtomHTTPError',
+    'AtomHTTPRequestError',
+    'AtomHTTPNetworkError',
+    'AtomHTTPTimeoutError'
+]

atomhttp/errors/http_errors.py

@@ -0,0 +1,142 @@
+"""
+HTTP Error Module
+-----------------
+Custom exception classes for AtomHTTP client error handling.
+
+This module provides a hierarchy of exception classes for different types
+of HTTP request failures, similar to axios error handling. Each error type
+includes relevant context such as request configuration, response data,
+and error codes for programmatic error identification.
+"""
+
+from typing import Optional, Any
+
+
+class AtomHTTPError(Exception):
+    """
+    Base exception class for all AtomHTTP errors.
+    
+    This is the parent class for all AtomHTTP-specific exceptions. It provides
+    common attributes that are useful for debugging and error handling.
+    
+    Attributes:
+        message (str): Human-readable error description
+        config (Optional[Any]): Request configuration that caused the error
+        response (Optional[Any]): Response object if error occurred after receiving response
+        request (Optional[Any]): Original request configuration (alias for config)
+        code (Optional[str]): Standardized error code for programmatic handling
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        config: Optional[Any] = None,
+        response: Optional[Any] = None,
+        request: Optional[Any] = None
+    ):
+        """
+        Initialize a AtomHTTP error with optional context.
+        
+        Args:
+            message (str): Human-readable error description
+            config (Optional[Any]): Request configuration used for the request
+            response (Optional[Any]): Response object (if available)
+            request (Optional[Any]): Original request (usually same as config)
+        """
+        super().__init__(message)
+        self.message = message
+        self.config = config
+        self.response = response
+        self.request = request
+        self.code: Optional[str] = None
+
+
+class AtomHTTPRequestError(AtomHTTPError):
+    """
+    Exception raised for bad requests or client errors (4xx status codes).
+    
+    This error occurs when the request is malformed, validation fails,
+    or the server responds with a client error status code (400-499).
+    
+    Error Code: 'ERR_BAD_REQUEST'
+    
+    Attributes:
+        code (str): Standardized error code always set to 'ERR_BAD_REQUEST'
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        request: Optional[Any] = None,
+        config: Optional[Any] = None,
+        response: Optional[Any] = None
+    ):
+        """
+        Initialize a request error.
+        
+        Args:
+            message (str): Error description
+            request (Optional[Any]): Original request that failed
+            config (Optional[Any]): Request configuration (alias for request)
+            response (Optional[Any]): Response from server (if available)
+        """
+        super().__init__(message, config=config, response=response, request=request)
+        self.code = 'ERR_BAD_REQUEST'
+
+
+class AtomHTTPNetworkError(AtomHTTPError):
+    """
+    Exception raised for network-related failures.
+    
+    This error occurs when the request cannot reach the server due to
+    network issues such as DNS resolution failure, connection refused,
+    SSL errors, or general connectivity problems.
+    
+    Error Code: 'ERR_NETWORK'
+    
+    Attributes:
+        code (str): Standardized error code always set to 'ERR_NETWORK'
+    """
+    
+    def __init__(self, message: str, config: Optional[Any] = None):
+        """
+        Initialize a network error.
+        
+        Args:
+            message (str): Error description (connection error, DNS error, etc.)
+            config (Optional[Any]): Request configuration used for the request
+        """
+        super().__init__(message, config=config)
+        self.code = 'ERR_NETWORK'
+
+
+class AtomHTTPTimeoutError(AtomHTTPError):
+    """
+    Exception raised when a request exceeds the configured timeout.
+    
+    This error occurs when the request takes longer than the specified
+    timeout value. The request may have been partially sent or the
+    response may have been partially received before timeout occurred.
+    
+    Error Code: 'ECONNABORTED'
+    
+    Attributes:
+        code (str): Standardized error code always set to 'ECONNABORTED'
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        config: Optional[Any] = None,
+        request: Optional[Any] = None
+    ):
+        """
+        Initialize a timeout error.
+        
+        Args:
+            message (str): Error description with timeout duration
+            config (Optional[Any]): Request configuration used for the request
+            request (Optional[Any]): Original request (alias for config)
+        """
+        super().__init__(message, config=config, request=request)
+        self.code = 'ECONNABORTED'

atomhttp/interceptors/__init__.py

@@ -0,0 +1,5 @@
+from .manager import InterceptorManager
+from .request_interceptor import RequestInterceptor
+from .response_interceptor import ResponseInterceptor
+
+__all__ = ['InterceptorManager', 'RequestInterceptor', 'ResponseInterceptor']

atomhttp/interceptors/manager.py

@@ -0,0 +1,136 @@
+"""
+Interceptor Manager Module
+--------------------------
+Manages request and response interceptors for the AtomHTTP client.
+
+This module provides the InterceptorManager class which handles registration,
+execution order, and removal of interceptors. Interceptors allow modifying
+requests before they are sent and responses before they are returned to
+the caller, similar to middleware in other HTTP clients.
+"""
+
+from typing import List, Callable, Any
+
+
+class InterceptorManager:
+    """
+    Manages request and response interceptors for the HTTP client.
+    
+    Interceptors are functions that can modify requests before they are
+    sent or modify responses before they are returned to the caller.
+    This enables functionality such as:
+        - Adding authentication headers to all requests
+        - Logging requests and responses
+        - Retrying failed requests
+        - Transforming request/response data
+        - Handling errors globally
+    
+    The interceptor execution order follows the registration order:
+        - Request interceptors execute in the order they were added
+        - Response interceptors execute in the order they were added
+    
+    Interceptors can be either synchronous or asynchronous functions.
+    Asynchronous interceptors must be declared with `async def`.
+    
+    Attributes:
+        request_interceptors (List[Callable]): List of request interceptor functions
+        response_interceptors (List[Callable]): List of response interceptor functions
+    """
+    
+    def __init__(self):
+        """
+        Initialize an empty interceptor manager.
+        
+        Both request and response interceptor lists start empty.
+        Use the use() method to add interceptors.
+        """
+        self.request_interceptors: List[Callable] = []
+        self.response_interceptors: List[Callable] = []
+    
+    def use(self, interceptor: Callable, is_response: bool = False) -> int:
+        """
+        Add an interceptor to the manager.
+        
+        The interceptor will be added to the end of the list and will
+        be executed after all previously added interceptors.
+        
+        Args:
+            interceptor (Callable): The interceptor function.
+                                  Can be sync: `fn(config)` or `fn(response)`
+                                  or async: `async fn(config)` or `async fn(response)`
+            is_response (bool): If True, adds to response interceptors list.
+                               If False (default), adds to request interceptors list.
+        
+        Returns:
+            int: The index of the added interceptor. This index can be used
+                with the eject() method to remove the interceptor later.
+        
+        Example:
+            >>> manager = InterceptorManager()
+            >>> 
+            >>> # Request interceptor (adds auth header)
+            >>> async def add_auth(config):
+            ...     config.headers['Authorization'] = 'Bearer token'
+            ...     return config
+            >>> 
+            >>> index = manager.use(add_auth)  # Request interceptor
+            >>> 
+            >>> # Response interceptor (logs response)
+            >>> async def log_response(response):
+            ...     print(f"Status: {response.status}")
+            ...     return response
+            >>> 
+            >>> resp_index = manager.use(log_response, is_response=True)
+        """
+        if is_response:
+            self.response_interceptors.append(interceptor)
+            return len(self.response_interceptors) - 1
+        else:
+            self.request_interceptors.append(interceptor)
+            return len(self.request_interceptors) - 1
+    
+    def eject(self, index: int, is_response: bool = False) -> None:
+        """
+        Remove an interceptor by its index.
+        
+        This method removes the interceptor at the specified index from
+        either the request or response interceptor list. The index must
+        be the one returned by the use() method when the interceptor
+        was added.
+        
+        Args:
+            index (int): Index of the interceptor to remove
+            is_response (bool): If True, removes from response interceptors list.
+                               If False (default), removes from request interceptors list.
+        
+        Example:
+            >>> manager = InterceptorManager()
+            >>> index = manager.use(some_interceptor)
+            >>> # Later...
+            >>> manager.eject(index)  # Remove the interceptor
+        
+        Note:
+            If the index is out of range, the method does nothing (no error raised).
+        """
+        if is_response:
+            if 0 <= index < len(self.response_interceptors):
+                self.response_interceptors.pop(index)
+        else:
+            if 0 <= index < len(self.request_interceptors):
+                self.request_interceptors.pop(index)
+    
+    def clear(self) -> None:
+        """
+        Remove all registered interceptors.
+        
+        This method clears both request and response interceptor lists,
+        effectively resetting the manager to its initial empty state.
+        
+        Example:
+            >>> manager = InterceptorManager()
+            >>> manager.use(interceptor1)
+            >>> manager.use(interceptor2, is_response=True)
+            >>> manager.clear()  # Removes all interceptors
+        """
+        self.request_interceptors.clear()
+        self.response_interceptors.clear()

atomhttp/interceptors/request_interceptor.py

@@ -0,0 +1,18 @@
+"""
+Request Interceptor Type Definition
+-----------------------------------
+Type hint for request interceptor functions in AtomHTTP.
+
+This module defines the RequestInterceptor type alias for use in type annotations
+throughout the AtomHTTP codebase. Request interceptors are functions that
+modify or inspect request configurations before they are sent.
+"""
+
+from typing import Callable, Awaitable
+from ..core.config import RequestConfig
+
+# Type alias for request interceptor functions
+# Request interceptors receive a RequestConfig object and return a
+# (potentially modified) RequestConfig object. They can be either
+# synchronous or asynchronous.
+RequestInterceptor = Callable[[RequestConfig], Awaitable[RequestConfig]]

atomhttp/interceptors/response_interceptor.py

@@ -0,0 +1,18 @@
+"""
+Response Interceptor Type Definition
+------------------------------------
+Type hint for response interceptor functions in AtomHTTP.
+
+This module defines the ResponseInterceptor type alias for use in type annotations
+throughout the AtomHTTP codebase. Response interceptors are functions that
+modify or inspect response objects before they are returned to the caller.
+"""
+
+from typing import Callable, Awaitable
+from ..core.response import Response
+
+# Type alias for response interceptor functions
+# Response interceptors receive a Response object and return a
+# (potentially modified) Response object. They can be either
+# synchronous or asynchronous.
+ResponseInterceptor = Callable[[Response], Awaitable[Response]]

atomhttp/progress/__init__.py

@@ -0,0 +1,3 @@
+from .upload_progress import ProgressTracker
+
+__all__ = ['ProgressTracker']