hibachi_xyz.executors package

Submodules

hibachi_xyz.executors.aiohttp module

WebSocket executor implementation using aiohttp.

This module provides WebSocket connection handling using the aiohttp library, supporting async WebSocket operations for the Hibachi SDK.

class hibachi_xyz.executors.aiohttp.AiohttpWsConnection(ws: ClientWebSocketResponse)

Bases: WsConnection

WebSocket connection implementation using aiohttp.

Wraps an aiohttp ClientWebSocketResponse for WebSocket communication.

async close() → None

Close the WebSocket connection.

async recv() → str

Receive a message from the WebSocket connection.

Returns:

The received message as a string.

Raises:

• WebSocketConnectionError – If the WebSocket is closed or encounters an error.

• WebSocketMessageError – If an unexpected message type is received.

• DeserializationError – If decoding the message fails.

• TransportError – If receiving the message fails for any other reason.

async send(serialized_body: str) → None

Send a message through the WebSocket connection.

Parameters:

serialized_body – The serialized message string to send.

Raises:

• WebSocketConnectionError – If the connection is lost while sending.

• WebSocketMessageError – If sending the message fails for any other reason.

class hibachi_xyz.executors.aiohttp.AiohttpWsExecutor

Bases: WsExecutor

WebSocket executor implementation using aiohttp.

Manages aiohttp ClientSession and establishes WebSocket connections.

async close() → None

Close the executor and its underlying aiohttp session.

async connect(web_url: str, headers: dict[str, str] | None = None) → WsConnection

Connect to a WebSocket endpoint.

Parameters:

• web_url – The WebSocket URL to connect to.

• headers – Optional dictionary of HTTP headers to send with the connection request.

Returns:

A WsConnection instance wrapping the established WebSocket connection.

Raises:

• WebSocketConnectionError – If the WebSocket handshake fails, connection fails, or the connection times out.

• TransportError – If an unexpected error occurs during connection.

hibachi_xyz.executors.defaults module

Default executor configurations.

This module defines the default HTTP and WebSocket executor implementations used by the Hibachi SDK when no custom executor is provided.

hibachi_xyz.executors.httpx module

HTTP executor implementation using httpx.

This module provides HTTP request handling using the httpx library, supporting both sync and async operations for the Hibachi SDK.

class hibachi_xyz.executors.httpx.HttpxHttpExecutor(api_url: str = 'https://api.hibachi.xyz', data_api_url: str = 'https://data-api.hibachi.xyz', api_key: str | None = None)

Bases: HttpExecutor

HTTP executor implementation using httpx.

Provides synchronous HTTP request execution using the httpx library.

send_authorized_request(method: str, path: str, json: dict[str, JsonValue] | None = None) → HttpResponse

Send an authenticated request to the API.

Parameters:

• method – The HTTP method to use (e.g., ‘GET’, ‘POST’, ‘PUT’, ‘DELETE’).

• path – The API endpoint path to request (will be appended to api_url).

• json – Optional JSON data to include in the request body. Defaults to None.

Returns:

HttpResponse containing the status code and deserialized response body.

Raises:

• ValidationError – If the api_key is not set.

• TransportTimeoutError – If the request times out.

• HttpConnectionError – If there is a connection or network error.

• TransportError – If any other transport-level error occurs.

• ExchangeError – If an exchange-specific error occurs (re-raised).

send_simple_request(path: str) → HttpResponse

Send a simple unauthenticated GET request to the Data API.

Parameters:

path – The API endpoint path to request (will be appended to data_api_url).

Returns:

HttpResponse containing the status code and deserialized response body.

Raises:

• TransportTimeoutError – If the request times out.

• HttpConnectionError – If there is a connection or network error.

• TransportError – If any other transport-level error occurs.

hibachi_xyz.executors.interface module

Abstract interfaces for HTTP and WebSocket executors.

This module defines the abstract base classes that all HTTP and WebSocket executor implementations must follow, enabling pluggable transport layers.

