atomhttp 1.0.0__py3-none-any.whl

atomhttp/progress/upload_progress.py

@@ -0,0 +1,89 @@
+"""
+Progress Tracker Module
+-----------------------
+Provides progress tracking functionality for upload and download operations.
+
+This module contains the ProgressTracker class which monitors data transfer
+progress and notifies callbacks as data is transmitted. It is used by the
+HTTP adapter to provide real-time progress updates for large uploads and
+downloads.
+"""
+
+from typing import Callable, Optional
+
+
+class ProgressTracker:
+    """
+    Track upload and download progress for HTTP operations.
+    
+    This class maintains progress state for data transfer operations and
+    invokes a callback function whenever progress is updated. It is designed
+    to work with both upload and download scenarios, tracking bytes transferred
+    against the total expected size (when known).
+    
+    The progress callback receives two arguments:
+        - loaded (int): Number of bytes transferred so far
+        - total (int): Total bytes expected (0 if unknown)
+    
+    Attributes:
+        callback (Optional[Callable]): Function called on each progress update.
+                                      Signature: callback(loaded: int, total: int)
+        total (int): Total bytes expected to transfer (0 if unknown)
+        loaded (int): Number of bytes transferred so far
+    """
+    
+    def __init__(self, callback: Optional[Callable] = None):
+        """
+        Initialize a new progress tracker.
+        
+        Args:
+            callback (Optional[Callable]): Function to call on progress updates.
+                                         Receives (loaded, total) arguments.
+                                         If None, progress is tracked but no
+                                         notifications are sent.
+        """
+        self.callback = callback
+        self.total = 0
+        self.loaded = 0
+    
+    def update(self, loaded: int, total: Optional[int] = None) -> None:
+        """
+        Update the current progress and notify callback if present.
+        
+        This method updates the amount of data transferred and optionally
+        sets the total expected size. After updating internal state, it
+        invokes the callback function (if provided) with the current
+        progress values.
+        
+        Args:
+            loaded (int): Current number of bytes transferred
+            total (Optional[int]): Total bytes expected to transfer.
+                                  If provided, updates self.total.
+                                  If None, self.total remains unchanged.
+        
+        Example:
+            >>> tracker = ProgressTracker(lambda l, t: print(f"{l}/{t}"))
+            >>> tracker.update(0, 100)   # Start: 0/100 bytes
+            >>> tracker.update(50)        # Halfway: 50/100 bytes
+            >>> tracker.update(100)       # Complete: 100/100 bytes
+        """
+        self.loaded = loaded
+        if total is not None:
+            self.total = total
+        
+        if self.callback:
+            self.callback(self.loaded, self.total)
+    
+    def reset(self) -> None:
+        """
+        Reset the progress tracker to initial state.
+        
+        This method resets both loaded and total counters to zero.
+        Useful when reusing the same tracker for multiple operations.
+        
+        Note:
+            This does not call the callback function. The callback will
+            be called on the next update() call with the reset values.
+        """
+        self.loaded = 0
+        self.total = 0

atomhttp/transforms/__init__.py

@@ -0,0 +1,5 @@
+from .request_transform import RequestTransformer
+from .response_transform import ResponseTransformer
+from .data_serializer import DataSerializer
+
+__all__ = ['RequestTransformer', 'ResponseTransformer', 'DataSerializer']

atomhttp/transforms/data_serializer.py

