atomhttp 1.0.0__py3-none-any.whl

atomhttp/core/config.py

@@ -0,0 +1,186 @@
+"""
+Request Configuration Module
+----------------------------
+Defines the configuration data class for HTTP requests in AtomHTTP.
+
+This module provides the RequestConfig dataclass which holds all configuration
+parameters for an HTTP request, similar to axios configuration objects.
+It supports timeouts, headers, authentication, proxies, redirects, data
+transformation, and various other request settings.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import Dict, Any, Optional, Callable, Union
+from datetime import timedelta
+
+
+@dataclass
+class RequestConfig:
+    """
+    Configuration object for HTTP requests, inspired by axios config.
+    
+    This dataclass holds all parameters needed to configure and execute
+    an HTTP request. It provides a flexible and extensible way to specify
+    request options including URL, method, headers, data, timeouts,
+    authentication, proxy settings, and response handling.
+    
+    Attributes:
+        url (str): Target URL for the request. Can be absolute or relative
+                  when used with baseURL.
+        
+        method (str): HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS).
+                     Defaults to 'GET'.
+        
+        baseURL (str): Base URL prepended to relative URLs. Useful for API clients.
+        
+        headers (Dict[str, str]): Custom HTTP headers to send with the request.
+                                 These override default headers.
+        
+        params (Dict[str, Any]): Query parameters to append to the URL.
+                                Automatically URL-encoded.
+        
+        data (Any): Request body data. Can be dict (JSON), str, bytes,
+                   FormData, or file-like object.
+        
+        timeout (Union[int, float, timedelta]): Request timeout in seconds.
+                                               Can be integer, float, or timedelta.
+                                               Defaults to 30 seconds.
+        
+        withCredentials (bool): Whether to send cookies with cross-site requests.
+                               Defaults to False.
+        
+        auth (Optional[Dict[str, str]]): Basic authentication credentials.
+                                        Format: {'username': 'user', 'password': 'pass'}
+        
+        proxy (Optional[Dict[str, Any]]): Proxy server configuration.
+                                         Format: {'host': 'http://proxy:8080', 'auth': {...}}
+        
+        maxRedirects (int): Maximum number of redirects to follow. Defaults to 5.
+        
+        maxContentLength (int): Maximum allowed response body size in bytes.
+                               -1 means no limit. Defaults to -1.
+        
+        maxBodyLength (int): Maximum allowed request body size in bytes.
+                            -1 means no limit. Defaults to -1.
+        
+        transformRequest (Optional[Callable]): Function to transform request data
+                                              before sending.
+        
+        transformResponse (Optional[Callable]): Function to transform response data
+                                               before returning.
+        
+        responseType (str): Expected response type. Options: 'json', 'text',
+                           'blob', 'arraybuffer', 'stream'. Defaults to 'json'.
+        
+        xsrfCookieName (str): Name of the cookie containing the XSRF token.
+                             Defaults to 'XSRF-TOKEN'.
+        
+        xsrfHeaderName (str): Name of the header to send XSRF token in.
+                             Defaults to 'X-XSRF-TOKEN'.
+        
+        onUploadProgress (Optional[Callable]): Callback for upload progress.
+                                              Receives (loaded, total) arguments.
+        
+        onDownloadProgress (Optional[Callable]): Callback for download progress.
+                                                Receives (loaded, total) arguments.
+        
+        socketPath (Optional[str]): Unix domain socket path for connection.
+                                   Example: '/var/run/docker.sock'
+        
+        keepAlive (bool): Enable HTTP keep-alive connections. Defaults to True.
+        
+        decompress (bool): Automatically decompress gzip/deflate responses.
+                          Defaults to True.
+        
+        validateStatus (Optional[Callable]): Function to determine if status code
+                                            should resolve or reject. Receives status.
+        
+        adapter (Optional[Any]): Custom HTTP adapter for request execution.
+        
+        transitional (Dict[str, bool]): Transitional configuration options for
+                                       backward compatibility.
+    """
+    
+    # Core request parameters
+    url: str = ''
+    method: str = 'GET'
+    baseURL: str = ''
+    
+    # Headers and parameters
+    headers: Dict[str, str] = field(default_factory=dict)
+    params: Dict[str, Any] = field(default_factory=dict)
+    data: Any = None
+    
+    # Timing and connection settings
+    timeout: Union[int, float, timedelta] = 30
+    withCredentials: bool = False
+    
+    # Authentication and proxy
+    auth: Optional[Dict[str, str]] = None
+    proxy: Optional[Dict[str, Any]] = None
+    
+    # Request limits and redirects
+    maxRedirects: int = 5
+    maxContentLength: int = -1
+    maxBodyLength: int = -1
+    
+    # Data transformation
+    transformRequest: Optional[Callable] = None
+    transformResponse: Optional[Callable] = None
+    
+    # Response handling
+    responseType: str = 'json'
+    
+    # CSRF protection
+    xsrfCookieName: str = 'XSRF-TOKEN'
+    xsrfHeaderName: str = 'X-XSRF-TOKEN'
+    
+    # Progress tracking
+    onUploadProgress: Optional[Callable] = None
+    onDownloadProgress: Optional[Callable] = None
+    
+    # Low-level connection options
+    socketPath: Optional[str] = None
+    keepAlive: bool = True
+    decompress: bool = True
+    
+    # Status validation
+    validateStatus: Optional[Callable] = None
+    
+    # Custom adapter
+    adapter: Optional[Any] = None
+    
+    # Transitional options for backward compatibility
+    transitional: Dict[str, bool] = field(default_factory=lambda: {
+        'silentJSONParsing': True,
+        'forcedJSONParsing': True,
+        'clarifyTimeoutError': False
+    })
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert the configuration to a dictionary, omitting None values.
+        
+        This method serializes the RequestConfig object to a dictionary
+        suitable for JSON serialization or for passing to other functions.
+        Special handling is applied to timedelta timeout values, converting
+        them to seconds.
+        
+        Returns:
+            Dict[str, Any]: Dictionary representation of the config with all
+                           non-None values included.
+        
+        Example:
+            >>> config = RequestConfig(url='/api', timeout=timedelta(seconds=5))
+            >>> config.to_dict()
+            {'url': '/api', 'timeout': 5.0}
+        """
+        # Convert dataclass to dictionary
+        data = asdict(self)
+        
+        # Convert timedelta to seconds if present
+        if isinstance(self.timeout, timedelta):
+            data['timeout'] = self.timeout.total_seconds()
+        
+        # Remove None values to keep the dictionary clean
+        return {k: v for k, v in data.items() if v is not None}

