Home       Trees       Indices       Help   
kyotocabinet
Module kyotocabinet :: Class DB
[frames] | no frames]

Class DB

Interface of database abstraction.

Instance Methods
 
__init__(self, opts=0)
Create a database object.
 
error(self)
Get the last happened error.
 
open(self, path=':', mode=6)
Open a database file.
 
close(self)
Close the database file.
 
accept(self, key, visitor, writable=True)
Accept a visitor to a record.
 
accept_bulk(self, keys, visitor, writable=True)
Accept a visitor to multiple records at once.
 
iterate(self, visitor, writable=True)
Iterate to accept a visitor for each record.
 
set(self, key, value)
Set the value of a record.
 
add(self, key, value)
Add a record.
 
replace(self, key, value)
Replace the value of a record.
 
append(self, key, value)
Append the value of a record.
 
increment(self, key, num=0, orig=0)
Add a number to the numeric integer value of a record.
 
increment_double(self, key, num=0.0, orig=0.0)
Add a number to the numeric double value of a record.
 
cas(self, key, oval, nval)
Perform compare-and-swap.
 
remove(self, key)
Remove a record.
 
get(self, key)
Retrieve the value of a record.
 
get_str(self, key)
Retrieve the value of a record.
 
check(self, key)
Check the existence of a record.
 
seize(self, key)
Retrieve the value of a record and remove it atomically.
 
seize_str(self, key)
Retrieve the value of a record and remove it atomically.
 
set_bulk(self, recs, atomic=True)
Store records at once.
 
remove_bulk(self, keys, atomic=True)
Remove records at once.
 
get_bulk(self, keys, atomic=True)
Retrieve records at once.
 
get_bulk_str(self, keys, atomic=True)
Retrieve records at once.
 
clear(self)
Remove all records.
 
synchronize(self, hard=False, proc=None)
Synchronize updated contents with the file and the device.
 
occupy(self, writable=False, proc=None)
Occupy database by locking and do something meanwhile.
 
copy(self, dest)
Create a copy of the database file.
 
begin_transaction(self, hard=False)
Begin transaction.
 
end_transaction(self, commit=True)
End transaction.
 
transaction(self, proc, hard=False)
Perform entire transaction by a functor.
 
dump_snapshot(self, dest)
Dump records into a snapshot file.
 
load_snapshot(self, src)
Load records from a snapshot file.
 
count(self)
Get the number of records.
 
size(self)
Get the size of the database file.
 
path(self)
Get the path of the database file.
 
status(self)
Get the miscellaneous status information.
 
match_prefix(self, prefix, max=-1)
Get keys matching a prefix string.
 
match_regex(self, regex, max=-1)
Get keys matching a regular expression string.
 
match_similar(self, origin, range=1, utf=False, max=-1)
Get keys similar to a string in terms of the levenshtein distance.
 
merge(self, srcary, mode=0)
Merge records from other databases.
 
cursor(self)
Create a cursor object.
 
cursor_process(self, proc)
Process a cursor by a functor.
 
shift(self)
Remove the first record.
 
shift_str(self)
Remove the first record.
 
tune_exception_rule(self, codes)
Set the rule about throwing exception.
 
__repr__(self)
Get the representing expression.
 
__str__(self)
Get the string expression.
 
__len__(self)
Alias of the count method.
 
__getitem__(self, key, value)
Alias of the get method.
 
__setitem__(self, key, value)
Alias of the set method.
 
__iter__(self)
Alias of the cursor method.
 
process(proc, path='*', mode=6, opts=0)
Process a database by a functor.
Class Variables
  GEXCEPTIONAL = 1
generic mode: exceptional mode.
  GCONCURRENT = 2
generic mode: concurrent mode.
  OREADER = 1
open mode: open as a reader.
  OWRITER = 2
open mode: open as a writer.
  OCREATE = 4
open mode: writer creating.
  OTRUNCATE = 8
