tonutils 2.0.1b5__py3-none-any.whl → 2.0.1b7__py3-none-any.whl

tonutils/clients/http/balancer.py

@@ -10,7 +10,7 @@ from itertools import cycle
 from pytoniq_core import Transaction
 
 from tonutils.clients.base import BaseClient
-from tonutils.clients.http.clients.quicknode import QuicknodeHttpClient
+from tonutils.clients.http.clients.quicknode import QuicknodeClient
 from tonutils.exceptions import (
     BalancerError,
     ClientError,
@@ -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")
 
@@ -50,8 +51,8 @@ class HttpBalancer(BaseClient):
 
     def __init__(
         self,
-        *,
         network: NetworkGlobalID = NetworkGlobalID.MAINNET,
+        *,
         clients: t.List[BaseClient],
         request_timeout: float = 12.0,
     ) -> None:
@@ -60,27 +61,27 @@ class HttpBalancer(BaseClient):
 
         Each supported HTTP client requires its own credentials or endpoint
         configuration. You can obtain them from the corresponding provider:
-            - ToncenterHttpClient:
+            - ToncenterClient:
                 API key available via Telegram bot: https://t.me/toncenter
-            - TonapiHttpClient:
+            - TonapiClient:
                 API key available on the Tonconsole website: https://tonconsole.com/
-            - ChainstackHttpClient:
+            - ChainstackClient:
                 Personal endpoint available on: https://chainstack.com/
-            - QuicknodeHttpClient:
+            - QuicknodeClient:
                 Personal endpoint available on: https://www.quicknode.com/
-            - TatumHttpClient:
+            - TatumClient:
                 API key available on: https://tatum.io/
 
         :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, QuicknodeHttpClient)