atomhttp/core/defaults.py

@@ -0,0 +1,212 @@
+"""
+Defaults Configuration Module
+-----------------------------
+Manages default configuration settings for the AtomHTTP client.
+
+This module provides the Defaults class which maintains the default
+configuration values for all AtomHTTP client instances. It supports
+merging custom configurations with defaults, updating individual
+settings, and accessing default values as attributes.
+"""
+
+from typing import Dict, Any
+from .config import RequestConfig
+
+
+class Defaults:
+    """
+    Default configuration manager for AtomHTTP client instances.
+    
+    This class holds the default configuration that will be applied to
+    all requests made by a AtomHTTP client unless overridden. It supports
+    updating defaults with custom values, accessing defaults as attributes,
+    and converting defaults to dictionary format.
+    
+    The Defaults class is designed to be used internally by the AtomHTTP
+    client, but can also be accessed directly for advanced use cases.
+    
+    Features:
+        - Centralized default configuration management
+        - Deep merging of header dictionaries
+        - Attribute-style access to configuration values
+        - Support for updating individual settings
+        - Dictionary conversion for serialization
+    
+    Attributes:
+        _config (RequestConfig): Internal RequestConfig object holding all
+                                default values.
+    
+    Example:
+        >>> defaults = Defaults()
+        >>> print(defaults.timeout)
+        30
+        >>> defaults.timeout = 60
+        >>> print(defaults.timeout)
+        60
+        >>> defaults.update(RequestConfig(headers={'X-Custom': 'value'}))
+        >>> print(defaults.headers['X-Custom'])
+        'value'
+    """
+    
+    def __init__(self):
+        """
+        Initialize default configuration with sensible defaults.
+        
+        Default values are chosen to provide a balanced experience
+        between security, performance, and compatibility:
+            - Accept header accepts JSON, text, and any format
+            - User-Agent identifies the client as atomhttp/2.0.0
+            - 30 second timeout prevents hanging requests
+            - Up to 5 redirects followed automatically
+            - JSON response parsing by default
+            - CSRF protection enabled with standard header names
+            - Credentials not sent cross-origin by default
+            - Keep-alive enabled for connection reuse
+            - Automatic gzip/deflate decompression enabled
+        """
+        self._config = RequestConfig(
+            # Default headers for all requests
+            headers={
+                'Accept': 'application/json, text/plain, */*',
+                'User-Agent': 'atomhttp/2.0.0'
+            },
+            # Request timeout in seconds
+            timeout=30,
+            # Maximum number of redirects to follow
+            maxRedirects=5,
+            # Default response parsing type
+            responseType='json',
+            # CSRF protection cookie name
+            xsrfCookieName='XSRF-TOKEN',
+            # CSRF protection header name
+            xsrfHeaderName='X-XSRF-TOKEN',
+            # Do not send credentials cross-origin by default
+            withCredentials=False,
+            # Enable HTTP keep-alive for connection reuse
+            keepAlive=True,
+            # Automatically decompress compressed responses
+            decompress=True,
+            # No base URL by default (use absolute URLs)
+            baseURL=''
+        )
+    
+    def update(self, config: RequestConfig):
+        """
+        Update default configuration with values from another config.
+        
+        This method merges the provided configuration into the defaults.
+        Headers are merged (custom headers added, existing ones overwritten),
+        while other fields are replaced entirely if non-None.
+        
+        Args:
+            config (RequestConfig): Configuration containing values to merge
+                                   into the defaults. Only non-None values
+                                   are considered for the update.
+        
+        Example:
+            >>> defaults = Defaults()
+            >>> custom = RequestConfig(
+            ...     headers={'X-API-Key': '12345'},
+            ...     timeout=15
+            ... )
+            >>> defaults.update(custom)
+            >>> print(defaults.timeout)  # Updated to 15
+            >>> print(defaults.headers['X-API-Key'])  # New header added
+        """
+        # Convert config to dictionary for iteration
+        config_dict = config.to_dict()
+        
+        # Process each key-value pair
+        for key, value in config_dict.items():
+            # Skip None values (they represent no change)
+            if value is not None and hasattr(self._config, key):
+                # Special handling for headers: merge dictionaries instead of replacing
+                if key == 'headers' and isinstance(value, dict):
+                    self._config.headers.update(value)
+                else:
+                    # Replace other attributes directly
+                    setattr(self._config, key, value)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert all default configuration to a dictionary.
+        
+        This method returns a complete dictionary representation of the
+        current default configuration, with None values omitted.
+        
+        Returns:
+            Dict[str, Any]: Dictionary containing all non-None default
+                           configuration values.
+        
+        Example:
+            >>> defaults = Defaults()
+            >>> defaults_dict = defaults.to_dict()
+            >>> print(defaults_dict.keys())
+            dict_keys(['headers', 'timeout', 'maxRedirects', ...])
+        """
+        return self._config.to_dict()
+    
+    def __getattr__(self, name):
+        """
+        Access configuration values as attributes.
+        
+        This magic method allows direct attribute access to configuration
+        values stored in the internal _config object.
+        
+        Args:
+            name (str): Name of the configuration attribute to retrieve
+            
+        Returns:
+            Any: Value of the requested configuration attribute
+            
+        Raises:
+            AttributeError: If the attribute doesn't exist in _config
+        
+        Example:
+            >>> defaults = Defaults()
+            >>> print(defaults.timeout)  # Access via __getattr__
+            30
+        """
+        return getattr(self._config, name)
+    
+    def __setattr__(self, name, value):
+        """
+        Set configuration values as attributes.
+        
+        This magic method routes attribute assignment to the internal
+        _config object, except for the special '_config' attribute itself.
+        
+        Args:
+            name (str): Name of the configuration attribute to set
+            value (Any): Value to assign to the configuration attribute
+        
+        Example:
+            >>> defaults = Defaults()
+            >>> defaults.timeout = 45  # Sets _config.timeout = 45
+        """
+        # Special handling for the internal _config attribute
+        if name == '_config':
+            super().__setattr__(name, value)
+        else:
+            # Route all other attribute assignments to the _config object
+            setattr(self._config, name, value)
+    
+    @property
+    def baseURL(self) -> str:
+        """
+        Get the base URL configured in defaults.
+        
+        Returns:
+            str: Current base URL value (empty string if not set)
+        """
+        return self._config.baseURL
+    
+    @baseURL.setter
+    def baseURL(self, value: str):
+        """
+        Set the base URL in defaults.
+        
+        Args:
+            value (str): New base URL value to set
+        """
+        self._config.baseURL = value

atomhttp/core/form_data.py

@@ -0,0 +1,282 @@
+"""
+FormData Module
+---------------
+Provides multipart/form-data and URL-encoded form data handling for AtomHTTP.
+
+This module implements a FormData class that mimics the browser's FormData API,
+allowing easy construction of form data for HTTP requests. It supports:
+    - Multiple values for the same field name
+    - File uploads with automatic MIME type detection
+    - Mixed field and file data in the same form
+    - Streaming of file contents without loading entire files into memory
+    - Conversion to both multipart/form-data and application/x-www-form-urlencoded formats
+"""
+
+import io
+import os
+import random
+import string
+from typing import Dict, Any, Optional, Union, Tuple, List
+from pathlib import Path
+from urllib.parse import urlencode
+
+
+class FormDataItem:
+    """
+    Represents a single item in a FormData field.
+    
+    FormData fields can have multiple values (e.g., for multi-select inputs),
+    and each value is stored as a FormDataItem. This class holds the value
+    along with optional metadata for file uploads.
+    
+    Attributes:
+        value (Any): The actual data value (string, bytes, file-like, Path, etc.)
+        filename (Optional[str]): Original filename for file uploads
+        content_type (Optional[str]): MIME type of the file content
+    """
+    
+    def __init__(self, value: Any, filename: Optional[str] = None, content_type: Optional[str] = None):
+        """
+        Initialize a form data item.
+        
+        Args:
+            value (Any): The data value. Can be string, bytes, file object, Path, etc.
+            filename (Optional[str]): Original filename (for file uploads)
+            content_type (Optional[str]): MIME type (auto-detected if not provided)
+        """
+        self.value = value
+        self.filename = filename
+        self.content_type = content_type
+
+
+class FormData:
+    """
+    FormData implementation similar to browser FormData API.
+    
+    This class provides a convenient interface for constructing form data
+    suitable for HTTP requests, supporting both multipart/form-data (for
+    file uploads and mixed content) and URL-encoded (for simple forms).
+    
+    Features:
+        - Append multiple values to the same field name
+        - Automatic MIME type detection from file extensions
+        - Support for various value types (str, bytes, file objects, Path)
+        - Streaming of large file contents
+        - Boundary generation for multipart requests
+    """
+    
+    def __init__(self):
+        """
+        Initialize an empty FormData object.
+        
+        The internal data structure maps field names to lists of FormDataItem
+        objects, allowing multiple values per field.
+        """
+        self._data: Dict[str, List[FormDataItem]] = {}
+        self._boundary: Optional[str] = None
+    
+    def append(self, name: str, value: Any, filename: Optional[str] = None, content_type: Optional[str] = None):
+        """
+        Append a value to a form data field.
+        
+        If the field name already exists, the new value is added to the list
+        of values for that field (multiple values are allowed).
+        
+        Args:
+            name (str): Field name
+            value (Any): Field value (string, bytes, file object, Path, etc.)
+            filename (Optional[str]): Original filename (for file uploads)
+            content_type (Optional[str]): MIME type (auto-detected from filename if not provided)
+        """
+        if name not in self._data:
+            self._data[name] = []
+        
+        item = FormDataItem(value, filename, content_type)
+        self._data[name].append(item)
+    
+    def delete(self, name: str):
+        """
+        Delete all values for a form data field.
+        
+        Args:
+            name (str): Field name to remove
+        """
+        if name in self._data:
+            del self._data[name]
+    
+    def get(self, name: str) -> Optional[Any]:
+        """
+        Get the first value of a form data field.
+        
+        Args:
+            name (str): Field name to retrieve
+            
+        Returns:
+            Optional[Any]: First value of the field, or None if field doesn't exist
+        """
+        if name in self._data and self._data[name]:
+            return self._data[name][0].value
+        return None
+    
+    def get_all(self, name: str) -> List[Any]:
+        """
+        Get all values of a form data field.
+        
+        Args:
+            name (str): Field name to retrieve
+            
+        Returns:
+            List[Any]: List of all values for the field (empty list if field doesn't exist)
+        """
+        if name in self._data:
+            return [item.value for item in self._data[name]]
+        return []
+    
+    def has(self, name: str) -> bool:
+        """
+        Check if a field exists in the form data.
+        
+        Args:
+            name (str): Field name to check
+            
+        Returns:
+            bool: True if field exists, False otherwise
+        """
+        return name in self._data
+    
+    def keys(self) -> List[str]:
+        """
+        Get all field names in the form data.
+        
+        Returns:
+            List[str]: List of all field names
+        """
+        return list(self._data.keys())
+    
+    def values(self) -> List[Any]:
+        """
+        Get all values in the form data (flattened).
+        
+        Returns:
+            List[Any]: List of all values (all items from all fields)
+        """
+        return [item.value for items in self._data.values() for item in items]
+    
+    def items(self) -> List[Tuple[str, Any]]:
+        """
+        Get all field-value pairs (flattened).
+        
+        Returns:
+            List[Tuple[str, Any]]: List of (field_name, value) tuples
+        """
+        return [(name, item.value) for name, items in self._data.items() for item in items]
+    
+    def _generate_boundary(self) -> str:
+        """
+        Generate a unique multipart boundary string.
+        
+        The boundary is a random string that separates different parts of
+        a multipart/form-data request. It's designed to be unique enough
+        to not appear in the actual data.
+        
+        Returns:
+            str: Random boundary string
+        """
+        return '----WebKitFormBoundary' + ''.join(random.choices(string.ascii_letters + string.digits, k=16))
+    
+    def to_multipart(self) -> Tuple[bytes, str]:
+        """
+        Convert form data to multipart/form-data format.
+        
+        This method serializes the FormData object into the multipart format
+        required by HTTP requests. Each field becomes a separate part with
+        its own headers and content.
+        
+        The format follows RFC 7578 (Returning Values from Forms: multipart/form-data).
+        
+        Returns:
+            Tuple[bytes, str]: A tuple containing:
+                - bytes: The complete multipart/form-data body
+                - str: The boundary string used for the multipart parts
+        """
+        if not self._boundary:
+            self._boundary = self._generate_boundary()
+        
+        lines = []
+        
+        for name, items in self._data.items():
+            for item in items:
+                lines.append(f'--{self._boundary}')
+                lines.append(f'Content-Disposition: form-data; name="{name}"')
+                
+                if item.filename:
+                    lines[-1] = f'Content-Disposition: form-data; name="{name}"; filename="{item.filename}"'
+                    
+                    if item.content_type:
+                        lines.append(f'Content-Type: {item.content_type}')
+                    else:
+                        ext = os.path.splitext(item.filename)[1].lower()
+                        content_types = {
+                            '.txt': 'text/plain',
+                            '.json': 'application/json',
+                            '.xml': 'application/xml',
+                            '.html': 'text/html',
+                            '.css': 'text/css',
+                            '.js': 'application/javascript',
+                            '.png': 'image/png',
+                            '.jpg': 'image/jpeg',
+                            '.jpeg': 'image/jpeg',
+                            '.gif': 'image/gif',
+                            '.pdf': 'application/pdf',
+                            '.zip': 'application/zip',
+                            '.mp4': 'video/mp4',
+                            '.mp3': 'audio/mpeg',
+                        }
+                        lines.append(f'Content-Type: {content_types.get(ext, "application/octet-stream")}')
+                
+                lines.append('')
+                
+                if isinstance(item.value, (bytes, bytearray)):
+                    lines.append(item.value)
+                elif isinstance(item.value, (io.IOBase, io.BufferedReader)):
+                    lines.append(item.value.read())
+                elif isinstance(item.value, Path):
+                    with open(item.value, 'rb') as f:
+                        lines.append(f.read())
+                else:
+                    lines.append(str(item.value).encode('utf-8'))
+                
+                lines.append('')
+        
+        lines.append(f'--{self._boundary}--')
+        lines.append('')
+        
+        result = []
+        for line in lines:
+            if isinstance(line, bytes):
+                result.append(line)
+            else:
+                result.append(line.encode('utf-8'))
+            result.append(b'\r\n')
+        
+        return b''.join(result), self._boundary
+    
+    def to_urlencoded(self) -> str:
+        """
+        Convert form data to application/x-www-form-urlencoded format.
+        
+        This method serializes the FormData object into the URL-encoded
+        format suitable for HTML forms without file uploads.
+        
+        Note: Only the first value of each field is included in the output.
+        Multiple values are not supported in standard URL-encoded forms.
+        
+        Returns:
+            str: URL-encoded form data string
+        """
+        params = {}
+        for name, items in self._data.items():
+            if items:
+                params[name] = items[0].value
+        
+        return urlencode(params)