Symbolic default values¶

The default value you provide for a parameter can’t be any arbitraryexpression. Currently the following are explicitly supported:

• Numeric constants (integer and float)

• String constants

• True,False, andNone

• Simple symbolic constants likesys.maxsize, which muststart with the name of the module

In case you’re curious, this is implemented infrom_builtin()inLib/inspect.py.

(In the future, this may need to get even more elaborate,to allow full expressions likeCONSTANT-1.)

Renaming the C functions and variables generated by Argument Clinic¶

Argument Clinic automatically names the functions it generates for you.Occasionally this may cause a problem, if the generated name collides withthe name of an existing C function. There’s an easy solution: override the namesused for the C functions. Just add the keyword"as"to your function declaration line, followed by the function name you wish to use.Argument Clinic will use that function name for the base (generated) function,then add"_impl" to the end and use that for the name of the impl function.

For example, if we wanted to rename the C function names generated forpickle.Pickler.dump, it’d look like this:

/*[clinic input]pickle.Pickler.dump as pickler_dumper...

The base function would now be namedpickler_dumper(),and the impl function would now be namedpickler_dumper_impl().

Similarly, you may have a problem where you want to give a parametera specific Python name, but that name may be inconvenient in C. ArgumentClinic allows you to give a parameter different names in Python and in C,using the same"as" syntax:

/*[clinic input]pickle.Pickler.dump    obj: object    file as file_obj: object    protocol: object = NULL    *    fix_imports: bool = True

Here, the name used in Python (in the signature and thekeywordsarray) would befile, but the C variable would be namedfile_obj.

You can use this to rename theself parameter too!

Converting functions using PyArg_UnpackTuple¶

To convert a function parsing its arguments withPyArg_UnpackTuple(),simply write out all the arguments, specifying each as anobject. Youmay specify thetype argument to cast the type as appropriate. Allarguments should be marked positional-only (add a/ on a line by itselfafter the last argument).

Currently the generated code will usePyArg_ParseTuple(), but thiswill change soon.

Optional Groups¶

Some legacy functions have a tricky approach to parsing their arguments:they count the number of positional arguments, then use aswitch statementto call one of several differentPyArg_ParseTuple() calls depending onhow many positional arguments there are. (These functions cannot acceptkeyword-only arguments.) This approach was used to simulate optionalarguments back beforePyArg_ParseTupleAndKeywords() was created.

While functions using this approach can often be converted tousePyArg_ParseTupleAndKeywords(), optional arguments, and default values,it’s not always possible. Some of these legacy functions havebehaviorsPyArg_ParseTupleAndKeywords() doesn’t directly support.The most obvious example is the builtin functionrange(), which hasan optional argument on theleft side of its required argument!Another example iscurses.window.addch(), which has a group of twoarguments that must always be specified together. (The arguments arecalledx andy; if you call the function passing inx,you must also pass iny—and if you don’t pass inx you may notpass iny either.)

In any case, the goal of Argument Clinic is to support argument parsingfor all existing CPython builtins without changing their semantics.Therefore Argument Clinic supportsthis alternate approach to parsing, using what are calledoptional groups.Optional groups are groups of arguments that must all be passed in together.They can be to the left or the right of the required arguments. Theycanonly be used with positional-only parameters.

To specify an optional group, add a[ on a line by itself beforethe parameters you wish to group together, and a] on a line by itselfafter these parameters. As an example, here’s howcurses.window.addchuses optional groups to make the first two parameters and the lastparameter optional:

/*[clinic input]curses.window.addch    [    x: int      X-coordinate.    y: int      Y-coordinate.    ]    ch: object      Character to add.    [    attr: long      Attributes for the character.    ]    /...

Notes:

• For every optional group, one additional parameter will be passed into theimpl function representing the group. The parameter will be an int namedgroup_{direction}_{number},where{direction} is eitherright orleft depending on whether the groupis before or after the required parameters, and{number} is a monotonicallyincreasing number (starting at 1) indicating how far away the group is fromthe required parameters. When the impl is called, this parameter will be setto zero if this group was unused, and set to non-zero if this group was used.(By used or unused, I mean whether or not the parameters received argumentsin this invocation.)

• If there are no required arguments, the optional groups will behaveas if they’re to the right of the required arguments.

• In the case of ambiguity, the argument parsing codefavors parameters on the left (before the required parameters).

• Optional groups can only contain positional-only parameters.

• Optional groups areonly intended for legacy code. Please do notuse optional groups for new code.

Using real Argument Clinic converters, instead of “legacy converters”¶

To save time, and to minimize how much you need to learnto achieve your first port to Argument Clinic, the walkthrough above tellsyou to use “legacy converters”. “Legacy converters” are a convenience,designed explicitly to make porting existing code to Argument Cliniceasier. And to be clear, their use is acceptable when porting code forPython 3.4.

However, in the long term we probably want all our blocks touse Argument Clinic’s real syntax for converters. Why? A couplereasons:

• The proper converters are far easier to read and clearer in their intent.

• There are some format units that are unsupported as “legacy converters”,because they require arguments, and the legacy converter syntax doesn’tsupport specifying arguments.

• In the future we may have a new argument parsing library that isn’trestricted to whatPyArg_ParseTuple() supports; this flexibilitywon’t be available to parameters using legacy converters.

Therefore, if you don’t mind a little extra effort, please use the normalconverters instead of legacy converters.

In a nutshell, the syntax for Argument Clinic (non-legacy) converterslooks like a Python function call. However, if there are no explicitarguments to the function (all functions take their default values),you may omit the parentheses. Thusbool andbool() are exactlythe same converters.

All arguments to Argument Clinic converters are keyword-only.All Argument Clinic converters accept the following arguments:

c_default

The default value for this parameter when defined in C.Specifically, this will be the initializer for the variable declaredin the “parse function”. Seethe section on default valuesfor how to use this.Specified as a string.

annotation

The annotation value for this parameter. Not currently supported,becausePEP 8 mandates that the Python library may not useannotations.

In addition, some converters accept additional arguments. Here is a listof these arguments, along with their meanings:

accept

A set of Python types (and possibly pseudo-types);this restricts the allowable Python argument to values of these types.(This is not a general-purpose facility; as a rule it only supportsspecific lists of types as shown in the legacy converter table.)

To acceptNone, addNoneType to this set.

bitwise

Only supported for unsigned integers. The native integer value of thisPython argument will be written to the parameter without any range checking,even for negative values.

converter

Only supported by theobject converter. Specifies the name of aC “converter function”to use to convert this object to a native type.

encoding

Only supported for strings. Specifies the encoding to use when convertingthis string from a Python str (Unicode) value into a Cchar* value.

subclass_of

Only supported for theobject converter. Requires that the Pythonvalue be a subclass of a Python type, as expressed in C.

type

Only supported for theobject andself converters. Specifiesthe C type that will be used to declare the variable. Default value is"PyObject*".

zeroes

Only supported for strings. If true, embedded NUL bytes ('\\0') arepermitted inside the value. The length of the string will be passed into the impl function, just after the string parameter, as a parameter named<parameter_name>_length.

Please note, not every possible combination of arguments will work.Usually these arguments are implemented by specificPyArg_ParseTupleformat units, with specific behavior. For example, currently you cannotcallunsigned_short without also specifyingbitwise=True.Although it’s perfectly reasonable to think this would work, these semantics don’tmap to any existing format unit. So Argument Clinic doesn’t support it. (Or, atleast, not yet.)

Below is a table showing the mapping of legacy converters into realArgument Clinic converters. On the left is the legacy converter,on the right is the text you’d replace it with.

As an example, here’s our samplepickle.Pickler.dump using the properconverter:

/*[clinic input]pickle.Pickler.dump    obj: object        The object to be pickled.    /Write a pickled representation of obj to the open file.[clinic start generated code]*/

