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

simple_socket_server/__init__.py

@@ -0,0 +1,262 @@
+"""
+Simple TCP socket server built on select().
+
+The server is single-threaded: run() polls the sockets 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 select
+import socket
+import threading
+
+from typing import Dict, List, Optional, Tuple
+
+from event_bus import EventBus
+
+__all__ = ["SimpleSocketServer", "SimpleSocketServerException"]
+
+__version__ = "2.0"
+
+#: Peer address as returned by accept(): (host, port).
+Address = Tuple[str, int]
+
+#: 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
+
+
+class SimpleSocketServerException(socket.error):
+    """Raised when the listening socket cannot be created, bound or enabled."""
+
+
+class SimpleSocketServer(EventBus):
+    """Single-threaded TCP server dispatching events through an event bus.
+
+    Events, in the order they may arrive:
+
+    ``start(host, port)``
+        The listening socket is ready.
+    ``connect(sock, peer)``
+        A client has been accepted.
+    ``message(sock, peer, data)``
+        A chunk of bytes has been received.
+    ``disconnect(sock, peer)``
+        The connection is gone: the peer closed it, reset it or a send failed.
+    ``error(sock, peer, error)``
+        A socket error occurred; the connection is closed right after.
+    ``stop(host, port)``
+        run() has returned and every socket is closed.
+
+    Handlers are called from the thread that runs run(), one at a time, so a
+    slow handler delays every other connection.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.__host = "0.0.0.0"
+        self.__port = 6666
+        self.__max_conn = 5
+        self.__server_socket: Optional[socket.socket] = None
+        self.__inputs: List[socket.socket] = []
+        self.__outputs: List[socket.socket] = []
+        self.__pending: Dict[socket.socket, bytearray] = {}
+        self.__clients: Dict[socket.socket, Address] = {}
+        self.__stop = threading.Event()
+
+    @property
+    def is_running(self) -> bool:
+        """True while run() is serving connections."""
+        return self.__server_socket is not None and not self.__stop.is_set()
+
+    @property
+    def host(self) -> str:
+        """Host the listening socket is bound to."""
+        return self.__host
+
+    @property
+    def port(self) -> int:
+        """Port the listening socket is bound to."""
+        return self.__port
+
+    def run(self, host: str = "0.0.0.0", port: int = 6666, max_conn: int = 5) -> None:
+        """Serve connections until stop() is called.
+
+        The call blocks the calling thread. Once it returns, every client socket
+        and the listening socket are closed. A port of 0 makes the operating
+        system pick a free port; the actual address is reported by the start
+        event and by the host and port properties.
+        """
+        if self.is_running:
+            raise RuntimeError("the server is already running")
+        self.__host = host
+        self.__port = port
+        self.__max_conn = max_conn
+        self.__stop.clear()
+        self.__initialize()
+        try:
+            while not self.__stop.is_set():
+                self.__select()
+        finally:
+            self.__shutdown()
+
+    def stop(self) -> None:
+        """Ask run() to return.
+
+        It only raises a flag, so it is safe to call from an event handler or
+        from another thread. run() finishes the current poll and then closes
+        every socket.
+        """
+        self.__stop.set()
+
+    def send(self, sock: socket.socket, message: bytes) -> None:
+        """Queue message for delivery to a client of this 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.
+        """
+        if sock not in self.__pending:
+            raise ValueError("the socket is not a client of this server")
+        if not message:
+            return
+        self.__pending[sock].extend(message)
+        if sock not in self.__outputs:
+            self.__outputs.append(sock)
+
+    def __initialize(self) -> None:
+        server_socket = socket.socket(
+            socket.AF_INET,
+            socket.SOCK_STREAM,
+            socket.IPPROTO_TCP,
+        )
+        try:
+            server_socket.setblocking(False)
+            server_socket.setsockopt(
+                socket.SOL_SOCKET,
+                socket.SO_REUSEADDR,
+                1,
+            )
+            server_socket.bind((self.__host, self.__port))
+            server_socket.listen(self.__max_conn)
+        except OSError as error:
+            server_socket.close()
+            raise SimpleSocketServerException(
+                "cannot listen on %s:%s" % (self.__host, self.__port)
+            ) from error
+        self.__server_socket = server_socket
+        self.__inputs.append(server_socket)
+        # A port of 0 is resolved by the system, so report the real address.
+        self.__host, self.__port = server_socket.getsockname()[:2]
+        self.emit("start", self.__host, self.__port)
+
+    def __select(self) -> None:
+        try:
+            sock_to_read, sock_to_write, sock_errors = select.select(
+                self.__inputs,
+                self.__outputs,
+                self.__inputs,
+                _POLL_INTERVAL,
+            )
+        except OSError as error:
+            # select() itself failed, so the listening socket is unusable.
+            self.emit("error", None, None, error)
+            self.stop()
+            return
+        for sock in sock_errors:
+            if sock is self.__server_socket:
+                self.stop()
+            else:
+                self.__close(sock)
+        for sock in sock_to_read:
+            if sock is self.__server_socket:
+                self.__accept()
+            else:
+                self.__receive(sock)
+        for sock in sock_to_write:
+            self.__flush(sock)
+
+    def __accept(self) -> None:
+        try:
+            client_socket, client_address = self.__server_socket.accept()
+        except OSError as error:
+            self.emit("error", self.__server_socket, None, error)
+            return
+        client_socket.setblocking(False)
+        self.__clients[client_socket] = client_address
+        self.__pending[client_socket] = bytearray()
+        self.__inputs.append(client_socket)
+        self.emit("connect", client_socket, client_address)
+
+    def __receive(self, sock: socket.socket) -> None:
+        peer = self.__clients.get(sock)
+        if peer is None:
+            # The socket was already dropped during this poll.
+            return
+        try:
+            data = sock.recv(_RECV_SIZE)
+        except BlockingIOError:
+            # select() woke us up for nothing; try again on the next poll.
+            return
+        except (ConnectionResetError, ConnectionAbortedError, BrokenPipeError):
+            self.__close(sock)
+            return
+        except OSError as error:
+            self.emit("error", sock, peer, error)
+            self.__close(sock)
+            return
+        if not data:
+            # An empty chunk means the peer closed its end of the connection.
+            self.__close(sock)
+            return
+        self.emit("message", sock, peer, data)
+
+    def __flush(self, sock: socket.socket) -> None:
+        pending = self.__pending.get(sock)
+        if pending is None:
+            if sock in self.__outputs:
+                self.__outputs.remove(sock)
+            return
+        try:
+            sent = sock.send(pending)
+        except BlockingIOError:
+            # The kernel buffer is full again; the tail stays queued.
+            return
+        except OSError as error:
+            self.emit("error", sock, self.__clients.get(sock), error)
+            self.__close(sock)
+            return
+        del pending[:sent]
+        if not pending and sock in self.__outputs:
+            self.__outputs.remove(sock)
+
+    def __close(self, sock: socket.socket) -> None:
+        """Close a client connection and forget it. Safe to call twice."""
+        peer = self.__clients.pop(sock, None)
+        if sock in self.__inputs:
+            self.__inputs.remove(sock)
+        if sock in self.__outputs:
+            self.__outputs.remove(sock)
+        self.__pending.pop(sock, None)
+        if peer is None:
+            sock.close()
+            return
+        try:
+            self.emit("disconnect", sock, peer)
+        finally:
+            sock.close()
+
+    def __shutdown(self) -> None:
+        for sock in list(self.__clients):
+            self.__close(sock)
+        server_socket, self.__server_socket = self.__server_socket, None
+        if server_socket is not None:
+            if server_socket in self.__inputs:
+                self.__inputs.remove(server_socket)
+            server_socket.close()
+        self.emit("stop", self.__host, self.__port)

