picows 0.2.0__tar.gz → 0.2.2__tar.gz

{picows-0.2.0 → picows-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: picows
-Version: 0.2.0
+Version: 0.2.2
 Summary: Fast websocket client and server for asyncio
 Author-email: Taras Kozlov <tarasko.projects@gmail.com>
 Project-URL: Homepage, https://github.com/tarasko/picows
@@ -28,6 +28,18 @@ Description-Content-Type: text/x-rst
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 
+.. image:: https://github.com/tarasko/picows/workflows/run%20tests/badge.svg
+   :target: https://github.com/tarasko/picows/actions?query=workflow%3Arun-tests
+   :alt: GitHub Actions status for master branch
+
+.. image:: https://badge.fury.io/py/picows.svg
+   :target: https://pypi.org/project/picows
+   :alt: Latest PyPI package version
+
+.. image:: https://img.shields.io/pypi/dm/picows
+   :target: https://pypistats.org/packages/picows
+   :alt: Downloads count
+
 picows is a library for building WebSocket clients and servers with a focus on performance.
 
 Performance
@@ -57,9 +69,11 @@ These features come with a significant cost even when messages are small, unfrag
 
 API Design
 ----------
-The API follows low-level `transport/protocol design from asyncio <https://docs.python.org/3/library/asyncio-protocol.html#asyncio-transports-protocols>`_
-It passes frames instead of messages to a user handler. A message can potentially consist of multiple frame but it is up to user to choose the best strategy for merging frames.
-Though the most common case is when messages and frames are the same i.e. a message consists of only a single frame.
+The API follows the low-level `transport/protocol design from asyncio <https://docs.python.org/3/library/asyncio-protocol.html#asyncio-transports-protocols>`_.
+It passes frames instead of messages to a user handler. A message can potentially consist of multiple frames but it is up to user to choose the best strategy for merging them. 
+Same principle applies for compression and flow control. User can implement their own strategies using the most appropriate tools.
+
+That being said that the most common use-case is when messages and frames are the same, i.e. a message consists of only a single frame, and no compression is being used.
 
 Getting started
 ---------------
@@ -76,6 +90,7 @@ Connects to an echo server, sends a message and disconnect upon reply.
 
   class ClientListener(WSListener):
       def on_ws_connected(self, transport: WSTransport):
+          self.transport = transport
           transport.send(WSMsgType.TEXT, b"Hello world")
   
       def on_ws_frame(self, transport: WSTransport, frame: WSFrame):
@@ -84,9 +99,8 @@ Connects to an echo server, sends a message and disconnect upon reply.
 
 
   async def main(endpoint):
-    # ClientListener instance will be created after successfull accept and http upgrade.
     (_, client) = await ws_connect(endpoint, ClientListener, "client")
-    await client._transport.wait_until_closed()
+    await client.transport.wait_until_closed()
 
 
   if __name__ == '__main__':
@@ -106,7 +120,7 @@ Echo server
 
   import asyncio
   import uvloop
-  from picows import WSFrame, WSTransport, WSListener, ws_connect, WSMsgType
+  from picows import WSFrame, WSTransport, WSListener, ws_create_server, WSMsgType
 
   class ServerClientListener(WSListener):
       def on_ws_connected(self, transport: WSTransport):
@@ -119,7 +133,6 @@ Echo server
 
   async def main():
       url = "ws://127.0.0.1:9001"
-      # ServerClientListener instance will be created for each client after accept and successfull http upgrade. 
       server = await ws_create_server(url, ServerClientListener, "server")
       print(f"Server started on {url}")
       await server.serve_forever()

{picows-0.2.0 → picows-0.2.2}/README.rst

@@ -1,3 +1,15 @@
+.. image:: https://github.com/tarasko/picows/workflows/run%20tests/badge.svg
+   :target: https://github.com/tarasko/picows/actions?query=workflow%3Arun-tests
+   :alt: GitHub Actions status for master branch
+
+.. image:: https://badge.fury.io/py/picows.svg
+   :target: https://pypi.org/project/picows
+   :alt: Latest PyPI package version
+
+.. image:: https://img.shields.io/pypi/dm/picows
+   :target: https://pypistats.org/packages/picows
+   :alt: Downloads count
+
 picows is a library for building WebSocket clients and servers with a focus on performance.
 
 Performance
@@ -27,9 +39,11 @@ These features come with a significant cost even when messages are small, unfrag
 
 API Design
 ----------
-The API follows low-level `transport/protocol design from asyncio <https://docs.python.org/3/library/asyncio-protocol.html#asyncio-transports-protocols>`_
-It passes frames instead of messages to a user handler. A message can potentially consist of multiple frame but it is up to user to choose the best strategy for merging frames.
-Though the most common case is when messages and frames are the same i.e. a message consists of only a single frame.
+The API follows the low-level `transport/protocol design from asyncio <https://docs.python.org/3/library/asyncio-protocol.html#asyncio-transports-protocols>`_.
+It passes frames instead of messages to a user handler. A message can potentially consist of multiple frames but it is up to user to choose the best strategy for merging them. 
+Same principle applies for compression and flow control. User can implement their own strategies using the most appropriate tools.
+
+That being said that the most common use-case is when messages and frames are the same, i.e. a message consists of only a single frame, and no compression is being used.
 
 Getting started
 ---------------
@@ -46,6 +60,7 @@ Connects to an echo server, sends a message and disconnect upon reply.
 
   class ClientListener(WSListener):
       def on_ws_connected(self, transport: WSTransport):
+          self.transport = transport
           transport.send(WSMsgType.TEXT, b"Hello world")
   
       def on_ws_frame(self, transport: WSTransport, frame: WSFrame):
@@ -54,9 +69,8 @@ Connects to an echo server, sends a message and disconnect upon reply.
 
 
   async def main(endpoint):
-    # ClientListener instance will be created after successfull accept and http upgrade.
     (_, client) = await ws_connect(endpoint, ClientListener, "client")
-    await client._transport.wait_until_closed()
+    await client.transport.wait_until_closed()
 
 
   if __name__ == '__main__':
@@ -76,7 +90,7 @@ Echo server
 
   import asyncio
   import uvloop
-  from picows import WSFrame, WSTransport, WSListener, ws_connect, WSMsgType
+  from picows import WSFrame, WSTransport, WSListener, ws_create_server, WSMsgType
 
   class ServerClientListener(WSListener):
       def on_ws_connected(self, transport: WSTransport):
@@ -89,7 +103,6 @@ Echo server
 
   async def main():
       url = "ws://127.0.0.1:9001"
-      # ServerClientListener instance will be created for each client after accept and successfull http upgrade. 
       server = await ws_create_server(url, ServerClientListener, "server")
       print(f"Server started on {url}")
       await server.serve_forever()

picows-0.2.2/picows/__init__.py

@@ -0,0 +1,23 @@
+__version__ = "0.2.2"
+
+from .picows import (
+    WSMsgType,
+    WSCloseCode,
+    WSFrame,
+    WSTransport,
+    WSListener,
+    ws_connect,
+    ws_create_server,
+    PICOWS_DEBUG_LL
+)
+
+__all__ = [
+    'WSMsgType',
+    'WSCloseCode',
+    'WSFrame',
+    'WSTransport',
+    'WSListener',
+    'ws_connect',
+    'ws_create_server',
+    'PICOWS_DEBUG_LL'
+]

{picows-0.2.0 → picows-0.2.2}/picows/picows.pxd

@@ -59,8 +59,8 @@ cdef class WSFrame:
         readonly uint8_t fin
         readonly uint8_t last_in_buffer
 
-    # Creates a new python object every time
     cpdef bytes get_payload_as_bytes(self)
+    cpdef str get_payload_as_utf8_text(self)
     cpdef str get_payload_as_ascii_text(self)
     cpdef object get_payload_as_memoryview(self)
 

{picows-0.2.0 → picows-0.2.2}/picows/picows.pyx

@@ -23,21 +23,55 @@ from libc.stdlib cimport rand
 PICOWS_DEBUG_LL = 9
 
 
-cdef extern from "arpa/inet.h" nogil:
+cdef extern from * nogil:
+    """
+    #if (defined(_WIN16) || defined(_WIN32) || defined(_WIN64)) && !defined(__WINDOWS__)
+    #	define __WINDOWS__
+    #endif
+
+    #if defined(__linux__)
+      #include <arpa/inet.h>
+      #include <endian.h>
+    #elif defined(__APPLE__)
+      #include <arpa/inet.h>
+      #include <libkern/OSByteOrder.h>
+      #define be64toh(x) OSSwapBigToHostInt64(x)
+      #define htobe64(x) OSSwapHostToBigInt64(x)
+    #elif defined(__OpenBSD__)
+      #include <arpa/inet.h>
+      #include <sys/endian.h>
+    #elif defined(__NetBSD__) || defined(__FreeBSD__) || defined(__DragonFly__)
+      #include <arpa/inet.h>
+      #include <sys/endian.h>
+      #define be64toh(x) betoh64(x)
+    #elif defined(__WINDOWS__)
+      #include <winsock2.h>
+      #if BYTE_ORDER == LITTLE_ENDIAN
+        #define be64toh(x) ntohll(x)
+        #define htobe64(x) htonll(x)
+      #elif BYTE_ORDER == BIG_ENDIAN
+        #define be64toh(x) (x)
+        #define htobe64(x) (x)
+      #endif
+    #else
+      error byte order not supported
+    #endif
+    """
+
+    # Network order is big-endian
+
     uint32_t ntohl(uint32_t)
     uint32_t htonl(uint32_t)
     uint16_t ntohs(uint16_t)
     uint16_t htons(uint16_t)
 
-
-cdef extern from "endian.h" nogil:
-    # Network order is big-endian
     uint64_t be64toh(uint64_t)
     uint64_t htobe64(uint64_t)
 
 
 cdef extern from "Python.h":
     PyObject *PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
+    PyObject *PyUnicode_DecodeASCII(char *s, Py_ssize_t size, char *errors)
 
 
 class PicowsError(Exception):
@@ -79,15 +113,40 @@ cdef _mask_payload(uint8_t* input, size_t input_len, uint32_t mask):
 @cython.freelist(64)
 cdef class WSFrame:
     cpdef bytes get_payload_as_bytes(self):
+        """
+        Returns a new bytes object with a copy of frame payload.
+        """
         return PyBytes_FromStringAndSize(self.payload_ptr, <Py_ssize_t>self.payload_size)
 
+    cpdef str get_payload_as_utf8_text(self):
+        """
+        Interpret payload as UTF8 text and returns a new str object.
+        Behaviour is underfined (most likely python will crash) if payload doesn't contain a valid UTF8
+        """
+        cdef str s = <str>PyUnicode_FromStringAndSize(self.payload_ptr, <Py_ssize_t>self.payload_size)
+        # Workaround for broken cython reference counting
+        Py_DECREF(s)
+        return s
+
     cpdef str get_payload_as_ascii_text(self):
+        """
+        Interpret payload as UTF8 text and returns a new str object.
+        Behaviour is underfined (most likely python will crash) if payload doesn't contain a valid UTF8
+        """
+        cdef PyObject* ptr = PyUnicode_DecodeASCII(self.payload_ptr, <Py_ssize_t>self.payload_size, NULL)
+        if ptr == NULL:
+            raise PicowsError("payload doesn't contain ASCII string")
+        cdef str s = <str>ptr
         # Workaround for broken cython reference counting
-        cdef str s = <str> PyUnicode_FromStringAndSize(self.payload_ptr, <Py_ssize_t>self.payload_size)
         Py_DECREF(s)
         return s
 
     cpdef object get_payload_as_memoryview(self):
+        """
+        Return continous memoryview to a parser buffer with payload. 
+        Memoryview content will be invalidated after on_ws_frame is complete.
+        Please process payload or copy it as soon as possible.
+        """
         return PyMemoryView_FromMemory(self.payload_ptr, <Py_ssize_t>self.payload_size, PyBUF_READ)
 
     cpdef WSCloseCode get_close_code(self):
@@ -264,7 +323,7 @@ cdef class WSFrameParser:
             if rsv1 or rsv2 or rsv3:
                 mem_dump = PyBytes_FromStringAndSize(
                     self._buffer.data + self._f_curr_state_start_pos,
-                    max(self._f_new_data_start_pos - self._f_curr_state_start_pos, 64)
+                    max(self._f_new_data_start_pos - self._f_curr_state_start_pos, <size_t>64)
                 )
                 raise PicowsError(
                     WSCloseCode.PROTOCOL_ERROR,
@@ -627,7 +686,6 @@ cdef class WSProtocol:
         WSFrameParser _frame_parser
         object _loop
         object _handshake_timeout_handle
-        object _listener_factory
         bint _is_client_side
         bint _log_debug_enabled
 
@@ -641,12 +699,11 @@ cdef class WSProtocol:
         self._frame_parser = None
         self._loop = asyncio.get_running_loop()
         self._handshake_timeout_handle = None
-        self._listener_factory = ws_listener_factory
         self._is_client_side = is_client_side
         self._log_debug_enabled = self._logger.isEnabledFor(PICOWS_DEBUG_LL)
 
         self.transport = None
-        self.listener = None
+        self.listener = ws_listener_factory()
 
     def connection_made(self, transport: asyncio.Transport):
         sock = transport.get_extra_info('socket')
@@ -654,24 +711,27 @@ cdef class WSProtocol:
         sockname = transport.get_extra_info('sockname')
 
         sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
-        sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_QUICKACK, 1)
+        if hasattr(socket, "TCP_QUICKACK"):
+            sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_QUICKACK, 1)
 
         self._logger = self._logger.getChild(str(sock.fileno()))
         self._frame_parser = WSFrameParser(self._logger)
 
