Merge pull request #79 from tarasko/feature/ai_docs_cleanup

Feature/ai docs cleanup

Author: tarasko

README.rst

@@ -22,8 +22,8 @@ Introduction
     :target: https://deepwiki.com/tarasko/picows 
     :alt: Ask DeepWiki
 
-**picows** is a high-performance python library designed for building asyncio WebSocket clients and servers.
-Implemented in Cython, it offers exceptional speed and efficiency, surpassing other popular WebSocket python libraries.
+**picows** is a high-performance Python library designed for building asyncio WebSocket clients and servers.
+Implemented in Cython, it offers exceptional speed and efficiency, surpassing other popular Python WebSocket libraries.
 
 .. image:: https://raw.githubusercontent.com/tarasko/websocket-benchmark/master/results/benchmark-256.png
     :target: https://github.com/tarasko/websocket-benchmark/blob/master
@@ -79,7 +79,7 @@ Getting started
 
 Echo client
 -----------
-Connects to an echo server, sends a message and disconnect upon reply.
+Connects to an echo server, sends a message, and disconnects after receiving a reply.
 
 .. code-block:: python
 
@@ -147,8 +147,8 @@ Echo server
 Features
 ====================
 * Maximally efficient WebSocket frame parser and builder implemented in Cython
-* Re-use memory as much as possible, avoid reallocations, and avoid unnecessary Python object creations
-* Provide Cython .pxd for efficient integration of user Cythonized code with picows
+* Reuse memory as much as possible, avoid reallocations, and avoid unnecessary Python object creation
+* Provide a Cython .pxd for efficient integration of user Cythonized code with picows
 * Ability to check if a frame is the last one in the receiving buffer
 * Auto ping-pong with an option to customize ping/pong messages.
 * Convenient method to measure websocket roundtrip time using ping/pong messages.
@@ -174,7 +174,7 @@ Contributing / Building From Source
     # To build docs
     $ pip install -r docs/requirements.txt
 
-4. Build inplace and run tests::
+4. Build in place and run tests::
 
     $ python setup.py build_ext --inplace
     $ pytest -s -v
@@ -185,4 +185,3 @@ Contributing / Building From Source
 5. Build docs::
 
     $ make -C docs clean html
-

docs/source/guides.rst

@@ -19,13 +19,13 @@ Eager tasks do not wait for the next event loop cycle and get executed immediate
 See `echo_client_async_callbacks.py <https://raw.githubusercontent.com/tarasko/picows/master/examples/echo_client_async_callbacks.py>`_
 illustrating this approach.
 
-If you need an async get_message(), similar to what aiohttp and websockets offer, than you would have to use asyncio.Queue.
+If you need an async receive_message(), similar to what aiohttp and websockets offer, then you would have to use asyncio.Queue.
 The latency penalty will become bigger, since awaiting coroutine can only be woken up on the next event loop cycle
 and message payload will always have to be copied.
 See `echo_client_async_iteration.py <https://raw.githubusercontent.com/tarasko/picows/master/examples/echo_client_async_iteration.py>`_
 illustrating this approach.
 
-**picows** let you choose the best possible approach for your project. Very often turning async is not really necessary on
+**picows** lets you choose the best possible approach for your project. Very often turning async is not really necessary on
 the data path. With **picows** you can delay this and do it only when necessary, for example, only when you actually have to start
 some async operation.
 
@@ -77,10 +77,10 @@ debug logging.
 Exceptions handling
 -------------------
 
-When talking about how library deals with exceptions, there are 2 questions that
+When talking about how the library deals with exceptions, there are two questions that
 must be addressed:
 
-**What kinds of exceptions can the library functions throws?**
+**What kinds of exceptions can the library functions throw?**
 
 **picows** may raise any exception that the underlying system calls may raise.
 For example, `ConnectionResetError` from :any:`ws_connect` or `BrokenPipeError`
@@ -113,7 +113,7 @@ From the user's perspective, these frames function like regular frames and may c
 
 **picows** offers an efficient 'auto ping' mechanism to automatically send a PING to the remote peer after a specified period of inactivity and to handle and verify PONG responses. If no PONG is received, the WebSocket will be disconnected.
 
-This behaviour is controlled by the 3 parameters passed to :any:`ws_connect` or :any:`ws_create_server`:
+This behavior is controlled by three parameters passed to :any:`ws_connect` or :any:`ws_create_server`:
 
 .. code-block:: python
 
@@ -126,7 +126,7 @@ This behaviour is controlled by the 3 parameters passed to :any:`ws_connect` or
 
 
 Furthermore, it is possible to customize what will be ping and pong frames.
-Apart from PING/PONG msg types other common options are:
+Apart from PING/PONG message types, other common options are:
 
     * TEXT frames with 'ping' and 'pong' payload.
     * TEXT frames with full json payload like {"op": "ping"} and {"op": "pong"}
