Everything in between these two lines is input for Argument Clinic. All of these lines, including the beginning and ending comment lines, are collectively called an Argument Clinic “block”. 

When Argument Clinic parses one of these blocks, it generates output. This output is rewritten into the C file immediately after the block, followed by a comment containing a checksum. The Argument Clinic block now looks like this: 

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

If you run Argument Clinic on the same file a second time, Argument Clinic will discard the old output and write out the new output with a fresh checksum line. However, if the input hasn’t changed, the output won’t change either. 

You should never modify the output portion of an Argument Clinic block. Instead, change the input until it produces the output you want. (That’s the purpose of the checksum—to detect if someone changed the output, as these edits would be lost the next time Argument Clinic writes out fresh output.) 

For the sake of clarity, here’s the terminology we’ll use with Argument Clinic: 

• The first line of the comment ($_{/*[clinic input]}$ ) is the start line . 

• The last line of the initial comment ($_{[clinic start generated code]*/}$ ) is the end line . 

• The last line ($_{/*[clinic end generated code: checksum=...]*/}$ ) is the checksum line . 

• In between the start line and the end line is the input . 

• In between the end line and the checksum line is the output . 

• All the text collectively, from the start line to the checksum line inclusively, is the block . (A block that hasn’t been successfully processed by Argument Clinic yet doesn’t have output or a checksum line, but it’s still con- sidered a block.) 

## 3 Converting Your First Function 

The best way to get a sense of how Argument Clinic works is to convert a function to work with it. Here, then, are the bare minimum steps you’d need to follow to convert a function to work with Argument Clinic. Note that for code you plan to check in to CPython, you really should take the conversion farther, using some of the advanced concepts you’ll see later on in the document (like “return converters” and “self converters”). But we’ll keep it simple for this walkthrough so you can learn. 

Let’s dive in! 

0. Make sure you’re working with a freshly updated checkout of the CPython trunk. 

1. Find a Python builtin that calls either PyArg_ParseTuple() or PyArg_ParseTupleAndKeywords() , and hasn’t been converted to work with Argument Clinic yet. For my example I’m using$_{_pickle.Pickler.dump()}$ . 

2. If the call to the$_{PyArg_Parse}$ function uses any of the following format units: 

O& O! es es# et et# 

or if it has multiple calls to$_{PyArg_ParseTuple()}$ , you should choose a different function. Argument Clinic does support all of these scenarios. But these are advanced topics—let’s do something simpler for your first function. 

