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, connection_pool=False, 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).
  • connection_pool (bool) – use a connection pool to manage sockets.
  • default_db (int) – default database to operate on.

Client for interacting with Kyoto Tycoon database.

close(allow_reuse=True)
Parameters:allow_reuse (bool) – when the connection pool is enabled, this flag indicates whether the connection can be reused. For unpooled clients this flag has no effect.

Close the connection to the server.

close_all()

When using the connection pool, this method can close all client connections.

get_bulk(keys, db=None, decode_values=True)
Parameters:
  • keys (list) – keys to retrieve
  • db (int) – database index
  • decode_values (bool) – decode values using the configured serialization scheme.
Returns:

result dictionary

Efficiently retrieve multiple key/value pairs from the database. If a key does not exist, it will not be present in the result dictionary.

get_bulk_details(keys, db=None, decode_values=True)
Parameters:
  • keys (list) – keys to retrieve
  • db (int) – database index
  • decode_values (bool) – decode values using the configured serialization scheme.
Returns:

List of tuples: (db index, key, value, expire time)

Like get_bulk(), but the return value is a list of tuples with additional information for each key.

get_bulk_raw(db_key_list, decode_values=True)
Parameters:
  • db_key_list – a list of 2-tuples to retrieve: (db index, key)
  • decode_values (bool) – decode values using the configured serialization scheme.
Returns:

result dictionary

Like get_bulk(), except it supports fetching key/value pairs from multiple databases. The input is a list of 2-tuples consisting of (db, key) and the return value is a dictionary of key: value pairs.

get_bulk_raw_details(db_key_list, decode_values=True)
Parameters:
  • db_key_list – a list of 2-tuples to retrieve: (db index, key)
  • decode_values (bool) – decode values using the configured serialization scheme.
Returns:

List of tuples: (db index, key, value, expire time)

Like get_bulk_raw(), but the return value is a list of tuples with additional information for each key.

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

deserialized value or None if key does not exist.

Fetch and (optionally) deserialize the value for the given key.

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

raw bytestring value or None if key does not exist.

Fetch the value for the given key. The resulting value will not be deserialized.

set_bulk(data, db=None, expire_time=None, no_reply=False, encode_values=True)
Parameters:
  • data (dict) – mapping of key/value pairs to set.
  • db (int) – database index
  • expire_time (int) – expiration time in seconds
  • no_reply (bool) – execute the operation without a server acknowledgment.
  • encode_values (bool) – serialize the values using the configured serialization scheme (e.g., KT_MSGPACK).
Returns:

number of keys that were set, or None if no_reply.

Efficiently set multiple key/value pairs. If given, the provided db and expire_time values will be used for all key/value pairs being set.

set_bulk_raw(data, no_reply=False, encode_values=True)
Parameters:
  • data (list) – a list of 4-tuples: (db, key, value, expire time)
  • no_reply (bool) – execute the operation without a server acknowledgment.
  • encode_values (bool) – serialize the values using the configured serialization scheme (e.g., KT_MSGPACK).
Returns:

number of keys that were set, or None if no_reply.

Efficiently set multiple key/value pairs. Unlike set_bulk(), this method can be used to set key/value pairs in multiple databases in a single call, and each key can specify its own expire time.

set(key, value, db=None, expire_time=None, no_reply=False)
Parameters:
  • key (str) – key to set
  • value – value to store (will be serialized using serializer)
  • db (int) – database index
  • expire_time (int) – expiration time in seconds
  • no_reply (bool) – execute the operation without a server acknowledgment.
Returns:

number of rows set (1)

Set a single key/value pair.

set_bytes(key, value, db=None, expire_time=None, no_reply=False)
Parameters:
  • key (str) – key to set
  • value – raw value to store
  • db (int) – database index
  • expire_time (int) – expiration time in seconds
  • no_reply (bool) – execute the operation without a server acknowledgment.
Returns:

number of rows set (1)

Set a single key/value pair without encoding the value.

remove_bulk(keys, db=None, no_reply=False)
Parameters:
  • keys (list) – list of keys to remove
  • db (int) – database index
  • no_reply (bool) – execute the operation without a server acknowledgment.
Returns:

number of keys that were removed

