API

Serializers

KT_BINARY

Default value serialization. Serializes values as UTF-8 byte-strings and deserializes to unicode.

KT_JSON

Serialize values as JSON (encoded as UTF-8).

KT_MSGPACK

Uses msgpack to serialize and deserialize values.

KT_NONE

No serialization or deserialization. Values must be byte-strings.

KT_PICKLE

Serialize and deserialize using Python’s pickle module.

Kyoto Tycoon client

class KyotoTycoon(host='127.0.0.1', port=1978, serializer=KT_BINARY, decode_keys=True, timeout=None, default_db=0)
Parameters:
  • host (str) – server host.
  • port (int) – server port.
  • serializer – serialization method to use for storing/retrieving values. Accepts KT_BINARY, KT_JSON, KT_MSGPACK, KT_NONE or KT_PICKLE.
  • decode_keys (bool) – allow unicode keys, encoded as UTF-8.
  • timeout (int) – socket timeout (optional).
  • default_db (int) – default database to operate on.

Client for interacting with Kyoto Tycoon database.

checkin()

Return the communication socket to the pool for re-use.

close()

Close the connection to the server.

get(key, db=None)
Parameters:
  • key (str) – key to look-up
  • db (int or None) – database index
Returns:

deserialized value or None if key does not exist.

set(key, value, db=None, expire_time=None)
Parameters:
  • key (str) – key to set
  • value – value to store (will be serialized using serializer)
  • db (int or None) – database index
  • expire_time (int or None) – expiration time in seconds
Returns:

number of rows set (1)

remove(key, db=None)
Parameters:
  • key (str) – key to remove
  • db (int or None) – database index
Returns:

number of rows removed

get_bulk(keys, db=None)
Parameters:
  • keys (list) – list of keys to look-up
  • db (int or None) – database index
Returns:

dictionary of all key/value pairs that were found

Return type:

dict

set_bulk(__data=None, db=None, expire_time=None, **kwargs)
Parameters:
  • __data (dict) – mapping of key/value pairs to set.
  • db (int or None) – database index
  • expire_time (int or None) – expiration time in seconds
  • kwargs – mapping of key/value pairs to set, expressed as keyword arguments
Returns:

number of keys that were set

remove_bulk(keys, db=None)
Parameters:
  • keys (list) – list of keys to remove
  • db (int or None) – database index
Returns:

number of keys that were removed

script(name, __data=None, encode_values=True, **kwargs)
Parameters:
  • name (str) – name of lua function to call
  • __data (dict) – mapping of key/value pairs to pass to lua function.
  • encode_values (bool) – serialize values passed to lua function.
  • kwargs – mapping of key/value pairs to pass to lua function, expressed as keyword arguments
Returns:

dictionary of key/value pairs returned by function

Return type:

dict

Execute a lua function. Kyoto Tycoon lua extensions accept arbitrary key/value pairs as input, and return a result dictionary. If encode_values is True, the input values will be serialized and the result values will be deserialized using the client’s serializer.

clear(db=None)
Parameters:db (int or None) – database index
Returns:boolean indicating success

Remove all keys from the database.

status(db=None)
Parameters:db (int or None) – database index
Returns:status fields and values
Return type:dict

Obtain status information from the server about the selected database.

report()
Returns:status fields and values
Return type:dict

Obtain report on overall status of server, including all databases.

add(key, value, db=None, expire_time=None)
Parameters:
  • key (str) – key to add
  • value – value to store (will be serialized using serializer)
  • db (int or None) – database index
  • expire_time (int or None) – expiration time in seconds
Returns:

boolean indicating if key could be added or not

Return type:

bool

Add a key/value pair to the database. This operation will only succeed if the key does not already exist in the database.

replace(key, value, db=None, expire_time=None)
Parameters:
  • key (str) – key to replace
  • value – value to store (will be serialized using serializer)
  • db (int or None) – database index
  • expire_time (int or None) – expiration time in seconds
Returns:

boolean indicating if key could be replaced or not

Return type:

bool

Replace a key/value pair to the database. This operation will only succeed if the key alreadys exist in the database.

append(key, value, db=None, expire_time=None)
Parameters:
  • key (str) – key to append value to
  • value – data to append (will be serialized using serializer)
  • db (int or None) – database index
  • expire_time (int or None) – expiration time in seconds
Returns:

boolean indicating if value was appended

Return type:

bool

Appends data to an existing key/value pair. If the key does not exist, this is equivalent to set().

exists(key, db=None)
Parameters:
  • key (str) – key to test
  • db (int or None) – database index
Returns:

boolean indicating if key exists

Return type:

bool

seize(key, db=None)
Parameters:
  • key (str) – key to remove
  • db (int or None) – database index
Returns:

value stored at given key or None if key does not exist.

Get and remove the data stored in a given key.

