10000 [3.12] Docs: rework the dbm.dumb introduction (GH-114550) by miss-islington · Pull Request #114620 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

[3.12] Docs: rework the dbm.dumb introduction (GH-114550) #114620

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: rework the dbm.dumb introduction (GH-114550) #114620

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
8000
Diff view
66 changes: 36 additions & 30 deletions Doc/library/dbm.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -339,61 +339,67 @@ This module can be used with the "classic" NDBM interface or the

--------------

The :mod:`dbm.dumb` module provides a persistent dictionary-like interface which
is written entirely in Python. Unlike other modules such as :mod:`dbm.gnu` no
external library is required. As with other persistent mappings, the keys and
values are always stored as bytes.

The module defines the following:
The :mod:`dbm.dumb` module provides a persistent :class:`dict`-like
interface which is written entirely in Python.
Unlike other :mod:`dbm` backends, such as :mod:`dbm.gnu`, no
external library is required.
As with other :mod:`dbm` backends,
the keys and values are always stored as :class:`bytes`.

The :mod:`!dbm.dumb` module defines the following:

.. exception:: error

Raised on :mod:`dbm.dumb`-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="c", mode=0o666)

Open a ``dumbdbm`` database and return a dumbdbm object. The *filename* argument is
the basename of the database file (without any specific extensions). When a
dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions
are created.
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.

The optional *flag* argument can be:
:param filename:
The basename of the database file (without extensions).
A new database creates the following files:

.. csv-table::
:header: "Value", "Meaning"
- :file:`{filename}.dat`
- :file:`{filename}.dir`
:type database: :term:`path-like object`

``'r'``, |flag_r|
``'w'``, |flag_w|
``'c'`` (default), |flag_c|
``'n'``, |flag_n|
:param str flag:
.. csv-table::
:header: "Value", "Meaning"

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`` (and will be modified
by the prevailing umask).
``'r'``, |flag_r|
``'w'``, |flag_w|
``'c'`` (default), |flag_c|
``'n'``, |flag_n|

:param int mode:
The Unix file access mode of the file (default: ``0o666``),
used only when the database has to be created.

.. warning::
It is possible to crash the Python interpreter when loading a database
with a sufficiently large/complex entry due to stack depth limitations in
Python's AST compiler.

.. versionchanged:: 3.5
:func:`.open` always creates a new database when the flag has the value
``'n'``.
:func:`open` always creates a new database when *flag* is ``'n'``.

.. versionchanged:: 3.8
A database opened with flags ``'r'`` is now read-only. Opening with
flags ``'r'`` and ``'w'`` no longer creates a database if it does not
exist.
A database opened read-only if *flag* is ``'r'``.
A database is not created if it does not exist if *flag* is ``'r'`` or ``'w'``.

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

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

.. method:: dumbdbm.sync()

Expand All @@ -402,5 +408,5 @@ The module defines the following:

.. method:: dumbdbm.close()

Close the ``dumbdbm`` database.
Close the database.

0