Skip to content

Commit 095a88d

Browse files
erlend-aaslandaisk
authored andcommitted
Docs: rework the dbm.dumb introduction (python#114550)
- consistently use correct parameter markup - consistently use submodule name as database name - improve accuracy of the dbm.dumb.open() spec - remove dumbdbm class refs and replace them with generic "database object" - use parameter list for dbm.dumb.open()
1 parent f8d8361 commit 095a88d

File tree

1 file changed

+36
-30
lines changed

1 file changed

+36
-30
lines changed

Doc/library/dbm.rst

Lines changed: 36 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -351,61 +351,67 @@ This module can be used with the "classic" NDBM interface or the
351351

352352
--------------
353353

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

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

362363
.. exception:: error
363364

364365
Raised on :mod:`dbm.dumb`-specific errors, such as I/O errors. :exc:`KeyError` is
365366
raised for general mapping errors like specifying an incorrect key.
366367

367368

368-
.. function:: open(filename[, flag[, mode]])
369+
.. function:: open(filename, flag="c", mode=0o666)
369370

370-
Open a ``dumbdbm`` database and return a dumbdbm object. The *filename* argument is
371-
the basename of the database file (without any specific extensions). When a
372-
dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions
373-
are created.
371+
Open a :mod:`!dbm.dumb` database.
372+
The returned database object behaves similar to a :term:`mapping`,
373+
in addition to providing :meth:`~dumbdbm.sync` and :meth:`~dumbdbm.close`
374+
methods.
374375

375-
The optional *flag* argument can be:
376+
:param filename:
377+
The basename of the database file (without extensions).
378+
A new database creates the following files:
376379

377-
.. csv-table::
378-
:header: "Value", "Meaning"
380+
- :file:`{filename}.dat`
381+
- :file:`{filename}.dir`
382+
:type database: :term:`path-like object`
379383

380-
``'r'``, |flag_r|
381-
``'w'``, |flag_w|
382-
``'c'`` (default), |flag_c|
383-
``'n'``, |flag_n|
384+
:param str flag:
385+
.. csv-table::
386+
:header: "Value", "Meaning"
384387

385-
The optional *mode* argument is the Unix mode of the file, used only when the
386-
database has to be created. It defaults to octal ``0o666`` (and will be modified
387-
by the prevailing umask).
388+
``'r'``, |flag_r|
389+
``'w'``, |flag_w|
390+
``'c'`` (default), |flag_c|
391+
``'n'``, |flag_n|
392+
393+
:param int mode:
394+
The Unix file access mode of the file (default: ``0o666``),
395+
used only when the database has to be created.
388396

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

394402
.. versionchanged:: 3.5
395-
:func:`.open` always creates a new database when the flag has the value
396-
``'n'``.
403+
:func:`open` always creates a new database when *flag* is ``'n'``.
397404

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

403409
.. versionchanged:: 3.11
404-
Accepts :term:`path-like object` for filename.
410+
*filename* accepts a :term:`path-like object`.
405411

406412
In addition to the methods provided by the
407-
:class:`collections.abc.MutableMapping` class, :class:`dumbdbm` objects
408-
provide the following methods:
413+
:class:`collections.abc.MutableMapping` class,
414+
the following methods are provided:
409415

410416
.. method:: dumbdbm.sync()
411417

@@ -414,5 +420,5 @@ The module defines the following:
414420

415421
.. method:: dumbdbm.close()
416422

417-
Close the ``dumbdbm`` database.
423+
Close the database.
418424

0 commit comments

Comments
 (0)