/Doc/library/gdbm.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 126 lines · 88 code · 38 blank · 0 comment · 0 complexity · 5bc6318ee1d979cdfbeb9d94da8241a5 MD5 · raw file

  1. :mod:`gdbm` --- GNU's reinterpretation of dbm
  2. =============================================
  3. .. module:: gdbm
  4. :platform: Unix
  5. :synopsis: GNU's reinterpretation of dbm.
  6. .. note::
  7. The :mod:`gdbm` module has been renamed to :mod:`dbm.gnu` in Python 3.0. The
  8. :term:`2to3` tool will automatically adapt imports when converting your
  9. sources to 3.0.
  10. .. index:: module: dbm
  11. This module is quite similar to the :mod:`dbm` module, but uses ``gdbm`` instead
  12. to provide some additional functionality. Please note that the file formats
  13. created by ``gdbm`` and ``dbm`` are incompatible.
  14. The :mod:`gdbm` module provides an interface to the GNU DBM library. ``gdbm``
  15. objects behave like mappings (dictionaries), except that keys and values are
  16. always strings. Printing a ``gdbm`` object doesn't print the keys and values,
  17. and the :meth:`items` and :meth:`values` methods are not supported.
  18. The module defines the following constant and functions:
  19. .. exception:: error
  20. Raised on ``gdbm``\ -specific errors, such as I/O errors. :exc:`KeyError` is
  21. raised for general mapping errors like specifying an incorrect key.
  22. .. function:: open(filename, [flag, [mode]])
  23. Open a ``gdbm`` database and return a ``gdbm`` object. The *filename* argument
  24. is the name of the database file.
  25. The optional *flag* argument can be:
  26. +---------+-------------------------------------------+
  27. | Value | Meaning |
  28. +=========+===========================================+
  29. | ``'r'`` | Open existing database for reading only |
  30. | | (default) |
  31. +---------+-------------------------------------------+
  32. | ``'w'`` | Open existing database for reading and |
  33. | | writing |
  34. +---------+-------------------------------------------+
  35. | ``'c'`` | Open database for reading and writing, |
  36. | | creating it if it doesn't exist |
  37. +---------+-------------------------------------------+
  38. | ``'n'`` | Always create a new, empty database, open |
  39. | | for reading and writing |
  40. +---------+-------------------------------------------+
  41. The following additional characters may be appended to the flag to control
  42. how the database is opened:
  43. +---------+--------------------------------------------+
  44. | Value | Meaning |
  45. +=========+============================================+
  46. | ``'f'`` | Open the database in fast mode. Writes |
  47. | | to the database will not be synchronized. |
  48. +---------+--------------------------------------------+
  49. | ``'s'`` | Synchronized mode. This will cause changes |
  50. | | to the database to be immediately written |
  51. | | to the file. |
  52. +---------+--------------------------------------------+
  53. | ``'u'`` | Do not lock database. |
  54. +---------+--------------------------------------------+
  55. Not all flags are valid for all versions of ``gdbm``. The module constant
  56. :const:`open_flags` is a string of supported flag characters. The exception
  57. :exc:`error` is raised if an invalid flag is specified.
  58. The optional *mode* argument is the Unix mode of the file, used only when the
  59. database has to be created. It defaults to octal ``0666``.
  60. In addition to the dictionary-like methods, ``gdbm`` objects have the following
  61. methods:
  62. .. function:: firstkey()
  63. It's possible to loop over every key in the database using this method and the
  64. :meth:`nextkey` method. The traversal is ordered by ``gdbm``'s internal hash
  65. values, and won't be sorted by the key values. This method returns the starting
  66. key.
  67. .. function:: nextkey(key)
  68. Returns the key that follows *key* in the traversal. The following code prints
  69. every key in the database ``db``, without having to create a list in memory that
  70. contains them all::
  71. k = db.firstkey()
  72. while k != None:
  73. print k
  74. k = db.nextkey(k)
  75. .. function:: reorganize()
  76. If you have carried out a lot of deletions and would like to shrink the space
  77. used by the ``gdbm`` file, this routine will reorganize the database. ``gdbm``
  78. will not shorten the length of a database file except by using this
  79. reorganization; otherwise, deleted file space will be kept and reused as new
  80. (key, value) pairs are added.
  81. .. function:: sync()
  82. When the database has been opened in fast mode, this method forces any
  83. unwritten data to be written to the disk.
  84. .. seealso::
  85. Module :mod:`anydbm`
  86. Generic interface to ``dbm``\ -style databases.
  87. Module :mod:`whichdb`
  88. Utility module used to determine the type of an existing database.