| :mod:`dbm` --- Interfaces to Unix "databases" |
| ============================================= |
| |
| .. module:: dbm |
| :synopsis: Interfaces to various Unix "database" formats. |
| |
| :mod:`dbm` is a generic interface to variants of the DBM database --- |
| :mod:`dbm.bsd` (requires :mod:`bsddb`), :mod:`dbm.gnu`, or :mod:`dbm.ndbm`. If |
| none of these modules is installed, the slow-but-simple implementation in module |
| :mod:`dbm.dumb` will be used. |
| |
| |
| .. exception:: error |
| |
| A tuple containing the exceptions that can be raised by each of the supported |
| modules, with a unique exception also named :exc:`dbm.error` as the first |
| item --- the latter is used when :exc:`dbm.error` is raised. |
| |
| |
| .. function:: whichdb(filename) |
| |
| This functionattempts to guess which of the several simple database modules |
| available --- :mod:`dbm.bsd`, :mod:`dbm.gnu`, :mod:`dbm.ndbm` or |
| :mod:`dbm.dumb` --- should be used to open a given file. |
| |
| Returns one of the following values: ``None`` if the file can't be opened |
| because it's unreadable or doesn't exist; the empty string (``''``) if the |
| file's format can't be guessed; or a string containing the required module |
| name, such as ``'dbm.ndbm'`` or ``'dbm.gnu'``. |
| |
| |
| .. function:: open(filename[, flag[, mode]]) |
| |
| Open the database file *filename* and return a corresponding object. |
| |
| If the database file already exists, the :func:`whichdb` function is used to |
| determine its type and the appropriate module is used; if it does not exist, |
| the first module listed above that can be imported is used. |
| |
| The optional *flag* argument can be ``'r'`` to open an existing database for |
| reading only, ``'w'`` to open an existing database for reading and writing, |
| ``'c'`` to create the database if it doesn't exist, or ``'n'``, which will |
| always create a new empty database. If not specified, the default value is |
| ``'r'``. |
| |
| The optional *mode* argument is the Unix mode of the file, used only when the |
| database has to be created. It defaults to octal ``0o666`` (and will be |
| modified by the prevailing umask). |
| |
| |
| The object returned by :func:`open` supports most of the same functionality as |
| dictionaries; keys and their corresponding values can be stored, retrieved, and |
| deleted, and the :keyword:`in` operator and the :meth:`keys` method are |
| available. Keys and values must always be strings. |
| |
| The following example records some hostnames and a corresponding title, and |
| then prints out the contents of the database:: |
| |
| import dbm |
| |
| # Open database, creating it if necessary. |
| db = dbm.open('cache', 'c') |
| |
| # Record some values |
| db['www.python.org'] = 'Python Website' |
| db['www.cnn.com'] = 'Cable News Network' |
| |
| # Loop through contents. Other dictionary methods |
| # such as .keys(), .values() also work. |
| for k, v in db.iteritems(): |
| print(k, '\t', v) |
| |
| # Storing a non-string key or value will raise an exception (most |
| # likely a TypeError). |
| db['www.yahoo.com'] = 4 |
| |
| # Close when done. |
| db.close() |
| |
| |
| .. seealso:: |
| |
| Module :mod:`shelve` |
| Persistence module which stores non-string data. |
| |
| |
| The individual submodules are described in the following sections. |
| |
| |
| :mod:`dbm.bsd` --- DBM-style interface to the BSD database library |
| ------------------------------------------------------------------ |
| |
| .. module:: dbm.bsd |
| :synopsis: DBM-style interface to the BSD database library. |
| .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| |
| .. index:: module: bsddb |
| |
| The :mod:`dbm.bsd` module provides a function to open databases using the BSD |
| ``db`` library. This module mirrors the interface of the other Python database |
| modules that provide access to DBM-style databases. The :mod:`bsddb` module is |
| required to use :mod:`dbm.bsd`. |
| |
| .. exception:: error |
| |
| Exception raised on database errors other than :exc:`KeyError`. It is a synonym |
| for :exc:`bsddb.error`. |
| |
| |
| .. function:: open(path[, flag[, mode]]) |
| |
| Open a ``db`` database and return the database object. The *path* argument is |
| the name of the database file. |
| |
| The *flag* argument can be: |
| |
| +---------+-------------------------------------------+ |
| | Value | Meaning | |
| +=========+===========================================+ |
| | ``'r'`` | Open existing database for reading only | |
| | | (default) | |
| +---------+-------------------------------------------+ |
| | ``'w'`` | Open existing database for reading and | |
| | | writing | |
| +---------+-------------------------------------------+ |
| | ``'c'`` | Open database for reading and writing, | |
| | | creating it if it doesn't exist | |
| +---------+-------------------------------------------+ |
| | ``'n'`` | Always create a new, empty database, open | |
| | | for reading and writing | |
| +---------+-------------------------------------------+ |
| |
| For platforms on which the BSD ``db`` library supports locking, an ``'l'`` |
| can be appended to indicate that locking should be used. |
| |
| The optional *mode* parameter is used to indicate the Unix permission bits that |
| should be set if a new database must be created; this will be masked by the |
| current umask value for the process. |
| |
| The database objects returned by :func:`open` provide the methods common to all |
| the DBM-style databases and mapping objects. The following methods are |
| available in addition to the standard methods: |
| |
| .. method:: dbhash.first() |
| |
| It's possible to loop over every key/value pair in the database using this |
| method and the :meth:`next` method. The traversal is ordered by the databases |
| internal hash values, and won't be sorted by the key values. This method |
| returns the starting key. |
| |
| .. method:: dbhash.last() |
| |
| Return the last key/value pair in a database traversal. This may be used to |
| begin a reverse-order traversal; see :meth:`previous`. |
| |
| .. method:: dbhash.next() |
| |
| Returns the key next key/value pair in a database traversal. The following code |
| prints every key in the database ``db``, without having to create a list in |
| memory that contains them all:: |
| |
| print(db.first()) |
| for i in range(1, len(db)): |
| print(db.next()) |
| |
| .. method:: dbhash.previous() |
| |
| Returns the previous key/value pair in a forward-traversal of the database. In |
| conjunction with :meth:`last`, this may be used to implement a reverse-order |
| traversal. |
| |
| .. method:: dbhash.sync() |
| |
| This method forces any unwritten data to be written to the disk. |
| |
| |
| :mod:`dbm.gnu` --- GNU's reinterpretation of dbm |
| ------------------------------------------------ |
| |
| .. module:: dbm.gnu |
| :platform: Unix |
| :synopsis: GNU's reinterpretation of dbm. |
| |
| |
| This module is quite similar to the :mod:`dbm` module, but uses the GNU library |
| ``gdbm`` instead to provide some additional functionality. Please note that the |
| file formats created by ``gdbm`` and ``dbm`` are incompatible. |
| |
| The :mod:`dbm.gnu` module provides an interface to the GNU DBM library. |
| ``gdbm`` objects behave like mappings (dictionaries), except that keys and |
| values are always strings. Printing a :mod:`dbm.gnu` object doesn't print the |
| keys and values, and the :meth:`items` and :meth:`values` methods are not |
| supported. |
| |
| .. exception:: error |
| |
| Raised on ``gdbm``\ -specific errors, such as I/O errors. :exc:`KeyError` is |
| raised for general mapping errors like specifying an incorrect key. |
| |
| |
| .. function:: open(filename, [flag, [mode]]) |
| |
| Open a ``gdbm`` database and return a :class:`gdbm` object. The *filename* |
| argument is the name of the database file. |
| |
| The optional *flag* argument can be: |
| |
| +---------+-------------------------------------------+ |
| | Value | Meaning | |
| +=========+===========================================+ |
| | ``'r'`` | Open existing database for reading only | |
| | | (default) | |
| +---------+-------------------------------------------+ |
| | ``'w'`` | Open existing database for reading and | |
| | | writing | |
| +---------+-------------------------------------------+ |
| | ``'c'`` | Open database for reading and writing, | |
| | | creating it if it doesn't exist | |
| +---------+-------------------------------------------+ |
| | ``'n'`` | Always create a new, empty database, open | |
| | | for reading and writing | |
| +---------+-------------------------------------------+ |
| |
| The following additional characters may be appended to the flag to control |
| how the database is opened: |
| |
| +---------+--------------------------------------------+ |
| | Value | Meaning | |
| +=========+============================================+ |
| | ``'f'`` | Open the database in fast mode. Writes | |
| | | to the database will not be synchronized. | |
| +---------+--------------------------------------------+ |
| | ``'s'`` | Synchronized mode. This will cause changes | |
| | | to the database to be immediately written | |
| | | to the file. | |
| +---------+--------------------------------------------+ |
| | ``'u'`` | Do not lock database. | |
| +---------+--------------------------------------------+ |
| |
| Not all flags are valid for all versions of ``gdbm``. The module constant |
| :const:`open_flags` is a string of supported flag characters. The exception |
| :exc:`error` is raised if an invalid flag is specified. |
| |
| The optional *mode* argument is the Unix mode of the file, used only when the |
| database has to be created. It defaults to octal ``0o666``. |
| |
| In addition to the dictionary-like methods, ``gdbm`` objects have the |
| following methods: |
| |
| .. method:: gdbm.firstkey() |
| |
| It's possible to loop over every key in the database using this method and the |
| :meth:`nextkey` method. The traversal is ordered by ``gdbm``'s internal |
| hash values, and won't be sorted by the key values. This method returns |
| the starting key. |
| |
| .. method:: gdbm.nextkey(key) |
| |
| Returns the key that follows *key* in the traversal. The following code prints |
| every key in the database ``db``, without having to create a list in memory that |
| contains them all:: |
| |
| k = db.firstkey() |
| while k != None: |
| print(k) |
| k = db.nextkey(k) |
| |
| .. method:: gdbm.reorganize() |
| |
| If you have carried out a lot of deletions and would like to shrink the space |
| used by the ``gdbm`` file, this routine will reorganize the database. ``gdbm`` |
| will not shorten the length of a database file except by using this |
| reorganization; otherwise, deleted file space will be kept and reused as new |
| (key, value) pairs are added. |
| |
| .. method:: gdbm.sync() |
| |
| When the database has been opened in fast mode, this method forces any |
| unwritten data to be written to the disk. |
| |
| |
| :mod:`dbm.ndbm` --- Interface based on ndbm |
| ------------------------------------------- |
| |
| .. module:: dbm.ndbm |
| :platform: Unix |
| :synopsis: The standard "database" interface, based on ndbm. |
| |
| |
| The :mod:`dbm.ndbm` module provides an interface to the Unix "(n)dbm" library. |
| Dbm objects behave like mappings (dictionaries), except that keys and values are |
| always strings. Printing a dbm object doesn't print the keys and values, and the |
| :meth:`items` and :meth:`values` methods are not supported. |
| |
| This module can be used with the "classic" ndbm interface, the BSD DB |
| compatibility interface, or the GNU GDBM compatibility interface. On Unix, the |
| :program:`configure` script will attempt to locate the appropriate header file |
| to simplify building this module. |
| |
| .. exception:: error |
| |
| Raised on dbm-specific errors, such as I/O errors. :exc:`KeyError` is raised |
| for general mapping errors like specifying an incorrect key. |
| |
| |
| .. data:: library |
| |
| Name of the ``ndbm`` implementation library used. |
| |
| |
| .. function:: open(filename[, flag[, mode]]) |
| |
| Open a dbm database and return a dbm object. The *filename* argument is the |
| name of the database file (without the :file:`.dir` or :file:`.pag` extensions; |
| note that the BSD DB implementation of the interface will append the extension |
| :file:`.db` and only create one file). |
| |
| The optional *flag* argument must be one of these values: |
| |
| +---------+-------------------------------------------+ |
| | Value | Meaning | |
| +=========+===========================================+ |
| | ``'r'`` | Open existing database for reading only | |
| | | (default) | |
| +---------+-------------------------------------------+ |
| | ``'w'`` | Open existing database for reading and | |
| | | writing | |
| +---------+-------------------------------------------+ |
| | ``'c'`` | Open database for reading and writing, | |
| | | creating it if it doesn't exist | |
| +---------+-------------------------------------------+ |
| | ``'n'`` | Always create a new, empty database, open | |
| | | for reading and writing | |
| +---------+-------------------------------------------+ |
| |
| The optional *mode* argument is the Unix mode of the file, used only when the |
| database has to be created. It defaults to octal ``0o666`` (and will be |
| modified by the prevailing umask). |
| |
| |
| |
| :mod:`dbm.dumb` --- Portable DBM implementation |
| ----------------------------------------------- |
| |
| .. module:: dbm.dumb |
| :synopsis: Portable implementation of the simple DBM interface. |
| |
| .. index:: single: databases |
| |
| .. note:: |
| |
| The :mod:`dbm.dumb` module is intended as a last resort fallback for the |
| :mod:`dbm` module when no more robust module is available. The :mod:`dbm.dumb` |
| module is not written for speed and is not nearly as heavily used as the other |
| database modules. |
| |
| The :mod:`dbm.dumb` module provides a persistent dictionary-like interface which |
| is written entirely in Python. Unlike other modules such as :mod:`gdbm` and |
| :mod:`bsddb`, no external library is required. As with other persistent |
| mappings, the keys and values must always be strings. |
| |
| The module defines the following: |
| |
| |
| .. exception:: error |
| |
| Raised on dbm.dumb-specific errors, such as I/O errors. :exc:`KeyError` is |
| raised for general mapping errors like specifying an incorrect key. |
| |
| |
| .. function:: open(filename[, flag[, mode]]) |
| |
| Open a dumbdbm database and return a dumbdbm object. The *filename* argument is |
| the basename of the database file (without any specific extensions). When a |
| dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions |
| are created. |
| |
| The optional *flag* argument is currently ignored; the database is always opened |
| for update, and will be created if it does not exist. |
| |
| The optional *mode* argument is the Unix mode of the file, used only when the |
| database has to be created. It defaults to octal ``0o666`` (and will be modified |
| by the prevailing umask). |
| |
| In addition to the methods provided by the :class:`collections.MutableMapping` class, |
| :class:`dumbdbm` objects provide the following method: |
| |
| .. method:: dumbdbm.sync() |
| |
| Synchronize the on-disk directory and data files. This method is called |
| by the :meth:`Shelve.sync` method. |