One advantage of real converters is that they’re more flexible than legacyconverters. For example, theunsigned_int converter (and all theunsigned_ converters) can be specified withoutbitwise=True. Theirdefault behavior performs range checking on the value, and they won’t acceptnegative numbers. You just can’t do that with a legacy converter!

Argument Clinic will show you all the converters it hasavailable. For each converter it’ll show you all the parametersit accepts, along with the default value for each parameter.Just runTools/clinic/clinic.py--converters to see the full list.

Py_buffer¶

When using thePy_buffer converter(or the's*','w*','*y', or'z*' legacy converters),youmust not callPyBuffer_Release() on the provided buffer.Argument Clinic generates code that does it for you (in the parsing function).

Advanced converters¶

Remember those format units you skipped for your firsttime because they were advanced? Here’s how to handle those too.

The trick is, all those format units take arguments—eitherconversion functions, or types, or strings specifying an encoding.(But “legacy converters” don’t support arguments. That’s why weskipped them for your first function.) The argument you specifiedto the format unit is now an argument to the converter; thisargument is eitherconverter (forO&),subclass_of (forO!),orencoding (for all the format units that start withe).

When usingsubclass_of, you may also want to use the othercustom argument forobject():type, which lets you set the typeactually used for the parameter. For example, if you want to ensurethat the object is a subclass ofPyUnicode_Type, you probably wantto use the converterobject(type='PyUnicodeObject*',subclass_of='&PyUnicode_Type').

