traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merged revisions 81811 via svnmerge from 

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r81811 | victor.stinner | 2010-06-07 23:20:41 +0200 (lun., 07 juin 2010) | 9 lines

  Issue #8925: fix types of Py_Parse*() and Py_BuildValue() functions

   * Add links to Python types
   * Replace "string" by bytes or str
   * Replace "long" by "int"
   * Specify the default encoding
   * Fix reST syntax ("..note ::")
   * etc.
........
This commit is contained in:
Victor Stinner 2010-06-07 21:29:23 +00:00
parent d67cb78f18
commit 4704881235
1 changed files with 91 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

180
Doc/c-api/arg.rst
View File

@ -53,13 +53,13 @@ Unless otherwise stated, buffers are not NUL-terminated.
drop int support. It is best to always define :cmacro:`PY_SSIZE_T_CLEAN`.
``s`` (Unicode object) [const char \*]
``s`` (:class:`str`) [const char \*]
Convert a Unicode object to a C pointer to a character string.
A pointer to an existing string is stored in the character pointer
variable whose address you pass. The C string is NUL-terminated.
The Python string must not contain embedded NUL bytes; if it does,
a :exc:`TypeError` exception is raised. Unicode objects are converted
to C strings using the default encoding. If this conversion fails, a
to C strings using ``'utf-8'`` encoding. If this conversion fails, a
:exc:`UnicodeError` is raised.
.. note::
@ -68,111 +68,112 @@ Unless otherwise stated, buffers are not NUL-terminated.
preferrable to use the ``O&`` format with :cfunc:`PyUnicode_FSConverter`
as *converter*.
``s*`` (Unicode object or any buffer compatible object) [Py_buffer]
``s*`` (:class:`str`, :class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer]
This format accepts Unicode objects as well as objects supporting the
buffer protocol (such as :class:`bytes` or :class:`bytearray` objects).
buffer protocol.
It fills a :ctype:`Py_buffer` structure provided by the caller.
Unicode objects are converted to C strings using the default encoding.
In this case the resulting C string may contain embedded NUL bytes.
Unicode objects are converted to C strings using ``'utf-8'`` encoding.
``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int or :ctype:`Py_ssize_t`]
``s#`` (:class:`str`, :class:`bytes` or read-only buffer compatible object) [const char \*, int or :ctype:`Py_ssize_t`]
Like ``s*``, except that it doesn't accept mutable buffer-like objects
such as :class:`bytearray`. The result is stored into two C variables,
the first one a pointer to a C string, the second one its length.
The string may contain embedded null bytes.
The string may contain embedded null bytes. Unicode objects are converted
to C strings using ``'utf-8'`` encoding.
``z`` (Unicode object or ``None``) [const char \*]
``z`` (:class:`str` or ``None``) [const char \*]
Like ``s``, but the Python object may also be ``None``, in which case the C
pointer is set to *NULL*.
``z*`` (Unicode object or ``None`` or any buffer compatible object) [Py_buffer]
``z*`` (:class:`str`, :class:`bytes`, :class:`bytearray`, buffer compatible object or ``None``) [Py_buffer]
Like ``s*``, but the Python object may also be ``None``, in which case the
``buf`` member of the :ctype:`Py_buffer` structure is set to *NULL*.
``z#`` (Unicode object or ``None`` or any read buffer compatible object) [const char \*, int]
``z#`` (:class:`str`, :class:`bytes`, read-only buffer compatible object or ``None``) [const char \*, int]
Like ``s#``, but the Python object may also be ``None``, in which case the C
pointer is set to *NULL*.
``y`` (bytes object) [const char \*]
``y`` (:class:`bytes`) [const char \*]
This format converts a bytes-like object to a C pointer to a character
string; it does not accept Unicode objects. The bytes buffer must not
contain embedded NUL bytes; if it does, a :exc:`TypeError`
exception is raised.
``y*`` (any buffer compatible object) [Py_buffer \*]
``y*`` (:class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer \*]
This variant on ``s*`` doesn't accept Unicode objects, only objects
supporting the buffer protocol. **This is the recommended way to accept
binary data.**
``y#`` (bytes object) [const char \*, int]
``y#`` (:class:`bytes`) [const char \*, int]
This variant on ``s#`` doesn't accept Unicode objects, only bytes-like
objects.
``S`` (bytes object) [PyBytesObject \*]
``S`` (:class:`bytes`) [PyBytesObject \*]
Requires that the Python object is a :class:`bytes` object, without
attempting any conversion. Raises :exc:`TypeError` if the object is not
a bytes object. The C variable may also be declared as :ctype:`PyObject\*`.
``Y`` (bytearray object) [PyByteArrayObject \*]
``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
Requires that the Python object is a :class:`bytearray` object, without
attempting any conversion. Raises :exc:`TypeError` if the object is not
a bytearray object. The C variable may also be declared as :ctype:`PyObject\*`.
a :class:`bytearray` object. The C variable may also be declared as :ctype:`PyObject\*`.
``u`` (Unicode object) [Py_UNICODE \*]
``u`` (:class:`str`) [Py_UNICODE \*]
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
Unicode characters. You must pass the address of a :ctype:`Py_UNICODE`
pointer variable, which will be filled with the pointer to an existing
Unicode buffer. Please note that the width of a :ctype:`Py_UNICODE`
character depends on compilation options (it is either 16 or 32 bits).
..note ::
.. note::
Since ``u`` doesn't give you back the length of the string, and it
may contain embedded NUL characters, it is recommended to use ``u#``
or ``U`` instead.
``u#`` (Unicode object) [Py_UNICODE \*, int]
``u#`` (:class:`str`) [Py_UNICODE \*, int]
This variant on ``u`` stores into two C variables, the first one a pointer to a
Unicode data buffer, the second one its length. Non-Unicode objects are handled
by interpreting their read-buffer pointer as pointer to a :ctype:`Py_UNICODE`
array.
``Z`` (Unicode or ``None``) [Py_UNICODE \*]
``Z`` (:class:`str` or ``None``) [Py_UNICODE \*]
Like ``u``, but the Python object may also be ``None``, in which case the
:ctype:`Py_UNICODE` pointer is set to *NULL*.
``Z#`` (Unicode or ``None``) [Py_UNICODE \*, int]
``Z#`` (:class:`str` or ``None``) [Py_UNICODE \*, int]
Like ``u#``, but the Python object may also be ``None``, in which case the
:ctype:`Py_UNICODE` pointer is set to *NULL*.
``U`` (Unicode object) [PyUnicodeObject \*]
``U`` (:class:`str`) [PyUnicodeObject \*]
Requires that the Python object is a Unicode object, without attempting
any conversion. Raises :exc:`TypeError` if the object is not a Unicode
object. The C variable may also be declared as :ctype:`PyObject\*`.
``t#`` (read-only character buffer) [char \*, int]
``t#`` (:class:`bytes`, :class:`bytearray` or read-only character buffer) [char \*, int]
Like ``s#``, but accepts any object which implements the read-only buffer
interface. The :ctype:`char\*` variable is set to point to the first byte of
the buffer, and the :ctype:`int` is set to the length of the buffer. Only
single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
others.
``w`` (read-write character buffer) [char \*]
``w`` (:class:`bytearray` or read-write character buffer) [char \*]
Similar to ``s``, but accepts any object which implements the read-write buffer
interface. The caller must determine the length of the buffer by other means,
or use ``w#`` instead. Only single-segment buffer objects are accepted;
:exc:`TypeError` is raised for all others.
``w*`` (read-write byte-oriented buffer) [Py_buffer]
``w*`` (:class:`bytearray` or read-write byte-oriented buffer) [Py_buffer]
This is to ``w`` what ``s*`` is to ``s``.
``w#`` (read-write character buffer) [char \*, int]
``w#`` (:class:`bytearray` or read-write character buffer) [char \*, int]
Like ``s#``, but accepts any object which implements the read-write buffer
interface. The :ctype:`char \*` variable is set to point to the first byte
of the buffer, and the :ctype:`int` is set to the length of the buffer.
Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
for all others.
``es`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
``es`` (:class:`str`) [const char \*encoding, char \*\*buffer]
This variant on ``s`` is used for encoding Unicode and objects convertible to
Unicode into a character buffer. It only works for encoded data without embedded
NUL bytes.
@ -190,12 +191,12 @@ Unless otherwise stated, buffers are not NUL-terminated.
allocated storage. The caller is responsible for calling :cfunc:`PyMem_Free` to
free the allocated buffer after use.
``et`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
Same as ``es`` except that 8-bit string objects are passed through without
recoding them. Instead, the implementation assumes that the string object uses
``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer]
Same as ``es`` except that byte string objects are passed through without
recoding them. Instead, the implementation assumes that the byte string object uses
the encoding passed in as parameter.
``es#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
``es#`` (:class:`str`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
This variant on ``s#`` is used for encoding Unicode and objects convertible to
Unicode into a character buffer. Unlike the ``es`` format, this variant allows
input data which contains NUL characters.
@ -226,71 +227,71 @@ Unless otherwise stated, buffers are not NUL-terminated.
In both cases, *\*buffer_length* is set to the length of the encoded data
without the trailing NUL byte.
``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
Same as ``es#`` except that string objects are passed through without recoding
them. Instead, the implementation assumes that the string object uses the
``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
Same as ``es#`` except that byte string objects are passed through without recoding
them. Instead, the implementation assumes that the byte string object uses the
encoding passed in as parameter.
Numbers
-------
``b`` (integer) [unsigned char]
``b`` (:class:`int`) [unsigned char]
Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
:ctype:`unsigned char`.
``B`` (integer) [unsigned char]
``B`` (:class:`int`) [unsigned char]
Convert a Python integer to a tiny int without overflow checking, stored in a C
:ctype:`unsigned char`.
``h`` (integer) [short int]
``h`` (:class:`int`) [short int]
Convert a Python integer to a C :ctype:`short int`.
``H`` (integer) [unsigned short int]
``H`` (:class:`int`) [unsigned short int]
Convert a Python integer to a C :ctype:`unsigned short int`, without overflow
checking.
``i`` (integer) [int]
``i`` (:class:`int`) [int]
Convert a Python integer to a plain C :ctype:`int`.
``I`` (integer) [unsigned int]
``I`` (:class:`int`) [unsigned int]
Convert a Python integer to a C :ctype:`unsigned int`, without overflow
checking.
``l`` (integer) [long int]
``l`` (:class:`int`) [long int]
Convert a Python integer to a C :ctype:`long int`.
``k`` (integer) [unsigned long]
``k`` (:class:`int`) [unsigned long]
Convert a Python integer to a C :ctype:`unsigned long` without
overflow checking.
``L`` (integer) [PY_LONG_LONG]
``L`` (:class:`int`) [PY_LONG_LONG]
Convert a Python integer to a C :ctype:`long long`. This format is only
available on platforms that support :ctype:`long long` (or :ctype:`_int64` on
Windows).
``K`` (integer) [unsigned PY_LONG_LONG]
``K`` (:class:`int`) [unsigned PY_LONG_LONG]
Convert a Python integer to a C :ctype:`unsigned long long`
without overflow checking. This format is only available on platforms that
support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on Windows).
``n`` (integer) [Py_ssize_t]
``n`` (:class:`int`) [Py_ssize_t]
Convert a Python integer to a C :ctype:`Py_ssize_t`.
``c`` (bytes object of length 1) [char]
``c`` (:class:`bytes` of length 1) [char]
Convert a Python byte, represented as a :class:`bytes` object of length 1,
to a C :ctype:`char`.
``C`` (Unicode object of length 1) [int]
Convert a Python character, represented as a :class:`str`: object of
``C`` (:class:`str` of length 1) [int]
Convert a Python character, represented as a :class:`str` object of
length 1, to a C :ctype:`int`.
``f`` (float) [float]
``f`` (:class:`float`) [float]
Convert a Python floating point number to a C :ctype:`float`.
``d`` (float) [double]
``d`` (:class:`float`) [double]
Convert a Python floating point number to a C :ctype:`double`.
``D`` (complex) [Py_complex]
``D`` (:class:`complex`) [Py_complex]
Convert a Python complex number to a C :ctype:`Py_complex` structure.
Other objects
@ -330,7 +331,7 @@ Other objects
.. versionchanged:: 3.1
Py_CLEANUP_SUPPORTED was added.
``(items)`` (tuple) [*matching-items*]
``(items)`` (:class:`tuple`) [*matching-items*]
The object must be a Python sequence whose length is the number of format units
in *items*. The C arguments must correspond to the individual format units in
*items*. Format units for sequences may be nested.
@ -489,95 +490,96 @@ Building values
not within format units such as ``s#``). This can be used to make long format
strings a tad more readable.
``s`` (string) [char \*]
Convert a null-terminated C string to a Python object. If the C string pointer
is *NULL*, ``None`` is used.
``s`` (:class:`str` or ``None``) [char \*]
Convert a null-terminated C string to a Python object using ``'utf-8'``
encoding. If the C string pointer is *NULL*, ``None`` is used.
``s#`` (string) [char \*, int]
Convert a C string and its length to a Python object. If the C string pointer
is *NULL*, the length is ignored and ``None`` is returned.
``s#`` (:class:`str` or ``None``) [char \*, int]
Convert a C string and its length to a Python object using ``'utf-8'``
encoding. If the C string pointer is *NULL*, the length is ignored and
``None`` is returned.
``y`` (bytes) [char \*]
``y`` (:class:`bytes`) [char \*]
This converts a C string to a Python :func:`bytes` object. If the C
string pointer is *NULL*, ``None`` is returned.
``y#`` (bytes) [char \*, int]
``y#`` (:class:`bytes`) [char \*, int]
This converts a C string and its lengths to a Python object. If the C
string pointer is *NULL*, ``None`` is returned.
``z`` (string or ``None``) [char \*]
``z`` (:class:`str` or ``None``) [char \*]
Same as ``s``.
``z#`` (string or ``None``) [char \*, int]
``z#`` (:class:`str` or ``None``) [char \*, int]
Same as ``s#``.
``u`` (Unicode string) [Py_UNICODE \*]
``u`` (:class:`str`) [Py_UNICODE \*]
Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
Unicode object. If the Unicode buffer pointer is *NULL*, ``None`` is returned.
``u#`` (Unicode string) [Py_UNICODE \*, int]
``u#`` (:class:`str`) [Py_UNICODE \*, int]
Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python
Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored
and ``None`` is returned.
``U`` (string) [char \*]
``U`` (:class:`str` or ``None``) [char \*]
Convert a null-terminated C string to a Python unicode object. If the C string
pointer is *NULL*, ``None`` is used.
``U#`` (string) [char \*, int]
``U#`` (:class:`str` or ``None``) [char \*, int]
Convert a C string and its length to a Python unicode object. If the C string
pointer is *NULL*, the length is ignored and ``None`` is returned.
``i`` (integer) [int]
``i`` (:class:`int`) [int]
Convert a plain C :ctype:`int` to a Python integer object.
``b`` (integer) [char]
``b`` (:class:`int`) [char]
Convert a plain C :ctype:`char` to a Python integer object.
``h`` (integer) [short int]
``h`` (:class:`int`) [short int]
Convert a plain C :ctype:`short int` to a Python integer object.
``l`` (integer) [long int]
``l`` (:class:`int`) [long int]
Convert a C :ctype:`long int` to a Python integer object.
``B`` (integer) [unsigned char]
``B`` (:class:`int`) [unsigned char]
Convert a C :ctype:`unsigned char` to a Python integer object.
``H`` (integer) [unsigned short int]
``H`` (:class:`int`) [unsigned short int]
Convert a C :ctype:`unsigned short int` to a Python integer object.
``I`` (integer) [unsigned int]
``I`` (:class:`int`) [unsigned int]
Convert a C :ctype:`unsigned int` to a Python integer object.
``k`` (integer) [unsigned long]
``k`` (:class:`int`) [unsigned long]
Convert a C :ctype:`unsigned long` to a Python integer object.
``L`` (long) [PY_LONG_LONG]
``L`` (:class:`int`) [PY_LONG_LONG]
Convert a C :ctype:`long long` to a Python integer object. Only available
on platforms that support :ctype:`long long`.
``K`` (long) [unsigned PY_LONG_LONG]
``K`` (:class:`int`) [unsigned PY_LONG_LONG]
Convert a C :ctype:`unsigned long long` to a Python integer object. Only
available on platforms that support :ctype:`unsigned long long`.
``n`` (int) [Py_ssize_t]
``n`` (:class:`int`) [Py_ssize_t]
Convert a C :ctype:`Py_ssize_t` to a Python integer.
``c`` (string of length 1) [char]
Convert a C :ctype:`int` representing a byte to a Python byte string of
``c`` (:class:`bytes` of length 1) [char]
Convert a C :ctype:`int` representing a byte to a Python :class:`bytes` object of
length 1.
``C`` (string of length 1) [int]
Convert a C :ctype:`int` representing a character to Python unicode
string of length 1.
``C`` (:class:`str` of length 1) [int]
Convert a C :ctype:`int` representing a character to Python :class:`str`
object of length 1.
``d`` (float) [double]
``d`` (:class:`float`) [double]
Convert a C :ctype:`double` to a Python floating point number.
``f`` (float) [float]
Same as ``d``.
``f`` (:class:`float`) [float]
Convert a C :ctype:`float` to a Python floating point number.
``D`` (complex) [Py_complex \*]
``D`` (:class:`complex`) [Py_complex \*]
Convert a C :ctype:`Py_complex` structure to a Python complex number.
``O`` (object) [PyObject \*]
@ -602,13 +604,13 @@ Building values
\*`) as its argument and should return a "new" Python object, or *NULL* if an
error occurred.
``(items)`` (tuple) [*matching-items*]
``(items)`` (:class:`tuple`) [*matching-items*]
Convert a sequence of C values to a Python tuple with the same number of items.
``[items]`` (list) [*matching-items*]
``[items]`` (:class:`list`) [*matching-items*]
Convert a sequence of C values to a Python list with the same number of items.
``{items}`` (dictionary) [*matching-items*]
``{items}`` (:class:`dict`) [*matching-items*]
Convert a sequence of C values to a Python dictionary. Each pair of consecutive
C values adds one item to the dictionary, serving as key and value,
respectively.