Client

veltix.client.client.Client

TCP client for Veltix protocol.

Connects to a Veltix server and handles bidirectional communication. connect() blocks until the handshake is complete before returning, so it is always safe to send messages immediately after connect() returns True.

If retry > 0, the client automatically attempts to reconnect both on initial connection failure and on mid-session disconnections. The on_disconnect callback receives a DisconnectState at each attempt, letting the caller display progress or cancel retries via stop_retry().

__init__

__init__(config: ClientConfig) -> None

Initialize the TCP client.

Parameters:

Name	Type	Description	Default
config	ClientConfig	Client configuration.	required

stop_retry

stop_retry() -> None

Cancel all pending reconnection attempts.

If a retry loop is running, it will stop after the current attempt and fire on_disconnect with permanent=True.

retry

retry(max_: Optional[int] = None) -> None

Force an immediate reconnection attempt, even if retry_max was reached.

Parameters:

Name	Type	Description	Default
max_	Optional[int]	Override retry_max for this session (optional).	None

set_callback

set_callback(event: Union[str, Events], func: Callable) -> None

Bind a callback function to a client event.

Parameters:

Name	Type	Description	Default
event	Union[str, Events]	Event type (Events enum or string).	required
func	Callable	Callback function: - ON_RECV: func(response: Response) - ON_CONNECT: func() - ON_DISCONNECT: func(state: DisconnectState)	required

route

route(type_: MessageType) -> Callable

Decorator to register a route callback for a specific message type.

Usage

@client.route(MY_TYPE) def on_my_type(response: Response, client=None) -> None: ...

Parameters:

Name	Type	Description	Default
type_	MessageType	Message type to intercept.	required

Returns:

Type	Description
Callable	Decorator function.

connect

connect() -> bool

Connect to the server and start the message handler thread.

Blocks until the handshake is complete (or times out) before returning, so it is safe to send messages immediately after this returns True.

If the connection fails and retry > 0, automatically retries up to config.retry times with config.retry_delay seconds between attempts.

Returns:

Type	Description
bool	True if connection and handshake succeeded, False otherwise.

get_sender

get_sender() -> Sender

Return the sender instance.

send_and_wait

send_and_wait(request: Request, timeout: float = 5.0) -> Optional[Response]

Send a request and block until the matching response is received.

The request queue is registered before sending to avoid a race condition where the response could arrive before wait() is called.

Parameters:

Name	Type	Description	Default
request	Request	Request to send.	required
timeout	float	Maximum time to wait for a response in seconds (default: 5.0).	5.0

Returns:

Type	Description
Optional[Response]	Matching Response, or None on timeout or send failure.

ping_server

ping_server(timeout: float = 5.0) -> Optional[float]

Ping the server and measure round-trip latency.

Parameters:

Name	Type	Description	Default
timeout	float	Maximum time to wait for pong in seconds (default: 5.0).	5.0

Returns:

Type	Description
Optional[float]	Latency in milliseconds, or None on timeout.

disconnect

disconnect() -> bool

Disconnect from the server and clean up resources.

Fires on_disconnect with reason=MANUAL and permanent=True.

Returns:

Type	Description
bool	True if disconnection succeeded, False on unexpected error.

veltix.client.client.ClientConfig dataclass

TCP client configuration.

Attributes:

Name	Type	Description
server_addr	str	Server address to connect to.
port	int	Server port to connect to.
buffer_size	int	Buffer size for receiving data in bytes. Use BufferSize enum for common presets (default: BufferSize.SMALL). Can also be set to any custom integer value.
max_message_size	int	Maximum allowed message size in bytes (default: 10MB).
handshake_timeout	float	Maximum time to wait for handshake completion (default: 5.0s).
max_workers	int	Number of worker threads for callback execution (default: 4). Increase if your on_recv callback is slow or blocking.
retry	int	Number of reconnection attempts on failure (default: 0 = disabled). Applies both to the initial connect() and to mid-session disconnections.
retry_delay	float	Seconds to wait between reconnection attempts (default: 1.0).
performance_mode	PerformanceMode	Controls internal timing parameters (default: BALANCED).