remove_bulk_raw(db_key_list, no_reply=False)
Parameters:
  • db_key_list – a list of 2-tuples to retrieve: (db index, key)
  • no_reply (bool) – execute the operation without a server acknowledgment.
Returns:

number of keys that were removed

Like remove_bulk(), but allows keys to be removed from multiple databases in a single call.

remove(key, db=None, no_reply=False)
Parameters:
  • key (str) – key to remove
  • db (int) – database index
  • no_reply (bool) – execute the operation without a server acknowledgment.
Returns:

number of rows removed

script(name, data=None, no_reply=False, encode_values=True, decode_values=True)
Parameters:
  • name (str) – name of lua function to call
  • data (dict) – mapping of key/value pairs to pass to lua function.
  • no_reply (bool) – execute the operation without a server acknowledgment.
  • encode_values (bool) – serialize values passed to lua function.
  • decode_values (bool) – deserialize values returned by lua function.
Returns:

dictionary of key/value pairs returned by function

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. Likewise, if decode_values is True the values returned by the Lua function will be deserialized using the configured serializer.

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

Remove all keys from the database.

status(db=None)
Parameters:db (int) – 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.

ulog_list()
Returns:a list of 3-tuples describing the files in the update log.

Returns a list of metadata about the state of the update log. For each file in the update log, a 3-tuple is returned. For example:

>>> kt.ulog_list()
[('/var/lib/database/ulog/kt/0000000037.ulog',
  '67150706',
  datetime.datetime(2019, 1, 4, 1, 28, 42, 43000)),
 ('/var/lib/database/ulog/kt/0000000038.ulog',
  '14577366',
  datetime.datetime(2019, 1, 4, 1, 41, 7, 245000))]
ulog_remove(max_dt)
Parameters:max_dt (datetime) – maximum datetime to preserve
Returns:boolean indicating success

Removes all update-log files older than the given datetime.

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

boolean indicating success

Synchronize the database, optionally executing the given command upon success. This can be used to create hot backups, for example.

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

boolean indicating success

add(key, value, db=None, expire_time=None, encode_value=True)
Parameters:
  • key (str) – key to add
  • value – value to store
  • db (int) – database index
  • expire_time (int) – expiration time in seconds
  • encode_value (bool) – serialize the value using the configured serialization method.
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, encode_value=True)
Parameters:
  • key (str) – key to replace
  • value – value to store
  • db (int) – database index
  • expire_time (int) – expiration time in seconds
  • encode_value (bool) – serialize the value using the configured serialization method.
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, encode_value=True)
Parameters:
  • key (str) – key to append value to
  • value – data to append
  • db (int) – database index
  • expire_time (int) – expiration time in seconds
  • encode_value (bool) – serialize the value using the configured serialization method.
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) – database index
Returns:

boolean indicating if key exists

Return whether or not the given key exists in the database.

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

length of the value in bytes, or None if not found

Return the length of the raw value stored at the given key. If the key does not exist, returns None.

seize(key, db=None, decode_value=True)
Parameters:
  • key (str) – key to remove
  • db (int) – database index
  • decode_value (bool) – deserialize the value using the configured serialization method.
Returns:

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

Get and remove the data stored in a given key in a single operation.

cas(key, old_val, new_val, db=None, expire_time=None, encode_value=True)
Parameters:
  • key (str) – key to append value to
  • old_val – original value to test
  • new_val – new value to store
  • db (int) – database index
  • expire_time (int) – expiration time in seconds
  • encode_value (bool) – serialize the old and new values using the configured serialization method.
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) – database index
  • expire_time (int) – expiration time in seconds
Returns:

new value at key

Return type:

int

Increment the value stored in the given key.

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) – database index
  • expire_time (int) – expiration time in seconds
Returns:

new value at key

Return type:

float

Increment the floating-point value stored in the given key.

__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, no_reply=False, encode_values=True, **kwargs)

Efficiently set multiple key/value pairs. If given, the provided db and expire_time values will be used for all key/value pairs being set.

See KyotoTycoon.set_bulk() for details.

pop(key, db=None, decode_value=True)

Get and remove the data stored in a given key in a single operation.

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

Cursor object

keys(db=None)
Parameters:db (int) – database index
Returns:all keys in database
Return type:generator

Warning

The keys() method uses a cursor and can be rather slow.

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