@@ -198,13 +198,13 @@ Measuring/checking round-trip time
 ----------------------------------
 `Available since 1.5`
 
-**picows** allows to conveniently measure round-trip time to a remote peer using
-:any:`measure_roundtrip_time`. This is done by sending PING request multiple
+**picows** allows you to conveniently measure round-trip time to a remote peer using
+:any:`measure_roundtrip_time`. This is done by sending PING requests multiple
 times and measuring response delay.
 
-Checkout an `okx_roundtrip_time.py <https://raw.githubusercontent.com/tarasko/picows/master/examples/okx_roundtrip_time.py>`_
+Check out `okx_roundtrip_time.py <https://raw.githubusercontent.com/tarasko/picows/master/examples/okx_roundtrip_time.py>`_
 example of how to measure RTT to a popular OKX crypto-currency exchange and initiate
-reconnect if it doesn't satisfy a predefined threshold.
+reconnect if it does not satisfy a predefined threshold.
 
 Dealing with slow clients
 -------------------------
@@ -236,7 +236,7 @@ Using proxies
 
 :any:`ws_connect` supports HTTP, SOCKS4 and SOCKS5 proxies via
 `python-socks <https://github.com/romis2012/python-socks>`_.
-Use ``proxy`` argument with a proxy URL. HTTPS proxy URLs (``https://...``)
+Use the ``proxy`` argument with a proxy URL. HTTPS proxy URLs (``https://...``)
 are not currently supported:
 
 .. code-block:: python
@@ -254,10 +254,10 @@ Hostname resolution generally happens at the proxy, unless it is SOCK4.
 SOCK4 is an old protocol, where CONNECT request doesn't support host names, only IP addresses.
 SOCK4 hostname resolution is performed at the client.
 
-Basic auth is supported. Login/password can be specified in proxy url.
+Basic auth is supported. Login and password can be specified in the proxy URL.
 
 .. _getproxies: https://docs.python.org/3/library/urllib.request.html#urllib.request.getproxies
 
-Currently **picows** doesn't attempt to use system proxy settings. If you want to use
-a system wide proxy settings, get them using `getproxies`_ and pass one as a
+Currently, **picows** does not attempt to use system proxy settings. If you want to use
+system-wide proxy settings, get them using `getproxies`_ and pass one as the
 proxy argument.

docs/source/introduction.rst

@@ -16,8 +16,8 @@ Introduction
     :target: https://picows.readthedocs.io/en/latest/
     :alt: Latest Read The Docs
 
-**picows** is a high-performance python library designed for building asyncio WebSocket clients and servers.
-Implemented in Cython, it offers exceptional speed and efficiency, surpassing other popular WebSocket python libraries.
+**picows** is a high-performance Python library designed for building asyncio WebSocket clients and servers.
+Implemented in Cython, it offers exceptional speed and efficiency, surpassing other popular Python WebSocket libraries.
 
 .. image:: https://raw.githubusercontent.com/tarasko/websocket-benchmark/master/results/benchmark-256.png
     :target: https://github.com/tarasko/websocket-benchmark/blob/master
@@ -43,7 +43,7 @@ Getting started
 
 Echo client
 -----------
-Connects to an echo server, sends a message and disconnect upon reply.
+Connects to an echo server, sends a message, and disconnects after receiving a reply.
 
 .. code-block:: python
 

docs/source/reference.rst

@@ -48,7 +48,7 @@ Classes
         :type: bool
 
         Indicates whether rsv1 flag is set in the frame.
-        Some protocol extensions use this flag to indicated that the frame data
+        Some protocol extensions use this flag to indicate that the frame data
         is compressed.
         For example in `permessage_deflate extension <https://www.rfc-editor.org/rfc/rfc7692#section-7>`_
 
@@ -103,7 +103,7 @@ Classes
     .. py:attribute:: headers
         :type: CIMultiDict[str, str]
 
-        Request headers. Keys are case insensitive
+        Request headers. Keys are case-insensitive
 
 .. autoclass:: WSUpgradeResponse
     :members:
@@ -121,12 +121,12 @@ Classes
     .. py:attribute:: headers
         :type: CIMultiDict[str, str]
 
-        Response headers. Keys are case insensitive
+        Response headers. Keys are case-insensitive
 
     .. py:attribute:: body
         :type: bytes
 
-        Optional response body. Can be non-empty in case of errors
+        Optional response body. It can be non-empty in case of errors
 
 .. autoclass:: WSUpgradeResponseWithListener
     :members:
@@ -140,8 +140,8 @@ Classes
     .. 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`
+        if it cannot be sent immediately.
+        This behavior is derived from the underlying `asyncio.WriteTransport.write`
 
     .. py:attribute:: underlying_transport
         :type: asyncio.Transport
@@ -168,17 +168,17 @@ Classes
 
         Send a frame over websocket with a message as its payload.
         This function does not copy message to prepare websocket frames.
-        It reuses message's memory and append websocket header at the front.
+        It reuses the message's memory and appends a WebSocket header at the front.
 
         .. attention::
 
-            Message's buffer should have at least 14 bytes in front of the message pointer available for writing.
+            The message buffer should have at least 14 writable bytes in front of the message pointer.
 
         :param msg_type: Message type
         :param msg_ptr: Pointer to a message payload
         :param msg_size: Size of the message payload
         :param fin: fin bit in websocket frame.
-            Indicate that the frame is the last one in the message.
+            Indicates that the frame is the last one in the message.
         :param rsv1: first reserved bit in websocket frame.
             Some protocol extensions use it to indicate that payload
             is compressed.

picows/api.py

@@ -57,17 +57,17 @@ async def ws_connect(ws_listener_factory: Callable[[], WSListener], # type: igno
                      **kwargs
                      ) -> tuple[WSTransport, WSListener]:
     """
-    Open a websocket connection to a given ParsedURL.
+    Open a WebSocket connection to a given URL.
 
     This function forwards its `kwargs` directly to
     `asyncio.loop.create_connection <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.create_connection>`_
 
     :param ws_listener_factory:
         A parameterless factory function that returns a user handler.
         User handler has to derive from :any:`WSListener`.
-    :param url: Destination ParsedURL
+    :param url: Destination URL
     :param ssl_context: optional SSLContext to override default one when
-        wss scheme is used
+        the wss scheme is used
     :param disconnect_on_exception:
         Indicates whether the client should initiate disconnect on any exception
         thrown from WSListener.on_ws_frame callbacks
@@ -95,7 +95,7 @@ async def ws_connect(ws_listener_factory: Callable[[], WSListener], # type: igno
         * PING_WHEN_IDLE - ping only if there is no new incoming data.
         * PING_PERIODICALLY - send ping at regular intervals regardless of incoming data.
     :param enable_auto_pong:
-        If enabled then picows will automatically reply to incoming PING frames.
+        If enabled, 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.
     :param extra_headers:
@@ -196,11 +196,11 @@ async def ws_create_server(ws_listener_factory: WSServerListenerFactory,
                            **kwargs
                            ) -> asyncio.Server:
     """
-    Create a websocket server listening on TCP port of the host address.
+    Create a WebSocket server listening on a TCP port at the host address.
     This function forwards its `kwargs` directly to
     `asyncio.loop.create_server <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.create_server>`_
 
-    It has a few extra parameters to control the behaviour of websocket
+    It has a few extra parameters to control WebSocket behavior.
 
     :param ws_listener_factory:
         A factory function that accepts WSUpgradeRequest object and returns one of:
@@ -251,9 +251,9 @@ async def ws_create_server(ws_listener_factory: WSServerListenerFactory,
         * PING_WHEN_IDLE - ping only if there is no new incoming data.
         * PING_PERIODICALLY - send ping at regular intervals regardless of incoming data.
     :param enable_auto_pong:
-        If enabled then picows will automatically reply to incoming PING frames.
+        If enabled, 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 the server side receives a frame that is bigger than the max size.
     :return: `asyncio.Server <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.Server>`_ object
     """
 

picows/types.py

@@ -38,7 +38,7 @@ def create_error_response(status: Union[int, HTTPStatus],
                               body: Optional[bytes] = None,
                               extra_headers: Optional[WSHeadersLike] = None) -> Any:
         """
-        Create upgrade response with error.
+        Create an upgrade response with an error.
 
         :param status: int status code or http.HTTPStatus enum value
         :param body: optional bytes-like response body
@@ -63,10 +63,10 @@ def create_redirect_response(status: Union[int, HTTPStatus],
                                  location: str,
                                  extra_headers: Optional[WSHeadersLike] = None) -> Any:
         """
-        Create upgrade response with error.
+        Create an upgrade redirect response.
 
         :param status: int status code or http.HTTPStatus enum value
-        :param body: optional bytes-like response body
+        :param location: redirect target URL
         :param extra_headers: optional additional headers
         :return: a new WSUpgradeResponse object
         """
@@ -123,7 +123,7 @@ def to_bytes(self) -> bytearray:
 
 class WSUpgradeResponseWithListener:
     """
-    Bind :any:`WSUpgradeResponse` and :any:`WSListener` objects together..
+    Bind :any:`WSUpgradeResponse` and :any:`WSListener` objects together.
     """
     __slots__ = ("response", "listener")
 
@@ -140,7 +140,7 @@ def __init__(self, response: WSUpgradeResponse, listener: Any):
 
 class WSError(RuntimeError):
     """
-    Thrown by :any:`ws_connect` on any kind of handshake errors.
+    Raised by :any:`ws_connect` for any kind of handshake error.
     """
     raw_header: Optional[bytes]
     raw_body: Optional[bytes]