[Python-checkins] r81812 - in python/branches/release31-maint: Doc/c-api/arg.rst
victor.stinner
python-checkins at python.org
Mon Jun 7 23:29:23 CEST 2010
Author: victor.stinner
Date: Mon Jun 7 23:29:23 2010
New Revision: 81812
Log:
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.
........
Modified:
python/branches/release31-maint/ (props changed)
python/branches/release31-maint/Doc/c-api/arg.rst
Modified: python/branches/release31-maint/Doc/c-api/arg.rst
==============================================================================
--- python/branches/release31-maint/Doc/c-api/arg.rst (original)
+++ python/branches/release31-maint/Doc/c-api/arg.rst Mon Jun 7 23:29:23 2010
@@ -53,13 +53,13 @@
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 @@
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 @@
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 @@
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 @@
.. 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 @@
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#`` (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 \*]
+ 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#`` (: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 @@
\*`) 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.
More information about the Python-checkins
mailing list