open mode: writer truncating.
  OAUTOTRAN = 16
open mode: auto transaction.
  OAUTOSYNC = 32
open mode: auto synchronization.
  ONOLOCK = 64
open mode: open without locking.
  OTRYLOCK = 128
open mode: lock without blocking.
  ONOREPAIR = 256
open mode: open without auto repair.
  MSET = 0
merge mode: overwrite the existing value.
  MADD = 1
merge mode: keep the existing value.
  MREPLACE = 2
merge mode: modify the existing record only.
  MAPPEND = 3
merge mode: append the new value.
Method Details

__init__(self, opts=0)
(Constructor)

 

Create a database object.

Parameters:
  • opts - the optional features by bitwise-or: DB.GEXCEPTIONAL for the exceptional mode, DB.GCONCURRENT for the concurrent mode.
Returns:
the database object.

Note: The exceptional mode means that fatal errors caused by methods are reported by exceptions raised. The concurrent mode means that database operations by multiple threads are performed concurrently without the giant VM lock. However, it has a side effect that such methods with call back of Python code as DB#accept, DB#accept_bulk, DB#iterate, and Cursor#accept are disabled.

error(self)

 

Get the last happened error.

Returns:
the last happened error.

open(self, path=':', mode=6)

 

Open a database file.

Parameters:
  • path - the path of a database file. If it is "-", the database will be a prototype hash database. If it is "+", the database will be a prototype tree database. If it is ":", the database will be a stash database. If it is "*", the database will be a cache hash database. If it is "%", the database will be a cache tree database. If its suffix is ".kch", the database will be a file hash database. If its suffix is ".kct", the database will be a file tree database. If its suffix is ".kcd", the database will be a directory hash database. If its suffix is ".kcf", the database will be a directory tree database. If its suffix is ".kcx", the database will be a plain text database. Otherwise, this function fails. Tuning parameters can trail the name, separated by "#". Each parameter is composed of the name and the value, separated by "=". If the "type" parameter is specified, the database type is determined by the value in "-", "+", ":", "*", "%", "kch", "kct", "kcd", kcf", and "kcx". All database types support the logging parameters of "log", "logkinds", and "logpx". The prototype hash database and the prototype tree database do not support any other tuning parameter. The stash database supports "bnum". The cache hash database supports "opts", "bnum", "zcomp", "capcnt", "capsiz", and "zkey". The cache tree database supports all parameters of the cache hash database except for capacity limitation, and supports "psiz", "rcomp", "pccap" in addition. The file hash database supports "apow", "fpow", "opts", "bnum", "msiz", "dfunit", "zcomp", and "zkey". The file tree database supports all parameters of the file hash database and "psiz", "rcomp", "pccap" in addition. The directory hash database supports "opts", "zcomp", and "zkey". The directory tree database supports all parameters of the directory hash database and "psiz", "rcomp", "pccap" in addition. The plain text database does not support any other tuning parameter.
  • mode - the connection mode. DB.OWRITER as a writer, DB.OREADER as a reader. The following may be added to the writer mode by bitwise-or: DB.OCREATE, which means it creates a new database if the file does not exist, DB.OTRUNCATE, which means it creates a new database regardless if the file exists, DB.OAUTOTRAN, which means each updating operation is performed in implicit transaction, DB.OAUTOSYNC, which means each updating operation is followed by implicit synchronization with the file system. The following may be added to both of the reader mode and the writer mode by bitwise-or: DB.ONOLOCK, which means it opens the database file without file locking, DB.OTRYLOCK, which means locking is performed without blocking, DB.ONOREPAIR, which means the database file is not repaired implicitly even if file destruction is detected.
Returns:
true on success, or false on failure.

