This is a simple bit of documentation for the bsddb3.db Python extension module which wraps the Berkeley DB 4.x C library. The extension module is located in a Python package along with a few pure python modules.
It is expected that this module will be used in the following general ways by different programmers in different situations. The goals of this module are to allow all of these methods without making things too complex for the simple cases, and without leaving out funtionality needed by the complex cases.
The bsddb3.db extension module provides the following object types:
The Berkeley DB C API uses function return codes to signal various errors. The bsddb3.db module checks for these error codes and turns them into Python exceptions, allowing you to use familiar try:... except:... constructs and not have to bother with checking every method’s return value.
Each of the error codes is turned into an exception specific to that error code, as outlined in the table below. If you are using the C API documentation then it is very easy to map the error return codes specified there to the name of the Python exception that will be raised. Simply refer to the table below.
Each exception derives from the DBError exception class so if you just want to catch generic errors you can use DBError to do it. Since DBNotFoundError is raised when a given key is not found in the database, DBNotFoundError also derives from the standard KeyError exception to help make a DB look and act like a dictionary. We do the same trick with DBKeyEmptyError.
When any of these exceptions is raised, the associated value is a tuple containing an integer representing the error code and a string for the error message itself.
DBError Base class, all others derive from this DBCursorClosedError When trying to use a closed cursor DBForeignConflictError DB_FOREIGN_CONFLICT DBKeyEmptyError DB_KEYEMPTY (also derives from KeyError) DBKeyExistError DB_KEYEXIST DBLockDeadlockError DB_LOCK_DEADLOCK DBLockNotGrantedError DB_LOCK_NOTGRANTED DBNotFoundError DB_NOTFOUND (also derives from KeyError) DBOldVersionError DB_OLD_VERSION DBPageNotFoundError DB_PAGE_NOTFOUND DBRepHandleDeadError DB_REP_HANDLE_DEAD DBRepLeaseExpiredError DB_REP_LEASE_EXPIRED DBRepLockoutError DB_REP_LOCKOUT DBRepUnavailError DB_REP_UNAVAIL DBRunRecoveryError DB_RUNRECOVERY DBSecondaryBadError DB_SECONDARY_BAD DBVerifyBadError DB_VERIFY_BAD DBNoServerError DB_NOSERVER DBNoServerHomeError DB_NOSERVER_HOME DBNoServerIDError DB_NOSERVER_ID DBInvalidArgError EINVAL DBAccessError EACCES DBNoSpaceError ENOSPC DBNoMemoryError DB_BUFFER_SMALL DBAgainError EAGAIN DBBusyError EBUSY DBFileExistsError EEXIST DBNoSuchFileError ENOENT DBPermissionsError EPERM
A full unit test suite is being developed to exercise the various object types, their methods and the various usage modes described in the introduction. PyUnit is used and the tests are structured such that they can be run unattended and automated. There are currently 482 test cases! (March 2010)
See the C language API online documentation on Oracle’s website for more details of the functionality of each of these methods. The names of all the Python methods should be the same or similar to the names in the C API.
NOTE: All the methods shown below having more than one keyword argument are actually implemented using keyword argument parsing, so you can use keywords to provide optional parameters as desired. Those that have only a single optional argument are implemented without keyword parsing to help keep the implementation simple. If this is too confusing let me know and I’ll think about using keywords for everything.