[Python-Dev] The docstring hack for signature information has to go

Antoine Pitrou solipsis at pitrou.net
Mon Feb 3 23:26:05 CET 2014


On Mon, 03 Feb 2014 06:43:31 -0800
Larry Hastings <larry at hastings.org> wrote:
> 
> A: We create a PyMethodDefEx structure with an extra field: "const char 
> *signature".  We add a new METH_SIGNATURE (maybe just METH_SIG?) flag to 
> the flags, indicating that this is an extended structure.  When 
> iterating over the PyMethodDefs, we know how far to advance the pointer 
> based on this flag.

How do you create an array that mixes PyMethodDefs and PyMethodDefExs
together? It sounds like METH_SIGNATURE is the wrong mechanism.
Instead, you may want a tp_methods_ex as well as as a
Py_TPFLAGS_HAVE_METHODS_EX.

> B: Same as A, but we add three unused pointers (void *reserved1 etc) to 
> PyMethodDefEx to give us some room to grow.

Note that this constrains future growth to only add pointer fields,
unless you also add a couple of long fields. But at least it sounds
workable.

> C: Same as A, but we add two fields to PyMethodDefEx.  The second new 
> field identifies the "version" of the structure, telling us its size 
> somehow.  Like the lStructSize field of the OPENFILENAME structure in 
> Win32.  I suspect YAGNI.

That doesn't work. The size of elements of a C array is constant, so you
can't "mix and match" PyMethodDefExs of different versions with
different sizes each.

> Solution: we write a function (which users would have to copy into their 
> extension) that gives a PyMethodDefEx array to 3.4+, but converts it 
> into a PyMethodDef array for 3.3.  The tricky part there: what do we do 
> about the docstring?  The convention for builtins is to have the first 
> line(s) contain a handwritten signature.  But you *don't* want that if 
> you provide a signature, because help() will read that signature and 
> automatically render this first line for you.

Uh... If you write a "conversion function", you may as well make it so
it converts the "sig=" line to a plain signature line in 3.3, which
avoids the issue entirely.

(and how would that conversion function be shipped to the user anyway?
Python 3.3 and the stable ABI don't have it)

Regards

Antoine.




More information about the Python-Dev mailing list