Note: The tuning parameter "log" is for the original "tune_logger" and the value specifies the path of the log file, or "-" for the standard output, or "+" for the standard error. "logkinds" specifies kinds of logged messages and the value can be "debug", "info", "warn", or "error". "logpx" specifies the prefix of each log message. "opts" is for "tune_options" and the value can contain "s" for the small option, "l" for the linear option, and "c" for the compress option. "bnum" corresponds to "tune_bucket". "zcomp" is for "tune_compressor" and the value can be "zlib" for the ZLIB raw compressor, "def" for the ZLIB deflate compressor, "gz" for the ZLIB gzip compressor, "lzo" for the LZO compressor, "lzma" for the LZMA compressor, or "arc" for the Arcfour cipher. "zkey" specifies the cipher key of the compressor. "capcnt" is for "cap_count". "capsiz" is for "cap_size". "psiz" is for "tune_page". "rcomp" is for "tune_comparator" and the value can be "lex" for the lexical comparator, "dec" for the decimal comparator, "lexdesc" for the lexical descending comparator, or "decdesc" for the decimal descending comparator. "pccap" is for "tune_page_cache". "apow" is for "tune_alignment". "fpow" is for "tune_fbp". "msiz" is for "tune_map". "dfunit" is for "tune_defrag". Every opened database must be closed by the PolyDB::close method when it is no longer in use. It is not allowed for two or more database objects in the same process to keep their connections to the same database file at the same time.

close(self)

 

Close the database file.

Returns:
true on success, or false on failure.

accept(self, key, visitor, writable=True)

 

Accept a visitor to a record.

Parameters:
  • key - the key.
  • visitor - a visitor object which implements the Visitor interface, or a function object which receives the key and the value.
  • writable - true for writable operation, or false for read-only operation.
Returns:
true on success, or false on failure.

Note: The operation for each record is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

accept_bulk(self, keys, visitor, writable=True)

 

Accept a visitor to multiple records at once.

Parameters:
  • keys - specifies a sequence object of the keys.
  • visitor - a visitor object which implements the Visitor interface, or a function object which receives the key and the value.
  • writable - true for writable operation, or false for read-only operation.
Returns:
true on success, or false on failure.

Note: The operations for specified records are performed atomically and other threads accessing the same records are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

iterate(self, visitor, writable=True)

 

Iterate to accept a visitor for each record.

Parameters:
  • visitor - a visitor object which implements the Visitor interface, or a function object which receives the key and the value.
  • writable - true for writable operation, or false for read-only operation.
Returns:
true on success, or false on failure.

Note: The whole iteration is performed atomically and other threads are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

set(self, key, value)

 

Set the value of a record.

Parameters:
  • key - the key.
  • value - the value.
Returns:
true on success, or false on failure.

Note: If no record corresponds to the key, a new record is created. If the corresponding record exists, the value is overwritten.

add(self, key, value)

 

Add a record.

Parameters:
  • key - the key.
  • value - the value.
Returns:
true on success, or false on failure.

Note: If no record corresponds to the key, a new record is created. If the corresponding record exists, the record is not modified and false is returned.

replace(self, key, value)

 

Replace the value of a record.

Parameters:
  • key - the key.
  • value - the value.
Returns:
true on success, or false on failure.

Note: If no record corresponds to the key, no new record is created and false is returned. If the corresponding record exists, the value is modified.

append(self, key, value)

 

Append the value of a record.

Parameters:
  • key - the key.
  • value - the value.
Returns:
true on success, or false on failure.

Note: If no record corresponds to the key, a new record is created. If the corresponding record exists, the given value is appended at the end of the existing value.

increment(self, key, num=0, orig=0)

 

Add a number to the numeric integer value of a record.

Parameters:
  • key - the key.
  • num - the additional number.
  • orig - the origin number if no record corresponds to the key. If it is negative infinity and no record corresponds, this method fails. If it is positive infinity, the value is set as the additional number regardless of the current value.
Returns:
the result value, or None on failure.

Note: The value is serialized as an 8-byte binary integer in big-endian order, not a decimal string. If existing value is not 8-byte, this method fails.

