Merge pull request #473 from binance/release_common_v3.3.0

Author: alplabin

common/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 3.3.0 - 2025-12-22
+
+### Changed (6)
+
+- Added `body` parameter to `send_request` function for Rest API http requests.
+- Added `return_rate_limits` parameter to `ConfigurationWebSocketAPI` to avoid receiving rate limit headers.
+- Added `id_strict_int` parameter to `WebSocketStreamBase` to fix `Derivatives Trading Options` error.
+- Updated returned error value in `send_request` function.
+- Updated Websocket `timeout` and `reconnect_delay` to be in milliseconds.
+- Updated `backoff` to be in milliseconds.
+
 ## 3.2.0 - 2025-10-10
 
 ### Changed (1)

common/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "binance-common"
-version = "3.2.0"
+version = "3.3.0"
 description = "Binance Common Types and Utilities for Binance Connectors"
 authors = ["Binance"]
 license = "MIT"
@@ -11,7 +11,7 @@ packages = [
 ]
 
 [tool.poetry.dependencies]
-python = ">=3.9,<3.14"
+python = ">=3.9,<3.15"
 requests = ">=2.31.0"
 pydantic = ">=2.10.0"
 websockets = "^15.0.1"

common/src/binance_common/configuration.py

@@ -104,15 +104,16 @@ def __init__(
         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,
+        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,
         https_agent: Optional[ssl.SSLContext] = None,
         session_re_logon: Optional[bool] = True,
+        return_rate_limits: Optional[bool] = True
     ):
         """
         Initialize the API configuration.
@@ -132,6 +133,7 @@ def __init__(
             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).
+            return_rate_limits (Optional[bool]): Enable rate limits returns (default: True).
         """
 
         self.api_key = api_key
@@ -149,6 +151,7 @@ def __init__(
         self.https_agent = https_agent
         self.user_agent = ""
         self.session_re_logon = session_re_logon
+        self.return_rate_limits = return_rate_limits
 
 
 class ConfigurationWebSocketStreams:
@@ -166,7 +169,7 @@ class ConfigurationWebSocketStreams:
     def __init__(
         self,
         stream_url: str = "wss://stream.binance.com:9443/stream",
-        reconnect_delay: int = 5,
+        reconnect_delay: int = 5000,
         compression: int = 0,
         proxy: Optional[Dict[str, Union[str, int, Dict[str, str]]]] = None,
         mode: WebsocketMode = WebsocketMode.SINGLE,

common/src/binance_common/errors.py

@@ -8,9 +8,10 @@ class Error(Exception):
 class ClientError(Error):
     """Represents an error that occurred in the Connector client."""
 
-    def __init__(self, error_message: Optional[str] = None):
+    def __init__(self, error_message: Optional[str] = None, status_code: Optional[int] = None):
         self.error_message = error_message or "An unexpected error occurred."
-        super().__init__(error_message)
+        self.status_code = status_code
+        super().__init__(self.status_code, self.error_message)
 
 
 class RequiredError(Error):
@@ -27,43 +28,43 @@ 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):
+    def __init__(self, error_message: Optional[str] = None, status_code: Optional[int] = None):
         self.error_message = (
             error_message or "Unauthorized access. Authentication required."
         )
-        super().__init__(error_message)
-
+        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):
+    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."
         )
-        super().__init__(error_message)
-
+        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):
+    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."
         )
-        super().__init__(error_message)
-
+        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):
+    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."
         )
-        super().__init__(error_message)
-
+        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."""
@@ -89,16 +90,18 @@ 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):
+    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."
-        super().__init__(error_message)
+        self.status_code = status_code
+        super().__init__(self.status_code, self.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):
+    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."
         )
-        super().__init__(self.error_message)
+        self.status_code = status_code
+        super().__init__(self.status_code, self.error_message)

common/src/binance_common/utils.py

@@ -208,6 +208,15 @@ def get_uuid() -> str:
     return str(uuid.uuid4())
 
 
+def get_random_int() -> int:
+    """Generates a random alphanumeric string of the specified length.
+
+    Returns:
+        int: A random integer derived from a UUID.
+    """
+
+    return int(uuid.uuid4().int >> 64)
+
 def validate_time_unit(time_unit: Optional[str]) -> Optional[str]:
     """Validates the time unit against the defined TimeUnit constants.
 
