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

simple_socket_server-2.0/CHANGELOG.md

@@ -0,0 +1,115 @@
+# 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.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.0}/LICENSE.md

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

simple_socket_server-2.0/MANIFEST.in

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

simple_socket_server-2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,181 @@
+# 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/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simple-socket-server"
+description = "Simple TCP socket server with select"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "BSD-3-Clause"
+license-files = ["LICENSE.md"]
+authors = [
+    { name = "webtoucher", email = "webtoucher@ya.ru" },
+]
+keywords = ["socket", "tcp", "server", "select", "networking", "event-driven"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Networking",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX",
+    "Operating System :: Unix",
+    "Operating System :: MacOS",
+    "Typing :: Typed",
+]
+dynamic = ["version"]
+dependencies = [
+    "event-bus~=1.0.2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/webtoucher/simple-socket-server"
+Repository = "https://github.com/webtoucher/simple-socket-server"
+Issues = "https://github.com/webtoucher/simple-socket-server/issues"
+Changelog = "https://github.com/webtoucher/simple-socket-server/blob/master/CHANGELOG.md"
+
+[tool.setuptools]
+packages = ["simple_socket_server"]
+
+[tool.setuptools.dynamic]
+version = { attr = "simple_socket_server.__version__" }
+
+[tool.setuptools.package-data]
+simple_socket_server = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

{simple-socket-server-1.8 → simple_socket_server-2.0}/setup.cfg

@@ -1,4 +1,4 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-
+[egg_info]
+tag_build = 
+tag_date = 0
+