4.5 Using real Argument Clinic converters, instead of “legacy converters” In addition, some converters accept additional arguments. Here is a list of these arguments, along with their meanings: Notes: • For every optional group, one additional parameter will be passed into the impl function representing the group. The parameter will be an int named$_{group_{direction}_{number}}$, where$_{{direction}}$ is either right or left depending on whether the group is before or after the required parameters, and {number} is a monotonically increasing number (starting at 1) indicating how far away the group is from the required parameters. When the impl is called, this parameter will be set to 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 arguments in this invocation.) • If there are no required arguments, the optional groups will behave as if they’re to the right of the required arguments. • In the case of ambiguity, the argument parsing code favors parameters on the left (before the required param- eters). • Optional groups can only contain positional-only parameters. • Optional groups are only intended for legacy code. Please do not use optional groups for new code. To save time, and to minimize how much you need to learn to achieve your first port to Argument Clinic, the walk- through above tells you to use “legacy converters”. “Legacy converters” are a convenience, designed explicitly to make porting existing code to Argument Clinic easier. And to be clear, their use is acceptable when porting code for Python 3.4. However, in the long term we probably want all our blocks to use Argument Clinic’s real syntax for converters. Why? A couple reasons: • 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’t support specifying arguments. • In the future we may have a new argument parsing library that isn’t restricted to what PyArg_ParseTuple() supports; this flexibility won’t be available to parameters using legacy con- verters. Therefore, if you don’t mind a little extra effort, please use the normal converters instead of legacy converters. In a nutshell, the syntax for Argument Clinic (non-legacy) converters looks like a Python function call. However, if there are no explicit arguments to the function (all functions take their default values), you may omit the parentheses. Thus$_{bool}$and$_{bool()}$ are exactly the 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 declared in the “parse function”. See the section on default values for how to use this. Specified as a string. $_{annotation}$The annotation value for this parameter. Not currently supported, because PEP 8 man- dates that the Python library may not use annotations. $_{accept}$A set of Python types (and possibly pseudo-types); this restricts the allowable Python argu- ment to values of these types. (This is not a general-purpose facility; as a rule it only supports specific lists of types as shown in the legacy converter table.) To accept$_{None}$ , add$_{NoneType}$ to this set. bitwise Only supported for unsigned integers. The native integer value of this Python argument will be written to the parameter without any range checking, even for negative values. 11