increment_double(self, key, num=0.0, orig=0.0)

 

Add a number to the numeric double value of a record.

Parameters:
  • key - the key.
  • num - the additional number.
  • orig - the origin number if no record corresponds to the key. If it is negative infinity and no record corresponds, this method fails. If it is positive infinity, the value is set as the additional number regardless of the current value.
Returns:
the result value, or None on failure.

Note: The value is serialized as an 16-byte binary fixed-point number in big-endian order, not a decimal string. If existing value is not 16-byte, this method fails.

cas(self, key, oval, nval)

 

Perform compare-and-swap.

Parameters:
  • key - the key.
  • oval - the old value. None means that no record corresponds.
  • nval - the new value. None means that the record is removed.
Returns:
true on success, or false on failure.

remove(self, key)

 

Remove a record.

Parameters:
  • key - the key.
Returns:
true on success, or false on failure.

Note: If no record corresponds to the key, false is returned.

get(self, key)

 

Retrieve the value of a record.

Parameters:
  • key - the key.
Returns:
the value of the corresponding record, or None on failure.

get_str(self, key)

 

Retrieve the value of a record.

Note: Equal to the original DB::get method except that the return value is string.

check(self, key)

 

Check the existence of a record.

Parameters:
  • key - the key.
Returns:
the size of the value, or -1 on failure.

seize(self, key)

 

Retrieve the value of a record and remove it atomically.

Parameters:
  • key - the key.
Returns:
the value of the corresponding record, or None on failure.

seize_str(self, key)

 

Retrieve the value of a record and remove it atomically.

Note: Equal to the original DB::seize method except that the return value is string.

set_bulk(self, recs, atomic=True)

 

Store records at once.

Parameters:
  • recs - a map object of the records to store.
  • atomic - true to perform all operations atomically, or false for non-atomic operations.
Returns:
the number of stored records, or -1 on failure.

remove_bulk(self, keys, atomic=True)

 

Remove records at once.

Parameters:
  • keys - a sequence object of the keys of the records to remove.
  • atomic - true to perform all operations atomically, or false for non-atomic operations.
Returns:
the number of removed records, or -1 on failure.

get_bulk(self, keys, atomic=True)

 

Retrieve records at once.

Parameters:
  • keys - a sequence object of the keys of the records to retrieve.
  • atomic - true to perform all operations atomically, or false for non-atomic operations.
Returns:
a map object of retrieved records, or None on failure.

get_bulk_str(self, keys, atomic=True)

 

Retrieve records at once.

Note: Equal to the original DB::get_bulk method except that the return value is string map.

clear(self)

 

Remove all records.

Returns:
true on success, or false on failure.

synchronize(self, hard=False, proc=None)

 

Synchronize updated contents with the file and the device.

Parameters:
  • hard - true for physical synchronization with the device, or false for logical synchronization with the file system.
  • proc - a postprocessor object which implements the FileProcessor interface, or a function object which receives the same parameters. If it is None, no postprocessing is performed.
Returns:
true on success, or false on failure.

Note: The operation of the processor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

occupy(self, writable=False, proc=None)

 

Occupy database by locking and do something meanwhile.

Parameters:
  • writable - true to use writer lock, or false to use reader lock.
  • proc - a processor object which implements the FileProcessor interface, or a function object which receives the same parameters. If it is None, no processing is performed.
Returns:
true on success, or false on failure.

Note: The operation of the processor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

copy(self, dest)

 

Create a copy of the database file.

Parameters:
  • dest - the path of the destination file.
Returns:
true on success, or false on failure.

begin_transaction(self, hard=False)

 

Begin transaction.

Parameters:
  • hard - true for physical synchronization with the device, or false for logical synchronization with the file system.
Returns:
true on success, or false on failure.

end_transaction(self, commit=True)

 

End transaction.

Parameters:
  • commit - true to commit the transaction, or false to abort the transaction.