@@ -0,0 +1,96 @@
+"""
+Data Serializer Module
+----------------------
+Provides data serialization and deserialization utilities for different formats.
+
+This module contains the DataSerializer class with static methods for converting
+between Python data structures and various wire formats used in HTTP requests
+and responses, including JSON and URL-encoded form data.
+"""
+
+import json
+from typing import Any
+
+
+class DataSerializer:
+    """
+    Serialize and deserialize data for different content types.
+    
+    This utility class provides static methods for common data format
+    conversions needed in HTTP communication. It handles JSON serialization
+    and parsing, as well as URL-encoded form data serialization.
+    
+    All methods are static, so the class is not meant to be instantiated.
+    """
+    
+    @staticmethod
+    def serialize_json(data: Any) -> str:
+        """
+        Serialize Python object to JSON string.
+        
+        Converts Python data structures (dict, list, str, int, float, bool, None)
+        to a JSON formatted string. This is the inverse of to_json().
+        
+        Args:
+            data (Any): Python object to serialize. Must be JSON-serializable.
+                       Common types: dict, list, str, int, float, bool, None
+        
+        Returns:
+            str: JSON string representation of the input data
+        
+        Raises:
+            TypeError: If data contains non-serializable types
+            ValueError: If circular references are detected
+        
+        Example:
+            >>> DataSerializer.serialize_json({'name': 'John', 'age': 30})
+            '{"name": "John", "age": 30}'
+        """
+        return json.dumps(data)
+    
+    @staticmethod
+    def serialize_form_data(data: dict) -> str:
+        """
+        Serialize dictionary to URL-encoded form data string.
+        
+        Converts a dictionary of key-value pairs into a URL-encoded string
+        suitable for use as application/x-www-form-urlencoded body.
+        Values are automatically percent-encoded.
+        
+        Args:
+            data (dict): Dictionary of form fields. Keys and values are
+                        converted to strings and URL-encoded.
+        
+        Returns:
+            str: URL-encoded string in format 'key1=value1&key2=value2'
+        
+        Example:
+            >>> DataSerializer.serialize_form_data({'name': 'John Doe', 'age': 30})
+            'name=John%20Doe&age=30'
+        """
+        from urllib.parse import urlencode
+        return urlencode(data)
+    
+    @staticmethod
+    def to_json(data: str) -> Any:
+        """
+        Parse JSON string to Python object.
+        
+        Deserializes a JSON formatted string back into a Python data structure.
+        This is the inverse of serialize_json().
+        
+        Args:
+            data (str): JSON string to parse
+        
+        Returns:
+            Any: Python object (dict, list, str, int, float, bool, None)
+                depending on the JSON content
+        
+        Raises:
+            json.JSONDecodeError: If the string is not valid JSON
+        
+        Example:
+            >>> DataSerializer.to_json('{"name": "John", "age": 30}')
+            {'name': 'John', 'age': 30}
+        """
+        return json.loads(data)

atomhttp/transforms/request_transform.py

@@ -0,0 +1,96 @@
+"""
+Request Transformer Module
+--------------------------
+Handles transformation of request data before sending.
+
+This module provides the RequestTransformer class which applies various
+transformations to request configurations before they are sent over the
+network. Transformations include custom transform functions, automatic
+Content-Type header setting, and Basic authentication header generation.
+"""
+
+import json
+import base64
+from typing import Any
+from ..core.config import RequestConfig
+
+
+class RequestTransformer:
+    """
+    Transform request data before it is sent over the network.
+    
+    This class applies a series of transformations to RequestConfig objects
+    to prepare them for HTTP transmission. Transformations are applied in
+    a specific order:
+        1. Custom transformRequest function (if provided by user)
+        2. Automatic Content-Type header detection and setting
+        3. Basic authentication header generation (if auth credentials provided)
+    
+    The transformer is idempotent and can be called multiple times without
+    adverse effects, though it's designed to be called once per request.
+    """
+    
+    def transform(self, config: RequestConfig) -> RequestConfig:
+        """
+        Apply all request transformations to the configuration.
+        
+        This method modifies the request configuration in place and returns
+        it for method chaining. Transformations are applied in sequence:
+        
+        1. Custom transformation: If config.transformRequest is provided,
+           it is called with the current data and the result becomes the
+           new data.
+        
+        2. Content-Type auto-detection: If data is present and no
+           Content-Type header is set, the header is automatically added
+           based on data type (dict -> JSON, str -> text/plain).
+        
+        3. Basic Authentication: If config.auth contains username and
+           password, an Authorization header with Basic scheme is added.
+        
+        Args:
+            config (RequestConfig): The request configuration to transform
+            
+        Returns:
+            RequestConfig: The same configuration object after transformations
+                          (modified in place for efficiency)
+        
+        Example:
+            >>> transformer = RequestTransformer()
+            >>> config = RequestConfig(
+            ...     data={'name': 'John'},
+            ...     auth={'username': 'user', 'password': 'pass'}
+            ... )
+            >>> transformed = transformer.transform(config)
+            >>> print(transformed.headers['Content-Type'])
+            'application/json'
+            >>> print(transformed.headers['Authorization'])
+            'Basic dXNlcjpwYXNz'
+        """
+        # Apply custom request transformation if provided by user
+        # This allows users to modify data before any auto-transformations
+        if config.transformRequest:
+            config.data = config.transformRequest(config.data)
+        
+        # Automatically set Content-Type header based on data type
+        # Only applies if data exists and no Content-Type is already set
+        if config.data and 'Content-Type' not in config.headers:
+            if isinstance(config.data, dict):
+                # Dictionary data -> JSON format
+                config.headers['Content-Type'] = 'application/json'
+                config.data = json.dumps(config.data)
+            elif isinstance(config.data, str):
+                # String data -> plain text
+                config.headers['Content-Type'] = 'text/plain'
+        
+        # Handle Basic Authentication
+        # If auth dictionary contains username and password, generate Basic auth header
+        if config.auth:
+            # Combine username and password with colon separator
+            auth_str = f"{config.auth.get('username', '')}:{config.auth.get('password', '')}"
+            # Base64 encode the credentials
+            encoded = base64.b64encode(auth_str.encode()).decode()
+            # Add the Authorization header
+            config.headers['Authorization'] = f"Basic {encoded}"
+        
+        return config

