v3.0.0rc1 release (#204)

* v3.0.0rc1 release

* add user data

* refactoring module file name

* refactoring doc file

.github/workflows/pythonpackage.yml

@@ -43,7 +43,7 @@ jobs:
         flake8 . --statistics
     - name: Test with pytest
       run: |
-        pytest
+        pytest tests/
     - name: Test document build
       run: |
         python -m pip install sphinx sphinx-rtd-theme

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+
+## 3.0.0rc1 - 2023-02-10
+
+### Changed
+- Redesign of Websocket part. Please consult `README.md` for details on its new usage.
+
+### Added
+- Add Websocket API
+
 ## 2.0.0 - 2023-01-18
 ### Added
 - New endpoints for wallet

README.md

@@ -12,6 +12,7 @@ This is a lightweight library that works as a connector to [Binance public API](
     - `/sapi/*`
     - Spot Websocket Market Stream
     - Spot User Data Stream
+    - Spot WebSocket API
 - Inclusion of test cases and examples
 - Customizable base URL, request timeout and HTTP proxy
 - Response metadata can be displayed
@@ -219,6 +220,65 @@ There are 2 types of error returned from the library:
 
 ## Websocket
 
+### Connector v3
+
+WebSocket can be established through either of the following types of connections:
+- WebSocket API (`https://github.com/binance/binance-spot-api-docs/blob/master/web-socket-api.md`)
+- WebSocket Stream (`https://github.com/binance/binance-spot-api-docs/blob/master/web-socket-streams.md`)
+
+```python
+
+# WebSocket API Client
+from binance.websocket.spot.websocket_api import SpotWebsocketAPIClient
+
+def message_handler(_, message):
+    logging.info(message)
+
+my_client = SpotWebsocketAPIClient(on_message=message_handler)
+
+my_client.ticker(symbol="BNBBUSD", type="FULL")
+
+time.sleep(5)
+logging.info("closing ws connection")
+my_client.stop()
+```
+
+```python
+
+# WebSocket Stream Client
+from binance.websocket.spot.websocket_stream import SpotWebsocketStreamClient
+
+def message_handler(_, message):
+    logging.info(message)
+
+my_client = SpotWebsocketStreamClient(on_message=message_handler)
+
+# Subscribe to a single symbol stream
+my_client.agg_trade(symbol="bnbusdt")
+time.sleep(5)
+logging.info("closing ws connection")
+my_client.stop()
+```
+
+#### Request Id
+
+Client can assign a request id to each request. The request id will be returned in the response message. Not mandatory in the library, it generates a uuid format string if not provided.
+
+```python
+# id provided by client
+my_client.ping_connectivity(id="my_request_id")
+
+# library will generate a random uuid string
+my_client.ping_connectivity()
+```
+
+More websocket examples are available in the `examples` folder.
+
+Example file "examples/websocket_api/app_demo.py" demonstrates how Websocket API and Websocket Stream can be used together.
+
+
+### Connector v1 and v2
+
 ```python
 from binance.websocket.spot.websocket_client import SpotWebsocketClient as WebsocketClient
 
@@ -242,7 +302,6 @@ ws_client.instant_subscribe(
 
 ws_client.stop()
 ```
-More websocket examples are available in the `examples` folder
 
 ### Heartbeat
 

binance/__version__.py

@@ -1 +1 @@
-__version__ = "2.0.0"
+__version__ = "3.0.0rc1"

binance/error.py

@@ -52,3 +52,11 @@ def __init__(self, error_message):
 
     def __str__(self):
         return self.error_message
+
+
+class WebsocketClientError(Error):
+    def __init__(self, error_message):
+        self.error_message = error_message
+
+    def __str__(self):
+        return self.error_message

binance/lib/utils.py

@@ -1,11 +1,14 @@
 import json
 import time
-
+import uuid
+from collections import OrderedDict
 from urllib.parse import urlencode
+from binance.lib.authentication import hmac_hashing
 from binance.error import (
     ParameterRequiredError,
     ParameterValueError,
     ParameterTypeError,
+    WebsocketClientError,
 )
 
 
@@ -78,3 +81,34 @@ def config_logging(logging, logging_level, log_file: str = None):
         format="%(asctime)s.%(msecs)03d UTC %(levelname)s %(name)s: %(message)s",
         datefmt="%Y-%m-%d %H:%M:%S",
     )
+
+
+def get_uuid():
+    return str(uuid.uuid4())
+
+
+def purge_map(map: map):
+    """Remove None values from map"""
+    return {k: v for k, v in map.items() if v is not None and v != "" and v != 0}
+
+
+def websocket_api_signature(api_key: str, api_secret: str, parameters: dict):
+    """Generate signature for websocket API
+    Args:
+        api_key (str): API key.
+        api_secret (str): API secret.
+        params (dict): Parameters.
+    """
+
+    if not api_key or not api_secret:
+        raise WebsocketClientError(
+            "api_key and api_secret are required for websocket API signature"
+        )
+
+    parameters["timestamp"] = get_timestamp()
+    parameters["apiKey"] = api_key
+
+    parameters = OrderedDict(sorted(parameters.items()))
+    parameters["signature"] = hmac_hashing(api_secret, urlencode(parameters))
+
+    return parameters