mirror of
https://github.com/python/cpython.git
synced 2025-12-31 04:23:37 +00:00
Update the dbm documentation (GH-137919)
Unify documentation for all backends, enumerate all not implemented mapping methods, document particularities of implemented mapping methods.
This commit is contained in:
Serhiy Storchaka
GitHub
parent
ac37b77441
commit
8700404f86
2 changed files with 69 additions and 42 deletions
|
|
@ -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`, :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
|
||||
|
|
@ -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::
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -204,6 +219,7 @@ or any other SQLite browser, including the SQLite CLI.
|
|||
|
||||
.. versionadded:: next
|
||||
|
||||
|
||||
:mod:`dbm.gnu` --- GNU database manager
|
||||
---------------------------------------
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -270,14 +291,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.
|
||||
|
||||
A string of characters the *flag* parameter of :meth:`~dbm.gnu.open` supports.
|
||||
.. versionchanged:: 3.2
|
||||
Added the :meth:`!get` and :meth:`!setdefault` methods.
|
||||
|
||||
.. 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
|
||||
|
|
@ -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
|
||||
----------------------------------------
|
||||
|
|
@ -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.
|
||||
|
||||
: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.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
Added the :meth:`!get` and :meth:`!setdefault` methods.
|
||||
|
||||
.. versionchanged:: 3.13
|
||||
Added the :meth:`!clear` method.
|
||||
|
||||
The following method is also provided:
|
||||
|
||||
.. method:: ndbm.close()
|
||||
|
||||
Close the NDBM database.
|
||||
|
||||
.. method:: ndbm.clear()
|
||||
|
||||
Remove all items from the NDBM database.
|
||||
|
||||
.. versionadded:: 3.13
|
||||
|
||||
|
||||
:mod:`dbm.dumb` --- Portable DBM implementation
|
||||
-----------------------------------------------
|
||||
|
|
@ -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).
|
||||
|
|
@ -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:
|
||||
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()
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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`.)
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue