tonutils 2.0.1b2__py3-none-any.whl → 2.0.1b3__py3-none-any.whl

tonutils/exceptions.py

@@ -1,294 +1,202 @@
+import asyncio
 import typing as t
 
-from pytoniq_core import Address
-
 __all__ = [
-    "TonutilsException",
-    "ClientNotConnectedError",
-    "NotRefreshedError",
-    "ContractError",
+    "TonutilsError",
+    "TransportError",
+    "ProviderError",
     "ClientError",
-    "AdnlServerError",
-    "AdnlProviderError",
-    "AdnlProviderConnectError",
-    "AdnlProviderClosedError",
-    "AdnlProviderResponseError",
-    "AdnlProviderMissingBlockError",
-    "AdnlBalancerConnectionError",
-    "RateLimitExceededError",
+    "ContractError",
+    "BalancerError",
+    "NotConnectedError",
+    "ProviderTimeoutError",
+    "ProviderResponseError",
+    "RetryLimitError",
     "RunGetMethodError",
-    "AdnlHandshakeError",
-    "AdnlTransportError",
-    "AdnlTransportStateError",
-    "AdnlTransportCipherError",
-    "AdnlTransportFrameError",
+    "StateNotLoadedError",
+    "CDN_CHALLENGE_MARKERS",
 ]
 
 
-class TonutilsException(Exception):
-    """Base exception for all tonutils-specific errors."""
+class TonutilsError(Exception):
+    """Base exception for tonutils."""
 
-    @classmethod
-    def _obj_name(cls, obj: t.Union[object, type, str]) -> str:
-        """
-        Resolve a human-readable class name from an object or type.
 
-        :param obj: Instance, class or string name
-        :return: Resolved name used in error messages
-        """
-        if isinstance(obj, type):
-            return obj.__name__
-        if isinstance(obj, str):
-            return obj
-        return obj.__class__.__name__
+class TransportError(TonutilsError):
+    """Raise on transport-level failures (I/O, handshake, crypto, socket)."""
 
 
-class ClientNotConnectedError(TonutilsException):
-    """
-    Raised when a client method is called without an active connection.
+class ProviderError(TonutilsError):
+    """Raise on provider-level failures (protocol, parsing, session/state)."""
 
-    This usually indicates that connect() or an async context manager
-    was not used before making network requests.
-    """
 
-    def __init__(self, obj: t.Union[object, type, str]) -> None:
-        name = self._obj_name(obj)
-        super().__init__(
-            f"`{name}` is not connected.\n"
-            f"Use `async with {name}(...) as client:` "
-            f"or call `await {name}(...).connect()` before making requests."
-        )
+class ClientError(TonutilsError):
+    """Raise on client misuse, validation errors, or unsupported operations."""
 
 
-class NotRefreshedError(TonutilsException):
-    """
-    Raised when accessing derived state before an explicit refresh.
-
-    Typical usage is for contract wrappers that require refresh()
-    to be called before accessing state_info or derived properties.
-    """
+class BalancerError(TonutilsError):
+    """Raise on balancer failures (no alive backends, failover exhausted)."""
 
-    def __init__(self, obj: t.Union[object, type, str], attr: str) -> None:
-        name = self._obj_name(obj)
-        super().__init__(
-            f"Access to `{attr}` is not allowed.\n"
-            f"Call `await {name}.refresh()` before accessing `{attr}`."
-        )
 
+class NotConnectedError(TonutilsError, RuntimeError):
+    """Raise when an operation requires an active connection.
 
-class ContractError(TonutilsException):
+    Typically means the underlying client/provider is not connected yet or was closed.
     """
-    Generic error related to smart contract helpers.
 
-    Used for configuration issues, invalid versions and similar
-    contract wrapper problems.
-    """
+    def __init__(self) -> None:
+        super().__init__("not connected. Use `await connect()` or `async with ...`.")
 
-    def __init__(self, obj: t.Union[object, type, str], message: str) -> None:
-        super().__init__(f"{self._obj_name(obj)}: {message}.")
 
+class ProviderTimeoutError(ProviderError, asyncio.TimeoutError):
+    """Raise when a provider operation exceeds its timeout.
 
