dexscreen 0.0.1__py3-none-any.whl → 0.0.4__py3-none-any.whl

dexscreen/utils/retry.py

@@ -0,0 +1,357 @@
+"""
+Retry mechanism with exponential backoff for network operations
+"""
+
+import asyncio
+import logging
+import random
+import time
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar
+
+import curl_cffi.requests.exceptions
+
+# Type variables for generic function decorators
+F = TypeVar("F", bound=Callable[..., Any])
+AsyncF = TypeVar("AsyncF", bound=Callable[..., Any])
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RetryConfig:
+    """Configuration for retry behavior"""
+
+    max_retries: int = 3
+    base_delay: float = 1.0  # Base delay in seconds
+    max_delay: float = 60.0  # Maximum delay in seconds
+    backoff_factor: float = 2.0  # Exponential backoff multiplier
+    jitter: bool = True  # Add random jitter to prevent thundering herd
+    retryable_status_codes: set[int] = field(
+        default_factory=lambda: {
+            408,  # Request Timeout
+            429,  # Too Many Requests
+            500,  # Internal Server Error
+            502,  # Bad Gateway
+            503,  # Service Unavailable
+            504,  # Gateway Timeout
+            520,  # Web Server Returned an Unknown Error
+            521,  # Web Server Is Down
+            522,  # Connection Timed Out
+            523,  # Origin Is Unreachable
+            524,  # A Timeout Occurred
+        }
+    )
+    retryable_exceptions: tuple[type[Exception], ...] = field(
+        default_factory=lambda: (
+            # Network-related exceptions
+            curl_cffi.requests.exceptions.ConnectionError,
+            curl_cffi.requests.exceptions.Timeout,
+            curl_cffi.requests.exceptions.ReadTimeout,
+            curl_cffi.requests.exceptions.ConnectTimeout,
+            # OS-level network errors
+            OSError,
+            ConnectionError,
+            TimeoutError,
+        )
+    )
+
+    def __post_init__(self):
+        """Validate configuration"""
+        if self.max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+        if self.base_delay <= 0:
+            raise ValueError("base_delay must be positive")
+        if self.max_delay <= 0:
+            raise ValueError("max_delay must be positive")
+        if self.backoff_factor <= 1:
+            raise ValueError("backoff_factor must be greater than 1")
+
+
+class RetryError(Exception):
+    """Raised when all retry attempts have been exhausted"""
+
+    def __init__(self, message: str, original_exception: Exception, attempts: int):
+        super().__init__(message)
+        self.original_exception = original_exception
+        self.attempts = attempts
+
+
+def calculate_delay(attempt: int, config: RetryConfig) -> float:
+    """
+    Calculate delay for exponential backoff with optional jitter.
+
+    Args:
+        attempt: Current attempt number (0-based)
+        config: Retry configuration
+
+    Returns:
+        Delay in seconds
+    """
+    # Calculate exponential delay
+    delay = min(config.base_delay * (config.backoff_factor**attempt), config.max_delay)
+
+    # Add jitter if enabled
+    if config.jitter:
+        # Add random jitter up to 25% of the delay
+        jitter = delay * 0.25 * random.random()
+        delay += jitter
+
+    return delay
+
+
+def is_retryable(exception: Exception, config: RetryConfig) -> bool:
+    """
+    Determine if an exception is retryable based on configuration.
+
+    Args:
+        exception: The exception to check
+        config: Retry configuration
+
+    Returns:
+        True if the exception should trigger a retry
+    """
+    # Check if it's a retryable exception type
+    if isinstance(exception, config.retryable_exceptions):
+        return True
+
+    # Check if it's an HTTP response with retryable status code
+    if hasattr(exception, "response") and hasattr(exception.response, "status_code"):  # type: ignore[attr-defined]
+        return exception.response.status_code in config.retryable_status_codes  # type: ignore[attr-defined]
+
+    # Check for curl_cffi specific status codes
+    try:
+        if (
+            hasattr(curl_cffi.requests.exceptions, "HTTPError")
+            and isinstance(exception, curl_cffi.requests.exceptions.HTTPError)
+            and hasattr(exception, "response")
+            and exception.response is not None
+            and hasattr(exception.response, "status_code")
+        ):
+            return exception.response.status_code in config.retryable_status_codes
+    except AttributeError:
+        # curl_cffi.requests.exceptions.HTTPError doesn't exist, skip this check
+        pass
+
+    return False
+
+
+def retry_sync(config: Optional[RetryConfig] = None):
+    """
+    Decorator for synchronous functions with retry logic.
+
+    Args:
+        config: Retry configuration. If None, uses default RetryConfig.
+
+    Returns:
+        Decorated function
+    """
+    if config is None:
+        config = RetryConfig()
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            last_exception = None
+
+            for attempt in range(config.max_retries + 1):
+                try:
+                    result = func(*args, **kwargs)
+
+                    # Log successful retry if this wasn't the first attempt
+                    if attempt > 0:
+                        logger.info("Function %s succeeded after %d retries", func.__name__, attempt)
+
+                    return result
+
+                except Exception as e:
+                    last_exception = e
+
+                    # Check if we should retry
+                    if attempt < config.max_retries and is_retryable(e, config):
+                        delay = calculate_delay(attempt, config)
+
+                        logger.warning(
+                            "Function %s failed (attempt %d/%d): %s. Retrying in %.2f seconds",
+                            func.__name__,
+                            attempt + 1,
+                            config.max_retries + 1,
+                            str(e),
+                            delay,
+                        )
+
+                        time.sleep(delay)
+                    else:
+                        # Not retryable or max retries exceeded
+                        break
+
+            # All retries exhausted
+            error_msg = f"Function {func.__name__} failed after {config.max_retries + 1} attempts"
+            if last_exception:
+                logger.error("%s. Last error: %s", error_msg, str(last_exception))
+                raise RetryError(error_msg, last_exception, config.max_retries + 1)
+            else:
+                # This should never happen, but handle it gracefully
+                logger.error(error_msg)
+                raise RuntimeError(error_msg)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def retry_async(config: Optional[RetryConfig] = None):
+    """
+    Decorator for asynchronous functions with retry logic.
+
+    Args:
+        config: Retry configuration. If None, uses default RetryConfig.
+
+    Returns:
+        Decorated function
+    """
+    if config is None:
+        config = RetryConfig()
+
+    def decorator(func: AsyncF) -> AsyncF:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            last_exception = None
+
+            for attempt in range(config.max_retries + 1):
+                try:
+                    result = await func(*args, **kwargs)
+
+                    # Log successful retry if this wasn't the first attempt
+                    if attempt > 0:
+                        logger.info("Function %s succeeded after %d retries", func.__name__, attempt)
+
+                    return result
+
+                except Exception as e:
+                    last_exception = e
+
+                    # Check if we should retry
+                    if attempt < config.max_retries and is_retryable(e, config):
+                        delay = calculate_delay(attempt, config)
+
+                        logger.warning(
+                            "Function %s failed (attempt %d/%d): %s. Retrying in %.2f seconds",
+                            func.__name__,
+                            attempt + 1,
+                            config.max_retries + 1,
+                            str(e),
+                            delay,
+                        )
+
+                        await asyncio.sleep(delay)
+                    else:
+                        # Not retryable or max retries exceeded
+                        break
+
+            # All retries exhausted
+            error_msg = f"Function {func.__name__} failed after {config.max_retries + 1} attempts"
+            if last_exception:
+                logger.error("%s. Last error: %s", error_msg, str(last_exception))
+                raise RetryError(error_msg, last_exception, config.max_retries + 1)
+            else:
+                # This should never happen, but handle it gracefully
+                logger.error(error_msg)
+                raise RuntimeError(error_msg)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+class RetryManager:
+    """
+    Context manager for manual retry operations.
+    Useful when you need fine-grained control over retry logic.
+    """
+
+    def __init__(self, config: Optional[RetryConfig] = None):
+        self.config = config or RetryConfig()
+        self.attempt = 0
+        self.last_exception: Optional[Exception] = None
+
+    def should_retry(self, exception: Exception) -> bool:
+        """Check if we should retry given an exception"""
+        if self.attempt >= self.config.max_retries:
+            return False
+        return is_retryable(exception, self.config)
+
+    def record_failure(self, exception: Exception):
+        """Record a failure and prepare for potential retry"""
+        self.last_exception = exception
+        self.attempt += 1
+
+    def calculate_delay(self) -> float:
+        """Calculate delay for current attempt"""
+        return calculate_delay(self.attempt - 1, self.config)
+
+    def wait_sync(self):
+        """Wait synchronously for the calculated delay"""
+        if self.last_exception and self.should_retry(self.last_exception):
+            delay = self.calculate_delay()
+            logger.warning(
+                "Retrying after %.2f seconds (attempt %d/%d): %s",
+                delay,
+                self.attempt,
+                self.config.max_retries + 1,
+                str(self.last_exception),
+            )
+            time.sleep(delay)
+
+    async def wait_async(self):
+        """Wait asynchronously for the calculated delay"""
+        if self.last_exception and self.should_retry(self.last_exception):
+            delay = self.calculate_delay()
+            logger.warning(
+                "Retrying after %.2f seconds (attempt %d/%d): %s",
+                delay,
+                self.attempt,
+                self.config.max_retries + 1,
+                str(self.last_exception),
+            )
+            await asyncio.sleep(delay)
+
+    def raise_if_exhausted(self, operation_name: str = "Operation"):
+        """Raise RetryError if all retries are exhausted"""
+        if self.attempt > self.config.max_retries and self.last_exception:
+            error_msg = f"{operation_name} failed after {self.attempt} attempts"
+            logger.error("%s. Last error: %s", error_msg, str(self.last_exception))
+            raise RetryError(error_msg, self.last_exception, self.attempt)
+
+
+# Predefined retry configurations for common scenarios
+class RetryPresets:
+    """Predefined retry configurations for common use cases"""
+
+    @staticmethod
+    def network_operations() -> RetryConfig:
+        """Conservative retry for network operations"""
+        return RetryConfig(max_retries=3, base_delay=1.0, max_delay=30.0, backoff_factor=2.0, jitter=True)
+
+    @staticmethod
+    def api_calls() -> RetryConfig:
+        """Moderate retry for API calls"""
+        return RetryConfig(max_retries=5, base_delay=0.5, max_delay=60.0, backoff_factor=1.5, jitter=True)
+
+    @staticmethod
+    def aggressive() -> RetryConfig:
+        """Aggressive retry for critical operations"""
+        return RetryConfig(max_retries=10, base_delay=0.1, max_delay=120.0, backoff_factor=1.8, jitter=True)
+
+    @staticmethod
+    def rate_limit_heavy() -> RetryConfig:
+        """Retry configuration optimized for rate-limited APIs"""
+        return RetryConfig(
+            max_retries=8,
+            base_delay=2.0,
+            max_delay=300.0,  # 5 minutes max
+            backoff_factor=2.5,
+            jitter=True,
+            retryable_status_codes={429, 500, 502, 503, 504},  # Focus on rate limits and server errors
+        )

