Text of peps.python.org › pep-0436 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 436 – The Argument Clinic DSL | peps.python.org

PEP 436 – The Argument Clinic DSL PEP 436 – The Argument Clinic DSL Author : Larry Hastings <larry at hastings.org> Discussions-To : Python-Dev list Status : Final Type : Standards Track Created : 22-Feb-2013 Python-Version : 3.4 Table of Contents Abstract Rationale and Goals DSL Syntax Summary General Behavior Of the Argument Clinic DSL Module and Class Declarations Function Declaration Parameter Declaration Legacy Converters Parameter Docstrings Special Syntax For Parameter Lines Function Docstring Converters Return Converters Directives Python Code Output Functions With Positional-Only Parameters Current Status Argument Clinic Programmatic Interfaces Notes / TBD Acknowledgements References Copyright Abstract This document proposes “Argument Clinic”, a DSL to facilitate argument processing for built-in functions in the implementation of CPython.

Rationale and Goals The primary implementation of Python, “CPython”, is written in a mixture of Python and C. One implementation detail of CPython is what are called “built-in” functions – functions available to Python programs but written in C. When a Python program calls a built-in function and passes in arguments, those arguments must be translated from Python values into C values. This process is called “parsing arguments”.

As of CPython 3.3, builtin functions nearly always parse their arguments with one of two functions: the original PyArg_ParseTuple() , [1] and the more modern PyArg_ParseTupleAndKeywords() . [2] The former only handles positional parameters; the latter also accommodates keyword and keyword-only parameters, and is preferred for new code. With either function, the caller specifies the translation for parsing arguments in a “format string”: [3] each parameter corresponds to a “format unit”, a short character sequence telling the parsing function what Python types to accept and how to translate them into the appropriate C value for that parameter.

PyArg_ParseTuple() was reasonable when it was first conceived. There were only a dozen or so of these “format units”; each one was distinct, and easy to understand and remember. But over the years the PyArg_Parse interface has been extended in numerous ways. The modern API is complex, to the point that it is somewhat painful to use. Consider: There are now forty different “format units”; a few are even three characters long.

This makes it difficult for the programmer to understand what the format string says–or even perhaps to parse it–without constantly cross-indexing it with the documentation. There are also six meta-format units that may be buried in the format string. (They are: "()|$:;" .) The more format units are added, the less likely it is the implementer can pick an easy-to-use mnemonic for the format unit, because the character of choice is probably already in use.

In other words, the more format units we have, the more obtuse the format units become. Several format units are nearly identical to others, having only subtle differences. This makes understanding the exact semantics of the format string even harder, and can make it difficult to figure out exactly which format unit you want. The docstring is specified as a static C string, making it mildly bothersome to read and edit since it must obey C string quoting rules.

When adding a new parameter to a function using PyArg_ParseTupleAndKeywords() , it’s necessary to touch six different places in the code: [4] Declaring the variable to store the argument. Passing in a pointer to that variable in the correct spot in PyArg_ParseTupleAndKeywords() , also passing in any “length” or “converter” arguments in the correct order. Adding the name of the argument in the correct spot of the “keywords” array passed in to PyArg_ParseTupleAndKeywords() .

Adding the format unit to the correct spot in the format string. Adding the parameter to the prototype in the docstring. Documenting the parameter in the docstring. There is currently no mechanism for builtin functions to provide their “signature” information (see inspect.getfullargspec and inspect.Signature ). Adding this information using a mechanism similar to the existing PyArg_Parse functions would require repeating ourselves yet again.

The goal of Argument Clinic is to replace this API with a mechanism inheriting none of these downsides: You need specify each parameter only once. All information about a parameter is kept together in one place. For each parameter, you specify a conversion function; Argument Clinic handles the translation from Python value into C value for you. Argument Clinic also allows for fine-tuning of argument processing behavior with parameterized conversion functions.

Docstrings are written in plain text. Function docstrings are required; per-parameter docstrings are encouraged. From this, Argument Clinic generates for you all the mundane, repetitious code and data structures CPython needs internally. Once you’ve specified the interface, the next step is simply to write your implementation using native C types. Every detail of argument parsing is handled for you. Argument Clinic is implemented as a preprocessor.

It draws inspiration for its workflow directly from [Cog] by Ned Batchelder. To use Clinic, add a block comment to your C source code beginning and ending with special text strings, then run Clinic on the file. Clinic will find the block comment, process the contents, and write the output back into your C source file directly after the comment. The intent is that Clinic’s output becomes part of your source code; it’s checked in to revision control, and distributed with source packages.

This means that Python will still ship ready-to-build. It does complicate development slightly; in order to add a new function, or modify the arguments or documentation of an existing function using Clinic, you’ll need a working Python 3 interpreter. Future goals of Argument Clinic include: providing signature information for builtins, enabling alternative implementations of Python to create automated library compatibility tests, and speeding up argument parsing with improvements to the generated code.

DSL Syntax Summary The Argument Clinic DSL is specified as a comment embedded in a C file, as follows. The “Example” column on the right shows you sample input to the Argument Clinic DSL, and the “Section” column on the left specifies what each line represents in turn. Argument Clinic’s DSL syntax mirrors the Python def statement, lending it some familiarity to Python core developers. +-----------------------+-----------------------------------------------------------------+ | Section | Example | +-----------------------+-----------------------------------------------------------------+ | Clinic DSL start | /* [ clinic ] | | Module declaration | module module_name | | Class declaration | class module_name . class_name | | Function declaration | module_name . function_name -> return_annotation | | Parameter declaration | name : converter ( param = value ) | | Parameter docstring | Lorem ipsum dolor sit amet , consectetur | | | adipisicing elit , sed do eiusmod tempor | | Function docstring | Lorem ipsum dolor sit amet , consectetur adipisicing | | | elit , sed do eiusmod tempor incididunt ut labore et | | Clinic DSL end | [ clinic ] */ | | Clinic output | ... | | Clinic output end | /* [ clinic end output : < checksum > ] */ | +-----------------------+-----------------------------------------------------------------+ To give some flavor of the proposed DSL syntax, here are some sample Clinic code blocks.

This first block reflects the normally preferred style, including blank lines between parameters and per-argument docstrings. It also includes a user-defined converter ( path_t ) created locally: /* [ clinic ] os . stat as os_stat_fn -> stat result path : path_t ( allow_fd = 1 ) Path to be examined ; can be string , bytes , or open - file - descriptor int

The rest of this page is on the live site.