atomhttp 1.0.0__py3-none-any.whl

atomhttp/__init__.py

@@ -0,0 +1,76 @@
+"""
+AtomHTTP - Professional HTTP Client for Python
+===============================================
+
+A comprehensive, asynchronous HTTP client for Python with features including:
+    - Full HTTP method support (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
+    - Request and response interceptors
+    - Upload and download progress tracking
+    - FormData (multipart/form-data) with file uploads
+    - Blob, ArrayBuffer, and stream response types
+    - Concurrent request helpers (all, spread)
+    - Base URL configuration
+    - Automatic JSON serialization/deserialization
+    - Comprehensive error handling with typed exceptions
+    - Type hints for better IDE support
+    - Mock adapter for testing
+    - Keep-alive connection pooling
+    - Proxy support
+    - Unix socket path support
+    - Configurable timeouts and redirect limits
+
+This module exports the main AtomHTTP client class along with all necessary
+types, exceptions, and utilities for making HTTP requests.
+
+Example:
+    >>> import asyncio
+    >>> from atomhttp import AtomHTTP
+    >>> 
+    >>> async def main():
+    ...     client = AtomHTTP({'baseURL': 'https://api.example.com'})
+    ...     response = await client.get('/users')
+    ...     print(response.status, response.data)
+    ...     await client.close()
+    >>> 
+    >>> asyncio.run(main())
+"""
+
+from .client import AtomHTTP
+from .errors.http_errors import (
+    AtomHTTPError,
+    AtomHTTPRequestError,
+    AtomHTTPNetworkError,
+    AtomHTTPTimeoutError
+)
+from .core.response import Response
+from .core.config import RequestConfig
+from .core.form_data import FormData
+from .core.adapters import HTTPAdapter, MockAdapter
+from .interceptors.manager import InterceptorManager
+
+__version__ = "2.0.0"
+
+__all__ = [
+    # Main client
+    "AtomHTTP",
+    
+    # Exception classes
+    "AtomHTTPError",
+    "AtomHTTPRequestError",
+    "AtomHTTPNetworkError",
+    "AtomHTTPTimeoutError",
+    
+    # Core types
+    "Response",
+    "RequestConfig",
+    
+    # Interceptor management
+    "InterceptorManager",
+    
+    # Data types
+    "FormData",
+    
+    # Adapters
+    "HTTPAdapter",
+    "MockAdapter",
+]

atomhttp/adapters/__init__.py

@@ -0,0 +1,4 @@
+from .http_adapter import HTTPAdapter
+from .mock_adapter import MockAdapter
+
+__all__ = ['HTTPAdapter', 'MockAdapter']

atomhttp/adapters/http_adapter.py