Non-lazy implementation of keys(). Behind-the-scenes, calls match_prefix() with an empty string as the prefix.

values(db=None)
Parameters:db (int) – database index
Returns:all values in database
Return type:generator
items(db=None)
Parameters:db (int) – 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 index for the client.

Tokyo Tyrant client

class TokyoTyrant(host='127.0.0.1', port=1978, serializer=KT_BINARY, decode_keys=True, timeout=None, connection_pool=False)
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, KT_PICKLE, or TT_TABLE (for use with table databases).
  • decode_keys (bool) – automatically decode keys, encoded as UTF-8.
  • timeout (int) – socket timeout (optional).
  • connection_pool (bool) – use a connection pool to manage sockets.

Client for interacting with Tokyo Tyrant database.

close(allow_reuse=True)
Parameters:allow_reuse (bool) – when the connection pool is enabled, this flag indicates whether the connection can be reused. For unpooled clients this flag has no effect.

Close the connection to the server.

close_all()

When using the connection pool, this method can close all client connections.

get_bulk(keys, decode_values=True)
Parameters:
  • keys (list) – list of keys to retrieve
  • decode_values (bool) – decode values using the configured serialization scheme.
Returns:

dictionary of all key/value pairs that were found

Efficiently retrieve multiple key/value pairs from the database. If a key does not exist, it will not be present in the result dictionary.

get(key)
Parameters:key (str) – key to look-up
Returns:deserialized value or None if key does not exist.

Fetch and (optionally) deserialize the value for the given key.

get_bytes(key)
Parameters:key (str) – key to look-up
Returns:raw bytestring value or None if key does not exist.

Fetch the value for the given key. The resulting value will not be deserialized.

set_bulk(data, no_reply=False, encode_values=True)
Parameters:
  • data (dict) – mapping of key/value pairs to set.
  • no_reply (bool) – execute the operation without a server acknowledgment.
  • encode_values (bool) – serialize the values using the configured serialization scheme (e.g., KT_MSGPACK).
Returns:

boolean indicating success, or None if no_reply.

Efficiently set multiple key/value pairs.

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

boolean indicating success

Set a single key/value pair.

set_bytes(key, value)
Parameters:
  • key (str) – key to set
  • value – raw value to store
Returns:

boolean indicating success

Set a single key/value pair without encoding the value.

remove_bulk(keys)
Parameters:keys (list) – list of keys to remove
Returns:boolean indicating success
remove(key)
Parameters:key (str) – key to remove
Returns:boolean indicating success
script(name, key=None, value=None, lock_records=False, lock_all=False, encode_value=True, decode_result=False, as_list=False, as_dict=False, as_int=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_value (bool) – deserialize the script return value
  • as_list (bool) – deserialize newline-separated value into a list
  • as_dict (bool) – deserialize list of tab-separated key/value pairs into dict
  • as_int (bool) – return value as integer
Returns:

byte-string or object returned by function (depending on decode_value)

Execute a lua function, passing as arguments the given key and value (if provided). The return value is a bytestring, which can be deserialized by specifying decode_value=True. The arguments as_list, as_dict and as_int can be used to apply specific deserialization to the returned value.

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.

synchronize()
Returns:boolean indicating success

Synchronize data to disk.

optimize(options)
Parameters:options (str) – option format string to use when optimizing database.
Returns:boolean indicating success
add(key, value, encode_value=True)
Parameters:
  • key (str) – key to add
  • value – value to store
  • encode_value (bool) – serialize the value using the configured serialization scheme.
Returns:

boolean indicating if key could be added or not

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, encode_value=True)
Parameters:
  • key (str) – key to append value to
  • value – value to append
  • encode_value (bool) – serialize the value using the configured serialization scheme.
Returns:

boolean indicating if value was appended

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

addshl(key, value, width, encode_value=True)
Parameters:
  • key (str) – key to append value to
  • value – data to append
  • width (int) – number of bytes to shift
  • encode_value (bool) – serialize the value using the configured serialization scheme.
Returns:

boolean indicating success

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

exists(key)
Parameters:key (str) – key to test
Returns:boolean indicating if key exists

Return whether or not the given key exists in the database.

length(key)
Parameters:
  • key (str) – key
  • db (int) – database index
