Argument Clinic "converters" specify how to convert an individual
argument to the function you're defining. Although a converter
could theoretically represent any sort of conversion, most of the
time they directly represent types like "int" or "double" or "str".
Because there's such variety in argument parsing, the converters are
customizable with parameters. Many of these are common enough that
Argument Clinic suggests some standard names. Examples:
"zeroes=True" for strings and buffers means "permit internal \0
characters", and "bitwise=True" for unsigned integers means "copy
the bits over, even if there's overflow/underflow, and even if the
original is negative".
A third example is "nullable=True", which means "also accept None
for this parameter". This was originally intended for use with
strings (compare the "s" and "z" format units for PyArg_ParseTuple),
however it looks like we'll have a use for "nullable ints" in the
ongoing Argument Clinic conversion work.
Several people have said they found the name "nullable" surprising,
suggesting I use another name like "allow_none" or "noneable". I,
in turn, find their surprise surprising; "nullable" is a term long
associated with exactly this concept. It's used in C# and SQL, and
the term even has its own Wikipedia page:
http://en.wikipedia.org/wiki/Nullable_type
Most amusingly, Vala *used* to have an annotation called
"(allow-none)", but they've broken it out into two annotations,
"(nullable)" and "(optional)".
http://blogs.gnome.org/desrt/2014/05/27/allow-none-is-dead-long-live-nullable/
Before you say "the term 'nullable' will confuse end users", let me
remind you: this is not user-facing. This is a parameter for an
Argument Clinic converter, and will only ever be seen by CPython
core developers. A group which I hope is not so easily confused.
It's my contention that "nullable" is the correct name. But I've
been asked to bring up the topic for discussion, to see if a
consensus forms around this or around some other name.
Let the bike-shedding begin,
/arry