https://github.com/python/cpython/commit/511b37a6023ba05069e09a430d15c0a574815b28
commit: 511b37a6023ba05069e09a430d15c0a574815b28
branch: 3.13
author: Serhiy Storchaka <[email protected]>
committer: serhiy-storchaka <[email protected]>
date: 2025-08-19T20:39:08+03:00
summary:
[3.13] Update the dbm documentation (GH-137919) (GH-137963)
Unify documentation for all backends, enumerate all not implemented mapping
methods, document particularities of implemented mapping methods.
(cherry picked from commit 8700404f8688d6a56279dce47a5a5802ec53ed06)
files:
M Doc/library/dbm.rst
M Doc/whatsnew/3.13.rst
diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index 36221c026d6d4b..628232cb631bd4 100644
--- a/Doc/library/dbm.rst
+++ b/Doc/library/dbm.rst
@@ -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
@@ -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::
@@ -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.
@@ -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
---------------------------------------
@@ -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.
@@ -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
@@ -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
----------------------------------------
@@ -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
@@ -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).
@@ -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.
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index c7a31853426b54..64e8259a7082e2 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -843,7 +843,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`.)
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
