dexscreen 0.0.2__py3-none-any.whl → 0.0.5__py3-none-any.whl

dexscreen/__init__.py

@@ -5,6 +5,50 @@ A modern, stable, and reliable Python SDK for DexScreener API with HTTP support.
 """
 
 from .api.client import DexscreenerClient
+from .core.exceptions import (
+    # API errors
+    APIError,
+    APILimitError,
+    AuthenticationError,
+    # Configuration errors
+    ConfigurationError,
+    ConnectionError,
+    DataFormatError,
+    # Base exceptions
+    DexscreenError,
+    FilterConfigError,
+    HttpConnectionError,
+    # HTTP errors
+    HttpError,
+    HttpRequestError,
+    HttpResponseParsingError,
+    HttpSessionError,
+    HttpTimeoutError,
+    InvalidAddressError,
+    InvalidChainError,
+    InvalidConfigError,
+    InvalidResponseError,
+    MissingConfigError,
+    MissingDataError,
+    # Network errors
+    NetworkError,
+    ProxyError,
+    RateLimitError,
+    ServerError,
+    StreamConnectionError,
+    StreamDataError,
+    # Streaming errors
+    StreamError,
+    StreamTimeoutError,
+    SubscriptionError,
+    TimeoutError,
+    # Validation errors
+    ValidationError,
+    # Utility functions
+    get_error_category,
+    is_retryable_error,
+    should_wait_before_retry,
+)
 from .core.models import (
     BaseToken,
     Liquidity,
@@ -18,14 +62,57 @@ from .utils.filters import FilterConfig, FilterPresets
 
 __version__ = "1.0.0"
 __all__ = [
+    # API errors
+    "APIError",
+    "APILimitError",
+    "AuthenticationError",
+    # Core models and client
     "BaseToken",
+    # Configuration errors
+    "ConfigurationError",
+    "ConnectionError",
+    "DataFormatError",
+    # Base exceptions
+    "DexscreenError",
     "DexscreenerClient",
     "FilterConfig",
+    "FilterConfigError",
     "FilterPresets",
+    "HttpConnectionError",
+    # HTTP errors
+    "HttpError",
+    "HttpRequestError",
+    "HttpResponseParsingError",
+    "HttpSessionError",
+    "HttpTimeoutError",
+    "InvalidAddressError",
+    "InvalidChainError",
+    "InvalidConfigError",
+    "InvalidResponseError",
     "Liquidity",
+    "MissingConfigError",
+    "MissingDataError",
+    # Network errors
+    "NetworkError",
     "PairTransactionCounts",
     "PriceChangePeriods",
+    "ProxyError",
+    "RateLimitError",
+    "ServerError",
+    "StreamConnectionError",
+    "StreamDataError",
+    # Streaming errors
+    "StreamError",
+    "StreamTimeoutError",
+    "SubscriptionError",
+    "TimeoutError",
     "TokenPair",
     "TransactionCount",
+    # Validation errors
+    "ValidationError",
     "VolumeChangePeriods",
+    # Utility functions
+    "get_error_category",
+    "is_retryable_error",
+    "should_wait_before_retry",
 ]

dexscreen/api/client.py

@@ -3,12 +3,26 @@ Simplified Dexscreener client with clean API
 """
 
 import asyncio
+import logging
 from typing import Any, Callable, Optional, Union
 
+from ..core.exceptions import (
+    HttpError,
+)
 from ..core.http import HttpClientCffi
 from ..core.models import OrderInfo, TokenInfo, TokenPair
+from ..core.validators import (
+    validate_address,
+    validate_addresses_list,
+    validate_chain_id,
+    validate_dict_config,
+    validate_string,
+)
 from ..stream.polling import PollingStream
 from ..utils.filters import FilterConfig, TokenPairFilter
+from ..utils.logging_config import get_contextual_logger, log_function_call, with_correlation_id
+
+logger = logging.getLogger(__name__)
 
 
 class DexscreenerClient:
@@ -27,7 +41,17 @@ class DexscreenerClient:
         Args:
             impersonate: Browser to impersonate (default: None, uses random market-share based selection)
             client_kwargs: Optional kwargs to pass to curl_cffi clients.
