Merge pull request #506 from binance/release_common_v3.7.0

Author: alplabin

common/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.7.0 - 2026-03-16
+
+### Added (1)
+
+- Added `serverShutdown` event handler.
+
 ## 3.6.0 - 2026-02-11
 
 ### Updated (2)

common/pyproject.toml

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

common/src/binance_common/configuration.py

@@ -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),
         }
 
 
@@ -113,7 +113,7 @@ def __init__(
         time_unit: TimeUnit = None,
         https_agent: Optional[ssl.SSLContext] = None,
         session_re_logon: Optional[bool] = True,
-        return_rate_limits: Optional[bool] = True
+        return_rate_limits: Optional[bool] = True,
     ):
         """
         Initialize the API configuration.

common/src/binance_common/constants.py

@@ -8,10 +8,12 @@ class TimeUnit(Enum):
     MICROSECOND = "MICROSECOND"
     microsecond = "microsecond"
 
+
 class WebsocketMode(Enum):
     SINGLE = "single"
     POOL = "pool"
 
+
 # Algo constants
 ALGO_REST_API_PROD_URL = "https://api.binance.com"
 
@@ -38,33 +40,58 @@ class WebsocketMode(Enum):
 
 # 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_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_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_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_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_USDS_FUTURES_WS_STREAMS_TESTNET_URL = (
+    "wss://fstream.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://fstream.binance.com"
 
 # 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_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"
+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"
@@ -98,10 +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_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_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_REST_API_MARKET_URL = "https://data-api.binance.vision"
 SPOT_WS_STREAMS_MARKET_URL = "wss://data-stream.binance.vision"
 

common/src/binance_common/errors.py

@@ -8,7 +8,9 @@ class Error(Exception):
 class ClientError(Error):
     """Represents an error that occurred in the Connector client."""
 
-    def __init__(self, error_message: Optional[str] = None, status_code: Optional[int] = None):
+    def __init__(
+        self, error_message: Optional[str] = None, status_code: Optional[int] = None
+    ):
         self.error_message = error_message or "An unexpected error occurred."
         self.status_code = status_code
         super().__init__(self.status_code, self.error_message)
@@ -28,44 +30,56 @@ def __init__(self, field: str, error_message: Optional[str] = None):
 class UnauthorizedError(Error):
     """Represents an error when a client is unauthorized to access a resource."""
 
-    def __init__(self, error_message: Optional[str] = None, status_code: Optional[int] = None):
+    def __init__(
+        self, error_message: Optional[str] = None, status_code: Optional[int] = None
+    ):
         self.error_message = (
             error_message or "Unauthorized access. Authentication required."
         )
         self.status_code = status_code
         super().__init__(self.status_code, self.error_message)
 
+
 class ForbiddenError(Error):
     """Represents an error when access to the resource is forbidden."""
 
-    def __init__(self, error_message: Optional[str] = None, status_code: Optional[int] = None):
+    def __init__(
+        self, error_message: Optional[str] = None, status_code: Optional[int] = None
+    ):
         self.error_message = (
             error_message or "Access to the requested resource is forbidden."
         )
         self.status_code = status_code
         super().__init__(self.status_code, self.error_message)
 
+
 class TooManyRequestsError(Error):
     """Represents an error when the client is doing too many requests."""
 
-    def __init__(self, error_message: Optional[str] = None, status_code: Optional[int] = None):
+    def __init__(
+        self, error_message: Optional[str] = None, status_code: Optional[int] = None
+    ):
         self.error_message = (
             error_message or "Too many requests. You are being rate-limited."
         )
         self.status_code = status_code
         super().__init__(self.status_code, self.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, status_code: Optional[int] = None):
+    def __init__(
+        self, error_message: Optional[str] = None, status_code: Optional[int] = None
+    ):
         self.error_message = (
             error_message or "The IP address has been banned for exceeding rate limits."
         )
         self.status_code = status_code
         super().__init__(self.status_code, self.error_message)
 
+
 class ServerError(Error):
     """Represents an error when there is an internal server error."""
 
@@ -90,7 +104,9 @@ def __init__(self, error_message: Optional[str] = None):
 class NotFoundError(Error):
     """Represents an error when the requested resource was not found."""
 
-    def __init__(self, error_message: Optional[str] = None, status_code: Optional[int] = None):
+    def __init__(
+        self, error_message: Optional[str] = None, status_code: Optional[int] = None
+    ):
         self.error_message = error_message or "The requested resource was not found."
         self.status_code = status_code
         super().__init__(self.status_code, self.error_message)
@@ -99,7 +115,9 @@ def __init__(self, error_message: Optional[str] = None, status_code: Optional[in
 class BadRequestError(Error):
     """Represents an error when a request is invalid or cannot be otherwise served."""
 
-    def __init__(self, error_message: Optional[str] = None, status_code: Optional[int] = None):
+    def __init__(
+        self, error_message: Optional[str] = None, status_code: Optional[int] = None
+    ):
         self.error_message = (
             error_message or "The request was invalid or cannot be otherwise served."
         )

common/src/binance_common/headers.py

@@ -2,6 +2,7 @@
 
 from typing import List, Optional, Union
 
+
 def sanitize_header_value(value: Union[str, List[str]]) -> Union[str, List[str]]:
     """Sanitizes a header value by checking for and preventing carriage return and line feed characters.
 
