Skip to content

Commit 4445822

Browse files
Address Serhiy's initial round of review
- Don't use "dumbdbm" as a database name; instead use the submodule name - Don't use a class name; only talk about "database objects" - Consistently use correct markup for parameters - Use param list for open()
1 parent 081a228 commit 4445822

File tree

1 file changed

+27
-24
lines changed

1 file changed

+27
-24
lines changed

Doc/library/dbm.rst

Lines changed: 27 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -350,7 +350,7 @@ The :mod:`dbm.dumb` module provides a persistent :class:`dict`-like
350350
interface which is written entirely in Python.
351351
Unlike other :mod:`dbm` backends, such as :mod:`dbm.gnu` no
352352
external library is required.
353-
As with other persistent :term:`mappings <mapping>`,
353+
As with other :mod:`dbm` backends,
354354
the keys and values are always stored as :class:`bytes`.
355355

356356
The :mod:`!dbm.dumb` module defines the following:
@@ -363,46 +363,49 @@ The :mod:`!dbm.dumb` module defines the following:
363363

364364
.. function:: open(filename, flag="c", mode=0o666)
365365

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

372-
The optional *flag* argument can be:
371+
:param filename:
372+
The basename of the database file (without extensions).
373+
A new database creates the following files:
374+
- :samp:`{filename}.dat`
375+
- :samp:`{filename}.dir`
376+
:type database: :term:`path-like object`
373377

374-
.. csv-table::
375-
:header: "Value", "Meaning"
378+
:param str flag:
379+
.. csv-table::
380+
:header: "Value", "Meaning"
376381

377-
``'r'``, |flag_r|
378-
``'w'``, |flag_w|
379-
``'c'`` (default), |flag_c|
380-
``'n'``, |flag_n|
382+
``'r'``, |flag_r|
383+
``'w'``, |flag_w|
384+
``'c'`` (default), |flag_c|
385+
``'n'``, |flag_n|
381386

382-
The optional *mode* argument is the Unix mode of the file, used only when the
383-
database has to be created. It defaults to octal ``0o666`` (and will be modified
384-
by the prevailing umask).
387+
:param int mode:
388+
The Unix file access mode of the file (default: ``0o666``),
389+
used only when the database has to be created.
385390

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

391396
.. versionchanged:: 3.5
392-
:func:`open` always creates a new database when the flag has the value
393-
``'n'``.
397+
:func:`open` always creates a new database when *flag* is ``'n'``.
394398

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

400403
.. versionchanged:: 3.11
401-
Accepts :term:`path-like object` for filename.
404+
*filename* accepts a :term:`path-like object`.
402405

403406
In addition to the methods provided by the
404-
:class:`collections.abc.MutableMapping` class, :class:`!dumbdbm` objects
405-
provide the following methods:
407+
:class:`collections.abc.MutableMapping` class,
408+
the following methods are provided:
406409

407410
.. method:: dumbdbm.sync()
408411

0 commit comments

Comments
 (0)