@@ -276,10 +285,11 @@ def send_request(
     method: str,
     path: str,
     payload: Optional[dict] = None,
+    body: Optional[dict] = None,
     time_unit: Optional[str] = None,
     response_model: Type[T] = None,
     is_signed: bool = False,
-    signer: Optional[Signers]=None
+    signer: Optional[Signers]=None,
 ) -> ApiResponse[T]:
     """Sends an HTTP request with the specified configuration, method, path, and
     optional payload and time unit.
@@ -290,9 +300,11 @@ def send_request(
     - `method`: The HTTP method to use (e.g. "GET", "POST", etc.).
     - `path`: The API endpoint path.
     - `payload`: The request payload (optional).
+    - `body`: The body data to send with the request (optional).
     - `time_unit`: The time unit for the `X-MBX-TIME-UNIT` header (optional).
     - `response_model`: The response model to use for deserializing the response (optional).
     - `is_signed`: A boolean indicating whether the request should be signed (optional).
+    - `signer`: The signer to use for signing the request (optional).
 
     The function returns the JSON response from the server, or raises an appropriate exception if an error occurs.
     """
@@ -302,6 +314,8 @@ def send_request(
 
     if is_signed:
         cleaned_payload = clean_none_value(payload)
+        if body:
+            cleaned_payload.update(clean_none_value(body))
         cleaned_payload["timestamp"] = get_timestamp()
         query_string = encoded_string(cleaned_payload)
         cleaned_payload["signature"] = get_signature(configuration, query_string, signer)
@@ -317,7 +331,7 @@ def send_request(
 
     url = f"{configuration.base_path}{path}"
     retries = configuration.retries if configuration else 0
-    backoff = configuration.backoff if configuration else 1
+    backoff = configuration.backoff / 1000 if configuration else 1
     timeout = configuration.timeout / 1000 if configuration else 10
     proxies = (
         parse_proxies(configuration.proxy)
@@ -347,6 +361,7 @@ def send_request(
                 headers=headers,
                 timeout=timeout,
                 proxies=proxies,
+                data=encoded_string(clean_none_value(body)) if body else None,
             )
 
             if response.status_code >= 400:
@@ -360,17 +375,17 @@ def send_request(
                 )
 
                 if status == 400:
-                    raise BadRequestError(error_message=data.get("msg"))
+                    raise BadRequestError(error_message=data.get("msg"), status_code=data.get("code"))
                 elif status == 401:
-                    raise UnauthorizedError(error_message=data.get("msg"))
+                    raise UnauthorizedError(error_message=data.get("msg"), status_code=data.get("code"))
                 elif status == 403:
-                    raise ForbiddenError(error_message=data.get("msg"))
+                    raise ForbiddenError(error_message=data.get("msg"), status_code=data.get("code"))
                 elif status == 404:
-                    raise NotFoundError(error_message=data.get("msg"))
+                    raise NotFoundError(error_message=data.get("msg"), status_code=data.get("code"))
                 elif status == 418:
-                    raise RateLimitBanError(error_message=data.get("msg"))
+                    raise RateLimitBanError(error_message=data.get("msg"), status_code=data.get("code"))
                 elif status == 429:
-                    raise TooManyRequestsError(error_message=data.get("msg"))
+                    raise TooManyRequestsError(error_message=data.get("msg"), status_code=data.get("code"))
                 elif 500 <= status < 600:
                     raise ServerError(
                         error_message=f"Server error: {status}", status_code=status