[3.11] Docs: mark up dbm.gnu.open() and dbm.ndbm.open() using param list (GH-114762...

(cherry picked from commit c8cf5d7d148944f2850f25b02334400dd0238cb0)

Co-authored-by: Erlend E. Aasland <erlend@python.org>

diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index 8f6704da72d59435ff4519c5ba1d615d45925001..413d24461796a20669cdd0a8b66af4f1d3a603b5 100644 (file)
--- a/Doc/library/dbm.rst
+++ b/Doc/library/dbm.rst
@@ -52,6 +52,10 @@ the Oracle Berkeley DB.
 .. |flag_n| replace::
    Always create a new, empty database, open for reading and writing.
 
+.. |mode_param_doc| replace::
+   The Unix file access mode of the file (default: octal ``0o666``),
+   used only when the database has to be created.
+
 .. |incompat_note| replace::
    The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible
    and can not be used interchangeably.
@@ -69,14 +73,13 @@ the Oracle Berkeley DB.
    :type file: :term:`path-like object`
 
    :param str flag:
-      * ``'r'`` (default), |flag_r|
-      * ``'w'``, |flag_w|
-      * ``'c'``, |flag_c|
-      * ``'n'``, |flag_n|
+      * ``'r'`` (default): |flag_r|
+      * ``'w'``: |flag_w|
+      * ``'c'``: |flag_c|
+      * ``'n'``: |flag_n|
 
    :param int mode:
-      The Unix file access mode of the file (default: octal ``0o666``),
-      used only when the database has to be created.
+      |mode_param_doc|
 
    .. versionchanged:: 3.11
       *file* accepts a :term:`path-like object`.
@@ -171,47 +174,45 @@ and the :meth:`!items` and :meth:`!values` methods are not supported.
 
 .. function:: open(filename, flag="r", mode=0o666, /)
 
-   Open a GDBM database and return a :class:`!gdbm` object.  The *filename*
-   argument is the name of the database file.
-
-   The optional *flag* argument can be:
+   Open a GDBM database and return a :class:`!gdbm` object.
 
-   .. csv-table::
-      :header: "Value", "Meaning"
+   :param filename:
+      The database file to open.
+   :type filename: :term:`path-like object`
 
-      ``'r'`` (default), |flag_r|
-      ``'w'``, |flag_w|
-      ``'c'``, |flag_c|
-      ``'n'``, |flag_n|
+   :param str flag:
+      * ``'r'`` (default): |flag_r|
+      * ``'w'``: |flag_w|
+      * ``'c'``: |flag_c|
+      * ``'n'``: |flag_n|
 
-   The following additional characters may be appended to the flag to control
-   how the database is opened:
+      The following additional characters may be appended
+      to control how the database is opened:
 
-   +---------+--------------------------------------------+
-   | Value   | Meaning                                    |
-   +=========+============================================+
-   | ``'f'`` | Open the database in fast mode.  Writes    |
-   |         | to the database will not be synchronized.  |
-   +---------+--------------------------------------------+
-   | ``'s'`` | Synchronized mode. This will cause changes |
-   |         | to the database to be immediately written  |
-   |         | to the file.                               |
-   +---------+--------------------------------------------+
-   | ``'u'`` | Do not lock database.                      |
-   +---------+--------------------------------------------+
+      * ``'f'``: Open the database in fast mode.
+        Writes to the database will not be synchronized.
+      * ``'s'``: Synchronized mode.
+        Changes to the database will be written immediately to the file.
+      * ``'u'``: Do not lock database.
 
-   Not all flags are valid for all versions of GDBM.  The module constant
-   :const:`open_flags` is a string of supported flag characters.  The exception
-   :exc:`error` is raised if an invalid flag is specified.
+      Not all flags are valid for all versions of GDBM.
+      See the :data:`open_flags` member for a list of supported flag characters.
 
-   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``.
+   :param int mode:
+      |mode_param_doc|
 
-   In addition to the dictionary-like methods, :class:`gdbm` objects have the
-   following methods:
+   :raises error:
+      If an invalid *flag* argument is passed.
 
    .. versionchanged:: 3.11
-      Accepts :term:`path-like object` for filename.
+      *filename* accepts a :term:`path-like object`.
+
+   .. data:: open_flags
+
+      A string of characters the *flag* parameter of :meth:`~dbm.gnu.open` supports.
+
+   In addition to the dictionary-like methods, :class:`gdbm` objects have the
+   following methods and attributes:
 
    .. method:: gdbm.firstkey()
 
@@ -292,22 +293,20 @@ This module can be used with the "classic" NDBM interface or the
 .. function:: open(filename, flag="r", mode=0o666, /)
 
    Open an NDBM database and return an :class:`!ndbm` object.
-   The *filename* argument is the name of the database file
-   (without the :file:`.dir` or :file:`.pag` extensions).
-
-   The optional *flag* argument must be one of these values:
 
-   .. csv-table::
-      :header: "Value", "Meaning"
+   :param filename:
+      The basename of the database file
+      (without the :file:`.dir` or :file:`.pag` extensions).
+   :type filename: :term:`path-like object`
 
-      ``'r'`` (default), |flag_r|
-      ``'w'``, |flag_w|
-      ``'c'``, |flag_c|
-      ``'n'``, |flag_n|
+   :param str flag:
+      * ``'r'`` (default): |flag_r|
+      * ``'w'``: |flag_w|
+      * ``'c'``: |flag_c|
+      * ``'n'``: |flag_n|
 
-   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).
+   :param int mode:
+      |mode_param_doc|
 
    In addition to the dictionary-like methods, :class:`!ndbm` objects
    provide the following method:
@@ -370,17 +369,13 @@ The :mod:`!dbm.dumb` module defines the following:
    :type database: :term:`path-like object`
 
    :param str flag:
-      .. csv-table::
-         :header: "Value", "Meaning"
-
-         ``'r'``, |flag_r|
-         ``'w'``, |flag_w|
-         ``'c'`` (default), |flag_c|
-         ``'n'``, |flag_n|
+      * ``'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.
+      |mode_param_doc|
 
    .. warning::
       It is possible to crash the Python interpreter when loading a database
@@ -388,7 +383,7 @@ The :mod:`!dbm.dumb` module defines the following:
       Python's AST compiler.
 
    .. versionchanged:: 3.5
-      :func:`open` always creates a new database when *flag* is ``'n'``.
+      :func:`~dbm.dumb.open` always creates a new database when *flag* is ``'n'``.
 
    .. versionchanged:: 3.8
       A database opened read-only if *flag* is ``'r'``.