{dexscreen-0.0.1.dist-info → dexscreen-0.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dexscreen
-Version: 0.0.1
+Version: 0.0.4
 Summary: Python wrapper for Dexscreener API with stable HTTP support
 Project-URL: Repository, https://github.com/solanab/dexscreen
 Project-URL: Documentation, https://github.com/solanab/dexscreen#readme
@@ -68,8 +68,12 @@ pip install dexscreen
 ```python
 from dexscreen import DexscreenerClient
 
+# Default client with 10-second timeout
 client = DexscreenerClient()
 
+# Custom timeout client
+client = DexscreenerClient(client_kwargs={"timeout": 30})
+
 # Get a specific pair by token address
 pairs = client.get_pairs_by_token_address("solana", "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN")
 if pairs:
@@ -259,6 +263,47 @@ The SDK automatically handles rate limiting:
 - 60 requests/minute for token profile endpoints
 - 300 requests/minute for pair data endpoints
 
+## Timeout Configuration
+
+The SDK provides flexible timeout configuration for different use cases:
+
+### Default Timeout
+```python
+# Default timeout is 10 seconds
+client = DexscreenerClient()
+```
+
+### Custom Timeout
+```python
+# Set custom timeout during initialization
+client = DexscreenerClient(client_kwargs={"timeout": 30})
+
+# Different timeouts for different scenarios
+fast_client = DexscreenerClient(client_kwargs={"timeout": 5})    # Quick responses
+stable_client = DexscreenerClient(client_kwargs={"timeout": 60}) # Stable connections
+```
+
+### Runtime Timeout Updates
+```python
+# Update timeout at runtime
+await client._client_300rpm.update_config({"timeout": 15})
+
+# Multiple config updates including timeout
+await client._client_300rpm.update_config({
+    "timeout": 25,
+    "impersonate": "chrome136"
+})
+```
+
+### Recommended Timeout Values
+
+| Use Case | Timeout (seconds) | Description |
+|----------|------------------|-------------|
+| Quick Trading | 5-10 | Fast response for time-sensitive operations |
+| General Use | 10-15 | Default balanced setting |
+| Stable Monitoring | 20-30 | Reliable for long-running subscriptions |
+| Poor Networks | 30-60 | Handle unstable connections |
+
 ## Browser Impersonation
 
 The SDK uses curl_cffi for browser impersonation to bypass anti-bot protection:
@@ -267,6 +312,12 @@ The SDK uses curl_cffi for browser impersonation to bypass anti-bot protection:
 # Use different browser versions
 client = DexscreenerClient(impersonate="chrome134")
 client = DexscreenerClient(impersonate="safari180")
+
+# Combine browser impersonation with custom timeout
+client = DexscreenerClient(
+    impersonate="chrome136", 
+    client_kwargs={"timeout": 20}
+)
 ```
 
 ## Contributing

dexscreen-0.0.4.dist-info/RECORD

@@ -0,0 +1,22 @@
+dexscreen/__init__.py,sha256=TZfBw2mQ_oy5c7kJ82GP5tu5fSm_vCZJGBOIRULGn6E,2639
+dexscreen/api/__init__.py,sha256=_fFBxC2rrc4nzeRFS_0MQM3cNFrz-ZtvMKrKXX9gtyI,71
+dexscreen/api/client.py,sha256=ic_EcFpnr4VfL3chHIpaovvBhf2qYRlLwTT21ssFkr8,37847
+dexscreen/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dexscreen/core/__init__.py,sha256=_QvgIu4e9RG06TrCTC-BIJMJ5duEFwp1LLTZ7sG4YuM,490
+dexscreen/core/exceptions.py,sha256=IKL-_yWJ3fjmdj09QxOLHTF0zHeinkL0IY7bL51VpmQ,34339
+dexscreen/core/http.py,sha256=T8BFQoQBsiOnVtHb02uZaQ3N8MwqE3C_d-xSVPbHQ34,49096
+dexscreen/core/models.py,sha256=7-EN63yyQK92T1ZRhfHwwXJ8Cg1VbO3CY-wdlpljIu4,2573
+dexscreen/core/validators.py,sha256=BFoey2XangE_i7bxLtuBlRVL-PbUh4ZIrGPq0seRvVI,14536
+dexscreen/stream/__init__.py,sha256=vqoiFQ4LwLjaIEWl7p60StTfG1bSJhyEapjWILVP168,100
+dexscreen/stream/polling.py,sha256=nH12bFvB81HK_efQRcWqXuBlZgKqQCwnLCP5Z1EY7Rk,26462
+dexscreen/utils/__init__.py,sha256=H_70Na9bPmT-5kYgmFbG7_n2MRTJ4PiPIkVyZjhTy7U,1282
+dexscreen/utils/browser_selector.py,sha256=OB14lfSO6zyen3Qga2Cw2Xc9u9_Y5OkEuIdgLeG2_TA,1186
+dexscreen/utils/filters.py,sha256=OnFH_9ZjzkqMZ2804E3V3etSPzTn7FCU5_rJoKOTwC4,14872
+dexscreen/utils/logging_config.py,sha256=M5CJNx8rqZsYTAQF-yT1wVQgj7TvEmR87wJkDCm8_sk,14170
+dexscreen/utils/middleware.py,sha256=7oq628-W9bgoIoAx4W48V-dl3G0WVPThVgwhCCN8q58,12758
+dexscreen/utils/ratelimit.py,sha256=u6VqMVV5mV5XLJpQSPvDFo618Y29rPt76PN0aArnIDo,10203
+dexscreen/utils/retry.py,sha256=-nwhU3GwJULLxCoD4er_wh1EWxh96tf4uDzEdFsrEmQ,12536
+dexscreen-0.0.4.dist-info/METADATA,sha256=uBPvq-c4Mr8IHbkwwUOz51r-lu-198Xt5FHpXWv16eQ,9345
+dexscreen-0.0.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dexscreen-0.0.4.dist-info/licenses/LICENSE,sha256=YLNduNj40Iu4upUYI6XEXrgBlv0hxMNf6uEVAJITYN0,1064
+dexscreen-0.0.4.dist-info/RECORD,,

dexscreen-0.0.1.dist-info/RECORD

@@ -1,17 +0,0 @@
-dexscreen/__init__.py,sha256=W7jJhDNMyzsLsOfQefZJ4pEphfmoIYQbj7rViLplgVg,663
-dexscreen/api/__init__.py,sha256=_fFBxC2rrc4nzeRFS_0MQM3cNFrz-ZtvMKrKXX9gtyI,71
-dexscreen/api/client.py,sha256=_5iQjzx7X4nLhkFimLOPI6dVOcXopgZzya1UNJJns4I,28502
-dexscreen/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-dexscreen/core/__init__.py,sha256=_QvgIu4e9RG06TrCTC-BIJMJ5duEFwp1LLTZ7sG4YuM,490
-dexscreen/core/http.py,sha256=pimTHfsV1v2txnlPk8DIaKesxpZi6cFATm9Z8wlS-No,16327
-dexscreen/core/models.py,sha256=7-EN63yyQK92T1ZRhfHwwXJ8Cg1VbO3CY-wdlpljIu4,2573
-dexscreen/stream/__init__.py,sha256=vqoiFQ4LwLjaIEWl7p60StTfG1bSJhyEapjWILVP168,100
-dexscreen/stream/polling.py,sha256=yltLwKHQJkN2RJAkgJFxzKvRwcv9M3DYHl19D_ZYSog,17517
-dexscreen/utils/__init__.py,sha256=2IXzfN8UFzC4iMX3IoK_9rUY-0CtCCsdaFa66Bdv2zw,180
-dexscreen/utils/browser_selector.py,sha256=OB14lfSO6zyen3Qga2Cw2Xc9u9_Y5OkEuIdgLeG2_TA,1186
-dexscreen/utils/filters.py,sha256=rAgcMOLi3VgTvi4ga6p2dBQ-hWlU3DURpCrabyV-V2g,8145
-dexscreen/utils/ratelimit.py,sha256=NncESbX_8RHPSA9vpxH-vnFwoPwssvooOZthqEQ0-G0,1570
-dexscreen-0.0.1.dist-info/METADATA,sha256=imRHIwcAMcMZG_67e8ccYt0z0ueNPWvLgUpm4gqOyE4,7881
-dexscreen-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dexscreen-0.0.1.dist-info/licenses/LICENSE,sha256=YLNduNj40Iu4upUYI6XEXrgBlv0hxMNf6uEVAJITYN0,1064
-dexscreen-0.0.1.dist-info/RECORD,,