This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Clean up Clinic's type expressions of buffers
Type: behavior Stage: resolved
Components: Argument Clinic Versions: Python 3.5
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 2022-04-11 14:58 by admin. This issue is now closed.

File name Uploaded Description Edit larry, 2015-04-13 16:54 review larry, 2015-04-13 20:00 review larry, 2015-04-14 18:21 review 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


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)

actually checks / specifically handles bytes objects

actually checks / specifically handles bytearray objects

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) (Python triager) Date: 2015-04-16 03:02
New changeset 4f74452a11e5 by Larry Hastings in branch 'default':
Issue #23935: Argument Clinic's understanding of format units
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!
Date User Action Args
2022-04-11 14:58:15adminsetgithub: 68123
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: +

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: +

messages: + msg240975
2015-04-14 09:14:11serhiy.storchakasetmessages: + msg240861
2015-04-13 20:00:27larrysetfiles: +

messages: + msg240720
2015-04-13 16:54:40larrysetfiles: +

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