Merge pull request #422 from binance/release_common_v3.0.0

Author: alplabin

common/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.0.0 - 2025-09-05
+
+### Added (2)
+
+- Support automatic session re-logon on reconncetions/renewals when session is already logged on (`Session re-logon` option on `WebSocketAPIBase`).
+- Added the `api_key` parameter to include `apiKey` in WebsocketAPI request parameters.
+
+### Changed (2)
+
+- Fixed return type mismatch by returning the raw value.
+- Updated `WebsocketAPI` user data return value to match its type.
+
 ## 2.0.0 - 2025-08-22
 
 ### Changed (3)

common/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "binance-common"
-version = "2.0.0"
+version = "3.0.0"
 description = "Binance Common Types and Utilities for Binance Connectors"
 authors = ["Binance"]
 license = "MIT"

common/src/binance_common/configuration.py

@@ -94,6 +94,7 @@ class ConfigurationWebSocketAPI:
     - WebSocket Pool
     - Time Unit
     - Proxy support
+    - Session re-logon
     """
 
     def __init__(
@@ -111,6 +112,7 @@ def __init__(
         pool_size: int = 2,
         time_unit: TimeUnit = None,
         https_agent: Optional[ssl.SSLContext] = None,
+        session_re_logon: Optional[bool] = True,
     ):
         """
         Initialize the API configuration.
@@ -129,6 +131,7 @@ def __init__(
             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).
+            session_re_logon (Optional[bool]): Enable session re-logon (default: True).
         """
 
         self.api_key = api_key
@@ -145,6 +148,7 @@ def __init__(
         self.time_unit = time_unit
         self.https_agent = https_agent
         self.user_agent = ""
+        self.session_re_logon = session_re_logon
 
 
 class ConfigurationWebSocketStreams:

common/src/binance_common/models.py

@@ -1,6 +1,8 @@
 from typing import List, Optional, Callable, TypeVar, Generic
 from pydantic import BaseModel
 
+from binance_common.signature import Signers
+
 T = TypeVar("T")
 T_Response = TypeVar("T_Response")
 T_Stream = TypeVar("T_Stream")
@@ -107,3 +109,31 @@ def __init__(
     ):
         self.response = response
         self.stream = stream
+
+
+class WebsocketApiOptions(Generic[T]):
+    """Options for configuring WebSocket API connections.
+
+    :param api_key: A boolean flag indicating whether to include the API key in the request.
+    :param is_signed: A boolean flag indicating whether the request should be signed.
+    :param skip_auth: A boolean flag indicating whether to skip authentication.
+    :param signer: An optional Signers instance for signing requests.
+    """
+
+    def __init__(
+        self,
+        api_key: bool = False,
+        is_signed: bool = True,
+        skip_auth: bool = True,
+        signer: Optional[Signers] = None,
+    ):
+        self.signer = signer
+        self.api_key = api_key
+        self.is_signed = is_signed
+        self.skip_auth = skip_auth
+
+class WebsocketApiUserDataEndpoints(BaseModel):
+    """Represents the WebSocket user data endpoints."""
+
+    user_data_stream_subscribe: str
+    user_data_stream_logout: str

common/src/binance_common/utils.py

@@ -1,5 +1,7 @@
+import copy
 import hashlib
 import hmac
+import importlib
 import json
 import re
 import requests
@@ -9,11 +11,12 @@
 import uuid
 
 from base64 import b64encode
+from collections import OrderedDict
 from Crypto.Hash import SHA256
 from Crypto.Signature.pkcs1_15 import PKCS115_SigScheme
 from enum import Enum
 from pydantic import BaseModel
-from typing import Dict, List, Optional, Type, TypeVar, Union
+from typing import Dict, List, Optional, Type, TypeVar, Union, get_args
 from urllib.parse import urlencode
 from urllib3.util.ssl_ import create_urllib3_context
 
@@ -30,7 +33,12 @@
     TooManyRequestsError,
     UnauthorizedError,
 )
-from binance_common.models import ApiResponse, RateLimit, WebsocketApiRateLimit
+from binance_common.models import (
+    ApiResponse,
+    RateLimit,
+    WebsocketApiOptions,
+    WebsocketApiRateLimit
+)
 from binance_common.signature import Signers
 
 
@@ -346,8 +354,14 @@ def send_request(
             else:
                 data_function = lambda: response_model.model_validate(parsed)
 
+            try:
+                data_function()  
+                final_data_function = data_function
+            except Exception:
+                final_data_function = lambda: parsed
+
             return ApiResponse[T](
-                data_function=data_function,
+                data_function=final_data_function,
                 status=response.status_code,
                 headers=response.headers,
                 rate_limits=parse_rate_limit_headers(response.headers),
@@ -506,6 +520,7 @@ def ws_streams_placeholder(stream: str, params: dict = {}) -> str:
         stream,
     )
 
+
 def parse_ws_rate_limit_headers(
     headers: List[Dict[str, Union[str, int]]],
 ) -> List[WebsocketApiRateLimit]:
@@ -522,6 +537,7 @@ def parse_ws_rate_limit_headers(
         rate_limits.append(WebsocketApiRateLimit(**header))
     return rate_limits
 
+
 def normalize_query_values(parsed, expected_types=None):
     """Normalizes the values in a parsed query dictionary.
 
