author:: Larry Hastings

Source code:Tools/clinic/clinic.py.

Argument Clinic is a preprocessor for CPython C files.It was introduced in Python 3.4 withPEP 436,in order to provide introspection signatures,and to generate performant and tailor-made boilerplate codefor argument parsing in CPython builtins, module level functions, and class methods.This document is divided in four major sections:

Background talks about the basic concepts and goals of Argument Clinic.
Reference describes the command-line interface and Argument Clinic terminology.
Tutorial guides you through all the steps required to adapt an existing C function to Argument Clinic.
How-to guides details how to handle specific tasks.

Note

Argument Clinic is considered internal-onlyfor CPython. Its use is not supported for files outsideCPython, and no guarantees are made regarding backwardscompatibility for future versions. In other words: if youmaintain an external C extension for CPython, you’re welcometo experiment with Argument Clinic in your own code. But theversion of Argument Clinic that ships with the next versionof CPythoncould be totally incompatible and break all your code.

Background¶

Basic concepts¶

When Argument Clinic is run on a file, either via theCommand-line interfaceor viamakeclinic, it will scan over the input files looking forstart lines:

/*[clinic input]

When it finds one, it reads everything up to theend line:

[clinic start generated code]*/

Everything in between these two lines is Argument Clinicinput.When Argument Clinic parses input, it generatesoutput.The output is rewritten into the C file immediately after the input,followed by achecksum line.All of these lines, including thestart line andchecksum line,are collectively called an Argument Clinicblock:

/*[clinic input]... clinic input goes here ...[clinic start generated code]*/... clinic output goes here .../*[clinic end generated code: ...]*/

If you run Argument Clinic on the same file a second time, Argument Clinicwill discard the oldoutput and write out the new output with a freshchecksum line.If theinput hasn’t changed, the output won’t change either.

Note

You should never modify the output of an Argument Clinic block,as any change will be lost in future Argument Clinic runs;Argument Clinic will detect an output checksum mismatch and regenerate thecorrect output.If you are not happy with the generated output,you should instead change the input until it produces the output you want.

Reference¶

Terminology¶

start line¶: The line/*[clinicinput].This line marks the beginning of Argument Clinic input.Note that thestart line opens a C block comment.
end line¶: The line[clinicstartgeneratedcode]*/.Theend line marks theend of Argument Clinicinput,but at the same time marks thestart of Argument Clinicoutput,thus the text“clinic start start generated code”Note that theend line closes the C block comment openedby thestart line.
checksum¶: A hash to distinguish uniqueinputsandoutputs.
checksum line¶: A line that looks like/*[clinicendgeneratedcode:...]*/.The three dots will be replaced by achecksum generated from theinput, and achecksum generated from theoutput.The checksum line marks the end of Argument Clinic generated code,and is used by Argument Clinic to determine if it needs to regenerateoutput.
input¶: The text between thestart line and theend line.Note that the start and end lines open and close a C block comment;theinput is thus a part of that same C block comment.
output¶: The text between theend line and thechecksum line.
block¶: All text from thestart line to thechecksum line inclusively.

Command-line interface¶

The Argument ClinicCLI is typically used toprocess a single source file, like this:

$python3./Tools/clinic/clinic.pyfoo.c

The CLI supports the following options:

-h,--help ¶: Print CLI usage.

-f,--force¶: Force output regeneration.

-o,--outputOUTPUT¶: Redirect file output to OUTPUT

-v,--verbose¶: Enable verbose mode.

--converters¶: Print a list of all supported converters and return converters.

--make¶: Walk--srcdir to run over all relevant files.

--srcdirSRCDIR¶: The directory tree to walk in--make mode.

--excludeEXCLUDE¶: A file to exclude in--make mode.This option can be given multiple times.

--limited¶: Use theLimited API to parse arguments in the generated C code.SeeHow to use the Limited C API.

FILE...¶: The list of files to process.

Classes for extending Argument Clinic¶

classclinic.CConverter¶

The base class for all converters.SeeHow to write a custom converter for how to subclass this class.

type¶: The C type to use for this variable.type should be a Python string specifying the type,for example,'int'.If this is a pointer type, the type string should end with'*'.

default¶: The Python default value for this parameter, as a Python value.Or the magic valueunspecified if there is no default.

py_default¶: default as it should appear in Python code,as a string.OrNone if there is no default.

c_default¶: default as it should appear in C code,as a string.OrNone if there is no default.

c_ignored_default¶: The default value used to initialize the C variable whenthere is no default, but not specifying a default mayresult in an “uninitialized variable” warning. This caneasily happen when using option groups—althoughproperly written code will never actually use this value,the variable does get passed in to the impl, and theC compiler will complain about the “use” of theuninitialized value. This value should always be anon-empty string.

converter¶: The name of the C converter function, as a string.

impl_by_reference¶: A boolean value. If true,Argument Clinic will add a& in front of the name ofthe variable when passing it into the impl function.

parse_by_reference¶: A boolean value. If true,Argument Clinic will add a& in front of the name ofthe variable when passing it intoPyArg_ParseTuple().

On this page

Argument Clinic
- Background
  - Basic concepts
- Reference