-class ClientError(TonutilsException):
-    """
-    Base error for client-side failures.
+    Used for both ADNL and HTTP providers.
 
-    Used for issues related to specific client implementations
-    (HTTP, ADNL, balancers, etc.).
+    :param timeout: Timeout in seconds.
+    :param endpoint: Endpoint identifier (URL or host:port).
+    :param operation: Operation label (e.g. "adnl query", "http request").
     """
 
+    timeout: float
+    endpoint: str
+    operation: str
 
-class AdnlServerError(ClientError):
-    """
-    Lite-server reported an internal error while processing a request.
-
-    Wraps lite-server error code and message as returned by ADNL.
-    """
+    def __init__(self, *, timeout: float, endpoint: str, operation: str) -> None:
+        self.timeout = float(timeout)
+        self.endpoint = endpoint
+        self.operation = operation
+        super().__init__(f"{operation} timed out after {timeout}s: {endpoint}")
 
-    def __init__(self, code: int, message: str) -> None:
-        """
-        :param code: Lite-server error code
-        :param message: Lite-server error message
-        """
-        super().__init__(f"Lite-server crashed with `{code}` code. Message: {message}.")
-        self.message = message
-        self.code = code
 
+class ProviderResponseError(ProviderError):
+    """Raise when a backend returns an error response.
 
-class AdnlProviderError(ClientError):
-    """
-    Base error for ADNL provider failures.
+    This is a normalized provider error for:
+    - HTTP status codes (e.g. 429/5xx)
+    - lite-server numeric error codes
 
-    Includes additional context about the lite-server host and port.
+    :param code: Backend code (HTTP status or lite-server code).
+    :param message: Backend error description.
+    :param endpoint: Endpoint identifier (URL or host:port).
     """
 
-    def __init__(self, message: str, host: str, port: int) -> None:
-        """
-        :param message: Error description
-        :param host: Lite-server host
-        :param port: Lite-server port
-        """
-        full_message = f"{message} ({host}:{port})."
-        super().__init__(full_message)
-        self.host = host
-        self.port = port
-
+    code: int
+    message: str
+    endpoint: str
 
-class AdnlProviderConnectError(AdnlProviderError):
-    """
-    Failed to establish an ADNL connection to the lite-server.
-
-    Wraps network or handshake errors that occur during connect().
-    """
+    def __init__(self, *, code: int, message: str, endpoint: str) -> None:
+        self.code = int(code)
+        self.message = message
+        self.endpoint = endpoint
+        super().__init__(f"request failed with code {code} at {endpoint}: {message}")
 
-    def __init__(self, host: str, port: int, message: str) -> None:
-        super().__init__(
-            f"Failed to connect: {message}.",
-            host=host,
-            port=port,
-        )
 
+class RetryLimitError(ProviderError):
+    """Raise when retry policy is exhausted for a matched rule.
 
-class AdnlProviderClosedError(AdnlProviderError):
+    :param attempts: Attempts already performed for the matched rule.
+    :param max_attempts: Maximum attempts allowed by the matched rule.
+    :param last_error: Last provider error that triggered a retry.
     """
-    ADNL provider was closed while waiting for a response.
 
-    Typically raised when transport is torn down during an in-flight
-    request or when the remote peer closes connection unexpectedly.
-    """
+    attempts: int
+    max_attempts: int
+    last_error: ProviderError
 
-    def __init__(self, host: str, port: int) -> None:
+    def __init__(
+        self,
+        *,
+        attempts: int,
+        max_attempts: int,
+        last_error: ProviderError,
+    ) -> None:
+        self.attempts = int(attempts)
+        self.max_attempts = int(max_attempts)
+        self.last_error = last_error
         super().__init__(
-            "Provider closed while waiting response.",
-            host=host,
-            port=port,
+            f"retry exhausted ({self.attempts}/{self.max_attempts}). "
+            f"Last error: {last_error}"
         )
 
 
-class AdnlProviderResponseError(AdnlProviderError):
-    """
-    Received an invalid or malformed response from lite-server.
+class ContractError(ClientError):
+    """Raise when a contract wrapper operation fails.
 