+        quickack = sock.getsockopt(socket.IPPROTO_TCP, socket.TCP_QUICKACK) if hasattr(socket, "TCP_QUICKACK") else False
+
         if self._is_client_side:
             self._logger.info("WS connection established: %s -> %s, recvbuf=%d, sendbuf=%d, quickack=%d, nodelay=%d",
                               peername, sockname,
                               sock.getsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF),
                               sock.getsockopt(socket.SOL_SOCKET, socket.SO_SNDBUF),
-                              sock.getsockopt(socket.IPPROTO_TCP, socket.TCP_QUICKACK),
+                              quickack,
                               sock.getsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY))
         else:
             self._logger.info("New connection accepted: %s -> %s, recvbuf=%d, sendbuf=%d, quickack=%d, nodelay=%d",
                               peername, sockname,
                               sock.getsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF),
                               sock.getsockopt(socket.SOL_SOCKET, socket.SO_SNDBUF),
-                              sock.getsockopt(socket.IPPROTO_TCP, socket.TCP_QUICKACK),
+                              quickack,
                               sock.getsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY))
 
 
@@ -717,8 +777,6 @@ cdef class WSProtocol:
                 self._frame_parser.handshake_complete_future.set_result(None)
                 self._handshake_timeout_handle.cancel()
                 self._handshake_timeout_handle = None
