sockets

class pyhs.sockets.Connection(protocol, host, port=None, timeout=None)

Single HandlerSocket connection.

Maintains a streamed socket connection and defines methods to send and read data from it. In case of failure retry_time will be set to the exact time after which the connection may be retried to deal with temporary connection issues.

Parameters:
  • protocol (string) – socket protocol (‘unix’ and ‘inet’ are supported).
  • host (string) – server host for ‘inet’ protocol or socket file path for ‘unix’.
  • port (integer or None) – server port for ‘inet’ protocol connection.
  • timeout (integer or None) – timeout value for socket, default is defined in DEFAULT_TIMEOUT.
connect()

Establishes connection with a new socket. If some socket is associated with the instance - no new socket will be created.

disconnect()

Closes a socket and disassociates it from the connection instance.

Note

It ignores any socket exceptions that might happen in process.

is_ready()

Checks if connection instance is ready to be used.

Return type:bool
readline()

Reads one line from the socket stream and returns it. Lines are expected to be delimited with LF. Throws ConnectionError in case of failure.

Return type:string

Note

Currently Connection class supports only one line per request/response. All data in the stream after first LF will be ignored.

send(data)

Sends all given data into the socket stream. Throws ConnectionError in case of failure.

Parameters:data (string) – data to send
set_debug_mode(mode)

Changes debugging mode of the connection. If enabled, some debugging info will be printed to stdout.

Parameters:mode (bool) – mode value
class pyhs.sockets.HandlerSocket(servers, debug=False)

Pool of HandlerSocket connections.

Manages connections and defines common HandlerSocket operations. Uses internal index id cache. Subclasses threading.local to put connection pool and indexes data in thread-local storage as they’re not safe to share between threads.

Warning

Shouldn’t be used directly in most cases. Use ReadSocket for read operations and WriteSocket for writes.

Pool constructor initializes connections for all given HandlerSocket servers.

Parameters:
  • servers (iterable) – a list of lists that define server data, format: (protocol, host, port, timeout). See Connection for details.
  • debug (bool) – enable or disable debug mode, default is False.
get_index_id(db, table, fields, index_name=None)

Returns index id for given index data. This id must be used in all operations that use given data.

Uses internal index cache that keys index ids on a combination of: db:table:index_name:fields. In case no index was found in the cache, a new index will be opened.

Note

fields is position-dependent, so change of fields order will open a new index with another index id.

Parameters:
  • db (string) – database name.
  • table (string) – table name.
  • fields (iterable) – list of table’s fields that would be used in further operations. See _open_index() for more info on fields order.
  • index_name (string or None) – name of the index, default is PRIMARY.
Return type:

integer or None

purge()

Closes all connections, cleans caches, zeroes index id counter.

purge_index(index_id)

Clear single index connection and cache.

Parameters:index_id (integer) – id of the index to purge.
purge_indexes()

Closes all indexed connections, cleans caches, zeroes index id counter.

class pyhs.sockets.ReadSocket(servers, debug=False)

HandlerSocket client for read operations.

Pool constructor initializes connections for all given HandlerSocket servers.

Parameters:
  • servers (iterable) – a list of lists that define server data, format: (protocol, host, port, timeout). See Connection for details.
  • debug (bool) – enable or disable debug mode, default is False.
find(index_id, operation, columns, limit=0, offset=0)

Finds row(s) via opened index.

Raises ValueError if given data doesn’t validate.

Parameters:
  • index_id (integer) – id of opened index.
  • operation (string) – logical comparison operation to use over columns. Currently allowed operations are defined in FIND_OPERATIONS. Only one operation is allowed per call.
  • columns (iterable) – list of column values for comparison operation. List must be ordered in the same way as columns are defined in opened index.
  • limit (integer) – optional limit of results to return. Default is one row. In case multiple results are expected, limit must be set explicitly, HS wont return all found rows by default.
  • offset (integer) – optional offset of rows to search for.
Return type:

list

class pyhs.sockets.WriteSocket(servers, debug=False)

HandlerSocket client for write operations.

Pool constructor initializes connections for all given HandlerSocket servers.

Parameters:
  • servers (iterable) – a list of lists that define server data, format: (protocol, host, port, timeout). See Connection for details.
  • debug (bool) – enable or disable debug mode, default is False.
find_modify(index_id, operation, columns, modify_operation, modify_columns=[], limit=0, offset=0)

Updates/deletes row(s) using opened index.

Returns number of modified rows or a list of original values in case modify_operation ends with ?.

Raises ValueError if given data doesn’t validate.

Parameters:
  • index_id (integer) – id of opened index.
  • operation (string) – logical comparison operation to use over columns. Currently allowed operations are defined in FIND_OPERATIONS. Only one operation is allowed per call.
  • columns (iterable) – list of column values for comparison operation. List must be ordered in the same way as columns are defined in opened index.
  • modify_operation (string) – modification operation (update or delete). Currently allowed operations are defined in MODIFY_OPERATIONS.
  • modify_columns (iterable) – list of column values for update operation. List must be ordered in the same way as columns are defined in opened index. Only usable for update operation,
  • limit (integer) – optional limit of results to change. Default is one row. In case multiple rows are expected to be changed, limit must be set explicitly, HS wont change all found rows by default.
  • offset (integer) – optional offset of rows to search for.
Return type:

list

insert(index_id, columns)

Inserts single row using opened index.

Raises ValueError if given data doesn’t validate.

Parameters:
  • index_id (integer) – id of opened index.
  • columns (list) – list of column values for insertion. List must be ordered in the same way as columns are defined in opened index.
Return type:

bool