Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/arg.rst @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents 62b3185359e3
children c00b08842d7f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _arg-parsing:
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Parsing arguments and building values
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 =====================================
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 These functions are useful when creating your own extensions functions and
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 methods. Additional information and examples are available in
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 :ref:`extending-index`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 The first three of these functions described, :cfunc:`PyArg_ParseTuple`,
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
13 :cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
14 *format strings* which are used to tell the function about the expected
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
15 arguments. The format strings use the same syntax for each of these
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
16 functions.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
17
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 A format string consists of zero or more "format units." A format unit
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
19 describes one Python object; it is usually a single character or a
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
20 parenthesized sequence of format units. With a few exceptions, a format unit
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
21 that is not a parenthesized sequence normally corresponds to a single address
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
22 argument to these functions. In the following description, the quoted form is
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
23 the format unit; the entry in (round) parentheses is the Python object type
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
24 that matches the format unit; and the entry in [square] brackets is the type
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
25 of the C variable(s) whose address should be passed.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
26
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 ``s`` (string or Unicode object) [const char \*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
28 Convert a Python string or Unicode object to a C pointer to a character
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
29 string. You must not provide storage for the string itself; a pointer to
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
30 an existing string is stored into the character pointer variable whose
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
31 address you pass. The C string is NUL-terminated. The Python string must
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
32 not contain embedded NUL bytes; if it does, a :exc:`TypeError` exception is
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
33 raised. Unicode objects are converted to C strings using the default
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
34 encoding. If this conversion fails, a :exc:`UnicodeError` is raised.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
49833
1e919d34c982 merge in r67362 documentation update to document PY_SSIZE_T_CLEAN
Gregory P. Smith <greg@mad-scientist.com>
parents: 48243
diff changeset
36 ``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :ctype:`Py_ssize_t`, see below)]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
37 This variant on ``s`` stores into two C variables, the first one a pointer
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
38 to a character string, the second one its length. In this case the Python
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
39 string may contain embedded null bytes. Unicode objects pass back a
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
40 pointer to the default encoded string version of the object if such a
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
41 conversion is possible. All other read-buffer compatible objects pass back
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
42 a reference to the raw internal data representation.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
44 Starting with Python 2.5 the type of the length argument can be controlled
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
45 by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
46 :file:`Python.h`. If the macro is defined, length is a :ctype:`Py_ssize_t`
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
47 rather than an int.
49833
1e919d34c982 merge in r67362 documentation update to document PY_SSIZE_T_CLEAN
Gregory P. Smith <greg@mad-scientist.com>
parents: 48243
diff changeset
48
48221
b8c4bf393794 Issue #3139: Make buffer-interface thread-safe wrt. PyArg_ParseTuple,
Martin v. Löwis <martin@v.loewis.de>
parents: 45653
diff changeset
49 ``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer \*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
50 Similar to ``s#``, this code fills a Py_buffer structure provided by the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
51 caller. The buffer gets locked, so that the caller can subsequently use
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
52 the buffer even inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
53 responsible for calling ``PyBuffer_Release`` with the structure after it
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
54 has processed the data.
48221
b8c4bf393794 Issue #3139: Make buffer-interface thread-safe wrt. PyArg_ParseTuple,
Martin v. Löwis <martin@v.loewis.de>
parents: 45653
diff changeset
55
50459
8eddd665e9b9 #4811: fix markup glitches (mostly remains of the conversion),
Georg Brandl <georg@python.org>
parents: 50327
diff changeset
56 .. versionadded:: 2.6
48221
b8c4bf393794 Issue #3139: Make buffer-interface thread-safe wrt. PyArg_ParseTuple,
Martin v. Löwis <martin@v.loewis.de>
parents: 45653
diff changeset
57
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 ``z`` (string or ``None``) [const char \*]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 Like ``s``, but the Python object may also be ``None``, in which case the C
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 pointer is set to *NULL*.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 ``z#`` (string or ``None`` or any read buffer compatible object) [const char \*, int]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 This is to ``s#`` as ``z`` is to ``s``.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
64
48221
b8c4bf393794 Issue #3139: Make buffer-interface thread-safe wrt. PyArg_ParseTuple,
Martin v. Löwis <martin@v.loewis.de>
parents: 45653
diff changeset
65 ``z*`` (string or ``None`` or any buffer compatible object) [Py_buffer*]
b8c4bf393794 Issue #3139: Make buffer-interface thread-safe wrt. PyArg_ParseTuple,
Martin v. Löwis <martin@v.loewis.de>
parents: 45653
diff changeset
66 This is to ``s*`` as ``z`` is to ``s``.
48243
c37f4b03637f fix markup
Benjamin Peterson <benjamin@python.org>
parents: 48221
diff changeset
67
50459
8eddd665e9b9 #4811: fix markup glitches (mostly remains of the conversion),
Georg Brandl <georg@python.org>
parents: 50327
diff changeset
68 .. versionadded:: 2.6
48221
b8c4bf393794 Issue #3139: Make buffer-interface thread-safe wrt. PyArg_ParseTuple,
Martin v. Löwis <martin@v.loewis.de>
parents: 45653
diff changeset
69
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 ``u`` (Unicode object) [Py_UNICODE \*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
71 Convert a Python Unicode object to a C pointer to a NUL-terminated buffer
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
72 of 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
73 provide storage for the Unicode data buffer; a pointer to the existing
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
74 Unicode data is stored into the :ctype:`Py_UNICODE` pointer variable whose
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
75 address you pass.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
76
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 ``u#`` (Unicode object) [Py_UNICODE \*, int]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
78 This variant on ``u`` stores into two C variables, the first one a pointer
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
79 to a Unicode data buffer, the second one its length. Non-Unicode objects
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
80 are handled by interpreting their read-buffer pointer as pointer to a
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
81 :ctype:`Py_UNICODE` array.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 ``es`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
84 This variant on ``s`` is used for encoding Unicode and objects convertible
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
85 to Unicode into a character buffer. It only works for encoded data without
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
86 embedded NUL bytes.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 This format requires two arguments. The first is only used as input, and
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
89 must be a :ctype:`const char\*` which points to the name of an encoding as
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
90 a NUL-terminated string, or *NULL*, in which case the default encoding is
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
91 used. An exception is raised if the named encoding is not known to Python.
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
92 The second argument must be a :ctype:`char\*\*`; the value of the pointer
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
93 it references will be set to a buffer with the contents of the argument
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
94 text. The text will be encoded in the encoding specified by the first
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
95 argument.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
96
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
97 :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
98 the encoded data into this buffer and adjust *\*buffer* to reference the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
99 newly allocated storage. The caller is responsible for calling
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
100 :cfunc:`PyMem_Free` to free the allocated buffer after use.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
101
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 ``et`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 Same as ``es`` except that 8-bit string objects are passed through without
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
104 recoding them. Instead, the implementation assumes that the string object
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
105 uses the encoding passed in as parameter.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
106
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 ``es#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
108 This variant on ``s#`` is used for encoding Unicode and objects convertible
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
109 to Unicode into a character buffer. Unlike the ``es`` format, this variant
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
110 allows input data which contains NUL characters.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
111
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
112 It requires three arguments. The first is only used as input, and must be
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
113 a :ctype:`const char\*` which points to the name of an encoding as a
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
114 NUL-terminated string, or *NULL*, in which case the default encoding is
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
115 used. An exception is raised if the named encoding is not known to Python.
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
116 The second argument must be a :ctype:`char\*\*`; the value of the pointer
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
117 it references will be set to a buffer with the contents of the argument
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
118 text. The text will be encoded in the encoding specified by the first
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
119 argument. The third argument must be a pointer to an integer; the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
120 referenced integer will be set to the number of bytes in the output buffer.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
121
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 There are two modes of operation:
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
124 If *\*buffer* points a *NULL* pointer, the function will allocate a buffer
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
125 of the needed size, copy the encoded data into this buffer and set
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
126 *\*buffer* to reference the newly allocated storage. The caller is
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
127 responsible for calling :cfunc:`PyMem_Free` to free the allocated buffer
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
128 after usage.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
129
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
131 :cfunc:`PyArg_ParseTuple` will use this location as the buffer and
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
132 interpret the initial value of *\*buffer_length* as the buffer size. It
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
133 will then copy the encoded data into the buffer and NUL-terminate it. If
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
134 the buffer is not large enough, a :exc:`ValueError` will be set.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
135
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 In both cases, *\*buffer_length* is set to the length of the encoded data
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 without the trailing NUL byte.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 ``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
140 Same as ``es#`` except that string objects are passed through without
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
141 recoding them. Instead, the implementation assumes that the string object
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
142 uses the encoding passed in as parameter.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
143
50312
1b88932defdb #4682: 'b' is actually unsigned char.
Georg Brandl <georg@python.org>
parents: 50305
diff changeset
144 ``b`` (integer) [unsigned char]
1b88932defdb #4682: 'b' is actually unsigned char.
Georg Brandl <georg@python.org>
parents: 50305
diff changeset
145 Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
1b88932defdb #4682: 'b' is actually unsigned char.
Georg Brandl <georg@python.org>
parents: 50305
diff changeset
146 :ctype:`unsigned char`.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
147
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 ``B`` (integer) [unsigned char]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
149 Convert a Python integer to a tiny int without overflow checking, stored in
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
150 a C :ctype:`unsigned char`.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
152 .. versionadded:: 2.3
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
153
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 ``h`` (integer) [short int]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 Convert a Python integer to a C :ctype:`short int`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
157 ``H`` (integer) [unsigned short int]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
158 Convert a Python integer to a C :ctype:`unsigned short int`, without
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
159 overflow checking.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
160
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 .. versionadded:: 2.3
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
163 ``i`` (integer) [int]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
164 Convert a Python integer to a plain C :ctype:`int`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
165
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
166 ``I`` (integer) [unsigned int]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
167 Convert a Python integer to a C :ctype:`unsigned int`, without overflow
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 checking.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
169
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
170 .. versionadded:: 2.3
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
171
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
172 ``l`` (integer) [long int]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 Convert a Python integer to a C :ctype:`long int`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
174
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
175 ``k`` (integer) [unsigned long]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
176 Convert a Python integer or long integer to a C :ctype:`unsigned long`
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
177 without overflow checking.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
178
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 .. versionadded:: 2.3
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
180
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 ``L`` (integer) [PY_LONG_LONG]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 Convert a Python integer to a C :ctype:`long long`. This format is only
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
183 available on platforms that support :ctype:`long long` (or :ctype:`_int64`
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
184 on Windows).
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
185
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 ``K`` (integer) [unsigned PY_LONG_LONG]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 Convert a Python integer or long integer to a C :ctype:`unsigned long long`
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 without overflow checking. This format is only available on platforms that
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
189 support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
190 Windows).
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
191
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 .. versionadded:: 2.3
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
193
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 ``n`` (integer) [Py_ssize_t]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
195 Convert a Python integer or long integer to a C :ctype:`Py_ssize_t`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
196
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
197 .. versionadded:: 2.5
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
198
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 ``c`` (string of length 1) [char]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 Convert a Python character, represented as a string of length 1, to a C
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
201 :ctype:`char`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
202
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 ``f`` (float) [float]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
204 Convert a Python floating point number to a C :ctype:`float`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
205
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 ``d`` (float) [double]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
207 Convert a Python floating point number to a C :ctype:`double`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
208
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 ``D`` (complex) [Py_complex]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
210 Convert a Python complex number to a C :ctype:`Py_complex` structure.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
211
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
212 ``O`` (object) [PyObject \*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
213 Store a Python object (without any conversion) in a C object pointer. The
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
214 C program thus receives the actual object that was passed. The object's
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
215 reference count is not increased. The pointer stored is not *NULL*.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
216
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 ``O!`` (object) [*typeobject*, PyObject \*]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 Store a Python object in a C object pointer. This is similar to ``O``, but
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
219 takes two C arguments: the first is the address of a Python type object,
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
220 the second is the address of the C variable (of type :ctype:`PyObject\*`)
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
221 into which the object pointer is stored. If the Python object does not
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
222 have the required type, :exc:`TypeError` is raised.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
223
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
224 ``O&`` (object) [*converter*, *anything*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
225 Convert a Python object to a C variable through a *converter* function.
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
226 This takes two arguments: the first is a function, the second is the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
227 address of a C variable (of arbitrary type), converted to :ctype:`void \*`.
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
228 The *converter* function in turn is called as follows::
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
229
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 status = converter(object, address);
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
231
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 where *object* is the Python object to be converted and *address* is the
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
233 :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*`
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
234 function. The returned *status* should be ``1`` for a successful
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
235 conversion and ``0`` if the conversion has failed. When the conversion
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
236 fails, the *converter* function should raise an exception and leave the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
237 content of *address* unmodified.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
238
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
239 ``S`` (string) [PyStringObject \*]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
240 Like ``O`` but requires that the Python object is a string object. Raises
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
241 :exc:`TypeError` if the object is not a string object. The C variable may
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
242 also be declared as :ctype:`PyObject\*`.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
243
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
244 ``U`` (Unicode string) [PyUnicodeObject \*]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
245 Like ``O`` but requires that the Python object is a Unicode object. Raises
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
246 :exc:`TypeError` if the object is not a Unicode object. The C variable may
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
247 also be declared as :ctype:`PyObject\*`.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
248
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
249 ``t#`` (read-only character buffer) [char \*, int]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
250 Like ``s#``, but accepts any object which implements the read-only buffer
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
251 interface. The :ctype:`char\*` variable is set to point to the first byte
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
252 of the buffer, and the :ctype:`int` is set to the length of the buffer.
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
253 Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
254 for all others.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
255
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 ``w`` (read-write character buffer) [char \*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
257 Similar to ``s``, but accepts any object which implements the read-write
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
258 buffer interface. The caller must determine the length of the buffer by
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
259 other means, or use ``w#`` instead. Only single-segment buffer objects are
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
260 accepted; :exc:`TypeError` is raised for all others.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
261
49903
b962d04bb7f0 w# requires Py_ssize_t, not int.
Christian Heimes <christian@cheimes.de>
parents: 49833
diff changeset
262 ``w#`` (read-write character buffer) [char \*, Py_ssize_t]
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
263 Like ``s#``, but accepts any object which implements the read-write buffer
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
264 interface. The :ctype:`char \*` variable is set to point to the first byte
53421
62b3185359e3 Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
265 of the buffer, and the :ctype:`Py_ssize_t` is set to the length of the
62b3185359e3 Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
266 buffer. Only single-segment buffer objects are accepted; :exc:`TypeError`
62b3185359e3 Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
267 is raised for all others.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
268
48221
b8c4bf393794 Issue #3139: Make buffer-interface thread-safe wrt. PyArg_ParseTuple,
Martin v. Löwis <martin@v.loewis.de>
parents: 45653
diff changeset
269 ``w*`` (read-write byte-oriented buffer) [Py_buffer \*]
b8c4bf393794 Issue #3139: Make buffer-interface thread-safe wrt. PyArg_ParseTuple,
Martin v. Löwis <martin@v.loewis.de>
parents: 45653
diff changeset
270 This is to ``w`` what ``s*`` is to ``s``.
50459
8eddd665e9b9 #4811: fix markup glitches (mostly remains of the conversion),
Georg Brandl <georg@python.org>
parents: 50327
diff changeset
271
48221
b8c4bf393794 Issue #3139: Make buffer-interface thread-safe wrt. PyArg_ParseTuple,
Martin v. Löwis <martin@v.loewis.de>
parents: 45653
diff changeset
272 .. versionadded:: 2.6
b8c4bf393794 Issue #3139: Make buffer-interface thread-safe wrt. PyArg_ParseTuple,
Martin v. Löwis <martin@v.loewis.de>
parents: 45653
diff changeset
273
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
274 ``(items)`` (tuple) [*matching-items*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
275 The object must be a Python sequence whose length is the number of format
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
276 units in *items*. The C arguments must correspond to the individual format
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
277 units in *items*. Format units for sequences may be nested.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
278
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 .. note::
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
280
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
281 Prior to Python version 1.5.2, this format specifier only accepted a
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
282 tuple containing the individual parameters, not an arbitrary sequence.
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
283 Code which previously caused :exc:`TypeError` to be raised here may now
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
284 proceed without an exception. This is not expected to be a problem for
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
285 existing code.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
286
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
287 It is possible to pass Python long integers where integers are requested;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
288 however no proper range checking is done --- the most significant bits are
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
289 silently truncated when the receiving field is too small to receive the value
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
290 (actually, the semantics are inherited from downcasts in C --- your mileage
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
291 may vary).
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
292
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
293 A few other characters have a meaning in a format string. These may not occur
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
294 inside nested parentheses. They are:
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
295
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
296 ``|``
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
297 Indicates that the remaining arguments in the Python argument list are
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
298 optional. The C variables corresponding to optional arguments should be
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
299 initialized to their default value --- when an optional argument is not
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
300 specified, :cfunc:`PyArg_ParseTuple` does not touch the contents of the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
301 corresponding C variable(s).
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
302
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
303 ``:``
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
304 The list of format units ends here; the string after the colon is used as
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
305 the function name in error messages (the "associated value" of the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
306 exception that :cfunc:`PyArg_ParseTuple` raises).
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
307
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
308 ``;``
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
309 The list of format units ends here; the string after the semicolon is used
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
310 as the error message *instead* of the default error message. ``:`` and
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
311 ``;`` mutually exclude each other.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
312
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
313 Note that any Python object references which are provided to the caller are
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
314 *borrowed* references; do not decrement their reference count!
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
315
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
316 Additional arguments passed to these functions must be addresses of variables
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
317 whose type is determined by the format string; these are used to store values
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
318 from the input tuple. There are a few cases, as described in the list of
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
319 format units above, where these parameters are used as input values; they
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
320 should match what is specified for the corresponding format unit in that case.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
321
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
322 For the conversion to succeed, the *arg* object must match the format and the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
323 format must be exhausted. On success, the :cfunc:`PyArg_Parse\*` functions
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
324 return true, otherwise they return false and raise an appropriate exception.
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
325 When the :cfunc:`PyArg_Parse\*` functions fail due to conversion failure in
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
326 one of the format units, the variables at the addresses corresponding to that
45653
dd016a6ddcc5 #2230: document that PyArg_* leaves addresses alone on error.
Georg Brandl <georg@python.org>
parents: 44797
diff changeset
327 and the following format units are left untouched.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
328
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
329
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
330 .. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
331
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
332 Parse the parameters of a function that takes only positional parameters
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
333 into local variables. Returns true on success; on failure, it returns
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
334 false and raises the appropriate exception.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
335
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
336
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
337 .. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
338
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
339 Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
340 rather than a variable number of arguments.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
341
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
342
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
343 .. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
344
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
345 Parse the parameters of a function that takes both positional and keyword
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
346 parameters into local variables. Returns true on success; on failure, it
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
347 returns false and raises the appropriate exception.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
348
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
349
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
350 .. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
351
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
352 Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
353 va_list rather than a variable number of arguments.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
354
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
355
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
356 .. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
357
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
358 Function used to deconstruct the argument lists of "old-style" functions
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
359 --- these are functions which use the :const:`METH_OLDARGS` parameter
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
360 parsing method. This is not recommended for use in parameter parsing in
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
361 new code, and most code in the standard interpreter has been modified to no
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
362 longer use this for that purpose. It does remain a convenient way to
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
363 decompose other tuples, however, and may continue to be used for that
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
364 purpose.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
365
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
366
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
367 .. cfunction:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
368
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
369 A simpler form of parameter retrieval which does not use a format string to
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
370 specify the types of the arguments. Functions which use this method to
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
371 retrieve their parameters should be declared as :const:`METH_VARARGS` in
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
372 function or method tables. The tuple containing the actual parameters
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
373 should be passed as *args*; it must actually be a tuple. The length of the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
374 tuple must be at least *min* and no more than *max*; *min* and *max* may be
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
375 equal. Additional arguments must be passed to the function, each of which
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
376 should be a pointer to a :ctype:`PyObject\*` variable; these will be filled
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
377 in with the values from *args*; they will contain borrowed references. The
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
378 variables which correspond to optional parameters not given by *args* will
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
379 not be filled in; these should be initialized by the caller. This function
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
380 returns true on success and false if *args* is not a tuple or contains the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
381 wrong number of elements; an exception will be set if there was a failure.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
382
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
383 This is an example of the use of this function, taken from the sources for
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
384 the :mod:`_weakref` helper module for weak references::
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
385
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
386 static PyObject *
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
387 weakref_ref(PyObject *self, PyObject *args)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
388 {
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
389 PyObject *object;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
390 PyObject *callback = NULL;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
391 PyObject *result = NULL;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
392
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
393 if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
394 result = PyWeakref_NewRef(object, callback);
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
395 }
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
396 return result;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
397 }
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
398
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
399 The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
400 equivalent to this call to :cfunc:`PyArg_ParseTuple`::
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
401
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
402 PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
403
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
404 .. versionadded:: 2.2
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
405
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53398
diff changeset
406 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53398
diff changeset
407 This function used an :ctype:`int` type for *min* and *max*. This might
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53398
diff changeset
408 require changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53398
diff changeset
409
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
410
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
411 .. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
412
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
413 Create a new value based on a format string similar to those accepted by
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
414 the :cfunc:`PyArg_Parse\*` family of functions and a sequence of values.
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
415 Returns the value or *NULL* in the case of an error; an exception will be
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
416 raised if *NULL* is returned.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
417
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
418 :cfunc:`Py_BuildValue` does not always build a tuple. It builds a tuple
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
419 only if its format string contains two or more format units. If the format
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
420 string is empty, it returns ``None``; if it contains exactly one format
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
421 unit, it returns whatever object is described by that format unit. To
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
422 force it to return a tuple of size 0 or one, parenthesize the format
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
423 string.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
424
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
425 When memory buffers are passed as parameters to supply data to build
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
426 objects, as for the ``s`` and ``s#`` formats, the required data is copied.
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
427 Buffers provided by the caller are never referenced by the objects created
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
428 by :cfunc:`Py_BuildValue`. In other words, if your code invokes
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
429 :cfunc:`malloc` and passes the allocated memory to :cfunc:`Py_BuildValue`,
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
430 your code is responsible for calling :cfunc:`free` for that memory once
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
431 :cfunc:`Py_BuildValue` returns.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
432
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
433 In the following description, the quoted form is the format unit; the entry
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
434 in (round) parentheses is the Python object type that the format unit will
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
435 return; and the entry in [square] brackets is the type of the C value(s) to
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
436 be passed.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
437
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
438 The characters space, tab, colon and comma are ignored in format strings
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
439 (but not within format units such as ``s#``). This can be used to make
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
440 long format strings a tad more readable.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
441
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
442 ``s`` (string) [char \*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
443 Convert a null-terminated C string to a Python object. If the C string
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
444 pointer is *NULL*, ``None`` is used.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
445
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
446 ``s#`` (string) [char \*, int]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
447 Convert a C string and its length to a Python object. If the C string
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
448 pointer is *NULL*, the length is ignored and ``None`` is returned.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
449
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
450 ``z`` (string or ``None``) [char \*]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
451 Same as ``s``.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
452
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
453 ``z#`` (string or ``None``) [char \*, int]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
454 Same as ``s#``.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
455
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
456 ``u`` (Unicode string) [Py_UNICODE \*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
457 Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
458 Python Unicode object. If the Unicode buffer pointer is *NULL*,
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
459 ``None`` is returned.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
460
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
461 ``u#`` (Unicode string) [Py_UNICODE \*, int]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
462 Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
463 Python Unicode object. If the Unicode buffer pointer is *NULL*, the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
464 length is ignored and ``None`` is returned.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
465
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
466 ``i`` (integer) [int]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
467 Convert a plain C :ctype:`int` to a Python integer object.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
468
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
469 ``b`` (integer) [char]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
470 Convert a plain C :ctype:`char` to a Python integer object.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
471
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
472 ``h`` (integer) [short int]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
473 Convert a plain C :ctype:`short int` to a Python integer object.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
474
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
475 ``l`` (integer) [long int]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
476 Convert a C :ctype:`long int` to a Python integer object.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
477
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
478 ``B`` (integer) [unsigned char]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
479 Convert a C :ctype:`unsigned char` to a Python integer object.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
480
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
481 ``H`` (integer) [unsigned short int]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
482 Convert a C :ctype:`unsigned short int` to a Python integer object.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
483
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
484 ``I`` (integer/long) [unsigned int]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
485 Convert a C :ctype:`unsigned int` to a Python integer object or a Python
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
486 long integer object, if it is larger than ``sys.maxint``.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
487
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
488 ``k`` (integer/long) [unsigned long]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
489 Convert a C :ctype:`unsigned long` to a Python integer object or a
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
490 Python long integer object, if it is larger than ``sys.maxint``.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
491
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
492 ``L`` (long) [PY_LONG_LONG]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
493 Convert a C :ctype:`long long` to a Python long integer object. Only
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
494 available on platforms that support :ctype:`long long`.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
495
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
496 ``K`` (long) [unsigned PY_LONG_LONG]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
497 Convert a C :ctype:`unsigned long long` to a Python long integer object.
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
498 Only available on platforms that support :ctype:`unsigned long long`.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
499
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
500 ``n`` (int) [Py_ssize_t]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
501 Convert a C :ctype:`Py_ssize_t` to a Python integer or long integer.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
502
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
503 .. versionadded:: 2.5
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
504
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
505 ``c`` (string of length 1) [char]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
506 Convert a C :ctype:`int` representing a character to a Python string of
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
507 length 1.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
508
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
509 ``d`` (float) [double]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
510 Convert a C :ctype:`double` to a Python floating point number.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
511
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
512 ``f`` (float) [float]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
513 Same as ``d``.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
514
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
515 ``D`` (complex) [Py_complex \*]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
516 Convert a C :ctype:`Py_complex` structure to a Python complex number.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
517
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
518 ``O`` (object) [PyObject \*]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
519 Pass a Python object untouched (except for its reference count, which is
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
520 incremented by one). If the object passed in is a *NULL* pointer, it is
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
521 assumed that this was caused because the call producing the argument
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
522 found an error and set an exception. Therefore, :cfunc:`Py_BuildValue`
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
523 will return *NULL* but won't raise an exception. If no exception has
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
524 been raised yet, :exc:`SystemError` is set.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
525
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
526 ``S`` (object) [PyObject \*]
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
527 Same as ``O``.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
528
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
529 ``N`` (object) [PyObject \*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
530 Same as ``O``, except it doesn't increment the reference count on the
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
531 object. Useful when the object is created by a call to an object
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
532 constructor in the argument list.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
533
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
534 ``O&`` (object) [*converter*, *anything*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
535 Convert *anything* to a Python object through a *converter* function.
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
536 The function is called with *anything* (which should be compatible with
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
537 :ctype:`void \*`) as its argument and should return a "new" Python
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
538 object, or *NULL* if an error occurred.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
539
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
540 ``(items)`` (tuple) [*matching-items*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
541 Convert a sequence of C values to a Python tuple with the same number of
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
542 items.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
543
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
544 ``[items]`` (list) [*matching-items*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
545 Convert a sequence of C values to a Python list with the same number of
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
546 items.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
547
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
548 ``{items}`` (dictionary) [*matching-items*]
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
549 Convert a sequence of C values to a Python dictionary. Each pair of
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
550 consecutive C values adds one item to the dictionary, serving as key and
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
551 value, respectively.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
552
53398
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
553 If there is an error in the format string, the :exc:`SystemError` exception
eabe6cf9734c Reformat file prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50459
diff changeset
554 is set and *NULL* returned.
50327
db0ddce28d0f Document Py_VaBuildValue.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 50312
diff changeset
555
db0ddce28d0f Document Py_VaBuildValue.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 50312
diff changeset
556 .. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
db0ddce28d0f Document Py_VaBuildValue.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 50312
diff changeset
557
db0ddce28d0f Document Py_VaBuildValue.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 50312
diff changeset
558 Identical to :cfunc:`Py_BuildValue`, except that it accepts a va_list
db0ddce28d0f Document Py_VaBuildValue.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 50312
diff changeset
559 rather than a variable number of arguments.