class hibachi_xyz.executors.interface.HttpExecutor(api_url: str, data_api_url: str, api_key: str | None)

Bases: ABC

Abstract base class for HTTP request executors.

Defines the interface for sending both authenticated and unauthenticated HTTP requests.

api_key: str | None = None

abstractmethod send_authorized_request(method: str, path: str, json: Any | None = None) → HttpResponse

Send an authorized HTTP request with API key authentication.

Parameters:

• method – The HTTP method (e.g., ‘GET’, ‘POST’, ‘PUT’, ‘DELETE’).

• path – The URL path for the request.

• json – Optional JSON payload to send with the request.

Returns:

An HttpResponse object containing the status, body, and headers.

abstractmethod send_simple_request(path: str) → HttpResponse

Send a simple HTTP GET request without authentication.

Parameters:

path – The URL path for the request.

Returns:

An HttpResponse object containing the status, body, and headers.

class hibachi_xyz.executors.interface.HttpResponse(*, status: int, body: dict[str, JsonValue] | None = None, headers: dict[str, str] | None = None)

Bases: object

Container for HTTP response data.

Encapsulates the status code, body, and headers from an HTTP response.

body: dict[str, JsonValue]

headers: dict[str, str] | None

status: int

class hibachi_xyz.executors.interface.WsConnection

Bases: ABC

Abstract base class for WebSocket connection wrappers.

Defines the interface for WebSocket communication operations.

abstractmethod async close() → None

Close the WebSocket connection.

abstractmethod async recv() → str

Receive a message from the WebSocket connection.

Returns:

The received message as a string.

abstractmethod async send(serialized_body: str) → None

Send a message through the WebSocket connection.

Parameters:

serialized_body – The serialized message body to send.

class hibachi_xyz.executors.interface.WsExecutor

Bases: ABC

Abstract base class for WebSocket connection executors.

Defines the interface for establishing WebSocket connections.

abstractmethod async connect(web_url: str, headers: dict[str, str] | None = None) → WsConnection

Establish a WebSocket connection.

Parameters:

• web_url – The WebSocket URL to connect to.

• headers – Optional headers to include in the connection handshake.

Returns:

A WsConnection object representing the established connection.

hibachi_xyz.executors.requests module

HTTP executor implementation using requests.

This module provides HTTP request handling using the popular requests library, serving as the default HTTP executor for the Hibachi SDK.

class hibachi_xyz.executors.requests.RequestsHttpExecutor(api_url: str = 'https://api.hibachi.xyz', data_api_url: str = 'https://data-api.hibachi.xyz', api_key: str | None = None)

Bases: HttpExecutor

HTTP executor implementation using requests.

Provides synchronous HTTP request execution using the requests library.

send_authorized_request(method: str, path: str, json: dict[str, JsonValue] | None = None) → HttpResponse

Send an authenticated HTTP request to the API.

Parameters:

• method – The HTTP method to use (e.g., GET, POST, PUT, DELETE).

• path – The API endpoint path to append to the API URL.

• json – Optional JSON payload to send with the request.

Returns:

HttpResponse containing the status code and deserialized response body.

Raises:

• TransportTimeoutError – If the request times out.

• HttpConnectionError – If the connection to the server fails.

• TransportError – If any other transport-level error occurs.

send_simple_request(path: str) → HttpResponse

Send an unauthenticated GET request to the data API.

Parameters:

path – The API endpoint path to append to the data API URL.

Returns:

HttpResponse containing the status code and deserialized response body.

Raises:

• TransportTimeoutError – If the request times out.

• HttpConnectionError – If the connection to the server fails.

• TransportError – If any other transport-level error occurs.

hibachi_xyz.executors.websockets module

WebSocket executor implementation using websockets.

This module provides WebSocket connection handling using the websockets library, serving as the default WebSocket executor for the Hibachi SDK.

class hibachi_xyz.executors.websockets.WebsocketsWsConnection(ws: ClientConnection)

Bases: WsConnection

WebSocket connection implementation using websockets.

Wraps a websockets ClientConnection for WebSocket communication.

async close() → None

Close the WebSocket connection gracefully.

async recv() → str

Receive a message from the WebSocket connection.

Returns:

The received message as a UTF-8 decoded string.

Raises:

• WebSocketConnectionError – If the connection is closed while receiving.

• DeserializationError – If the message cannot be decoded as UTF-8.

• WebSocketMessageError – If receiving the message fails for any other reason.

async send(serialized_body: str) → None

Send a message over the WebSocket connection.

Parameters:

serialized_body – The serialized message string to send.

Raises:

• WebSocketConnectionError – If the connection is closed while sending.

• WebSocketMessageError – If sending the message fails for any other reason.

class hibachi_xyz.executors.websockets.WebsocketsWsExecutor

Bases: WsExecutor

WebSocket executor implementation using websockets.

Establishes WebSocket connections using the websockets library.

async connect(web_url: str, headers: dict[str, str] | None = None) → WsConnection

Establish a WebSocket connection to the specified URL.

Parameters:

• web_url – The WebSocket URL to connect to (ws:// or wss://).

• headers – Optional dictionary of additional HTTP headers to send during the handshake. Defaults to None.

Returns:

A WsConnection instance wrapping the established connection.

Raises:

• WebSocketConnectionError – If the URL is invalid, the handshake fails, or the connection cannot be established.

• TransportError – If an unexpected error occurs during connection.

Module contents

HTTP and WebSocket executor implementations.

This package provides pluggable HTTP and WebSocket client implementations for the Hibachi SDK, supporting multiple underlying libraries like requests, httpx, websockets, and aiohttp.

class hibachi_xyz.executors.AiohttpWsExecutor

Bases: WsExecutor

WebSocket executor implementation using aiohttp.

Manages aiohttp ClientSession and establishes WebSocket connections.

async close() → None

Close the executor and its underlying aiohttp session.

async connect(web_url: str, headers: dict[str, str] | None = None) → WsConnection

Connect to a WebSocket endpoint.

Parameters:

• web_url – The WebSocket URL to connect to.

• headers – Optional dictionary of HTTP headers to send with the connection request.

Returns:

A WsConnection instance wrapping the established WebSocket connection.

Raises:

• WebSocketConnectionError – If the WebSocket handshake fails, connection fails, or the connection times out.

• TransportError – If an unexpected error occurs during connection.

hibachi_xyz.executors.DEFAULT_HTTP_EXECUTOR

alias of HttpxHttpExecutor

hibachi_xyz.executors.DEFAULT_WS_EXECUTOR

alias of AiohttpWsExecutor

class hibachi_xyz.executors.HttpExecutor(api_url: str, data_api_url: str, api_key: str | None)

Bases: ABC

Abstract base class for HTTP request executors.

Defines the interface for sending both authenticated and unauthenticated HTTP requests.

api_key: str | None = None

abstractmethod send_authorized_request(method: str, path: str, json: Any | None = None) → HttpResponse

Send an authorized HTTP request with API key authentication.

Parameters:

• method – The HTTP method (e.g., ‘GET’, ‘POST’, ‘PUT’, ‘DELETE’).

• path – The URL path for the request.

• json – Optional JSON payload to send with the request.

Returns:

An HttpResponse object containing the status, body, and headers.

abstractmethod send_simple_request(path: str) → HttpResponse

Send a simple HTTP GET request without authentication.

Parameters:

path – The URL path for the request.

Returns:

An HttpResponse object containing the status, body, and headers.

class hibachi_xyz.executors.HttpxHttpExecutor(api_url: str = 'https://api.hibachi.xyz', data_api_url: str = 'https://data-api.hibachi.xyz', api_key: str | None = None)

Bases: HttpExecutor

HTTP executor implementation using httpx.

Provides synchronous HTTP request execution using the httpx library.

send_authorized_request(method: str, path: str, json: dict[str, JsonValue] | None = None) → HttpResponse

Send an authenticated request to the API.

Parameters:

• method – The HTTP method to use (e.g., ‘GET’, ‘POST’, ‘PUT’, ‘DELETE’).

• path – The API endpoint path to request (will be appended to api_url).

• json – Optional JSON data to include in the request body. Defaults to None.

Returns:

HttpResponse containing the status code and deserialized response body.

Raises:

• ValidationError – If the api_key is not set.

• TransportTimeoutError – If the request times out.

• HttpConnectionError – If there is a connection or network error.

• TransportError – If any other transport-level error occurs.

• ExchangeError – If an exchange-specific error occurs (re-raised).

send_simple_request(path: str) → HttpResponse

Send a simple unauthenticated GET request to the Data API.

Parameters:

path – The API endpoint path to request (will be appended to data_api_url).

Returns:

HttpResponse containing the status code and deserialized response body.

Raises:

• TransportTimeoutError – If the request times out.

• HttpConnectionError – If there is a connection or network error.

• TransportError – If any other transport-level error occurs.

class hibachi_xyz.executors.RequestsHttpExecutor(api_url: str = 'https://api.hibachi.xyz', data_api_url: str = 'https://data-api.hibachi.xyz', api_key: str | None = None)

Bases: HttpExecutor

HTTP executor implementation using requests.

Provides synchronous HTTP request execution using the requests library.

send_authorized_request(method: str, path: str, json: dict[str, JsonValue] | None = None) → HttpResponse

Send an authenticated HTTP request to the API.

Parameters:

• method – The HTTP method to use (e.g., GET, POST, PUT, DELETE).

• path – The API endpoint path to append to the API URL.

• json – Optional JSON payload to send with the request.

Returns:

HttpResponse containing the status code and deserialized response body.

Raises:

• TransportTimeoutError – If the request times out.

• HttpConnectionError – If the connection to the server fails.

• TransportError – If any other transport-level error occurs.

send_simple_request(path: str) → HttpResponse

Send an unauthenticated GET request to the data API.

Parameters:

path – The API endpoint path to append to the data API URL.

Returns:

HttpResponse containing the status code and deserialized response body.

Raises:

• TransportTimeoutError – If the request times out.

• HttpConnectionError – If the connection to the server fails.

• TransportError – If any other transport-level error occurs.

class hibachi_xyz.executors.WebsocketsWsExecutor

Bases: WsExecutor

WebSocket executor implementation using websockets.

Establishes WebSocket connections using the websockets library.

async connect(web_url: str, headers: dict[str, str] | None = None) → WsConnection

Establish a WebSocket connection to the specified URL.

Parameters:

• web_url – The WebSocket URL to connect to (ws:// or wss://).

• headers – Optional dictionary of additional HTTP headers to send during the handshake. Defaults to None.

Returns:

A WsConnection instance wrapping the established connection.

Raises:

• WebSocketConnectionError – If the URL is invalid, the handshake fails, or the connection cannot be established.

• TransportError – If an unexpected error occurs during connection.

class hibachi_xyz.executors.WsConnection

Bases: ABC

Abstract base class for WebSocket connection wrappers.

Defines the interface for WebSocket communication operations.

abstractmethod async close() → None

Close the WebSocket connection.

abstractmethod async recv() → str

Receive a message from the WebSocket connection.

Returns:

The received message as a string.

abstractmethod async send(serialized_body: str) → None

Send a message through the WebSocket connection.

Parameters:

serialized_body – The serialized message body to send.

class hibachi_xyz.executors.WsExecutor

Bases: ABC

Abstract base class for WebSocket connection executors.

Defines the interface for establishing WebSocket connections.

abstractmethod async connect(web_url: str, headers: dict[str, str] | None = None) → WsConnection

Establish a WebSocket connection.

Parameters:

• web_url – The WebSocket URL to connect to.

• headers – Optional headers to include in the connection handshake.

Returns:

A WsConnection object representing the established connection.