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.

TT_TABLE

Special serializer for use with TokyoTyrant’s remote table database. Values are represented as dictionaries.

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.
get_raw(key, db=None)
Parameters:
  • key (str) – key to look-up
  • db (int or None) – database index
Returns:

raw bytestring 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
get_bulk_raw(keys, db=None)
Parameters:
  • keys (list) – list of keys to look-up
  • db (int or None) – database index
Returns:

dictionary of all key/raw-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.

synchronize(hard=False, command=None, db=None)
Parameters:
  • hard (bool) – perform a “hard” synchronization
  • command (str) – command to run after synchronization
  • db (int or None) – database index
Returns:

boolean indicating success
vacuum(step=0, db=None)
Parameters:
  • step (int) – number of steps, default is 0
  • db (int or None) – database index
Returns:

boolean indicating success
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
count(db=None)
Parameters:db (int or None) – database index
Returns:total number of keys in the database.
Return type:int

Count total number of keys in the database.

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
cursor(db=None, cursor_id=None)
Parameters:
  • db (int or None) – database index
  • cursor_id (int or None) – cursor id (will be automatically created if None)
Returns:

Cursor object
keys(db=None)
Parameters:db (int or None) – database index
Returns:all keys in database
Return type:generator
values(db=None)
Parameters:db (int or None) – database index
Returns:all values in database
Return type:generator
items(db=None)
Parameters:db (int or None) – database index
Returns:all key/value tuples in database
Return type:generator
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.
get_raw(key)
Parameters:key (str) – key to look-up
Returns:raw binary 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
get_bulk_raw(keys)
Parameters:keys (list) – list of keys to look-up
Returns:dictionary of all key/raw-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, lock_records=False, lock_all=False, encode_value=True, decode_result=False)
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)
  • lock_records (bool) – lock records modified during script execution
  • lock_all (bool) – lock all records during script execution
  • encode_value (bool) – serialize the value before sending to the script
  • decode_result (bool) – deserialize the script return value
Returns:

byte-string or obj returned by function (depending on decode_result)

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().

addshl(key, value, width)
Parameters:
  • key (str) – key to append value to
  • value – data to append (will be serialized using serializer)
  • width (int) – number of bytes to shift
Returns:

boolean indicating success
Return type:

bool

Concatenate a value at the end of the existing record and shift it to the left by width bytes.

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

no return value

Set with no server response.

setnr_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:

no return value

Set multiple key/value pairs using the same no-response API as TokyoTyrant.setnr().

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

boolean indicating success

Set key/value pair. If using a BTree and the key already exists, the new value will be added to the end.

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

boolean indicating success

Set key/value pair. If using a BTree and the key already exists, the new value will be added to the front.

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
length(key)
Parameters:key (str) – key to test
Returns:length of value stored at key (or None if key does not exist)
Return type:int
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, args=None, update_log=True)
Parameters:
  • cmd (str) – Command to execute
  • args (list) – Zero or more bytestring arguments to misc function.
  • update_log (bool) – Add misc command to update log.

Run a miscellaneous command using the “misc” API. Returns a list of zero or more bytestrings.

count()
Returns:number of key/value pairs in the database
Return type:int
__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 a 2-tuple of error code and message for the last error reported by the server (if set).

optimize(options)
Parameters:options (str) – option format string to use when optimizing database.
Returns:boolean indicating success
synchronize()
Returns:boolean indicating success

Synchronize data to disk.

copy(path)
Parameters:path (str) – destination for copy of database.
Returns:boolean indicating success

Copy the database file to the given path.

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
items()
Returns:list of all key/value tuples in database
Return type:list
set_index(name, index_type, check_exists=False)
Parameters:
  • name (str) – column name to index
  • index_type (int) – see Index types for values
  • check_exists (bool) – if true, an error will be raised if the index already exists.
Returns:

boolean indicating success

Create an index on the given column in a table database.

optimize_index(name)
Parameters:name (str) – column name index to optimize
Returns:boolean indicating success

Optimize the index on a given column.

delete_index(name)
Parameters:name (str) – column name index to delete
Returns:boolean indicating success

Delete the index on a given column.

search(expressions, cmd=None)
Parameters:
  • expressions (list) – zero or more search expressions
  • cmd (str) – extra command to apply to search results
Returns:

varies depending on cmd.

Perform a search on a table database. Rather than call this method directly, it is recommended that you use the QueryBuilder to construct and execute table queries.

genuid()
Returns:integer id

Generate a unique ID.

class QueryBuilder

Construct and execute table queries.

filter(column, op, value)
Parameters:
  • column (str) – column name to filter on
  • op (int) – operation, see Filter types for available values
  • value – value for filter expression

Add a filter expression to the query.

order_by(column, ordering=None)
Parameters:
  • column (str) – column name to order by
  • ordering (int) – ordering method, defaults to lexical ordering. See Ordering types for available values.

Specify ordering of query results.

limit(limit=None)
Parameters:limit (int) – maximum number of results

Limit the number of results returned by query.

offset(offset=None)
Parameters:offset (int) – number of results to skip over.

Skip over results returned by query.

execute(client)
Parameters:client (TokyoTyrant) – database client
Returns:list of keys matching query criteria
Return type:list

Execute the query and return a list of the keys of matching records.

delete(client)
Parameters:client (TokyoTyrant) – database client
Returns:boolean indicating success

Delete records that match the query criteria.

get(client)
Parameters:client (TokyoTyrant) – database client
Returns:list of 2-tuples consisting of key, value.
Rtype list:

Execute query and return a list of keys and values for records matching the query criteria.

count(client)
Parameters:client (TokyoTyrant) – database client
Returns:number of query results

Return count of matching records.

Index types

INDEX_STR
INDEX_NUM
INDEX_TOKEN
INDEX_QGRAM

Filter types

OP_STR_EQ
OP_STR_CONTAINS
OP_STR_STARTSWITH
OP_STR_ENDSWITH
OP_STR_ALL
OP_STR_ANY
OP_STR_ANYEXACT
OP_STR_REGEX
OP_NUM_EQ
OP_NUM_GT
OP_NUM_GE
OP_NUM_LT
OP_NUM_LE
OP_NUM_BETWEEN
OP_NUM_ANYEXACT
OP_FTS_PHRASE
OP_FTS_ALL
OP_FTS_ANY
OP_FTS_EXPRESSION
OP_NEGATE

Combine with other operand using bitwise-or to negate the filter.

OP_NOINDEX

Combine with other operand using bitwise-or to prevent using an index.

Ordering types

ORDER_STR_ASC
ORDER_STR_DESC
ORDER_NUM_ASC
ORDER_NUM_DESC

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.