tonutils 2.0.1b6__py3-none-any.whl → 2.0.1b8__py3-none-any.whl

tonutils/clients/http/balancer.py

@@ -19,8 +19,9 @@ from tonutils.exceptions import (
     ProviderResponseError,
     RunGetMethodError,
     ProviderTimeoutError,
+    NotConnectedError,
 )
-from tonutils.types import ClientType, ContractStateInfo, NetworkGlobalID
+from tonutils.types import ClientType, ContractInfo, NetworkGlobalID
 
 _T = t.TypeVar("_T")
 
@@ -73,14 +74,14 @@ class HttpBalancer(BaseClient):
 
         :param network: Target TON network (mainnet or testnet)
         :param clients: List of HTTP BaseClient instances to balance between
-        :param request_timeout: Maximum total time in seconds for a balancer operation,
+        :param request_timeout: Maximum total time in seconds for a balancer method,
             including all failover attempts across providers
         """
         self.network = network
 
         self._clients: t.List[BaseClient] = []
         self._states: t.List[HttpClientState] = []
-        self.__init_clients(clients)
+        self._init_clients(clients)
 
         self._rr = cycle(self._clients)
 
@@ -89,31 +90,14 @@ class HttpBalancer(BaseClient):
 
         self._request_timeout = request_timeout
 
-    def __init_clients(
-        self,
-        clients: t.List[BaseClient],
-    ) -> None:
-        """Validate and register input HTTP clients."""
-        for client in clients:
-            if client.TYPE != ClientType.HTTP:
-                raise ClientError(
-                    "HttpBalancer can work only with HTTP clients, "
-                    f"got {client.__class__.__name__}."
-                )
-
-            if (
-                isinstance(client, QuicknodeClient)
-                and self.network == NetworkGlobalID.TESTNET
-            ):
-                raise ClientError(
-                    "QuickNode HTTP client does not support testnet network."
-                )
-
-            client.network = self.network
-            state = HttpClientState(client=client)
+    @property
+    def connected(self) -> bool:
+        """
+        Check whether at least one underlying client is connected.
 
-            self._clients.append(client)
-            self._states.append(state)
+        :return: True if any client is connected, otherwise False
+        """
+        return any(c.connected for c in self._clients)
 
     @property
     def provider(self) -> t.Any:
@@ -125,14 +109,17 @@ class HttpBalancer(BaseClient):
         c = self._pick_client()
         return c.provider
 
-    @property
-    def is_connected(self) -> bool:
-        """
-        Check whether at least one underlying client is connected.
+    async def connect(self) -> None:
+        await asyncio.gather(
+            *(state.client.connect() for state in self._states),
+            return_exceptions=True,
+        )
 
-        :return: True if any client is connected, otherwise False
-        """
-        return any(c.is_connected for c in self._clients)
+    async def close(self) -> None:
+        await asyncio.gather(
+            *(state.client.close() for state in self._states),
+            return_exceptions=True,
+        )
 
     @property
     def clients(self) -> t.Tuple[BaseClient, ...]:
@@ -154,7 +141,8 @@ class HttpBalancer(BaseClient):
         return tuple(
             state.client
             for state in self._states
-            if state.retry_after is None or state.retry_after <= now
+            if state.client.connected
+            and (state.retry_after is None or state.retry_after <= now)
         )
 
     @property
@@ -171,24 +159,31 @@ class HttpBalancer(BaseClient):
             if state.retry_after is not None and state.retry_after > now
         )
 
-    async def __aenter__(self) -> HttpBalancer:
-        """
-        Enter async context manager and connect all underlying clients.
-
-        :return: Self instance with initialized connections
-        """
-        await self.connect()
-        return self
-
-    async def __aexit__(
+    def _init_clients(
         self,
-        exc_type: t.Optional[t.Type[BaseException]],
-        exc_value: t.Optional[BaseException],
-        traceback: t.Optional[t.Any],
+        clients: t.List[BaseClient],
     ) -> None:
-        """Exit async context manager and close all underlying clients."""
-        with suppress(asyncio.CancelledError):
-            await self.close()
+        """Validate and register input HTTP clients."""
+        for client in clients:
+            if client.TYPE != ClientType.HTTP:
+                raise ClientError(
+                    "HttpBalancer can work only with HTTP clients, "
+                    f"got {client.__class__.__name__}."
+                )
+
+            if (
+                isinstance(client, QuicknodeClient)
+                and self.network == NetworkGlobalID.TESTNET
+            ):
+                raise ClientError(
+                    "QuickNode HTTP client does not support testnet network."
+                )
+
+            client.network = self.network
+            state = HttpClientState(client=client)
+
+            self._clients.append(client)
+            self._states.append(state)
 
     def _pick_client(self) -> BaseClient:
         """