+
+        Raises:
+            InvalidTypeError: If parameters have invalid types
+            InvalidParameterError: If impersonate value is invalid
         """
+        # Validate inputs
+        if impersonate is not None:
+            impersonate = validate_string(impersonate, "impersonate", 1, 50)
+
+        client_kwargs = validate_dict_config(client_kwargs, "client_kwargs", allow_none=True)
+
         # Setup client kwargs
         self.client_kwargs = client_kwargs or {}
         # Use provided impersonate or our custom realworld browser selection
@@ -54,33 +78,144 @@ class DexscreenerClient:
         # Filters for each subscription
         self._filters: dict[str, TokenPairFilter] = {}
 
+        # Enhanced logging
+        self.contextual_logger = get_contextual_logger(__name__)
+
+        init_context = {
+            "impersonate": impersonate,
+            "has_client_kwargs": bool(client_kwargs),
+            "client_kwargs_keys": list(client_kwargs.keys()) if client_kwargs else [],
+        }
+
+        self.contextual_logger.debug("DexscreenerClient initialized", context=init_context)
+
     # ========== Single Query Methods ==========
 
+    @with_correlation_id()
+    @log_function_call(log_args=True, log_result=False)
     def get_pair(self, address: str) -> Optional[TokenPair]:
-        """Get a single token pair by address using search"""
-        # Since the API requires chain ID, we use search as a workaround
-        resp = self._client_300rpm.request("GET", f"latest/dex/search?q={address}")
-        if resp is not None and isinstance(resp, dict) and "pairs" in resp and len(resp["pairs"]) > 0:
-            # Return the first matching pair
-            for pair in resp["pairs"]:
-                if pair.get("pairAddress", "").lower() == address.lower():
-                    return TokenPair(**pair)
-            # If no exact match, return the first result
-            return TokenPair(**resp["pairs"][0])
-        return None
+        """
+        Get a single token pair by address using search.
+
+        Args:
+            address: Token pair address to search for
+
+        Returns:
+            TokenPair object if found, None otherwise
+
+        Raises:
+            InvalidAddressError: If address format is invalid
+            HttpError: If HTTP request fails (connection, timeout, etc.)
+        """
+        # Validate input
+        address = validate_address(address)
+
+        search_context: dict[str, Any] = {
+            "operation": "get_pair",
+            "address": address[:10] + "..." if len(address) > 10 else address,
+            "method": "search_workaround",
+        }
+
+        self.contextual_logger.debug("Getting pair by address", context=search_context)
+
+        try:
+            # Since the API requires chain ID, we use search as a workaround
+            resp = self._client_300rpm.request("GET", f"latest/dex/search?q={address}")
+            if resp is not None and isinstance(resp, dict) and "pairs" in resp and len(resp["pairs"]) > 0:
+                pairs_found = len(resp["pairs"])
+                search_context["pairs_found"] = pairs_found
+
+                # Return the first matching pair
+                for pair in resp["pairs"]:
+                    if pair.get("pairAddress", "").lower() == address.lower():
+                        search_context["exact_match"] = True
+                        self.contextual_logger.debug("Found exact pair match", context=search_context)
+                        return TokenPair(**pair)
+
+                # If no exact match, return the first result
+                search_context["exact_match"] = False
+                search_context["using_first_result"] = True
+                self.contextual_logger.debug("No exact match, using first result", context=search_context)
+                return TokenPair(**resp["pairs"][0])
+            else:
+                search_context["pairs_found"] = 0
+                search_context["response_valid"] = resp is not None
+                self.contextual_logger.warning("No pairs found for address", context=search_context)
+                return None
+        except HttpError as e:
+            error_context = search_context.copy()
+            error_context["error_type"] = type(e).__name__
+            error_context["error_message"] = str(e)
+
+            self.contextual_logger.error(
+                "Failed to get pair for address: %s", str(e), context=error_context, exc_info=True
+            )
 
+            logger.error("Failed to get pair for address %s: %s", address, e)  # Keep original logging
+            raise  # Re-raise the HTTP error for caller to handle
+
+    @with_correlation_id()
+    @log_function_call(log_args=True, log_result=False)
     async def get_pair_async(self, address: str) -> Optional[TokenPair]:
-        """Async version of get_pair"""
-        # Since the API requires chain ID, we use search as a workaround
-        resp = await self._client_300rpm.request_async("GET", f"latest/dex/search?q={address}")
-        if resp is not None and isinstance(resp, dict) and "pairs" in resp and len(resp["pairs"]) > 0:
-            # Return the first matching pair
-            for pair in resp["pairs"]:
-                if pair.get("pairAddress", "").lower() == address.lower():
-                    return TokenPair(**pair)
-            # If no exact match, return the first result
-            return TokenPair(**resp["pairs"][0])
-        return None
+        """
+        Async version of get_pair.
+
+        Args:
+            address: Token pair address to search for
+
+        Returns:
+            TokenPair object if found, None otherwise
+
+        Raises:
+            InvalidAddressError: If address format is invalid
+            HttpError: If HTTP request fails (connection, timeout, etc.)
+        """
+        # Validate input
+        address = validate_address(address)
+
+        search_context: dict[str, Any] = {
+            "operation": "get_pair_async",
+            "address": address[:10] + "..." if len(address) > 10 else address,
+            "method": "search_workaround",
+        }
+
+        self.contextual_logger.debug("Getting pair by address (async)", context=search_context)
+
+        try:
+            # Since the API requires chain ID, we use search as a workaround
+            resp = await self._client_300rpm.request_async("GET", f"latest/dex/search?q={address}")
+            if resp is not None and isinstance(resp, dict) and "pairs" in resp and len(resp["pairs"]) > 0:
+                pairs_found = len(resp["pairs"])
+                search_context["pairs_found"] = pairs_found
+
+                # Return the first matching pair
+                for pair in resp["pairs"]:
+                    if pair.get("pairAddress", "").lower() == address.lower():
+                        search_context["exact_match"] = True
+                        self.contextual_logger.debug("Found exact pair match (async)", context=search_context)
+                        return TokenPair(**pair)
+
+                # If no exact match, return the first result
+                search_context["exact_match"] = False
+                search_context["using_first_result"] = True
+                self.contextual_logger.debug("No exact match, using first result (async)", context=search_context)
+                return TokenPair(**resp["pairs"][0])
+            else:
+                search_context["pairs_found"] = 0
+                search_context["response_valid"] = resp is not None
+                self.contextual_logger.warning("No pairs found for address (async)", context=search_context)
+                return None
+        except HttpError as e:
+            error_context = search_context.copy()
+            error_context["error_type"] = type(e).__name__
+            error_context["error_message"] = str(e)
+
+            self.contextual_logger.error(
+                "Failed to get pair for address (async): %s", str(e), context=error_context, exc_info=True
+            )
+
+            logger.error("Failed to get pair for address %s: %s", address, e)  # Keep original logging
+            raise  # Re-raise the HTTP error for caller to handle
 
     def get_pairs_by_pairs_addresses(self, chain_id: str, pair_addresses: list[str]) -> list[TokenPair]:
         """