atomhttp/transforms/response_transform.py

@@ -0,0 +1,73 @@
+"""
+Response Transformer Module
+---------------------------
+Handles transformation of response data after receiving.
+
+This module provides the ResponseTransformer class which applies transformations
+to response data before it is returned to the caller. Transformations include
+custom transformResponse functions provided by the user.
+"""
+
+import json
+from ..core.response import Response
+
+
+class ResponseTransformer:
+    """
+    Transform response data after it is received from the network.
+    
+    This class applies user-defined transformations to response data before
+    the response object is returned to the caller. The primary use case is
+    the transformResponse function that users can configure to modify or
+    preprocess response data.
+    
+    Transformations are applied in order:
+        1. Custom transformResponse function (if provided by user)
+    
+    The transformer is idempotent and can be called multiple times without
+    adverse effects, though it's designed to be called once per response.
+    """
+    
+    def transform(self, response: Response) -> Response:
+        """
+        Apply all response transformations to the response object.
+        
+        This method modifies the response data in place and returns the
+        response object for method chaining. The primary transformation is:
+        
+        1. Custom transformation: If response.config.transformResponse is
+           provided, it is called with the current response data and the
+           result becomes the new response data.
+        
+        This allows users to implement features like:
+            - Automatic date parsing
+            - Data normalization
+            - Error structure standardization
+            - Response caching
+            - Logging or analytics
+        
+        Args:
+            response (Response): The response object to transform
+            
+        Returns:
+            Response: The same response object after transformations
+                     (modified in place for efficiency)
+        
+        Example:
+            >>> transformer = ResponseTransformer()
+            >>> config = RequestConfig(transformResponse=lambda data: data.get('result', {}))
+            >>> response = Response(
+            ...     data={'result': {'id': 1, 'name': 'John'}},
+            ...     config=config,
+            ...     ...
+            ... )
+            >>> transformed = transformer.transform(response)
+            >>> print(transformed.data)
+            {'id': 1, 'name': 'John'}
+        """
+        # Apply custom response transformation if provided by user
+        # This allows users to modify or extract data before it reaches their code
+        if response.config.transformResponse:
+            response.data = response.config.transformResponse(response.data)
+        
+        return response

atomhttp/utils/__init__.py

@@ -0,0 +1,5 @@
+from .helpers import merge_headers, build_url, parse_params
+from .cookies import CookieManager
+from .redirect import RedirectHandler
+
+__all__ = ['merge_headers', 'build_url', 'parse_params', 'CookieManager', 'RedirectHandler']