One possible problem with using Argument Clinic: it takes away some possibleflexibility for the format units starting withe. When writing aPyArg_Parse call by hand, you could theoretically decide at runtime whatencoding string to pass in toPyArg_ParseTuple(). But now this string mustbe hard-coded at Argument-Clinic-preprocessing-time. This limitation is deliberate;it made supporting this format unit much easier, and may allow for future optimizations.This restriction doesn’t seem unreasonable; CPython itself always passes in statichard-coded encoding strings for parameters whose format units start withe.

Parameter default values¶

Default values for parameters can be any of a number of values.At their simplest, they can be string, int, or float literals:

foo: str = "abc"bar: int = 123bat: float = 45.6

They can also use any of Python’s built-in constants:

yep:  bool = Truenope: bool = Falsenada: object = None

There’s also special support for a default value ofNULL, andfor simple expressions, documented in the following sections.

TheNULL default value¶

For string and object parameters, you can set them toNone to indicatethat there’s no default. However, that means the C variable will beinitialized toPy_None. For convenience’s sakes, there’s a specialvalue calledNULL for just this reason: from Python’s perspective itbehaves like a default value ofNone, but the C variable is initializedwithNULL.

Expressions specified as default values¶

The default value for a parameter can be more than just a literal value.It can be an entire expression, using math operators and looking up attributeson objects. However, this support isn’t exactly simple, because of somenon-obvious semantics.

Consider the following example:

foo: Py_ssize_t = sys.maxsize - 1

sys.maxsize can have different values on different platforms. ThereforeArgument Clinic can’t simply evaluate that expression locally and hard-code itin C. So it stores the default in such a way that it will get evaluated atruntime, when the user asks for the function’s signature.

What namespace is available when the expression is evaluated? It’s evaluatedin the context of the module the builtin came from. So, if your module has anattribute called “max_widgets”, you may simply use it:

foo: Py_ssize_t = max_widgets

If the symbol isn’t found in the current module, it fails over to looking insys.modules. That’s how it can findsys.maxsize for example. (Since youdon’t know in advance what modules the user will load into their interpreter,it’s best to restrict yourself to modules that are preloaded by Python itself.)

Evaluating default values only at runtime means Argument Clinic can’t computethe correct equivalent C default value. So you need to tell it explicitly.When you use an expression, you must also specify the equivalent expressionin C, using thec_default parameter to the converter:

foo: Py_ssize_t(c_default="PY_SSIZE_T_MAX - 1") = sys.maxsize - 1

Another complication: Argument Clinic can’t know in advance whether or not theexpression you supply is valid. It parses it to make sure it looks legal, butit can’tactually know. You must be very careful when using expressions tospecify values that are guaranteed to be valid at runtime!

Finally, because expressions must be representable as static C values, thereare many restrictions on legal expressions. Here’s a list of Python featuresyou’re not permitted to use:

• Function calls.

• Inline if statements (3iffooelse5).

• Automatic sequence unpacking (*[1,2,3]).

• List/set/dict comprehensions and generator expressions.

• Tuple/list/set/dict literals.

Using a return converter¶

By default the impl function Argument Clinic generates for you returnsPyObject*.But your C function often computes some C type, then converts it into thePyObject*at the last moment. Argument Clinic handles converting your inputs from Python typesinto native C types—why not have it convert your return value from a native C typeinto a Python type too?

That’s what a “return converter” does. It changes your impl function to returnsome C type, then adds code to the generated (non-impl) function to handle convertingthat value into the appropriatePyObject*.

The syntax for return converters is similar to that of parameter converters.You specify the return converter like it was a return annotation on thefunction itself. Return converters behave much the same as parameter converters;they take arguments, the arguments are all keyword-only, and if you’re not changingany of the default arguments you can omit the parentheses.

