unicex 0.13.17__py3-none-any.whl

unicex/types.py

@@ -0,0 +1,164 @@
+"""Модуль, который предоставляет типы данных для работы с библиотекой."""
+
+__all__ = [
+    "TickerDailyDict",
+    "TickerDailyItem",
+    "KlineDict",
+    "TradeDict",
+    "AggTradeDict",
+    "RequestMethod",
+    "LoggerLike",
+    "OpenInterestDict",
+    "OpenInterestItem",
+    "TickerInfoItem",
+    "TickersInfoDict",
+    "LiquidationDict",
+]
+
+from logging import Logger as LoggingLogger
+from typing import Literal, TypedDict
+
+import loguru
+
+type LoggerLike = LoggingLogger | loguru.Logger
+"""Объединение логгеров: loguru._logger.Logger или logging.Logger."""
+
+type RequestMethod = Literal["GET", "POST", "PUT", "DELETE", "PATCH"]
+"""Типы методов HTTP запросов."""
+
+
+class TickerDailyItem(TypedDict):
+    """Статистика одного тикера за последние 24 часа."""
+
+    p: float
+    """Изменение цены за 24 ч."""
+
+    v: float
+    """Объем торгов за 24 ч. в монетах."""
+
+    q: float
+    """Объем торгов за 24 ч. в долларах."""
+
+
+type TickerDailyDict = dict[str, TickerDailyItem]
+"""Статистика тикеров за последние 24 часа."""
+
+
+class KlineDict(TypedDict):
+    """Модель свечи."""
+
+    s: str
+    """Символ."""
+
+    t: int
+    """Время открытия. В миллисекундах."""
+
+    o: float
+    """Цена открытия свечи."""
+
+    h: float
+    """Верхняя точка свечи."""
+
+    l: float  # noqa
+    """Нижняя точка свечи."""
+
+    c: float
+    """Цена закрытия свечи."""
+
+    v: float
+    """Объем свечи. В монетах."""
+
+    q: float
+    """Объем свечи. В долларах."""
+
+    T: int | None
+    """Время закрытия. В миллисекундах."""
+
+    x: bool | None
+    """Флаг закрыта ли свеча."""
+
+
+class TradeDict(TypedDict):
+    """Модель сделки."""
+
+    t: int
+    """Время сделки. В миллисекундах."""
+
+    s: str
+    """Символ."""
+
+    S: Literal["BUY", "SELL"]
+    """Направление сделки."""
+
+    p: float
+    """Цена сделки."""
+
+    v: float
+    """Объем сделки. В монетах."""
+
+
+class AggTradeDict(TradeDict):
+    """Модель агрегированной сделки."""
+
+    pass
+
+
+class OpenInterestItem(TypedDict):
+    """Модель одного элемента открытого интереса."""
+
+    t: int
+    """Время. В миллисекундах."""
+
+    v: float
+    """Открытый интерес. В монетах."""
+
+
+type OpenInterestDict = dict[str, OpenInterestItem]
+"""Модель открытого интереса."""
+
+
+class LiquidationDict(TypedDict):
+    """Модель ликвидации."""
+
+    t: int
+    """Время. В миллисекундах."""
+
+    s: str
+    """Символ."""
+
+    S: Literal["BUY", "SELL"]
+    """Сторона."""
+
+    v: float
+    """Объем ликвидации. В монетах."""
+
+    p: float
+    """Цена ликвидации."""
+
+
+class TickerInfoItem(TypedDict):
+    """Информация о размерах тиков, ступеней цены и множителя контракта (если есть) для тикера.
+
+    На некоторых биржах удобнее делать округление через precisions, на некоторых через step,
+    потому что иногда встречаются шаги, которые не являются степенью 10. Поэтому обязательно
+    должны быть определены tick_precision ИЛИ tick_step, а так же size_precision ИЛИ size_step.
+    """
+
+    tick_precision: int | None
+    """Количество знаков после запятой для цены."""
+
+    tick_step: float | None
+    """Шаг одного деления для цены."""
+
+    size_precision: int | None
+    """Количество знаков после запятой для объема."""
+
+    size_step: float | None
+    """Шаг одного деления для объема."""
+
+    contract_size: float | None
+    """Множитель контракта (если есть)."""
+
+
+type TickersInfoDict = dict[str, TickerInfoItem]
+"""Информация о размерах тиков, ступеней цены и множителя контракта (если есть) для всех тикеров."""

