[Python-Dev] [Python-checkins] peps: New DSL syntax and slightly changed semantics for the Argument Clinic DSL.

[Stefan Krah]

[PEP 436 revised syntax]

While I like the syntax better and appreciate the option to condense the
function declaration I still fear that the amount of implicitness will
distract from what is important: programming in C.

This applies especially if people start declaring converters using the
[python] feature.

So I hope that at least converters can be declared statically in a header
file, like I suggested in PEP 437.


A couple of comments:


> 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.

What is the source for this? I seem to remember a discussion on python-ideas
(but cannot find it now) where some developers preferred non-keyword functions
for some use cases.

For example it's strange to write div(x=10, y=3), or worse, div(y=3, x=10).
Using positional-only arguments prevents this "feature".


>  /*[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.

I do not see where the C initialization or the cleanup are specified. Are
they part of the converter specification?


> /*[clinic]
> curses.window.addch
>
>    [
>    x: int
>      X-coordinate.
>
>    y: int
>      Y-coordinate.
>    ]

The parameters appear to be in the wrong order.


> The return annotation is also optional.  If skipped, the arrow ("``->``")
> must also be omitted.

Why is it optional? Aren't type annotations important?


> Clinic will ship with a number of built-in converters; new converters can
> also be added dynamically.

How are the converters specified? Inside the preprocessor source? Are initialization
and cleanup part of the specification, e.g. is a converter represented by a class?

I would prefer if the converters were in a header file, like I suggested in
PEP 437. Any tool can read such a file and custom converters can be redeclared
above their definition.


> The default value is dynamically assigned, "live" in the generated C code,
> and although it's specified as a Python value, it's translated into a native
> C value in the generated C code. Few default values are permitted, owing to
> this manual translation step.

I think there should be a table that lists which values are converted and what
the result of the conversion is.


> ``[``
>    Establishes the start of an optional "group" of parameters.
>    Note that "groups" may nest inside other "groups".
>    See `Functions With Positional-Only Parameters`_ below.

I don't quite understand the terminology: Functions with the ``/`` are also
"positional-only".  Why not reserve this syntax exclusively for the legacy
left-and-right optional case?


> ``/``
>    This hints to Argument Clinic that this function is performance-sensitive,
>    and that it's acceptable to forego supporting keyword parameters when parsing.
>    (In early implementations of Clinic, this will switch Clinic from generating
>    code using ``PyArg_ParseTupleAndKeywords`` to using ``PyArg_ParseTuple``.
>    The hope is that in the future there will be no appreciable speed difference,
>    rendering this syntax irrelevant and deprecated but harmless.)

Here I would use "positional-only" and mention that the slash plays essentially
the same role as the vertical bar in the existing syntax. If this isn't the
intention, then I simply did not understand the paragraph.


> types
>
>    A list of strings representing acceptable Python types for this object.
>    There are also four strings which represent Python protocols:

I don't quite follow: Aren't input types always specified by the converter
function?


> Argument Clinic also permits embedding Python code inside C files, which
> is executed in-place when Argument Clinic processes the file. Embedded code
> looks like this:

The example in posixmodule.c takes up a lot of space and from the perspective
of auditing the effects it's a little like following a longjmp.



Stefan Krah