atomhttp/utils/cookies.py

@@ -0,0 +1,128 @@
+"""
+Cookie Manager Module
+---------------------
+Provides HTTP cookie handling for the AtomHTTP client.
+
+This module contains the CookieManager class which manages HTTP cookies
+for client sessions. It supports setting, retrieving, and formatting cookies
+for requests, as well as parsing cookies from server responses.
+"""
+
+from http.cookies import SimpleCookie
+from typing import Dict, Optional
+
+
+class CookieManager:
+    """
+    Manage HTTP cookies for client sessions.
+    
+    This class wraps Python's SimpleCookie to provide a convenient interface
+    for cookie management in HTTP client operations. It supports:
+        - Setting cookies with additional attributes (domain, path, expires, etc.)
+        - Retrieving cookie values by name
+        - Generating Cookie header values for requests
+        - Parsing Set-Cookie headers from responses
+    
+    The manager maintains cookies across requests when the same client
+    instance is used, enabling session persistence.
+    
+    Attributes:
+        _cookies (SimpleCookie): Internal SimpleCookie object storing all cookies
+    """
+    
+    def __init__(self):
+        """
+        Initialize an empty cookie manager.
+        
+        No cookies are present initially. Cookies can be added via set_cookie()
+        or loaded from response headers via load_from_response().
+        """
+        self._cookies = SimpleCookie()
+    
+    def set_cookie(self, name: str, value: str, **kwargs) -> None:
+        """
+        Set a cookie with optional attributes.
+        
+        This method sets a cookie value and optionally adds attributes such
+        as domain, path, expires, secure, httponly, etc.
+        
+        Args:
+            name (str): Cookie name
+            value (str): Cookie value
+            **kwargs: Optional cookie attributes (domain, path, expires, max-age,
+                     secure, httponly, samesite, etc.)
+        
+        Example:
+            >>> manager = CookieManager()
+            >>> manager.set_cookie('session', 'abc123', domain='.example.com', path='/')
+            >>> manager.set_cookie('user', 'john', max_age=3600, secure=True)
+        """
+        self._cookies[name] = value
+        for key, val in kwargs.items():
+            self._cookies[name][key] = val
+    
+    def get_cookie(self, name: str) -> Optional[str]:
+        """
+        Get the value of a cookie by name.
+        
+        Args:
+            name (str): Name of the cookie to retrieve
+            
+        Returns:
+            Optional[str]: Cookie value if found, None otherwise
+        
+        Example:
+            >>> manager = CookieManager()
+            >>> manager.set_cookie('session', 'abc123')
+            >>> value = manager.get_cookie('session')
+            >>> print(value)
+            'abc123'
+        """
+        if name in self._cookies:
+            return self._cookies[name].value
+        return None
+    
+    def get_header(self) -> str:
+        """
+        Generate the Cookie header value for HTTP requests.
+        
+        This method formats all stored cookies into a string suitable for
+        the Cookie header. Cookies are formatted as "name=value" pairs
+        separated by semicolons.
+        
+        Returns:
+            str: Cookie header value (empty string if no cookies)
+        
+        Example:
+            >>> manager = CookieManager()
+            >>> manager.set_cookie('session', 'abc123')
+            >>> manager.set_cookie('user', 'john')
+            >>> print(manager.get_header())
+            'session=abc123; user=john'
+        """
+        return '; '.join([f"{k}={v.value}" for k, v in self._cookies.items()])
+    
+    def load_from_response(self, header: str) -> None:
+        """
+        Parse and load cookies from a Set-Cookie response header.
+        
+        This method processes Set-Cookie headers from server responses and
+        adds the cookies to the manager. Existing cookies with the same
+        name may be overwritten according to cookie precedence rules.
+        
+        Args:
+            header (str): The Set-Cookie header value from an HTTP response
+        
+        Example:
+            >>> manager = CookieManager()
+            >>> set_cookie = "session=abc123; Path=/; HttpOnly"
+            >>> manager.load_from_response(set_cookie)
+            >>> print(manager.get_cookie('session'))
+            'abc123'
+        
+        Note:
+            This method uses SimpleCookie.load() which parses the cookie
+            string according to RFC 6265. Multiple cookies in a single
+            header are supported as per the standard.
+        """
+        self._cookies.load(header)

