simple-socket-client 2.0__py3-none-any.whl

simple_socket_client/__init__.py

@@ -0,0 +1,302 @@
+"""
+Simple TCP socket client built on select().
+
+The client keeps its connection in a background thread: send() queues the bytes
+for that thread, which polls the socket and calls the handlers registered for its
+events. No third-party networking code is involved, the only runtime dependency
+is the event bus used to dispatch those events.
+
+Copyright (c) 2023–2026 webtoucher
+Distributed under the BSD 3-Clause license. See LICENSE.md for more info.
+"""
+
+import queue
+import select
+import socket
+import threading
+
+from collections import deque
+from typing import Deque, Optional
+
+from event_bus import EventBus
+
+__all__ = ["SimpleSocketClient", "SimpleSocketClientException"]
+
+__version__ = "2.0"
+
+#: Size of a single recv() chunk; a message event carries one such chunk.
+_RECV_SIZE = 1024
+
+#: How long select() waits for socket activity, in seconds.
+_POLL_INTERVAL = 0.1
+
+#: How long disconnect() waits for the queued messages before it lets them go.
+_DRAIN_TIMEOUT = 5.0
+
+
+class SimpleSocketClientException(socket.error):
+    """Raised when the connection cannot be opened or is not available."""
+
+
+class SimpleSocketClient(EventBus):
+    """TCP client dispatching events through an event bus.
+
+    Events, in the order they may arrive:
+
+    ``connect(host, port)``
+        The connection is open. Emitted by connect(), so it is called from the
+        thread that called connect().
+    ``message(data)``
+        A chunk of bytes has been received.
+    ``disconnect(host, port)``
+        The connection is closed: the server closed it, reset it, a send failed
+        or disconnect() was called. Queued messages are delivered before it.
+    ``error(error)``
+        A socket error occurred; the connection is closed right after and
+        ``disconnect`` follows.
+
+    Every handler but the ``connect`` one is called from the thread that serves
+    the connection, one at a time, so a slow handler delays reading and writing.
+    **Handlers must not raise**: the exception breaks the serving loop, the
+    connection is closed and the exception is printed by the threading module.
+    """
+
+    def __init__(self, host: str, port: int) -> None:
+        super().__init__()
+        self.__host = host
+        self.__port = port
+        self.__socket: Optional[socket.socket] = None
+        self.__thread: Optional[threading.Thread] = None
+        self.__pending = bytearray()
+        self.__answers: Deque[queue.Queue] = deque()
+        self.__closing = False
+        self.__lock = threading.Lock()
+
+    @property
+    def is_connected(self) -> bool:
+        """True while the connection is open and serving messages."""
+        return self.__socket is not None and not self.__closing
+
+    @property
+    def host(self) -> str:
+        """Host the client connects to."""
+        return self.__host
+
+    @property
+    def port(self) -> int:
+        """Port the client connects to."""
+        return self.__port
+
+    def connect(self, timeout: Optional[float] = None) -> None:
+        """Open the connection to host:port.
+
+        The call blocks until the connection is established or fails. timeout is
+        passed to the socket, so None waits as long as the system allows.
+        A rejected, unreachable or timed out connection raises
+        SimpleSocketClientException.
+
+        A second connect() on a live connection raises RuntimeError; after
+        disconnect() the previous queue is delivered first.
+        """
+        if self.is_connected:
+            raise RuntimeError("the client is already connected")
+        thread = self.__thread
+        if thread is not None and thread.is_alive():
+            # The previous connection is still draining its queue.
+            self.__wait_closed(thread)
+        sock = socket.socket(
+            socket.AF_INET,
+            socket.SOCK_STREAM,
+            socket.IPPROTO_TCP,
+        )
+        try:
+            sock.settimeout(timeout)
+            sock.connect((self.__host, self.__port))
+            sock.setblocking(False)
+        except socket.timeout as error:
+            sock.close()
+            raise SimpleSocketClientException(
+                "connection to %s:%s timed out" % (self.__host, self.__port)
+            ) from error
+        except OSError as error:
+            sock.close()
+            raise SimpleSocketClientException(
+                "cannot connect to %s:%s" % (self.__host, self.__port)
+            ) from error
+        with self.__lock:
+            self.__socket = sock
+            self.__pending.clear()
+            self.__closing = False
+        self.__thread = threading.Thread(target=self.__serve, args=(sock,), daemon=True)
+        self.__thread.start()
+        self.emit("connect", self.__host, self.__port)
+
+    def disconnect(self) -> None:
+        """Close the connection gracefully.
+
+        The socket stops being read, the messages already queued by send() are
+        delivered, and only then the socket is closed and the ``disconnect``
+        event is emitted. A call from another thread waits for that to finish, for
+        up to 5 seconds (_DRAIN_TIMEOUT): a server that stopped reading makes the
+        rest of the queue be dropped. A call from an event handler only raises
+        the flag, the serving thread closes the socket itself.
+
+        Calling it on a closed client does nothing.
+        """
+        with self.__lock:
+            if self.__socket is None:
+                return
+            self.__closing = True
+            thread = self.__thread
+        if thread is None or thread is threading.current_thread():
+            return
+        self.__wait_closed(thread)
+
+    def send(self, message: bytes) -> None:
+        """Queue message for delivery to the server.
+
+        The socket is non-blocking, so the bytes are buffered and the unwritten
+        tail is retried on the next poll; a message larger than the socket buffer
+        is delivered in full. Empty messages are ignored.
+
+        Safe to call from another thread: delivery happens during the next poll,
+        so it may take up to the poll interval. Raises
+        SimpleSocketClientException when the client is not connected.
+        """
+        if not message:
+            return
+        with self.__lock:
+            if self.__socket is None or self.__closing:
+                raise SimpleSocketClientException("the client is not connected")
+            self.__pending.extend(message)
+
+    def ask(self, message: bytes, timeout: Optional[float] = 1.) -> bytes:
+        """Send message and return the first chunk of the answer.
+
+        The call blocks until data arrives: TimeoutError when nothing comes
+        within timeout, SimpleSocketClientException when the client is not
+        connected or the connection is closed while waiting. The chunk is
+        emitted through the ``message`` event as well, so the two ways of
+        receiving it see the same bytes. When several threads wait at once, each
+        chunk goes to the oldest of them.
+        """
+        waiter: queue.Queue = queue.Queue()
+        with self.__lock:
+            self.__answers.append(waiter)
+        try:
+            self.send(message)
+            try:
+                answer = waiter.get(timeout=timeout)
+            except queue.Empty:
+                raise TimeoutError(
+                    "no answer from %s:%s in %s seconds"
+                    % (self.__host, self.__port, timeout)
+                ) from None
+        finally:
+            with self.__lock:
+                if waiter in self.__answers:
+                    self.__answers.remove(waiter)
+        if answer is None:
+            raise SimpleSocketClientException("the connection is closed")
+        return answer
+
+    def __serve(self, sock: socket.socket) -> None:
+        """Poll the socket, write the queue and hand the answers over."""
+        try:
+            while True:
+                with self.__lock:
+                    pending = bool(self.__pending)
+                    if self.__closing and not pending:
+                        break
+                try:
+                    readable, writable, _ = select.select(
+                        [] if self.__closing else [sock],
+                        [sock] if pending else [],
+                        [],
+                        _POLL_INTERVAL,
+                    )
+                except (OSError, ValueError) as error:
+                    # select() broke: the socket was closed behind our back or
+                    # is unusable, so the connection cannot be served any more.
+                    self.emit("error", error)
+                    break
+                if writable and not self.__flush(sock):
+                    break
+                if readable and not self.__receive(sock):
+                    break
+        finally:
+            self.__close(sock)
+
+    def __flush(self, sock: socket.socket) -> bool:
+        """Write as much of the queue as the socket accepts. False on failure."""
+        failure: Optional[OSError] = None
+        with self.__lock:
+            if not self.__pending:
+                return True
+            try:
+                sent = sock.send(self.__pending)
+            except BlockingIOError:
+                # The kernel buffer is full again; the tail stays queued.
+                return True
+            except OSError as error:
+                failure = error
+            else:
+                del self.__pending[:sent]
+        if failure is None:
+            return True
+        self.emit("error", failure)
+        return False
+
+    def __receive(self, sock: socket.socket) -> bool:
+        """Read one chunk. False when the connection cannot be served anymore."""
+        try:
+            data = sock.recv(_RECV_SIZE)
+        except BlockingIOError:
+            # select() woke us up for nothing; try again on the next poll.
+            return True
+        except OSError as error:
+            self.emit("error", error)
+            return False
+        if not data:
+            # An empty chunk means the server closed its end of the connection.
+            # The messages queued for it are still delivered before the socket
+            # goes, the way a half-closed connection can still be written to.
+            with self.__lock:
+                self.__closing = True
+            return True
+        self.__deliver(data)
+        return True
+
+    def __deliver(self, data: bytes) -> None:
+        """Hand the chunk over to the oldest ask() waiting and emit the event."""
+        with self.__lock:
+            waiter = self.__answers.popleft() if self.__answers else None
+        if waiter is not None:
+            waiter.put(data)
+        self.emit("message", data)
+
+    def __close(self, sock: socket.socket) -> None:
+        """Drop the connection, release the waiting ask() calls and close."""
+        with self.__lock:
+            if self.__socket is not sock:
+                return
+            self.__socket = None
+            self.__closing = True
+            self.__pending.clear()
+            waiters, self.__answers = list(self.__answers), deque()
+        for waiter in waiters:
+            waiter.put(None)
+        try:
+            self.emit("disconnect", self.__host, self.__port)
+        finally:
+            sock.close()
+
+    def __wait_closed(self, thread: threading.Thread) -> None:
+        """Wait until the serving loop has written its queue and closed."""
+        thread.join(_DRAIN_TIMEOUT)
+        if not thread.is_alive():
+            return
+        # The server stopped reading: let the queue go instead of waiting.
+        with self.__lock:
+            self.__pending.clear()
+        thread.join()