-    Raised when the ADNL response payload does not match the expected
-    structure or type.
+    :param target: Contract instance or contract class related to the failure.
+    :param message: Human-readable error message.
     """
 
-    def __init__(self, host: str, port: int) -> None:
-        super().__init__(
-            "Invalid response from provider.",
-            host=host,
-            port=port,
-        )
+    target: t.Any
+    message: str
 
+    def __init__(self, target: t.Any, message: str) -> None:
+        self.target = target
+        self.message = message
 
-class AdnlProviderMissingBlockError(AdnlProviderError):
-    """
-    Lite-server reported that a requested block is missing.
-
-    Used for specific lite-server error codes that indicate
-    absence of the requested block.
-    """
-
-    def __init__(self, attempts: int, host: str, port: int, message: str) -> None:
-        super().__init__(
-            f"Cannot load block after {attempts} attempts: {message}.",
-            host=host,
-            port=port,
+        name = (
+            target.__name__ if isinstance(target, type) else target.__class__.__name__
         )
-        self.attempts = attempts
+        super().__init__(f"{name}: {message}")
 
 
-class AdnlBalancerConnectionError(ClientError):
-    """
-    All ADNL lite-server providers failed to connect or process a request.
-
-    Raised by AdnlBalancer when no healthy providers remain.
-    """
+class StateNotLoadedError(ContractError):
+    """Raise when a contract wrapper requires state that is not loaded.
 
+    Typical cases:
+    - state_info not fetched
+    - state_data not decoded/available
 
-class RateLimitExceededError(ClientError):
+    :param contract: Contract instance related to the failure.
+    :param missing: Missing field name (e.g. "state_info", "state_data").
     """
-    Request was retried multiple times but rate limits could not be bypassed.
 
-    Raised after exhausting configured retry attempts.
-    """
+    missing: str
 
-    def __init__(self, attempts: int) -> None:
-        """
-        :param attempts: Number of attempts performed before giving up
-        """
-        super().__init__(f"Rate limit exceeded after `{attempts}` attempts.")
-        self.attempts = attempts
+    def __init__(self, contract: t.Any, *, missing: str) -> None:
+        self.missing = missing
+        name = contract.__class__.__name__
+        super().__init__(contract, f"{missing} is not loaded. Call {name}.refresh().")
 
 
 class RunGetMethodError(ClientError):
-    """
-    get-method execution failed with a non-zero exit code.
+    """Raise when a contract get-method returns a non-zero TVM exit code.
 
-    Raised when lite-server returns exit_code != 0 for a runSmcMethod call.
+    :param address: Contract address (string form).
+    :param method_name: Get-method name.
+    :param exit_code: TVM exit code.
     """
 
-    def __init__(self, address: Address, method_name: str, exit_code: int) -> None:
-        """
-        :param address: Contract address on which get-method was executed
-        :param method_name: Name of the get-method
-        :param exit_code: Non-zero TVM exit code returned by the method
-        """
+    address: str
+    method_name: str
+    exit_code: int
+
+    def __init__(self, *, address: str, method_name: str, exit_code: int) -> None:
+        self.address = address
+        self.method_name = method_name
+        self.exit_code = int(exit_code)
         super().__init__(
-            f"Get method `{method_name}` on `{address.to_str()}` "
-            f"failed with `{exit_code}` exit code."
+            f"get-method `{method_name}` failed for {address} (exit code {self.exit_code})."
         )
-        self.method_name = method_name
-        self.exit_code = exit_code
-        self.address = address
-
-
-class AdnlTransportError(TonutilsException):
-    """
-    Base error for raw ADNL transport failures.
-
-    Covers handshake, cipher initialization, framing and state issues.
-    """
-
-
-class AdnlHandshakeError(AdnlTransportError):
-    """
-    ADNL handshake failed during initial connection.
 