-                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,92 +285,107 @@ 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_contract_transactions(
+    async def _get_transactions(
         self,
         address: str,
         limit: int = 100,
         from_lt: t.Optional[int] = None,
-        to_lt: int = 0,
+        to_lt: t.Optional[int] = None,
     ) -> t.List[Transaction]:
         async def _call(client: BaseClient) -> t.List[Transaction]:
-            return await client._get_contract_transactions(
+            return await client._get_transactions(
                 address=address,
                 limit=limit,
                 from_lt=from_lt,
                 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/__init__.py

@@ -1,13 +1,13 @@
-from .chainstack import ChainstackHttpClient
-from .quicknode import QuicknodeHttpClient
-from .tatum import TatumHttpClient
-from .tonapi import TonapiHttpClient
-from .toncenter import ToncenterHttpClient
+from .chainstack import ChainstackClient
+from .quicknode import QuicknodeClient
+from .tatum import TatumClient
+from .tonapi import TonapiClient
+from .toncenter import ToncenterClient
 
 __all__ = [
-    "ChainstackHttpClient",
-    "QuicknodeHttpClient",
-    "TatumHttpClient",
-    "TonapiHttpClient",
-    "ToncenterHttpClient",
+    "ChainstackClient",
+    "QuicknodeClient",
+    "TatumClient",
+    "TonapiClient",
+    "ToncenterClient",
 ]

tonutils/clients/http/clients/chainstack.py

@@ -2,16 +2,16 @@ import typing as t
 
 from aiohttp import ClientSession
 
-from tonutils.clients.http.clients.toncenter import ToncenterHttpClient
+from tonutils.clients.http.clients.toncenter import ToncenterClient
 from tonutils.types import NetworkGlobalID, RetryPolicy
 
 
-class ChainstackHttpClient(ToncenterHttpClient):
+class ChainstackClient(ToncenterClient):
 
     def __init__(
         self,
-        *,
         network: NetworkGlobalID,
+        *,
         http_provider_url: str,
         timeout: float = 10.0,
         session: t.Optional[ClientSession] = None,

tonutils/clients/http/clients/quicknode.py

@@ -2,11 +2,11 @@ import typing as t
 
 from aiohttp import ClientSession
 
-from tonutils.clients.http.clients.toncenter import ToncenterHttpClient
+from tonutils.clients.http.clients.toncenter import ToncenterClient
 from tonutils.types import NetworkGlobalID, RetryPolicy
 
 
-class QuicknodeHttpClient(ToncenterHttpClient):
+class QuicknodeClient(ToncenterClient):
 
     def __init__(
         self,
@@ -33,7 +33,6 @@ class QuicknodeHttpClient(ToncenterHttpClient):
         :param rps_period: Rate limit period in seconds.
         :param retry_policy: Optional retry policy that defines per-error-code retry rules
         """
-
         super().__init__(
             network=NetworkGlobalID.MAINNET,
             base_url=http_provider_url,

tonutils/clients/http/clients/tatum.py

@@ -2,16 +2,16 @@ import typing as t
 
 from aiohttp import ClientSession
 
-from tonutils.clients.http.clients.toncenter import ToncenterHttpClient
+from tonutils.clients.http.clients.toncenter import ToncenterClient
 from tonutils.types import NetworkGlobalID, RetryPolicy
 
 
-class TatumHttpClient(ToncenterHttpClient):
+class TatumClient(ToncenterClient):
 
     def __init__(
         self,
-        *,
         network: NetworkGlobalID,
+        *,
         api_key: str,
         base_url: t.Optional[str] = None,
         timeout: float = 10.0,
@@ -42,6 +42,7 @@ class TatumHttpClient(ToncenterHttpClient):
             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

@@ -6,14 +6,14 @@ from aiohttp import ClientSession
 from pytoniq_core import Cell, Slice, Transaction
 
 from tonutils.clients.base import BaseClient
-from tonutils.clients.http.providers.tonapi.models import BlockchainMessagePayload
-from tonutils.clients.http.providers.tonapi.provider import TonapiHttpProvider
+from tonutils.clients.http.provider.models import BlockchainMessagePayload
+from tonutils.clients.http.provider.tonapi import TonapiHttpProvider
 from tonutils.clients.http.utils import encode_tonapi_stack, decode_tonapi_stack
 from tonutils.exceptions import ClientError, RunGetMethodError
 from tonutils.types import (
     ClientType,
     ContractState,
-    ContractStateInfo,
+    ContractInfo,
     NetworkGlobalID,
     RetryPolicy,
 )
@@ -23,15 +23,15 @@ from tonutils.utils import (
 )
 
 
-class TonapiHttpClient(BaseClient):
+class TonapiClient(BaseClient):
     """TON blockchain client using Tonapi HTTP API as transport."""
 
     TYPE = ClientType.HTTP
 
     def __init__(
         self,
-        *,
         network: NetworkGlobalID = NetworkGlobalID.MAINNET,
+        *,
         api_key: str,
         base_url: t.Optional[str] = None,
         timeout: float = 10.0,
@@ -72,31 +72,25 @@ class TonapiHttpClient(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) -> TonapiHttpClient:
+    @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 TonapiHttpClient(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,
@@ -122,21 +116,20 @@ class TonapiHttpClient(BaseClient):
 
         return contract_info
 
-    async def _get_contract_transactions(
+    async def _get_transactions(
         self,
         address: str,
         limit: int = 100,
         from_lt: t.Optional[int] = None,
-        to_lt: int = 0,
+        to_lt: t.Optional[int] = None,
     ) -> t.List[Transaction]:
-        if from_lt is not None:
-            from_lt += 1
+        before_lt = from_lt + 1 if from_lt is not None else None
 
         result = await self.provider.blockchain_account_transactions(
             address=address,
             limit=limit,
             after_lt=to_lt,
-            before_lt=from_lt,
+            before_lt=before_lt,
         )
 
         transactions = []
@@ -166,9 +159,3 @@ class TonapiHttpClient(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()