classification
Title: Incorrect documentation for `s#` arguments in C API argument parsing
Type: enhancement Stage: resolved
Components: C API, Documentation Versions: Python 3.9, Python 3.8, Python 3.7, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, enrico, inada.naoki
Priority: normal Keywords: easy, patch

Created on 2019-07-01 08:20 by enrico, last changed 2020-04-23 05:20 by inada.naoki. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 17478 closed iustin, 2020-01-25 14:33
Messages (5)
msg346974 - (view) Author: Enrico Zini (enrico) Date: 2019-07-01 08:20
In https://docs.python.org/3.9/c-api/arg.html, in the documentation for parsing argument, there is:

     s# (str, read-only bytes-like object) [const char *, int or Py_ssize_t]

In my amd64 system, `Py_ssize_t` is a different type than `int`, and passing a `Py_ssize_t` causes undefine behaviour.

I assume this has been switched to an `int` in the API, and that thisinstance of the documentation has not been updated accordingly. At the bottom of the page in the documentation of `Py_BuildValue`, `s#` is correctly documented as using an `int` and no `Py_ssize_t`, for example.
msg346976 - (view) Author: Inada Naoki (inada.naoki) * (Python committer) Date: 2019-07-01 08:31
See note in https://docs.python.org/3.9/c-api/arg.html#strings-and-buffers

"""
Note: For all # variants of formats (s#, y#, etc.), the type of the length argument (int or Py_ssize_t) is controlled by defining the macro PY_SSIZE_T_CLEAN before including Python.h. If the macro was defined, length is a Py_ssize_t rather than an int. This behavior will change in a future Python version to only support Py_ssize_t and drop int support. It is best to always define PY_SSIZE_T_CLEAN. 
"""
msg346982 - (view) Author: Enrico Zini (enrico) Date: 2019-07-01 09:07
Oh! Fair enough, I had missed it. Does the note also involve `Py_BuildValue`? If so, the documentation of `Py_BuildValue` should probably be updated; if not, I think it would be clearer if the note mentioned that it only applies to parsing, not building, values.
msg347102 - (view) Author: Inada Naoki (inada.naoki) * (Python committer) Date: 2019-07-02 04:22
> Oh! Fair enough, I had missed it. Does the note also involve `Py_BuildValue`? If so, the documentation of `Py_BuildValue` should probably be updated; if not, I think it would be clearer if the note mentioned that it only applies to parsing, not building, values.

Yes, this is same to Py_BuildValue.  The document of Py_BuildValue
should be `int or Py_ssize_t` too.
msg367078 - (view) Author: Inada Naoki (inada.naoki) * (Python committer) Date: 2020-04-23 05:20
Fixed via GH-18663.
History
Date User Action Args
2020-04-23 05:20:33inada.naokisetstatus: open -> closed
resolution: fixed
messages: + msg367078

stage: patch review -> resolved
2020-01-25 14:33:07iustinsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request17566
2019-12-10 05:48:47serhiy.storchakasetkeywords: + easy
stage: needs patch
type: enhancement
versions: + Python 2.7, - Python 3.5, Python 3.6
2019-12-09 16:13:10vstinnersetcomponents: + C API
2019-07-02 04:22:36inada.naokisetmessages: + msg347102
2019-07-01 09:07:11enricosetmessages: + msg346982
2019-07-01 08:31:05inada.naokisetnosy: + inada.naoki
messages: + msg346976
2019-07-01 08:20:20enricocreate