-    Raised when the remote side closes the connection or does not
-    respond within the expected timeout.
-    """
-
-
-class AdnlTransportStateError(AdnlTransportError):
-    """
-    Invalid internal state of the ADNL transport.
-
-    Raised when required transport components (reader, writer, cipher, etc.)
-    are not initialized or used incorrectly.
-    """
-
-    def __init__(self, message: str) -> None:
-        super().__init__(f"ADNL transport state error: {message}.")
-
-
-class AdnlTransportCipherError(AdnlTransportError):
-    """
-    ADNL cipher was used before being initialized.
-
-    Raised when trying to encrypt or decrypt frames without
-    a valid session cipher.
-    """
-
-    def __init__(self, direction: str) -> None:
-        super().__init__(f"ADNL {direction} cipher is not initialized.")
-
-
-class AdnlTransportFrameError(AdnlTransportError):
-    """
-    Malformed or invalid ADNL frame was received.
-
-    Raised when frame length, structure or checksum validation fails.
-    """
 
-    def __init__(self, reason: str) -> None:
-        super().__init__(f"Invalid ADNL frame: {reason}.")
+CDN_CHALLENGE_MARKERS: t.Dict[str, str] = {
+    # Cloudflare
+    "cloudflare": "Cloudflare protection triggered or blocked the request.",
+    "cf-ray": "Cloudflare intermediate error (cf-ray header detected).",
+    "just a moment": "Cloudflare browser verification page.",
+    "checking your browser": "Cloudflare browser verification page.",
+    "attention required": "Cloudflare challenge page.",
+    "captcha": "Cloudflare CAPTCHA challenge.",
+    # Other CDNs / proxies
+    "akamai": "Akamai CDN blocked or intercepted the request.",
+    "fastly": "Fastly CDN error response detected.",
+    "varnish": "Varnish cache/CDN interference.",
+    "nginx": "Reverse proxy (nginx) error response.",
+    # Upstream failures
+    "502 bad gateway": "Bad gateway from upstream or proxy.",
+    "503 service unavailable": "Service temporarily unavailable (proxy or CDN).",
+    "ddos": "Possible DDoS protection or mitigation page.",
+}
+"""Markers for detecting CDN / proxy challenge and anti-DDoS responses, 
+used for error normalization and default retry policies."""

tonutils/types.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import base64
 import typing as t
+from dataclasses import dataclass
 from enum import Enum
 
 from nacl.signing import SigningKey
@@ -16,6 +17,8 @@ __all__ = [
     "ClientType",
     "ContractState",
     "ContractStateInfo",
+    "DEFAULT_ADNL_RETRY_POLICY",
+    "DEFAULT_HTTP_RETRY_POLICY",
     "DEFAULT_SENDMODE",
     "DEFAULT_SUBWALLET_ID",
     "DNSCategory",
@@ -24,6 +27,8 @@ __all__ = [
     "NetworkGlobalID",
     "PrivateKey",
     "PublicKey",
+    "RetryPolicy",
+    "RetryRule",
     "SendMode",
     "StackItem",
     "StackItems",
@@ -31,6 +36,8 @@ __all__ = [
     "WorkchainID",
 ]
 
+from tonutils.exceptions import CDN_CHALLENGE_MARKERS
+
 AddressLike = t.Union[Address, str]
 """Type alias for TON address inputs. Accepts either an Address object or string representation."""
 
@@ -375,6 +382,114 @@ class BagID(ADNL):
     """TON Storage bag identifier (32 bytes)."""
 
 
+@dataclass(slots=True, frozen=True)
+class RetryRule:
+    """
+    Retry rule matched by numeric code and/or message substrings.
+
+    Matching:
+    - if codes is set: code must be in codes
+    - if markers is set: any marker must be present in message (case-insensitive)
+    - if both are set: both conditions must match
+
+    Attributes:
+        attempts: Maximum number of retry attempts
+        base_delay: Initial delay before first retry (seconds)
+        cap_delay: Maximum delay between retries (seconds)
+        codes: Error or status codes this rule applies to
+        markers: Case-insensitive substrings matched against error message
+    """
+
+    attempts: int = 3
+    base_delay: float = 0.3
+    cap_delay: float = 3.0
+
+    codes: t.Optional[t.Tuple[int, ...]] = None
+    markers: t.Optional[t.Tuple[str, ...]] = None
+
+    def __post_init__(self) -> None:
+        if self.attempts < 1:
+            raise ValueError("attempts must be >= 1")
+        if self.base_delay < 0:
+            raise ValueError("base_delay must be >= 0")
+        if self.cap_delay < 0:
+            raise ValueError("cap_delay must be >= 0")
+        if self.cap_delay < self.base_delay:
+            raise ValueError("cap_delay must be >= base_delay")
+        if self.markers:
+            norm = tuple(m.strip().lower() for m in self.markers if m and m.strip())
+            object.__setattr__(self, "markers", norm or None)
+
+    def matches(self, code: int, message: t.Any) -> bool:
+        if self.codes is not None and code not in self.codes:
+            return False
+
+        if self.markers:
+            msg = str(message or "").lower()
+            if not any(m in msg for m in self.markers):
+                return False
+
+        return True
+
+    def delay(self, attempt_index: int) -> float:
+        if attempt_index < 0:
+            raise ValueError("attempt_index must be >= 0")
+        d = self.base_delay * (2**attempt_index)
+        return d if d < self.cap_delay else self.cap_delay
+
+
+@dataclass(slots=True, frozen=True)
+class RetryPolicy:
+    """Ordered collection of retry rules (first match wins)."""
+
+    rules: t.Tuple[RetryRule, ...]
+
+    def rule_for(self, code: int, message: t.Any) -> t.Optional[RetryRule]:
+        for r in self.rules:
+            if r.matches(code, message):
+                return r
+        return None
+
+
+DEFAULT_HTTP_RETRY_POLICY = RetryPolicy(
+    rules=(
+        # rate limit exceed
+        RetryRule(
+            codes=(429,),
+            attempts=3,
+            base_delay=0.3,
+            cap_delay=3.0,
+        ),
+        # transient gateway/service failures
+        RetryRule(
+            codes=(502, 503, 504),
+            attempts=3,
+            base_delay=0.5,
+            cap_delay=5.0,
+        ),
+        # CDN/protection/challenge pages (сloudflare, etc.)
+        RetryRule(
+            attempts=3,
+            base_delay=1.0,
+            cap_delay=8.0,
+            markers=tuple(CDN_CHALLENGE_MARKERS.keys()),
+        ),
+    )
+)
+"""Default retry policy for HTTP queries."""
+
+DEFAULT_ADNL_RETRY_POLICY = RetryPolicy(
+    rules=(
+        # rate limit exceed
+        RetryRule(codes=(228, 5556), attempts=3),
+        # block (...) is not in db
+        RetryRule(codes=(651,), attempts=4),
+        # backend node timeout
+        RetryRule(codes=(502,), attempts=5),
+    )
+)
+"""Default retry policy for ADNL queries."""
+
 DEFAULT_SUBWALLET_ID = 698983191
 """Default subwallet ID for wallet contracts."""
 

tonutils/utils.py

@@ -34,7 +34,7 @@ from tonutils.types import (
 )
 
 if t.TYPE_CHECKING:
-    from tonutils.protocols import ClientProtocol
+    from tonutils.clients.protocol import ClientProtocol
 
 
 __all__ = [
@@ -229,7 +229,7 @@ def norm_stack_cell(
     return maybe_stack_addr(cell)
 
 
-def parse_stack_config(config_slice: Slice) -> dict[int, t.Any]:
+def parse_stack_config(config_slice: Slice) -> t.Dict[int, t.Any]:
     """
     Parse blockchain configuration parameters from a config cell.
 
@@ -514,7 +514,7 @@ class TextCipher:
         """
         Decrypt an encrypted text message.
 
-        Decrypts a message that was encrypted with the encrypt() method.
+        Decrypts a message that was encrypted with the encrypt() method
         Verifies message integrity using HMAC authentication.
 
         :param payload: Encrypted message as Cell, hex string, base64 string, or bytes

{tonutils-2.0.1b2.dist-info → tonutils-2.0.1b3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tonutils
-Version: 2.0.1b2
+Version: 2.0.1b3
 Summary: Tonutils is a high-level, object-oriented Python library designed to facilitate seamless interactions with the TON blockchain.
 Author: nessshon
 Maintainer: nessshon
@@ -26,11 +26,11 @@ Requires-Python: <3.15,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp>=3.7.0
-Requires-Dist: pyapiq>=0.2.1
 Requires-Dist: pycryptodomex~=3.23.0
 Requires-Dist: pydantic<3.0,>=2.0
 Requires-Dist: pynacl~=1.6.0
 Requires-Dist: pytoniq-core~=0.1.45
+Requires-Dist: requests>=2.31.0
 Dynamic: license-file
 
 # 📦 Tonutils 2.0 [BETA]