Skip to content

Commit

Permalink
gh-107507: Replace 'The goals of Argument Clinic' with a summary (#10…
Browse files Browse the repository at this point in the history
…7508)

Summarise the goals of Argument Clinic in a single sentence.
Mention that Argument Clinic was introduced with PEP-436.
  • Loading branch information
erlend-aasland authored Jul 31, 2023
1 parent dfb55d9 commit abb71c6
Showing 1 changed file with 4 additions and 54 deletions.
58 changes: 4 additions & 54 deletions Doc/howto/clinic.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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
--------------

Expand Down

0 comments on commit abb71c6

Please sign in to comment.