From fd6085529935afec085cea0729507ba6d4b34ab3 Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
 <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 31 Jul 2023 14:42:58 -0700
Subject: [PATCH] [3.12] gh-107507: Replace 'The goals of Argument Clinic' with
 a summary (GH-107508) (#107516)

Summarise the goals of Argument Clinic in a single sentence.
Mention that Argument Clinic was introduced with PEP-436.
(cherry picked from commit abb71c6a8f73482c910ffdf050a86089a48e0e60)

Co-authored-by: Erlend E. Aasland <erlend@python.org>
---
 Doc/howto/clinic.rst | 58 +++-----------------------------------------
 1 file changed, 4 insertions(+), 54 deletions(-)

diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index 7aafd48711b58e..9c9a4f45dd0f58 100644
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -13,8 +13,10 @@ Argument Clinic How-To
 .. topic:: Abstract
 
   Argument Clinic is a preprocessor for CPython C files.
-  Its purpose is to automate all the boilerplate involved
-  with writing argument parsing code for "builtins",
+  It was introduced in Python 3.4 with :pep:`436`,
+  in order to provide introspection signatures,
+  and to generate performant and tailor-made boilerplate code
+  for argument parsing in CPython builtins,
   module level functions, and class methods.
   This document is divided in four major sections:
 
@@ -44,58 +46,6 @@ Argument Clinic How-To
 Background
 ==========
 
-
-The goals of Argument Clinic
-----------------------------
-
-Argument Clinic's primary goal
-is to take over responsibility for all argument parsing code
-inside CPython.  This means that, when you convert a function
-to work with Argument Clinic, that function should no longer
-do any of its own argument parsing—the code generated by
-Argument Clinic should be a "black box" to you, where CPython
-calls in at the top, and your code gets called at the bottom,
-with ``PyObject *args`` (and maybe ``PyObject *kwargs``)
-magically converted into the C variables and types you need.
-
-In order for Argument Clinic to accomplish its primary goal,
-it must be easy to use.  Currently, working with CPython's
-argument parsing library is a chore, requiring maintaining
-redundant information in a surprising number of places.
-When you use Argument Clinic, you don't have to repeat yourself.
-
-Obviously, no one would want to use Argument Clinic unless
-it's solving their problem—and without creating new problems of
-its own.
-So it's paramount that Argument Clinic generate correct code.
-It'd be nice if the code was faster, too, but at the very least
-it should not introduce a major speed regression.  (Eventually Argument
-Clinic *should* make a major speedup possible—we could
-rewrite its code generator to produce tailor-made argument
-parsing code, rather than calling the general-purpose CPython
-argument parsing library.  That would make for the fastest
-argument parsing possible!)
-
-Additionally, Argument Clinic must be flexible enough to
-work with any approach to argument parsing.  Python has
-some functions with some very strange parsing behaviors;
-Argument Clinic's goal is to support all of them.
-
-Finally, the original motivation for Argument Clinic was
-to provide introspection "signatures" for CPython builtins.
-It used to be, the introspection query functions would throw
-an exception if you passed in a builtin.  With Argument
-Clinic, that's a thing of the past!
-
-One idea you should keep in mind, as you work with
-Argument Clinic: the more information you give it, the
-better job it'll be able to do.
-Argument Clinic is admittedly relatively simple right
-now.  But as it evolves it will get more sophisticated,
-and it should be able to do many interesting and smart
-things with all the information you give it.
-
-
 Basic concepts
 --------------