Protocol

Protocol implementation for Tokyo Tyrant.

Let’s assume some defaults for our sandbox:

>>> TEST_HOST = '127.0.0.1'
>>> TEST_PORT = 1983    # default port is 1978

class pyrant.protocol.TyrantProtocol(host, port, timeout=None)

A straightforward implementation of the Tokyo Tyrant protocol. Provides all low level constants and operations. Provides a level of abstraction that is just enough to communicate with server from Python using Tyrant API.

More sophisticated APIs can be built on top of this class. Two of them are included in pyrant: the dict-like API (Pyrant) and the query API (Query).

Let’s connect to a sanbdox Tyrant server:

>>> from pyrant import protocol
>>> p = protocol.TyrantProtocol(host=TEST_HOST, port=TEST_PORT)

# remove anything that could be left from previous time
>>> p.vanish()

# make sure there are zero records in the database
>>> p.rnum()
0

add_index(name, kind=None, keep=False)

Sets index on given column. Returns True if index was successfully created.

Parameters:

• name – column name for which index should be set.
• kind – index type, one of: lexical, decimal, token, q-gram.
• keep – if True, index is only created if it did not yet exist. Default is False, i.e. any existing index is reset.

Note

we have chosen not to mimic the original API here because it is a bit too confusing. Instead of a single cumbersome function Pyrant provides three: add_index(), optimize_index() and drop_index(). They all do what their names suggest.

adddouble(key, num=0.0)

Adds given double to existing one. Stores and returns the sum.

addint(key, num=0)

Adds given integer to existing one. Stores and returns the sum.

copy(path)

Hot-copies the database to given path.

drop_index(name)

Removes index for given column. Returns True if the operation was successfully performed. In most cases the operation fails when the index doesn’t exist. You can add index using add_index().

ext(func, opts, key, value)

Calls func(key, value) with opts.

Parameters:

• opts – a bitflag that can be RDBXOLCKREC for record locking and/or RDBXOLCKGLB for global locking.

fwmkeys(prefix, maxkeys=-1)

Get up to the first maxkeys starting with prefix

genuid()

Generates and returns a unique primary key. Raises ValueError if the database could not return sensible data.

get(key, literal=False)

Returns the value of key as stored on the server:

>>> p.get(u'foo')
u'barbaz'
>>> p.get(u'fox')
u'boxquux'

getdouble(key)

Returns a double for given key. Value must be set by adddouble().

getint(key)

Returns an integer for given key. Value must be set by addint().

iterinit()

Begins iteration over all keys of the database.

>>> p.iterinit()    # now we can call iternext()

iternext()

Returns the next key after iterinit call. Raises an exception which is subclass of TyrantError on iteration end:

>>> p.iternext()  # assume iterinit() was already called
u'foo'
>>> p.iternext()
u'fox'
>>> p.iternext()
Traceback (most recent call last):
    ...
InvalidOperation

mget(keys)

Returns key,value pairs from the server for the given list of keys:

>>> p.mget(['foo', 'fox'])
[('foo', 'barbaz'), ('fox', 'boxquux')]

misc(func, args, opts=0)

Executes custom function.

Parameters:

• func – the function name (see below)
• opts – a bitflag (see below)

Functions supported by all databases:

• putlist stores records. It receives keys and values one after the other, and returns an empty list.
• outlist removes records. It receives keys, and returns an empty list.
• getlist retrieves records. It receives keys, and returns values.

Functions supported by the table database (in addition to mentioned above):

• setindex
• search
• genuid.

Possible options:

• TyrantProtocol.RDBMONOULOG to prevent writing to the update log.

optimize_index(name)

Optimizes index for given column. Returns True if the operation was successfully performed. In most cases the operation fails when the index does not exist. You can add index using add_index().

out(key)

Removes key from server.

put(key, value)

Unconditionally sets key to value:

>>> p.put(u'foo', u'barbaz')
>>> p.rnum()
1
>>> p.put('fox', u'boxquux')
>>> p.rnum()
2

putcat(key, value)

Appends value to the existing value for key, or sets key to value if it does not already exist.

putkeep(key, value)

Sets key to value if key does not already exist.

putnr(key, value)

Sets key to value without waiting for a server response.

putshl(key, value, width)

Equivalent to:

self.putcat(key, value)
self.put(key, self.get(key)[-width:])

restore(path, msec)

Restores the database from path at given timestamp (in msec).

rnum()

Returns the number of records in the database.

search(conditions, limit=10, offset=0, order_type=0, order_column=None, opts=0, ms_conditions=None, ms_type=None, columns=None, out=False, count=False, hint=False)

Returns list of keys for elements matching given conditions.

Parameters:

• conditions – a list of tuples in the form (column, op, expr) where column is name of a column and op is operation code (one of TyrantProtocol.RDBQC[...]). The conditions are implicitly combined with logical AND. See ms_conditions and ms_type for more complex operations.
• limit – integer. Defaults to 10.
• offset – integer. Defaults to 0.
• order_column – string; if defined, results are sorted by this column using default or custom ordering method.
• order_type – one of TyrantProtocol.RDBQO[...]; if defined along with order_column, results are sorted by the latter using given method. Default is RDBQOSTRASC.
• opts – a bitflag (see misc()
• ms_conditions – MetaSearch conditions.
• ms_type – MetaSearch operation type.
• columns – iterable; if not empty, returns only given columns for matched records.
• out – boolean; if True, all items that correspond to the query are deleted from the database when the query is executed.
• count – boolean; if True, the return value is the number of items that correspond to the query.
• hint – boolean; if True, the hint string is added to the return value.

setmst(host, port)

Sets master to host:port.

size()

Returns the size of the database in bytes.

stat()

Returns some statistics about the database.

sync()

Synchronizes the updated contents of the remote database object with the file and the device.

vanish()

Removes all records from the database.

vsiz(key)

Returns the size of a value for given key.