@@ -0,0 +1,102 @@
+"""
+HTTP Adapter Module
+-------------------
+This module provides the base HTTP adapter for making asynchronous HTTP requests
+using aiohttp. It handles request execution, timeout management, proxy support,
+and response processing.
+
+The HTTPAdapter is the default transport layer for the AtomHTTP client,
+responsible for converting RequestConfig objects into actual HTTP requests
+and wrapping responses into AtomHTTP Response objects.
+"""
+
+import aiohttp
+from typing import Optional
+from ..core.config import RequestConfig
+from ..core.response import Response
+
+
+class HTTPAdapter:
+    """
+    HTTP adapter for making asynchronous HTTP requests using aiohttp.
+    
+    This adapter serves as the transport layer for the AtomHTTP client,
+    handling the low-level details of HTTP communication including connection
+    management, timeout handling, proxy configuration, and response parsing.
+    
+    Attributes:
+        proxy (Optional[str]): Proxy server URL to use for requests.
+                              Format: 'http://proxy.example.com:8080'
+    """
+    
+    def __init__(self, proxy: Optional[str] = None):
+        """
+        Initialize the HTTP adapter with optional proxy configuration.
+        
+        Args:
+            proxy (Optional[str]): Proxy server URL. If provided, all requests
+                                  will be routed through this proxy.
+        """
+        self.proxy = proxy
+    
+    async def send(self, config: RequestConfig) -> Response:
+        """
+        Execute an HTTP request based on the provided configuration.
+        
+        This method performs the actual HTTP request using aiohttp,
+        handling all aspects of the request lifecycle including connection
+        establishment, timeout management, request headers and body,
+        redirect following, and response parsing.
+        
+        Args:
+            config (RequestConfig): Request configuration object containing all
+                                   request parameters such as URL, method,
+                                   headers, data, timeout, etc.
+        
+        Returns:
+            Response: A AtomHTTP Response object containing the parsed response
+                     data, status code, headers, and original configuration.
+        
+        Raises:
+            aiohttp.ClientError: If a network-related error occurs
+            asyncio.TimeoutError: If the request exceeds the configured timeout
+            json.JSONDecodeError: If response_type='json' and response is invalid JSON
+        """
+        # Configure timeout with total request duration limit
+        timeout = aiohttp.ClientTimeout(total=config.timeout)
+        
+        # Create TCP connector if proxy is configured
+        connector = None
+        if self.proxy:
+            connector = aiohttp.TCPConnector()
+        
+        # Create a new client session for this request
+        # Using async context manager ensures proper cleanup
+        async with aiohttp.ClientSession(connector=connector) as session:
+            # Execute the HTTP request with all configured parameters
+            async with session.request(
+                method=config.method,
+                url=config.url,
+                headers=config.headers,
+                params=config.params,
+                data=config.data,
+                timeout=timeout,
+                max_redirects=config.maxRedirects
+            ) as response:
+                # Parse response body based on expected response type
+                # JSON responses are automatically deserialized to dict/list
+                # Non-JSON responses are returned as plain text
+                if config.responseType == 'json':
+                    data = await response.json()
+                else:
+                    data = await response.text()
+                
+                # Wrap the aiohttp response in AtomHTTP's Response object
+                return Response(
+                    data=data,
+                    status=response.status,
+                    status_text=response.reason,
+                    headers=dict(response.headers),
+                    config=config,
+                    request=config
+                )

atomhttp/adapters/mock_adapter.py

