cpython/Doc/library/anydbm.rst

115 lines
3.9 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:01 -03:00
:mod:`anydbm` --- Generic access to DBM-style databases
=======================================================
.. module:: anydbm
:synopsis: Generic interface to DBM-style database modules.
.. note::
The :mod:`anydbm` module has been renamed to :mod:`dbm` in Python 3.0. The
:term:`2to3` tool will automatically adapt imports when converting your
sources to 3.0.
2007-08-15 11:28:01 -03:00
.. index::
module: dbhash
module: bsddb
module: gdbm
module: dbm
module: dumbdbm
:mod:`anydbm` is a generic interface to variants of the DBM database ---
:mod:`dbhash` (requires :mod:`bsddb`), :mod:`gdbm`, or :mod:`dbm`. If none of
these modules is installed, the slow-but-simple implementation in module
:mod:`dumbdbm` will be used.
.. function:: open(filename[, flag[, mode]])
Open the database file *filename* and return a corresponding object.
Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r72319 | georg.brandl | 2009-05-05 10:28:49 +0200 (Di, 05 Mai 2009) | 1 line #1309567: fix linecache behavior of stripping subdirectories from paths when looking for relative filename matches. Also add a linecache test suite. ........ r72320 | georg.brandl | 2009-05-05 10:30:28 +0200 (Di, 05 Mai 2009) | 1 line Add a news entry for r72319. ........ r72467 | georg.brandl | 2009-05-08 14:17:34 +0200 (Fr, 08 Mai 2009) | 1 line Fix name. ........ r72661 | georg.brandl | 2009-05-15 10:03:03 +0200 (Fr, 15 Mai 2009) | 1 line Fix example output for doctest-like demos. ........ r72675 | georg.brandl | 2009-05-16 13:13:21 +0200 (Sa, 16 Mai 2009) | 1 line #6034: clarify __reversed__ doc. ........ r72676 | georg.brandl | 2009-05-16 13:14:46 +0200 (Sa, 16 Mai 2009) | 1 line #6025: fix signature of parse(). ........ r72677 | georg.brandl | 2009-05-16 13:18:55 +0200 (Sa, 16 Mai 2009) | 1 line #6009: undocument default argument of Option as deprecated. ........ r72678 | georg.brandl | 2009-05-16 13:21:29 +0200 (Sa, 16 Mai 2009) | 1 line #2856: document 2.x os.listdir() behavior for undecodable filenames. ........ r72679 | georg.brandl | 2009-05-16 13:24:41 +0200 (Sa, 16 Mai 2009) | 1 line Fix about and bugs pages to match real workflow. ........ r72703 | georg.brandl | 2009-05-17 10:10:27 +0200 (So, 17 Mai 2009) | 1 line part of #4144: fix exception message in console session. ........ r72708 | georg.brandl | 2009-05-17 10:24:29 +0200 (So, 17 Mai 2009) | 1 line #6017: better document behavior of dictiterators when the dict is changed. ........ r72710 | georg.brandl | 2009-05-17 10:36:04 +0200 (So, 17 Mai 2009) | 1 line #5942: Copy over flag table from dbm.rst which is clearer. ........ r72712 | georg.brandl | 2009-05-17 10:55:00 +0200 (So, 17 Mai 2009) | 1 line #5935: mention that BROWSER is looked for in PATH. ........ r72801 | georg.brandl | 2009-05-20 20:31:14 +0200 (Mi, 20 Mai 2009) | 1 line #6055: refer to "sqlite3" consistently. ........ r72802 | georg.brandl | 2009-05-20 20:35:27 +0200 (Mi, 20 Mai 2009) | 1 line #6051: refer to email examples for better way to construct email messages. ........ r72820 | georg.brandl | 2009-05-22 09:23:32 +0200 (Fr, 22 Mai 2009) | 1 line Use raise X(y). ........ r72822 | georg.brandl | 2009-05-22 11:33:25 +0200 (Fr, 22 Mai 2009) | 1 line #6084: fix example. ........ r72824 | georg.brandl | 2009-05-22 11:43:17 +0200 (Fr, 22 Mai 2009) | 1 line Fix references to file-related functions and methods (os.* vs file.*). ........ r72826 | georg.brandl | 2009-05-22 11:49:42 +0200 (Fr, 22 Mai 2009) | 1 line Fix confusing wording. ........ r72827 | georg.brandl | 2009-05-22 11:50:30 +0200 (Fr, 22 Mai 2009) | 1 line s/use/call/ ........ r72828 | georg.brandl | 2009-05-22 11:58:48 +0200 (Fr, 22 Mai 2009) | 1 line Correction in softspace behavior description. ........ r72830 | georg.brandl | 2009-05-22 12:40:00 +0200 (Fr, 22 Mai 2009) | 1 line #6086: fix spelling and use a better exception to catch. ........
2009-05-26 06:04:23 -03:00
If the database file already exists, the :mod:`whichdb` module 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 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 |
+---------+-------------------------------------------+
If not specified, the default value is ``'r'``.
2007-08-15 11:28:01 -03:00
The optional *mode* argument is the Unix mode of the file, used only when the
Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r72319 | georg.brandl | 2009-05-05 10:28:49 +0200 (Di, 05 Mai 2009) | 1 line #1309567: fix linecache behavior of stripping subdirectories from paths when looking for relative filename matches. Also add a linecache test suite. ........ r72320 | georg.brandl | 2009-05-05 10:30:28 +0200 (Di, 05 Mai 2009) | 1 line Add a news entry for r72319. ........ r72467 | georg.brandl | 2009-05-08 14:17:34 +0200 (Fr, 08 Mai 2009) | 1 line Fix name. ........ r72661 | georg.brandl | 2009-05-15 10:03:03 +0200 (Fr, 15 Mai 2009) | 1 line Fix example output for doctest-like demos. ........ r72675 | georg.brandl | 2009-05-16 13:13:21 +0200 (Sa, 16 Mai 2009) | 1 line #6034: clarify __reversed__ doc. ........ r72676 | georg.brandl | 2009-05-16 13:14:46 +0200 (Sa, 16 Mai 2009) | 1 line #6025: fix signature of parse(). ........ r72677 | georg.brandl | 2009-05-16 13:18:55 +0200 (Sa, 16 Mai 2009) | 1 line #6009: undocument default argument of Option as deprecated. ........ r72678 | georg.brandl | 2009-05-16 13:21:29 +0200 (Sa, 16 Mai 2009) | 1 line #2856: document 2.x os.listdir() behavior for undecodable filenames. ........ r72679 | georg.brandl | 2009-05-16 13:24:41 +0200 (Sa, 16 Mai 2009) | 1 line Fix about and bugs pages to match real workflow. ........ r72703 | georg.brandl | 2009-05-17 10:10:27 +0200 (So, 17 Mai 2009) | 1 line part of #4144: fix exception message in console session. ........ r72708 | georg.brandl | 2009-05-17 10:24:29 +0200 (So, 17 Mai 2009) | 1 line #6017: better document behavior of dictiterators when the dict is changed. ........ r72710 | georg.brandl | 2009-05-17 10:36:04 +0200 (So, 17 Mai 2009) | 1 line #5942: Copy over flag table from dbm.rst which is clearer. ........ r72712 | georg.brandl | 2009-05-17 10:55:00 +0200 (So, 17 Mai 2009) | 1 line #5935: mention that BROWSER is looked for in PATH. ........ r72801 | georg.brandl | 2009-05-20 20:31:14 +0200 (Mi, 20 Mai 2009) | 1 line #6055: refer to "sqlite3" consistently. ........ r72802 | georg.brandl | 2009-05-20 20:35:27 +0200 (Mi, 20 Mai 2009) | 1 line #6051: refer to email examples for better way to construct email messages. ........ r72820 | georg.brandl | 2009-05-22 09:23:32 +0200 (Fr, 22 Mai 2009) | 1 line Use raise X(y). ........ r72822 | georg.brandl | 2009-05-22 11:33:25 +0200 (Fr, 22 Mai 2009) | 1 line #6084: fix example. ........ r72824 | georg.brandl | 2009-05-22 11:43:17 +0200 (Fr, 22 Mai 2009) | 1 line Fix references to file-related functions and methods (os.* vs file.*). ........ r72826 | georg.brandl | 2009-05-22 11:49:42 +0200 (Fr, 22 Mai 2009) | 1 line Fix confusing wording. ........ r72827 | georg.brandl | 2009-05-22 11:50:30 +0200 (Fr, 22 Mai 2009) | 1 line s/use/call/ ........ r72828 | georg.brandl | 2009-05-22 11:58:48 +0200 (Fr, 22 Mai 2009) | 1 line Correction in softspace behavior description. ........ r72830 | georg.brandl | 2009-05-22 12:40:00 +0200 (Fr, 22 Mai 2009) | 1 line #6086: fix spelling and use a better exception to catch. ........
2009-05-26 06:04:23 -03:00
database has to be created. It defaults to octal ``0666`` (and will be
modified by the prevailing umask).
2007-08-15 11:28:01 -03:00
.. exception:: error
A tuple containing the exceptions that can be raised by each of the supported
modules, with a unique exception also named :exc:`anydbm.error` as the first
item --- the latter is used when :exc:`anydbm.error` is raised.
The object returned by :func:`.open` supports most of the same functionality as
2007-08-15 11:28:01 -03:00
dictionaries; keys and their corresponding values can be stored, retrieved, and
deleted, and the :meth:`has_key` and :meth:`keys` methods 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 anydbm
# Open database, creating it if necessary.
db = anydbm.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:`dbhash`
BSD ``db`` database interface.
Module :mod:`dbm`
Standard Unix database interface.
Module :mod:`dumbdbm`
Portable implementation of the ``dbm`` interface.
Module :mod:`gdbm`
GNU database interface, based on the ``dbm`` interface.
Module :mod:`shelve`
General object persistence built on top of the Python ``dbm`` interface.
Module :mod:`whichdb`
Utility module used to determine the type of an existing database.