binance-common 1.0.0__py3-none-any.whl

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0 - 2025-xx-xx
+
+First release

README.md

@@ -0,0 +1,36 @@
+# Binance Common Types and Utilities for Binance Connectors
+
+[![Code Style: Black](https://img.shields.io/badge/code_style-black-black)](https://black.readthedocs.io/en/stable/)
+[![PyPI version](https://img.shields.io/pypi/v/binance-common)](https://pypi.python.org/pypi/binance-common)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/binance-common.svg)](https://pypi.org/project/binance-common/)
+[![Python version](https://img.shields.io/pypi/pyversions/binance-connector)](https://www.python.org/downloads/)
+[![Known Vulnerabilities](https://img.shields.io/badge/security-scanned-brightgreen)](https://github.com/binance/binance-connector-python/security)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`binance-common` is a **utility package** for Binance modular connectors, providing commonly used functions and helpers for working with Binance REST/WebSocket APIs. It ensures reusable and optimized utilities to streamline development.
+
+## Installation
+
+To use this library, ensure your environment is running Python version **3.9** or later.
+
+```bash
+pip install binance-common
+```
+
+## Features
+
+- **Common Utility Functions** for API requests, timestamps, and signatures.
+- **Optimized for Binance Connectors** to ensure seamless integration.
+- **Lightweight & Tree-Shakeable** – only imports what you need.
+
+## Contributing
+
+Contributions are welcome!
+
+1. Open a GitHub issue before making changes.
+2. Discuss proposed changes with maintainers.
+3. Follow the existing TypeScript structure.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENCE) file for details.

binance_common/configuration.py

@@ -0,0 +1,190 @@
+import ssl
+
+from typing import Optional, Dict, Union
+from http.client import HTTPSConnection
+
+from binance_common.constants import TimeUnit, WebsocketMode
+
+
+class ConfigurationRestAPI:
+    """
+    Configuration for the Binance REST API client.
+
+    Supports:
+    - API authentication
+    - Keep-Alive
+    - Timeout handling
+    - Compression (gzip, deflate, br)
+    - HTTPS Agent
+    - Time Unit
+    - Proxy support
+    - Retries & Backoff
+    """
+
+    def __init__(
+        self,
+        api_key: str = None,
+        api_secret: Optional[str] = None,
+        base_path: str = None,
+        timeout: int = 1000,
+        proxy: Optional[Dict[str, Union[str, int, Dict[str, str]]]] = None,
+        keep_alive: bool = True,
+        compression: bool = True,
+        retries: int = 3,
+        backoff: int = 1000,
+        https_agent: Optional[Union[bool, HTTPSConnection]] = None,
+        time_unit: Optional[str] = None,
+        private_key: Optional[Union[bytes, str]] = None,
+        private_key_passphrase: Optional[str] = None,
+    ):
+        """
+        Initialize the API configuration.
+
+        Args:
+            api_key (str): API key for authentication.
+            api_secret (Optional[str]): API secret for authentication (default: None).
+            base_path (str): Base API URL (default: None).
+            timeout (int): Request timeout in milliseconds (default: 1000).
+            proxy (Optional[Dict[str, Union[str, int, Dict[str, str]]]]): Proxy settings (default: None).
+            keep_alive (bool): Enable Keep-Alive (default: True).
+            compression (bool): Enable response compression (default: True).
+            retries (int): Number of retry attempts for failed requests (default: 3).
+            backoff (int): Delay (ms) between retries (default: 1000).
+            https_agent (Optional[Union[bool, HTTPSConnection]]): Custom HTTPS Agent (default: None).
+            time_unit (Optional[str]): Time unit for time-based responses (default: None).
+            private_key (Optional[Union[bytes, str]]): Private key for authentication (default: None).
+            private_key_passphrase (Optional[str]): Passphrase for private key (default: None).
+        """
+
+        self.api_key = api_key
+        self.api_secret = api_secret
+        self.base_path = base_path
+        self.timeout = timeout
+        self.proxy = proxy
+        self.keep_alive = keep_alive
+        self.compression = compression
+        self.retries = retries
+        self.backoff = backoff
+        self.https_agent = https_agent
+        self.time_unit = time_unit
+        self.private_key = private_key
+        self.private_key_passphrase = private_key_passphrase
+
+        self.base_headers = {
+            "Accept": "application/json",
+            "X-MBX-APIKEY": str(self.api_key) if self.api_key else "",
+        }
+
+
+class ConfigurationWebSocketAPI:
+    """
+    Configuration for the Binance Websocket API client.
+
+    Supports:
+    - API authentication
+    - Keep-Alive
+    - Timeout handling
+    - Compression (gzip, deflate, br)
+    - HTTPS Agent
+    - WebSocket Pool
+    - Time Unit
+    - Proxy support
+    """
+
+    def __init__(
+        self,
+        api_key: str = None,
+        api_secret: Optional[str] = None,
+        private_key: Optional[Union[bytes, str]] = None,
+        private_key_passphrase: Optional[str] = None,
+        stream_url: str = "wss://ws-api.binance.com/ws-api/v3",
+        timeout: int = 5,
+        reconnect_delay: int = 5,
+        compression: int = 0,
+        proxy: Optional[Dict[str, Union[str, int, Dict[str, str]]]] = None,
+        mode: WebsocketMode = WebsocketMode.SINGLE,
+        pool_size: int = 2,
+        time_unit: TimeUnit = None,
+        https_agent: Optional[ssl.SSLContext] = None,
+    ):
+        """
+        Initialize the API configuration.
+
+        Args:
+            api_key (str): API key for authentication.
+            api_secret (Optional[str]): API secret for authentication (default: None).
+            private_key (Optional[Union[bytes, str]]): Private key for authentication (default: None).
+            private_key_passphrase (Optional[str]): Passphrase for private key (default: None).
+            stream_url (str): Base WebSocket API URL (default: "wss://ws-api.binance.com/ws-api/v3").
+            timeout (int): Request timeout in milliseconds (default: 5000).
+            reconnect_delay (int): Delay (ms) between reconnections (default: 5000).
+            compression (int): Compression level (default: 0).
+            proxy (Optional[Dict[str, Union[str, int, Dict[str, str]]]]): Proxy settings (default: None).
+            mode (WebsocketMode): WebSocket mode ("single" or "pool") (default: "single").
+            pool_size (int): Number of WebSocket connections in pool (default: 2).
+            time_unit (Optional[TimeUnit]): Time unit for time-based responses (default: None).
+            https_agent (Optional[ssl.SSLContext]): Custom HTTPS Agent (default: None).
+        """
+
+        self.api_key = api_key
+        self.api_secret = api_secret
+        self.private_key = private_key
+        self.private_key_passphrase = private_key_passphrase
+        self.stream_url = stream_url
+        self.timeout = timeout
+        self.reconnect_delay = reconnect_delay
+        self.compression = compression
+        self.proxy = proxy
+        self.mode = mode
+        self.pool_size = pool_size
+        self.time_unit = time_unit
+        self.https_agent = https_agent
+        self.user_agent = ""
+
+
+class ConfigurationWebSocketStreams:
+    """
+    Configuration for the Binance Websocket Stream client.
+
+    Supports:
+    - Keep-Alive
+    - Compression (gzip, deflate, br)
+    - HTTPS Agent
+    - WebSocket Pool
+    - Time Unit
+    """
+
+    def __init__(
+        self,
+        stream_url: str = "wss://stream.binance.com:9443/stream",
+        reconnect_delay: int = 5,
+        compression: int = 0,
+        proxy: Optional[Dict[str, Union[str, int, Dict[str, str]]]] = None,
+        mode: WebsocketMode = WebsocketMode.SINGLE,
+        pool_size: int = 2,
+        time_unit: TimeUnit = None,
+        https_agent: Optional[ssl.SSLContext] = None,
+    ):
+        """
+        Initialize the Websocket Stream configuration.
+
+        Args:
+            stream_url (str): Base WebSocket Stream URL (default: "wss://stream.binance.com:9443").
+            reconnect_delay (int): Delay (ms) between reconnections (default: 5000).
+            compression (int): Compression level (default: 0).
+            proxy (Optional[Dict[str, Union[str, int, Dict[str, str]]]]): Proxy settings (default: None).
+            mode (WebsocketMode): WebSocket mode ("single" or "pool") (default: "single").
+            pool_size (int): Number of WebSocket connections in pool (default: 2).
+            time_unit (Optional[TimeUnit]): Time unit for time-based responses (default: None).
+            https_agent (Optional[ssl.SSLContext]): Custom HTTPS Agent (default: None).
+        """
+
+        self.stream_url = stream_url
+        self.reconnect_delay = reconnect_delay
+        self.compression = compression
+        self.proxy = proxy
+        self.mode = mode
+        self.pool_size = pool_size
+        self.time_unit = time_unit
+        self.https_agent = https_agent
+        self.user_agent = ""

binance_common/constants.py

@@ -0,0 +1,115 @@
+from enum import Enum
+
+
+# TimeUnit Constants
+class TimeUnit(Enum):
+    MILLISECOND = "MILLISECOND"
+    millisecond = "millisecond"
+    MICROSECOND = "MICROSECOND"
+    microsecond = "microsecond"
+
+class WebsocketMode(Enum):
+    SINGLE = "single"
+    POOL = "pool"
+
+# Algo constants
+ALGO_REST_API_PROD_URL = "https://api.binance.com"
+
+# Auto Invest constants
+AUTO_INVEST_REST_API_PROD_URL = "https://api.binance.com"
+
+# C2C constants
+C2C_REST_API_PROD_URL = "https://api.binance.com"
+
+# Convert constants
+CONVERT_REST_API_PROD_URL = "https://api.binance.com"
+
+# Copy Trading constants
+COPY_TRADING_REST_API_PROD_URL = "https://api.binance.com"
+
+# Crypto Loan constants
+CRYPTO_LOAN_REST_API_PROD_URL = "https://api.binance.com"
+
+# Derivatives Trading constants
+DERIVATIVES_TRADING_REST_API_PROD_URL = "https://api.binance.com"
+
+# Derivatives Trading (COIN-M Futures) constants
+DERIVATIVES_TRADING_COIN_FUTURES_REST_API_PROD_URL = "https://dapi.binance.com"
+DERIVATIVES_TRADING_COIN_FUTURES_REST_API_TESTNET_URL = "https://testnet.binancefuture.com"
+DERIVATIVES_TRADING_COIN_FUTURES_WS_API_PROD_URL = "wss://ws-dapi.binance.com/ws-dapi/v1"
+DERIVATIVES_TRADING_COIN_FUTURES_WS_API_TESTNET_URL = "wss://testnet.binancefuture.com/ws-dapi/v1"
+DERIVATIVES_TRADING_COIN_FUTURES_WS_STREAMS_PROD_URL = "wss://dstream.binance.com"
+DERIVATIVES_TRADING_COIN_FUTURES_WS_STREAMS_TESTNET_URL = "wss://dstream.binancefuture.com"
+
+# Derivatives Trading (USDS Futures) constants
+DERIVATIVES_TRADING_USDS_FUTURES_REST_API_PROD_URL = "https://fapi.binance.com"
+DERIVATIVES_TRADING_USDS_FUTURES_REST_API_TESTNET_URL = "https://testnet.binancefuture.com"
+DERIVATIVES_TRADING_USDS_FUTURES_WS_API_PROD_URL = "wss://ws-fapi.binance.com/ws-fapi/v1"
+DERIVATIVES_TRADING_USDS_FUTURES_WS_API_TESTNET_URL = "wss://testnet.binancefuture.com/ws-fapi/v1"
+DERIVATIVES_TRADING_USDS_FUTURES_WS_STREAMS_PROD_URL = "wss://fstream.binance.com"
+DERIVATIVES_TRADING_USDS_FUTURES_WS_STREAMS_TESTNET_URL = "wss://stream.binancefuture.com"
+
+# Derivatives Trading (Options) constants
+DERIVATIVES_TRADING_OPTIONS_REST_API_PROD_URL = "https://eapi.binance.com"
+DERIVATIVES_TRADING_OPTIONS_WS_STREAMS_PROD_URL = "wss://nbstream.binance.com/eoptions"
+
+# Derivatives Trading (Portfolio Margin) constants
+DERIVATIVES_TRADING_PORTFOLIO_MARGIN_REST_API_PROD_URL = "https://papi.binance.com"
+DERIVATIVES_TRADING_PORTFOLIO_MARGIN_REST_API_TESTNET_URL = "https://testnet.binancefuture.com"
+DERIVATIVES_TRADING_PORTFOLIO_MARGIN_WS_STREAMS_PROD_URL = "wss://fstream.binance.com/pm"
+DERIVATIVES_TRADING_PORTFOLIO_MARGIN_WS_STREAMS_TESTNET_URL = "wss://fstream.binancefuture.com/pm"
+
+# Derivatives Trading (Portfolio Margin Pro) constants
+DERIVATIVES_TRADING_PORTFOLIO_MARGIN_PRO_REST_API_PROD_URL = "https://api.binance.com"
+DERIVATIVES_TRADING_PORTFOLIO_MARGIN_PRO_WS_STREAMS_PROD_URL = "wss://fstream.binance.com/pm-classic"
+
+# Dual Investment constants
+DUAL_INVESTMENT_REST_API_PROD_URL = "https://api.binance.com"
+
+# Fiat constants
+FIAT_REST_API_PROD_URL = "https://api.binance.com"
+
+# Gift Card constants
+GIFT_CARD_REST_API_PROD_URL = "https://api.binance.com"
+
+# Margin Trading constants
+MARGIN_TRADING_REST_API_PROD_URL = "https://api.binance.com"
+MARGIN_TRADING_WS_STREAMS_PROD_URL = "wss://stream.binance.com:9443"
+MARGIN_TRADING_RISK_WS_STREAMS_PROD_URL = "wss://margin-stream.binance.com"
+
+# Mining constants
+MINING_REST_API_PROD_URL = "https://api.binance.com"
+
+# NFT constants
+NFT_REST_API_PROD_URL = "https://api.binance.com"
+
+# Pay constants
+PAY_REST_API_PROD_URL = "https://api.binance.com"
+
+# Rebate constants
+REBATE_REST_API_PROD_URL = "https://api.binance.com"
+
+# Simple Earn constants
+SIMPLE_EARN_REST_API_PROD_URL = "https://api.binance.com"
+
+# Spot Constants
+SPOT_REST_API_PROD_URL = "https://api.binance.com"
+SPOT_REST_API_TESTNET_URL = "https://testnet.binance.vision"
+SPOT_WS_API_PROD_URL = "wss://ws-api.binance.com:443/ws-api/v3"
+SPOT_WS_API_TESTNET_URL = "wss://ws-api.testnet.binance.vision/ws-api/v3"
+SPOT_WS_STREAMS_PROD_URL = "wss://stream.binance.com:9443"
+SPOT_WS_STREAMS_TESTNET_URL = "wss://stream.testnet.binance.vision"
+SPOT_REST_API_MARKET_URL = "https://data-api.binance.vision"
+SPOT_WS_STREAMS_MARKET_URL = "wss://data-stream.binance.vision"
+
+# Staking constants
+STAKING_REST_API_PROD_URL = "https://api.binance.com"
+
+# Sub Account constants
+SUB_ACCOUNT_REST_API_PROD_URL = "https://api.binance.com"
+
+# VIP Loan constants
+VIP_LOAN_REST_API_PROD_URL = "https://api.binance.com"
+
+# Wallet constants
+WALLET_REST_API_PROD_URL = "https://api.binance.com"

binance_common/errors.py

@@ -0,0 +1,104 @@
+from typing import Optional
+
+
+class Error(Exception):
+    pass
+
+
+class ClientError(Error):
+    """Represents an error that occurred in the Connector client."""
+
+    def __init__(self, error_message: Optional[str] = None):
+        self.error_message = error_message or "An unexpected error occurred."
+        super().__init__(error_message)
+
+
+class RequiredError(Error):
+    """Represents an error when a required parameter is missing or undefined."""
+
+    def __init__(self, field: str, error_message: Optional[str] = None):
+        self.error_message = (
+            error_message or f"Required parameter {field} was null or undefined."
+        )
+        self.field = field
+        super().__init__(error_message)
+
+
+class UnauthorizedError(Error):
+    """Represents an error when a client is unauthorized to access a resource."""
+
+    def __init__(self, error_message: Optional[str] = None):
+        self.error_message = (
+            error_message or "Unauthorized access. Authentication required."
+        )
+        super().__init__(error_message)
+
+
+class ForbiddenError(Error):
+    """Represents an error when access to the resource is forbidden."""
+
+    def __init__(self, error_message: Optional[str] = None):
+        self.error_message = (
+            error_message or "Access to the requested resource is forbidden."
+        )
+        super().__init__(error_message)
+
+
+class TooManyRequestsError(Error):
+    """Represents an error when the client is doing too many requests."""
+
+    def __init__(self, error_message: Optional[str] = None):
+        self.error_message = (
+            error_message or "Too many requests. You are being rate-limited."
+        )
+        super().__init__(error_message)
+
+
+class RateLimitBanError(Error):
+    """Represents an error when the client's IP has been banned for exceeding rate
+    limits."""
+
+    def __init__(self, error_message: Optional[str] = None):
+        self.error_message = (
+            error_message or "The IP address has been banned for exceeding rate limits."
+        )
+        super().__init__(error_message)
+
+
+class ServerError(Error):
+    """Represents an error when there is an internal server error."""
+
+    def __init__(
+        self,
+        error_message: Optional[str] = None,
+        status_code: Optional[int] = None,
+    ):
+        self.error_message = error_message or "An internal server error occurred."
+        self.status_code = status_code
+        super().__init__(error_message)
+
+
+class NetworkError(Error):
+    """Represents an error when a network error occurs."""
+
+    def __init__(self, error_message: Optional[str] = None):
+        self.error_message = error_message or "A network error occurred."
+        super().__init__(error_message)
+
+
+class NotFoundError(Error):
+    """Represents an error when the requested resource was not found."""
+
+    def __init__(self, error_message: Optional[str] = None):
+        self.error_message = error_message or "The requested resource was not found."
+        super().__init__(error_message)
+
+
+class BadRequestError(Error):
+    """Represents an error when a request is invalid or cannot be otherwise served."""
+
+    def __init__(self, error_message: Optional[str] = None):
+        self.error_message = (
+            error_message or "The request was invalid or cannot be otherwise served."
+        )
+        super().__init__(self.error_message)

binance_common/logger.py

@@ -0,0 +1,69 @@
+import logging
+from enum import Enum
+
+
+class LogLevel(Enum):
+    NONE = 0
+    DEBUG = 10
+    INFO = 20
+    WARN = 30
+    ERROR = 40
+
+
+class Logger:
+    _instance = None
+
+    def __init__(self):
+        """Ensure only one instance is initialized."""
+        if not Logger._instance:
+            Logger._instance = self
+            self._initialize()
+        else:
+            self.__dict__ = Logger._instance.__dict__  # Share attributes
+
+    @classmethod
+    def get_instance(cls):
+        """Retrieve or initialize the singleton logger."""
+        if not cls._instance:
+            cls._instance = cls()
+        return cls._instance
+
+    def _initialize(self):
+        """Initialize the logger settings."""
+        self._logger = logging.getLogger("ConnectorLogger")
+
+        # Prevent duplicate handlers if logger is re-initialized
+        if not self._logger.hasHandlers():
+            handler = logging.StreamHandler()
+            formatter = logging.Formatter("[%(asctime)s] [%(levelname)s] %(message)s")
+            handler.setFormatter(formatter)
+            self._logger.addHandler(handler)
+
+        self._logger.setLevel(LogLevel.INFO.value)
+        self.min_log_level = LogLevel.INFO
+
+    def set_min_log_level(self, level: LogLevel):
+        """Set the minimum log level."""
+        if not isinstance(level, LogLevel):
+            raise ValueError(f"Invalid log level: {level}")
+        self.min_log_level = level
+        self._logger.setLevel(level.value)
+
+    def debug(self, *message):
+        if self._allow_level_log(LogLevel.DEBUG):
+            self._logger.debug(" ".join(map(str, message)))
+
+    def info(self, *message):
+        if self._allow_level_log(LogLevel.INFO):
+            self._logger.info(" ".join(map(str, message)))
+
+    def warn(self, *message):
+        if self._allow_level_log(LogLevel.WARN):
+            self._logger.warning(" ".join(map(str, message)))
+
+    def error(self, *message):
+        if self._allow_level_log(LogLevel.ERROR):
+            self._logger.error(" ".join(map(str, message)))
+
+    def _allow_level_log(self, level: LogLevel) -> bool:
+        return level.value >= self.min_log_level.value

binance_common/models.py

@@ -0,0 +1,92 @@
+from typing import List, Optional, Callable, TypeVar, Generic
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class RateLimit(BaseModel):
+    """Represents a single rate limit entry.
+
+    :param rateLimitType: The type of the rate limit (e.g., 'REQUEST_WEIGHT', 'ORDERS').
+    :param interval: The time interval (e.g., 'SECOND', 'MINUTE', 'HOUR', 'DAY').
+    :param intervalNum: The interval number (e.g., 1, 10, etc.).
+    :param count: The number of requests/orders used in the interval.
+    :param retryAfter: Optional retry time in seconds if rate-limited.
+    """
+
+    rateLimitType: str
+    interval: str
+    intervalNum: int
+    count: int
+    retryAfter: Optional[int]
+
+
+class ApiResponse(Generic[T]):
+    """A wrapper for API responses that includes parsed data and rate limit headers.
+
+    :param data_function: A callable that lazily returns the parsed data of type T.
+    :param status: The HTTP status code of the response.
+    :param headers: A dictionary of response headers.
+    :param rate_limits: A list of rate limit headers parsed from the response.
+    """
+
+    def __init__(
+        self,
+        data_function: Callable[[], T],
+        status: int,
+        headers: dict,
+        rate_limits: List[RateLimit] = None,
+    ):
+        self._data_function = data_function
+        self.status = status
+        self.headers = headers or {}
+        self.rate_limits = rate_limits or []
+
+    def data(self) -> T:
+        """Lazily retrieves the response data.
+
+        :return: The parsed data of type T.
+        """
+        return self._data_function()
+
+
+class WebsocketApiRateLimit(BaseModel):
+    """Represents a single rate limit entry for WebSocket API.
+
+    :param rateLimitType: The type of the rate limit (e.g., 'REQUEST_WEIGHT', 'ORDERS').
+    :param interval: The time interval (e.g., 'SECOND', 'MINUTE', 'HOUR', 'DAY').
+    :param intervalNum: The number of intervals for the rate limit.
+    :param limit: The maximum number of requests or orders allowed within the specified interval.
+    :param count: The current count of requests or orders for the rate limit.
+    """
+
+    rateLimitType: str
+    interval: str
+    intervalNum: int
+    limit: int
+    count: int = 0
+
+
+class WebsocketApiResponse(Generic[T]):
+    """A wrapper for WebSocket API responses that includes parsed data and rate limit headers.
+
+    :param data_function: A callable that lazily returns the parsed data of type T.
+    :param status: The HTTP status code of the response.
+    :param headers: A dictionary of response headers.
+    :param rate_limits: A list of rate limit headers parsed from the response.
+    """
+
+    def __init__(
+        self,
+        data_function: T = None,
+        rate_limits: List[WebsocketApiRateLimit] = None,
+    ):
+        self._data_function = data_function
+        self.rate_limits = rate_limits or []
+
+    def data(self) -> T:
+        """Lazily retrieves the response data.
+
+        :return: The parsed data of type T.
+        """
+        return self._data_function()