unicex/utils.py

@@ -0,0 +1,218 @@
+"""Модуль, который предоставляет дополнительные функции, которые нужны для внутренного использования в библиотеке."""
+
+__all__ = [
+    "dict_to_query_string",
+    "generate_hmac_sha256_signature",
+    "sort_params_by_alphabetical_order",
+    "filter_params",
+    "batched_list",
+    "catch_adapter_errors",
+    "decorate_all_methods",
+    "symbol_to_exchange_format",
+]
+
+import base64
+import hashlib
+import hmac
+import json
+from collections.abc import Callable, Iterable
+from functools import wraps
+from typing import Any, Literal
+from urllib.parse import urlencode
+
+from unicex.enums import Exchange, MarketType
+from unicex.exceptions import AdapterError
+
+
+def filter_params(params: dict) -> dict:
+    """Фильтрует параметры запроса, удаляя None-значения.
+
+    Параметры:
+        params (`dict`): Словарь параметров запроса.
+
+    Возвращает:
+        `dict`: Отфильтрованный словарь параметров запроса.
+    """
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def sort_params_by_alphabetical_order(params: dict) -> dict:
+    """Сортирует параметры запроса по алфавиту.
+
+    Параметры:
+        params (`dict`): Словарь параметров запроса.
+
+    Возвращает:
+        `dict`: Отсортированный словарь параметров запроса.
+    """
+    return dict(sorted(params.items()))
+
+
+def dict_to_query_string(params: dict) -> str:
+    """Преобразует словарь параметров в query string для URL.
+
+    - Списки и словари автоматически сериализуются в JSON.
+    - Используется стандартная urlencode кодировка.
+
+    Параметры:
+        params (`dict`): Словарь параметров запроса.
+
+    Возвращает:
+        `str`: Строка параметров, готовая для использования в URL.
+    """
+    processed = {
+        k: json.dumps(v, separators=(",", ":")) if isinstance(v, list | dict) else v
+        for k, v in params.items()
+    }
+    return urlencode(processed, doseq=True)
+
+
+def generate_hmac_sha256_signature(
+    secret_key: str,
+    payload: str,
+    encoding: Literal["hex", "base64"] = "hex",
+) -> str:
+    """Генерирует HMAC-SHA256 подпись.
+
+    encoding:
+        - "hex" → шестнадцатеричная строка
+        - "base64" → base64-строка
+    """
+    digest = hmac.new(secret_key.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).digest()
+    if encoding == "hex":
+        return digest.hex()
+    elif encoding == "base64":
+        return base64.b64encode(digest).decode()
+    else:
+        raise ValueError("encoding must be 'hex' or 'base64'")
+
+
+def batched_list[T](iterable: Iterable[T], n: int) -> list[list[T]]:
+    """Разбивает последовательность на чанки фиксированного размера.
+
+    Всегда возвращает список списков (list[list[T]]).
+    """
+    if n <= 0:
+        raise ValueError("n must be greater than 0")
+
+    result: list[list[T]] = []
+    batch: list[T] = []
+    for item in iterable:
+        batch.append(item)
+        if len(batch) == n:
+            result.append(batch)
+            batch = []
+    if batch:
+        result.append(batch)
+    return result
+
+
+def catch_adapter_errors(func: Callable):
+    """Декоратор для унификации обработки ошибок в адаптерах.
+
+    Перехватывает все исключения внутри функции и выбрасывает AdapterError
+    с подробным сообщением, включающим тип и текст исходного исключения,
+    а также имя функции.
+
+    Параметры:
+        func (Callable): Декорируемая функция.
+
+    Возвращает:
+        Callable: Обёрнутую функцию, выбрасывающую AdapterError при ошибке.
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            args_repr = repr(args)
+            if len(args_repr) > 400:
+                args_preview = args_repr[:400] + "... (truncated)"
+            else:
+                args_preview = args_repr
+
+            kwargs_repr = repr(kwargs)
+            if len(kwargs_repr) > 400:
+                kwargs_preview = kwargs_repr[:400] + "... (truncated)"
+            else:
+                kwargs_preview = kwargs_repr
+
+            raise AdapterError(
+                f"({type(e).__name__}): {e}. Can not convert input (args={args_preview}, kwargs={kwargs_preview}) in function `{func.__name__}`."
+            ) from None
+
+    return wrapper
+
+
+def decorate_all_methods(decorator: Callable[[Callable[..., Any]], Callable[..., Any]]) -> Callable:
+    """Класс-декоратор, который оборачивает все методы класса указанным декоратором.
+
+    Декоратор применяется только к методам/функциям, не начинающимся с "__".
+
+    Парамтеры:
+        decorator: Декоратор, который нужно применить ко всем методам.
+
+    Возвращает:
+        Callable: Декоратор для классов.
+
+    Пример:
+        >>> def debug(func):
+        ...     def wrapper(*args, **kwargs):
+        ...         print(f"Call {func.__name__}")
+        ...         return func(*args, **kwargs)
+        ...
+        ...     return wrapper
+        >>> @decorate_all_methods(debug)
+        ... class Test:
+        ...     def hello(self):
+        ...         return "hi"
+        >>> Test().hello()
+        Call hello
+        'hi'
+
+    """
+
+    def wrapper(cls: type) -> type:
+        for k, v in cls.__dict__.items():
+            if isinstance(v, staticmethod):
+                func = v.__func__
+                setattr(cls, k, staticmethod(decorator(func)))
+            elif isinstance(v, classmethod):
+                func = v.__func__
+                setattr(cls, k, classmethod(decorator(func)))
+            elif callable(v) and not k.startswith("__"):
+                setattr(cls, k, decorator(v))
+        return cls
+
+    return wrapper
+
+
+def symbol_to_exchange_format(
+    symbol: str, exchange: Exchange, market_type: MarketType | None = None
+) -> str:
+    """Преобразует символ в формат, который используется на бирже.
+
+    Параметры:
+        symbol (str): Символ, обязательно в формате 'BTCUSDT' или 'btcusdt'.
+
+    Возвращает:
+        str: Символ в формате, который используется на бирже, заглавными буквами.
+    """
+    symbol_upper = symbol.upper()
+    if exchange == Exchange.MEXC:
+        if market_type == MarketType.FUTURES:
+            return symbol_upper.replace("USDT", "_USDT")
+    elif exchange == Exchange.OKX:
+        if market_type == MarketType.FUTURES:
+            return symbol_upper.replace("USDT", "-USDT-SWAP")
+        elif market_type == MarketType.SPOT:
+            return symbol_upper.replace("USDT", "-USDT")
+    elif exchange == Exchange.GATE:
+        return symbol_upper.replace("USDT", "_USDT")
+    elif exchange == Exchange.HYPERLIQUID:
+        if market_type == MarketType.FUTURES:
+            return symbol.removesuffix("USDT")  # Вот тут мб и не так, там вроде что-то к USDC
+        else:
+            return symbol.removesuffix("USDT")  # Вот тут мб и не так, там вроде что-то к USDC
+    return symbol_upper

unicex-0.13.17.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: unicex
+Version: 0.13.17
+Summary: Unified Crypto Exchange API 
+Author-email: LoveBloodAndDiamonds <ayazshakirzyanov27@gmail.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2025, LoveBloodAndDiamonds
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Github, https://github.com/LoveBloodAndDiamonds/uni-cex-api
+Project-URL: Author, https://t.me/LoveBloodAndDiamonds
+Project-URL: Readthedocs, https://unicex.readthedocs.io/ru/latest/
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.12.15
+Requires-Dist: eth-account>=0.13.7
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: msgpack>=1.1.1
+Requires-Dist: orjson>=3.11.3
+Requires-Dist: protobuf>=6.32.1
+Requires-Dist: websockets>=15.0.1
+Dynamic: license-file
+
+# Unified Crypto Exchange API
+
+`unicex` — асинхронная библиотека для работы с криптовалютными биржами, реализующая унифицированный интерфейс поверх «сырых» REST и WebSocket API разных бирж. Поддерживает спотовый и USDT-фьючерсный рынки.
+
+## ✅ Статус реализации
+
+| Exchange        | Client | Auth | WS Manager | User WS | Uni Client | Uni WS Manager | ExchangeInfo |
+|-----------------|--------|------|------------|---------|------------|----------------|--------------|
+| **Binance**     | ✓      | ✓    | ✓          | ✓       | ✓          | ✓              | ✓            |
+| **Bitget**      | ✓      | ✓    | ✓          |         | ✓          |                | ✓            |
+| **Bybit**       | ✓      | ✓    | ✓          |         | ✓          | ✓              | ✓            |
+| **Gateio**      | ✓      | ✓    | ✓          |         | ✓          |                | ✓            |
+| **Hyperliquid** | ✓      | ✓    | ✓          | ✓       | ✓          |                |              |
+| **Mexc**        | ✓      | ✓    | ✓          |         | ✓          |                | ✓            |
+| **Okx**         | ✓      | ✓    | ✓          |         | ✓          |                | ✓            |
+---
+
+
+### 📖 Описание колонок
+
+- **Client** – Обертки над HTTP методами следующих разделов: market, order, position, account.
+- **Auth** – Поддержка авторизации и приватных эндпоинтов.
+- **WS Manager** – Обертки над вебсокетами биржи.
+- **User WS** – Поддержка пользовательских вебсокетов.
+- **UniClient** –Унифированный клиент.
+- **UniWebsocketManager** – Унифированный менеджер вебсокетов.
+- **ExchangeInfo** - Информация о бирже для округления цен и объемов
+---
+
+## 🚀 Быстрый старт
+
+- Установка: `pip install unicex` или из исходников: `pip install -e .`
+- Библиотека полностью асинхронная. Примеры импорта:
+  - Сырые клиенты: `from unicex.binance import Client`
+  - Унифицированные клиенты: `from unicex.binance import UniClient`
+  - Вебсокет менеджеры: `from unicex.binance import WebsocketManager, UniWebsocketManager`
+
+### Пример: Получение рыночных данных через API
+
+```python
+import asyncio
+
+from unicex import Exchange, Timeframe, get_uni_client
+
+# Выбираем биржу, с которой хотим работать.
+# Поддерживаются: Binance, Bybit, Bitget, Mexc, Gateio, Hyperliquid и другие.
+exchange = Exchange.BYBIT
+
+
+async def main() -> None:
+    """Пример простого использования унифицированного клиента unicex."""
+    # 1️⃣ Создаём клиент для выбранной биржи
+    client = await get_uni_client(exchange).create()
+
+    # 2️⃣ Получаем открытый интерес по всем контрактам
+    open_interest = await client.open_interest()
+    print(open_interest)
+
+    # Пример вывода:
+    # {
+    #   "BTCUSDT": {"t": 1759669833728, "v": 61099320.0},
+    #   "ETHUSDT": {"t": 1759669833728, "v": 16302340.0},
+    #   "SOLUSDT": {"t": 1759669833728, "v": 3427780.0},
+    #   ...
+    # }
+
+    # 3️⃣ Можно точно так же получать другие данные в едином формате:
+    await client.tickers()  # список всех тикеров
+    await client.futures_tickers()  # тикеры фьючерсов
+    await client.ticker_24hr()  # статистика за 24 часа (spot)
+    await client.futures_ticker_24hr()  # статистика за 24 часа (futures)
+    await client.klines("BTCUSDT", Timeframe.MIN_5)  # свечи спота
+    await client.futures_klines("BTCUSDT", Timeframe.HOUR_1)  # свечи фьючерсов
+    await client.funding_rate()  # ставка финансирования
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+### Пример: Получение данных в реальном времени через Websocket API
+
+```python
+import asyncio
+from unicex import Exchange, TradeDict, get_uni_websocket_manager
+from unicex.enums import Timeframe
+
+# Выбираем биржу, с которой хотим работать.
+# Поддерживаются: Binance, Bybit, Bitget, Mexc, Gateio, Hyperliquid и другие.
+exchange = Exchange.BITGET
+
+
+async def main() -> None:
+    """Пример простого использования унифицированного менеджера Websocket от UniCEX."""
+
+    # 1️⃣ Создаём WebSocket-менеджер для выбранной биржи
+    ws_manager = get_uni_websocket_manager(exchange)()
+
+    # 2️⃣ Подключаемся к потоку сделок (aggTrades)
+    aggtrades_ws = ws_manager.aggtrades(
+        callback=callback,
+        symbols=["BTCUSDT", "ETHUSDT"],
+    )
+
+    # Запускаем получение данных
+    await aggtrades_ws.start()
+
+    # 3️⃣ Примеры других типов потоков:
+    futures_aggtrades_ws = ws_manager.futures_aggtrades(
+        callback=callback,
+        symbols=["BTCUSDT", "ETHUSDT"],
+    )
+
+    klines_ws = ws_manager.klines(
+        callback=callback,
+        symbols=["BTCUSDT", "ETHUSDT"],
+        timeframe=Timeframe.MIN_5,
+    )
+
+    futures_klines_ws = ws_manager.futures_klines(
+        callback=callback,
+        symbols=["BTCUSDT", "ETHUSDT"],
+        timeframe=Timeframe.MIN_1,
+    )
+
+    # 💡 Также у каждой биржи есть свой WebsocketManager:
+    #     unicex.<exchange>.websocket_manager.WebsocketManager
+    # В нём реализованы остальные методы для работы с WS API.
+
+
+async def callback(trade: TradeDict) -> None:
+    """Обработка входящих данных из Websocket."""
+    print(trade)
+    # Пример вывода:
+    # {'t': 1759670527594, 's': 'BTCUSDT', 'S': 'BUY',  'p': 123238.87, 'v': 0.05}
+    # {'t': 1759670527594, 's': 'BTCUSDT', 'S': 'BUY',  'p': 123238.87, 'v': 0.04}
+    # {'t': 1759670346828, 's': 'ETHUSDT', 'S': 'SELL', 'p': 4535.0,    'v': 0.0044}
+    # {'t': 1759670347087, 's': 'ETHUSDT', 'S': 'BUY',  'p': 4534.91,   'v': 0.2712}
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+
+### Пример: Округление цен используя фоновый класс ExchangeInfo
+
+
+```python
+import asyncio
+from unicex import start_exchanges_info, get_exchange_info, Exchange
+
+
+async def main() -> None:
+    # ⏳ Запускаем фоновые процессы, которые собирают рыночные параметры всех бирж:
+    #  - количество знаков после точки для цены и объема
+    #  - множители контрактов для фьючерсов
+    await start_exchanges_info()
+
+    # Небольшая пауза, чтобы данные успели подгрузиться
+    await asyncio.sleep(1)
+
+    # 1️⃣ Пример 1: Округление цены для фьючерсов OKX
+    okx_exchange_info = get_exchange_info(Exchange.OKX)
+    okx_rounded_price = okx_exchange_info.round_futures_price("BTC-USDT-SWAP", 123456.1234567890)
+    print(okx_rounded_price)  # >> 123456.1
+
+    # 2️⃣ Пример 2: Округление объема для спота Binance
+    binance_exchange_info = get_exchange_info(Exchange.BINANCE)
+    binance_rounded_quantity = binance_exchange_info.round_quantity("BTCUSDT", 1.123456789)
+    print(binance_rounded_quantity)  # >> 1.12345
+
+    # 3️⃣ Пример 3: Получение множителя контракта (например, Mexc Futures)
+    mexc_exchange_info = get_exchange_info(Exchange.MEXC)
+    mexc_contract_multiplier = mexc_exchange_info.get_futures_ticker_info("BTC_USDT")["contract_size"]
+    print(mexc_contract_multiplier)  # >> 0.0001
+
+    # 4️⃣ Пример 4: Реальное применение — вычисляем тейк-профит вручную
+    # Допустим, позиция открыта по 123123.1 USDT, хотим +3.5% тейк-профит:
+    take_profit_raw = 123123.1 * 1.035
+    print("До округления:", take_profit_raw)  # >> 127432.40849999999
+
+    # Биржа требует цену в допустимом формате — округляем:
+    take_profit = okx_exchange_info.round_futures_price("BTC-USDT-SWAP", take_profit_raw)
+    print("После округления:", take_profit)  # >> 127432.4
+
+    # Теперь это число можно безопасно передать в API без ошибок:
+    # await client.create_order(symbol="BTC-USDT-SWAP", price=take_profit, ...)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```