A storage/query backend for Tokyo Cabinet.
Allows direct access to the database and is thus extremely fast. However, it locks the database and is therefore not suitable for environments where concurrent access is required. Please use Tokyo Tyrant for such environments.
status: | beta |
---|---|
database: | Tokyo Cabinet |
dependencies: | tokyo-python, pyrant |
suitable for: | general purpose, embedded |
Warning
this module is not intended for production despite it may be stable. Bug reports and patches are welcome.
Note
this module should not depend on Pyrant; just needs some refactoring.
Note
support for metasearch is planned.
Usage:
>>> import os
>>> import doqu
>>> DB_SETTINGS = {
... 'backend': 'doqu.ext.tokyo_cabinet',
... 'path': '_tc_test.tct',
... }
>>> assert not os.path.exists(DB_SETTINGS['path']), 'test database must not exist'
>>> db = doqu.get_db(DB_SETTINGS)
>>> class Person(doqu.Document):
... structure = {'name': unicode}
... def __unicode__(self):
... u'%(name)s' % self
...
>>> Person.objects(db) # the database is expected to be empty
[]
>>> db.connection['john'] = {'name': 'John'}
>>> mary = Person(name='Mary')
>>> mary_pk = mary.save(db)
>>> q = Person.objects(db)
>>> q
[<Person John>, <Person Mary>]
>>> q.where(name__matches='^J')
[<Person John>]
>>> q # the original query was not modified by the descendant
[<Person John>, <Person Mary>]
>>> db.connection.close()
>>> os.unlink(DB_SETTINGS['path'])
Parameters: | path – relative or absolute path to the database file (e.g. test.tct) |
---|
Note
Currently only table flavour of Tokyo Cabinet databases is supported. It is uncertain whether it is worth supporting other flavours as they do not provide query mechanisms other than access by primary key.
Clears the whole storage from data, resets autoincrement counters.
Connects to the database. Raises RuntimeError if the connection is not closed yet. Use reconnect() to explicitly close the connection and open it again.
Deletes record with given primary key.
Closes internal store and removes the reference to it. If the backend works with a file, then all pending changes are saved now.
Returns instances of given class, optionally filtered by given conditions.
Parameters: |
|
---|
Note
By default this returns a tuple of (key, data_dict) per item. However, this can be changed if doc_class provides the method from_storage(). For example, Document has the notion of “saved state” so it can store the key within. Thus, only a single Document object is returned per item.
Returns document instance for given document class and primary key. Raises KeyError if there is no item with given key in the database.
Parameters: |
|
---|
Returns an iterator of documents with primary keys from given list. Basically this is just a simple wrapper around get() but some backends can reimplement the method in a much more efficient way.
Queries the database for records associated with given document class and conforming to given extra conditions. If such records exist, picks the first one (the order may be random depending on the database). If there are no such records, creates one.
Returns the document instance and a boolean value “created”.
alias of QueryAdapter
Gracefully closes current connection (if it’s not broken) and connects again to the database (e.g. reopens the file).
Saves given data with given primary key into the storage. Returns the primary key.
Parameters: |
|
---|
Note that you must provide current primary key for a record which is already in the database in order to update it instead of copying it.
Synchronizes the storage to disk immediately if the backend supports this operation. Normally the data is synchronized either on save(), or on timeout, or on disconnect(). This is strictly backend-specific. If a backend does not support the operation, NotImplementedError is raised.
The Query class.
Same as __len__ but without fetching the records (i.e. faster).
Deletes all records that match current query.
Returns a query object with same conditions but with results sorted by given field. By default the direction of sorting is ascending.
Parameters: |
|
---|
Returns an iterator that yields distinct values for given column name.
Note
this is currently highly inefficient because the underlying library does not support columns mode (tctdbiternext3). Moreover, even current implementation can be optimized by removing the overhead of creating full-blown document objects (though preserving data type is necessary).
Returns Query instance filtered by given conditions. The conditions are specified by backend’s underlying API.
Returns Query instance. Inverted version of where().