Introduction

EasySync is a universal state synchronization library for Python. It allows you to share object states across different scripts, processes, or machines with minimal boilerplate.

EasySync works by wrapping your class attributes in proxies that automatically transmit changes when a value is updated.

Installation

pip install py-easysync

Optional Dependencies

For high-performance data (NumPy/Torch), install the extra requirements:

pip install py-easysync[heavy]

EasySHM (No-Socket IPC)

EasySHM is the ultimate engine for local synchronization. It uses Shared Memory instead of network sockets to pass data between processes.

Why use SHM?

Feature TCP Network EasySHM
Latency ~1.0ms - 10ms < 0.05ms
Throughput Limited by Nic (1Gbps) Unlimited (RAM Speed)
Overhead TCP/IP Stack Zero (Direct RAM)

Example Usage

from easysync import shm_connect, SyncedObject

# Connect directly to local RAM bus
client = shm_connect("my_cluster")

@SyncedObject(client)
class State:
    def __init__(self):
        self.score = 0
SHM mode requires no server. The memory segment itself acts as the communication bus.

Hybrid TCP/UDP

EasySync allows you to choose the transport protocol for each decorated object or attribute.

  • TCP: Guaranteed delivery. Best for scores, inventory, and configuration.
  • UDP: Fast, but may lose packets. Best for positions, rotations, and streams.

Per-attribute configuration

@SyncedObject(transport="udp")
class Player:
    pos_x = 0 # This will use UDP
    inventory = [] # You should use TCP for this!

Codecs & Delta Sync

The Delta Sync engine calculates differentials between states to save bandwidth. This is specifically powerful for NumPy arrays.

Old State (10MB)
XOR Delta (100KB)
New State (10MB)
With Delta Sync, synchronizing a full screen image can drop from 5MB/update to only 150KB/update.

API Reference

Decorator: @SyncedObject

The core decorator of EasySync.

  • client: Instance contextuelle (SyncClient ou SHMSyncClient).
  • transport: "tcp" ou "udp".

Functions: connect() & shm_connect()

# Network mode
client = connect(host="127.0.0.1", port=5000)

# Ultra-fast local mode
client = shm_connect(cluster_name="my_app")

Telemetry & Stats

Every client tracks real-time statistics in its stats dictionary.

print(client.stats["latency_ms"])
print(client.stats["bytes_sent"])
print(client.stats["packets_recv"])
Telemetry is zero-overhead in SHM mode.