Table of Contents

Please enable javascript to display TOC.

Python Library for accessing Kyoto Tycoon via Binary Protocol

published: 22 Jan 2013

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 CPython (2.6.6) and PyPy (2.0.0-beta1/Python 2.7.3) on a 64bit machine. It should also be easy to make the code compatible with Py3k.

Download the Library

If you use this library, a link back to this website would be appreciated but is not required.

Python library to access Kyoto Tycoon (Version 0.1.0) (3.7 kB)

Documentation

The library consists of a single class named KyotoTycoon. Exceptions thrown by its member functions are of type KyotoTycoonError.

New connections are created using the constructor. A connection is automatically closed when the object is destroyed.

Keys and values of database entries are python (byte-)strings. Unicode strings are not supported. You could, however, encode unicode strings as UTF-8 (or any other encoding) before storing them in the database. Other objects should be encoded vis JSON, Protocol Buffers or similar methods. Please be careful when using Python's built-in pickling module as you will lose compatibility with other languages.

KyotoTycoon

class kyototycoon.KyotoTycoon(host=DEFAULT_HOST, port=DEFAULT_PORT, lazy=True, timeout=None)

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

set_bulk

Stores multiple records at once.

set_bulk(recs, flags=0)

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.

Return Values

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

set_bulk_kv

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

set_bulk_kv(kv, db, expire=DEFAULT_EXPIRE, flags=0)

Parameters

kv

dict of key/value pairs.

db

Database index to store the records in.

expire

Expiration time for all entries. kyototycoon.DEFAULT_EXPIRE is 0xffffffffff 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.

Return Values

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

set

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

set(key, val, db, expire=DEFAULT_EXPIRE, flags=0)

Parameters

key

The key of the entry.

val

The value of the entry.

db

Database index to store the record in.

expire

Expiration time for the entry. kyototycoon.DEFAULT_EXPIRE is 0xffffffffff which means that the record should never expire in the near future.

flags

If set to kyototycoon.FLAG_NOREPLY, function will not wait for an answer of the server.

Return Values

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

get_bulk

Retrieves multiple records at once.

get_bulk(recs, flags=0)

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.

Return Values

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

get_bulk_keys

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

get_bulk_keys(keys, db, flags=0)

Parameters

keys

iterable (e.g. list) of keys.

db

Database index.

flags

Reserved and not used now.

Return Values

dict of key/value pairs.

get

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

get(key, db, flags=0)

Parameters

key

The key of the entry.

db

Database index.

flags

Reserved and not used now.

Return Values

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

remove_bulk

Remove multiple records at once.

remove_bulk(recs, flags=0)

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.

Return Values

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

remove_bulk_keys

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

remove_bulk_keys(keys, db, flags=0)

Parameters

keys

iterable (e.g. list) of keys.

db

Database index.

flags

If set to kyototycoon.FLAG_NOREPLY, function will not wait for an answer of the server.

Return Values

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

remove

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

remove(key, db, flags=0)

Parameters

key

The key of the entry.

db

Database index.

flags

If set to kyototycoon.FLAG_NOREPLY, function will not wait for an answer of the server.

Return Values

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

play_script

Calls a procedure of the LUA scripting language extension.

play_script(name, recs, flags=0)

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.

Return Values

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

Example

Here is a simple example.

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import kyototycoon

kt = kyototycoon.KyotoTycoon()
print 'testkey =', kt.get('testkey', 0)
print 'setting testkey=testvalue...', kt.set('testkey', 'testvalue', 0)
print 'testkey =', kt.get('testkey', 0)
print 'removing testkey...', kt.remove('testkey', 0)
print 'testkey =', kt.get('testkey', 0)

The output should be:

testkey = None
setting testkey=testvalue... 1
testkey = testvalue
removing testkey... 1
testkey = None

Questions? Comments?

If you have questions regarding this library or suggestions for improvements, do not hesitate to contact me.