mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-27 02:39:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

Docs: mark up dbm.gnu.open() and dbm.ndbm.open() using param list (#114762)

Browse source
This commit is contained in:
Erlend E. Aasland 2024-01-31 07:59:34 +01:00 • committed by GitHub
parent 2ed8f924ee
commit c8cf5d7d14
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 56 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

117
Doc/library/dbm.rst
View file

@ -52,6 +52,10 @@ the Oracle Berkeley DB.
.. |flag_n| replace:: .. |flag_n| replace::
Always create a new, empty database, open for reading and writing. 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:: .. |incompat_note| replace::
The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible
and can not be used interchangeably. and can not be used interchangeably.
@ -69,14 +73,13 @@ the Oracle Berkeley DB.
:type file: :term:`path-like object` :type file: :term:`path-like object`
:param str flag: :param str flag:
* ``'r'`` (default), |flag_r| * ``'r'`` (default): |flag_r|
* ``'w'``, |flag_w| * ``'w'``: |flag_w|
* ``'c'``, |flag_c| * ``'c'``: |flag_c|
* ``'n'``, |flag_n| * ``'n'``: |flag_n|
:param int mode: :param int mode:
The Unix file access mode of the file (default: octal ``0o666``), |mode_param_doc|
used only when the database has to be created.
.. versionchanged:: 3.11 .. versionchanged:: 3.11
*file* accepts a :term:`path-like object`. *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, /) .. function:: open(filename, flag="r", mode=0o666, /)
Open a GDBM database and return a :class:`!gdbm` object. The *filename* Open a GDBM database and return a :class:`!gdbm` object.
argument is the name of the database file.
The optional *flag* argument can be: :param filename:
The database file to open.
:type filename: :term:`path-like object`
.. csv-table:: :param str flag:
:header: "Value", "Meaning" * ``'r'`` (default): |flag_r|
* ``'w'``: |flag_w|
* ``'c'``: |flag_c|
* ``'n'``: |flag_n|
``'r'`` (default), |flag_r| The following additional characters may be appended
``'w'``, |flag_w| to control how the database is opened:
``'c'``, |flag_c|
``'n'``, |flag_n|
The following additional characters may be appended to the flag to control * ``'f'``: Open the database in fast mode.
how the database is opened: 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.
| Value | Meaning | See the :data:`open_flags` member for a list of supported flag characters.
+=========+============================================+
| ``'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. |
+---------+--------------------------------------------+
Not all flags are valid for all versions of GDBM. The module constant :param int mode:
:const:`open_flags` is a string of supported flag characters. The exception |mode_param_doc|
:exc:`error` is raised if an invalid flag is specified.
The optional *mode* argument is the Unix mode of the file, used only when the :raises error:
database has to be created. It defaults to octal ``0o666``. If an invalid *flag* argument is passed.
In addition to the dictionary-like methods, :class:`gdbm` objects have the
following methods:
.. versionchanged:: 3.11 .. 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() .. method:: gdbm.firstkey()
@ -298,22 +299,20 @@ This module can be used with the "classic" NDBM interface or the
.. function:: open(filename, flag="r", mode=0o666, /) .. function:: open(filename, flag="r", mode=0o666, /)
Open an NDBM database and return an :class:`!ndbm` object. 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: :param filename:
The basename of the database file
(without the :file:`.dir` or :file:`.pag` extensions).
:type filename: :term:`path-like object`
.. csv-table:: :param str flag:
:header: "Value", "Meaning" * ``'r'`` (default): |flag_r|
* ``'w'``: |flag_w|
* ``'c'``: |flag_c|
* ``'n'``: |flag_n|
``'r'`` (default), |flag_r| :param int mode:
``'w'``, |flag_w| |mode_param_doc|
``'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).
In addition to the dictionary-like methods, :class:`!ndbm` objects In addition to the dictionary-like methods, :class:`!ndbm` objects
provide the following method: provide the following method:
@ -382,17 +381,13 @@ The :mod:`!dbm.dumb` module defines the following:
:type database: :term:`path-like object` :type database: :term:`path-like object`
:param str flag: :param str flag:
.. csv-table:: * ``'r'``: |flag_r|
:header: "Value", "Meaning" * ``'w'``: |flag_w|
* ``'c'`` (default): |flag_c|
``'r'``, |flag_r| * ``'n'``: |flag_n|
``'w'``, |flag_w|
``'c'`` (default), |flag_c|
``'n'``, |flag_n|
:param int mode: :param int mode:
The Unix file access mode of the file (default: ``0o666``), |mode_param_doc|
used only when the database has to be created.
.. warning:: .. warning::
It is possible to crash the Python interpreter when loading a database It is possible to crash the Python interpreter when loading a database
@ -400,7 +395,7 @@ The :mod:`!dbm.dumb` module defines the following:
Python's AST compiler. Python's AST compiler.
.. versionchanged:: 3.5 .. 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 .. versionchanged:: 3.8
A database opened read-only if *flag* is ``'r'``. A database opened read-only if *flag* is ``'r'``.