describe json vs protobuf, use Any for payloads

Author: FZambia

README.md

@@ -23,9 +23,23 @@ from centrifuge import Client
 
 See [example code](https://github.com/centrifugal/centrifuge-python/blob/master/example.py) and [how to run it](#run-example) locally.
 
+## JSON vs Protobuf protocols
+
+By default, SDK uses JSON protocol. If you want to use Protobuf protocol instead then pass `use_protobuf=True` option.
+
+When using JSON protocol:
+
+* all payloads (data to publish, connect/subscribe data) you pass to the library are encoded to JSON internally using `json.dumps` before sending to server. So make sure you pass only JSON-serializable data to the library.
+* all payloads received from server are decoded to Python objects using `json.loads` internally before passing to your code.
+
+When using Protobuf protocol:
+
+* all payloads you pass to the library must be `bytes` or `None` if optional. If you pass non-`bytes` data – exception will be raised.
+* all payloads received from the library will be `bytes` or `None` if not present.
+
 ## Run tests
 
-To run tests first start Centrifugo server:
+To run tests, first start Centrifugo server:
 
 ```bash
 docker run -p 8000:8000 centrifugo/centrifugo:v5 centrifugo --client_insecure --log_level debug
@@ -37,12 +51,12 @@ And then:
 python -m venv env
 . env/bin/activate
 make dev
-python -m unittest discover -s tests
+make test
 ```
 
 ## Run example
 
-Start Centrifugo with config like this (defines namespace called "example", enables features used in the example):
+To run [example](https://github.com/centrifugal/centrifuge-python/blob/master/example.py), first start Centrifugo with config like this:
 
 ```json
 {

centrifuge/__init__.py

@@ -32,8 +32,6 @@
     UnauthorizedError,
 )
 from .types import (
-    JSON,
-    BytesOrJSON,
     ClientInfo,
     HistoryResult,
     PresenceResult,
@@ -45,8 +43,6 @@
 )
 
 __all__ = [
-    "JSON",
-    "BytesOrJSON",
     "CentrifugeError",
     "Client",
     "ClientDisconnectedError",

centrifuge/__meta__.py

@@ -1 +1 @@
-__version__ = "0.3.0b1"
+__version__ = "0.3.0b2"

centrifuge/client.py

@@ -58,7 +58,6 @@
     SubscriptionEventHandler,
 )
 from centrifuge.types import (
-    BytesOrJSON,
     ClientInfo,
     HistoryResult,
     PresenceResult,
@@ -122,7 +121,7 @@ def __init__(
         max_server_ping_delay: float = 10.0,
         name: str = "python",
         version: str = "",
-        data: BytesOrJSON = None,
+        data: Any = None,
         min_reconnect_delay: float = 0.1,
         max_reconnect_delay: float = 20.0,
         loop: Any = None,
@@ -748,7 +747,7 @@ async def _future_success(self, cmd_id: int, reply):
         if cb.done:
             await cb.done
 
-    def _decode_data(self, data: BytesOrJSON):
+    def _decode_data(self, data: Any):
         if data is None:
             return None
         if self._use_protobuf:
@@ -758,7 +757,7 @@ def _decode_data(self, data: BytesOrJSON):
         else:
             return data
 
-    def _encode_data(self, data: BytesOrJSON):
+    def _encode_data(self, data: Any):
         if self._use_protobuf:
             if not isinstance(data, bytes):
                 raise CentrifugeError(
@@ -789,7 +788,7 @@ async def ready(self, timeout: Optional[float] = None) -> None:
     async def publish(
         self,
         channel: str,
-        data: BytesOrJSON,
+        data: Any,
         timeout: Optional[float] = None,
     ) -> PublishResult:
         await self.ready()
@@ -911,7 +910,7 @@ async def presence_stats(
     async def rpc(
         self,
         method: str,
-        data: BytesOrJSON,
+        data: Any,
         timeout: Optional[float] = None,
     ) -> RpcResult:
         await self.ready()
@@ -1268,7 +1267,7 @@ async def presence_stats(self, timeout: Optional[float] = None) -> PresenceStats
         # noinspection PyProtectedMember
         return await self._client.presence_stats(self.channel, timeout=timeout)
 
-    async def publish(self, data: BytesOrJSON, timeout: Optional[float] = None) -> PublishResult:
+    async def publish(self, data: Any, timeout: Optional[float] = None) -> PublishResult:
         await self.ready(timeout=timeout)
         # noinspection PyProtectedMember
         return await self._client.publish(self.channel, data, timeout=timeout)

centrifuge/contexts.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
-from typing import Optional
+from typing import Optional, Any
 
-from centrifuge.types import BytesOrJSON, ClientInfo, Publication, StreamPosition
+from centrifuge.types import ClientInfo, Publication, StreamPosition
 
 
 @dataclass
@@ -17,7 +17,7 @@ class ConnectedContext:
 
     client: str
     version: str
-    data: Optional[BytesOrJSON]
+    data: Optional[Any]
 
 
 @dataclass
@@ -134,7 +134,7 @@ class SubscribedContext:
     stream_position: Optional[StreamPosition]
     was_recovering: bool
     recovered: bool
-    data: Optional[BytesOrJSON]
+    data: Optional[Any]
 
 
 @dataclass

centrifuge/types.py

@@ -1,10 +1,5 @@
 from dataclasses import dataclass
-from typing import Dict, List, Optional, Union
-
-# JSON type represents objects which may be encoded to JSON.
-JSON = Union[Dict[str, "JSON"], List["JSON"], str, int, float, bool, None]
-# BytesOrJSON type represents objects which may be encoded to JSON or bytes.
-BytesOrJSON = Union[bytes, JSON]
+from typing import Dict, List, Optional, Any
 
 
 @dataclass
@@ -29,8 +24,8 @@ class ClientInfo:
 
     client: str
     user: str
-    conn_info: Optional[BytesOrJSON]
-    chan_info: Optional[BytesOrJSON]
+    conn_info: Optional[Any]
+    chan_info: Optional[Any]
 
 
 @dataclass
@@ -45,7 +40,7 @@ class Publication:
     """
 
     offset: int
-    data: BytesOrJSON
+    data: Any
     info: Optional[ClientInfo]
 
 
@@ -58,7 +53,7 @@ class PublishResult:
 class RpcResult:
     """RpcResult is a result of RPC operation."""
 
-    data: BytesOrJSON
+    data: Any
 
 
 @dataclass