Skip to content

Commit 4cf068e

Browse files
Docs: reword dbm.ndbm introduction (#114549)
- add abbreviation directives for NDBM and GDBM - consistently spell NDBM as NDBM - silence broken ndbm class refs - improve accuracy of dbm.ndbm.open() spec - use replacement text for NDBM/GDBM file format incompatibility note
1 parent 65cf5dc commit 4cf068e

File tree

1 file changed

+26
-21
lines changed

1 file changed

+26
-21
lines changed

Doc/library/dbm.rst

Lines changed: 26 additions & 21 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+
.. |incompat_note| replace::
56+
The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible
57+
and can not be used interchangeably.
58+
5559
.. function:: open(file, flag='r', mode=0o666)
5660

5761
Open the database file *file* and return a corresponding object.
@@ -157,9 +161,7 @@ functionality like crash tolerance.
157161
except that keys and values are always converted to :class:`bytes` before storing,
158162
and the :meth:`!items` and :meth:`!values` methods are not supported.
159163

160-
.. note::
161-
The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are
162-
incompatible and can not be used interchangeably.
164+
.. note:: |incompat_note|
163165

164166
.. exception:: error
165167

@@ -253,29 +255,31 @@ and the :meth:`!items` and :meth:`!values` methods are not supported.
253255
.. versionadded:: 3.13
254256

255257

256-
:mod:`dbm.ndbm` --- Interface based on ndbm
257-
-------------------------------------------
258+
:mod:`dbm.ndbm` --- New Database Manager
259+
----------------------------------------
258260

259261
.. module:: dbm.ndbm
260262
:platform: Unix
261-
:synopsis: The standard "database" interface, based on ndbm.
263+
:synopsis: The New Database Manager
262264

263265
**Source code:** :source:`Lib/dbm/ndbm.py`
264266

265267
--------------
266268

267-
The :mod:`dbm.ndbm` module provides an interface to the Unix "(n)dbm" library.
268-
Dbm objects behave like mappings (dictionaries), except that keys and values are
269-
always stored as bytes. Printing a ``dbm`` object doesn't print the keys and
270-
values, and the :meth:`items` and :meth:`values` methods are not supported.
269+
The :mod:`dbm.ndbm` module provides an interface to the
270+
:abbr:`NDBM (New Database Manager)` library.
271+
:class:`!ndbm` objects behave similar to :term:`mappings <mapping>`,
272+
except that keys and values are always stored as :class:`bytes`,
273+
and the :meth:`!items` and :meth:`!values` methods are not supported.
274+
275+
This module can be used with the "classic" NDBM interface or the
276+
:abbr:`GDBM (GNU dbm)` compatibility interface.
271277

272-
This module can be used with the "classic" ndbm interface or the GNU GDBM
273-
compatibility interface. On Unix, the :program:`configure` script will attempt
274-
to locate the appropriate header file to simplify building this module.
278+
.. note:: |incompat_note|
275279

276280
.. warning::
277281

278-
The ndbm library shipped as part of macOS has an undocumented limitation on the
282+
The NDBM library shipped as part of macOS has an undocumented limitation on the
279283
size of values, which can result in corrupted database files
280284
when storing values larger than this limit. Reading such corrupted files can
281285
result in a hard crash (segmentation fault).
@@ -288,13 +292,14 @@ to locate the appropriate header file to simplify building this module.
288292

289293
.. data:: library
290294

291-
Name of the ``ndbm`` implementation library used.
295+
Name of the NDBM implementation library used.
292296

293297

294-
.. function:: open(filename[, flag[, mode]])
298+
.. function:: open(filename, flag="r", mode=0o666, /)
295299

296-
Open a dbm database and return a ``ndbm`` object. The *filename* argument is the
297-
name of the database file (without the :file:`.dir` or :file:`.pag` extensions).
300+
Open an NDBM database and return an :class:`!ndbm` object.
301+
The *filename* argument is the name of the database file
302+
(without the :file:`.dir` or :file:`.pag` extensions).
298303

299304
The optional *flag* argument must be one of these values:
300305

@@ -310,19 +315,19 @@ to locate the appropriate header file to simplify building this module.
310315
database has to be created. It defaults to octal ``0o666`` (and will be
311316
modified by the prevailing umask).
312317

313-
In addition to the dictionary-like methods, ``ndbm`` objects
318+
In addition to the dictionary-like methods, :class:`!ndbm` objects
314319
provide the following method:
315320

316321
.. versionchanged:: 3.11
317322
Accepts :term:`path-like object` for filename.
318323

319324
.. method:: ndbm.close()
320325

321-
Close the ``ndbm`` database.
326+
Close the NDBM database.
322327

323328
.. method:: ndbm.clear()
324329

325-
Remove all items from the ``ndbm`` database.
330+
Remove all items from the NDBM database.
326331

327332
.. versionadded:: 3.13
328333

0 commit comments

Comments
 (0)