classification
Title: Improve c-api/arg.rst: use "bytes" or "str" types instead of "string"
Type: Stage:
Components: Documentation, Unicode Versions: Python 3.2
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, georg.brandl, lemburg, vstinner
Priority: normal Keywords: patch

Created on 2010-06-06 19:03 by vstinner, last changed 2010-06-13 22:21 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
arg.patch vstinner, 2010-06-06 19:03
Messages (10)
msg107209 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-06 19:03
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.
msg107215 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-06-06 19:40
-   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?
msg107217 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-06-06 19:56
If there is a glossary entry, use :term:`buffer protocol`.  If there is none, write one :)

PEPs are referenced by :pep:`4711`.
msg107230 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-06 21:13
> 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?
msg107234 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-06-06 21:38
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.
msg107243 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-06-06 22:21
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`.
msg107281 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-07 21:33
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.
msg107283 - (view) Author: Marc-Andre Lemburg (lemburg) * (Python committer) Date: 2010-06-07 21:43
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.
msg107289 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-07 23:04
> 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.
msg107761 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-06-13 22:21
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>.
History
Date User Action Args
2010-06-13 22:21:33eric.araujosetmessages: + msg107761
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"
2010-06-07 23:04:51vstinnersetmessages: + msg107289
2010-06-07 21:43:42lemburgsetnosy: + 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"
messages: + msg107283
2010-06-07 21:34:32vstinnersetstatus: open -> closed
resolution: fixed
2010-06-07 21:33:53vstinnersetmessages: + msg107281
2010-06-06 22:21:42georg.brandlsetmessages: + msg107243
2010-06-06 21:38:13eric.araujosetmessages: + msg107234
2010-06-06 21:13:56vstinnersetmessages: + msg107230
2010-06-06 19:56:22georg.brandlsetnosy: + georg.brandl
messages: + msg107217
2010-06-06 19:40:53eric.araujosetnosy: + eric.araujo
messages: + msg107215
2010-06-06 19:03:54vstinnercreate