@@ -0,0 +1,130 @@
+"""
+Mock Adapter Module
+-------------------
+This module provides a mock HTTP adapter for testing purposes.
+
+The MockAdapter allows developers to simulate HTTP responses without making
+actual network requests. This is useful for unit testing, integration testing,
+and development scenarios where external APIs are unavailable or undesirable
+to call directly.
+"""
+
+from typing import Dict, Any, Optional
+from ..core.config import RequestConfig
+from ..core.response import Response
+
+
+class MockAdapter:
+    """
+    Mock adapter for testing HTTP requests without actual network calls.
+    
+    This adapter stores predefined responses for specific request patterns
+    and returns them when matching requests are made. It enables isolated
+    testing of code that depends on HTTP responses without external dependencies.
+    
+    Features:
+        - Register mock responses for specific HTTP methods and URLs
+        - Customizable response data, status codes, and status texts
+        - Automatic 404 response for unregistered endpoints
+        - No actual network connections are established
+    
+    Attributes:
+        _responses (Dict[str, Dict]): Internal storage mapping request keys
+                                     to their configured mock responses.
+    
+    Example:
+        >>> mock = MockAdapter()
+        >>> mock.on('GET', 'https://api.test/users', {'users': []}, 200)
+        >>> response = await mock.send(config)
+    """
+    
+    def __init__(self):
+        """
+        Initialize an empty mock adapter with no predefined responses.
+        
+        Use the on() method to register mock responses before sending requests.
+        """
+        self._responses: Dict[str, Dict] = {}
+    
+    def on(self, method: str, url: str, response_data: Any, status: int = 200):
+        """
+        Register a mock response for a specific HTTP method and URL.
+        
+        When a request with the matching method and URL is sent through this
+        adapter, the registered response will be returned instead of making
+        an actual network request.
+        
+        Args:
+            method (str): HTTP method (GET, POST, PUT, DELETE, etc.)
+            url (str): Full URL or path that this mock should respond to
+            response_data (Any): Data to be returned as the response body.
+                                Can be dict, list, string, or any JSON-serializable type.
+            status (int): HTTP status code to return. Defaults to 200.
+        
+        Note:
+            If multiple responses are registered for the same method and URL,
+            the last registration will overwrite previous ones.
+        
+        Example:
+            >>> mock = MockAdapter()
+            >>> mock.on('GET', 'https://api.test/users', {'users': []}, 200)
+            >>> mock.on('POST', 'https://api.test/users', {'id': 1}, 201)
+            >>> mock.on('GET', 'https://api.test/users/1', {'name': 'John'}, 200)
+        """
+        # Create a unique key combining method and URL for lookup
+        key = f"{method}:{url}"
+        
+        # Store the mock response configuration
+        self._responses[key] = {
+            'data': response_data,
+            'status': status,
+            'status_text': 'OK' if status == 200 else 'Error'
+        }
+    
+    async def send(self, config: RequestConfig) -> Response:
+        """
+        Send a mock request and return a predefined response.
+        
+        This method looks up the request method and URL in the registered
+        responses. If a match is found, the corresponding mock response is
+        returned. Otherwise, a 404 Not Found response is returned.
+        
+        Args:
+            config (RequestConfig): Request configuration containing method and URL.
+                                   Other config fields (headers, data, etc.) are
+                                   ignored in mock mode.
+        
+        Returns:
+            Response: A AtomHTTP Response object containing either the registered
+                     mock data or a 404 error response.
+        
+        Note:
+            No actual HTTP request is made. The response is constructed entirely
+            from in-memory mock data, making this adapter suitable for tests
+            that require deterministic, repeatable responses.
+        """
+        # Build lookup key from request configuration
+        key = f"{config.method}:{config.url}"
+        
+        # Check if a mock response is registered for this request
+        if key in self._responses:
+            mock = self._responses[key]
+            # Return the registered mock response
+            return Response(
+                data=mock['data'],
+                status=mock['status'],
+                status_text=mock['status_text'],
+                headers={},
+                config=config,
+                request=config
+            )
+        else:
+            # Return default 404 response for unregistered endpoints
+            return Response(
+                data={'error': 'No mock found'},
+                status=404,
+                status_text='Not Found',
+                headers={},
+                config=config,
+                request=config
+            )

atomhttp/auth/__init__.py

@@ -0,0 +1,4 @@
+from .basic_auth import BasicAuth
+from .bearer_auth import BearerAuth
+
+__all__ = ['BasicAuth', 'BearerAuth']

atomhttp/auth/basic_auth.py

@@ -0,0 +1,90 @@
+"""
+Basic Authentication Module
+---------------------------
+This module provides Basic HTTP Authentication support for the AtomHTTP client.
+
+Basic Authentication is a simple authentication scheme built into the HTTP
+protocol. The client sends the username and password encoded in base64 within
+the Authorization header.
+"""
+
+import base64
+from typing import Dict
+
+
+class BasicAuth:
+    """
+    Basic Authentication handler for HTTP requests.
+    
+    This class implements the HTTP Basic Authentication scheme as defined in
+    RFC 7617. It handles the encoding of username and password credentials
+    into the standard Basic authentication header format.
+    
+    How Basic Auth Works:
+        1. Credentials are combined as "username:password"
+        2. The combined string is encoded using Base64
+        3. The encoded string is prefixed with "Basic " and sent in the
+           Authorization header
+        
+    Security Considerations:
+        - Base64 encoding is NOT encryption; it's easily reversible
+        - Basic Auth should ONLY be used over HTTPS connections
+        - Credentials are sent with every request
+        
+    Attributes:
+        username (str): The authentication username
+        password (str): The authentication password
+    
+    Example:
+        >>> auth = BasicAuth('admin', 'secret123')
+        >>> headers = auth.get_header()
+        >>> response = await client.get('/protected', headers=headers)
+    """
+    
+    def __init__(self, username: str, password: str):
+        """
+        Initialize Basic Authentication with username and password.
+        
+        Args:
+            username (str): The username for authentication
+            password (str): The password for authentication
+        
+        Note:
+            Username and password are stored in plain text in memory.
+            Always use HTTPS when using Basic Authentication.
+        """
+        self.username = username
+        self.password = password
+    
+    def get_header(self) -> Dict[str, str]:
+        """
+        Generate the HTTP Authorization header for Basic Authentication.
+        
+        This method encodes the username and password credentials according
+        to the Basic Authentication scheme and returns a dictionary ready
+        to be merged into request headers.
+        
+        The encoding process:
+            1. Combine username and password with a colon: "user:pass"
+            2. Encode the result to bytes using UTF-8
+            3. Apply Base64 encoding to the bytes
+            4. Decode back to string and prefix with "Basic "
+        
+        Returns:
+            Dict[str, str]: A dictionary containing the Authorization header.
+                           Format: {'Authorization': 'Basic <base64-credentials>'}
+        
+        Example:
+            >>> auth = BasicAuth('john', 'secret')
+            >>> header = auth.get_header()
+            >>> print(header)
+            {'Authorization': 'Basic am9objpzZWNyZXQ='}
+        """
+        # Combine username and password with colon separator as per RFC 7617
+        credentials = f"{self.username}:{self.password}"
+        
+        # Encode to bytes, then apply Base64 encoding
+        encoded = base64.b64encode(credentials.encode()).decode()
+        
+        # Return the complete Authorization header
+        return {'Authorization': f'Basic {encoded}'}

