[issue8925] Improve c-api/arg.rst: use "bytes" or "str" types instead of "string"
New submission from STINNER Victor <victor.stinner@haypocalc.com>: http://docs.python.org/py3k/c-api/arg.html is unclear about what is a "string". Attached patch: - Use directly bytes, bytearray and str types - Replace "default encoding" by "``'utf-8'`` encoding" - Add bytes and/or bytearray to "... buffer compatible object" because it's not easy to understand what is a buffer compatible object, especially because there are different kind of buffer objects: read-only, read-write, pinned, etc. - Fix reST syntax ("..note ::") - Fix "es", "es#", "et" and "et#" formats: they doesn't accept "character buffer compatible object" (can someone double check that?) Py_BuildValue(): I choosed to mark U and U# formats as deprecated alias to s/s# => see issue #8848. I wrote the patch by reading getargs.c. ---------- assignee: docs@python components: Documentation, Unicode files: arg.patch keywords: patch messages: 107209 nosy: docs@python, haypo priority: normal severity: normal status: open title: Improve c-api/arg.rst: use "bytes" or "str" types instead of "string" versions: Python 3.2 Added file: http://bugs.python.org/file17576/arg.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8925> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: - buffer protocol (such as :class:`bytes` or :class:`bytearray` objects). + buffer protocol. Is there a reST construct to use here, say to reference a PEP or point to a glossary entry that defines this protocol? ---------- nosy: +merwok _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8925> _______________________________________
Georg Brandl <georg@python.org> added the comment: If there is a glossary entry, use :term:`buffer protocol`. If there is none, write one :) PEPs are referenced by :pep:`4711`. ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8925> _______________________________________
STINNER Victor <victor.stinner@haypocalc.com> added the comment:
Is there a reST construct to use here, say to reference a PEP or point to a glossary entry that defines this protocol?
buffer API ("protocol" ?) is documented in Doc/c-api/buffer.rst. Should I link to this document? How? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8925> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: I see that the top section of this file can be referenced though the index entry named “buffer interface”. Georg, would “:term:`buffer interface`” work? Victor, “protocol” is the named used in Python for what you could call an interface, e.g. the iterator protocol, the sequence protocol, etc. It’s a documented set of methods, return types and use cases. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8925> _______________________________________
Georg Brandl <georg@python.org> added the comment: The glossary (see docs.python.org/glossary) does not have an entry for "buffer interface" or "buffer protocol". An index entry just means that some location in the code defines this entry and gets a link back. Of course, you can also link to the C API section using :ref:`bufferobjects`. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8925> _______________________________________
STINNER Victor <victor.stinner@haypocalc.com> added the comment: Commited to 3.2 (r81811) and 3.1 (r81812). The final patch adds also links to tuple, list, dict, float, complex and int. Replace also long by int (long doesn't exist anymore in Python3). @merwok: Please open a new issue if you would like to improve the documentation about the buffer protocol. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8925> _______________________________________
Changes by STINNER Victor <victor.stinner@haypocalc.com>: ---------- resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8925> _______________________________________
Marc-Andre Lemburg <mal@egenix.com> added the comment: STINNER Victor wrote:
New submission from STINNER Victor <victor.stinner@haypocalc.com>:
http://docs.python.org/py3k/c-api/arg.html is unclear about what is a "string".
Attached patch: - Use directly bytes, bytearray and str types - Replace "default encoding" by "``'utf-8'`` encoding" - Add bytes and/or bytearray to "... buffer compatible object" because it's not easy to understand what is a buffer compatible object, especially because there are different kind of buffer objects: read-only, read-write, pinned, etc. - Fix reST syntax ("..note ::") - Fix "es", "es#", "et" and "et#" formats: they doesn't accept "character buffer compatible object" (can someone double check that?)
The character buffer concept is (unfortunately) gone in Python3. There's no way for a buffer compatible object to tell the arg parser that it is storing text data. Perhaps we can add something like that back via the Py_buffer flags for getting buffers. ---------- nosy: +lemburg title: Improve c-api/arg.rst: use "bytes" or "str" types instead of "string" -> Improve c-api/arg.rst: use "bytes" or "str" types instead of "string" _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8925> _______________________________________
STINNER Victor <victor.stinner@haypocalc.com> added the comment:
There's no way for a buffer compatible object to tell the arg parser that it is storing text data.
I think that the buffer protocol targets byte strings/arrays, and that unicode type should be enough. If applications have to exchange text data, they use utf8, which is a byte string. I don't see the use case. Open a discussion on python-dev if you would like to continue the discussion because this issue is closed. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8925> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: haypo, I was not speaking about documenting the buffer protocol in general, but reacting to this specific change in your patch/commit: - buffer protocol (such as :class:`bytes` or :class:`bytearray` objects). + buffer protocol. Before the commit, the term “buffer protocol” was explained by the two examples with links, but now there’s neither link nor example, which is arguably a doc regression <wink>. ---------- title: Improve c-api/arg.rst: use "bytes" or "str" types instead of "string" -> Improve c-api/arg.rst: use "bytes" or "str" types instead of "string" _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8925> _______________________________________
participants (4)
-
Georg Brandl -
Marc-Andre Lemburg
-
STINNER Victor
-
Éric Araujo