summaryrefslogtreecommitdiffstats
path: root/Doc/c-api/arg.rst
diff options
context:
space:
mode:
authorGregory P. Smith <greg@mad-scientist.com>2008-11-23 23:49:16 (GMT)
committerGregory P. Smith <greg@mad-scientist.com>2008-11-23 23:49:16 (GMT)
commit02c3b5cc308a6425ad0cfd23b7d53bc351bc1a4b (patch)
treede640df181f451ca53bb51a4c0ed8a9333ecba42 /Doc/c-api/arg.rst
parente8068edf1e8c95adcb9de2ab66bb96cecfcffa5d (diff)
downloadcpython-02c3b5cc308a6425ad0cfd23b7d53bc351bc1a4b.zip
cpython-02c3b5cc308a6425ad0cfd23b7d53bc351bc1a4b.tar.gz
cpython-02c3b5cc308a6425ad0cfd23b7d53bc351bc1a4b.tar.bz2
Document PY_SSIZE_T_CLEAN use and behavior for PyArg_ParseTuple and
mention that it will become the default in a future python version.
Diffstat (limited to 'Doc/c-api/arg.rst')
-rw-r--r--Doc/c-api/arg.rst10
1 files changed, 8 insertions, 2 deletions
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 94f62f1..e4b91b9 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -42,12 +42,18 @@ variable(s) whose address should be passed.
responsible** for calling ``PyBuffer_Release`` with the structure after it
has processed the data.
-``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int]
+``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int or :ctype:`Py_ssize_t`]
This variant on ``s*`` stores into two C variables, the first one a pointer
to a character string, the second one its length. All other read-buffer
compatible objects pass back a reference to the raw internal data
representation. Since this format doesn't allow writable buffer compatible
- objects like byte arrays, ``s*`` is to be preferred.
+ objects like byte arrays, ``s*`` is to be preferred. The type of
+ the length argument (int or :ctype:`Py_ssize_t`) is controlled by
+ defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including
+ :file:`Python.h`. If the macro was defined, length is a :ctype:`Py_ssize_t`
+ rather than an int. This behavior will change in a future Python
+ version to only support :ctype:`Py_ssize_t` and drop int support.
+ It is best to always define :cmacro:`PY_SSIZE_T_CLEAN`.
``y`` (bytes object) [const char \*]
This variant on ``s`` converts a Python bytes or bytearray object to a C