@@ -563,3 +579,144 @@ def convert(val, expected_type=None):
         normalized[k] = converted[0] if len(converted) == 1 else converted
 
     return normalized
+
+
+def ws_api_payload(config, payload: Dict, websocket_options: WebsocketApiOptions):
+    """Generate payload for websocket API
+
+    Args:
+        config: The API configuration.
+        payload (Dict): The payload to send.
+        websocket_options (WebsocketApiOptions): The WebSocket API options.
+
+    Returns:
+        Dict: The generated payload for the WebSocket API.
+    """
+
+    payload = copy.copy(payload)
+
+    if websocket_options.api_key and websocket_options.skip_auth is False:
+        payload["params"]["apiKey"] = config.api_key
+
+    payload["id"] = payload["id"] if "id" in payload else get_uuid()
+
+    payload["params"] = {
+        snake_to_camel(k): json.dumps(make_serializable(v), separators=(",", ":"))
+        if isinstance(v, (list, dict))
+        else make_serializable(v)
+        for k, v in payload["params"].items()
+    }
+
+    if websocket_options.is_signed:
+        if websocket_options.skip_auth is True:
+            payload["params"]["timestamp"] = get_timestamp()
+        else:
+            payload["params"] = websocket_api_signature(config, payload["params"], websocket_options.signer)
+
+    return payload
+
+
+def websocket_api_signature(config, payload: Optional[Dict] = {}, signer: Signers = None) -> dict:
+    """Generate signature for websocket API
+
+    Args:
+        payload (Optional[Dict]): Payload.
+        signer (Signers): Signer for the payload.
+    Returns:
+        dict: The generated signature for the WebSocket API.
+    """
+
+    payload["apiKey"] = config.api_key
+    payload["timestamp"] = get_timestamp()
+    parameters = OrderedDict(sorted(payload.items()))
+    parameters["signature"] = get_signature(
+        config, urlencode(parameters), signer
+    )
+    return parameters
+
+
+def get_validator_field_map(response_model_cls: Type[BaseModel]) -> dict[str, str]:
+    """Map User Data response schema class name to oneof_schema_N_validator field dynamically
+
+    Args:
+        response_model_cls (Type[BaseModel]): The response model class.
+
+    Returns:
+        dict[str, str]: The mapping of field names to validator field names.
+    """
+
+    field_map = {}
+    annotations = getattr(response_model_cls, "__annotations__", {})
+
+    for field_name, annotation in annotations.items():
+        if field_name.startswith("oneof_schema_") and field_name.endswith("_validator"):
+            if getattr(annotation, "__origin__", None) is Union:
+                type_ = next((arg for arg in get_args(annotation) if arg is not type(None)), None)
+            else:
+                type_ = annotation
+            if isinstance(type_, str):
+                type_ = re.sub(r'^Optional\[(.*)\]$', r'\1', type_)
+
+            if type_:
+                field_map[type_] = field_name
+
+    return field_map
+
+
+def resolve_model_from_event(response_model_cls: Type[BaseModel], event_name: str) -> Type[BaseModel]:
+    """Resolve the correct model class for the websocket event dynamically.
+
+    Args:
+        response_model_cls (Type[BaseModel]): The response model class.
+        event_name (str): The name of the event.
+
+    Returns:
+        Type[BaseModel]: The resolved model class or None.
+    """
+
+    if not event_name:
+        return None
+
+    one_of_schemas_field = response_model_cls.__pydantic_fields__.get("one_of_schemas")
+    if not one_of_schemas_field:
+        return None
+
+    one_of_schemas = list(one_of_schemas_field.default)
+    event_to_class_map = {name[0].lower() + name[1:]: name for name in one_of_schemas}
+
+    class_name = event_to_class_map.get(event_name)
+    if not class_name:
+        return None
+
+    module = importlib.import_module(response_model_cls.__module__)
+    return getattr(module, class_name, None)
+
+
+def parse_user_event(payload: dict, response_model_cls: Type[BaseModel]) -> BaseModel:
+    """Parse user event to response model.
+
+    Args:
+        payload (dict): The payload dictionary containing event data.
+        response_model_cls (Type[BaseModel]): The response model class.
+
+    Returns:
+        BaseModel: The parsed response model instance.
+    """
+
+    event_name = payload.get("e")
+    model_cls = resolve_model_from_event(response_model_cls, event_name)
+
+    if not model_cls:
+        return response_model_cls(actual_instance=payload)
+
+    try:
+        instance = model_cls.model_validate(payload)
+        validator_field_map = get_validator_field_map(response_model_cls)
+        kwargs = {"actual_instance": instance}
+        if validator_field := validator_field_map.get(model_cls.__name__):
+            kwargs[validator_field] = instance
+        return response_model_cls(**kwargs)
+
+    except Exception as e:
+        print(f"Failed to parse {event_name}: {e}")
+        return response_model_cls(actual_instance=payload)