Returns:

length of the value in bytes, or None if not found

Return the length of the raw value stored at the given key. If the key does not exist, returns None.

seize(key, decode_value=True)
Parameters:
  • key (str) – key to remove
  • decode_value (bool) – deserialize the value using the configured serialization method.
Returns:

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

Get and remove the data stored in a given key in a single operation.

incr(key, n=1)
Parameters:
  • key (str) – key to increment
  • n (int) – value to add
Returns:

incremented result value

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

incremented result value

Increment the floating-point value stored in the given key.

count()
Returns:number of key/value pairs in the database
Return type:int

Count the number of key/value pairs in the database

__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.

Identical to count().

update(__data=None, no_reply=False, encode_values=True, **kwargs)
Parameters:
  • __data (dict) – mapping of key/value pairs to set.
  • no_reply (bool) – execute the operation without a server acknowledgment.
  • encode_values (bool) – serialize the values using the configured serialization scheme.
  • kwargs – arbitrary key/value pairs to set.
Returns:

boolean indicating success.

Efficiently set multiple key/value pairs. Data can be provided as a dict or as an arbitrary number of keyword arguments.

See also: set_bulk().

setdup(key, value, encode_value=True)
Parameters:
  • key (str) – key to set
  • value – value to store
  • encode_value (bool) – serialize the value using the configured serialization scheme.
Returns:

boolean indicating success

Set key/value pair. If using a B-Tree and the key already exists, the new value will be added to the beginning.

setdupback(key, value)
Parameters:
  • key (str) – key to set
  • value – value to store
  • encode_value (bool) – serialize the value using the configured serialization scheme.
Returns:

boolean indicating success

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

get_part(key, start=None, end=None, decode_value=True)
Parameters:
  • key (str) – key to look-up
  • start (int) – start offset
  • end (int) – number of characters to retrieve (after start).
  • decode_value (bool) – deserialize the value using the configured serialization scheme.
Returns:

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

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.

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

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

Copy the database file to the given path.

restore(path, timestamp, options=0)
Parameters:
  • path (str) – path to update log directory
  • timestamp (datetime) – datetime from which to restore
  • options (int) – optional flags
Returns:

boolean indicating success

Restore the database file from the update log.

set_master(host, port, timestamp, options=0)
Parameters:
  • host (str) – host of master server
  • port (int) – port of master server
  • timestamp (datetime) – start timestamp
  • options (int) – optional flags
Returns:

boolean indicating success

Set the replication master.

clear_cache()
Returns:boolean indicating success
defragment(nsteps=None)
Parameters:nsteps (int) – number of defragmentation steps
Returns:boolean indicating success

Defragment the database.

get_range(start, stop=None, max_keys=0, decode_values=True)
Parameters:
  • start (str) – start-key for range
  • stop (str) – stop-key for range (optional)
  • max_keys (int) – maximum keys to fetch
  • decode_values (bool) – deserialize the values using the configured serialization scheme.
Returns:

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

Fetch a range of key/value pairs and return them as a dictionary.

Note

Only works with tree databases.

get_rangelist(start, stop=None, max_keys=0, decode_values=True)
Parameters:
  • start (str) – start-key for range
  • stop (str) – stop-key for range (optional)
  • max_keys (int) – maximum keys to fetch
  • decode_values (bool) – deserialize the values using the configured serialization scheme.
Returns:

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

Fetch a range of key/value pairs and return them as an ordered list of key/value tuples.

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.

match_regex(regex, max_keys=None, decode_values=True)
Parameters:
  • regex (str) – regular-expression to match
  • max_keys (int) – maximum number of results to return
  • decode_values (bool) – deserialize the values using the configured serialization scheme.
Returns:

a dictionary mapping of key-value pairs which matched the regex.

match_regexlist(regex, max_keys=None, decode_values=True)
Parameters:
  • regex (str) – regular-expression to match
  • max_keys (int) – maximum number of results to return
  • decode_values (bool) – deserialize the values using the configured serialization scheme.
Returns:

a list of ordered key-value pairs which matched the regex.

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

Return a list of all keys in the database in a single operation.

items()
Returns:list all key/value tuples in database
Return type:generator
items_fast()
Returns:list of all key/value tuples in database in a single operation.
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.