atomhttp/utils/helpers.py

@@ -0,0 +1,111 @@
+"""
+URL and Header Utilities
+------------------------
+Helper functions for URL construction, header merging, and parameter parsing.
+
+This module provides utility functions for common operations needed in HTTP
+client operations, including merging headers, building URLs with query
+parameters, and parsing parameter dictionaries.
+"""
+
+from typing import Dict, Any, Optional
+from urllib.parse import urlencode, urljoin
+
+
+def merge_headers(default: Dict[str, str], custom: Dict[str, str]) -> Dict[str, str]:
+    """
+    Merge default headers with custom headers.
+    
+    Custom headers take precedence over default headers when keys conflict.
+    This function creates a new dictionary rather than modifying the originals.
+    
+    Args:
+        default (Dict[str, str]): Default headers (base values)
+        custom (Dict[str, str]): Custom headers that override defaults
+    
+    Returns:
+        Dict[str, str]: Merged headers dictionary where custom headers
+                       override default headers on key conflicts
+    
+    Example:
+        >>> default = {'Accept': 'application/json', 'User-Agent': 'client/1.0'}
+        >>> custom = {'Authorization': 'Bearer token', 'Accept': 'text/plain'}
+        >>> merged = merge_headers(default, custom)
+        >>> print(merged)
+        {'Accept': 'text/plain', 'User-Agent': 'client/1.0', 'Authorization': 'Bearer token'}
+    """
+    merged = default.copy()
+    merged.update(custom)
+    return merged
+
+
+def build_url(
+    base_url: str,
+    path: str,
+    params: Optional[Dict[str, Any]] = None
+) -> str:
+    """
+    Build a complete URL by combining base URL, path, and query parameters.
+    
+    This function handles both absolute and relative paths. If the path
+    already contains a protocol (http:// or https://), the base_url is
+    ignored and the path is used as the full URL.
+    
+    Args:
+        base_url (str): Base URL (e.g., 'https://api.example.com')
+        path (str): URL path (e.g., '/users' or 'https://other.com/api')
+        params (Optional[Dict[str, Any]]): Query parameters to append
+        
+    Returns:
+        str: Complete URL with path and query parameters properly encoded
+    
+    Example:
+        >>> build_url('https://api.example.com', '/users', {'page': 1, 'limit': 10})
+        'https://api.example.com/users?page=1&limit=10'
+        
+        >>> build_url('https://api.example.com', 'https://other.com/api')
+        'https://other.com/api'
+        
+        >>> build_url('https://api.example.com', '/search', {'q': 'python http'})
+        'https://api.example.com/search?q=python%20http'
+    """
+    # If path is absolute (has protocol), use it as the full URL
+    if path.startswith(('http://', 'https://')):
+        url = path
+    else:
+        # Combine base URL and relative path
+        url = urljoin(base_url, path)
+    
+    # Append query parameters if provided
+    if params:
+        query_string = urlencode(params)
+        # Add parameters as query string (appending if already exists)
+        if '?' not in url:
+            url = f"{url}?{query_string}"
+        else:
+            url = f"{url}&{query_string}"
+    
+    return url
+
+
+def parse_params(params: Dict[str, Any]) -> Dict[str, str]:
+    """
+    Parse and convert parameter dictionary to string-keyed dictionary.
+    
+    This function filters out None values and converts all values to strings,
+    preparing them for URL encoding or other string-based operations.
+    
+    Args:
+        params (Dict[str, Any]): Input parameters with any value types
+        
+    Returns:
+        Dict[str, str]: Filtered dictionary with None values removed and
+                       all values converted to strings
+    
+    Example:
+        >>> params = {'page': 1, 'limit': 10, 'sort': None, 'active': True}
+        >>> parsed = parse_params(params)
+        >>> print(parsed)
+        {'page': '1', 'limit': '10', 'active': 'True'}
+    """
+    return {k: str(v) for k, v in params.items() if v is not None}