unicex 0.13.17__py3-none-any.whl

unicex/bybit/websocket_manager.py

@@ -0,0 +1,339 @@
+__all__ = ["WebsocketManager"]
+
+import json
+import warnings
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any, Literal
+
+from unicex._base import Websocket
+
+from .client import Client
+
+type CallbackType = Callable[[Any], Awaitable[None]]
+
+
+class WebsocketManager:
+    """Менеджер асинхронных вебсокетов для Bybit."""
+
+    _SPOT_URL: str = "wss://stream.bybit.com/v5/public/spot"
+    """Базовый URL для вебсокета на спот."""
+
+    _LINEAR_URL: str = "wss://stream.bybit.com/v5/public/linear"
+    """Базовый URL для вебсокета на USDT/USDC перпетуалы и фьючерсы."""
+
+    _INVERSE_URL: str = "wss://stream.bybit.com/v5/public/inverse"
+    """Базовый URL для вебсокета на инверсные контракты."""
+
+    _OPTION_URL: str = "wss://stream.bybit.com/v5/public/option"
+    """Базовый URL для вебсокета на опционы."""
+
+    _PRIVATE_URL: str = "wss://stream.bybit.com/v5/private"
+    """Базовый URL для приватных вебсокетов."""
+
+    def __init__(self, client: Client | None = None, **ws_kwargs: Any) -> None:
+        """Инициализирует менеджер вебсокетов для Bybit.
+
+        Параметры:
+            client (`Client | None`): Клиент для выполнения запросов. Нужен, чтобы открыть приватные вебсокеты.
+            ws_kwargs (`dict[str, Any]`): Дополнительные аргументы, которые прокидываются в `Websocket`.
+        """
+        self.client = client
+        self._ws_kwargs = ws_kwargs
+
+    def _generate_subscription_message(
+        self,
+        topics: Sequence[str],
+        req_id: str | None = None,
+    ) -> list[str]:
+        """Сформировать сообщение для подписки на вебсокет.
+
+        Параметры:
+            topics (`Sequence[str]`): Список топиков для подписки.
+            req_id (`str | None`): Опциональный идентификатор запроса.
+
+        Возвращает:
+            `list[str]`: Список JSON строк для отправки.
+        """
+        message = {"op": "subscribe", "args": list(topics)}
+        if req_id:
+            message["req_id"] = req_id
+
+        return [json.dumps(message)]
+
+    def _get_url_for_category(
+        self, category: Literal["spot", "linear", "inverse", "option", "private"]
+    ) -> str:
+        """Получить URL для категории.
+
+        Параметры:
+            category (`Literal["spot", "linear", "inverse", "option", "private"]`): Категория рынка.
+
+        Возвращает:
+            `str`: URL для вебсокета.
+        """
+        if category == "spot":
+            return self._SPOT_URL
+        elif category == "linear":
+            return self._LINEAR_URL
+        elif category == "inverse":
+            return self._INVERSE_URL
+        elif category == "option":
+            return self._OPTION_URL
+        elif category == "private":
+            return self._PRIVATE_URL
+        else:
+            raise ValueError(f"Unsupported category: {category}")
+
+    def orderbook(
+        self,
+        callback: CallbackType,
+        category: Literal["spot", "linear", "inverse", "option"],
+        depth: Literal[1, 25, 50, 100, 200, 500, 1000] = 1,
+        symbol: str | None = None,
+        symbols: Sequence[str] | None = None,
+        req_id: str | None = None,
+    ) -> Websocket:
+        """Создает вебсокет для получения данных order book.
+
+        https://bybit-exchange.github.io/docs/v5/websocket/public/orderbook
+
+        Параметры:
+            callback (`CallbackType`): Асинхронная функция обратного вызова для обработки сообщений.
+            category (`Literal["spot", "linear", "inverse", "option"]`): Категория рынка.
+            depth (`Literal[1, 25, 50, 100, 200, 500, 1000]`): Глубина order book.
+            symbol (`str | None`): Один символ для подписки.
+            symbols (`Sequence[str] | None`): Список символов для мультиплекс‑подключения.
+            req_id (`str | None`): Опциональный идентификатор запроса.
+
+        Возвращает:
+            `Websocket`: Объект для управления вебсокет соединением.
+        """
+        if symbol and symbols:
+            raise ValueError("Parameters symbol and symbols cannot be used together")
+        if not (symbol or symbols):
+            raise ValueError("Either symbol or symbols must be provided")
+
+        tickers = [symbol] if symbol else symbols
+        topics = [f"orderbook.{depth}.{ticker.upper()}" for ticker in tickers]  # type: ignore
+
+        subscription_messages = self._generate_subscription_message(topics, req_id)
+        url = self._get_url_for_category(category)
+
+        return Websocket(
+            callback=callback,
+            url=url,
+            subscription_messages=subscription_messages,
+            **self._ws_kwargs,
+        )
+
+    def kline(
+        self,
+        callback: CallbackType,
+        category: Literal["spot", "linear", "inverse", "option"],
+        interval: Literal[
+            "1", "3", "5", "15", "30", "60", "120", "240", "360", "720", "D", "W", "M"
+        ],
+        symbol: str | None = None,
+        symbols: Sequence[str] | None = None,
+        req_id: str | None = None,
+    ) -> Websocket:
+        """Создает вебсокет для получения данных klines (свечей).
+
+        https://bybit-exchange.github.io/docs/v5/websocket/public/kline
+
+        Параметры:
+            callback (`CallbackType`): Асинхронная функция обратного вызова для обработки сообщений.
+            category (`Literal["spot", "linear", "inverse", "option"]`): Категория рынка.
+            interval (`Literal["1", "3", "5", "15", "30", "60", "120", "240", "360", "720", "D", "W", "M"]`): Интервал свечи.
+            symbol (`str | None`): Один символ для подписки.
+            symbols (`Sequence[str] | None`): Список символов для мультиплекс‑подключения.
+            req_id (`str | None`): Опциональный идентификатор запроса.
+
+        Возвращает:
+            `Websocket`: Объект для управления вебсокет соединением.
+        """
+        if symbol and symbols:
+            raise ValueError("Parameters symbol and symbols cannot be used together")
+        if not (symbol or symbols):
+            raise ValueError("Either symbol or symbols must be provided")
+
+        tickers = [symbol] if symbol else symbols
+        topics = [f"kline.{interval}.{ticker.upper()}" for ticker in tickers]  # type: ignore
+
+        subscription_messages = self._generate_subscription_message(topics, req_id)
+        url = self._get_url_for_category(category)
+
+        return Websocket(
+            callback=callback,
+            url=url,
+            subscription_messages=subscription_messages,
+            **self._ws_kwargs,
+        )
+
+    def trade(
+        self,
+        callback: CallbackType,
+        category: Literal["spot", "linear", "inverse", "option"],
+        symbol: str | None = None,
+        symbols: Sequence[str] | None = None,
+        req_id: str | None = None,
+    ) -> Websocket:
+        """Создает вебсокет для получения публичных сделок.
+
+        https://bybit-exchange.github.io/docs/v5/websocket/public/trade
+
+        Параметры:
+            callback (`CallbackType`): Асинхронная функция обратного вызова для обработки сообщений.
+            category (`Literal["spot", "linear", "inverse", "option"]`): Категория рынка.
+            symbol (`str | None`): Один символ для подписки.
+            symbols (`Sequence[str] | None`): Список символов для мультиплекс‑подключения.
+            req_id (`str | None`): Опциональный идентификатор запроса.
+
+        Возвращает:
+            `Websocket`: Объект для управления вебсокет соединением.
+        """
+        if symbol and symbols:
+            raise ValueError("Parameters symbol and symbols cannot be used together")
+        if not (symbol or symbols):
+            raise ValueError("Either symbol or symbols must be provided")
+
+        tickers = [symbol] if symbol else symbols
+        topics = [f"publicTrade.{ticker.upper()}" for ticker in tickers]  # type: ignore
+
+        subscription_messages = self._generate_subscription_message(topics, req_id)
+        url = self._get_url_for_category(category)
+
+        return Websocket(
+            callback=callback,
+            url=url,
+            subscription_messages=subscription_messages,
+            **self._ws_kwargs,
+        )
+
+    def ticker(
+        self,
+        callback: CallbackType,
+        category: Literal["spot", "linear", "inverse", "option"],
+        symbol: str | None = None,
+        symbols: Sequence[str] | None = None,
+        req_id: str | None = None,
+    ) -> Websocket:
+        """Создает вебсокет для получения тикеров.
+
+        https://bybit-exchange.github.io/docs/v5/websocket/public/ticker
+
+        Параметры:
+            callback (`CallbackType`): Асинхронная функция обратного вызова для обработки сообщений.
+            category (`Literal["spot", "linear", "inverse", "option"]`): Категория рынка.
+            symbol (`str | None`): Один символ для подписки.
+            symbols (`Sequence[str] | None`): Список символов для мультиплекс‑подключения.
+            req_id (`str | None`): Опциональный идентификатор запроса.
+
+        Возвращает:
+            `Websocket`: Объект для управления вебсокет соединением.
+        """
+        if symbol and symbols:
+            raise ValueError("Parameters symbol and symbols cannot be used together")
+        if not (symbol or symbols):
+            raise ValueError("Either symbol or symbols must be provided")
+
+        tickers = [symbol] if symbol else symbols
+        topics = [f"tickers.{ticker.upper()}" for ticker in tickers]  # type: ignore
+
+        subscription_messages = self._generate_subscription_message(topics, req_id)
+        url = self._get_url_for_category(category)
+
+        return Websocket(
+            callback=callback,
+            url=url,
+            subscription_messages=subscription_messages,
+            **self._ws_kwargs,
+        )
+
+    def liquidation(
+        self,
+        callback: CallbackType,
+        category: Literal["linear", "inverse"],
+        symbol: str | None = None,
+        symbols: Sequence[str] | None = None,
+        req_id: str | None = None,
+    ) -> Websocket:
+        """Создает вебсокет для получения данных ликвидаций.
+
+        https://bybit-exchange.github.io/docs/v5/websocket/public/liquidation
+
+        Параметры:
+            callback (`CallbackType`): Асинхронная функция обратного вызова для обработки сообщений.
+            category (`Literal["linear", "inverse"]`): Категория рынка (только для деривативов).
+            symbol (`str | None`): Один символ для подписки.
+            symbols (`Sequence[str] | None`): Список символов для мультиплекс‑подключения.
+            req_id (`str | None`): Опциональный идентификатор запроса.
+
+        Возвращает:
+            `Websocket`: Объект для управления вебсокет соединением.
+        """
+        warnings.warn(
+            "TDepreicated liquidation stream, please move to All Liquidation Subscribe"
+            "to the liquidation stream. Pushes at most one order per second per symbol."
+            "As such, this feed does not push all liquidations that occur on Bybit.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        if symbol and symbols:
+            raise ValueError("Parameters symbol and symbols cannot be used together")
+        if not (symbol or symbols):
+            raise ValueError("Either symbol or symbols must be provided")
+
+        tickers = [symbol] if symbol else symbols
+        topics = [f"liquidation.{ticker.upper()}" for ticker in tickers]  # type: ignore
+
+        subscription_messages = self._generate_subscription_message(topics, req_id)
+        url = self._get_url_for_category(category)
+
+        return Websocket(
+            callback=callback,
+            url=url,
+            subscription_messages=subscription_messages,
+            **self._ws_kwargs,
+        )
+
+    def all_liquidation(
+        self,
+        callback: CallbackType,
+        category: Literal["linear", "inverse"],
+        symbol: str | None = None,
+        symbols: Sequence[str] | None = None,
+        req_id: str | None = None,
+    ) -> Websocket:
+        """Создает вебсокет для получения данных ликвидаций.
+
+        https://bybit-exchange.github.io/docs/v5/websocket/public/all-liquidation
+
+        Параметры:
+            callback (`CallbackType`): Асинхронная функция обратного вызова для обработки сообщений.
+            category (`Literal["linear", "inverse"]`): Категория рынка (только для деривативов).
+            symbol (`str | None`): Один символ для подписки.
+            symbols (`Sequence[str] | None`): Список символов для мультиплекс‑подключения.
+            req_id (`str | None`): Опциональный идентификатор запроса.
+
+        Возвращает:
+            `Websocket`: Объект для управления вебсокет соединением.
+        """
+        if symbol and symbols:
+            raise ValueError("Parameters symbol and symbols cannot be used together")
+        if not (symbol or symbols):
+            raise ValueError("Either symbol or symbols must be provided")
+
+        tickers = [symbol] if symbol else symbols
+        topics = [f"allLiquidation.{ticker.upper()}" for ticker in tickers]  # type: ignore
+
+        subscription_messages = self._generate_subscription_message(topics, req_id)
+        url = self._get_url_for_category(category)
+
+        return Websocket(
+            callback=callback,
+            url=url,
+            subscription_messages=subscription_messages,
+            **self._ws_kwargs,
+        )

unicex/enums.py

@@ -0,0 +1,273 @@
+"""Модуль, который описывает перечисления."""
+
+__all__ = [
+    "MarketType",
+    "Exchange",
+    "Timeframe",
+    "Side",
+]
+
+from enum import StrEnum
+
+
+class MarketType(StrEnum):
+    """Перечисление типов криптовалютных рынков."""
+
+    FUTURES = "FUTURES"
+    SPOT = "SPOT"
+
+    def __add__(self, exchange: "Exchange") -> tuple["Exchange", "MarketType"]:
+        """Возвращает кортеж из биржи и типа рынка."""
+        return exchange, self
+
+
+class Exchange(StrEnum):
+    """Перечисление бирж."""
+
+    BINANCE = "BINANCE"
+    BITGET = "BITGET"
+    BITUNIX = "BITUNIX"
+    BYBIT = "BYBIT"
+    GATE = "GATE"
+    HYPERLIQUID = "HYPERLIQUID"
+    KCEX = "KCEX"
+    MEXC = "MEXC"
+    OKX = "OKX"
+    XT = "XT"
+
+    def __add__(self, market_type: "MarketType") -> tuple["Exchange", "MarketType"]:
+        """Возвращает кортеж из биржи и типа рынка."""
+        return self, market_type
+
+
+class Side(StrEnum):
+    """Перечисление сторон сделки."""
+
+    BUY = "BUY"
+    SELL = "SELL"
+
+
+class Timeframe(StrEnum):
+    """Перечисление таймфреймов."""
+
+    SECOND_1 = "1s"
+
+    MIN_1 = "1m"
+    MIN_3 = "3m"
+    MIN_5 = "5m"
+    MIN_15 = "15m"
+    MIN_30 = "30m"
+
+    HOUR_1 = "1h"
+    HOUR_2 = "2h"
+    HOUR_4 = "4h"
+    HOUR_6 = "6h"
+    HOUR_8 = "8h"
+    HOUR_12 = "12h"
+
+    DAY_1 = "1d"
+    DAY_3 = "3d"
+
+    WEEK_1 = "1w"
+
+    MONTH_1 = "1M"
+
+    @property
+    def mapping(self) -> dict[Exchange | tuple[Exchange, MarketType], dict["Timeframe", str]]:
+        """Возвращает словарь с маппингом таймфреймов для каждой биржи."""
+        return {
+            (Exchange.BINANCE, MarketType.SPOT): {
+                Timeframe.SECOND_1: "1s",
+                Timeframe.MIN_1: "1m",
+                Timeframe.MIN_3: "3m",
+                Timeframe.MIN_5: "5m",
+                Timeframe.MIN_15: "15m",
+                Timeframe.MIN_30: "30m",
+                Timeframe.HOUR_1: "1h",
+                Timeframe.HOUR_2: "2h",
+                Timeframe.HOUR_4: "4h",
+                Timeframe.HOUR_6: "6h",
+                Timeframe.HOUR_8: "8h",
+                Timeframe.HOUR_12: "12h",
+                Timeframe.DAY_1: "1d",
+                Timeframe.DAY_3: "3d",
+                Timeframe.WEEK_1: "1w",
+                Timeframe.MONTH_1: "1M",
+            },
+            (Exchange.BINANCE, MarketType.FUTURES): {
+                Timeframe.MIN_1: "1m",
+                Timeframe.MIN_3: "3m",
+                Timeframe.MIN_5: "5m",
+                Timeframe.MIN_15: "15m",
+                Timeframe.MIN_30: "30m",
+                Timeframe.HOUR_1: "1h",
+                Timeframe.HOUR_2: "2h",
+                Timeframe.HOUR_4: "4h",
+                Timeframe.HOUR_6: "6h",
+                Timeframe.HOUR_8: "8h",
+                Timeframe.HOUR_12: "12h",
+                Timeframe.DAY_1: "1d",
+                Timeframe.DAY_3: "3d",
+                Timeframe.WEEK_1: "1w",
+                Timeframe.MONTH_1: "1M",
+            },
+            Exchange.BYBIT: {
+                Timeframe.MIN_1: "1",
+                Timeframe.MIN_3: "3",
+                Timeframe.MIN_5: "5",
+                Timeframe.MIN_15: "15",
+                Timeframe.MIN_30: "30",
+                Timeframe.HOUR_1: "60",
+                Timeframe.HOUR_2: "120",
+                Timeframe.HOUR_4: "240",
+                Timeframe.HOUR_6: "360",
+                Timeframe.HOUR_12: "720",
+                Timeframe.DAY_1: "D",
+                Timeframe.WEEK_1: "W",
+                Timeframe.MONTH_1: "M",
+            },
+            (Exchange.BITGET, MarketType.SPOT): {
+                Timeframe.MIN_1: "1min",
+                Timeframe.MIN_5: "5min",
+                Timeframe.MIN_15: "15min",
+                Timeframe.MIN_30: "30min",
+                Timeframe.HOUR_1: "1h",
+                Timeframe.HOUR_4: "4h",
+                Timeframe.HOUR_6: "6h",
+                Timeframe.HOUR_12: "12h",
+                Timeframe.DAY_1: "1day",
+                Timeframe.DAY_3: "3day",
+                Timeframe.WEEK_1: "1week",
+                Timeframe.MONTH_1: "1M",
+            },
+            (Exchange.BITGET, MarketType.FUTURES): {
+                Timeframe.MIN_1: "1m",
+                Timeframe.MIN_5: "5m",
+                Timeframe.MIN_15: "15m",
+                Timeframe.MIN_30: "30m",
+                Timeframe.HOUR_1: "1H",
+                Timeframe.HOUR_4: "4H",
+                Timeframe.HOUR_6: "6H",
+                Timeframe.HOUR_12: "12H",
+                Timeframe.DAY_1: "1D",
+                Timeframe.DAY_3: "3D",
+                Timeframe.WEEK_1: "1W",
+                Timeframe.MONTH_1: "1M",
+            },
+            (Exchange.MEXC, MarketType.SPOT): {
+                Timeframe.MIN_1: "1m",
+                Timeframe.MIN_5: "5m",
+                Timeframe.MIN_15: "15m",
+                Timeframe.MIN_30: "30m",
+                Timeframe.HOUR_1: "60m",
+                Timeframe.HOUR_4: "4h",
+                Timeframe.HOUR_8: "8h",
+                Timeframe.DAY_1: "1d",
+                Timeframe.WEEK_1: "1W",
+                Timeframe.MONTH_1: "1M",
+            },
+            (Exchange.MEXC, MarketType.FUTURES): {
+                Timeframe.MIN_1: "Min1",
+                Timeframe.MIN_5: "Min5",
+                Timeframe.MIN_15: "Min15",
+                Timeframe.MIN_30: "Min30",
+                Timeframe.HOUR_1: "Min60",
+                Timeframe.HOUR_4: "Hour4",
+                Timeframe.HOUR_8: "Hour8",
+                Timeframe.DAY_1: "Day1",
+                Timeframe.WEEK_1: "Week1",
+                Timeframe.MONTH_1: "Month1",
+            },
+            Exchange.OKX: {
+                Timeframe.MIN_1: "1m",
+                Timeframe.MIN_3: "3m",
+                Timeframe.MIN_5: "5m",
+                Timeframe.MIN_15: "15m",
+                Timeframe.MIN_30: "30m",
+                Timeframe.HOUR_1: "1H",
+                Timeframe.HOUR_2: "2H",
+                Timeframe.HOUR_4: "4H",
+                Timeframe.HOUR_6: "6H",
+                Timeframe.HOUR_12: "12H",
+                Timeframe.DAY_1: "1D",
+                Timeframe.DAY_3: "3D",
+                Timeframe.WEEK_1: "1W",
+                Timeframe.MONTH_1: "1M",
+            },
+            (Exchange.GATE, MarketType.FUTURES): {
+                Timeframe.SECOND_1: "1s",
+                Timeframe.MIN_1: "1m",
+                Timeframe.MIN_5: "5m",
+                Timeframe.MIN_15: "15m",
+                Timeframe.MIN_30: "30m",
+                Timeframe.HOUR_1: "1h",
+                Timeframe.HOUR_2: "2h",
+                Timeframe.HOUR_4: "4h",
+                Timeframe.HOUR_6: "6h",
+                Timeframe.HOUR_8: "8h",
+                Timeframe.HOUR_12: "12h",
+                Timeframe.DAY_1: "1d",
+                Timeframe.WEEK_1: "1w",
+                Timeframe.MONTH_1: "30d",
+            },
+            (Exchange.GATE, MarketType.SPOT): {
+                Timeframe.MIN_1: "1m",
+                Timeframe.MIN_5: "5m",
+                Timeframe.MIN_15: "15m",
+                Timeframe.MIN_30: "30m",
+                Timeframe.HOUR_1: "1h",
+                Timeframe.HOUR_4: "4h",
+                Timeframe.HOUR_8: "8h",
+                Timeframe.DAY_1: "1d",
+                Timeframe.WEEK_1: "7d",
+                Timeframe.MONTH_1: "30d",
+            },
+            Exchange.HYPERLIQUID: {
+                Timeframe.MIN_1: "1m",
+                Timeframe.MIN_3: "3m",
+                Timeframe.MIN_5: "5m",
+                Timeframe.MIN_15: "15m",
+                Timeframe.MIN_30: "30m",
+                Timeframe.HOUR_1: "1h",
+                Timeframe.HOUR_2: "2h",
+                Timeframe.HOUR_4: "4h",
+                Timeframe.HOUR_8: "8h",
+                Timeframe.HOUR_12: "12h",
+                Timeframe.DAY_1: "1d",
+                Timeframe.DAY_3: "3d",
+                Timeframe.WEEK_1: "1w",
+                Timeframe.MONTH_1: "1M",
+            },
+        }
+
+    def to_exchange_format(self, exchange: Exchange, market_type: MarketType | None = None) -> str:
+        """Конвертирует таймфрейм в формат, подходящий для указанной биржи."""
+        # Обрабатываем ситуацию, при которой биржа имеет одинаковый маппинг как на споте, так и на фьючерсах:
+        if exchange in self.mapping:
+            key = exchange
+        else:
+            if not market_type:
+                raise ValueError(
+                    f"Market type is required for exchange {exchange.value} to map to timeframe {self.value}"
+                )
+            key = exchange + market_type
+        try:
+            return self.mapping[key][self]  # type: ignore
+        except KeyError as e:
+            details = f" and market type {market_type.value}" if market_type else ""
+            raise ValueError(
+                f"Timeframe {self.value} is not supported for exchange {exchange.value}{details}"
+            ) from e
+
+    @property
+    def to_seconds(self) -> int:
+        """Возвращает количество секунд для таймфрейма."""
+        unit_map = {
+            "m": 60,
+            "h": 3600,
+            "d": 86400,
+            "w": 604800,
+            "M": 2592000,
+        }  # Условно 30 дней в месяце
+        value, unit = int(self.value[:-1]), self.value[-1]
+        return value * unit_map[unit]

unicex/exceptions.py

@@ -0,0 +1,64 @@
+"""Модуль,который описывает исключения и ошибки, которые могут возникнуть при работе с библиотекой."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class UniCexException(Exception):
+    """Базовое исключение библиотеки."""
+
+    message: str
+    """Сообщение об ошибке."""
+
+
+@dataclass
+class NotAuthorized(UniCexException):
+    """Исключение, возникающее при отсутствии авторизации."""
+
+    pass
+
+
+@dataclass
+class NotSupported(UniCexException):
+    """Исключение, возникающее при попытке использования не поддерживаемой функции."""
+
+    pass
+
+
+@dataclass
+class AdapterError(UniCexException):
+    """Исключение, возникающее при ошибке адаптации данных."""
+
+    pass
+
+
+@dataclass
+class QueueOverflowError(UniCexException):
+    """Исключение, возникающее при переполнении очереди сообщений."""
+
+    pass
+
+
+@dataclass
+class ResponseError(UniCexException):
+    """Исключение, возникающее при ошибке ответа."""
+
+    status_code: int
+    code: str = ""  # "" - means undefined
+    response_json: dict = field(default_factory=dict)
+    response_text: str = ""
+
+    def __str__(self) -> str:
+        """Возвращает строковое представление исключения."""
+        if self.response_json:
+            preview = str(self.response_json)
+            if len(preview) > 500:
+                preview = preview[:500] + "..."
+            return f"ResponseError: status_code={self.status_code}, code={self.code}, response_json: {preview}"
+        elif self.response_text:
+            preview = str(self.response_text)
+            if len(preview) > 500:
+                preview = preview[:500] + "..."
+            return f"ResponseError: status_code={self.status_code}, code={self.code}, response_text: {preview}"
+        else:
+            return f"ResponseError: status_code={self.status_code}, code={self.code}"