https://github.com/python/cpython/commit/fe5094c65f3a2f25b7023c3da78a4f9c74f... commit: fe5094c65f3a2f25b7023c3da78a4f9c74f02796 branch: 3.12 author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> committer: erlend-aasland <erlend.aasland@protonmail.com> date: 2024-01-31T07:06:13Z summary: [3.12] Docs: mark up dbm.gnu.open() and dbm.ndbm.open() using param list (GH-114762) (#114783) (cherry picked from commit c8cf5d7d148944f2850f25b02334400dd0238cb0) Co-authored-by: Erlend E. Aasland <erlend@python.org> files: M Doc/library/dbm.rst diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst index 8f6704da72d594..413d24461796a2 100644 --- 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'``.