mirror of https://github.com/python/cpython
Docs: reword dbm.gnu introduction (#114548)
Also... - consistently spell GDBM as GDBM - silence gdbm class refs - improve accuracy of dbm.gdbm.open() spec
This commit is contained in:
parent
01d970c1b8
commit
06c5de36f2
|
@ -137,27 +137,28 @@ then prints out the contents of the database::
|
|||
The individual submodules are described in the following sections.
|
||||
|
||||
|
||||
:mod:`dbm.gnu` --- GNU's reinterpretation of dbm
|
||||
------------------------------------------------
|
||||
:mod:`dbm.gnu` --- GNU database manager
|
||||
---------------------------------------
|
||||
|
||||
.. module:: dbm.gnu
|
||||
:platform: Unix
|
||||
:synopsis: GNU's reinterpretation of dbm.
|
||||
:synopsis: GNU database manager
|
||||
|
||||
**Source code:** :source:`Lib/dbm/gnu.py`
|
||||
|
||||
--------------
|
||||
|
||||
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 :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible.
|
||||
The :mod:`dbm.gnu` module provides an interface to the :abbr:`GDBM (GNU dbm)`
|
||||
library, similar to the :mod:`dbm.ndbm` module, but with additional
|
||||
functionality like crash tolerance.
|
||||
|
||||
The :mod:`dbm.gnu` module provides an interface to the GNU DBM library.
|
||||
``dbm.gnu.gdbm`` objects behave like mappings (dictionaries), except that keys and
|
||||
values are always converted to bytes before storing. Printing a ``gdbm``
|
||||
object doesn't print the
|
||||
keys and values, and the :meth:`items` and :meth:`values` methods are not
|
||||
supported.
|
||||
:class:`!gdbm` objects behave similar to :term:`mappings <mapping>`,
|
||||
except that keys and values are always converted to :class:`bytes` before storing,
|
||||
and the :meth:`!items` and :meth:`!values` methods are not supported.
|
||||
|
||||
.. note::
|
||||
The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are
|
||||
incompatible and can not be used interchangeably.
|
||||
|
||||
.. exception:: error
|
||||
|
||||
|
@ -165,9 +166,9 @@ supported.
|
|||
raised for general mapping errors like specifying an incorrect key.
|
||||
|
||||
|
||||
.. function:: open(filename[, flag[, mode]])
|
||||
.. function:: open(filename, flag="r", mode=0o666, /)
|
||||
|
||||
Open a ``gdbm`` database and return a :class:`gdbm` object. The *filename*
|
||||
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:
|
||||
|
@ -196,14 +197,14 @@ supported.
|
|||
| ``'u'`` | Do not lock database. |
|
||||
+---------+--------------------------------------------+
|
||||
|
||||
Not all flags are valid for all versions of ``gdbm``. The module constant
|
||||
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
|
||||
In addition to the dictionary-like methods, :class:`gdbm` objects have the
|
||||
following methods:
|
||||
|
||||
.. versionchanged:: 3.11
|
||||
|
@ -212,7 +213,7 @@ supported.
|
|||
.. 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
|
||||
: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.
|
||||
|
||||
|
@ -230,7 +231,7 @@ supported.
|
|||
.. 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``
|
||||
used by the GDBM file, this routine will reorganize the database. :class:`!gdbm`
|
||||
objects 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.
|
||||
|
@ -242,11 +243,11 @@ supported.
|
|||
|
||||
.. method:: gdbm.close()
|
||||
|
||||
Close the ``gdbm`` database.
|
||||
Close the GDBM database.
|
||||
|
||||
.. method:: gdbm.clear()
|
||||
|
||||
Remove all items from the ``gdbm`` database.
|
||||
Remove all items from the GDBM database.
|
||||
|
||||
.. versionadded:: 3.13
|
||||
|
||||
|
|
Loading…
Reference in New Issue