(If you use both"as"and a return converter for your function,the"as" should come before the return converter.)

There’s one additional complication when using return converters: how do youindicate an error has occurred? Normally, a function returns a valid (non-NULL)pointer for success, andNULL for failure. But if you use an integer return converter,all integers are valid. How can Argument Clinic detect an error? Its solution: each returnconverter implicitly looks for a special value that indicates an error. If you returnthat value, and an error has been set (PyErr_Occurred() returns a truevalue), then the generated code will propagate the error. Otherwise it willencode the value you return like normal.

Currently Argument Clinic supports only a few return converters:

boolintunsigned intlongunsigned intsize_tPy_ssize_tfloatdoubleDecodeFSDefault

None of these take parameters. For the first three, return -1 to indicateerror. ForDecodeFSDefault, the return type isconstchar*; return aNULLpointer to indicate an error.

(There’s also an experimentalNoneType converter, which lets youreturnPy_None on success orNULL on failure, without havingto increment the reference count onPy_None. I’m not sure it addsenough clarity to be worth using.)

To see all the return converters Argument Clinic supports, along withtheir parameters (if any),just runTools/clinic/clinic.py--converters for the full list.

Cloning existing functions¶

If you have a number of functions that look similar, you may be able touse Clinic’s “clone” feature. When you clone an existing function,you reuse:

• its parameters, including

  • their names,

  • their converters, with all parameters,

  • their default values,

  • their per-parameter docstrings,

  • theirkind (whether they’re positional only,positional or keyword, or keyword only), and

• its return converter.

The only thing not copied from the original function is its docstring;the syntax allows you to specify a new docstring.

Here’s the syntax for cloning a function:

/*[clinic input]module.class.new_function [as c_basename] = module.class.existing_functionDocstring for new_function goes here.[clinic start generated code]*/

(The functions can be in different modules or classes. I wrotemodule.class in the sample just to illustrate that you mustuse the full path toboth functions.)

Sorry, there’s no syntax for partially-cloning a function, or cloning a functionthen modifying it. Cloning is an all-or nothing proposition.

Also, the function you are cloning from must have been previously definedin the current file.

Calling Python code¶

The rest of the advanced topics require you to write Python codewhich lives inside your C file and modifies Argument Clinic’sruntime state. This is simple: you simply define a Python block.

A Python block uses different delimiter lines than an ArgumentClinic function block. It looks like this:

/*[python input]# python code goes here[python start generated code]*/

All the code inside the Python block is executed at thetime it’s parsed. All text written to stdout inside the blockis redirected into the “output” after the block.

As an example, here’s a Python block that adds a static integervariable to the C code:

/*[python input]print('static int __ignored_unused_variable__ = 0;')[python start generated code]*/staticint__ignored_unused_variable__=0;/*[python checksum:...]*/

Using a “self converter”¶

Argument Clinic automatically adds a “self” parameter for youusing a default converter. It automatically sets thetypeof this parameter to the “pointer to an instance” you specifiedwhen you declared the type. However, you can overrideArgument Clinic’s converter and specify one yourself.Just add your ownself parameter as the first parameter in ablock, and ensure that its converter is an instance ofself_converter or a subclass thereof.

What’s the point? This lets you override the type ofself,or give it a different default name.

How do you specify the custom type you want to castself to?If you only have one or two functions with the same type forself,you can directly use Argument Clinic’s existingself converter,passing in the type you want to use as thetype parameter:

/*[clinic input]_pickle.Pickler.dump  self: self(type="PicklerObject *")  obj: object  /Write a pickled representation of the given object to the open file.[clinic start generated code]*/

On the other hand, if you have a lot of functions that will use the sametype forself, it’s best to create your own converter, subclassingself_converter but overwriting thetype member:

/*[python input]class PicklerObject_converter(self_converter):    type = "PicklerObject *"[python start generated code]*//*[clinic input]_pickle.Pickler.dump  self: PicklerObject  obj: object  /Write a pickled representation of the given object to the open file.[clinic start generated code]*/

Writing a custom converter¶

As we hinted at in the previous section… you can write your own converters!A converter is simply a Python class that inherits fromCConverter.The main purpose of a custom converter is if you have a parameter usingtheO& format unit—parsing this parameter means callingaPyArg_ParseTuple() “converter function”.

