Merge pull request #517 from binance/release_common_v3.8.0

Author: alplabin

common/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 3.8.0 - 2026-03-26
+
+### Added (2)
+
+- Added `py.typed` file to indicate that the package supports type hints.
+- Added clear cache option to `Signer` class to allow clearing cached signatures.
+
+### Updated (4)
+
+- Fix bug with exposing secrets on messages logging.
+- Updated `print` statement to be logged instead of printed.
+- Updated mutable default parameter to avoid shared state between instances.
+- Updated `tox.ini` file
+
 ## 3.7.0 - 2026-03-16
 
 ### Added (1)

common/pyproject.toml

@@ -1,11 +1,11 @@
 [tool.poetry]
 name = "binance-common"
-version = "3.7.0"
+version = "3.8.0"
 description = "Binance Common Types and Utilities for Binance Connectors"
 authors = ["Binance"]
 license = "MIT"
 readme = "README.md"
-include = ["CHANGELOG.md", "LICENSE", "README.md"]
+include = ["CHANGELOG.md", "LICENSE", "README.md", "src/binance_common/py.typed"]
 packages = [
   { include = "binance_common", from = "src" }
 ]
@@ -37,3 +37,6 @@ exclude = [".git", ".tox", "build", "dist"]
 
 [tool.ruff.lint]
 ignore = ["E741"]
+
+[tool.flake8]
+max-line-length = 100

common/src/binance_common/configuration.py

