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