@@ -13,8 +13,10 @@ Argument Clinic How-To
13
13
.. topic :: Abstract
14
14
15
15
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,
18
20
module level functions, and class methods.
19
21
This document is divided in four major sections:
20
22
@@ -44,58 +46,6 @@ Argument Clinic How-To
44
46
Background
45
47
==========
46
48
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
-
99
49
Basic concepts
100
50
--------------
101
51
0 commit comments