@@ -201,8 +196,10 @@ class HttpBalancer(BaseClient):
 
         :return: Selected BaseClient instance
         """
-        alive = list(self.alive_clients)
+        if not self.connected:
+            raise NotConnectedError(component=self.__class__.__name__)
 
+        alive = list(self.alive_clients)
         height_candidates: t.List[
             t.Tuple[
                 float,
@@ -223,7 +220,9 @@ class HttpBalancer(BaseClient):
             height_candidates.append((wait, state.error_count, state))
 
         if not height_candidates:
-            raise BalancerError("no available HTTP clients")
+            raise BalancerError(
+                "http balancer has no available clients (all in cooldown or not connected)"
+            )
 
         height_candidates.sort(key=lambda x: (x[0], x[1]))
         best_wait, best_err, _ = height_candidates[0]
@@ -286,75 +285,89 @@ class HttpBalancer(BaseClient):
     async def _with_failover(
         self,
         func: t.Callable[[BaseClient], t.Awaitable[_T]],
+        method: str,
     ) -> _T:
         """
-        Execute a client operation with automatic failover.
+        Execute a client method with automatic failover.
 
         Iterates through available clients until one succeeds
         or all clients fail.
 
-        :param func: Callable performing an operation using a client
+        :param func: Callable performing an method using a client
         :return: Result of the successful invocation
         """
 
         async def _run() -> _T:
+            if not self.connected:
+                raise NotConnectedError(
+                    component=self.__class__.__name__,
+                    operation=method,
+                )
+
             last_exc: t.Optional[BaseException] = None
+            attempts = 0
 
             for _ in range(len(self._clients)):
                 if not self.alive_clients:
                     break
 
                 client = self._pick_client()
+                attempts += 1
 
                 try:
                     result = await func(client)
-
                 except RunGetMethodError:
                     raise
                 except ProviderResponseError as e:
-                    is_rate_limit = e.code == 429
-                    self._mark_error(client, is_rate_limit=is_rate_limit)
+                    self._mark_error(client, is_rate_limit=(e.code == 429))
                     last_exc = e
                     continue
                 except (TransportError, ProviderError) as e:
                     self._mark_error(client, is_rate_limit=False)
                     last_exc = e
                     continue
+                else:
+                    self._mark_success(client)
+                    return result
 
-                self._mark_success(client)
-                return result
-
-            if last_exc is not None:
-                raise last_exc
+            if last_exc is None:
+                raise BalancerError(
+                    "http balancer has no available clients (all in cooldown or not connected)"
+                )
 
-            raise ClientError("all HTTP clients failed to process request.")
+            raise BalancerError(
+                f"http failover exhausted after {attempts} attempt(s)"
+            ) from last_exc
 
         try:
             return await asyncio.wait_for(_run(), timeout=self._request_timeout)
         except asyncio.TimeoutError as exc:
             raise ProviderTimeoutError(
                 timeout=self._request_timeout,
-                endpoint="http balancer",
-                operation="failover request",
+                endpoint=self.__class__.__name__,
+                operation="request",
             ) from exc
 
-    async def _send_boc(self, boc: str) -> None:
+    async def _send_message(self, boc: str) -> None:
         async def _call(client: BaseClient) -> None:
-            return await client._send_boc(boc)
+            return await client._send_message(boc)
 
-        return await self._with_failover(_call)
+        method = "send_message"
+        return await self._with_failover(_call, method)
 
-    async def _get_blockchain_config(self) -> t.Dict[int, t.Any]:
+    async def _get_config(self) -> t.Dict[int, t.Any]:
         async def _call(client: BaseClient) -> t.Dict[int, t.Any]:
-            return await client._get_blockchain_config()
+            return await client._get_config()
 
-        return await self._with_failover(_call)
+        method = "get_config"
+        return await self._with_failover(_call, method)
 
-    async def _get_contract_info(self, address: str) -> ContractStateInfo:
-        async def _call(client: BaseClient) -> ContractStateInfo:
-            return await client._get_contract_info(address)
+    async def _get_info(self, address: str) -> ContractInfo:
+        async def _call(client: BaseClient) -> ContractInfo:
+            return await client._get_info(address)
 
-        return await self._with_failover(_call)
+        method = "get_info"
+        return await self._with_failover(_call, method)
 
     async def _get_transactions(
         self,
@@ -371,7 +384,8 @@ class HttpBalancer(BaseClient):
                 to_lt=to_lt,
             )
 
-        return await self._with_failover(_call)
+        method = "get_transactions"
+        return await self._with_failover(_call, method)
 
     async def _run_get_method(
         self,
@@ -386,16 +400,5 @@ class HttpBalancer(BaseClient):
                 stack=stack,
             )
 
-        return await self._with_failover(_call)
-
-    async def connect(self) -> None:
-        await asyncio.gather(
-            *(state.client.connect() for state in self._states),
-            return_exceptions=True,
-        )
-
-    async def close(self) -> None:
-        await asyncio.gather(
-            *(state.client.close() for state in self._states),
-            return_exceptions=True,
-        )
+        method = "run_get_method"
+        return await self._with_failover(_call, method)

tonutils/clients/http/clients/tatum.py

@@ -42,6 +42,7 @@ class TatumClient(ToncenterClient):
             NetworkGlobalID.TESTNET: "https://ton-testnet.gateway.tatum.io",
         }
         base_url = base_url or urls.get(network)
+
         super().__init__(
             network=network,
             api_key=api_key,

tonutils/clients/http/clients/tonapi.py

@@ -13,7 +13,7 @@ from tonutils.exceptions import ClientError, RunGetMethodError
 from tonutils.types import (
     ClientType,
     ContractState,
-    ContractStateInfo,
+    ContractInfo,
     NetworkGlobalID,
     RetryPolicy,
 )
@@ -72,31 +72,25 @@ class TonapiClient(BaseClient):
         )
 
     @property
-    def provider(self) -> TonapiHttpProvider:
-        return self._provider
-
-    @property
-    def is_connected(self) -> bool:
+    def connected(self) -> bool:
         session = self._provider.session
         return session is not None and not session.closed
 
-    async def __aenter__(self) -> TonapiClient:
+    @property
+    def provider(self) -> TonapiHttpProvider:
+        return self._provider
+
+    async def connect(self) -> None:
         await self._provider.connect()
-        return self
 
-    async def __aexit__(
-        self,
-        exc_type: t.Optional[t.Type[BaseException]],
-        exc_value: t.Optional[BaseException],
-        traceback: t.Optional[t.Any],
-    ) -> None:
+    async def close(self) -> None:
         await self._provider.close()
 
-    async def _send_boc(self, boc: str) -> None:
+    async def _send_message(self, boc: str) -> None:
         payload = BlockchainMessagePayload(boc=boc)
         return await self.provider.blockchain_message(payload=payload)
 
-    async def _get_blockchain_config(self) -> t.Dict[int, t.Any]:
+    async def _get_config(self) -> t.Dict[int, t.Any]:
         result = await self.provider.blockchain_config()
 
         if result.raw is None:
@@ -106,10 +100,10 @@ class TonapiClient(BaseClient):
         config_slice = config_cell.begin_parse()
         return parse_stack_config(config_slice)
 
-    async def _get_contract_info(self, address: str) -> ContractStateInfo:
+    async def _get_info(self, address: str) -> ContractInfo:
         result = await self.provider.blockchain_account(address)
 
-        contract_info = ContractStateInfo(
+        contract_info = ContractInfo(
             balance=result.balance,
             state=ContractState(result.status),
             last_transaction_lt=result.last_transaction_lt,
@@ -165,9 +159,3 @@ class TonapiClient(BaseClient):
             )
 
         return decode_tonapi_stack(result.stack or [])
-
-    async def connect(self) -> None:
-        await self._provider.connect()
-
-    async def close(self) -> None:
-        await self._provider.close()

tonutils/clients/http/clients/toncenter.py

@@ -14,7 +14,7 @@ from tonutils.exceptions import ClientError, RunGetMethodError
 from tonutils.types import (
     ClientType,
     ContractState,
-    ContractStateInfo,
+    ContractInfo,
     NetworkGlobalID,
     RetryPolicy,
 )
@@ -70,56 +70,44 @@ class ToncenterClient(BaseClient):
         )
 
     @property
-    def provider(self) -> ToncenterHttpProvider:
-        return self._provider
-
-    @property
-    def is_connected(self) -> bool:
+    def connected(self) -> bool:
         session = self._provider.session
         return session is not None and not session.closed
 
-    async def __aenter__(self) -> ToncenterClient:
+    @property
+    def provider(self) -> ToncenterHttpProvider:
+        return self._provider
+
+    async def connect(self) -> None:
         await self._provider.connect()
-        return self
 
-    async def __aexit__(
-        self,
-        exc_type: t.Optional[t.Type[BaseException]],
-        exc_value: t.Optional[BaseException],
-        traceback: t.Optional[t.Any],
-    ) -> None:
+    async def close(self) -> None:
         await self._provider.close()
 
-    async def _send_boc(self, boc: str) -> None:
+    async def _send_message(self, boc: str) -> None:
         payload = SendBocPayload(boc=boc)
         return await self.provider.send_boc(payload=payload)
 
-    async def _get_blockchain_config(self) -> t.Dict[int, t.Any]:
+    async def _get_config(self) -> t.Dict[int, t.Any]:
         request = await self.provider.get_config_all()
 
         if request.result is None:
-            raise ClientError(
-                "Invalid get_config_all response: missing 'result' field."
-            )
+            raise ClientError("Invalid get_config response: missing `result`.")
 
         if request.result.config is None:
-            raise ClientError(
-                "Invalid config response: missing 'config' section in result."
-            )
+            raise ClientError("Invalid config response: missing `config` in `result`.")
 
         if request.result.config.bytes is None:
-            raise ClientError(
-                "Invalid config response: missing 'bytes' field in 'config' section."
-            )
+            raise ClientError("Invalid config response: missing `config.bytes`.")
 
         config_cell = Cell.one_from_boc(request.result.config.bytes)
         config_slice = config_cell.begin_parse()
         return parse_stack_config(config_slice)
 
-    async def _get_contract_info(self, address: str) -> ContractStateInfo:
+    async def _get_info(self, address: str) -> ContractInfo:
         request = await self.provider.get_address_information(address)
 
-        contract_info = ContractStateInfo(
+        contract_info = ContractInfo(
             balance=int(request.result.balance),
             state=ContractState(request.result.state),
         )
@@ -241,9 +229,3 @@ class ToncenterClient(BaseClient):
             )
 
         return decode_toncenter_stack(request.result.stack or [])
-
-    async def connect(self) -> None:
-        await self._provider.connect()
-
-    async def close(self) -> None:
-        await self._provider.close()

tonutils/clients/http/provider/base.py

@@ -5,6 +5,7 @@ import json
 import typing as t
 
 import aiohttp
+from pydantic import BaseModel, ValidationError
 
 from tonutils.clients.limiter import RateLimiter
 from tonutils.exceptions import (
@@ -13,6 +14,8 @@ from tonutils.exceptions import (
     ProviderTimeoutError,
     RetryLimitError,
     CDN_CHALLENGE_MARKERS,
+    TransportError,
+    ProviderError,
 )
 from tonutils.types import RetryPolicy
 
@@ -65,17 +68,77 @@ class HttpProvider:
         return self._session
 
     @property
-    def is_connected(self) -> bool:
+    def connected(self) -> bool:
         """Check whether the provider session is initialized and open."""
         return self._session is not None and not self._session.closed
 
+    @staticmethod
+    def _model(model: t.Type[BaseModel], data: t.Any) -> t.Any:
+        try:
+            return model.model_validate(data)
+        except ValidationError as e:
+            raise ProviderError(
+                f"invalid response: {model.__name__} validation failed"
+            ) from e
+
+    async def send_http_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: t.Any = None,
+        json_data: t.Any = None,
+    ) -> t.Any:
+        """Send an HTTP request with retry handling.
+
+        On provider error, retries the request according to the retry policy
+        matched by error code and message. If no rule matches, or retry attempts
+        are exhausted, the error is raised.
+
+        :param method: HTTP method.
+        :param path: Endpoint path relative to base_url.
+        :param params: Optional query parameters.
+        :param json_data: Optional JSON body.
+        :return: Parsed response payload.
+        """
+        attempts: t.Dict[int, int] = {}
+
+        while True:
+            try:
+                return await self._send_once(
+                    method,
+                    path,
+                    params=params,
+                    json_data=json_data,
+                )
+            except ProviderResponseError as e:
+                policy = self._retry_policy
+                if policy is None:
+                    raise
+
+                rule = policy.rule_for(e.code, e.message)
+                if rule is None:
+                    raise
+
+                key = id(rule)
+                attempts[key] = attempts.get(key, 0) + 1
+
+                if attempts[key] >= rule.attempts:
+                    raise RetryLimitError(
+                        attempts=attempts[key],
+                        max_attempts=rule.attempts,
+                        last_error=e,
+                    ) from e
+
+                await asyncio.sleep(rule.delay(attempts[key] - 1))
+
     async def connect(self) -> None:
         """Initialize HTTP session if not already connected."""
-        if self.is_connected:
+        if self.connected:
             return
 
         async with self._connect_lock:
-            if self.is_connected:
+            if self.connected:
                 return
 
             self._session = aiohttp.ClientSession(
@@ -139,8 +202,12 @@ class HttpProvider:
         :param json_data: Optional JSON body.
         :return: Parsed response payload.
         """