-                self.listener = self._listener_factory()
-                self._listener_factory = None
                 self.listener.on_ws_connected(self.transport)
 
         cdef WSFrame frame = self._get_next_frame()
@@ -793,7 +851,7 @@ async def ws_connect(str url, ws_listener_factory, str logger_name, ssl_context=
     else:
         raise ValueError(f"invalid url scheme: {url}")
 
-    ws_protocol_factory = lambda: WSProtocol(url_parts.netloc, url_parts.path, True, None, logger_name)
+    ws_protocol_factory = lambda: WSProtocol(url_parts.netloc, url_parts.path, True, ws_listener_factory, logger_name)
 
     cdef WSProtocol ws_protocol
 
@@ -802,7 +860,6 @@ async def ws_connect(str url, ws_listener_factory, str logger_name, ssl_context=
         ssl_handshake_timeout=ssl_handshake_timeout, ssl_shutdown_timeout=ssl_shutdown_timeout)
 
     await ws_protocol.wait_until_handshake_complete()
-    ws_protocol.listener = ws_listener_factory()
     ws_protocol.listener.on_ws_connected(ws_protocol.transport)
 
     return ws_protocol.transport, ws_protocol.listener

{picows-0.2.0 → picows-0.2.2}/picows.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: picows
-Version: 0.2.0
+Version: 0.2.2
 Summary: Fast websocket client and server for asyncio
 Author-email: Taras Kozlov <tarasko.projects@gmail.com>
 Project-URL: Homepage, https://github.com/tarasko/picows
@@ -28,6 +28,18 @@ Description-Content-Type: text/x-rst
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 
+.. image:: https://github.com/tarasko/picows/workflows/run%20tests/badge.svg
+   :target: https://github.com/tarasko/picows/actions?query=workflow%3Arun-tests
+   :alt: GitHub Actions status for master branch
+
+.. image:: https://badge.fury.io/py/picows.svg
+   :target: https://pypi.org/project/picows
+   :alt: Latest PyPI package version
+
+.. image:: https://img.shields.io/pypi/dm/picows
+   :target: https://pypistats.org/packages/picows
+   :alt: Downloads count
+
 picows is a library for building WebSocket clients and servers with a focus on performance.
 
 Performance
@@ -57,9 +69,11 @@ These features come with a significant cost even when messages are small, unfrag
 
 API Design
 ----------
-The API follows low-level `transport/protocol design from asyncio <https://docs.python.org/3/library/asyncio-protocol.html#asyncio-transports-protocols>`_
-It passes frames instead of messages to a user handler. A message can potentially consist of multiple frame but it is up to user to choose the best strategy for merging frames.
-Though the most common case is when messages and frames are the same i.e. a message consists of only a single frame.
+The API follows the low-level `transport/protocol design from asyncio <https://docs.python.org/3/library/asyncio-protocol.html#asyncio-transports-protocols>`_.
+It passes frames instead of messages to a user handler. A message can potentially consist of multiple frames but it is up to user to choose the best strategy for merging them. 
+Same principle applies for compression and flow control. User can implement their own strategies using the most appropriate tools.
+
+That being said that the most common use-case is when messages and frames are the same, i.e. a message consists of only a single frame, and no compression is being used.
 
 Getting started
 ---------------
@@ -76,6 +90,7 @@ Connects to an echo server, sends a message and disconnect upon reply.
 
   class ClientListener(WSListener):
       def on_ws_connected(self, transport: WSTransport):
+          self.transport = transport
           transport.send(WSMsgType.TEXT, b"Hello world")
   
       def on_ws_frame(self, transport: WSTransport, frame: WSFrame):
@@ -84,9 +99,8 @@ Connects to an echo server, sends a message and disconnect upon reply.
 
 
   async def main(endpoint):
-    # ClientListener instance will be created after successfull accept and http upgrade.
     (_, client) = await ws_connect(endpoint, ClientListener, "client")
-    await client._transport.wait_until_closed()
+    await client.transport.wait_until_closed()
 
 
   if __name__ == '__main__':
@@ -106,7 +120,7 @@ Echo server
 
   import asyncio
   import uvloop
-  from picows import WSFrame, WSTransport, WSListener, ws_connect, WSMsgType
+  from picows import WSFrame, WSTransport, WSListener, ws_create_server, WSMsgType
 
   class ServerClientListener(WSListener):
       def on_ws_connected(self, transport: WSTransport):
@@ -119,7 +133,6 @@ Echo server
 
   async def main():
       url = "ws://127.0.0.1:9001"
-      # ServerClientListener instance will be created for each client after accept and successfull http upgrade. 
       server = await ws_create_server(url, ServerClientListener, "server")
       print(f"Server started on {url}")
       await server.serve_forever()

{picows-0.2.0 → picows-0.2.2}/picows.egg-info/SOURCES.txt

@@ -9,4 +9,5 @@ picows.egg-info/PKG-INFO
 picows.egg-info/SOURCES.txt
 picows.egg-info/dependency_links.txt
 picows.egg-info/requires.txt
-picows.egg-info/top_level.txt
+picows.egg-info/top_level.txt
+tests/test_echo.py

{picows-0.2.0 → picows-0.2.2}/setup.py

@@ -7,8 +7,13 @@ vi = sys.version_info
 if vi < (3, 8):
     raise RuntimeError('picows requires Python 3.8 or greater')
 
+if os.name == 'nt':
+    libraries = ["Ws2_32"]
+else:
+    libraries = None
+
 cython_modules = [
-    Extension("picows.picows", ["picows/picows.pyx"])
+    Extension("picows.picows", ["picows/picows.pyx"], libraries=libraries)
     ]
 
 if os.getenv("PICOWS_BUILD_EXAMPLES") is not None:
@@ -17,8 +22,8 @@ if os.getenv("PICOWS_BUILD_EXAMPLES") is not None:
 setup(
     ext_modules=cythonize(
         cython_modules,
-        compiler_directives = {
-            'language_level' : sys.version_info[0],
+        compiler_directives={
+            'language_level': sys.version_info[0],
             'profile': False,
             'nonecheck': False,
             'boundscheck': False,
@@ -31,4 +36,3 @@ setup(
         gdb_debug=False
     )
 )
-

picows-0.2.2/tests/test_echo.py

@@ -0,0 +1,76 @@
+import asyncio
+import os
+
+import pytest_asyncio
+
+import picows
+import pytest
+
+URL = "ws://127.0.0.1:9001"
+
+
+class WSFrameMaterialized:
+    def __init__(self, frame: picows.WSFrame):
+        self.opcode = frame.opcode
+        self.payload_as_bytes = frame.get_payload_as_bytes()
+        self.payload_as_bytes_from_mv = bytes(frame.get_payload_as_memoryview())
+        self.fin = frame.fin
+
+
+#@pytest.fixture(scope="module")
+@pytest.fixture
+async def echo_server():
+    class PicowsServerListener(picows.WSListener):
+        def on_ws_connected(self, transport: picows.WSTransport):
+            print("echo_server:on_ws_connected")
+            self._transport = transport
+
+        def on_ws_frame(self, transport: picows.WSTransport, frame: picows.WSFrame):
+            print("echo_server:on_ws_frame")
+            self._transport.send(frame.opcode, frame.get_payload_as_bytes())
+            if frame.opcode == picows.WSMsgType.CLOSE:
+                self._transport.disconnect()
+
+    server = await picows.ws_create_server(URL, PicowsServerListener, "server")
+    task = asyncio.create_task(server.serve_forever())
+    print("initiated module level echo server")
+    yield server
+
+    # Teardown server
+    task.cancel()
+    try:
+        await(task)
+    except:
+        pass
+
+    print("stopped module level echo server")
+
+
+# @pytest.fixture(scope="module")
+@pytest.fixture
+async def echo_client(echo_server):
+    class PicowsClientListener(picows.WSListener):
+        def on_ws_connected(self, transport: picows.WSTransport):
+            self.transport = transport
+            self.msg_queue = asyncio.Queue()
+
+        def on_ws_frame(self, transport: picows.WSTransport, frame: picows.WSFrame):
+            self.msg_queue.put_nowait(WSFrameMaterialized(frame))
+
+    (_, client) = await picows.ws_connect(URL, PicowsClientListener, "client")
+    yield client
+
+    # Teardown client
+    client.transport.disconnect()
+    await client.transport.wait_until_closed()
+
+
+@pytest.mark.parametrize("msg_size", [32, 1024, 20000])
+async def test_echo(echo_client, msg_size):
+    msg = os.urandom(msg_size)
+    echo_client.transport.send(picows.WSMsgType.BINARY, msg)
+    frame: WSFrameMaterialized = await echo_client.msg_queue.get()
+    assert frame.opcode == picows.WSMsgType.BINARY
+    assert frame.payload_as_bytes == msg
+    # assert frame.payload_as_ascii_text == msg.decode("ascii")
+    assert frame.payload_as_bytes_from_mv == msg

picows-0.2.0/picows/__init__.py

@@ -1,12 +0,0 @@
-__version__ = "0.2.0"
-
-from .picows import (
-    WSMsgType,
-    WSCloseCode,
-    WSFrame,
-    WSTransport,
-    WSListener,
-    ws_connect,
-    ws_create_server,
-    PICOWS_DEBUG_LL
-)