@@ -25,9 +25,9 @@ class ConfigurationRestAPI:
 
     def __init__(
         self,
-        api_key: str = None,
+        api_key: Optional[str] = None,
         api_secret: Optional[str] = None,
-        base_path: str = None,
+        base_path: Optional[str] = None,
         timeout: int = 1000,
         proxy: Optional[Dict[str, Union[str, int, Dict[str, str]]]] = None,
         keep_alive: bool = True,
@@ -38,15 +38,15 @@ def __init__(
         time_unit: Optional[str] = None,
         private_key: Optional[Union[bytes, str]] = None,
         private_key_passphrase: Optional[str] = None,
-        custom_headers: Optional[dict[str, Union[str, List[str]]]] = {},
+        custom_headers: Optional[dict[str, Union[str, List[str]]]] = None,
     ):
         """
         Initialize the API configuration.
 
         Args:
-            api_key (str): API key for authentication.
+            api_key (Optional[str]): API key for authentication (default: None).
             api_secret (Optional[str]): API secret for authentication (default: None).
-            base_path (str): Base API URL (default: None).
+            base_path (Optional[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).
@@ -77,7 +77,7 @@ def __init__(
         self.base_headers = {
             "Accept": "application/json",
             "X-MBX-APIKEY": str(self.api_key) if self.api_key else "",
-            **parse_custom_headers(custom_headers),
+            **parse_custom_headers(custom_headers if custom_headers else {}),
         }
 
 
@@ -99,18 +99,18 @@ class ConfigurationWebSocketAPI:
 
     def __init__(
         self,
-        api_key: str = None,
+        api_key: Optional[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",
+        stream_url: Optional[str] = None,
         timeout: int = 5000,
         reconnect_delay: int = 5000,
         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,
+        time_unit: Optional[TimeUnit] = None,
         https_agent: Optional[ssl.SSLContext] = None,
         session_re_logon: Optional[bool] = True,
         return_rate_limits: Optional[bool] = True,
@@ -119,11 +119,11 @@ def __init__(
         Initialize the API configuration.
 
         Args:
-            api_key (str): API key for authentication.
+            api_key (Optional[str]): API key for authentication (default: None).
             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").
+            stream_url (Optional[str]): Base WebSocket API URL (default: None).
             timeout (int): Request timeout in milliseconds (default: 5000).
             reconnect_delay (int): Delay (ms) between reconnections (default: 5000).
             compression (int): Compression level (default: 0).
@@ -168,20 +168,20 @@ class ConfigurationWebSocketStreams:
 
     def __init__(
         self,
-        stream_url: str = "wss://stream.binance.com:9443/stream",
+        stream_url: Optional[str] = None,
         reconnect_delay: int = 5000,
         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,
+        time_unit: Optional[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").
+            stream_url (Optional[str]): Base WebSocket Stream URL (default: None).
             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).

common/src/binance_common/constants.py

@@ -59,7 +59,7 @@ class WebsocketMode(Enum):
 DERIVATIVES_TRADING_USDS_FUTURES_REST_API_TESTNET_URL = (
     "https://testnet.binancefuture.com"
 )
-DERIVATIVES_TRADING_USDS_FUTURES_REST_API_DEMO_URL = 'https://demo-fapi.binance.com'
+DERIVATIVES_TRADING_USDS_FUTURES_REST_API_DEMO_URL = "https://demo-fapi.binance.com"
 DERIVATIVES_TRADING_USDS_FUTURES_WS_API_PROD_URL = (
     "wss://ws-fapi.binance.com/ws-fapi/v1"
 )
@@ -125,13 +125,13 @@ class WebsocketMode(Enum):
 # Spot Constants
 SPOT_REST_API_PROD_URL = "https://api.binance.com"
 SPOT_REST_API_TESTNET_URL = "https://testnet.binance.vision"
-SPOT_REST_API_DEMO_URL = 'https://demo-api.binance.com'
+SPOT_REST_API_DEMO_URL = "https://demo-api.binance.com"
 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_API_DEMO_URL = 'wss://demo-ws-api.binance.com/ws-api/v3'
+SPOT_WS_API_DEMO_URL = "wss://demo-ws-api.binance.com/ws-api/v3"
 SPOT_WS_STREAMS_PROD_URL = "wss://stream.binance.com:9443"
 SPOT_WS_STREAMS_TESTNET_URL = "wss://stream.testnet.binance.vision"
-SPOT_WS_STREAMS_DEMO_URL = 'wss://demo-stream.binance.com:9443'
+SPOT_WS_STREAMS_DEMO_URL = "wss://demo-stream.binance.com:9443"
 SPOT_REST_API_MARKET_URL = "https://data-api.binance.vision"
 SPOT_WS_STREAMS_MARKET_URL = "wss://data-stream.binance.vision"
 

common/src/binance_common/models.py

@@ -39,7 +39,7 @@ def __init__(
         data_function: Callable[[], T],
         status: int,
         headers: dict,
-        rate_limits: List[RateLimit] = None,
+        rate_limits: Optional[List[RateLimit]] = None,
     ):
         self._data_function = data_function
         self.status = status
@@ -82,8 +82,8 @@ class WebsocketApiResponse(Generic[T]):
 
     def __init__(
         self,
-        data_function: T = None,
-        rate_limits: List[WebsocketApiRateLimit] = None,
+        data_function: Optional[T] = None,
+        rate_limits: Optional[List[WebsocketApiRateLimit]] = None,
     ):
         self._data_function = data_function
         self.rate_limits = rate_limits or []
@@ -93,6 +93,8 @@ def data(self) -> T:
 
         :return: The parsed data of type T.
         """
+        if self._data_function is None:
+            raise ValueError("No data function provided for this response.")
         return self._data_function()
 
 

common/src/binance_common/py.typed

@@ -38,6 +38,11 @@ def get_rsa_signer(
             cls._rsa_signers[cache_key] = pkcs1_15.new(rsa_key)
         return cls._rsa_signers[cache_key]
 
+    @classmethod
+    def clear_rsa_cache(cls):
+        cls._rsa_keys.clear()
+        cls._rsa_signers.clear()
+
     @classmethod
     def get_ed25519_key(cls, key: str, passphrase: Optional[str]) -> ECC.EccKey:
         key_data = cls._load_private_key_data(key)
@@ -56,6 +61,11 @@ def get_ed25519_signer(cls, key: str, passphrase: Optional[str]) -> object:
             cls._ed25519_signers[cache_key] = eddsa.new(ed_key, "rfc8032")
         return cls._ed25519_signers[cache_key]
 
+    @classmethod
+    def clear_ed25519_cache(cls):
+        cls._ed25519_keys.clear()
+        cls._ed25519_signers.clear()
+
     @classmethod
     def get_signer(
         cls, private_key: str, passphrase: Optional[str] = None

common/src/binance_common/signature.py

@@ -3,6 +3,7 @@
 import hmac
 import importlib
 import json
+import logging
 import re
 import requests
 import requests.adapters
@@ -48,7 +49,7 @@
 class CustomHTTPSAdapter(requests.adapters.HTTPAdapter):
     """A custom HTTPS adapter that supports SSLContext (including certificate pinning)."""
 
-    def __init__(self, ssl_context: ssl.SSLContext = None, **kwargs):
+    def __init__(self, ssl_context: Optional[ssl.SSLContext] = None, **kwargs):
         self.ssl_context = ssl_context or create_urllib3_context()
         super().__init__(**kwargs)
 
@@ -262,7 +263,9 @@ def get_signature(
         )
 
 
-def should_retry_request(error, method: str = None, retries_left: int = None) -> bool:
+def should_retry_request(
+    error, method: Optional[str] = None, retries_left: Optional[int] = None
+) -> bool:
     """Determines whether a request should be retried based on the error.
 
     :param error: The error object to check.
@@ -295,14 +298,15 @@ def send_request(
     payload: Optional[dict] = None,
     body: Optional[dict] = None,
     time_unit: Optional[str] = None,
-    response_model: Type[T] = None,
+    response_model: Optional[Type[T]] = None,
     is_signed: bool = False,
     signer: Optional[Signers] = None,
 ) -> ApiResponse[T]:
     """Sends an HTTP request with the specified configuration, method, path, and
     optional payload and time unit.
 
-    The `send_request` function is responsible for sending an HTTP request with the provided parameters. It handles retries, error handling, and response processing. The function takes the following parameters:
+    The `send_request` function is responsible for sending an HTTP request with the provided parameters.
+    It handles retries, error handling, and response processing. The function takes the following parameters:
 
     - `configuration`: The configuration object containing the necessary information for sending the request.
     - `method`: The HTTP method to use (e.g. "GET", "POST", etc.).
@@ -424,17 +428,27 @@ def send_request(
                 or (not isinstance(parsed[0], list) if is_list else False)
             )
             if (is_list and not is_flat_list) or not response_model:
-                data_function = lambda: parsed
+
+                def data_function():
+                    return parsed
+
             elif is_oneof or is_list or hasattr(response_model, "from_dict"):
-                data_function = lambda: response_model.from_dict(parsed)
+
+                def data_function():
+                    return response_model.from_dict(parsed)
+
             else:
-                data_function = lambda: response_model.model_validate(parsed)
+
+                def data_function():
+                    return response_model.model_validate(parsed)
 
             try:
                 data_function()
                 final_data_function = data_function
             except Exception:
-                final_data_function = lambda: parsed
+
+                def final_data_function():
+                    return parsed
 
             return ApiResponse[T](
                 data_function=final_data_function,
@@ -558,16 +572,19 @@ def parse_proxies(
     return {"https": proxy_url, "http": proxy_url}
 
 
-def ws_streams_placeholder(stream: str, params: dict = {}) -> str:
+def ws_streams_placeholder(stream: str, params: Optional[dict] = None) -> str:
     """Replaces placeholders in the stream string with values from the params dictionary.
 
     Args:
         stream (str): The stream string with placeholders.
-        params (dict): A dictionary containing values to replace the placeholders.
+        params (Optional[dict]): A dictionary containing values to replace the placeholders. Defaults to None.
 
     Returns:
         str: The stream string with placeholders replaced by actual values.
     """
+    if params is None:
+        params = {}
+
     params = {k: v for k, v in params.items() if v is not None}
 
     normalized_variables = {
@@ -698,17 +715,19 @@ def ws_api_payload(config, payload: Dict, websocket_options: WebsocketApiOptions
 
 
 def websocket_api_signature(
-    config, payload: Optional[Dict] = {}, signer: Signers = None
+    config, payload: Optional[Dict] = None, signer: Optional[Signers] = None
 ) -> dict:
     """Generate signature for websocket API
 
     Args:
         payload (Optional[Dict]): Payload.
-        signer (Signers): Signer for the payload.
+        signer (Optional[Signers]): Signer for the payload.
     Returns:
         dict: The generated signature for the WebSocket API.
     """
 
+    if payload is None:
+        payload = {}
     payload["apiKey"] = config.api_key
     payload["timestamp"] = get_timestamp()
     parameters = OrderedDict(sorted(payload.items()))
@@ -803,5 +822,31 @@ def parse_user_event(payload: dict, response_model_cls: Type[BaseModel]) -> Base
         return response_model_cls(**kwargs)
 
     except Exception as e:
-        print(f"Failed to parse {event_name}: {e}")
+        logging.warning(f"Failed to parse {event_name}: {e}")
         return response_model_cls(actual_instance=payload)
+
+
+def redact_sensitive_info(config: dict) -> dict:
+    """Redacts sensitive information from the configuration for logging purposes.
+
+    Args:
+        config (Union[ConfigurationWebSocketAPI, ConfigurationRestAPI]): The configuration object to redact.
+    Returns:
+        dict: A dictionary representation of the configuration with sensitive information redacted.
+    """
+    redacted_config = copy.deepcopy(config)
+    SENSITIVE_KEYS = ["apiKey", "signature"]
+
+    if isinstance(redacted_config, dict) or isinstance(redacted_config, OrderedDict):
+        for key, value in redacted_config.items():
+            if key in SENSITIVE_KEYS:
+                redacted_config[key] = "[REDACTED]"
+            else:
+                if isinstance(value, (dict, OrderedDict, list)):
+                    redacted_config[key] = redact_sensitive_info(value)
+    elif isinstance(redacted_config, list):
+        for i, item in enumerate(redacted_config):
+            if isinstance(item, (dict, OrderedDict, list)):
+                redacted_config[i] = redact_sensitive_info(item)
+
+    return redacted_config