10000 [3.12] Docs: mark up dbm.gnu.open() and dbm.ndbm.open() using param l… · python/cpython@fe5094c · GitHub
[go: up one dir, main page]
Skip to content

Commit fe5094c

Browse files
miss-islingtonerlend-aasland
miss-islington
and
erlend-aasland
authored
[3.12] Docs: mark up dbm.gnu.open() and dbm.ndbm.open() using param list (GH-114762) (#114783)
(cherry picked from commit c8cf5d7) Co-authored-by: Erlend E. Aasland <erlend@python.org>
1 parent 2e8417e commit fe5094c

File tree

1 file changed

+56
-61
lines changed

1 file changed

+56
-61
lines changed

‎Doc/library/dbm.rst

Lines changed: 56 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,10 @@ the Oracle Berkeley DB.
5252
.. |flag_n| replace::
5353
Always create a new, empty database, open for reading and writing.
5454

55+
.. |mode_param_doc| replace::
56+
The Unix file access mode of the file (default: octal ``0o666``),
57+
used only when the database has to be created.
58+
5559
.. |incompat_note| replace::
5660
The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible
5761
and can not be used interchangeably.
@@ -69,14 +73,13 @@ the Oracle Berkeley DB.
6973
:type file: :term:`path-like object`
7074

7175
:param str flag:
72-
* ``'r'`` (default), |flag_r|
73-
* ``'w'``, |flag_w|
74-
* ``'c'``, |flag_c|
75-
* ``'n'``, |flag_n|
76+
* ``'r'`` (default): |flag_r|
77+
* ``'w'``: |flag_w|
78+
* ``'c'``: |flag_c|
79+
* ``'n'``: |flag_n|
7680

7781
:param int mode:
78-
The Unix file access mode of the file (default: octal ``0o666``),
79-
used only when the database has to be created.
82+
|mode_param_doc|
8083

8184
.. versionchanged:: 3.11
8285
*file* accepts a :term:`path-like object`.
@@ -171,47 +174,45 @@ and the :meth:`!items` and :meth:`!values` methods are not supported.
171174

172175
.. function:: open(filename, flag="r", mode=0o666, /)
173176

174-
Open a GDBM database and return a :class:`!gdbm` object. The *filename*
175-
argument is the name of the database file.
176-
177-
The optional *flag* argument can be:
177+
Open a GDBM database and return a :class:`!gdbm` object.
178178

179-
.. csv-table::
180-
:header: "Value", "Meaning"
179+
:param filename:
180+
The database file to open.
181+
:type filename: :term:`path-like object`
181182

182-
``'r'`` (default), |flag_r|
183-
``'w'``, |flag_w|
184-
``'c'``, |flag_c|
185-
``'n'``, |flag_n|
183+
:param str flag:
184+
* ``'r'`` (default): |flag_r|
185+
* ``'w'``: |flag_w|
186+
* ``'c'``: |flag_c|
187+
* ``'n'``: |flag_n|
186188

187-
The following additional characters may be appended to the flag to control
188-
how the database is opened:
189+
The following additional characters may be appended
190+
to control how the database is opened:
189191

190-
+---------+--------------------------------------------+
191-
| Value | Meaning |
192-
+=========+============================================+
193-
| ``'f'`` | Open the database in fast mode. Writes |
194-
| | to the database will not be synchronized. |
195-
+---------+--------------------------------------------+
196-
| ``'s'`` | Synchronized mode. This will cause changes |
197-
| | to the database to be immediately written |
198-
| | to the file. |
199-
+---------+--------------------------------------------+
200-
| ``'u'`` | Do not lock database. |
201-
+---------+--------------------------------------------+
192+
* ``'f'``: Open the database in fast mode.
193+
Writes to the database will not be synchronized.
194+
* ``'s'``: Synchronized mode.
195+
Changes to the database will be written immediately to the file.
196+
* ``'u'``: Do not lock database.
202197

203-
Not all flags are valid for all versions of GDBM. The module constant
204-
:const:`open_flags` is a string of supported flag characters. The exception
205-
:exc:`error` is raised if an invalid flag is specified.
198+
Not all flags are valid for all versions of GDBM.
199+
See the :data:`open_flags` member for a list of supported flag characters.
206200

207-
The optional *mode* argument is the Unix mode of the file, used only when the
208-
database has to be created. It defaults to octal ``0o666``.
201+
:param int mode:
202+
|mode_param_doc|
209203

210-
In addition to the dictionary-like methods, :class:`gdbm` objects have the
211-
following methods:
204+
:raises error:
205+
If an invalid *flag* argument is passed.
212206

213207
.. versionchanged:: 3.11
214-
Accepts :term:`path-like object` for filename.
208+
*filename* accepts a :term:`path-like object`.
209+
210+
.. data:: open_flags
211+
212+
A string of characters the *flag* parameter of :meth:`~dbm.gnu.open` supports.
213+
214+
In addition to the dictionary-like methods, :class:`gdbm` objects have the
215+
following methods and attributes:
215216

216217
.. method:: gdbm.firstkey()
217218

@@ -292,22 +293,20 @@ This module can be used with the "classic" NDBM interface or the
292293
.. function:: open(filename, flag="r", mode=0o666, /)
293294

294295
Open an NDBM database and return an :class:`!ndbm` object.
295-
The *filename* argument is the name of the database file
296-
(without the :file:`.dir` or :file:`.pag` extensions).
297-
298-
The optional *flag* argument must be one of these values:
299296

300-
.. csv-table::
301-
:header: "Value", "Meaning"
297+
:param filename:
298+
The basename of the database file
299+
(without the :file:`.dir` or :file:`.pag` extensions).
300+
:type filename: :term:`path-like object`
302301

303-
``'r'`` (default), |flag_r|
304-
``'w'``, |flag_w|
305-
``'c'``, |flag_c|
306-
``'n'``, |flag_n|
302+
:param str flag:
303+
* ``'r'`` (default): |flag_r|
304+
* ``'w'``: |flag_w|
305+
* ``'c'``: |flag_c|
306+
* ``'n'``: |flag_n|
307307

308-
The optional *mode* argument is the Unix mode of the file, used only when the
309-
database has to be created. It defaults to octal ``0o666`` (and will be
310-
modified by the prevailing umask).
308+
:param int mode:
309+
|mode_param_doc|
311310

312311
In addition to the dictionary-like methods, :class:`!ndbm` objects
313312
provide the following method:
@@ -370,25 +369,21 @@ The :mod:`!dbm.dumb` module defines the following:
370369
:type database: :term:`path-like object`
371370

372371
:param str flag:
373-
.. csv-table::
374-
:header: "Value", "Meaning"
375-
376-
``'r'``, |flag_r|
377-
``'w'``, |flag_w|
378-
``'c'`` (default), |flag_c|
379-
``'n'``, |flag_n|
372+
* ``'r'``: |flag_r|
373+
* ``'w'``: |flag_w|
374+
* ``'c'`` (default): |flag_c|
375+
* ``'n'``: |flag_n|
380376

381377
:param int mode:
382-
The Unix file access mode of the file (default: ``0o666``),
383-
used only when the database has to be created.
378+
|mode_param_doc|
384379

385380
.. warning::
386381
It is possible to crash the Python interpreter when loading a database
387382
with a sufficiently large/complex entry due to stack depth limitations in
388383
Python's AST compiler.
389384

390385
.. versionchanged:: 3.5
391-
:func:`open` always creates a new database when *flag* is ``'n'``.
386+
:func:`~dbm.dumb.open` always creates a new database when *flag* is ``'n'``.
392387

393388
.. versionchanged:: 3.8
394389
A database opened read-only if *flag* is ``'r'``.

0 commit comments

Comments
 (0)
0