Merge pull request #46 from tarasko/feature/45_clarify_docs

Feature/45 clarify send behavior in docs

Author: tarasko

docs/source/reference.rst

@@ -136,14 +136,20 @@ Classes
 .. autoclass:: WSTransport
     :members:
 
+    .. note::
+
+        All `send` methods never block. The data is buffered and arranged to be sent out asynchronously in case
+        if it can't be sent immediately.
+        This behaviour is derived from the underlying `asyncio.WriteTransport.write`
+
     .. py:attribute:: underlying_transport
         :type: asyncio.Transport
 
         Underlying TCP or SSL transport. Can be used to set buffer limits, check connection state, etc.
 
         .. note::
 
-            Please don't use it to send data. Use only WSTransport.send_* methods to send frames.
+            Please don't use it to send data. Use only `WSTransport.send` methods to send frames.
 
     .. py:attribute:: request
         :type: WSUpgradeRequest

examples/echo_client_benchmark.py

@@ -56,7 +56,6 @@ def on_ws_connected(self, transport: WSTransport):
             self._transport.send(WSMsgType.BINARY, msg)
 
         def on_ws_frame(self, transport: WSTransport, frame: WSFrame):
-            global result
             self._cnt += 1
 
             if time() - self._start_time >= duration:
@@ -130,7 +129,6 @@ async def aiohttp_main(url: str, data: bytes, duration: int, ssl_context):
 
 
 def run_for_websockets_library(plain_url, ssl_url, ssl_context, msg, duration):
-    global NAMES, RPS
     _, rps = asyncio.run(websockets_main(plain_url, msg, duration, None))
     RPS["plain"].append(rps)
     name, rps = asyncio.run(websockets_main(ssl_url, msg, duration, ssl_context))
@@ -139,7 +137,6 @@ def run_for_websockets_library(plain_url, ssl_url, ssl_context, msg, duration):
 
 
 def run_for_aiohttp_library(plain_url, ssl_url, ssl_context, msg, duration):
-    global NAMES, RPS
     _, rps = asyncio.run(aiohttp_main(plain_url, msg, duration, None))
     RPS["plain"].append(rps)
     name, rps = asyncio.run(aiohttp_main(ssl_url, msg, duration, ssl_context))
@@ -148,7 +145,6 @@ def run_for_aiohttp_library(plain_url, ssl_url, ssl_context, msg, duration):
 
 
 def run_picows_client(plain_url, ssl_url, ssl_context, msg, duration):
-    global NAMES, RPS
     _, rps = asyncio.run(picows_main(plain_url, msg, duration, None))
     RPS["plain"].append(rps)
     name, rps = asyncio.run(picows_main(ssl_url, msg, duration, ssl_context))
@@ -157,22 +153,18 @@ def run_picows_client(plain_url, ssl_url, ssl_context, msg, duration):
 
 
 def run_picows_cython_plain_client(plain_url, ssl_url, ssl_context, msg, duration):
-    global NAMES, RPS
     print("Run picows cython plain client")
     rps = asyncio.run(picows_main_cython(plain_url, msg, duration, None))
     RPS["plain"].append(rps)
 
 
 def run_picows_cython_ssl_client(plain_url, ssl_url, ssl_context, msg, duration):
-    global NAMES, RPS
     print("Run picows cython ssl client")
     rps = asyncio.run(picows_main_cython(ssl_url, msg, duration, ssl_context))
     RPS["ssl"].append(rps)
 
 
 def run_boost_beast_client(args):
-    global NAMES, RPS
-
     print("Run boost.beast plain client")
     pr = subprocess.run([args.boost_client, b"0",
                          args.host.encode(),

picows/picows.pyx

@@ -1605,8 +1605,7 @@ async def ws_connect(ws_listener_factory: Callable[[], WSListener],
     :param enable_auto_pong:
         If enabled then picows will automatically reply to incoming PING frames.
     :param max_frame_size:
-        * Maximum allowed frame size. Disconnect will be initiated if client receives
-        a frame that is bigger than max size.
+        * Maximum allowed frame size. Disconnect will be initiated if client receives a frame that is bigger than max size.
     :param extra_headers:
         Arbitrary HTTP headers to add to the handshake request.
     :return: :any:`WSTransport` object and a user handler returned by `ws_listener_factory()`
@@ -1722,8 +1721,7 @@ async def ws_create_server(ws_listener_factory: WSServerListenerFactory,
     :param enable_auto_pong:
         If enabled then picows will automatically reply to incoming PING frames.
     :param max_frame_size:
-        * Maximum allowed frame size. Disconnect will be initiated if server side receives
-        frame that is bigger than max size.
+        * Maximum allowed frame size. Disconnect will be initiated if server side receives frame that is bigger than max size.
     :return: `asyncio.Server <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.Server>`_ object
     """