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 only requires the modules socket and struct (Python standard library). 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 interoduced in 3.4. If pypy will implement asyncio in can be ported to pypy.

class ktasync.KyotoTycoon(host='localhost', port=1978, lazy=True, timeout=None, max_connections=5)

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.
  • lazy – If set to True, connection is not immediately established on object creation, instead it is openend automatically when required for the first time. This is the recommended setting, because opening a connection is only necessary if you actually use it.
  • timeout – Optional timeout for the socket. None means no timeout (please also look at the Python socket manual).
close()

Close the socket

static embedded(args=None, timeout=None, max_connections=5, range_from=16384, range_to=32767)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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

Class for Exceptions in this module

Indices and tables