Your converter class should be named*something*_converter.If the name follows this convention, then your converter classwill be automatically registered with Argument Clinic; its namewill be the name of your class with the_converter suffixstripped off. (This is accomplished with a metaclass.)

You shouldn’t subclassCConverter.__init__. Instead, you shouldwrite aconverter_init() function.converter_init()always accepts aself parameter; after that, all additionalparametersmust be keyword-only. Any arguments passed in tothe converter in Argument Clinic will be passed along to yourconverter_init().

There are some additional members ofCConverter you may wishto specify in your subclass. Here’s the current list:

type

The C type to use for this variable.type should be a Python string specifying the type, e.g.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().

Here’s the simplest example of a custom converter, fromModules/zlibmodule.c:

/*[python input]class ssize_t_converter(CConverter):    type = 'Py_ssize_t'    converter = 'ssize_t_converter'[python start generated code]*//*[python end generated code: output=da39a3ee5e6b4b0d input=35521e4e733823c7]*/

This block adds a converter to Argument Clinic namedssize_t. Parametersdeclared asssize_t will be declared as typePy_ssize_t, and willbe parsed by the'O&' format unit, which will call thessize_t_converter converter function.ssize_t variablesautomatically support default values.

More sophisticated custom converters can insert custom C code tohandle initialization and cleanup.You can see more examples of custom converters in the CPythonsource tree; grep the C files for the stringCConverter.

Writing a custom return converter¶

Writing a custom return converter is much like writinga custom converter. Except it’s somewhat simpler, because returnconverters are themselves much simpler.

Return converters must subclassCReturnConverter.There are no examples yet of custom return converters,because they are not widely used yet. If you wish towrite your own return converter, please readTools/clinic/clinic.py,specifically the implementation ofCReturnConverter andall its subclasses.

METH_O and METH_NOARGS¶

To convert a function usingMETH_O, make sure the function’ssingle argument is using theobject converter, and mark thearguments as positional-only:

/*[clinic input]meth_o_sample     argument: object     /[clinic start generated code]*/

To convert a function usingMETH_NOARGS, just don’t specifyany arguments.

You can still use a self converter, a return converter, and specifyatype argument to the object converter forMETH_O.

tp_new and tp_init functions¶

You can converttp_new andtp_init functions. Just namethem__new__ or__init__ as appropriate. Notes:

• The function name generated for__new__ doesn’t end in__new__like it would by default. It’s just the name of the class, convertedinto a valid C identifier.

• NoPyMethodDef#define is generated for these functions.

• __init__ functions returnint, notPyObject*.

• Use the docstring as the class docstring.

• Although__new__ and__init__ functions must alwaysaccept both theargs andkwargs objects, when convertingyou may specify any signature for these functions that you like.(If your function doesn’t support keywords, the parsing functiongenerated will throw an exception if it receives any.)

Changing and redirecting Clinic’s output¶

It can be inconvenient to have Clinic’s output interspersed withyour conventional hand-edited C code. Luckily, Clinic is configurable:you can buffer up its output for printing later (or earlier!), or writeits output to a separate file. You can also add a prefix or suffix toevery line of Clinic’s generated output.

While changing Clinic’s output in this manner can be a boon to readability,it may result in Clinic code using types before they are defined, oryour code attempting to use Clinic-generated code before it is defined.These problems can be easily solved by rearranging the declarations in your file,or moving where Clinic’s generated code goes. (This is why the default behaviorof Clinic is to output everything into the current block; while many peopleconsider this hampers readability, it will never require rearranging yourcode to fix definition-before-use problems.)

Let’s start with defining some terminology:

field

A field, in this context, is a subsection of Clinic’s output.For example, the#define for thePyMethodDef structureis a field, calledmethoddef_define. Clinic has sevendifferent fields it can output per function definition:

docstring_prototypedocstring_definitionmethoddef_defineimpl_prototypeparser_prototypeparser_definitionimpl_definition

