@@ -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
4446Background
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-
9949Basic concepts
10050--------------
10151
0 commit comments