Veltix

Python TCP, without the boilerplate.

v2.0.0 release notes

Sync, thread-friendly, zero dependencies : TCP done right. Veltix handles framing, threading, handshake, routing, and reconnection so you can focus on your application logic.

Mature & tested - 564 tests · CI on Python 3.8-3.14 · 30+ releases

Table of Contents

• Why Veltix?
• Raw Socket vs Veltix
• Installation
• Quick Start
• Key Features
• Backend Comparison: Threading vs Async
• Performance
• When NOT to use Veltix
• Comparison
• Built with Veltix
• Documentation
• Contributing
• License

Why Veltix?

I wrote Veltix because I got tired of rewriting the same networking boilerplate every time I needed two programs to talk to each other.

Raw sockets are powerful, but they leave framing, request routing, handshakes, reconnection, and thread management entirely up to you. asyncio solves part of the problem, but adopting it often means committing your whole application to an async architecture. Twisted is incredibly capable, but it comes with its own programming model and can feel more like learning a framework than writing plain Python.

I wanted something different: a lightweight library that handles the repetitive networking work without forcing a particular architecture. Define your message types, register your handlers, and focus on your application instead of socket plumbing.

That's the idea behind Veltix: modern TCP communication with a simple, synchronous API, sensible defaults, and zero dependencies.

Raw Socket vs Veltix

Echo server with raw sockets (15 lines):

import socket
import threading


def handle_client(conn, addr):
    while True:
        data = conn.recv(1024)
        if not data:
            break
        conn.sendall(data)
    conn.close()


server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
server.bind(("0.0.0.0", 8080))
server.listen(5)

while True:
    conn, addr = server.accept()
    threading.Thread(target=handle_client, args=(conn, addr)).start()

Same thing with Veltix (7 lines):

from veltix import Server, ServerConfig, ClientInfo, Response, MessageType, Request

ECHO = MessageType("echo")
server = Server(ServerConfig(host="0.0.0.0", port=8080))


@server.route(ECHO)
def on_echo(client: ClientInfo, response: Response) -> None:
    server.send(Request(ECHO, response.content), client)


server.start()

No manual framing. No thread management. No boilerplate.

What you get out of the box:

• Message framing: no more recv() loops and buffer handling
• Protocol routing: @server.route(MY_TYPE) instead of if/elif chains
• Automatic handshake: JSON raw-socket protocol with version compatibility
• Built-in ping/pong: bidirectional latency measurement, zero config
• Auto-reconnect: configurable retry with disconnect state callbacks
• Message integrity: CRC32 verification on every message
• Request/Response: send_and_wait() with timeout and correlation
• Convenience send: server.send() / client.send() — no need to touch Sender directly
• Content decoding: response.text and response.json — lazy, cached, zero-copy
• Text & JSON payloads: Request(MY_TYPE, text="hello") / Request(MY_TYPE, json={"x": 1})
• Thread-safe callbacks: slow handlers never block reception
• Client tagging: attach metadata, broadcast to groups
• Integrated logger: colorized, rotating, thread-safe
• Structured event bus: powered by Avyra — subscribe to lifecycle, message, protocol, and error events

Designed for: LAN tools, multiplayer games, real-time dashboards, custom protocols, IPC, remote tooling, file transfer.

Installation

pip install veltix

Requirements: Python 3.8+, no additional dependencies.

Quick Start

Server:

from veltix import Server, ServerConfig, ClientInfo, Response, MessageType, Request

CHAT = MessageType("chat")

server = Server(ServerConfig(host="0.0.0.0", port=8080))


@server.route(CHAT)
def on_message(client: ClientInfo, response: Response) -> None:
    print(f"[{client.ip}] {response.text}")
    server.broadcast(Request(CHAT, response.text))


server.start()

input("Press Enter to stop...")
server.close_all()

Client:

from veltix import Client, ClientConfig, Response, MessageType, Request

CHAT = MessageType("chat")

client = Client(ClientConfig(server_addr="127.0.0.1", port=8080))


@client.route(CHAT)
def on_message(response: Response) -> None:
    print(f"Server: {response.text}")


client.connect()

client.send(Request(CHAT, text="Hello Server!"))
input("Press Enter to disconnect...")
client.disconnect()

python server.py
python client.py  # In a separate terminal

Key Features

# Content decoding (lazy, cached)
response.text  # UTF-8 string
response.json  # parsed JSON
response.is_json  # bool, no exception

# Text & JSON payloads (no manual encoding)
Request(MY_TYPE, text="hello")
Request(MY_TYPE, json={"key": "value"})

# Request/Response correlation
response = client.send_and_wait(Request(MY_TYPE, b"data"), timeout=3.0)

# Server convenience
server.send(request, client)
server.broadcast(request)
server.broadcast(request, except_clients=[client])
server.wait_until_closed()
server.restart()

# Client convenience
client.send(request)
client.send_and_wait(request, timeout=5.0)
client.ping_server()
client.wait_until_closed()
client.stop_retry()

# Client tags
client.add_tag("channel", "general")
targets = server.get_clients_by_tag("channel", "general")

Backend Comparison: Threading vs Async

Veltix lets you switch between two socket backends via SocketCore. Pick the one that fits your use case.

Quick rule of thumb:

• Few clients, simple logic, want easy debugging? Use THREADING.
• Many clients, high throughput, memory-conscious? Use ASYNC.

from veltix import Server, ServerConfig, SocketCore

server = Server(ServerConfig(socket_core=SocketCore.THREADING))  # or .ASYNC

Performance

Benchmarked on Python 3.14.5 : 12-core CPU, 30.5 GB RAM, Linux (loopback).

Full benchmark details, methodology, and how to run them yourself : PERFORMANCE.md

When NOT to use Veltix

Veltix is great for TCP, but not every problem is a TCP problem.

• HTTP/REST APIs: use Flask, FastAPI, or Django REST Framework
• Browser clients: Veltix speaks raw TCP, not WebSocket; use websockets or Socket.IO
• Async-first codebases: Veltix is sync by design; use asyncio directly if your whole project is async
• Ultra high throughput (>100k msg/s per connection): consider a compiled language for the hot path
• Single request-response: if you just need to fetch something once, requests or urllib is simpler

Everything else? Veltix has you covered.

Comparison

✓ Built-in    ~ Possible but requires manual setup    ✗ Not provided (you implement it yourself)

Built with Veltix

Projects using Veltix in production:

• Nexo : Fast LAN file transfer tool CLI + GUI. Uses Veltix's TCP server, client tags, route decorators, and send_and_wait() for reliable chunked file transfers with concurrent connection handling.

Built something with Veltix ? Open a PR or start a discussion to add your project.

Documentation

• Full documentation
• FAQ
• Advanced features
• Migration guide
• Changelog
• Examples

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before submitting a pull request.

• Bug reports : Open an issue
• Discussions : Join the Discord
• Pull requests : Follow the contribution guide

License

MIT License : see LICENSE for details.

Links

• GitHub : NytroxDev/Veltix
• PyPI : pypi.org/project/veltix
• Documentation : https://nytroxdev.github.io/Veltix/
• Discord : discord.gg/gz8K369a6p