easy-sock

A friendly, batteries-included wrapper around Python's built-in socket module - with sensible message framing, timeouts, JSON helpers, file transfer and a threaded server loop.

• No dependencies - standard library only
• TCP and UDP
• Length-prefixed, newline-delimited or raw framing
• Context-manager friendly
• Typed, with py.typed

Installation

pip install easy-sock

Quick start

Echo server

from easy_sock import EasySocket


def handle(client, address):
    print("connected:", address)
    for message in client:
        client.send(message)


server = EasySocket.server("0.0.0.0", 9000)
print("listening on", server.address)
try:
    server.serve_forever(handle)
except KeyboardInterrupt:
    server.stop()
finally:
    server.close()

Client

from easy_sock import EasySocket

with EasySocket.connect_to("127.0.0.1", 9000) as sock:
    sock.send("hello server")
    print(sock.recv())

JSON messages

sock.send_message({"type": "ping", "id": 42})
reply = sock.recv_message()

Sending a file

sock.send_file("report.pdf")
path = sock.recv_file(destination="./downloads")

API overview

Options

Exceptions

SocketEasyError
  +-- ConnectionClosed
  +-- SocketTimeout
  +-- ProtocolError

Development

git clone https://github.com/yourname/easy-sock
cd easy-sock
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
pytest

Publishing

python -m build
twine check dist/*
twine upload dist/*

License

MIT (c) 2025 Your Name