From af10bc1cce0197727a38482c3ab34cda703c396a Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 23 Jan 2024 20:54:44 +0100 Subject: [PATCH] Docs: use placeholders in dbm flag param docs (GH-114482) Also correct the default flag param for dbm.dumb.open(); it's 'c', not 'r'. (cherry picked from commit 8c265408c51609c6b4a6788cac9cc5fea7a14888) Co-authored-by: Erlend E. Aasland --- Doc/library/dbm.rst | 103 ++++++++++++++++++-------------------------- 1 file changed, 43 insertions(+), 60 deletions(-) diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst index 8b799ad6cb57fd..bc72f0f76ac2e2 100644 --- a/Doc/library/dbm.rst +++ b/Doc/library/dbm.rst @@ -36,6 +36,21 @@ the Oracle Berkeley DB. .. versionchanged:: 3.11 Accepts :term:`path-like object` for filename. +.. Substitutions for the open() flag param docs; + all submodules use the same text. + +.. |flag_r| replace:: + Open existing database for reading only. + +.. |flag_w| replace:: + Open existing database for reading and writing. + +.. |flag_c| replace:: + Open database for reading and writing, creating it if it doesn't exist. + +.. |flag_n| replace:: + Always create a new, empty database, open for reading and writing. + .. function:: open(file, flag='r', mode=0o666) Open the database file *file* and return a corresponding object. @@ -46,21 +61,13 @@ the Oracle Berkeley DB. The optional *flag* argument can be: - +---------+-------------------------------------------+ - | Value | Meaning | - +=========+===========================================+ - | ``'r'`` | Open existing database for reading only | - | | (default) | - +---------+-------------------------------------------+ - | ``'w'`` | Open existing database for reading and | - | | writing | - +---------+-------------------------------------------+ - | ``'c'`` | Open database for reading and writing, | - | | creating it if it doesn't exist | - +---------+-------------------------------------------+ - | ``'n'`` | Always create a new, empty database, open | - | | for reading and writing | - +---------+-------------------------------------------+ + .. csv-table:: + :header: "Value", "Meaning" + + ``'r'`` (default), |flag_r| + ``'w'``, |flag_w| + ``'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 @@ -165,21 +172,13 @@ supported. The optional *flag* argument can be: - +---------+-------------------------------------------+ - | Value | Meaning | - +=========+===========================================+ - | ``'r'`` | Open existing database for reading only | - | | (default) | - +---------+-------------------------------------------+ - | ``'w'`` | Open existing database for reading and | - | | writing | - +---------+-------------------------------------------+ - | ``'c'`` | Open database for reading and writing, | - | | creating it if it doesn't exist | - +---------+-------------------------------------------+ - | ``'n'`` | Always create a new, empty database, open | - | | for reading and writing | - +---------+-------------------------------------------+ + .. csv-table:: + :header: "Value", "Meaning" + + ``'r'`` (default), |flag_r| + ``'w'``, |flag_w| + ``'c'``, |flag_c| + ``'n'``, |flag_n| The following additional characters may be appended to the flag to control how the database is opened: @@ -290,21 +289,13 @@ to locate the appropriate header file to simplify building this module. The optional *flag* argument must be one of these values: - +---------+-------------------------------------------+ - | Value | Meaning | - +=========+===========================================+ - | ``'r'`` | Open existing database for reading only | - | | (default) | - +---------+-------------------------------------------+ - | ``'w'`` | Open existing database for reading and | - | | writing | - +---------+-------------------------------------------+ - | ``'c'`` | Open database for reading and writing, | - | | creating it if it doesn't exist | - +---------+-------------------------------------------+ - | ``'n'`` | Always create a new, empty database, open | - | | for reading and writing | - +---------+-------------------------------------------+ + .. csv-table:: + :header: "Value", "Meaning" + + ``'r'`` (default), |flag_r| + ``'w'``, |flag_w| + ``'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 @@ -363,21 +354,13 @@ The module defines the following: The optional *flag* argument can be: - +---------+-------------------------------------------+ - | Value | Meaning | - +=========+===========================================+ - | ``'r'`` | Open existing database for reading only | - | | (default) | - +---------+-------------------------------------------+ - | ``'w'`` | Open existing database for reading and | - | | writing | - +---------+-------------------------------------------+ - | ``'c'`` | Open database for reading and writing, | - | | creating it if it doesn't exist | - +---------+-------------------------------------------+ - | ``'n'`` | Always create a new, empty database, open | - | | for reading and writing | - +---------+-------------------------------------------+ + .. csv-table:: + :header: "Value", "Meaning" + + ``'r'``, |flag_r| + ``'w'``, |flag_w| + ``'c'`` (default), |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