@@ -19,7 +20,10 @@ def sanitize_header_value(value: Union[str, List[str]]) -> Union[str, List[str]]
         raise ValueError(f'Invalid header value (contains CR/LF): "{value}"')
     return value
 
-def parse_custom_headers(custom_headers: Optional[dict[str, Union[str, List[str]]]]) -> dict[str, Union[str, List[str]]]:
+
+def parse_custom_headers(
+    custom_headers: Optional[dict[str, Union[str, List[str]]]],
+) -> dict[str, Union[str, List[str]]]:
     """Parses custom headers for the API client.
 
     Args:
@@ -46,8 +50,8 @@ def parse_custom_headers(custom_headers: Optional[dict[str, Union[str, List[str]
                 parsed_headers[header_name] = [sanitize_header_value(v) for v in value]
             else:
                 parsed_headers[header_name] = sanitize_header_value(value)
-        except ValueError as e:
+        except ValueError:
             logging.warning(f"Dropping header '{header_name}' due to invalid value.")
             continue
 
-    return parsed_headers
+    return parsed_headers

common/src/binance_common/models.py

@@ -7,6 +7,7 @@
 T_Response = TypeVar("T_Response")
 T_Stream = TypeVar("T_Stream")
 
+
 class RateLimit(BaseModel):
     """Represents a single rate limit entry.
 
@@ -132,6 +133,7 @@ def __init__(
         self.is_signed = is_signed
         self.skip_auth = skip_auth
 
+
 class WebsocketApiUserDataEndpoints(BaseModel):
     """Represents the WebSocket user data endpoints."""
 

common/src/binance_common/signature.py

@@ -55,9 +55,11 @@ def get_ed25519_signer(cls, key: str, passphrase: Optional[str]) -> object:
             ed_key = cls.get_ed25519_key(key, passphrase)
             cls._ed25519_signers[cache_key] = eddsa.new(ed_key, "rfc8032")
         return cls._ed25519_signers[cache_key]
-    
+
     @classmethod
-    def get_signer(cls, private_key: str, passphrase: Optional[str] = None) -> Union[pkcs1_15.PKCS115_SigScheme, object]:
+    def get_signer(
+        cls, private_key: str, passphrase: Optional[str] = None
+    ) -> Union[pkcs1_15.PKCS115_SigScheme, object]:
         """
         Automatically detects the key type (RSA or Ed25519) and returns the appropriate signer.
         Raises ValueError if the key is not supported.
@@ -73,4 +75,6 @@ def get_signer(cls, private_key: str, passphrase: Optional[str] = None) -> Union
         except (ValueError, IndexError, TypeError):
             pass
 
-        raise ValueError("Unsupported or invalid private key format. Private key must be either 'RSA' or 'ED25519'")
+        raise ValueError(
+            "Unsupported or invalid private key format. Private key must be either 'RSA' or 'ED25519'"
+        )