Skip to content

[3.14] Update the dbm documentation (GH-137919) #137962

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

Open
wants to merge 1 commit into
base: 3.14
Choose a base branch
from
+67 −41
Open

[3.14] Update the dbm documentation (GH-137919) #137962

Show file tree
Hide file tree
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
106 changes: 66 additions & 40 deletions Doc/library/dbm.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,10 +84,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`, :meth:`!setdefault` and :meth:`!clear` are available.
The :meth:`!keys` method 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 @@ -108,6 +111,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 @@ -167,9 +174,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 @@ -186,6 +190,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 method is also provided:

.. method:: sqlite3.close()

Close the SQLite database.


:mod:`dbm.gnu` --- GNU database manager
---------------------------------------
Expand Down Expand Up @@ -215,6 +230,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 @@ -250,14 +270,25 @@ functionality like crash tolerance.
.. versionchanged:: 3.11
*filename* accepts a :term:`path-like object`.

.. data:: open_flags
: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.

.. versionchanged:: 3.2
Added the :meth:`!get` and :meth:`!setdefault` methods.

A string of characters the *flag* parameter of :meth:`~dbm.gnu.open` supports.
.. versionchanged:: 3.13
Added the :meth:`!clear` method.

: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.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 @@ -289,16 +320,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 @@ -359,22 +380,27 @@ 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.
.. versionchanged:: 3.2
Added the :meth:`!get` and :meth:`!setdefault` methods.

.. method:: ndbm.clear()
.. versionchanged:: 3.13
Added the :meth:`!clear` method.

Remove all items from the NDBM database.
The following method is also provided:

.. versionadded:: 3.13
.. method:: ndbm.close()

Close the NDBM database.


:mod:`dbm.dumb` --- Portable DBM implementation
Expand Down Expand Up @@ -412,9 +438,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 @@ -448,15 +471,18 @@ 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:
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.

.. method:: dumbdbm.sync()

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()

Close the database.

.. method:: dumbdbm.sync()

Synchronize the on-disk directory and data files. This method is called
by the :meth:`shelve.Shelf.sync` method.
2 changes: 1 addition & 1 deletion Doc/whatsnew/3.13.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -834,7 +834,7 @@ dbm
(Contributed by Raymond Hettinger and Erlend E. Aasland in :gh:`100414`.)

* Allow removing all items from the database through
the new :meth:`.gdbm.clear` and :meth:`.ndbm.clear` methods.
the new :meth:`!clear` methods of the GDBM and NDBM database objects.
(Contributed by Donghee Na in :gh:`107122`.)


Expand Down
Loading