mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-30 20:31:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

[3.12] Docs: reword dbm.ndbm introduction (#114549) (#114599)

Browse source 
(cherry picked from commit 4cf068ed08)

- 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
This commit is contained in:
Erlend E. Aasland 2024-01-26 13:56:39 +01:00 • committed by GitHub
parent 4545845d7a
commit 9726cabfb6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 26 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

46
Doc/library/dbm.rst
View file

@ -52,6 +52,10 @@ the Oracle Berkeley DB.
.. |flag_n| replace::
Always create a new, empty database, open for reading and writing.
.. |incompat_note| replace::
The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible
and can not be used interchangeably.
.. function:: open(file, flag='r', mode=0o666)
Open the database file *file* and return a corresponding object.
@ -157,9 +161,7 @@ functionality like crash tolerance.
except that keys and values are always converted to :class:`bytes` before storing,
and the :meth:`!items` and :meth:`!values` methods are not supported.
.. note::
The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are
incompatible and can not be used interchangeably.
.. note:: |incompat_note|
.. exception:: error
@ -246,29 +248,32 @@ and the :meth:`!items` and :meth:`!values` methods are not supported.
Close the GDBM database.
:mod:`dbm.ndbm` --- Interface based on ndbm
-------------------------------------------
:mod:`dbm.ndbm` --- New Database Manager
----------------------------------------
.. module:: dbm.ndbm
:platform: Unix
:synopsis: The standard "database" interface, based on ndbm.
:synopsis: The New Database Manager
**Source code:** :source:`Lib/dbm/ndbm.py`
--------------
The :mod:`dbm.ndbm` module provides an interface to the Unix "(n)dbm" library.
Dbm objects behave like mappings (dictionaries), except that keys and values are
always stored as bytes. Printing a ``dbm`` object doesn't print the keys and
values, and the :meth:`items` and :meth:`values` methods are not supported.
The :mod:`dbm.ndbm` module provides an interface to the
:abbr:`NDBM (New Database Manager)` library.
:class:`!ndbm` objects behave similar to :term:`mappings <mapping>`,
except that keys and values are always stored as :class:`bytes`,
and the :meth:`!items` and :meth:`!values` methods are not supported.
This module can be used with the "classic" ndbm interface or the GNU GDBM
compatibility interface. On Unix, the :program:`configure` script will attempt
to locate the appropriate header file to simplify building this module.
This module can be used with the "classic" NDBM interface or the
:abbr:`GDBM (GNU dbm)` compatibility interface.
.. note:: |incompat_note|
.. warning::
The ndbm library shipped as part of macOS has an undocumented limitation on the
The NDBM library shipped as part of macOS has an undocumented limitation on the
size of values, which can result in corrupted database files
when storing values larger than this limit. Reading such corrupted files can
result in a hard crash (segmentation fault).
@ -281,13 +286,14 @@ to locate the appropriate header file to simplify building this module.
.. data:: library
Name of the ``ndbm`` implementation library used.
Name of the NDBM implementation library used.
.. function:: open(filename[, flag[, mode]])
.. function:: open(filename, flag="r", mode=0o666, /)
Open a dbm database and return a ``ndbm`` object. The *filename* argument is the
name of the database file (without the :file:`.dir` or :file:`.pag` extensions).
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:
@ -303,7 +309,7 @@ to locate the appropriate header file to simplify building this module.
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, ``ndbm`` objects
In addition to the dictionary-like methods, :class:`!ndbm` objects
provide the following method:
.. versionchanged:: 3.11
@ -311,7 +317,7 @@ to locate the appropriate header file to simplify building this module.
.. method:: ndbm.close()
Close the ``ndbm`` database.
Close the NDBM database.
:mod:`dbm.dumb` --- Portable DBM implementation