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
orKT_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
isTrue
, 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 asget()
.
-
__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 avalue
or a 2-tuple consisting of(value, expire_time)
. Follows same semantics asset()
.
-
__delitem__
(key_or_keydb)¶ Item-deletion based on either
key
or a 2-tuple consisting of(key, db)
. Follows same semantics asremove()
.
-
__contains__
(key_or_keydb)¶ Check if key exists. Accepts either
key
or a 2-tuple consisting of(key, db)
. Follows same semantics asexists()
.
-
__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)¶
-
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
orKT_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 toget()
.Note
If the database is a tree, a slice of keys can be used to retrieve an ordered range of values.
-
__len__
()¶ Returns: total number of keys in the database. Return type: int
-
update
(__data=None, db=None, expire_time=None, **kwargs)¶
-
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.
-
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.
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.