@@ -96,14 +231,19 @@ class DexscreenerClient:
             List of TokenPair objects
 
         Raises:
-            ValueError: If more than 30 pair addresses are provided
+            InvalidChainIdError: If chain ID is invalid
+            InvalidAddressError: If any address format is invalid
+            TooManyItemsError: If more than 30 pair addresses are provided
         """
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        pair_addresses = validate_addresses_list(
+            pair_addresses, "pair_addresses", min_count=0, max_count=self.MAX_PAIRS_PER_REQUEST, chain_id=chain_id
+        )
+
         if not pair_addresses:
             return []
 
-        if len(pair_addresses) > self.MAX_PAIRS_PER_REQUEST:
-            raise ValueError(f"Maximum {self.MAX_PAIRS_PER_REQUEST} pair addresses allowed, got {len(pair_addresses)}")
-
         addresses_str = ",".join(pair_addresses)
         resp = self._client_300rpm.request("GET", f"latest/dex/pairs/{chain_id}/{addresses_str}")
         if resp is None:
@@ -126,14 +266,19 @@ class DexscreenerClient:
             List of TokenPair objects
 
         Raises:
-            ValueError: If more than 30 pair addresses are provided
+            InvalidChainIdError: If chain ID is invalid
+            InvalidAddressError: If any address format is invalid
+            TooManyItemsError: If more than 30 pair addresses are provided
         """
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        pair_addresses = validate_addresses_list(
+            pair_addresses, "pair_addresses", min_count=0, max_count=self.MAX_PAIRS_PER_REQUEST, chain_id=chain_id
+        )
+
         if not pair_addresses:
             return []
 
-        if len(pair_addresses) > self.MAX_PAIRS_PER_REQUEST:
-            raise ValueError(f"Maximum {self.MAX_PAIRS_PER_REQUEST} pair addresses allowed, got {len(pair_addresses)}")
-
         addresses_str = ",".join(pair_addresses)
         resp = await self._client_300rpm.request_async("GET", f"latest/dex/pairs/{chain_id}/{addresses_str}")
         if resp is None:
@@ -154,6 +299,11 @@ class DexscreenerClient:
 
     def search_pairs(self, query: str) -> list[TokenPair]:
         """Search for pairs by query"""