cas(key, old_val, new_val, db=None, expire_time=None)
Parameters:
  • key (str) – key to append value to
  • old_val – original value to test
  • old_val – new value to store
  • db (int or None) – database index
  • expire_time (int or None) – expiration time in seconds
Returns:

boolean indicating if compare-and-swap succeeded.

Return type:

bool

Compare-and-swap the value stored at a given key.

incr(key, n=1, orig=None, db=None, expire_time=None)
Parameters:
  • key (str) – key to increment
  • n (int) – value to add
  • orig (int) – default value if key does not exist
  • db (int or None) – database index
  • expire_time (int or None) – expiration time in seconds
Returns:

new value at key

Return type:

int

incr_double(key, n=1., orig=None, db=None, expire_time=None)
Parameters:
  • key (str) – key to increment
  • n (float) – value to add
  • orig (float) – default value if key does not exist
  • db (int or None) – database index
  • expire_time (int or None) – expiration time in seconds
Returns:

new value at key

Return type:

float

__getitem__(key_or_keydb)

Item-lookup based on either key or a 2-tuple consisting of (key, db). Follows same semantics as get().

__setitem__(key_or_keydb, value_or_valueexpire)

Item-setting based on either key or a 2-tuple consisting of (key, db). Value consists of either a value or a 2-tuple consisting of (value, expire_time). Follows same semantics as set().

__delitem__(key_or_keydb)

Item-deletion based on either key or a 2-tuple consisting of (key, db). Follows same semantics as remove().

__contains__(key_or_keydb)

Check if key exists. Accepts either key or a 2-tuple consisting of (key, db). Follows same semantics as exists().

__len__()
Returns:total number of keys in the default database.
Return type:int
update(__data=None, db=None, expire_time=None, **kwargs)

See KyotoTycoon.set_bulk().

pop(key, db=None)

See KyotoTycoon.seize().

match_prefix(prefix, max_keys=None, db=None)
Parameters:
  • prefix (str) – key prefix to match
  • max_keys (int) – maximum number of results to return (optional)
  • db (int or None) – database index
Returns:

list of keys that matched the given prefix.

Return type:

list

match_regex(regex, max_keys=None, db=None)
Parameters:
  • regex (str) – regular-expression to match
  • max_keys (int) – maximum number of results to return (optional)
  • db (int or None) – database index
Returns:

list of keys that matched the given regular expression.

Return type:

list

match_similar(origin, distance=None, max_keys=None, db=None)
Parameters:
  • origin (str) – source string for comparison
  • distance (int) – maximum edit-distance for similarity (optional)
  • max_keys (int) – maximum number of results to return (optional)
  • db (int or None) – database index
Returns:

list of keys that were within a certain edit-distance of origin

Return type:

list

keys(db=None)
Parameters:db (int or None) – database index
Returns:list of all keys in database
Return type:list
size

Property which exposes the size information returned by the status() API, for the default database.

path

Property which exposes the filename/path returned by the status() API, for the default database.

set_database(db)
Parameters:db (int) – database index

Specify the default database for the client.

Tokyo Tyrant client

class TokyoTyrant(host='127.0.0.1', port=1978, serializer=KT_BINARY, decode_keys=True, timeout=None)
Parameters:
  • host (str) – server host.
  • port (int) – server port.
  • serializer – serialization method to use for storing/retrieving values. Accepts KT_BINARY, KT_JSON, KT_MSGPACK, KT_NONE or KT_PICKLE.
  • decode_keys (bool) – allow unicode keys, encoded as UTF-8.
  • timeout (int) – socket timeout (optional).
  • default_db (int) – default database to operate on.

Client for interacting with Tokyo Tyrant database.

checkin()

Return the communication socket to the pool for re-use.

close()

Close the connection to the server.

get(key)
Parameters:key (str) – key to look-up
Returns:deserialized value or None if key does not exist.
set(key, value)
Parameters:
  • key (str) – key to set
  • value – value to store (will be serialized using serializer)
Returns:

boolean indicating success

remove(key)
Parameters:key (str) – key to remove
Returns:number of rows removed
get_bulk(keys)
Parameters:keys (list) – list of keys to look-up
Returns:dictionary of all key/value pairs that were found
Return type:dict
set_bulk(__data=None, **kwargs)
Parameters:
  • __data (dict) – mapping of key/value pairs to set.
  • kwargs – mapping of key/value pairs to set, expressed as keyword arguments
Returns:

boolean indicating success

remove_bulk(keys)
Parameters:keys (list) – list of keys to remove
Returns:boolean indicating success
script(name, key=None, value=None)
Parameters:
  • name (str) – name of lua function to call
  • key (str) – key to pass to lua function (optional)
  • value (str) – value to pass to lua function (optional)
Returns:

byte-string returned by function

Return type:

bytes

Execute a lua function. Tokyo Tyrant lua extensions accept two parameters, a key and a value, and return a result byte-string.

clear()
Returns:boolean indicating success

Remove all keys from the database.

status()
Returns:status fields and values
Return type:dict

