From 4ed1d90901ed0ded104e05afbdb4afae0312606f Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 23 Jan 2024 14:02:43 +0100 Subject: [PATCH 1/3] Docs: use placeholders in dbm flag param docs Also correct the default flag param for dbm.dumb.open() --- Doc/library/dbm.rst | 153 +++++++++++++++++++++++--------------------- 1 file changed, 81 insertions(+), 72 deletions(-) diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst index cb95c61322582f..a1a8b4bc8950ac 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,20 @@ 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 | - +---------+-------------------------------------------+ + .. list-table:: + :header-rows: 1 + + * - 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,37 +179,36 @@ 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 | - +---------+-------------------------------------------+ + .. list-table:: + :header-rows: 1 + + * - 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: - +---------+--------------------------------------------+ - | Value | Meaning | - +=========+============================================+ - | ``'f'`` | Open the database in fast mode. Writes | - | | to the database will not be synchronized. | - +---------+--------------------------------------------+ - | ``'s'`` | Synchronized mode. This will cause changes | - | | to the database to be immediately written | - | | to the file. | - +---------+--------------------------------------------+ - | ``'u'`` | Do not lock database. | - +---------+--------------------------------------------+ + .. list-table:: + :header-rows: 1 + + * - Value + - Meaning + * - ``'f'`` + - Open the database in fast mode. + Writes to the database will not be synchronized. + * - ``'s'`` + - Synchronized mode. + Changes to the database to be immediately written to the file. + * - ``'u'`` + - Do not lock the database. Not all flags are valid for all versions of ``gdbm``. The module constant :const:`open_flags` is a string of supported flag characters. The exception @@ -297,21 +310,19 @@ 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 | - +---------+-------------------------------------------+ + .. list-table:: + :header-rows: 1 + + * - 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 @@ -376,21 +387,19 @@ 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 | - +---------+-------------------------------------------+ + .. list-table:: + :header-rows: 1 + + * - 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 From 6ecdc37a1394c64a49d48590da7853aa1fc080bd Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 23 Jan 2024 14:16:22 +0100 Subject: [PATCH 2/3] Remove unrelated change; use csv-table for improved readability --- Doc/library/dbm.rst | 99 +++++++++++++++++---------------------------- 1 file changed, 37 insertions(+), 62 deletions(-) diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst index a1a8b4bc8950ac..30fbf6f76ca6e3 100644 --- a/Doc/library/dbm.rst +++ b/Doc/library/dbm.rst @@ -61,19 +61,13 @@ the Oracle Berkeley DB. The optional *flag* argument can be: - .. list-table:: - :header-rows: 1 + .. csv-table:: + :header: "Value", "Meaning" - * - Value - - Meaning - * - ``'r'`` (default) - - |flag_r| - * - ``'w'`` - - |flag_w| - * - ``'c'`` - - |flag_c| - * - ``'n'`` - - |flag_n| + ``'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 @@ -179,36 +173,29 @@ supported. The optional *flag* argument can be: - .. list-table:: - :header-rows: 1 + .. csv-table:: + :header: "Value", "Meaning" - * - Value - - Meaning - * - ``'r'`` (default) - - |flag_r| - * - ``'w'`` - - |flag_w| - * - ``'c'`` - - |flag_c| - * - ``'n'`` - - |flag_n| + ``'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: - .. list-table:: - :header-rows: 1 - - * - Value - - Meaning - * - ``'f'`` - - Open the database in fast mode. - Writes to the database will not be synchronized. - * - ``'s'`` - - Synchronized mode. - Changes to the database to be immediately written to the file. - * - ``'u'`` - - Do not lock the database. + +---------+--------------------------------------------+ + | Value | Meaning | + +=========+============================================+ + | ``'f'`` | Open the database in fast mode. Writes | + | | to the database will not be synchronized. | + +---------+--------------------------------------------+ + | ``'s'`` | Synchronized mode. This will cause changes | + | | to the database to be immediately written | + | | to the file. | + +---------+--------------------------------------------+ + | ``'u'`` | Do not lock database. | + +---------+--------------------------------------------+ Not all flags are valid for all versions of ``gdbm``. The module constant :const:`open_flags` is a string of supported flag characters. The exception @@ -310,19 +297,13 @@ to locate the appropriate header file to simplify building this module. The optional *flag* argument must be one of these values: - .. list-table:: - :header-rows: 1 + .. csv-table:: + :header: "Value", "Meaning" - * - Value - - Meaning - * - ``'r'`` (default) - - |flag_r| - * - ``'w'`` - - |flag_w| - * - ``'c'`` - - |flag_c| - * - ``'n'`` - - |flag_n| + ``'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 @@ -387,19 +368,13 @@ The module defines the following: The optional *flag* argument can be: - .. list-table:: - :header-rows: 1 - - * - Value - - Meaning - * - ``'r'`` - - |flag_r| - * - ``'w'`` - - |flag_w| - * - ``'c'`` (default) - - |flag_c| - * - ``'n'`` - - |flag_n| + .. 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 From 3f920bedc9bbfed6492f2f6d9b4ac39379ca5777 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 23 Jan 2024 14:22:35 +0100 Subject: [PATCH 3/3] Newline --- Doc/library/dbm.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst index 30fbf6f76ca6e3..eca1c25602a018 100644 --- a/Doc/library/dbm.rst +++ b/Doc/library/dbm.rst @@ -69,7 +69,6 @@ the Oracle Berkeley DB. ``'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 modified by the prevailing umask).