Skip to content

Commit abb71c6

Browse files
gh-107507: Replace 'The goals of Argument Clinic' with a summary (#107508)
Summarise the goals of Argument Clinic in a single sentence. Mention that Argument Clinic was introduced with PEP-436.
1 parent dfb55d9 commit abb71c6

File tree

1 file changed

+4
-54
lines changed

1 file changed

+4
-54
lines changed

Doc/howto/clinic.rst

+4-54
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,10 @@ Argument Clinic How-To
1313
.. topic:: Abstract
1414

1515
Argument Clinic is a preprocessor for CPython C files.
16-
Its purpose is to automate all the boilerplate involved
17-
with writing argument parsing code for "builtins",
16+
It was introduced in Python 3.4 with :pep:`436`,
17+
in order to provide introspection signatures,
18+
and to generate performant and tailor-made boilerplate code
19+
for argument parsing in CPython builtins,
1820
module level functions, and class methods.
1921
This document is divided in four major sections:
2022

@@ -44,58 +46,6 @@ Argument Clinic How-To
4446
Background
4547
==========
4648

47-
48-
The goals of Argument Clinic
49-
----------------------------
50-
51-
Argument Clinic's primary goal
52-
is to take over responsibility for all argument parsing code
53-
inside CPython. This means that, when you convert a function
54-
to work with Argument Clinic, that function should no longer
55-
do any of its own argument parsing—the code generated by
56-
Argument Clinic should be a "black box" to you, where CPython
57-
calls in at the top, and your code gets called at the bottom,
58-
with ``PyObject *args`` (and maybe ``PyObject *kwargs``)
59-
magically converted into the C variables and types you need.
60-
61-
In order for Argument Clinic to accomplish its primary goal,
62-
it must be easy to use. Currently, working with CPython's
63-
argument parsing library is a chore, requiring maintaining
64-
redundant information in a surprising number of places.
65-
When you use Argument Clinic, you don't have to repeat yourself.
66-
67-
Obviously, no one would want to use Argument Clinic unless
68-
it's solving their problem—and without creating new problems of
69-
its own.
70-
So it's paramount that Argument Clinic generate correct code.
71-
It'd be nice if the code was faster, too, but at the very least
72-
it should not introduce a major speed regression. (Eventually Argument
73-
Clinic *should* make a major speedup possible—we could
74-
rewrite its code generator to produce tailor-made argument
75-
parsing code, rather than calling the general-purpose CPython
76-
argument parsing library. That would make for the fastest
77-
argument parsing possible!)
78-
79-
Additionally, Argument Clinic must be flexible enough to
80-
work with any approach to argument parsing. Python has
81-
some functions with some very strange parsing behaviors;
82-
Argument Clinic's goal is to support all of them.
83-
84-
Finally, the original motivation for Argument Clinic was
85-
to provide introspection "signatures" for CPython builtins.
86-
It used to be, the introspection query functions would throw
87-
an exception if you passed in a builtin. With Argument
88-
Clinic, that's a thing of the past!
89-
90-
One idea you should keep in mind, as you work with
91-
Argument Clinic: the more information you give it, the
92-
better job it'll be able to do.
93-
Argument Clinic is admittedly relatively simple right
94-
now. But as it evolves it will get more sophisticated,
95-
and it should be able to do many interesting and smart
96-
things with all the information you give it.
97-
98-
9949
Basic concepts
10050
--------------
10151

0 commit comments

Comments
 (0)