Returns:
true on success, or false on failure.

transaction(self, proc, hard=False)

 

Perform entire transaction by a functor.

Parameters:
  • proc - the functor of operations during transaction. If the function returns true, the transaction is committed. If the function returns false or an exception is thrown, the transaction is aborted.
  • hard - true for physical synchronization with the device, or false for logical synchronization with the file system.
Returns:
true on success, or false on failure.

dump_snapshot(self, dest)

 

Dump records into a snapshot file.

Parameters:
  • dest - the name of the destination file.
Returns:
true on success, or false on failure.

load_snapshot(self, src)

 

Load records from a snapshot file.

Parameters:
  • src - the name of the source file.
Returns:
true on success, or false on failure.

count(self)

 

Get the number of records.

Returns:
the number of records, or -1 on failure.

size(self)

 

Get the size of the database file.

Returns:
the size of the database file in bytes, or -1 on failure.

path(self)

 

Get the path of the database file.

Returns:
the path of the database file, or None on failure.

status(self)

 

Get the miscellaneous status information.

Returns:
a dictionary object of the status information, or None on failure.

match_prefix(self, prefix, max=-1)

 

Get keys matching a prefix string.

Parameters:
  • prefix - the prefix string.
  • max - the maximum number to retrieve. If it is negative, no limit is specified.
Returns:
a list object of matching keys, or None on failure.

match_regex(self, regex, max=-1)

 

Get keys matching a regular expression string.

Parameters:
  • regex - the regular expression string.
  • max - the maximum number to retrieve. If it is negative, no limit is specified.
Returns:
a list object of matching keys, or None on failure.

match_similar(self, origin, range=1, utf=False, max=-1)

 

Get keys similar to a string in terms of the levenshtein distance.

Parameters:
  • origin - the origin string.
  • range - the maximum distance of keys to adopt.
  • utf - flag to treat keys as UTF-8 strings.
  • max - the maximum number to retrieve. If it is negative, no limit is specified.
Returns:
a list object of matching keys, or None on failure.

merge(self, srcary, mode=0)

 

Merge records from other databases.

Parameters:
  • srcary - an array of the source detabase objects.
  • mode - the merge mode. DB.MSET to overwrite the existing value, DB.MADD to keep the existing value, DB.MAPPEND to append the new value.
Returns:
true on success, or false on failure.

cursor(self)

 

Create a cursor object.

Returns:
the return value is the created cursor object. Each cursor should be disabled with the Cursor#disable method when it is no longer in use.

cursor_process(self, proc)

 

Process a cursor by a functor.

Parameters:
  • proc - the functor of operations for the cursor. The cursor is disabled implicitly after the block.
Returns:
always None.

shift(self)

 

Remove the first record.

Returns:
a pair of the key and the value of the removed record, or None on failure.

shift_str(self)

 

Remove the first record.

Note: Equal to the original DB::shift method except that the return value is string.

tune_exception_rule(self, codes)

 

Set the rule about throwing exception.

Parameters:
  • codes - a sequence of error codes. If each method occurs an error corresponding to one of the specified codes, the error is thrown as an exception.
Returns:
true on success, or false on failure.

__repr__(self)
(Representation operator)

 

Get the representing expression.

Returns:
the representing expression.

__str__(self)
(Informal representation operator)

 

Get the string expression.

Returns:
the string expression.

process(proc, path='*', mode=6, opts=0)

 

Process a database by a functor. (static method)

Parameters:
  • proc - the functor to process the database, whose object is passd as the parameter.
  • path - the same to the one of the open method.
  • mode - the same to the one of the open method.
  • opts - the optional features by bitwise-or: DB.GCONCURRENT for the concurrent mode.
Returns:
None on success, or an error object on failure.

   Home       Trees       Indices       Help   
kyotocabinet
Generated by Epydoc 3.0.1 on Fri May 25 01:00:16 2012 http://epydoc.sourceforge.net