simple_socket_server-2.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: simple-socket-server
+Version: 2.0
+Summary: Simple TCP socket server with select
+Author-email: webtoucher <webtoucher@ya.ru>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/webtoucher/simple-socket-server
+Project-URL: Repository, https://github.com/webtoucher/simple-socket-server
+Project-URL: Issues, https://github.com/webtoucher/simple-socket-server/issues
+Project-URL: Changelog, https://github.com/webtoucher/simple-socket-server/blob/master/CHANGELOG.md
+Keywords: socket,tcp,server,select,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 server with select
+
+![License](https://img.shields.io/badge/License-BSD%203--Clause-green)
+[![Downloads](https://img.shields.io/pypi/dm/simple-socket-server.svg?color=orange)](https://pypi.python.org/pypi/simple-socket-server)
+[![Latest Version](https://img.shields.io/pypi/v/simple-socket-server.svg)](https://pypi.python.org/pypi/simple-socket-server)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/simple-socket-server.svg)](https://pypi.python.org/pypi/simple-socket-server)
+[![tests](https://github.com/webtoucher/simple-socket-server/actions/workflows/tests.yml/badge.svg)](https://github.com/webtoucher/simple-socket-server/actions/workflows/tests.yml)
+
+A TCP server on a single `select()` loop with no networking framework underneath:
+you subscribe handlers to events and the server 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-server
+```
+
+Or you can add it as dependency in requirements.txt file of your python application:
+
+```
+simple-socket-server~=2.0
+```
+
+## Usage
+
+Easy way to understand how it works is testing socket server via telnet terminal:
+
+```python
+from socket import socket
+from simple_socket_server import SimpleSocketServer
+
+socket_server = SimpleSocketServer()
+
+
+@socket_server.on('start')
+def on_start(host, port):
+    print('Listening on %s:%s' % (host, port))
+
+
+@socket_server.on('connect')
+def on_connect(sock: socket, peer):
+    print('New connection from %s:%s' % peer)
+    socket_server.send(sock, b'What is your name?\r\n')
+
+
+@socket_server.on('disconnect')
+def on_disconnect(_sock, peer):
+    print('Connection from %s:%s is closed' % peer)
+
+
+@socket_server.on('message')
+def on_message(sock: socket, peer, message: bytes):
+    print('Incoming data from %s:%s' % peer, message)
+    socket_server.send(sock, b'Hi, ' + message)
+
+
+socket_server.run(host='0.0.0.0', port=5000)
+```
+
+Then you can connect to server:
+
+```shell
+telnet 127.0.0.1 5000
+```
+
+`run()` blocks, so the server stops when someone asks it to. That may be a signal
+handler, a timer or an event handler:
+
+```python
+@another_server.on('message')
+def on_message(sock, peer, message):
+    if message.strip() == b'quit':
+        another_server.stop()
+```
+
+A port of `0` lets the operating system pick a free port; the real address comes
+back in the `start` event and in the `host` and `port` properties:
+
+```python
+socket_server.run(host='127.0.0.1', port=0)
+# ... inside the start handler:
+print(socket_server.host, socket_server.port)
+```
+
+## Events
+
+Handlers are called from the thread that runs `run()`, one at a time.
+
+| Event        | Arguments               | When it fires                                                    |
+|--------------|-------------------------|------------------------------------------------------------------|
+| `start`      | `host, port`            | the listening socket is ready                                    |
+| `connect`    | `sock, peer`            | a client has been accepted                                       |
+| `message`    | `sock, peer, data`      | a chunk of bytes has been received                               |
+| `disconnect` | `sock, peer`            | the connection is gone; the socket is closed right after         |
+| `error`      | `sock, peer, error`     | a socket error occurred; `disconnect` follows                    |
+| `stop`       | `host, port`            | `run()` has returned and every socket is closed                  |
+
+`peer` is an `(host, port)` tuple, `data` is `bytes`, `error` is an `OSError`.
+
+## API
+
+| Member                                | Description                                                          |
+|---------------------------------------|----------------------------------------------------------------------|
+| `run(host='0.0.0.0', port=6666, max_conn=5)` | serve connections until `stop()` is called                    |
+| `stop()`                              | ask `run()` to return; safe from a handler or another thread          |
+| `send(sock, message)`                 | queue `bytes` for a client; `ValueError` if it is not a client        |
+| `is_running`                          | `True` while `run()` is serving connections                           |
+| `host`, `port`                        | the address the listening socket is bound to                          |
+| `on(event)`, `emit(...)`              | inherited from `event_bus.EventBus`                                   |
+
+Notes:
+
+- The server is single-threaded and handlers are called synchronously, so a slow
+  handler delays every other connection. Hand off long work to your own thread.
+- `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.
+- `send()` never blocks and never truncates: because client sockets are
+  non-blocking, 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.
+- Do not use the socket after `disconnect` or `error`: it is closed.
+- An exception raised by a handler propagates out of `run()`. The socket state is
+  still cleaned up before the call returns.
+
+## 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 server instance is independent: several servers may run in one process, each
+  in its own thread.
+
+## 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: `start`, `stop`, `is_running`, socket cleanup and port reuse,
+- the message flow: `connect`, echo round trips, ordering and large payloads,
+- disconnects: graceful close by the peer, an abrupt reset and a send to a
+  connection that is already gone,
+- error handling: an unknown socket for `send()` and a port that is already taken,
+- independence of two servers running in one process.
+
+Project layout:
+
+```
+simple_socket_server/__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_server-2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+simple_socket_server/__init__.py,sha256=NG1iCg4yUKkq6G77v7ffvkGdrkMivnqu_vcFq9wwYQk,9173
+simple_socket_server/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simple_socket_server-2.0.dist-info/licenses/LICENSE.md,sha256=viUOCJf97qThnFWXx3lGwpWwhWfuo8ug8QQAHtAFh8c,1496
+simple_socket_server-2.0.dist-info/METADATA,sha256=pehdXAJEjZO1_hgYGB3BGO49nrqExDJVQRgbwEsOUKc,8769
+simple_socket_server-2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+simple_socket_server-2.0.dist-info/top_level.txt,sha256=U3g9Q_CXbmmzcFW0pQ4cEZgmkbi0TORT9q3EA_C7I04,21
+simple_socket_server-2.0.dist-info/RECORD,,

simple_socket_server-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_server-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_server-2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+simple_socket_server