Skip to content

[3.12] Docs: reword dbm.gnu introduction (#114548) #114588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 26, 2024
Merged

[3.12] Docs: reword dbm.gnu introduction (#114548) #114588

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 20 additions & 19 deletions Doc/library/dbm.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,37 +137,38 @@ 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

Raised on :mod:`dbm.gnu`-specific errors, such as I/O errors. :exc:`KeyError` is
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:
Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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.
Expand All @@ -242,7 +243,7 @@ supported.

.. method:: gdbm.close()

Close the ``gdbm`` database.
Close the GDBM database.

:mod:`dbm.ndbm` --- Interface based on ndbm
-------------------------------------------
Expand Down