simple_socket_client-2.0.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: simple-socket-client
+Version: 2.0
+Summary: Simple TCP socket client with select
+Author-email: Alexey Kuznetsov <mirakuru@webtoucher.ru>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/webtoucher/simple-socket-client
+Project-URL: Repository, https://github.com/webtoucher/simple-socket-client
+Project-URL: Issues, https://github.com/webtoucher/simple-socket-client/issues
+Project-URL: Changelog, https://github.com/webtoucher/simple-socket-client/blob/master/CHANGELOG.md
+Keywords: socket,tcp,client,networking,event-driven
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: event-bus~=1.0.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# Simple TCP socket client with select
+
+![License](https://img.shields.io/badge/License-BSD%203--Clause-green)
+[![Downloads](https://img.shields.io/pypi/dm/simple-socket-client.svg?color=orange)](https://pypi.python.org/pypi/simple-socket-client)
+[![Latest Version](https://img.shields.io/pypi/v/simple-socket-client.svg)](https://pypi.python.org/pypi/simple-socket-client)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/simple-socket-client.svg)](https://pypi.python.org/pypi/simple-socket-client)
+[![tests](https://github.com/webtoucher/simple-socket-client/actions/workflows/tests.yml/badge.svg)](https://github.com/webtoucher/simple-socket-client/actions/workflows/tests.yml)
+
+A TCP client that keeps one connection in a background thread on a `select()` poll
+with no networking framework underneath: you subscribe handlers to events and the
+client calls them. Type hints are shipped with the package, the only runtime
+dependency is the event bus that dispatches those events.
+
+## Installation
+
+Install it with pip:
+
+```shell
+$ pip install simple-socket-client
+```
+
+Or you can add it as dependency in requirements.txt file of your python application:
+
+```
+simple-socket-client~=2.0
+```
+
+## Usage
+
+```python
+from simple_socket_client import SimpleSocketClient
+
+client = SimpleSocketClient('192.168.0.2', 6666)
+
+
+@client.on('message')
+def on_message(data: bytes):
+    print('Incoming data:', data)
+
+
+@client.on('disconnect')
+def on_disconnect(host, port):
+    print('Connection to %s:%s is closed' % (host, port))
+
+
+client.connect(timeout=10)
+
+client.send(b'Test')            # if you don't need an answer
+answer = client.ask(b'Hi!')
+print(answer.decode())
+
+client.disconnect()
+```
+
+`connect()` blocks the calling thread until the connection is established and
+raises `SimpleSocketClientException` when it fails, so there is no need to wait
+for the `connect` event to start using the client.
+
+`ask()` is a shorthand for "send and wait for the first chunk of the answer":
+
+```python
+answer = client.ask(b'PING\r\n', timeout=5)
+if answer == b'PONG\r\n':
+    print('the server is alive')
+```
+
+The same client works against [`simple-socket-server`](https://pypi.org/project/simple-socket-server/)
+and any other TCP server:
+
+```python
+from simple_socket_server import SimpleSocketServer
+
+server = SimpleSocketServer()
+
+
+@server.on('message')
+def on_message(sock, peer, data):
+    server.send(sock, b'Hi, ' + data)
+
+
+server.run(host='0.0.0.0', port=6666)
+```
+
+## Events
+
+Handlers are called one at a time from the thread that serves the connection;
+the `connect` handler is the exception, it is called by `connect()` itself.
+
+| Event        | Arguments       | When it fires                                                                 |
+|--------------|-----------------|-------------------------------------------------------------------------------|
+| `connect`    | `host, port`    | the connection is open                                                        |
+| `message`    | `data`          | a chunk of bytes has been received                                            |
+| `disconnect` | `host, port`    | the connection is closed; the messages queued by `send()` were delivered first |
+| `error`      | `error`         | a socket error occurred; the connection is closed and `disconnect` follows    |
+
+`data` is `bytes`, `error` is an `OSError`.
+
+## API
+
+| Member                                   | Description                                                           |
+|------------------------------------------|-----------------------------------------------------------------------|
+| `SimpleSocketClient(host, port)`         | a client for one address; nothing is opened until `connect()`         |
+| `connect(timeout=None)`                  | open the connection; blocks, `SimpleSocketClientException` on failure |
+| `disconnect()`                           | stop reading, deliver the queue, then close the connection            |
+| `send(message)`                          | queue `bytes` for the server                                          |
+| `ask(message, timeout=1.)`               | send `bytes` and return the first chunk of the answer                 |
+| `is_connected`                           | `True` while the connection is open and serving messages              |
+| `host`, `port`                           | the address the client connects to                                    |
+| `on(event)`, `emit(...)`                 | inherited from `event_bus.EventBus`                                   |
+
+Notes:
+
+- `connect()` raises `RuntimeError` for a live connection: one client object
+  serves one connection at a time. After `disconnect()` it can be called again,
+  and the queue of the previous connection is delivered first.
+- `send()` never blocks and never truncates: the socket is non-blocking, so the
+  bytes are buffered and the unwritten tail is retried on the next poll, so a
+  message larger than the socket buffer arrives in full.
+- `send()` and `disconnect()` are safe to call from another thread. Delivery
+  happens during the next poll, so it can take up to the poll interval (0.1 s).
+- `disconnect()` delivers the messages already queued, so a `send()` followed by
+  a `disconnect()` still reaches the server. From another thread the call waits
+  for that to finish, for up to 5 seconds: a server that stopped reading makes the
+  rest of the queue be dropped. From an event handler it only raises the flag and
+  the serving thread closes the socket itself.
+- **A handler must not raise.** The exception breaks the serving loop, the
+  connection is closed and `message` never arrives again; the exception itself is
+  printed by the `threading` module. Do the long work in your own thread and
+  handle per-message errors inside the handler.
+- `message` carries one raw `recv()` chunk of up to 1024 bytes. There is no
+  framing: the protocol you put on top has to delimit its own messages, and
+  `ask()` returns one chunk, which may hold more than the answer or less than a
+  full line.
+- `ask()` and a `message` handler see the same chunk. `ask()` raises
+  `TimeoutError` when nothing comes within the timeout and
+  `SimpleSocketClientException` when the connection is closed while waiting.
+- The serving thread is a daemon, so a forgotten `disconnect()` does not keep the
+  interpreter alive; the messages that were not written yet are lost then.
+- Do not call `sock.close()` yourself: the client owns the socket and drops it
+  with an `error` event of `select()` if it goes away behind its back.
+
+## Compatibility
+
+- Python **3.9 and newer**, including free-threaded builds: CI runs every version
+  from 3.9 to 3.15 plus the free-threaded `3.13t`.
+- One runtime dependency: [`event-bus`](https://pypi.org/project/event-bus/).
+- Type hints are shipped with the package (`py.typed`, PEP 561), so mypy and
+  pyright see real signatures instead of `Any`.
+- Any client instance is independent: several clients may serve several
+  connections in one process.
+
+## Development
+
+```shell
+$ python -m venv .venv
+$ .venv\Scripts\activate          # Windows; on POSIX: source .venv/bin/activate
+$ pip install -e ".[dev]"          # installs the package and pytest
+$ python -m pytest
+```
+
+The test suite covers:
+
+- the lifecycle: `connect`, `is_connected`, `host`, `port`, a rejected
+  connection, a second `connect()` on a live connection and a reconnect after a
+  graceful close,
+- the message flow: the `message` event for data the server sends on its own,
+  `ask()` round trips, `send()` ordering and a 256 KiB payload in both directions,
+- concurrency: several threads calling `send()` at once,
+- disconnects: the queue delivered before `disconnect()` closes the connection, an
+  idempotent `disconnect()`, a close and a reset by the server, and `ask()` that
+  waits when the connection goes away,
+- error handling: `send()` and `ask()` on a closed client, an empty message, an
+  `ask()` timeout, and a handler that raises,
+- the public API: `__all__`, the version and the package metadata.
+
+Project layout:
+
+```
+simple_socket_client/__init__.py  the whole library
+tests/                            test suite
+pyproject.toml                    metadata, build config and pytest settings
+.github/workflows/                CI: tests on Python 3.9-3.15 and 3.13t, release pipeline
+```
+
+To build and verify a release:
+
+```shell
+$ pip install build twine
+$ python -m build
+$ python -m twine check dist/*
+```
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md). GitHub Releases are generated from the matching
+entry of that file, so the history is available both in git and on the releases
+page.
+
+## License
+
+Distributed under the BSD 3-Clause license. See [LICENSE.md](LICENSE.md) for details.

simple_socket_client-2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+simple_socket_client/__init__.py,sha256=m66RyZ-aS9moaqDNWpYvZurF9Q6XP03R3cAjZO2yxAU,11566
+simple_socket_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simple_socket_client-2.0.dist-info/licenses/LICENSE.md,sha256=viUOCJf97qThnFWXx3lGwpWwhWfuo8ug8QQAHtAFh8c,1496
+simple_socket_client-2.0.dist-info/METADATA,sha256=Gz7flsvCTNLwqa57j9Nh4GP186CNA9JuwWAxCXPvnxQ,10386
+simple_socket_client-2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+simple_socket_client-2.0.dist-info/top_level.txt,sha256=KrID74qMjx5n9HChIxZbXInlAYezvB0-ifISpLKCtOI,21
+simple_socket_client-2.0.dist-info/RECORD,,

simple_socket_client-2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

simple_socket_client-2.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,13 @@
+Copyright (c) 2023–2026, webtoucher
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+* Neither the names of Alexey Kuznetsov or webtoucher nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

simple_socket_client-2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+simple_socket_client