-        if not self.is_connected:
-            raise NotConnectedError()
+        if not self.connected:
+            raise NotConnectedError(
+                component="HttpProvider",
+                endpoint=self._base_url,
+                operation=f"{method} {path}",
+            )
 
         assert self._session is not None
         url = f"{self._base_url}/{path.lstrip('/')}"
@@ -166,65 +233,13 @@ class HttpProvider:
                 endpoint=url,
                 operation="http request",
             ) from exc
-
         except aiohttp.ClientError as exc:
-            raise ProviderResponseError(
-                code=0,
-                message=str(exc),
+            raise TransportError(
                 endpoint=url,
+                operation="http request",
+                reason=str(exc),
             ) from exc
 
-    async def send_http_request(
-        self,
-        method: str,
-        path: str,
-        *,
-        params: t.Any = None,
-        json_data: t.Any = None,
-    ) -> t.Any:
-        """Send an HTTP request with retry handling.
-
-        On provider error, retries the request according to the retry policy
-        matched by error code and message. If no rule matches, or retry attempts
-        are exhausted, the error is raised.
-
-        :param method: HTTP method.
-        :param path: Endpoint path relative to base_url.
-        :param params: Optional query parameters.
-        :param json_data: Optional JSON body.
-        :return: Parsed response payload.
-        """
-        attempts: t.Dict[int, int] = {}
-
-        while True:
-            try:
-                return await self._send_once(
-                    method,
-                    path,
-                    params=params,
-                    json_data=json_data,
-                )
-            except ProviderResponseError as e:
-                policy = self._retry_policy
-                if policy is None:
-                    raise
-
-                rule = policy.rule_for(e.code, e.message)
-                if rule is None:
-                    raise
-
-                key = id(rule)
-                attempts[key] = attempts.get(key, 0) + 1
-
-                if attempts[key] >= rule.attempts:
-                    raise RetryLimitError(
-                        attempts=attempts[key],
-                        max_attempts=rule.attempts,
-                        last_error=e,
-                    ) from e
-
-                await asyncio.sleep(rule.delay(attempts[key] - 1))
-
     @classmethod
     def _detect_proxy_error(
         cls,

tonutils/clients/http/provider/models.py

@@ -140,7 +140,7 @@ class RunGetMethodPayload(BaseModel):
     stack: t.List[t.Any]
 
 
-class RunGetMethodResul(BaseModel):
+class RunGetMethodResult(BaseModel):
     """Response wrapper for /runGetMethod."""
 
     result: t.Optional[_GetMethod] = None

tonutils/clients/http/provider/tonapi.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import typing as t
 
 import aiohttp
-from pydantic import BaseModel
 
 from tonutils.clients.http.provider.base import HttpProvider
 from tonutils.clients.http.provider.models import (
@@ -50,10 +49,6 @@ class TonapiHttpProvider(HttpProvider):
             retry_policy=retry_policy,
         )
 
-    @staticmethod
-    def _model(model: t.Type[BaseModel], data: t.Any) -> t.Any:
-        return model.model_validate(data)
-
     async def blockchain_message(
         self,
         payload: BlockchainMessagePayload,