https://github.com/python/cpython/commit/89015c528c73131dd8026de8af58a870b2a17703
commit: 89015c528c73131dd8026de8af58a870b2a17703
branch: 3.11
author: Erlend E. Aasland <erl...@python.org>
committer: erlend-aasland <erlend.aasl...@protonmail.com>
date: 2024-01-26T13:56:52+01:00
summary:
[3.11] Docs: reword dbm.ndbm introduction (#114549) (#114600)
(cherry picked from commit 4cf068ed0879cccf86a45f06fb274b350b89e911)
- 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
files:
M Doc/library/dbm.rst
diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index f9995982698b21..fc2dcd5c6cc0e1 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.
+.. |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
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