+        from ..core.validators import validate_query_string
+
+        # Validate query string
+        query = validate_query_string(query, max_length=100)
+
         resp = self._client_300rpm.request("GET", f"latest/dex/search?q={query}")
         if resp is not None and isinstance(resp, dict):
             return [TokenPair(**pair) for pair in resp.get("pairs", [])]
@@ -161,6 +311,11 @@ class DexscreenerClient:
 
     async def search_pairs_async(self, query: str) -> list[TokenPair]:
         """Async version of search_pairs"""
+        from ..core.validators import validate_query_string
+
+        # Validate query string
+        query = validate_query_string(query, max_length=100)
+
         resp = await self._client_300rpm.request_async("GET", f"latest/dex/search?q={query}")
         if resp is not None and isinstance(resp, dict):
             return [TokenPair(**pair) for pair in resp.get("pairs", [])]
@@ -210,6 +365,10 @@ class DexscreenerClient:
 
     def get_orders_paid_of_token(self, chain_id: str, token_address: str) -> list[OrderInfo]:
         """Get orders for a token"""
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        token_address = validate_address(token_address, chain_id)
+
         resp = self._client_60rpm.request("GET", f"orders/v1/{chain_id}/{token_address}")
         if resp is not None:
             return [OrderInfo(**order) for order in resp]
@@ -217,6 +376,10 @@ class DexscreenerClient:
 
     async def get_orders_paid_of_token_async(self, chain_id: str, token_address: str) -> list[OrderInfo]:
         """Async version of get_orders_paid_of_token"""
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        token_address = validate_address(token_address, chain_id)
+
         resp = await self._client_60rpm.request_async("GET", f"orders/v1/{chain_id}/{token_address}")
         if resp is not None:
             return [OrderInfo(**order) for order in resp]
@@ -224,6 +387,10 @@ class DexscreenerClient:
 
     def get_pairs_by_token_address(self, chain_id: str, token_address: str) -> list[TokenPair]:
         """Get all pairs for a single token address on a specific chain"""
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        token_address = validate_address(token_address, chain_id)
+
         # Use the correct endpoint format: /tokens/v1/{chain}/{address}
         resp = self._client_300rpm.request("GET", f"tokens/v1/{chain_id}/{token_address}")
         if resp is None:
@@ -236,6 +403,10 @@ class DexscreenerClient:
 
     async def get_pairs_by_token_address_async(self, chain_id: str, token_address: str) -> list[TokenPair]:
         """Async version of get_pairs_by_token_address"""
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        token_address = validate_address(token_address, chain_id)
+
         # Use the correct endpoint format: /tokens/v1/{chain}/{address}
         resp = await self._client_300rpm.request_async("GET", f"tokens/v1/{chain_id}/{token_address}")
         if resp is None:
@@ -261,16 +432,19 @@ class DexscreenerClient:
             List of TokenPair objects (maximum 30 pairs)
 
         Raises:
-            ValueError: If more than 30 token addresses are provided
+            InvalidChainIdError: If chain ID is invalid
+            InvalidAddressError: If any address format is invalid
+            TooManyItemsError: If more than 30 token addresses are provided
         """
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        token_addresses = validate_addresses_list(
+            token_addresses, "token_addresses", min_count=0, max_count=self.MAX_TOKENS_PER_REQUEST, chain_id=chain_id
+        )
+
         if not token_addresses:
             return []
 
-        if len(token_addresses) > self.MAX_TOKENS_PER_REQUEST:
-            raise ValueError(
-                f"Maximum {self.MAX_TOKENS_PER_REQUEST} token addresses allowed, got {len(token_addresses)}"
-            )
-
         if len(token_addresses) == 1:
             # For single token, use the single token method
             return self.get_pairs_by_token_address(chain_id, token_addresses[0])
@@ -297,6 +471,10 @@ class DexscreenerClient:
 
     def get_pools_by_token_address(self, chain_id: str, token_address: str) -> list[TokenPair]:
         """Get pools info using token-pairs/v1 endpoint (Pool endpoint)"""
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        token_address = validate_address(token_address, chain_id)
+
         # Use the token-pairs/v1 endpoint
         resp = self._client_300rpm.request("GET", f"token-pairs/v1/{chain_id}/{token_address}")
         if resp is None:
@@ -309,6 +487,10 @@ class DexscreenerClient:
 
     async def get_pools_by_token_address_async(self, chain_id: str, token_address: str) -> list[TokenPair]:
         """Async version of get_pools_by_token_address"""
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        token_address = validate_address(token_address, chain_id)
+
         # Use the token-pairs/v1 endpoint
         resp = await self._client_300rpm.request_async("GET", f"token-pairs/v1/{chain_id}/{token_address}")
         if resp is None:
@@ -334,16 +516,19 @@ class DexscreenerClient:
             List of TokenPair objects (maximum 30 pairs)
 
         Raises:
-            ValueError: If more than 30 token addresses are provided
+            InvalidChainIdError: If chain ID is invalid
+            InvalidAddressError: If any address format is invalid
+            TooManyItemsError: If more than 30 token addresses are provided
         """
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        token_addresses = validate_addresses_list(
+            token_addresses, "token_addresses", min_count=0, max_count=self.MAX_TOKENS_PER_REQUEST, chain_id=chain_id
+        )
+
         if not token_addresses:
             return []
 
