[Python-Dev] New policies for the Derby -- please read!

Larry Hastings larry at hastings.org
Sat Jan 25 13:19:18 CET 2014



1) New policy for what can and cannot be converted during the Derby

First, let me apologize for only figuring this out now.  The Derby has 
been a learning process, discovering things that Argument Clinic didn't 
handle.  And there were a lot of funny edge cases that we weren't going 
to discover until we tried doing the conversion.  And to be honest I was 
pushing harder than I should have.

*ahem*

The new policy for conversion work for Python 3.4:

    We may only convert functions that have signatures that we can
    represent 100% accurately in an inspect.Signature object.

    IF the function has a default value that can't be represented in
    Python (e.g. NULL), but we can find a value in Python that behaves
    identically to not passing in that parameter (e.g. _sha1.sha1(b'')
    == _sha1.sha1()), then we may convert that function using that
    clever default value (e.g. "string: object(c_default='NULL') = b'' ").

    IF the function has parameters with default values that are dynamic
    or cannot be represented accurately in Python, it cannot be
    converted without changing its semantics.  So it cannot be converted
    for 3.4.

    IF the function *requires* "optional groups" (as in, the original
    function used switch(PyTuple_GET_SIZE(args)) and multiple calls to
    PyArg_ParseTuple()), then it's permissible to convert it for 3.4,
    but they are low priority.  Such functions have semantics that are
    so weird, we will have to modify inspect.Parameter to support them,
    and that will only happen in 3.5.  However, I will ensure that they
    otherwise convert correctly for 3.4.  (They won't actually generate
    signatures.  They will however generate the first line of the
    docstring.)


For 3.5, I expect we'll have more leeway in doing things like "this 
should accept an int or None".  But we should talk about that then.

If you have patches outstanding that convert functions that shouldn't be 
converted for 3.4, please put them aside.  We can almost certainly use 
them for 3.5.

If any conversions have been committed that change the semantics of the 
function, someone will have to back them out.  I'd appreciate it if the 
person who checked it in could do it.  I expect to make a pass before 
rc1 to check all the conversions myself.  (Which I hope will be quite 
time-consuming, as hopefully there will be lots of converted functions 
by then!)


_______________________________________________________________________________

2) New recommendation for marking to-do functions

If you examine a function and determine that it can't be converted to 
Argument Clinic right now, please add a comment to that effect. The 
comment should be one line, and contain a special marker so we can find 
it easily with searches.

I nominate two different markers:

"AC 3.4"  means "It's okay to convert this function to Argument Clinic 
in 3.4, but it can't be converted right now because of a bug or missing 
feature in Argument Clinic."

"AC 3.5" means "This function can't be converted to Argument Clinic in 
3.4, it must wait for 3.5."

I encourage you to add a little text saying why, like:

    /* AC 3.4: waiting for *args support */
    /* AC 3.5: value parameter has default value of NULL */


_______________________________________________________________________________

Finally, I've realized that right now there's no good way to stay 
abreast of what's new and changing in clinic.py.  I check in a patch 
just about every day for clinic.py, and sometimes I don't remember to 
update the "howto".  The best way unfortunately is to read the output of 
"hg log".

If you have questions, you can email me directly at "larry at hastings 
dot org", or you can find me in the #python-dev IRC channel.


Thank you, everybody who's participating in the Derby, and again I'm 
sorry I didn't realize sooner this *had* to be the policy for 3.4.

Hope to see your issues in the tracker,


/arry
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20140125/53399d93/attachment.html>


More information about the Python-Dev mailing list