/Doc/library/anydbm.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 114 lines · 81 code · 33 blank · 0 comment · 0 complexity · b4131a4b9169532f46e6a1836a8e48c5 MD5 · raw file

  1. :mod:`anydbm` --- Generic access to DBM-style databases
  2. =======================================================
  3. .. module:: anydbm
  4. :synopsis: Generic interface to DBM-style database modules.
  5. .. note::
  6. The :mod:`anydbm` module has been renamed to :mod:`dbm` in Python 3.0. The
  7. :term:`2to3` tool will automatically adapt imports when converting your
  8. sources to 3.0.
  9. .. index::
  10. module: dbhash
  11. module: bsddb
  12. module: gdbm
  13. module: dbm
  14. module: dumbdbm
  15. :mod:`anydbm` is a generic interface to variants of the DBM database ---
  16. :mod:`dbhash` (requires :mod:`bsddb`), :mod:`gdbm`, or :mod:`dbm`. If none of
  17. these modules is installed, the slow-but-simple implementation in module
  18. :mod:`dumbdbm` will be used.
  19. .. function:: open(filename[, flag[, mode]])
  20. Open the database file *filename* and return a corresponding object.
  21. If the database file already exists, the :mod:`whichdb` module is used to
  22. determine its type and the appropriate module is used; if it does not exist,
  23. the first module listed above that can be imported is used.
  24. The optional *flag* argument must be one of these values:
  25. +---------+-------------------------------------------+
  26. | Value | Meaning |
  27. +=========+===========================================+
  28. | ``'r'`` | Open existing database for reading only |
  29. | | (default) |
  30. +---------+-------------------------------------------+
  31. | ``'w'`` | Open existing database for reading and |
  32. | | writing |
  33. +---------+-------------------------------------------+
  34. | ``'c'`` | Open database for reading and writing, |
  35. | | creating it if it doesn't exist |
  36. +---------+-------------------------------------------+
  37. | ``'n'`` | Always create a new, empty database, open |
  38. | | for reading and writing |
  39. +---------+-------------------------------------------+
  40. If not specified, the default value is ``'r'``.
  41. The optional *mode* argument is the Unix mode of the file, used only when the
  42. database has to be created. It defaults to octal ``0666`` (and will be
  43. modified by the prevailing umask).
  44. .. exception:: error
  45. A tuple containing the exceptions that can be raised by each of the supported
  46. modules, with a unique exception also named :exc:`anydbm.error` as the first
  47. item --- the latter is used when :exc:`anydbm.error` is raised.
  48. The object returned by :func:`open` supports most of the same functionality as
  49. dictionaries; keys and their corresponding values can be stored, retrieved, and
  50. deleted, and the :meth:`has_key` and :meth:`keys` methods are available. Keys
  51. and values must always be strings.
  52. The following example records some hostnames and a corresponding title, and
  53. then prints out the contents of the database::
  54. import anydbm
  55. # Open database, creating it if necessary.
  56. db = anydbm.open('cache', 'c')
  57. # Record some values
  58. db['www.python.org'] = 'Python Website'
  59. db['www.cnn.com'] = 'Cable News Network'
  60. # Loop through contents. Other dictionary methods
  61. # such as .keys(), .values() also work.
  62. for k, v in db.iteritems():
  63. print k, '\t', v
  64. # Storing a non-string key or value will raise an exception (most
  65. # likely a TypeError).
  66. db['www.yahoo.com'] = 4
  67. # Close when done.
  68. db.close()
  69. .. seealso::
  70. Module :mod:`dbhash`
  71. BSD ``db`` database interface.
  72. Module :mod:`dbm`
  73. Standard Unix database interface.
  74. Module :mod:`dumbdbm`
  75. Portable implementation of the ``dbm`` interface.
  76. Module :mod:`gdbm`
  77. GNU database interface, based on the ``dbm`` interface.
  78. Module :mod:`shelve`
  79. General object persistence built on top of the Python ``dbm`` interface.
  80. Module :mod:`whichdb`
  81. Utility module used to determine the type of an existing database.