Obtain status information from the server.

add(key, value)
Parameters:
  • key (str) – key to add
  • value – value to store (will be serialized using serializer)
Returns:

boolean indicating if key could be added or not

Return type:

bool

Add a key/value pair to the database. This operation will only succeed if the key does not already exist in the database.

append(key, value)
Parameters:
  • key (str) – key to append value to
  • value – data to append (will be serialized using serializer)
Returns:

boolean indicating if value was appended

Return type:

bool

Appends data to an existing key/value pair. If the key does not exist, this is equivalent to set().

get_part(key, start=None, end=None)
Parameters:
  • key (str) – key to look-up
  • start (int) – start offset
  • end (int) – number of characters to retrieve (after start).
Returns:

the substring portion of value requested or False if the value does not exist or the start index exceeded the value length.

exists(key)
Parameters:key (str) – key to test
Returns:boolean indicating if key exists
Return type:bool
incr(key, n=1)
Parameters:
  • key (str) – key to increment
  • n (int) – value to add
Returns:

new value at key

Return type:

int

incr_double(key, n=1.)
Parameters:
  • key (str) – key to increment
  • n (float) – value to add
Returns:

new value at key

Return type:

float

misc(cmd, keys=None, data=None)
Parameters:
  • cmd (str) – Command to execute
  • keys (list) – List of arguments for command
  • data (dict) – Key/value data for command

Run a miscellaneous command using the “misc” API. Returns different values depending on command being executed.

__getitem__(key)

Get value at given key. Identical to get().

Note

If the database is a tree, a slice of keys can be used to retrieve an ordered range of values.

__setitem__(key, value)

Set value at given key. Identical to set().

__delitem__(key)

Remove the given key. Identical to remove().

__contains__(key)

Check if given key exists. Identical to exists().

__len__()
Returns:total number of keys in the database.
Return type:int
update(__data=None, db=None, expire_time=None, **kwargs)

See TokyoTyrant.set_bulk().

size

Property which exposes the size of the database.

error

Return the error message for the last error reported by the server.

get_range(start, stop=None, max_keys=0)
Parameters:
  • start (str) – start-key for range
  • stop (str) – stop-key for range (optional)
  • max_keys (int) – maximum keys to fetch
Returns:

a mapping of key-value pairs falling within the given range.

Return type:

dict

Note

Only works with tree databases.

match_prefix(prefix, max_keys=1024)
Parameters:
  • prefix (str) – key prefix to match
  • max_keys (int) – maximum number of results to return
Returns:

list of keys that matched the given prefix.

Return type:

list

match_regex(regex, max_keys=1024)
Parameters:
  • regex (str) – regular-expression to match
  • max_keys (int) – maximum number of results to return
Returns:

list of keys that matched the given regular expression.

Return type:

list

iter_from(start_key)
Parameters:start_key – key to start iteration.
Returns:list of key/value pairs obtained by iterating from start-key.
Return type:dict
keys()
Returns:list of all keys in database
Return type:list

Embedded Servers

class EmbeddedServer(server='ktserver', host='127.0.0.1', port=None, database='*', server_args=None)
Parameters:
  • server (str) – path to ktserver executable
  • host (str) – host to bind server on
  • port (int) – port to use (optional)
  • database (str) – database filename, default is in-memory hash table
  • server_args (list) – additional command-line arguments for server

Create a manager for running an embedded (sub-process) Kyoto Tycoon server. If the port is not specified, a random high port will be used.

Example:

>>> from kt import EmbeddedServer
>>> server = EmbeddedServer()
>>> server.run()
True
>>> client = server.client
>>> client.set('k1', 'v1')
1
>>> client.get('k1')
'v1'
>>> server.stop()
True
run()
Returns:boolean indicating if server successfully started

Run ktserver in a sub-process.

stop()
Returns:boolean indicating if server was stopped

Stop the running embedded server.

client

KyotoTycoon client bound to the embedded server.

class EmbeddedTokyoTyrantServer(server='ttserver', host='127.0.0.1', port=None, database='*', server_args=None)
Parameters:
  • server (str) – path to ttserver executable
  • host (str) – host to bind server on
  • port (int) – port to use (optional)
  • database (str) – database filename, default is in-memory hash table
  • server_args (list) – additional command-line arguments for server

Create a manager for running an embedded (sub-process) Tokyo Tyrant server. If the port is not specified, a random high port will be used.

Example:

>>> from kt import EmbeddedTokyoTyrantServer
>>> server = EmbeddedTokyoTyrantServer()
>>> server.run()
True
>>> client = server.client
>>> client.set('k1', 'v1')
True
>>> client.get('k1')
'v1'
>>> server.stop()
True
run()
Returns:boolean indicating if server successfully started

Run ttserver in a sub-process.

stop()
Returns:boolean indicating if server was stopped

Stop the running embedded server.

client

TokyoTyrant client bound to the embedded server.