Client

veltix.client.client.Client

TCP client for the 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

init_components

init_components() -> None

(Re)initialise all internal components (socket, sender, handler).

context_connect

context_connect() -> bool

Connect from within a retry context (suppresses own reconnect).

context_on_disconnect

context_on_disconnect(state: DisconnectState) -> None

Forward disconnect state to the public on_disconnect callback.

context_init

context_init() -> None

Reinitialise components before a reconnection attempt.

context_set_running

context_set_running(value: bool) -> None

Set whether the client is considered running.

context_set_connected

context_set_connected(value: bool) -> None

Set the connection flag without triggering side effects.

context_get_request_handler

context_get_request_handler() -> Optional[RequestHandler]

Return the current request handler instance.

context_get_on_recv

context_get_on_recv() -> Optional[Callable]

Return the current on_recv callback.

context_get_socket

context_get_socket() -> Optional[BaseSocket]

Return the current socket instance.

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(_from_retry: bool = False) -> 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.

stop_retry

stop_retry() -> None

Cancel all pending reconnection attempts.

retry

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

Force reconnection attempts, optionally overriding retry count.

Parameters:

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

veltix.client.config.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).

veltix.client.disconnect.DisconnectState dataclass

State passed to the on_disconnect callback.

Attributes:

Name	Type	Description
permanent	bool	True if the client has given up reconnecting. False if a reconnection attempt will follow.
attempt	int	Current retry attempt number (0 = first disconnection, before any retry has been attempted).
retry_max	int	Maximum number of retry attempts configured.
reason	DisconnectReason	Why the disconnection occurred.

veltix.client.disconnect.DisconnectReason

Bases: Enum

Reason for a disconnection.

Attributes:

Name	Type	Description
SERVER_CLOSED		Server closed the connection cleanly.
ERROR		Fatal network error (reset, aborted, etc.).
MANUAL		disconnect() was called manually by the user.