From f416af903f0566f4fd0e49e442354c166c62cd26 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 26 Jan 2024 11:13:35 +0100 Subject: [3.12] Docs: reword dbm.gnu introduction (#114548) (#114588) (cherry picked from commit 06c5de36f222b926bbc94831536096b974bd5e77) Also... - consistently spell GDBM as GDBM - silence gdbm class refs - improve accuracy of dbm.gdbm.open() spec --- Doc/library/dbm.rst | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst index bc72f0f..1e8e2bb 100644 --- a/Doc/library/dbm.rst +++ b/Doc/library/dbm.rst @@ -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 `, +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,7 +243,7 @@ supported. .. method:: gdbm.close() - Close the ``gdbm`` database. + Close the GDBM database. :mod:`dbm.ndbm` --- Interface based on ndbm ------------------------------------------- -- cgit v0.12