classification
Title: Clean up Clinic's type expressions of buffers
Type: behavior Stage: resolved
Components: Argument Clinic Versions: Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: larry Nosy List: larry, pdmccormick, python-dev, serhiy.storchaka, zach.ware
Priority: normal Keywords:

Created on 2015-04-13 16:53 by larry, last changed 2015-04-16 03:03 by larry. This issue is now closed.

Files
File name Uploaded Description Edit
larry.clinic.buffer.conceptual.cleanup.1.txt larry, 2015-04-13 16:54 review
larry.clinic.buffer.conceptual.cleanup.2.txt larry, 2015-04-13 20:00 review
larry.clinic.buffer.conceptual.cleanup.3.txt larry, 2015-04-14 18:21 review
larry.clinic.buffer.conceptual.cleanup.4.txt larry, 2015-04-15 04:13 review
Messages (11)
msg240660 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-04-13 16:53
Clinic was previously pretty confused about what things accepted "bytes", "bytearray", "buffer", "robuffer", and "rwbuffer".  This is because the documentation itself was somewhat confusing.

The documentation was recently cleaned up on these in trunk (including one final fix from me this morning).  This patch cleans up Clinic's understanding of how the types map to the format units.

My notes on how the format units map to types is copy & pasted below.

--


the documentation for format units is a little confused, and it is therefore confusing

inside:


getbuffer (buffer)
y* s* z*
  uses PyObject_GetBuffer(arg, view, PyBUF_SIMPLE)
  requires PyBuffer_IsContiguous(view, 'C')
  doesn't check specifically for bytes objects
  handles bytes objects
  accepts bytesarray
 

convertbuffer (robuffer)
y y# s# z#
  handles "read-only buffer object",
  all it really does is ensure it doesn't have a pb_releasebuffer,
  then call getbuffer() above

  so it doesn't accept bytesarray, *just because*


doesn't accept bytes
s z es es#

requires writeable buffer (rwbuffer)
w*

actually checks / specifically handles bytes objects
S

actually checks / specifically handles bytearray objects
Y

actually checks / specifically handles bytes and bytearray objects
c et et#
msg240661 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-04-13 16:54
Huh.  Why didn't it attach my patch?  Here it is.
msg240720 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-04-13 20:00
Updated the patch a little, to make it enforce compatible "types" parameters.  The previous patch had some functions that would permit passing in "types='blah de blah'" or other nonsense.
msg240861 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-04-14 09:14
Added few comments on Rietveld.
msg240975 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-04-14 18:21
New patch revision, including the new API change (the "types" argument to a constructor must now be a set of strings).
msg241030 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-04-14 21:11
The new API change looks doubtful for me. It is more verbose. And less readable. It makes harder to search in sources, because {'str', 'robuffer'} is the same as {'robuffer', 'str'}. If Argument Clinic would a tool with programmatic API, sets would make sense, but for now the main interface of Argument Clinic is text inclusions in C files.

If you want to convert the types parameter into a set, is it possible to continue to accept strings? Many user-friendly APIs accept either a sequence of string names or a string containing space-separated names. For example namedtuple, Enum.
msg241078 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-04-15 03:56
In the case of namedtuple and Enum, the parameter represents a sequence of strings--order is significant.  With the 'types' parameter for converters, the internal model was always meant to be a *set* of strings.  The order was explicitly *not* significant.  So types="str robuffer" and types="robuffer str" should be identical.  Your "harder to search in sources" was already true.

Argument Clinic isn't something very many people will learn.  Lots of people will read the conversions, but few will ever write a conversion, and they won't do it often and they'll forget the funny details. So we shouldn't make the API quirky and succinct at the expense of readability.  The best API will be one that makes the code easier to read.

I think requiring types to be a set of strings makes it easier to read because it makes the semantics obvious.  If you see
   types="str robuffer"
you aren't sure if order is significant, but if you see
   types={'str', 'robuffer'}
you are certain it is not.
msg241080 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-04-15 04:13
Latest patch, with another round of lovely comments from Serhiy.
msg241087 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-04-15 06:39
Many people will see Argument Clinic syntax in declarations in C files. My recent patches (for _io, _ssl and _codecs modules) adds many types=. But I agree that there are many reasons to make this change.

The patch LGTM. You can factorize it more if you like.
msg241193 - (view) Author: Roundup Robot (python-dev) Date: 2015-04-16 03:02
New changeset 4f74452a11e5 by Larry Hastings in branch 'default':
Issue #23935: Argument Clinic's understanding of format units
https://hg.python.org/cpython/rev/4f74452a11e5
msg241194 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-04-16 03:03
While cleaning this up I noticed that es# and et# should both require "nullable".  Fixed that too.  I sure hope it's all correct now!
History
Date User Action Args
2015-04-16 03:03:37larrysetstatus: open -> closed
resolution: fixed
messages: + msg241194

stage: patch review -> resolved
2015-04-16 03:02:29python-devsetnosy: + python-dev
messages: + msg241193
2015-04-15 06:39:06serhiy.storchakasetmessages: + msg241087
2015-04-15 04:13:02larrysetfiles: + larry.clinic.buffer.conceptual.cleanup.4.txt

messages: + msg241080
2015-04-15 03:56:27larrysetmessages: + msg241078
2015-04-14 22:51:44pdmccormicksetnosy: + pdmccormick
2015-04-14 21:11:04serhiy.storchakasetmessages: + msg241030
2015-04-14 18:21:28larrysetfiles: + larry.clinic.buffer.conceptual.cleanup.3.txt

messages: + msg240975
2015-04-14 09:14:11serhiy.storchakasetmessages: + msg240861
2015-04-13 20:00:27larrysetfiles: + larry.clinic.buffer.conceptual.cleanup.2.txt

messages: + msg240720
2015-04-13 16:54:40larrysetfiles: + larry.clinic.buffer.conceptual.cleanup.1.txt

messages: + msg240661
2015-04-13 16:53:53larrycreate