/Doc/library/dbhash.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 115 lines · 74 code · 41 blank · 0 comment · 0 complexity · 8ace6a35529bfa1031de60ade19163af MD5 · raw file

  1. :mod:`dbhash` --- DBM-style interface to the BSD database library
  2. =================================================================
  3. .. module:: dbhash
  4. :synopsis: DBM-style interface to the BSD database library.
  5. .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
  6. .. deprecated:: 2.6
  7. The :mod:`dbhash` module has been deprecated for removal in Python 3.0.
  8. .. index:: module: bsddb
  9. The :mod:`dbhash` module provides a function to open databases using the BSD
  10. ``db`` library. This module mirrors the interface of the other Python database
  11. modules that provide access to DBM-style databases. The :mod:`bsddb` module is
  12. required to use :mod:`dbhash`.
  13. This module provides an exception and a function:
  14. .. exception:: error
  15. Exception raised on database errors other than :exc:`KeyError`. It is a synonym
  16. for :exc:`bsddb.error`.
  17. .. function:: open(path[, flag[, mode]])
  18. Open a ``db`` database and return the database object. The *path* argument is
  19. the name of the database file.
  20. The *flag* argument can be:
  21. +---------+-------------------------------------------+
  22. | Value | Meaning |
  23. +=========+===========================================+
  24. | ``'r'`` | Open existing database for reading only |
  25. | | (default) |
  26. +---------+-------------------------------------------+
  27. | ``'w'`` | Open existing database for reading and |
  28. | | writing |
  29. +---------+-------------------------------------------+
  30. | ``'c'`` | Open database for reading and writing, |
  31. | | creating it if it doesn't exist |
  32. +---------+-------------------------------------------+
  33. | ``'n'`` | Always create a new, empty database, open |
  34. | | for reading and writing |
  35. +---------+-------------------------------------------+
  36. For platforms on which the BSD ``db`` library supports locking, an ``'l'``
  37. can be appended to indicate that locking should be used.
  38. The optional *mode* parameter is used to indicate the Unix permission bits that
  39. should be set if a new database must be created; this will be masked by the
  40. current umask value for the process.
  41. .. seealso::
  42. Module :mod:`anydbm`
  43. Generic interface to ``dbm``\ -style databases.
  44. Module :mod:`bsddb`
  45. Lower-level interface to the BSD ``db`` library.
  46. Module :mod:`whichdb`
  47. Utility module used to determine the type of an existing database.
  48. .. _dbhash-objects:
  49. Database Objects
  50. ----------------
  51. The database objects returned by :func:`open` provide the methods common to all
  52. the DBM-style databases and mapping objects. The following methods are
  53. available in addition to the standard methods.
  54. .. method:: dbhash.first()
  55. It's possible to loop over every key/value pair in the database using this
  56. method and the :meth:`next` method. The traversal is ordered by the databases
  57. internal hash values, and won't be sorted by the key values. This method
  58. returns the starting key.
  59. .. method:: dbhash.last()
  60. Return the last key/value pair in a database traversal. This may be used to
  61. begin a reverse-order traversal; see :meth:`previous`.
  62. .. method:: dbhash.next()
  63. Returns the key next key/value pair in a database traversal. The following code
  64. prints every key in the database ``db``, without having to create a list in
  65. memory that contains them all::
  66. print db.first()
  67. for i in xrange(1, len(db)):
  68. print db.next()
  69. .. method:: dbhash.previous()
  70. Returns the previous key/value pair in a forward-traversal of the database. In
  71. conjunction with :meth:`last`, this may be used to implement a reverse-order
  72. traversal.
  73. .. method:: dbhash.sync()
  74. This method forces any unwritten data to be written to the disk.