Kyoto Tycoon Asyncio (3.4+)

Binary protocol of Kyoto Tycoon with asyncio for io batching.

Kyoto Tycoon is a lightweight database server with impressive performance. It can be accessed via several protocols, including an efficient binary protocol which is used in this Python library.

The current implementation of this library provides access to the following commands: set_bulk, get_bulk, remove_bulk (plus some wrapper functions to easily use these commands if you only need to access a single item) and play_script.

The library is implemented in pure Python and requires the module asyncio and other Python standard library modules. Therefore, it is possible to use the library with other interpreters than the standard CPython. The code has been tested with python 3.4 since it is based on the asyncio module introduced in 3.4. If pypy will implement asyncio in can be ported to pypy and possibly other implementation.

class ktasync.KyotoTycoon(host='localhost', port=1978, probe=False, timeout=None, max_connections=4)[source]

New connections are created using the constructor. A connection is automatically closed when the object is destroyed. There is the factory method embedded which creates a server and client connected to it.

Keys and values of database entries are python bytes. You can pickle objects to bytes strings. The encoding is handled by the user when converting to bytes. Usually bytes(bla, encoding=”UTF-8”) is safe.

Parameters:
  • host – The hostname or IP to connect to, defaults to ‘localhost’.
  • port – The port number, defaults to 1978 which is the default port of Kyoto Tycoon.
  • probe – If set to True, the server connection is checked. The connections later are taken from a pool. This option helps to prevent later failures.
  • timeout – Optional timeout for the socket. None means no timeout (please also look at the Python socket manual).
close()[source]

Close the sockets

static embedded(args=None, timeout=None, max_connections=4, range_from=16384, range_to=32767)[source]

Start an embedded Kyoto Tycoon server and return a client conencted to it.

Parameters:
  • args – Additional arguments for the Kyoto Tycoon server.
  • timeout – Optional timeout for the socket. None means no timeout (please also look at the Python socket manual).
  • max_connections – Maximum connections for io batching.
  • range_from – Port range to select a random port from (from).
  • range_to – Port range to select a random port from (to).
Return type:

KyotoTycoon

get(key, db=0, flags=0)[source]

Wrapper function around get_bulk for easily retrieving a single item from the database.

Parameters:
  • key (bytes) – The key of the entry
  • db – The database index. Defaults to 0.
  • flags – reserved and not used now. (defined by protocol)
Returns:

The value of the record, or None if the record could not be found in the database.

get_bulk(recs, flags=0)[source]

Retrieves multiple records at once.

Parameters:
  • recs – iterable (e.g. list) of record descriptions. Each record is a list or tuple of 2 entries: key,db
  • flags – reserved and not used now. (defined by protocol)
Returns:

A list of records. Each record is a tuple of 4 entries: (key, val, db, expire)

get_bulk_keys(keys, db=0, flags=0)[source]

Wrapper function around get_bulk for simplifying the process of retrieving multiple records from the same database.

Parameters:
  • keys – iterable (e.g. list) of keys.
  • db – database index to store the values in. defaults to 0.
  • flags – reserved and not used now. (defined by protocol)
Returns:

dict of key/value pairs.

play_script(name, recs, flags=0)[source]

Calls a procedure of the LUA scripting language extension.

Parameters:
  • name – The name of the LUA function.
  • recs – iterable (e.g. list) of records. Each record is a list or tuple of 2 entries: key, val
  • flags – If set to kyototycoon.FLAG_NOREPLY, function will not wait for an answer of the server.
Returns:

A list of records. Each record is a tuple of 2 entries: (key, val). Or None if flags was set to kyototycoon.FLAG_NOREPLY.

remove(key, db, flags=0)[source]

Wrapper function around remove_bulk for easily removing a single item from the database.

Parameters:
  • key (bytes) – The key of the entry.
  • db – database index to store the values in. defaults to 0.
  • flags – If set to kyototycoon.FLAG_NOREPLY, function will not wait for an answer of the server.
Returns:

The number of removed records, or None if flags was set to kyototycoon.FLAG_NOREPLY

remove_bulk(recs, flags=0)[source]

Remove multiple records at once.

Parameters:
  • recs – iterable (e.g. list) of record descriptions. Each record is a list or tuple of 2 entries: key,db
  • flags – If set to kyototycoon.FLAG_NOREPLY, function will not wait for an answer of the server.
Returns:

The number of removed records, or None if flags was set to kyototycoon.FLAG_NOREPLY

remove_bulk_keys(keys, db, flags=0)[source]

Wrapper function around remove_bulk for simplifying the process of removing multiple records from the same database.

Parameters:
  • keys – iterable (e.g. list) of keys.
  • db – database index to store the values in. defaults to 0.
  • flags – If set to kyototycoon.FLAG_NOREPLY, function will not wait for an answer of the server.
Returns:

The number of removed records, or None if flags was set to kyototycoon.FLAG_NOREPLY

set(key, val, db=0, expire=9223372036854775807, flags=0)[source]

Wrapper function around set_bulk for easily storing a single item in the database.

Parameters:
  • key (bytes) – The key of the entry,
  • val (bytes) – The value of the entry
  • db (int) – Database index to store the record in. Default to 0.
  • expire – Expiration time for all entries. kyototycoon.DEFAULT_EXPIRE is 0x7FFFFFFFFFFFFFFF which means that the records should never expire in the (near) future.
  • flags – If set to kyototycoon.FLAG_NOREPLY, function will not wait for an answer of the server.
Returns:

The number of actually stored records, or None if flags was set to kyototycoon.FLAG_NOREPLY.

set_bulk(recs, flags=0)[source]

Stores multiple records at once.

Parameters:
  • recs – iterable (e.g. list) of records. Each record is a list or tuple of 4 entries: key, val, db, expire
  • flags – If set to kyototycoon.FLAG_NOREPLY, function will not wait for an answer of the server.
Returns:

The number of actually stored records, or None if flags was set to kyototycoon.FLAG_NOREPLY.

set_bulk_kv(kv, db=0, expire=9223372036854775807, flags=0)[source]

Wrapper function around set_bulk for simplifying the process of storing multiple records with equal expiration times in the same database.

Parameters:
  • kv – dict of key/value pairs.
  • db – database index to store the values in. defaults to 0.
  • expire – Expiration time for all entries. kyototycoon.DEFAULT_EXPIRE is 0x7FFFFFFFFFFFFFFF which means that the records should never expire in the (near) future.
  • flags – If set to kyototycoon.FLAG_NOREPLY, function will not wait for an answer of the server.
Returns:

The number of actually stored records, or None if flags was set to kyototycoon.FLAG_NOREPLY.

exception ktasync.KyotoTycoonError[source]

Class for Exceptions in this module

Indices and tables