-        if len(token_addresses) > self.MAX_TOKENS_PER_REQUEST:
-            raise ValueError(
-                f"Maximum {self.MAX_TOKENS_PER_REQUEST} token addresses allowed, got {len(token_addresses)}"
-            )
-
         if len(token_addresses) == 1:
             # For single token, use the single token method
             return await self.get_pairs_by_token_address_async(chain_id, token_addresses[0])
@@ -411,6 +596,22 @@ class DexscreenerClient:
             config = FilterConfig(price_change_threshold=0.02)
             await client.subscribe_pairs("ethereum", ["0x..."], callback, filter=config)
         """
+        # Import validators at the top of the method to avoid circular imports
+        from ..core.validators import (
+            validate_addresses_list,
+            validate_callback,
+            validate_chain_id,
+            validate_filter_config,
+            validate_interval,
+        )
+
+        # Validate inputs before any async operations
+        chain_id = validate_chain_id(chain_id)
+        pair_addresses = validate_addresses_list(pair_addresses, "pair_addresses", chain_id=chain_id)
+        callback = validate_callback(callback)
+        filter = validate_filter_config(filter)
+        interval = validate_interval(interval)
+
         # Handle single pair address for backward compatibility
         for pair_address in pair_addresses:
             subscription_key = f"{chain_id}:{pair_address}"
@@ -455,6 +656,7 @@ class DexscreenerClient:
 
                 actual_callback = filtered_callback
             else:
+                # This should not happen as validate_filter_config already checks this
                 raise ValueError(f"Invalid filter type: {type(filter)}. Must be bool or FilterConfig")
 
             # Store subscription info
@@ -498,6 +700,22 @@ class DexscreenerClient:
                 callback=handle_usdc_pairs
             )
         """
+        # Import validators at the top of the method to avoid circular imports
+        from ..core.validators import (
+            validate_addresses_list,
+            validate_callback,
+            validate_chain_id,
+            validate_filter_config,
+            validate_interval,
+        )
+
+        # Validate inputs before any async operations
+        chain_id = validate_chain_id(chain_id)
+        token_addresses = validate_addresses_list(token_addresses, "token_addresses", chain_id=chain_id)
+        callback = validate_callback(callback)
+        filter = validate_filter_config(filter)
+        interval = validate_interval(interval)
+
         # Handle multiple token addresses
         for token_address in token_addresses:
             subscription_key = f"token:{chain_id}:{token_address}"
@@ -550,6 +768,7 @@ class DexscreenerClient:
 
                 actual_callback = filtered_callback
             else:
+                # This should not happen as validate_filter_config already checks this
                 raise ValueError(f"Invalid filter type: {type(filter)}. Must be bool or FilterConfig")
 
             # Store subscription info
@@ -598,6 +817,13 @@ class DexscreenerClient:
 
     async def unsubscribe_pairs(self, chain_id: str, pair_addresses: list[str]) -> None:
         """Unsubscribe from pair updates"""
+        # Import validators at the top of the method to avoid circular imports
+        from ..core.validators import validate_addresses_list, validate_chain_id
+
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        pair_addresses = validate_addresses_list(pair_addresses, "pair_addresses", chain_id=chain_id)
+
         for pair_address in pair_addresses:
             subscription_key = f"{chain_id}:{pair_address}"
 
@@ -616,6 +842,13 @@ class DexscreenerClient:
 
     async def unsubscribe_tokens(self, chain_id: str, token_addresses: list[str]) -> None:
         """Unsubscribe from token pair updates"""
+        # Import validators at the top of the method to avoid circular imports
+        from ..core.validators import validate_addresses_list, validate_chain_id
+
+        # Validate inputs
+        chain_id = validate_chain_id(chain_id)
+        token_addresses = validate_addresses_list(token_addresses, "token_addresses", chain_id=chain_id)
+
         for token_address in token_addresses:
             subscription_key = f"token:{chain_id}:{token_address}"