All the names are of the form"<a>_<b>",where"<a>" is the semantic object represented (the parsing function,the impl function, the docstring, or the methoddef structure) and"<b>"represents what kind of statement the field is. Field names that end in"_prototype"represent forward declarations of that thing, without the actual body/dataof the thing; field names that end in"_definition" represent the actualdefinition of the thing, with the body/data of the thing. ("methoddef"is special, it’s the only one that ends with"_define", representing thatit’s a preprocessor #define.)

destination

A destination is a place Clinic can write output to. There arefive built-in destinations:

block

The default destination: printed in the output section ofthe current Clinic block.

buffer

A text buffer where you can save text for later. Text senthere is appended to the end of any existing text. It’s anerror to have any text left in the buffer when Clinic finishesprocessing a file.

file

A separate “clinic file” that will be created automatically by Clinic.The filename chosen for the file is{basename}.clinic{extension},wherebasename andextension were assigned the outputfromos.path.splitext() run on the current file. (Example:thefile destination for_pickle.c would be written to_pickle.clinic.c.)

Important: When using afiledestination, youmust check inthe generated file!

two-pass

A buffer likebuffer. However, a two-pass buffer can onlybe dumped once, and it prints out all text sent to it duringall processing, even from Clinic blocksafter the dumping point.

suppress

The text is suppressed—thrown away.

Clinic defines five new directives that let you reconfigure its output.

The first new directive isdump:

dump <destination>

This dumps the current contents of the named destination into the output ofthe current block, and empties it. This only works withbuffer andtwo-pass destinations.

The second new directive isoutput. The most basic form ofoutputis like this:

output <field> <destination>

This tells Clinic to outputfield todestination.output alsosupports a special meta-destination, calledeverything, which tellsClinic to outputall fields to thatdestination.

output has a number of other functions:

output pushoutput popoutput preset <preset>

outputpush andoutputpop allow you to push and popconfigurations on an internal configuration stack, so that youcan temporarily modify the output configuration, then easily restorethe previous configuration. Simply push before your change to savethe current configuration, then pop when you wish to restore theprevious configuration.

outputpreset sets Clinic’s output to one of several built-inpreset configurations, as follows:

block

Clinic’s original starting configuration. Writes everythingimmediately after the input block.

Suppress theparser_prototypeanddocstring_prototype, write everything else toblock.

file

Designed to write everything to the “clinic file” that it can.You then#include this file near the top of your file.You may need to rearrange your file to make this work, thoughusually this just means creating forward declarations for varioustypedef andPyTypeObject definitions.

Suppress theparser_prototypeanddocstring_prototype, write theimpl_definition toblock, and write everything else tofile.

The default filename is"{dirname}/clinic/{basename}.h".

buffer

Save up most of the output from Clinic, to be written intoyour file near the end. For Python files implementing modulesor builtin types, it’s recommended that you dump the bufferjust above the static structures for your module orbuiltin type; these are normally very near the end. Usingbuffer may require even more editing thanfile, ifyour file has staticPyMethodDef arrays defined in themiddle of the file.

Suppress theparser_prototype,impl_prototype,anddocstring_prototype, write theimpl_definition toblock, and write everything else tofile.

two-pass

Similar to thebuffer preset, but writes forward declarations tothetwo-pass buffer, and definitions to thebuffer.This is similar to thebuffer preset, but may requireless editing thanbuffer. Dump thetwo-pass buffernear the top of your file, and dump thebuffer nearthe end just like you would when using thebuffer preset.

Suppresses theimpl_prototype, write theimpl_definitiontoblock, writedocstring_prototype,methoddef_define,andparser_prototype totwo-pass, write everything elsetobuffer.

partial-buffer

Similar to thebuffer preset, but writes more things toblock,only writing the really big chunks of generated code tobuffer.This avoids the definition-before-use problem ofbuffer completely,at the small cost of having slightly more stuff in the block’s output.Dump thebuffer near the end, just like you would when usingthebuffer preset.

Suppresses theimpl_prototype, write thedocstring_definitionandparser_definition tobuffer, write everything else toblock.

The third new directive isdestination:

destination <name> <command> [...]

This performs an operation on the destination namedname.

There are two defined subcommands:new andclear.

Thenew subcommand works like this:

destination <name> new <type>

This creates a new destination with name<name> and type<type>.

There are five destination types:

suppress

Throws the text away.

block

Writes the text to the current block. This is what Clinicoriginally did.

buffer

A simple text buffer, like the “buffer” builtin destination above.

file

A text file. The file destination takes an extra argument,a template to use for building the filename, like so:

destination <name> new <type> <file_template>

The template can use three strings internally that will be replacedby bits of the filename:

{path}

The full path to the file, including directory and full filename.

{dirname}

The name of the directory the file is in.

{basename}

Just the name of the file, not including the directory.

{basename_root}

Basename with the extension clipped off(everything up to but not including the last ‘.’).

{basename_extension}

The last ‘.’ and everything after it. If the basenamedoes not contain a period, this will be the empty string.

If there are no periods in the filename, {basename} and {filename}are the same, and {extension} is empty. “{basename}{extension}”is always exactly the same as “{filename}”.”

two-pass

A two-pass buffer, like the “two-pass” builtin destination above.

Theclear subcommand works like this:

destination <name> clear

It removes all the accumulated text up to this point in the destination.(I don’t know what you’d need this for, but I thought maybe it’d beuseful while someone’s experimenting.)

The fourth new directive isset:

set line_prefix "string"set line_suffix "string"

set lets you set two internal variables in Clinic.line_prefix is a string that will be prepended to every line of Clinic’s output;line_suffix is a string that will be appended to every line of Clinic’s output.

Both of these support two format strings:

{blockcommentstart}

Turns into the string/*, the start-comment text sequence for C files.

{blockcommentend}

Turns into the string*/, the end-comment text sequence for C files.

The final new directive is one you shouldn’t need to use directly,calledpreserve:

preserve

This tells Clinic that the current contents of the output should be kept, unmodified.This is used internally by Clinic when dumping output intofile files; wrappingit in a Clinic block lets Clinic use its existing checksum functionality to ensurethe file was not modified by hand before it gets overwritten.

The #ifdef trick¶

If you’re converting a function that isn’t available on all platforms,there’s a trick you can use to make life a little easier. The existingcode probably looks like this:

#ifdef HAVE_FUNCTIONNAMEstaticmodule_functionname(...){...}#endif/* HAVE_FUNCTIONNAME */

And then in thePyMethodDef structure at the bottom the existing codewill have:

#ifdef HAVE_FUNCTIONNAME{'functionname', ... },#endif /* HAVE_FUNCTIONNAME */

In this scenario, you should enclose the body of your impl function inside the#ifdef,like so:

#ifdef HAVE_FUNCTIONNAME/*[clinic input]module.functionname...[clinic start generated code]*/staticmodule_functionname(...){...}#endif/* HAVE_FUNCTIONNAME */

Then, remove those three lines from thePyMethodDef structure,replacing them with the macro Argument Clinic generated:

MODULE_FUNCTIONNAME_METHODDEF

(You can find the real name for this macro inside the generated code.Or you can calculate it yourself: it’s the name of your function as definedon the first line of your block, but with periods changed to underscores,uppercased, and"_METHODDEF" added to the end.)

Perhaps you’re wondering: what ifHAVE_FUNCTIONNAME isn’t defined?TheMODULE_FUNCTIONNAME_METHODDEF macro won’t be defined either!

Here’s where Argument Clinic gets very clever. It actually detects that theArgument Clinic block might be deactivated by the#ifdef. When thathappens, it generates a little extra code that looks like this:

#ifndef MODULE_FUNCTIONNAME_METHODDEF#define MODULE_FUNCTIONNAME_METHODDEF#endif/* !defined(MODULE_FUNCTIONNAME_METHODDEF) */

That means the macro always works. If the function is defined, this turnsinto the correct structure, including the trailing comma. If the function isundefined, this turns into nothing.

However, this causes one ticklish problem: where should Argument Clinic put thisextra code when using the “block” output preset? It can’t go in the output block,because that could be deactivated by the#ifdef. (That’s the whole point!)

In this situation, Argument Clinic writes the extra code to the “buffer” destination.This may mean that you get a complaint from Argument Clinic:

Warning in file "Modules/posixmodule.c" on line 12357:Destination buffer 'buffer' not empty at end of file, emptying.

When this happens, just open your file, find thedumpbuffer block thatArgument Clinic added to your file (it’ll be at the very bottom), thenmove it above thePyMethodDef structure where that macro is used.

Using Argument Clinic in Python files¶

It’s actually possible to use Argument Clinic to preprocess Python files.There’s no point to using Argument Clinic blocks, of course, as the outputwouldn’t make any sense to the Python interpreter. But using Argument Clinicto run Python blocks lets you use Python as a Python preprocessor!

Since Python comments are different from C comments, Argument Clinicblocks embedded in Python files look slightly different. They look like this:

#/*[python input]#print("def foo(): pass")#[python start generated code]*/deffoo():pass#/*[python checksum:...]*/