pytonapi 0.4.9__tar.gz → 2.0.0__tar.gz

pytonapi-2.0.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: pytonapi
+Version: 2.0.0
+Summary: Python SDK for TONAPI — REST API, streaming, and webhooks for TON blockchain.
+Author: nessshon
+Maintainer: nessshon
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nessshon/pytonapi/
+Project-URL: Examples, https://github.com/nessshon/pytonapi/tree/main/examples/
+Keywords: AsyncIO,REST API,SDK,TON,TON blockchain,TONAPI,The Open Network,blockchain,crypto,streaming,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: pydantic<3.0,>=2.4.1
+Dynamic: license-file
+
+# 📦 PyTONAPI
+
+[![TON](https://img.shields.io/badge/TON-grey?logo=TON&logoColor=40AEF0)](https://ton.org)
+![Python Versions](https://img.shields.io/badge/Python-3.10%20--%203.14-black?color=FFE873&labelColor=3776AB)
+[![PyPI](https://img.shields.io/pypi/v/pytonapi.svg?color=FFE873&labelColor=3776AB)](https://pypi.python.org/pypi/pytonapi)
+[![License](https://img.shields.io/github/license/nessshon/pytonapi)](https://github.com/nessshon/pytonapi/blob/main/LICENSE)
+[![Donate](https://img.shields.io/badge/Donate-TON-blue)](https://tonviewer.com/UQCZq3_Vd21-4y4m7Wc-ej9NFOhh_qvdfAkAYAOHoQ__Ness)
+
+![Image](assets/banner.png)
+
+![Downloads](https://pepy.tech/badge/pytonapi)
+![Downloads](https://pepy.tech/badge/pytonapi/month)
+![Downloads](https://pepy.tech/badge/pytonapi/week)
+
+### Python SDK for [TONAPI](https://tonapi.io)
+
+Providing access to TON blockchain data via REST API, real-time streaming, and webhooks.  
+An API key is required and can be obtained at [tonconsole.com](https://tonconsole.com/). Documentation available
+at [docs.tonconsole.com](https://docs.tonconsole.com/).
+
+> For creating wallets, transferring TON, jettons, etc., use [tonutils](https://github.com/nessshon/tonutils).
+
+**Features**
+
+- **REST API** — accounts, NFTs, jettons, DNS, and more
+- **Streaming** — real-time events via SSE and WebSocket
+- **Webhooks** — push notifications with event dispatcher
+
+> If this project has been useful to you, consider supporting its development.  
+> **TON**: `UQCZq3_Vd21-4y4m7Wc-ej9NFOhh_qvdfAkAYAOHoQ__Ness`
+
+## Installation
+
+```bash
+pip install pytonapi
+```
+
+## Examples
+
+**REST API**
+
+- [Get account info](examples/get_account_info.py)
+- [Get account transactions](examples/get_account_transactions.py)
+- [Get NFTs by owner](examples/get_nft_by_owner.py)
+- [Get NFTs by collection](examples/get_nft_by_collection.py)
+
+**Streaming** (SSE & WebSocket)
+
+- [SSE subscriptions](examples/streaming_sse.py)
+- [WebSocket subscriptions](examples/streaming_websocket.py)
+
+**Webhooks**
+
+- [FastAPI webhook server](examples/webhook_fastapi.py)
+- [aiohttp webhook server](examples/webhook_aiohttp.py)
+
+**Transfers** (requires [tonutils](https://github.com/nessshon/tonutils))
+
+- [Transfer TON](examples/transfer_ton.py)
+- [Gasless transfer](examples/transfer_gasless.py)
+
+## Support
+
+Supported by [TON Society](https://github.com/ton-society/grants-and-bounties) and [TONAPI](https://tonapi.io).
+
+## License
+
+This repository is distributed under the [MIT License](LICENSE).

pytonapi-2.0.0/README.md

@@ -0,0 +1,68 @@
+# 📦 PyTONAPI
+
+[![TON](https://img.shields.io/badge/TON-grey?logo=TON&logoColor=40AEF0)](https://ton.org)
+![Python Versions](https://img.shields.io/badge/Python-3.10%20--%203.14-black?color=FFE873&labelColor=3776AB)
+[![PyPI](https://img.shields.io/pypi/v/pytonapi.svg?color=FFE873&labelColor=3776AB)](https://pypi.python.org/pypi/pytonapi)
+[![License](https://img.shields.io/github/license/nessshon/pytonapi)](https://github.com/nessshon/pytonapi/blob/main/LICENSE)
+[![Donate](https://img.shields.io/badge/Donate-TON-blue)](https://tonviewer.com/UQCZq3_Vd21-4y4m7Wc-ej9NFOhh_qvdfAkAYAOHoQ__Ness)
+
+![Image](assets/banner.png)
+
+![Downloads](https://pepy.tech/badge/pytonapi)
+![Downloads](https://pepy.tech/badge/pytonapi/month)
+![Downloads](https://pepy.tech/badge/pytonapi/week)
+
+### Python SDK for [TONAPI](https://tonapi.io)
+
+Providing access to TON blockchain data via REST API, real-time streaming, and webhooks.  
+An API key is required and can be obtained at [tonconsole.com](https://tonconsole.com/). Documentation available
+at [docs.tonconsole.com](https://docs.tonconsole.com/).
+
+> For creating wallets, transferring TON, jettons, etc., use [tonutils](https://github.com/nessshon/tonutils).
+
+**Features**
+
+- **REST API** — accounts, NFTs, jettons, DNS, and more
+- **Streaming** — real-time events via SSE and WebSocket
+- **Webhooks** — push notifications with event dispatcher
+
+> If this project has been useful to you, consider supporting its development.  
+> **TON**: `UQCZq3_Vd21-4y4m7Wc-ej9NFOhh_qvdfAkAYAOHoQ__Ness`
+
+## Installation
+
+```bash
+pip install pytonapi
+```
+
+## Examples
+
+**REST API**
+
+- [Get account info](examples/get_account_info.py)
+- [Get account transactions](examples/get_account_transactions.py)
+- [Get NFTs by owner](examples/get_nft_by_owner.py)
+- [Get NFTs by collection](examples/get_nft_by_collection.py)
+
+**Streaming** (SSE & WebSocket)
+
+- [SSE subscriptions](examples/streaming_sse.py)
+- [WebSocket subscriptions](examples/streaming_websocket.py)
+
+**Webhooks**
+
+- [FastAPI webhook server](examples/webhook_fastapi.py)
+- [aiohttp webhook server](examples/webhook_aiohttp.py)
+
+**Transfers** (requires [tonutils](https://github.com/nessshon/tonutils))
+
+- [Transfer TON](examples/transfer_ton.py)
+- [Gasless transfer](examples/transfer_gasless.py)
+
+## Support
+
+Supported by [TON Society](https://github.com/ton-society/grants-and-bounties) and [TONAPI](https://tonapi.io).
+
+## License
+
+This repository is distributed under the [MIT License](LICENSE).

pytonapi-2.0.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytonapi"
+description = "Python SDK for TONAPI — REST API, streaming, and webhooks for TON blockchain."
+requires-python = ">=3.10,<3.15"
+authors = [
+    { name = "nessshon" },
+]
+maintainers = [
+    { name = "nessshon" },
+]
+dependencies = [
+    "aiohttp>=3.9.0",
+    "pydantic>=2.4.1,<3.0",
+]
+keywords = [
+    "AsyncIO",
+    "REST API",
+    "SDK",
+    "TON",
+    "TON blockchain",
+    "TONAPI",
+    "The Open Network",
+    "blockchain",
+    "crypto",
+    "streaming",
+    "webhooks",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dynamic = ["version"]
+readme = "README.md"
+license = "MIT"
+
+[project.scripts]
+pytonapi = "pytonapi.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/nessshon/pytonapi/"
+Examples = "https://github.com/nessshon/pytonapi/tree/main/examples/"
+
+[tool.setuptools.packages.find]
+include = ["pytonapi", "pytonapi.*"]
+
+[tool.setuptools.package-data]
+pytonapi = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = { attr = "pytonapi.__init__.__version__" }
+
+[tool.mypy]
+python_version = "3.10"
+follow_imports = "skip"
+ignore_missing_imports = true

pytonapi-2.0.0/pytonapi/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) 2023 Shon Ness
+#
+# This source code is licensed under the MIT License found in the
+# LICENSE file in the root directory of this source tree.
+
+
+__all__ = [
+    "__uri__",
+    "__version__",
+]
+
+__version__ = "2.0.0"
+__uri__ = "https://github.com/nessshon/pytonapi"

pytonapi-2.0.0/pytonapi/cli.py

@@ -0,0 +1,23 @@
+import argparse
+
+from pytonapi import __version__
+
+
+def main() -> None:
+    """CLI entry-point."""
+    parser = argparse.ArgumentParser(
+        prog="pytonapi",
+        description="pytonapi CLI.",
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"pytonapi {__version__}",
+    )
+    parser.parse_args()
+    parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

pytonapi-2.0.0/pytonapi/client.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import typing as t
+
+import aiohttp
+
+from pytonapi.exceptions import (
+    TONAPIConnectionError,
+    TONAPIError,
+    TONAPIRetryLimitError,
+    TONAPISessionNotCreatedError,
+    raise_for_status,
+)
+from pytonapi.types import (
+    DEFAULT_RETRY_POLICY,
+    RetryPolicy,
+)
+
+__all__ = ["BaseClient"]
+
+T = t.TypeVar("T")
+
+
+class BaseClient:
+    """Base async HTTP client with session management and retry."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        timeout: float = 10.0,
+        session: t.Optional[aiohttp.ClientSession] = None,
+        headers: t.Optional[t.Dict[str, str]] = None,
+        cookies: t.Optional[t.Dict[str, str]] = None,
+        retry_policy: t.Optional[RetryPolicy] = DEFAULT_RETRY_POLICY,
+    ) -> None:
+        """Initialize the base HTTP client.
+
+        :param api_key: TONAPI key. Get one at https://tonconsole.com/.
+        :param base_url: Base URL for all requests.
+        :param timeout: Request timeout in seconds.
+        :param session: Optional external ``aiohttp.ClientSession``.
+            When provided, the client will not close it — the caller
+            is responsible for managing its lifecycle.
+        :param headers: Additional HTTP headers sent with every request.
+        :param cookies: Additional cookies sent with every request.
+        :param retry_policy: Retry policy, or ``None`` to disable retries.
+        """
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+
+        self._headers = headers or {}
+        self._cookies = cookies or {}
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._session: t.Optional[aiohttp.ClientSession] = session
+
+        self._is_external_session = session is not None
+        self._retry_policy = retry_policy
+
+    async def create_session(self) -> BaseClient:
+        """Create an ``aiohttp.ClientSession`` for making requests.
+
+        If an external session was provided via the ``session`` parameter,
+        this method does nothing — the external session is used as-is.
+
+        :return: This client instance.
+        """
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                headers=self._build_headers(),
+                cookies=self._cookies,
+                timeout=self._timeout,
+            )
+            self._is_external_session = False
+        return self
+
+    async def close_session(self) -> None:
+        """Close the ``aiohttp.ClientSession``.
+
+        If the session was provided externally, it is not closed here —
+        the caller is responsible for managing its lifecycle.
+        """
+        if self._session and not self._session.closed and not self._is_external_session:
+            await self._session.close()
+            self._session = None
+
+    async def __aenter__(self) -> BaseClient:
+        """Enter the async context manager."""
+        await self.create_session()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: t.Optional[t.Type[BaseException]],
+        exc_val: t.Optional[BaseException],
+        exc_tb: t.Optional[t.Any],
+    ) -> None:
+        """Exit the async context manager."""
+        await self.close_session()
+
+    def _build_headers(self) -> t.Dict[str, str]:
+        """Build default request headers.
+
+        :return: Merged headers dict.
+        """
+        base = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+        }
+        base.update(self._headers)
+        return base
+
+    @staticmethod
+    def _parse_body(text: str) -> t.Tuple[t.Any, str]:
+        """Parse response text and extract error message.
+
+        :param text: Raw response text.
+        :return: Tuple of ``(parsed_data, error_message)``.
+        """
+        try:
+            data = json.loads(text)
+        except (json.JSONDecodeError,):
+            return None, text
+
+        if isinstance(data, dict):
+            message = data.get("error") or data.get("Error") or text
+            if isinstance(message, dict):
+                message = str(message)
+            return data, message
+
+        return data, str(data)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: t.Optional[t.Dict[str, t.Any]] = None,
+        body: t.Optional[t.Any] = None,
+        headers: t.Optional[t.Dict[str, t.Any]] = None,
+        response_model: t.Optional[t.Type[T]] = None,
+    ) -> t.Any:
+        """Execute an HTTP request with retry.
+
+        :param method: HTTP method (``GET``, ``POST``, etc.).
+        :param path: API path.
+        :param params: Query parameters.
+        :param body: JSON request body.
+        :param headers: Additional request headers.
+        :param response_model: Pydantic model to parse response into.
+        :return: Parsed model instance, raw dict, or ``None``.
+        """
+        url = f"{self._base_url}{path}"
+        if params:
+            params = {
+                k: str(v).lower() if isinstance(v, bool) else v
+                for k, v in params.items()
+                if v is not None
+            }
+        if headers:
+            headers = {k: str(v) for k, v in headers.items() if v is not None}
+
+        if self._session is None or self._session.closed:
+            raise TONAPISessionNotCreatedError(self.__class__.__name__)
+
+        session = self._session
+        last_error: t.Optional[Exception] = None
+        last_status: t.Optional[int] = None
+        max_attempts = 1
+
+        if self._retry_policy:
+            max_rule_retries = max(
+                (r.max_retries for r in self._retry_policy.rules),
+                default=0,
+            )
+            max_attempts = max_rule_retries + 1
+
+        for attempt in range(max_attempts):
+            try:
+                async with session.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=body,
+                    headers=headers,
+                ) as response:
+                    if 200 <= response.status < 300:
+                        return await self._handle_success(
+                            response,
+                            response_model,
+                        )
+
+                    last_status = response.status
+
+                    if self._retry_policy:
+                        rule = self._retry_policy.find_rule(response.status)
+                        if rule and attempt < rule.max_retries:
+                            delay = rule.delay_for_attempt(attempt)
+                            await response.read()
+                            await asyncio.sleep(delay)
+                            continue
+
+                    text = await response.text()
+                    content_type = response.headers.get("Content-Type", "")
+                    raise_for_status(response.status, text, content_type)
+
+            except (TONAPIError,):
+                raise
+            except (aiohttp.ClientError,) as exc:
+                last_error = exc
+                if attempt < max_attempts - 1:
+                    await asyncio.sleep(1.0)
+                    continue
+                raise TONAPIConnectionError(
+                    f"Connection error: {exc}",
+                ) from exc
+
+        raise TONAPIRetryLimitError(
+            attempts=max_attempts,
+            last_status=last_status,
+            last_error=last_error,
+        )
+
+    async def _handle_success(
+        self,
+        response: aiohttp.ClientResponse,
+        response_model: t.Optional[t.Type[T]],
+    ) -> t.Any:
+        """Process a successful (2xx) response.
+
+        :param response: Aiohttp response.
+        :param response_model: Expected return type.
+        :return: Parsed result.
+        """
+        content_type = response.headers.get("Content-Type", "")
+        if "text/html" in content_type:
+            raise TONAPIError(
+                f"HTTP {response.status}: Unexpected HTML response",
+            )
+
+        if response_model is None:
+            text = await response.text()
+            data, _ = self._parse_body(text)
+            return data
+        if response_model is bytes:
+            return await response.read()
+        if response_model is str:
+            return await response.text()
+        if response_model is bool:
+            text = (await response.text()).strip().lower()
+            return text in ("true", "1")
+        if response_model in (int, float):
+            return response_model(await response.text())  # type: ignore[call-arg]
+
+        text = await response.text()
+        data, _ = self._parse_body(text)
+        if data is None:
+            raise TONAPIError(f"Expected JSON response, got: {text}")
+        return response_model.model_validate(data)  # type: ignore[attr-defined]