OK, I'll have a go at the PEP then. In addition to the proposed syntax
in my previous mail, I'm going to suggest this alternative:

/*[preprocessor]
# Declaration
os.stat [PyOs_Stat] (
  { path: [string, bytes, int] => path_converter => path_t },
  *,
  { dir_fd: [int, None] = None => OS_STAT_DIR_FD_CONVERTER => int },
  { follow_symlinks: bool = True => "p" => int }
) -> stat_result

# User code
path_t path = PATH_T_INITIALIZE("stat", 0, 1);
int dir_fd = DEFAULT_DIR_FD;
int follow_symlinks = 1;
[preprocessor]*/

It's a slight abuse of notation, since it looks like function composition.
The advantage is that the LHS of the first arrow is a complete legal Python
argument spec together with the type annotation.

The construct should be viewed like a Unix pipe and be read somewhat like:

Pass argument dir_fd of type [int, None], initialized to the default value
None to function OS_STAT_DIR_FD_CONVERTER, which yields a C int.

Both versions carry precisely the same amount of information. I have no strong
preference for either version, but perhaps other people do.

Regarding the positional arguments with groups, I'm suggesting this construct
for window.addch():

/*[preprocessor]
# Declaration
window.addch [addch] (
  { y: int => "i" => int },
  { x: int => "i" => int },
  { ch: int => "O" => PyObject * },
  { attr: int => "l" => long }
) -> None

WHERE groups = { [ch], [ch, attr], [y, x, ch], [y, x, ch, attr] }
[preprocessor]*/

The top part is largely the same as in the os.stat() example, the WHERE
clause means:

  - If you pass a single argument, it will be interpreted as "ch"

  - If you pass two arguments, they will be interpreted as "ch, attr"

  [and so forth ...]