This document is the API reference for Plyvel. It describes all classes, methods, functions, and attributes that are part of the public API.
Most of the terminology in the Plyvel API comes straight from the LevelDB API. See the LevelDB documentation and the LevelDB header files ($prefix/include/leveldb/*.h) for more detailed explanations of all flags and options.
Plyvel exposes the DB class as the main interface to LevelDB. Application code should create a DB and use the appropriate methods on this instance to create write batches, snapshots, and iterators for that LevelDB database.
LevelDB database
Open the underlying database handle.
Most of the arguments have the same name as the the corresponding LevelDB parameters; see the LevelDB documentation for details about the exact meaning. Argument that can be None are only propagated to LevelDB if specified, e.g. not specifying a write_buffer_size means the LevelDB defaults are used.
Most arguments are optional; only the database name is required.
See the descriptions for DB, DB::Open(), Cache, FilterPolicy, and Comparator in the LevelDB C++ API for more information.
Parameters: |
|
---|
Close the database.
This closes the database and releases associated resources such as open file pointers and caches. Any further operations on the closed database will raise a RuntimeError.
Warning
Closing a database while other threads are busy accessing the same database may result in hard crashes, since database operations do not perform any synchronisation/locking on the database object (for performance reasons) and simply assume it is available (and open). Applications should make sure not to close databases that are concurrently used from other threads.
See the description for DB in the LevelDB C++ API for more information. This method deletes the underlying DB handle in the LevelDB C++ API and also frees other related objects.
Boolean attribute indicating whether the database is closed.
Get the value for the specified key, or None if no value was set.
See the description for DB::Get() in the LevelDB C++ API for more information.
Parameters: |
|
---|---|
Returns: | value for the specified key, or None if not found |
Return type: | bytes |
Set a value for the specified key.
See the description for DB::Put() in the LevelDB C++ API for more information.
Parameters: |
|
---|
Delete the key/value pair for the specified key.
See the description for DB::Delete() in the LevelDB C++ API for more information.
Parameters: |
|
---|
Create a new WriteBatch instance for this database.
See the WriteBatch API for more information.
Note that this method does not write a batch to the database; it only creates a new write batch instance.
Parameters: |
|
---|---|
Returns: | new WriteBatch instance |
Return type: |
Create a new Iterator instance for this database.
All arguments are optional, and not all arguments can be used together, because some combinations make no sense. In particular:
Note: due to the whay the prefix support is implemented, this feature only works reliably when the default DB comparator is used.
See the Iterator API for more information about iterators.
Parameters: |
|
---|---|
Returns: | new Iterator instance |
Return type: |
Create a new Snapshot instance for this database.
See the Snapshot API for more information.
Get the specified property from LevelDB.
This returns the property value or None if no value is available. Example property name: b'leveldb.stats'.
See the description for DB::GetProperty() in the LevelDB C++ API for more information.
Parameters: | name (bytes) – name of the property |
---|---|
Returns: | property value or None |
Return type: | bytes |
Compact underlying storage for the specified key range.
See the description for DB::CompactRange() in the LevelDB C++ API for more information.
Parameters: |
|
---|
Return the approximate file system size for the specified range.
See the description for DB::GetApproximateSizes() in the LevelDB C++ API for more information.
Parameters: |
|
---|---|
Returns: | approximate size |
Return type: | int |
Return the approximate file system sizes for the specified ranges.
This method takes a variable number of arguments. Each argument denotes a range as a (start, stop) tuple, where start and stop are both byte strings. Example:
db.approximate_sizes(
(b'a-key', b'other-key'),
(b'some-other-key', b'yet-another-key'))
See the description for DB::GetApproximateSizes() in the LevelDB C++ API for more information.
Parameters: | ranges – variable number of (start, stop) tuples |
---|---|
Returns: | approximate sizes for the specified ranges |
Return type: | list |
Return a new PrefixedDB instance for this database.
See the PrefixedDB API for more information.
Parameters: | prefix (bytes) – prefix to use |
---|---|
Returns: | new PrefixedDB instance |
Return type: | PrefixedDB |
A DB-like object that transparently prefixes all database keys.
Do not instantiate directly; use DB.prefixed_db() instead.
The prefix used by this PrefixedDB.
See DB.delete().
See DB.write_batch().
See DB.iterator().
See DB.snapshot().
Create another PrefixedDB instance with an additional key prefix, which will be appended to the prefix used by this PrefixedDB instance.
See DB.prefixed_db().
Existing databases can be repaired or destroyed using these module level functions:
Repair the specified database.
See DB for a description of the arguments.
See the description for RepairDB() in the LevelDB C++ API for more information.
Destroy the specified database.
Parameters: | name (str) – name of the database (directory name) |
---|
See the description for DestroyDB() in the LevelDB C++ API for more information.
Write batch for batch put/delete operations
Instances of this class can be used as context managers (Python’s with block). When the with block terminates, the write batch will automatically write itself to the database without an explicit call to WriteBatch.write():
with db.write_batch() as b:
b.put(b'key', b'value')
The transaction argument to DB.write_batch() specifies whether the batch should be written after an exception occurred in the with block. By default, the batch is written (this is like a try statement with a finally clause), but if transaction mode is enabled`, the batch will be discarded (this is like a try statement with an else clause).
Note: methods on a WriteBatch do not take a sync argument; this flag can be specified for the complete write batch when it is created using DB.write_batch().
Do not instantiate directly; use DB.write_batch() instead.
See the descriptions for WriteBatch and DB::Write() in the LevelDB C++ API for more information.
Set a value for the specified key.
This is like DB.put(), but operates on the write batch instead.
Delete the key/value pair for the specified key.
This is like DB.delete(), but operates on the write batch instead.
Clear the batch.
This discards all updates buffered in this write batch.
Write the batch to the associated database. If you use the write batch as a context manager (in a with block), this method will be invoked automatically.
Database snapshot
A snapshot provides a consistent view over keys and values. After making a snapshot, puts and deletes on the database will not be visible by the snapshot.
Do not keep unnecessary references to instances of this class around longer than needed, because LevelDB will not release the resources required for this snapshot until a snapshot is released.
Do not instantiate directly; use DB.snapshot() instead.
See the descriptions for DB::GetSnapshot() and DB::ReleaseSnapshot() in the LevelDB C++ API for more information.
Get the value for the specified key, or None if no value was set.
Same as DB.get(), but operates on the snapshot instead.
Create a new Iterator instance for this snapshot.
Same as DB.iterator(), but operates on the snapshot instead.
Plyvel’s Iterator is intended to be used like a normal Python iterator, so you can just use a standard for loop to iterate over it. Directly invoking methods on the Iterator returned by DB.iterator() method is only required for additional functionality.
Iterator to iterate over (ranges of) a database
The next item in the iterator can be obtained using the next() built-in or by looping over the iterator using a for loop.
Do not instantiate directly; use DB.iterator() or Snapshot.iterator() instead.
See the descriptions for DB::NewIterator() and Iterator in the LevelDB C++ API for more information.
Move one step back and return the previous entry.
This returns the same value as the most recent next() call (if any).
Move the iterator to the start key (or the begin).
This “rewinds” the iterator, so that it is in the same state as when first created. This means calling next() afterwards will return the first entry.
Move the iterator to the stop key (or the end).
This “fast-forwards” the iterator past the end. After this call the iterator is exhausted, which means a call to next() raises StopIteration, but prev() will work.
Move the iterator to the specified target.
This moves the iterator to the the first key that sorts equal or before the specified target within the iterator range (start and stop).
Plyvel uses standard exceptions like TypeError and ValueError as much as possible. For LevelDB specific errors, Plyvel may raise a few custom exceptions: Error, IOError, and CorruptionError.
Generic LevelDB error
This class is also the “parent” error for other LevelDB errors (IOError and CorruptionError). Other exceptions from this module extend from this class.
LevelDB IO error
This class extends both the main LevelDB Error class from this module and Python’s built-in IOError.
LevelDB corruption error