Skip to content

Update the dbm documentation #137919

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 3 commits into from
Aug 19, 2025
Merged

Update the dbm documentation #137919

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ba9dfb1
Update the dbm documentation
serhiy-storchaka Aug 18, 2025
ed5015d
Document the clear() methods the same way as get() and setdefault() m…
serhiy-storchaka Aug 18, 2025
512da21
Fix references.
serhiy-storchaka Aug 18, 2025
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
103 changes: 65 additions & 38 deletions Doc/library/dbm.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,10 +90,13 @@ the Oracle Berkeley DB.
.. versionchanged:: 3.11
*file* accepts a :term:`path-like object`.

The object returned by :func:`~dbm.open` supports the same basic functionality as a
:class:`dict`; keys and their corresponding values can be stored, retrieved, and
deleted, and the :keyword:`in` operator and the :meth:`!keys` method are
available, as well as :meth:`!get` and :meth:`!setdefault` methods.
The object returned by :func:`~dbm.open` supports the basic
functionality of mutable :term:`mappings <mapping>`;
keys and their corresponding values can be stored, retrieved, and
deleted, and iteration, the :keyword:`in` operator and methods :meth:`!keys`,
:meth:`!get` and :meth:`!setdefault` are available.
The :meth:`!keys` method usually returns a list instead of a view object.
The :meth:`!setdefault` method requires two arguments.

Key and values are always stored as :class:`bytes`. This means that when
strings are used they are implicitly converted to the default encoding before
Expand All @@ -114,6 +117,10 @@ will automatically close them when done.
Deleting a key from a read-only database raises a database module specific exception
instead of :exc:`KeyError`.

.. versionchanged:: 3.13
:meth:`!clear` methods are now available for all :mod:`dbm` backends.


The following example records some hostnames and a corresponding title, and
then prints out the contents of the database::

Expand Down Expand Up @@ -173,9 +180,6 @@ or any other SQLite browser, including the SQLite CLI.
.. function:: open(filename, /, flag="r", mode=0o666)

Open an SQLite database.
The returned object behaves like a :term:`mapping`,
implements a :meth:`!close` method,
and supports a "closing" context manager via the :keyword:`with` keyword.

:param filename:
The path to the database to be opened.
Expand All @@ -192,6 +196,17 @@ or any other SQLite browser, including the SQLite CLI.
The Unix file access mode of the file (default: octal ``0o666``),
used only when the database has to be created.

The returned database object behaves similar to a mutable :term:`mapping`,
but the :meth:`!keys` method returns a list, and
the :meth:`!setdefault` method requires two arguments.
It also supports a "closing" context manager via the :keyword:`with` keyword.

The following methods are also provided:

.. method:: sqlite3.close()

Close the SQLite database.

.. method:: sqlite3.reorganize()

If you have carried out a lot of deletions and would like to shrink the space
Expand All @@ -204,6 +219,7 @@ or any other SQLite browser, including the SQLite CLI.

.. versionadded:: next


:mod:`dbm.gnu` --- GNU database manager
---------------------------------------

Expand Down Expand Up @@ -232,6 +248,11 @@ functionality like crash tolerance.
raised for general mapping errors like specifying an incorrect key.


.. data:: open_flags

A string of characters the *flag* parameter of :meth:`~dbm.gnu.open` supports.


.. function:: open(filename, flag="r", mode=0o666, /)

Open a GDBM database and return a :class:`!gdbm` object.
Expand Down Expand Up @@ -270,14 +291,25 @@ functionality like crash tolerance.
.. versionchanged:: 3.11
*filename* accepts a :term:`path-like object`.

.. data:: open_flags

A string of characters the *flag* parameter of :meth:`~dbm.gnu.open` supports.
:class:`!gdbm` objects behave similar to mutable :term:`mappings <mapping>`,
but methods :meth:`!items`, :meth:`!values`, :meth:`!pop`, :meth:`!popitem`,
and :meth:`!update` are not supported,
the :meth:`!keys` method returns a list, and
the :meth:`!setdefault` method requires two arguments.
It also supports a "closing" context manager via the :keyword:`with` keyword.

:class:`!gdbm` objects behave similar to :term:`mappings <mapping>`,
but :meth:`!items` and :meth:`!values` methods are not supported.
The following methods are also provided:

.. method:: gdbm.clear()

Remove all items from the GDBM database.

.. versionadded:: 3.13

.. method:: gdbm.close()

Close the GDBM database.

.. method:: gdbm.firstkey()

It's possible to loop over every key in the database using this method and the
Expand Down Expand Up @@ -313,16 +345,6 @@ functionality like crash tolerance.
When the database has been opened in fast mode, this method forces any
unwritten data to be written to the disk.

.. method:: gdbm.close()

Close the GDBM database.

.. method:: gdbm.clear()

Remove all items from the GDBM database.

.. versionadded:: 3.13


:mod:`dbm.ndbm` --- New Database Manager
----------------------------------------
Expand Down Expand Up @@ -383,23 +405,28 @@ This module can be used with the "classic" NDBM interface or the
:param int mode:
|mode_param_doc|

:class:`!ndbm` objects behave similar to :term:`mappings <mapping>`,
but :meth:`!items` and :meth:`!values` methods are not supported.
The following methods are also provided:

.. versionchanged:: 3.11
Accepts :term:`path-like object` for filename.

.. method:: ndbm.close()
:class:`!ndbm` objects behave similar to mutable :term:`mappings <mapping>`,
but methods :meth:`!items`, :meth:`!values`, :meth:`!pop`, :meth:`!popitem`,
and :meth:`!update` are not supported,
the :meth:`!keys` method returns a list, and
the :meth:`!setdefault` method requires two arguments.
It also supports a "closing" context manager via the :keyword:`with` keyword.

Close the NDBM database.
The following methods are also provided:

.. method:: ndbm.clear()

Remove all items from the NDBM database.

.. versionadded:: 3.13

.. method:: ndbm.close()

Close the NDBM database.


:mod:`dbm.dumb` --- Portable DBM implementation
-----------------------------------------------
Expand Down Expand Up @@ -436,9 +463,6 @@ The :mod:`!dbm.dumb` module defines the following:
.. function:: open(filename, flag="c", mode=0o666)

Open a :mod:`!dbm.dumb` database.
The returned database object behaves similar to a :term:`mapping`,
in addition to providing :meth:`~dumbdbm.sync` and :meth:`~dumbdbm.close`
methods.

:param filename:
The basename of the database file (without extensions).
Expand Down Expand Up @@ -477,14 +501,12 @@ The :mod:`!dbm.dumb` module defines the following:
.. versionchanged:: 3.11
*filename* accepts a :term:`path-like object`.

In addition to the methods provided by the
:class:`collections.abc.MutableMapping` class,
the following methods are provided:

.. method:: dumbdbm.sync()
The returned database object behaves similar to a mutable :term:`mapping`,
but the :meth:`!keys` and :meth:`!items` methods return lists, and
the :meth:`!setdefault` method requires two arguments.
It also supports a "closing" context manager via the :keyword:`with` keyword.

Synchronize the on-disk directory and data files. This method is called
by the :meth:`shelve.Shelf.sync` method.
The following methods are also provided:

.. method:: dumbdbm.close()

Expand All @@ -501,3 +523,8 @@ The :mod:`!dbm.dumb` module defines the following:
that this factor changes for each :mod:`dbm` submodule.

.. versionadded:: next

.. method:: dumbdbm.sync()

Synchronize the on-disk directory and data files. This method is called
by the :meth:`shelve.Shelf.sync` method.
Loading