simple-socket-server 1.8__tar.gz → 2.1__tar.gz

simple_socket_server-2.1/CHANGELOG.md

@@ -0,0 +1,168 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1] - 2026-11-15
+
+### Added
+
+- `disconnect(sock)`: a graceful way to drop a client from a handler or from
+  another thread. The socket stops being read, the replies already queued for it
+  are delivered, and only then it is closed and `disconnect` is emitted.
+- `max_clients` argument of `run()` (500 by default): a connection above the limit
+  is accepted, closed at once and reported through the `error` event.
+- Tests for the new behaviour: a client half-close, a queued reply delivered before
+  the close, a socket closed inside a handler, a failing `disconnect` handler
+  during `stop()`, the client limit and a port that is already taken.
+
+### Fixed
+
+- `select()` could kill the server with `ValueError`. A socket closed behind the
+  server's back left the poll set with a dead descriptor (`file descriptor cannot
+  be a negative integer`), and an oversized client set failed the same way
+  (`filedescriptor out of range`). Dead sockets are dropped before the poll,
+  failures of `select()` are reported through `error` and stop the server instead
+  of escaping `run()`, and the number of clients is capped below `FD_SETSIZE`.
+- The reply to a client that half-closed the connection (`sendall()` followed by
+  `shutdown(SHUT_WR)`, the way `nc -N` behaves) was thrown away. A connection that
+  ended its input keeps being written to until its queue is drained.
+- `stop()` could leave clients open and the port listening when a `disconnect`
+  handler raised. The listening socket is closed first, every client is closed in
+  its own `try`, and `stop` is emitted in any case; the first handler failure is
+  re-raised afterwards.
+- `send()` called from another thread mutated the poll state without a lock. The
+  queues and the poll sets are guarded by a lock now, and handlers are never called
+  under it.
+- Urgent (out of band) data disconnected the client without an `error` event. Only
+  the listening socket is passed to the exceptional set of `select()`.
+- A `BlockingIOError` of `accept()` was reported as an `error` event. It is ignored
+  now, any other `accept()` failure pauses before the next attempt, so a descriptor
+  shortage does not spin the loop.
+
+### Changed
+
+- A `disconnect` handler that raises no longer aborts the cleanup: `run()` closes
+  every socket and emits `stop` before the exception surfaces.
+- `error` for a failed `select()` or a broken listening socket reports the listening
+  socket and `peer=None`; for a rejected connection it reports the client socket
+  and its address.
+- Concurrent clients are limited to 500 by default. A larger `max_clients` can
+  exceed the descriptor limit of `select()` (512 on Windows), which stops the server
+  with an `error` event.
+- The version test reads the package metadata instead of a hard-coded version.
+- Documentation: `max_conn` is described as the `listen()` backlog and `max_clients`
+  as the limit of concurrent clients; the thread safety of `send()` and
+  `disconnect()`, the unbounded outbound queue, the `select()` descriptor limit and
+  the rule that a handler must not raise are spelled out.
+
+## [2.0] - 2026-11-15
+
+### Added
+
+- `SimpleSocketServer.stop()`: `run()` returns on request, closes every socket and
+  emits `stop(host, port)`. It only raises a flag, so it is safe to call from an
+  event handler or from another thread.
+- `is_running`, `host` and `port` properties. A port of `0` is resolved by the
+  system, and the `start` event plus both properties report the real address.
+- `simple_socket_server.__version__`, an explicit `__all__` and a public `Address`
+  alias for a peer address.
+- `py.typed` marker (PEP 561) and type hints on every public name, so mypy and
+  pyright see real signatures instead of `Any`.
+- `tests/`: pytest suite covering the lifecycle, event order, echo round trips,
+  graceful and abrupt disconnects, large messages, error handling and port reuse.
+- GitHub Actions workflows: tests on Python 3.9-3.15 and 3.13t, plus a tag-driven
+  release pipeline publishing to PyPI and creating a GitHub Release.
+- `CHANGELOG.md` and `.gitattributes` with `* text=auto eol=lf`.
+
+### Fixed
+
+- A peer closing the connection cleanly (`recv()` returning `b""`) was ignored, so
+  the socket stayed in the `select()` set forever: the loop spun on an idle file
+  descriptor and `disconnect` never fired.
+- `send()` raised `KeyError` for a socket that was not a client of the server; it
+  raises `ValueError` now, and an empty message is a no-op.
+- `send()` dropped data on a non-blocking socket: a single `send()` call can accept
+  only part of the buffer. The unwritten tail is buffered and retried, so a message
+  larger than the socket buffer arrives in full.
+- Closed sockets were never removed from the client table, so a long-lived server
+  leaked memory with every reconnection.
+- The `disconnect` event could be emitted twice for one socket, and a socket already
+  dropped earlier in the same poll was used again.
+- The state reset on the server-socket error path left the previous listening
+  socket open, and `run()` reused a stale initialized flag.
+- `SimpleSocketServerException` was raised with two positional arguments on a check
+  that could not trigger; bind and listen failures are reported now with the address.
+- A `select()` failure is reported through the `error` event and stops the server
+  instead of escaping `run()` as an unhandled exception.
+
+### Changed
+
+- Packaging moved from `setup.py` to `pyproject.toml` (PEP 621, PEP 639);
+  metadata, build configuration and pytest settings live in one file.
+- Errors that end a connection are reported through the `error` event and followed
+  by `disconnect`; `message` is never emitted for a reset connection.
+- `run()` no longer sleeps after `select()`: the poll interval is the `select()`
+  timeout alone, so the latency of a response is halved.
+- The listening socket no longer tries to restart itself after an error; a broken
+  listening socket stops the server with an `error` event.
+- `stop` is emitted when `run()` returns, after every socket is closed.
+- Documentation: README rewritten with the event table, the API table, the
+  framing and threading caveats, compatibility and development instructions.
+- Metadata: the `HTTP Servers` topic is replaced by `System :: Networking` and
+  `Software Development :: Libraries`, `Requires-Python` is declared, and project
+  URLs point to the changelog and issue tracker.
+
+### Removed
+
+- Python 2 leftovers: the `coding=utf8` header and the empty `__main__` block.
+- `setup.py` and `requirements.txt`: dependencies are declared in `pyproject.toml`.
+- The debug `print()` call on the server-socket error path.
+
+### Breaking
+
+- The `SimpleSocketServer` class is no longer a singleton: every instance is an
+  independent server, so two servers can run in one process.
+- Python 3.9 or newer is required.
+- `send()` raises `ValueError` instead of `KeyError` for an unknown socket.
+- `SimpleSocketServerException` wraps the underlying `OSError` (`raise ... from`),
+  so `except OSError` keeps working but the arguments differ.
+
+## [1.8] - 2023-02-10
+
+- Fixed getting the peer address after a disconnect.
+
+## [1.7] - 2023-02-06
+
+- `EventBus.__init__` is called from the server constructor.
+
+## [1.6] - 2023-02-06
+
+- Replaced the event emitter with the `event-bus` library.
+
+## [1.5] - 2023-02-05
+
+- Replaced the bundled event emitter.
+
+## [1.4] - 2023-02-04
+
+- `BrokenPipeError` on send is reported instead of escaping `run()`.
+
+## [1.3] - 2023-02-03
+
+- `ConnectionResetError` ends the connection instead of raising from the handler.
+
+## [1.2] - 2023-02-02
+
+- Removed the Flask integration.
+
+## [1.1] - 2023-02-01
+
+- `start` event with the listening address.
+
+## [1.0] - 2023-01-24
+
+- First published release: `select()`-based TCP server with `connect`, `message`
+  and `disconnect` events.

{simple-socket-server-1.8 → simple_socket_server-2.1}/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2023, Alexey Kuznetsov
+Copyright (c) 2023–2026, webtoucher
 
 All rights reserved.
 

simple_socket_server-2.1/MANIFEST.in

@@ -0,0 +1 @@
+include CHANGELOG.md

simple_socket_server-2.1/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: simple-socket-server
+Version: 2.1
+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.1
+```
+
+## 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 closed; the replies queued for it were delivered first   |
+| `error`      | `sock, peer, error`     | a socket error occurred; the connection is closed and `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`. When
+`error` reports a failure of the listening socket or of `select()` itself, `peer` is
+`None` and the server stops.
+
+## API
+
+| Member                                   | Description                                                          |
+|------------------------------------------|----------------------------------------------------------------------|
+| `run(host='0.0.0.0', port=6666, max_conn=5, max_clients=500)` | 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        |
+| `disconnect(sock)`                       | stop reading a client, deliver its queue, then close it               |
+| `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.
+- **A handler must not raise.** The exception propagates out of `run()` and stops
+  the server for every client; the sockets are still closed before the call returns.
+  If one connection misbehaves, handle it in the handler and call `disconnect()`.
+- `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.
+- The outbound queue has no size limit: a client that stops reading grows the
+  buffer of the server until you disconnect it.
+- `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).
+- `max_conn` is the `listen()` backlog: how many connections the system queues
+  before `accept()`. It is not a limit of served clients. `max_clients` is that
+  limit: a connection above it is accepted, closed at once and reported through
+  `error`.
+- Do not call `sock.close()` yourself and do not use the socket after
+  `disconnect` or `error`. Use `disconnect(sock)` instead: it stops reading the
+  client and closes the socket after the queued replies are delivered. A socket
+  closed behind the server's back is dropped on the next poll, without delivery.
+- Urgent (out of band) data is not supported, and such data is not treated as an
+  error: the bytes stay in the stream and arrive through `message`.
+
+## 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.
+- The poll set of `select()` is limited by the platform: 512 descriptors on Windows
+  and 1024 elsewhere, the listening socket included. That is why concurrent clients
+  are capped by `max_clients`, 500 by default; a larger value makes `select()` fail,
+  and the server stops with an `error` event.
+
+## 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: `send()` and `disconnect()` for an unknown socket, a client limit
+  that is reached, and a port that is already taken (POSIX only: on Windows
+  `SO_REUSEADDR` allows rebinding a listening port),
+- a half-close: the peer sends, shuts down its writing side and still receives the
+  whole reply, a 256 KiB one included,
+- server-driven disconnects: a queued reply reaches the client before the socket is
+  closed,
+- resilience: a handler that closes its socket does not stop the server, and
+  `stop()` closes every client and emits `stop` even if a `disconnect` handler
+  raises,
+- 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.1/README.md

@@ -0,0 +1,211 @@
+# 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.1
+```
+
+## 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 closed; the replies queued for it were delivered first   |
+| `error`      | `sock, peer, error`     | a socket error occurred; the connection is closed and `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`. When
+`error` reports a failure of the listening socket or of `select()` itself, `peer` is
+`None` and the server stops.
+
+## API
+
+| Member                                   | Description                                                          |
+|------------------------------------------|----------------------------------------------------------------------|
+| `run(host='0.0.0.0', port=6666, max_conn=5, max_clients=500)` | 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        |
+| `disconnect(sock)`                       | stop reading a client, deliver its queue, then close it               |
+| `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.
+- **A handler must not raise.** The exception propagates out of `run()` and stops
+  the server for every client; the sockets are still closed before the call returns.
+  If one connection misbehaves, handle it in the handler and call `disconnect()`.
+- `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.
+- The outbound queue has no size limit: a client that stops reading grows the
+  buffer of the server until you disconnect it.
+- `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).
+- `max_conn` is the `listen()` backlog: how many connections the system queues
+  before `accept()`. It is not a limit of served clients. `max_clients` is that
+  limit: a connection above it is accepted, closed at once and reported through
+  `error`.
+- Do not call `sock.close()` yourself and do not use the socket after
+  `disconnect` or `error`. Use `disconnect(sock)` instead: it stops reading the
+  client and closes the socket after the queued replies are delivered. A socket
+  closed behind the server's back is dropped on the next poll, without delivery.
+- Urgent (out of band) data is not supported, and such data is not treated as an
+  error: the bytes stay in the stream and arrive through `message`.
+
+## 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.
+- The poll set of `select()` is limited by the platform: 512 descriptors on Windows
+  and 1024 elsewhere, the listening socket included. That is why concurrent clients
+  are capped by `max_clients`, 500 by default; a larger value makes `select()` fail,
+  and the server stops with an `error` event.
+
+## 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: `send()` and `disconnect()` for an unknown socket, a client limit
+  that is reached, and a port that is already taken (POSIX only: on Windows
+  `SO_REUSEADDR` allows rebinding a listening port),
+- a half-close: the peer sends, shuts down its writing side and still receives the
+  whole reply, a 256 KiB one included,
+- server-driven disconnects: a queued reply reaches the client before the socket is
+  closed,
+- resilience: a handler that closes its socket does not stop the server, and
+  `stop()` closes every client and emits `stop` even if a `disconnect` handler
+  raises,
+- 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.