From 573576396bd02d8948622aa81069c3093ec71caa Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 22 Jul 2023 01:13:13 +0200 Subject: [PATCH 01/16] Docs: Argument Clinic: Restructure "Basic concepts and usage" Split "Basic concepts and usage" into: - Reference - Terminology - CLI reference - Background - Basic concepts --- Doc/howto/clinic.rst | 169 +++++++++++++++++++++++++++++++------------ 1 file changed, 124 insertions(+), 45 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index f6bf1d2234f88d..5b22c791aeefc0 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -8,6 +8,7 @@ Argument Clinic How-To :author: Larry Hastings +**Source code:** :source:`Tools/clinic/clinic.py`. .. topic:: Abstract @@ -15,10 +16,12 @@ Argument Clinic How-To Its purpose is to automate all the boilerplate involved with writing argument parsing code for "builtins", module level functions, and class methods. - This document is divided in three major sections: + This document is divided in four major sections: * :ref:`clinic-background` talks about the basic concepts and goals of Argument Clinic. + * :ref:`clinic-reference` describes the command-line interface and Argument + Clinic terminology. * :ref:`clinic-tutorial` guides you through all the steps required to adapt an existing C function to Argument Clinic. * :ref:`clinic-howtos` details how to handle specific tasks. @@ -93,67 +96,143 @@ and it should be able to do many interesting and smart things with all the information you give it. -Basic concepts and usage ------------------------- +Basic concepts +-------------- -Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic.py``. -If you run that script, specifying a C file as an argument: +When Argument Clinic is run on a file, either via the :ref:`clinic-cli` +or via ``make clinic``, it will scan over the input files looking for +:term:`start lines `: -.. code-block:: shell-session - - $ python Tools/clinic/clinic.py foo.c - -Argument Clinic will scan over the file looking for lines that -look exactly like this: - -.. code-block:: none +.. code-block:: c /*[clinic input] -When it finds one, it reads everything up to a line that looks -exactly like this: +When it finds one, it reads everything up to the :term:`end line`: -.. code-block:: none +.. code-block:: c [clinic start generated code]*/ -Everything in between these two lines is input for Argument Clinic. -All of these lines, including the beginning and ending comment -lines, are collectively called an Argument Clinic "block". - -When Argument Clinic parses one of these blocks, it -generates output. This output is rewritten into the C file -immediately after the block, followed by a comment containing a checksum. -The Argument Clinic block now looks like this: +Everything in between these two lines is Argument Clinic :term:`input`. +When Argument Clinic parses input, it generates :term:`output`. +The output is rewritten into the C file immediately after the input, +followed by a :term:`checksum line`. +All of these lines, including the :term:`start line` and :term:`checksum line`, +are collectively called an Argument Clinic :term:`block`: -.. code-block:: none +.. code-block:: c /*[clinic input] ... clinic input goes here ... [clinic start generated code]*/ ... clinic output goes here ... - /*[clinic end generated code: checksum=...]*/ + /*[clinic end generated code: ...]*/ If you run Argument Clinic on the same file a second time, Argument Clinic -will discard the old output and write out the new output with a fresh checksum -line. However, if the input hasn't changed, the output won't change either. - -You should never modify the output portion of an Argument Clinic block. Instead, -change the input until it produces the output you want. (That's the purpose of the -checksum—to detect if someone changed the output, as these edits would be lost -the next time Argument Clinic writes out fresh output.) - -For the sake of clarity, here's the terminology we'll use with Argument Clinic: - -* The first line of the comment (``/*[clinic input]``) is the *start line*. -* The last line of the initial comment (``[clinic start generated code]*/``) is the *end line*. -* The last line (``/*[clinic end generated code: checksum=...]*/``) is the *checksum line*. -* In between the start line and the end line is the *input*. -* In between the end line and the checksum line is the *output*. -* All the text collectively, from the start line to the checksum line inclusively, - is the *block*. (A block that hasn't been successfully processed by Argument - Clinic yet doesn't have output or a checksum line, but it's still considered - a block.) +will discard the old :term:`output` and write out the new output with a fresh +:term:`checksum line`. +If the :term:`input` hasn't changed, the output won't change either. + +.. note:: + + You should never modify the output of an Argument Clinic block, + as any change will be lost in future Argument Clinic runs; + Argument Clinic willl detect an output checksum mismatch and regenerate the + correct output. + If you are not happy with the generated output, + change instead the input until it produces the output you want. + + +.. _clinic-reference: + +Reference +========= + + +.. _clinic-terminology: + +Terminology +----------- + +.. glossary:: + + start line + The line ``/*[clinic input]``. + This line marks the beginning of Argument Clinic input. + + end line + The line ``[clinic start generated code]*/``. + This line marks the end of Argument Clinic input. + + checksum line + A line that looks like ``/*[clinic end generated code: ... */``. + (The three dots will be replaced by the actual checksum(s).) + The checksum line marks the end of Argument Clinic generated code. + + input + The text between the :term:`start line` and the :term:`end line`. + + output + The text between the :term:`end line` and the :term`checksum line`. + + block + All text from the :term:`start line` to the :term:`checksum line` inclusively. + +.. note:: + + A block that hasn't been successfully processed by Argument Clinic yet + doesn't have *output* or a *checksum line*, + but it's still considered a *block*. + + +.. _clinic-cli: + +Command-line interface +---------------------- + +The Argument Clinic :abbr:`CLI (Command Line Interface)` is typically used to +process a single source file, like this: + +.. code-block:: shell-session + + $ python3 ./Tools/clinic/clinic.py foo.c + +The CLI supports the following options: + +.. program:: ./Tools/clinic/clinic.py [-h] [-f] [-o OUTPUT] [-v] \ + [--converters] [--make] [--srcdir SRCDIR] [filename ...] + +.. option:: -h, --help + + Print CLI usage. + +.. option:: -f, --force + + Force clinic regeneration. + +.. option:: -o, --output OUTPUT + + Redirect file output to OUTPUT + +.. option:: -v, --verbose + + Enable verbose mode. + +.. option:: --converters + + Print a list of all supported converters and return converters. + +.. option:: --make + + Walk --srcdir to run over all relevant files. + +.. option:: --srcdir SRCDIR + + The directory tree to walk in --make mode. + +.. option:: filename ... + + The list of files to process. .. _clinic-tutorial: From e41203ae04be02d3b277d50ed6d72dcfb23314b0 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 22 Jul 2023 01:22:11 +0200 Subject: [PATCH 02/16] Sphinx lint --- Doc/howto/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 5b22c791aeefc0..59bee00c4b3dc6 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -173,7 +173,7 @@ Terminology The text between the :term:`start line` and the :term:`end line`. output - The text between the :term:`end line` and the :term`checksum line`. + The text between the :term:`end line` and the :term:`checksum line`. block All text from the :term:`start line` to the :term:`checksum line` inclusively. From 8fa70d676a5c4ea8e61f739aef56c91023442ad4 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 22 Jul 2023 21:56:02 +0200 Subject: [PATCH 03/16] Apply suggestions from code review Co-authored-by: Ezio Melotti Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/howto/clinic.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 59bee00c4b3dc6..6dfb2a4137b33e 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -137,10 +137,10 @@ If the :term:`input` hasn't changed, the output won't change either. You should never modify the output of an Argument Clinic block, as any change will be lost in future Argument Clinic runs; - Argument Clinic willl detect an output checksum mismatch and regenerate the + Argument Clinic will detect an output checksum mismatch and regenerate the correct output. If you are not happy with the generated output, - change instead the input until it produces the output you want. + you should instead change the input until it produces the output you want. .. _clinic-reference: @@ -165,7 +165,7 @@ Terminology This line marks the end of Argument Clinic input. checksum line - A line that looks like ``/*[clinic end generated code: ... */``. + A line that looks like ``/*[clinic end generated code: ...]*/``. (The three dots will be replaced by the actual checksum(s).) The checksum line marks the end of Argument Clinic generated code. @@ -190,7 +190,7 @@ Terminology Command-line interface ---------------------- -The Argument Clinic :abbr:`CLI (Command Line Interface)` is typically used to +The Argument Clinic :abbr:`CLI (Command-Line Interface)` is typically used to process a single source file, like this: .. code-block:: shell-session From 38f1d420e251f9f0088a906c02cd4084f2b6a13b Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 22 Jul 2023 21:59:01 +0200 Subject: [PATCH 04/16] Fix --srcdir and --make --- Doc/howto/clinic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 6dfb2a4137b33e..24b328999f4ab7 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -224,11 +224,11 @@ The CLI supports the following options: .. option:: --make - Walk --srcdir to run over all relevant files. + Walk :option:`--srcdir` to run over all relevant files. .. option:: --srcdir SRCDIR - The directory tree to walk in --make mode. + The directory tree to walk in :option:`--make` mode. .. option:: filename ... From 65d24585a92967023eb3431ed2095c0c02a11cc3 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 22 Jul 2023 21:59:56 +0200 Subject: [PATCH 05/16] Remove unneeded parens --- Doc/howto/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 24b328999f4ab7..e45b2086344cdd 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -166,7 +166,7 @@ Terminology checksum line A line that looks like ``/*[clinic end generated code: ...]*/``. - (The three dots will be replaced by the actual checksum(s).) + The three dots will be replaced by the actual checksum(s). The checksum line marks the end of Argument Clinic generated code. input From 951c92cf1372f95382fc27fcd6f8605c75f93b78 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 22 Jul 2023 22:06:42 +0200 Subject: [PATCH 06/16] In the glossary, add some words explaining that AC input is actually a C block comment --- Doc/howto/clinic.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index e45b2086344cdd..f097ed3fdf2aac 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -159,10 +159,13 @@ Terminology start line The line ``/*[clinic input]``. This line marks the beginning of Argument Clinic input. + Notice that the *start line* actually opens a C block comment. end line The line ``[clinic start generated code]*/``. This line marks the end of Argument Clinic input. + Notice that the *end line* closes the C block comment opened + by the *start line*. checksum line A line that looks like ``/*[clinic end generated code: ...]*/``. @@ -171,6 +174,8 @@ Terminology input The text between the :term:`start line` and the :term:`end line`. + Notice that the start and end lines open and close a C block comment; + the *input* is thus a part of that same C block comment. output The text between the :term:`end line` and the :term:`checksum line`. From cee1240ef9921195c05136e00d0f0df48553dc5b Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 22 Jul 2023 22:07:42 +0200 Subject: [PATCH 07/16] Revert C markup for clinic input --- Doc/howto/clinic.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index f097ed3fdf2aac..3f7fd4a725474b 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -103,13 +103,13 @@ When Argument Clinic is run on a file, either via the :ref:`clinic-cli` or via ``make clinic``, it will scan over the input files looking for :term:`start lines `: -.. code-block:: c +.. code-block:: none /*[clinic input] When it finds one, it reads everything up to the :term:`end line`: -.. code-block:: c +.. code-block:: none [clinic start generated code]*/ @@ -120,7 +120,7 @@ followed by a :term:`checksum line`. All of these lines, including the :term:`start line` and :term:`checksum line`, are collectively called an Argument Clinic :term:`block`: -.. code-block:: c +.. code-block:: none /*[clinic input] ... clinic input goes here ... From 3502b25ad0636298fc87a5fc8190d4a2d5471610 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 22 Jul 2023 22:34:08 +0200 Subject: [PATCH 08/16] Adjust wording --- Doc/howto/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 3f7fd4a725474b..2c09ac25c1459a 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -159,7 +159,7 @@ Terminology start line The line ``/*[clinic input]``. This line marks the beginning of Argument Clinic input. - Notice that the *start line* actually opens a C block comment. + Notice that the *start line* opens a C block comment. end line The line ``[clinic start generated code]*/``. From 9bdd1c5fc0551555d6c883b6ad386b5e9bd7b9e9 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 24 Jul 2023 18:06:53 +0200 Subject: [PATCH 09/16] Address review: add glossary item for 'checksum'; improve 'checksum line' entry --- Doc/howto/clinic.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 79522b5cf9cd8e..23cede4f3acef0 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -167,10 +167,18 @@ Terminology Notice that the *end line* closes the C block comment opened by the *start line*. + checksum + The 16 first hex digits of a :py:meth:`~hashlib.sha1` hash. + Argument Clinic generates checksums of the :term:`intput` + and the :term:`output` as part of the :term:`checksum line`. + checksum line A line that looks like ``/*[clinic end generated code: ...]*/``. - The three dots will be replaced by the actual checksum(s). - The checksum line marks the end of Argument Clinic generated code. + The three dots will be replaced by a :term:`checksum` generated from the + :term:`input`, and a :term:`checksum` generated from the :term:`output`. + The checksum line marks the end of Argument Clinic generated code, + and is used by Argument Clinic to determine if it needs to regenerate + output. input The text between the :term:`start line` and the :term:`end line`. From ab72fcf4dca6ac4c37b93d2c66ecb44eade0f5b8 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 24 Jul 2023 18:07:08 +0200 Subject: [PATCH 10/16] Address review: Notice => Note --- Doc/howto/clinic.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 23cede4f3acef0..8b04922b45361a 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -159,12 +159,12 @@ Terminology start line The line ``/*[clinic input]``. This line marks the beginning of Argument Clinic input. - Notice that the *start line* opens a C block comment. + Note that the *start line* opens a C block comment. end line The line ``[clinic start generated code]*/``. This line marks the end of Argument Clinic input. - Notice that the *end line* closes the C block comment opened + Note that the *end line* closes the C block comment opened by the *start line*. checksum @@ -182,7 +182,7 @@ Terminology input The text between the :term:`start line` and the :term:`end line`. - Notice that the start and end lines open and close a C block comment; + Note that the start and end lines open and close a C block comment; the *input* is thus a part of that same C block comment. output From 26eec6bcc7b62528f4bd654764b3718d32f7bb68 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 24 Jul 2023 18:07:28 +0200 Subject: [PATCH 11/16] Nit: three-space indent --- Doc/howto/clinic.rst | 68 ++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 8b04922b45361a..f34b919a78dac5 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -156,40 +156,40 @@ Terminology .. glossary:: - start line - The line ``/*[clinic input]``. - This line marks the beginning of Argument Clinic input. - Note that the *start line* opens a C block comment. - - end line - The line ``[clinic start generated code]*/``. - This line marks the end of Argument Clinic input. - Note that the *end line* closes the C block comment opened - by the *start line*. - - checksum - The 16 first hex digits of a :py:meth:`~hashlib.sha1` hash. - Argument Clinic generates checksums of the :term:`intput` - and the :term:`output` as part of the :term:`checksum line`. - - checksum line - A line that looks like ``/*[clinic end generated code: ...]*/``. - The three dots will be replaced by a :term:`checksum` generated from the - :term:`input`, and a :term:`checksum` generated from the :term:`output`. - The checksum line marks the end of Argument Clinic generated code, - and is used by Argument Clinic to determine if it needs to regenerate - output. - - input - The text between the :term:`start line` and the :term:`end line`. - Note that the start and end lines open and close a C block comment; - the *input* is thus a part of that same C block comment. - - output - The text between the :term:`end line` and the :term:`checksum line`. - - block - All text from the :term:`start line` to the :term:`checksum line` inclusively. + start line + The line ``/*[clinic input]``. + This line marks the beginning of Argument Clinic input. + Note that the *start line* opens a C block comment. + + end line + The line ``[clinic start generated code]*/``. + This line marks the end of Argument Clinic input. + Note that the *end line* closes the C block comment opened + by the *start line*. + + checksum + The 16 first hex digits of a :py:meth:`~hashlib.sha1` hash. + Argument Clinic generates checksums of the :term:`intput` + and the :term:`output` as part of the :term:`checksum line`. + + checksum line + A line that looks like ``/*[clinic end generated code: ...]*/``. + The three dots will be replaced by a :term:`checksum` generated from the + :term:`input`, and a :term:`checksum` generated from the :term:`output`. + The checksum line marks the end of Argument Clinic generated code, + and is used by Argument Clinic to determine if it needs to regenerate + output. + + input + The text between the :term:`start line` and the :term:`end line`. + Note that the start and end lines open and close a C block comment; + the *input* is thus a part of that same C block comment. + + output + The text between the :term:`end line` and the :term:`checksum line`. + + block + All text from the :term:`start line` to the :term:`checksum line` inclusively. .. note:: From 01830b5c2f5caaefbd7bd47c45e6a4d336f5d45c Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 24 Jul 2023 18:17:30 +0200 Subject: [PATCH 12/16] Address review: Mirror CLI option docs in CLI --help --- Doc/howto/clinic.rst | 6 +++--- Tools/clinic/clinic.py | 20 +++++++++++++------- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index f34b919a78dac5..a5acbce5559d89 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -213,7 +213,7 @@ process a single source file, like this: The CLI supports the following options: .. program:: ./Tools/clinic/clinic.py [-h] [-f] [-o OUTPUT] [-v] \ - [--converters] [--make] [--srcdir SRCDIR] [filename ...] + [--converters] [--make] [--srcdir SRCDIR] [FILE ...] .. option:: -h, --help @@ -221,7 +221,7 @@ The CLI supports the following options: .. option:: -f, --force - Force clinic regeneration. + Force output regeneration. .. option:: -o, --output OUTPUT @@ -243,7 +243,7 @@ The CLI supports the following options: The directory tree to walk in :option:`--make` mode. -.. option:: filename ... +.. option:: FILE ... The list of files to process. diff --git a/Tools/clinic/clinic.py b/Tools/clinic/clinic.py index eecb81dcad5881..5d78e13e260aa6 100755 --- a/Tools/clinic/clinic.py +++ b/Tools/clinic/clinic.py @@ -5602,15 +5602,21 @@ def main(argv): signatures ("docstrings") for CPython builtins. For more information see https://docs.python.org/3/howto/clinic.html""") - cmdline.add_argument("-f", "--force", action='store_true') - cmdline.add_argument("-o", "--output", type=str) - cmdline.add_argument("-v", "--verbose", action='store_true') - cmdline.add_argument("--converters", action='store_true') + cmdline.add_argument("-f", "--force", action='store_true', + help="force output regeneration") + cmdline.add_argument("-o", "--output", type=str, + help="redirect file output to OUTPUT") + cmdline.add_argument("-v", "--verbose", action='store_true', + help="enable verbose mode") + cmdline.add_argument("--converters", action='store_true', + help=("print a list of all supported converters " + "and return converters")) cmdline.add_argument("--make", action='store_true', - help="Walk --srcdir to run over all relevant files.") + help="walk --srcdir to run over all relevant files") cmdline.add_argument("--srcdir", type=str, default=os.curdir, - help="The directory tree to walk in --make mode.") - cmdline.add_argument("filename", type=str, nargs="*") + help="the directory tree to walk in --make mode") + cmdline.add_argument("filename", metavar="FILE", type=str, nargs="*", + help="the list of files to process") ns = cmdline.parse_args(argv) if ns.converters: From 72fe212adb9b87609ac5ca1232472e87acb749bf Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 24 Jul 2023 18:22:23 +0200 Subject: [PATCH 13/16] Address review: explain why the end line is named [clinic start generated code]*/ --- Doc/howto/clinic.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index a5acbce5559d89..30cd4b2961e3ab 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -163,7 +163,9 @@ Terminology end line The line ``[clinic start generated code]*/``. - This line marks the end of Argument Clinic input. + The *end line* marks the _end_ of Argument Clinic :term:`input`, + but at the same time marks the _start_ of Argument Clinic :term:`output`, + thus the text *"clinic start start generated code"* Note that the *end line* closes the C block comment opened by the *start line*. From 872bd13bf9e9d905e4f2cd2f13b2f4772e3f0d29 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 24 Jul 2023 18:26:17 +0200 Subject: [PATCH 14/16] "intput" --- Doc/howto/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 30cd4b2961e3ab..7938e826e872e0 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -171,7 +171,7 @@ Terminology checksum The 16 first hex digits of a :py:meth:`~hashlib.sha1` hash. - Argument Clinic generates checksums of the :term:`intput` + Argument Clinic generates checksums of the :term:`input` and the :term:`output` as part of the :term:`checksum line`. checksum line From 371d19316f284f3c225947bc65a973baa30b16b6 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 26 Jul 2023 23:15:44 +0200 Subject: [PATCH 15/16] Remove note about block internals --- Doc/howto/clinic.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index fbca8ac4a89629..c1a6f233dc210f 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -193,12 +193,6 @@ Terminology block All text from the :term:`start line` to the :term:`checksum line` inclusively. -.. note:: - - A block that hasn't been successfully processed by Argument Clinic yet - doesn't have *output* or a *checksum line*, - but it's still considered a *block*. - .. _clinic-cli: From 306858b7e1981bc512aaf436f9ea7feca2f72b29 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 26 Jul 2023 23:22:09 +0200 Subject: [PATCH 16/16] Add Alex's suggestion for the 'checksum' glossary entry --- Doc/howto/clinic.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index c1a6f233dc210f..7aafd48711b58e 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -170,9 +170,8 @@ Terminology by the *start line*. checksum - The 16 first hex digits of a :py:meth:`~hashlib.sha1` hash. - Argument Clinic generates checksums of the :term:`input` - and the :term:`output` as part of the :term:`checksum line`. + A hash to distinguish unique :term:`inputs ` + and :term:`outputs `. checksum line A line that looks like ``/*[clinic end generated code: ...]*/``.