atomhttp/auth/bearer_auth.py

@@ -0,0 +1,83 @@
+"""
+Bearer Token Authentication Module
+----------------------------------
+This module provides Bearer Token authentication support for the AtomHTTP client.
+
+Bearer Token authentication (also known as Token-based authentication) is widely
+used in RESTful APIs, particularly with OAuth 2.0. The client sends a token
+in the Authorization header to prove identity.
+"""
+
+from typing import Dict
+
+
+class BearerAuth:
+    """
+    Bearer Token authentication handler for HTTP requests.
+    
+    This class implements the Bearer Token authentication scheme as defined in
+    RFC 6750. It adds an Authorization header with the Bearer token to HTTP
+    requests, which is the standard way to authenticate with OAuth 2.0 and
+    many modern REST APIs.
+    
+    How Bearer Auth Works:
+        1. Client obtains a token (JWT, opaque string, etc.) from an auth server
+        2. Token is sent in the Authorization header as "Bearer <token>"
+        3. Server validates the token and grants access if valid
+    
+    Security Considerations:
+        - Tokens should be kept secure and never exposed in logs or URLs
+        - Tokens typically have expiration times for security
+        - Always use HTTPS to prevent token interception
+        - Consider implementing token refresh mechanisms
+    
+    Attributes:
+        token (str): The bearer token string used for authentication
+    
+    Example:
+        >>> auth = BearerAuth('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...')
+        >>> headers = auth.get_header()
+        >>> response = await client.get('/api/protected', headers=headers)
+    """
+    
+    def __init__(self, token: str):
+        """
+        Initialize Bearer Token authentication with a token string.
+        
+        Args:
+            token (str): The bearer token string. This is typically a JWT
+                        (JSON Web Token) or an opaque string provided by
+                        the authentication server.
+        
+        Note:
+            The token is stored in plain text in memory. Ensure proper
+            handling and cleanup of tokens when no longer needed.
+        
+        Example:
+            >>> auth = BearerAuth('your-api-token-here')
+        """
+        self.token = token
+    
+    def get_header(self) -> Dict[str, str]:
+        """
+        Generate the HTTP Authorization header for Bearer Token authentication.
+        
+        This method creates the standard Authorization header format required
+        by RFC 6750 for Bearer token authentication. The token is prefixed
+        with "Bearer " to indicate the authentication scheme.
+        
+        The resulting header format:
+            Authorization: Bearer <token>
+        
+        Returns:
+            Dict[str, str]: A dictionary containing the Authorization header.
+                           Format: {'Authorization': 'Bearer <token>'}
+        
+        Example:
+            >>> auth = BearerAuth('abc123xyz')
+            >>> header = auth.get_header()
+            >>> print(header)
+            {'Authorization': 'Bearer abc123xyz'}
+        """
+        # Return the Authorization header with Bearer scheme prefix
+        return {'Authorization': f'Bearer {self.token}'}