Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [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 *format |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 14 | strings* which are used to tell the function about the expected arguments. The |
| 15 | format strings use the same syntax for each of these functions. |
| 16 | |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 17 | ----------------- |
| 18 | Parsing arguments |
| 19 | ----------------- |
| 20 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 21 | A format string consists of zero or more "format units." A format unit |
| 22 | describes one Python object; it is usually a single character or a parenthesized |
| 23 | sequence of format units. With a few exceptions, a format unit that is not a |
| 24 | parenthesized sequence normally corresponds to a single address argument to |
| 25 | these functions. In the following description, the quoted form is the format |
| 26 | unit; the entry in (round) parentheses is the Python object type that matches |
| 27 | the format unit; and the entry in [square] brackets is the type of the C |
| 28 | variable(s) whose address should be passed. |
| 29 | |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 30 | Strings and buffers |
| 31 | ------------------- |
| 32 | |
Antoine Pitrou | d53dfa3 | 2011-01-06 07:16:31 +0000 | [diff] [blame] | 33 | These formats allow to access an object as a contiguous chunk of memory. |
| 34 | You don't have to provide raw storage for the returned unicode or bytes |
| 35 | area. Also, you won't have to release any memory yourself, except with the |
| 36 | ``es``, ``es#``, ``et`` and ``et#`` formats. |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 37 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 38 | However, when a :c:type:`Py_buffer` structure gets filled, the underlying |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 39 | buffer is locked so that the caller can subsequently use the buffer even |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 40 | inside a :c:type:`Py_BEGIN_ALLOW_THREADS` block without the risk of mutable data |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 41 | being resized or destroyed. As a result, **you have to call** |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 42 | :c:func:`PyBuffer_Release` after you have finished processing the data (or |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 43 | in any early abort case). |
| 44 | |
| 45 | Unless otherwise stated, buffers are not NUL-terminated. |
| 46 | |
| 47 | .. note:: |
| 48 | For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 49 | the length argument (int or :c:type:`Py_ssize_t`) is controlled by |
| 50 | defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 51 | :file:`Python.h`. If the macro was defined, length is a |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 52 | :c:type:`Py_ssize_t` rather than an :c:type:`int`. This behavior will change |
| 53 | in a future Python version to only support :c:type:`Py_ssize_t` and |
| 54 | drop :c:type:`int` support. It is best to always define :c:macro:`PY_SSIZE_T_CLEAN`. |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 55 | |
| 56 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 57 | ``s`` (:class:`str`) [const char \*] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 58 | Convert a Unicode object to a C pointer to a character string. |
| 59 | A pointer to an existing string is stored in the character pointer |
| 60 | variable whose address you pass. The C string is NUL-terminated. |
| 61 | The Python string must not contain embedded NUL bytes; if it does, |
| 62 | a :exc:`TypeError` exception is raised. Unicode objects are converted |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 63 | to C strings using ``'utf-8'`` encoding. If this conversion fails, a |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 64 | :exc:`UnicodeError` is raised. |
| 65 | |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 66 | .. note:: |
| 67 | This format does not accept bytes-like objects. If you want to accept |
| 68 | filesystem paths and convert them to C character strings, it is |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 69 | preferable to use the ``O&`` format with :c:func:`PyUnicode_FSConverter` |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 70 | as *converter*. |
Benjamin Peterson | 4469d0c | 2008-11-30 22:46:23 +0000 | [diff] [blame] | 71 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 72 | ``s*`` (:class:`str`, :class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 73 | This format accepts Unicode objects as well as objects supporting the |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 74 | buffer protocol. |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 75 | It fills a :c:type:`Py_buffer` structure provided by the caller. |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 76 | In this case the resulting C string may contain embedded NUL bytes. |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 77 | Unicode objects are converted to C strings using ``'utf-8'`` encoding. |
Georg Brandl | 8fa8952 | 2008-09-01 16:45:35 +0000 | [diff] [blame] | 78 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 79 | ``s#`` (:class:`str`, :class:`bytes` or read-only buffer compatible object) [const char \*, int or :c:type:`Py_ssize_t`] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 80 | Like ``s*``, except that it doesn't accept mutable buffer-like objects |
| 81 | such as :class:`bytearray`. The result is stored into two C variables, |
| 82 | the first one a pointer to a C string, the second one its length. |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 83 | The string may contain embedded null bytes. Unicode objects are converted |
| 84 | to C strings using ``'utf-8'`` encoding. |
Benjamin Peterson | 4469d0c | 2008-11-30 22:46:23 +0000 | [diff] [blame] | 85 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 86 | ``z`` (:class:`str` or ``None``) [const char \*] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 87 | Like ``s``, but the Python object may also be ``None``, in which case the C |
| 88 | pointer is set to *NULL*. |
| 89 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 90 | ``z*`` (:class:`str`, :class:`bytes`, :class:`bytearray`, buffer compatible object or ``None``) [Py_buffer] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 91 | Like ``s*``, but the Python object may also be ``None``, in which case the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 92 | ``buf`` member of the :c:type:`Py_buffer` structure is set to *NULL*. |
Martin v. Löwis | 423be95 | 2008-08-13 15:53:07 +0000 | [diff] [blame] | 93 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 94 | ``z#`` (:class:`str`, :class:`bytes`, read-only buffer compatible object or ``None``) [const char \*, int] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 95 | Like ``s#``, but the Python object may also be ``None``, in which case the C |
| 96 | pointer is set to *NULL*. |
| 97 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 98 | ``y`` (:class:`bytes`) [const char \*] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 99 | This format converts a bytes-like object to a C pointer to a character |
| 100 | string; it does not accept Unicode objects. The bytes buffer must not |
| 101 | contain embedded NUL bytes; if it does, a :exc:`TypeError` |
| 102 | exception is raised. |
| 103 | |
Victor Stinner | 1f1ccc0 | 2010-07-05 21:36:21 +0000 | [diff] [blame] | 104 | ``y*`` (:class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 105 | This variant on ``s*`` doesn't accept Unicode objects, only objects |
| 106 | supporting the buffer protocol. **This is the recommended way to accept |
| 107 | binary data.** |
| 108 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 109 | ``y#`` (:class:`bytes`) [const char \*, int] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 110 | This variant on ``s#`` doesn't accept Unicode objects, only bytes-like |
| 111 | objects. |
| 112 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 113 | ``S`` (:class:`bytes`) [PyBytesObject \*] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 114 | Requires that the Python object is a :class:`bytes` object, without |
| 115 | attempting any conversion. Raises :exc:`TypeError` if the object is not |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 116 | a bytes object. The C variable may also be declared as :c:type:`PyObject\*`. |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 117 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 118 | ``Y`` (:class:`bytearray`) [PyByteArrayObject \*] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 119 | Requires that the Python object is a :class:`bytearray` object, without |
| 120 | attempting any conversion. Raises :exc:`TypeError` if the object is not |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 121 | a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`. |
Georg Brandl | 8fa8952 | 2008-09-01 16:45:35 +0000 | [diff] [blame] | 122 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 123 | ``u`` (:class:`str`) [Py_UNICODE \*] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 124 | Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 125 | Unicode characters. You must pass the address of a :c:type:`Py_UNICODE` |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 126 | pointer variable, which will be filled with the pointer to an existing |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 127 | Unicode buffer. Please note that the width of a :c:type:`Py_UNICODE` |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 128 | character depends on compilation options (it is either 16 or 32 bits). |
Victor Stinner | 06e49dd | 2010-06-13 18:21:50 +0000 | [diff] [blame] | 129 | The Python string must not contain embedded NUL characters; if it does, |
| 130 | a :exc:`TypeError` exception is raised. |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 131 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 132 | .. note:: |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 133 | Since ``u`` doesn't give you back the length of the string, and it |
| 134 | may contain embedded NUL characters, it is recommended to use ``u#`` |
| 135 | or ``U`` instead. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 136 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 137 | ``u#`` (:class:`str`) [Py_UNICODE \*, int] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 138 | This variant on ``u`` stores into two C variables, the first one a pointer to a |
Victor Stinner | 7909b00 | 2010-06-11 23:30:12 +0000 | [diff] [blame] | 139 | Unicode data buffer, the second one its length. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 140 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 141 | ``Z`` (:class:`str` or ``None``) [Py_UNICODE \*] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 142 | Like ``u``, but the Python object may also be ``None``, in which case the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 143 | :c:type:`Py_UNICODE` pointer is set to *NULL*. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 144 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 145 | ``Z#`` (:class:`str` or ``None``) [Py_UNICODE \*, int] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 146 | Like ``u#``, but the Python object may also be ``None``, in which case the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 147 | :c:type:`Py_UNICODE` pointer is set to *NULL*. |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 148 | |
Victor Stinner | 3ba82aa | 2011-12-01 02:52:55 +0100 | [diff] [blame] | 149 | ``U`` (:class:`str`) [PyObject \*] |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 150 | Requires that the Python object is a Unicode object, without attempting |
| 151 | any conversion. Raises :exc:`TypeError` if the object is not a Unicode |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 152 | object. The C variable may also be declared as :c:type:`PyObject\*`. |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 153 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 154 | ``w*`` (:class:`bytearray` or read-write byte-oriented buffer) [Py_buffer] |
Victor Stinner | 25e8ec4 | 2010-06-25 00:02:38 +0000 | [diff] [blame] | 155 | This format accepts any object which implements the read-write buffer |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 156 | interface. It fills a :c:type:`Py_buffer` structure provided by the caller. |
Victor Stinner | 25e8ec4 | 2010-06-25 00:02:38 +0000 | [diff] [blame] | 157 | The buffer may contain embedded null bytes. The caller have to call |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 158 | :c:func:`PyBuffer_Release` when it is done with the buffer. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 159 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 160 | ``es`` (:class:`str`) [const char \*encoding, char \*\*buffer] |
Victor Stinner | 7909b00 | 2010-06-11 23:30:12 +0000 | [diff] [blame] | 161 | This variant on ``s`` is used for encoding Unicode into a character buffer. |
| 162 | It only works for encoded data without embedded NUL bytes. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 163 | |
| 164 | This format requires two arguments. The first is only used as input, and |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 165 | must be a :c:type:`const char\*` which points to the name of an encoding as a |
Victor Stinner | 7909b00 | 2010-06-11 23:30:12 +0000 | [diff] [blame] | 166 | NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 167 | An exception is raised if the named encoding is not known to Python. The |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 168 | second argument must be a :c:type:`char\*\*`; the value of the pointer it |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 169 | references will be set to a buffer with the contents of the argument text. |
| 170 | The text will be encoded in the encoding specified by the first argument. |
| 171 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 172 | :c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 173 | encoded data into this buffer and adjust *\*buffer* to reference the newly |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 174 | allocated storage. The caller is responsible for calling :c:func:`PyMem_Free` to |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 175 | free the allocated buffer after use. |
| 176 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 177 | ``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer] |
| 178 | Same as ``es`` except that byte string objects are passed through without |
| 179 | recoding them. Instead, the implementation assumes that the byte string object uses |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 180 | the encoding passed in as parameter. |
| 181 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 182 | ``es#`` (:class:`str`) [const char \*encoding, char \*\*buffer, int \*buffer_length] |
Victor Stinner | 7909b00 | 2010-06-11 23:30:12 +0000 | [diff] [blame] | 183 | This variant on ``s#`` is used for encoding Unicode into a character buffer. |
| 184 | Unlike the ``es`` format, this variant allows input data which contains NUL |
| 185 | characters. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 186 | |
| 187 | It requires three arguments. The first is only used as input, and must be a |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 188 | :c:type:`const char\*` which points to the name of an encoding as a |
Victor Stinner | 7909b00 | 2010-06-11 23:30:12 +0000 | [diff] [blame] | 189 | NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 190 | An exception is raised if the named encoding is not known to Python. The |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 191 | second argument must be a :c:type:`char\*\*`; the value of the pointer it |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 192 | references will be set to a buffer with the contents of the argument text. |
| 193 | The text will be encoded in the encoding specified by the first argument. |
| 194 | The third argument must be a pointer to an integer; the referenced integer |
| 195 | will be set to the number of bytes in the output buffer. |
| 196 | |
| 197 | There are two modes of operation: |
| 198 | |
| 199 | If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of |
| 200 | the needed size, copy the encoded data into this buffer and set *\*buffer* to |
| 201 | reference the newly allocated storage. The caller is responsible for calling |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 202 | :c:func:`PyMem_Free` to free the allocated buffer after usage. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 203 | |
| 204 | If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer), |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 205 | :c:func:`PyArg_ParseTuple` will use this location as the buffer and interpret the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 206 | initial value of *\*buffer_length* as the buffer size. It will then copy the |
| 207 | encoded data into the buffer and NUL-terminate it. If the buffer is not large |
| 208 | enough, a :exc:`ValueError` will be set. |
| 209 | |
| 210 | In both cases, *\*buffer_length* is set to the length of the encoded data |
| 211 | without the trailing NUL byte. |
| 212 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 213 | ``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer, int \*buffer_length] |
| 214 | Same as ``es#`` except that byte string objects are passed through without recoding |
| 215 | them. Instead, the implementation assumes that the byte string object uses the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 216 | encoding passed in as parameter. |
| 217 | |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 218 | Numbers |
| 219 | ------- |
| 220 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 221 | ``b`` (:class:`int`) [unsigned char] |
Benjamin Peterson | da10d3b | 2009-01-01 00:23:30 +0000 | [diff] [blame] | 222 | Convert a nonnegative Python integer to an unsigned tiny int, stored in a C |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 223 | :c:type:`unsigned char`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 224 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 225 | ``B`` (:class:`int`) [unsigned char] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 226 | Convert a Python integer to a tiny int without overflow checking, stored in a C |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 227 | :c:type:`unsigned char`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 228 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 229 | ``h`` (:class:`int`) [short int] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 230 | Convert a Python integer to a C :c:type:`short int`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 231 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 232 | ``H`` (:class:`int`) [unsigned short int] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 233 | Convert a Python integer to a C :c:type:`unsigned short int`, without overflow |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 234 | checking. |
| 235 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 236 | ``i`` (:class:`int`) [int] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 237 | Convert a Python integer to a plain C :c:type:`int`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 238 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 239 | ``I`` (:class:`int`) [unsigned int] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 240 | Convert a Python integer to a C :c:type:`unsigned int`, without overflow |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 241 | checking. |
| 242 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 243 | ``l`` (:class:`int`) [long int] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 244 | Convert a Python integer to a C :c:type:`long int`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 245 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 246 | ``k`` (:class:`int`) [unsigned long] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 247 | Convert a Python integer to a C :c:type:`unsigned long` without |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 248 | overflow checking. |
| 249 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 250 | ``L`` (:class:`int`) [PY_LONG_LONG] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 251 | Convert a Python integer to a C :c:type:`long long`. This format is only |
| 252 | available on platforms that support :c:type:`long long` (or :c:type:`_int64` on |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 253 | Windows). |
| 254 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 255 | ``K`` (:class:`int`) [unsigned PY_LONG_LONG] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 256 | Convert a Python integer to a C :c:type:`unsigned long long` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 257 | without overflow checking. This format is only available on platforms that |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 258 | support :c:type:`unsigned long long` (or :c:type:`unsigned _int64` on Windows). |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 259 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 260 | ``n`` (:class:`int`) [Py_ssize_t] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 261 | Convert a Python integer to a C :c:type:`Py_ssize_t`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 262 | |
Eli Bendersky | 906b88f | 2011-07-29 07:05:08 +0300 | [diff] [blame] | 263 | ``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char] |
| 264 | Convert a Python byte, represented as a :class:`bytes` or |
| 265 | :class:`bytearray` object of length 1, to a C :c:type:`char`. |
| 266 | |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 267 | .. versionchanged:: 3.3 |
| 268 | Allow :class:`bytearray` objects. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 269 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 270 | ``C`` (:class:`str` of length 1) [int] |
| 271 | Convert a Python character, represented as a :class:`str` object of |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 272 | length 1, to a C :c:type:`int`. |
Benjamin Peterson | 7fe9853 | 2009-04-02 00:33:55 +0000 | [diff] [blame] | 273 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 274 | ``f`` (:class:`float`) [float] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 275 | Convert a Python floating point number to a C :c:type:`float`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 276 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 277 | ``d`` (:class:`float`) [double] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 278 | Convert a Python floating point number to a C :c:type:`double`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 279 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 280 | ``D`` (:class:`complex`) [Py_complex] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 281 | Convert a Python complex number to a C :c:type:`Py_complex` structure. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 282 | |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 283 | Other objects |
| 284 | ------------- |
| 285 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 286 | ``O`` (object) [PyObject \*] |
| 287 | Store a Python object (without any conversion) in a C object pointer. The C |
| 288 | program thus receives the actual object that was passed. The object's reference |
| 289 | count is not increased. The pointer stored is not *NULL*. |
| 290 | |
| 291 | ``O!`` (object) [*typeobject*, PyObject \*] |
| 292 | Store a Python object in a C object pointer. This is similar to ``O``, but |
| 293 | takes two C arguments: the first is the address of a Python type object, the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 294 | second is the address of the C variable (of type :c:type:`PyObject\*`) into which |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 295 | the object pointer is stored. If the Python object does not have the required |
| 296 | type, :exc:`TypeError` is raised. |
| 297 | |
| 298 | ``O&`` (object) [*converter*, *anything*] |
| 299 | Convert a Python object to a C variable through a *converter* function. This |
| 300 | takes two arguments: the first is a function, the second is the address of a C |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 301 | variable (of arbitrary type), converted to :c:type:`void \*`. The *converter* |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 302 | function in turn is called as follows:: |
| 303 | |
| 304 | status = converter(object, address); |
| 305 | |
| 306 | where *object* is the Python object to be converted and *address* is the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 307 | :c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*` function. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 308 | The returned *status* should be ``1`` for a successful conversion and ``0`` if |
| 309 | the conversion has failed. When the conversion fails, the *converter* function |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 310 | should raise an exception and leave the content of *address* unmodified. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 311 | |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 312 | If the *converter* returns ``Py_CLEANUP_SUPPORTED``, it may get called a |
| 313 | second time if the argument parsing eventually fails, giving the converter a |
| 314 | chance to release any memory that it had already allocated. In this second |
| 315 | call, the *object* parameter will be NULL; *address* will have the same value |
| 316 | as in the original call. |
Martin v. Löwis | c15bdef | 2009-05-29 14:47:46 +0000 | [diff] [blame] | 317 | |
| 318 | .. versionchanged:: 3.1 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 319 | ``Py_CLEANUP_SUPPORTED`` was added. |
Martin v. Löwis | c15bdef | 2009-05-29 14:47:46 +0000 | [diff] [blame] | 320 | |
Larry Hastings | faf91e7 | 2012-05-05 16:54:29 -0700 | [diff] [blame] | 321 | ``p`` (:class:`bool`) [int] |
| 322 | Tests the value passed in for truth (a boolean **p**\redicate) and converts |
| 323 | the result to its equivalent C true/false integer value. |
| 324 | Sets the int to 1 if the expression was true and 0 if it was false. |
| 325 | This accepts any valid Python value. See :ref:`truth` for more |
| 326 | information about how Python tests values for truth. |
| 327 | |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 328 | .. versionadded:: 3.3 |
Larry Hastings | faf91e7 | 2012-05-05 16:54:29 -0700 | [diff] [blame] | 329 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 330 | ``(items)`` (:class:`tuple`) [*matching-items*] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 331 | The object must be a Python sequence whose length is the number of format units |
| 332 | in *items*. The C arguments must correspond to the individual format units in |
| 333 | *items*. Format units for sequences may be nested. |
| 334 | |
| 335 | It is possible to pass "long" integers (integers whose value exceeds the |
| 336 | platform's :const:`LONG_MAX`) however no proper range checking is done --- the |
| 337 | most significant bits are silently truncated when the receiving field is too |
| 338 | small to receive the value (actually, the semantics are inherited from downcasts |
| 339 | in C --- your mileage may vary). |
| 340 | |
| 341 | A few other characters have a meaning in a format string. These may not occur |
| 342 | inside nested parentheses. They are: |
| 343 | |
| 344 | ``|`` |
| 345 | Indicates that the remaining arguments in the Python argument list are optional. |
| 346 | The C variables corresponding to optional arguments should be initialized to |
| 347 | their default value --- when an optional argument is not specified, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 348 | :c:func:`PyArg_ParseTuple` does not touch the contents of the corresponding C |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 349 | variable(s). |
| 350 | |
Larry Hastings | 83a9f48 | 2012-03-20 20:06:16 +0000 | [diff] [blame] | 351 | ``$`` |
| 352 | :c:func:`PyArg_ParseTupleAndKeywords` only: |
| 353 | Indicates that the remaining arguments in the Python argument list are |
| 354 | keyword-only. Currently, all keyword-only arguments must also be optional |
| 355 | arguments, so ``|`` must always be specified before ``$`` in the format |
| 356 | string. |
| 357 | |
| 358 | .. versionadded:: 3.3 |
| 359 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 360 | ``:`` |
| 361 | The list of format units ends here; the string after the colon is used as the |
| 362 | function name in error messages (the "associated value" of the exception that |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 363 | :c:func:`PyArg_ParseTuple` raises). |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 364 | |
| 365 | ``;`` |
| 366 | The list of format units ends here; the string after the semicolon is used as |
Benjamin Peterson | 9203501 | 2008-12-27 16:00:54 +0000 | [diff] [blame] | 367 | the error message *instead* of the default error message. ``:`` and ``;`` |
| 368 | mutually exclude each other. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 369 | |
| 370 | Note that any Python object references which are provided to the caller are |
| 371 | *borrowed* references; do not decrement their reference count! |
| 372 | |
| 373 | Additional arguments passed to these functions must be addresses of variables |
| 374 | whose type is determined by the format string; these are used to store values |
| 375 | from the input tuple. There are a few cases, as described in the list of format |
| 376 | units above, where these parameters are used as input values; they should match |
| 377 | what is specified for the corresponding format unit in that case. |
| 378 | |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 379 | For the conversion to succeed, the *arg* object must match the format |
| 380 | and the format must be exhausted. On success, the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 381 | :c:func:`PyArg_Parse\*` functions return true, otherwise they return |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 382 | false and raise an appropriate exception. When the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 383 | :c:func:`PyArg_Parse\*` functions fail due to conversion failure in one |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 384 | of the format units, the variables at the addresses corresponding to that |
| 385 | and the following format units are left untouched. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 386 | |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 387 | API Functions |
| 388 | ------------- |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 389 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 390 | .. c:function:: int PyArg_ParseTuple(PyObject *args, const char *format, ...) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 391 | |
| 392 | Parse the parameters of a function that takes only positional parameters into |
| 393 | local variables. Returns true on success; on failure, it returns false and |
| 394 | raises the appropriate exception. |
| 395 | |
| 396 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 397 | .. c:function:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 398 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 399 | Identical to :c:func:`PyArg_ParseTuple`, except that it accepts a va_list rather |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 400 | than a variable number of arguments. |
| 401 | |
| 402 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 403 | .. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 404 | |
| 405 | Parse the parameters of a function that takes both positional and keyword |
| 406 | parameters into local variables. Returns true on success; on failure, it |
| 407 | returns false and raises the appropriate exception. |
| 408 | |
| 409 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 410 | .. c:function:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 411 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 412 | Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 413 | va_list rather than a variable number of arguments. |
| 414 | |
| 415 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 416 | .. c:function:: int PyArg_ValidateKeywordArguments(PyObject *) |
Benjamin Peterson | fb88636 | 2010-04-24 18:21:17 +0000 | [diff] [blame] | 417 | |
| 418 | Ensure that the keys in the keywords argument dictionary are strings. This |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 419 | is only needed if :c:func:`PyArg_ParseTupleAndKeywords` is not used, since the |
Benjamin Peterson | fb88636 | 2010-04-24 18:21:17 +0000 | [diff] [blame] | 420 | latter already does this check. |
| 421 | |
Benjamin Peterson | 44d3d78 | 2010-04-25 21:03:34 +0000 | [diff] [blame] | 422 | .. versionadded:: 3.2 |
| 423 | |
Benjamin Peterson | fb88636 | 2010-04-24 18:21:17 +0000 | [diff] [blame] | 424 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 425 | .. XXX deprecated, will be removed |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 426 | .. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 427 | |
| 428 | Function used to deconstruct the argument lists of "old-style" functions --- |
| 429 | these are functions which use the :const:`METH_OLDARGS` parameter parsing |
| 430 | method. This is not recommended for use in parameter parsing in new code, and |
| 431 | most code in the standard interpreter has been modified to no longer use this |
| 432 | for that purpose. It does remain a convenient way to decompose other tuples, |
| 433 | however, and may continue to be used for that purpose. |
| 434 | |
| 435 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 436 | .. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 437 | |
| 438 | A simpler form of parameter retrieval which does not use a format string to |
| 439 | specify the types of the arguments. Functions which use this method to retrieve |
| 440 | their parameters should be declared as :const:`METH_VARARGS` in function or |
| 441 | method tables. The tuple containing the actual parameters should be passed as |
| 442 | *args*; it must actually be a tuple. The length of the tuple must be at least |
| 443 | *min* and no more than *max*; *min* and *max* may be equal. Additional |
| 444 | arguments must be passed to the function, each of which should be a pointer to a |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 445 | :c:type:`PyObject\*` variable; these will be filled in with the values from |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 446 | *args*; they will contain borrowed references. The variables which correspond |
| 447 | to optional parameters not given by *args* will not be filled in; these should |
| 448 | be initialized by the caller. This function returns true on success and false if |
| 449 | *args* is not a tuple or contains the wrong number of elements; an exception |
| 450 | will be set if there was a failure. |
| 451 | |
| 452 | This is an example of the use of this function, taken from the sources for the |
| 453 | :mod:`_weakref` helper module for weak references:: |
| 454 | |
| 455 | static PyObject * |
| 456 | weakref_ref(PyObject *self, PyObject *args) |
| 457 | { |
| 458 | PyObject *object; |
| 459 | PyObject *callback = NULL; |
| 460 | PyObject *result = NULL; |
| 461 | |
| 462 | if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) { |
| 463 | result = PyWeakref_NewRef(object, callback); |
| 464 | } |
| 465 | return result; |
| 466 | } |
| 467 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 468 | The call to :c:func:`PyArg_UnpackTuple` in this example is entirely equivalent to |
| 469 | this call to :c:func:`PyArg_ParseTuple`:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 470 | |
| 471 | PyArg_ParseTuple(args, "O|O:ref", &object, &callback) |
| 472 | |
| 473 | |
Antoine Pitrou | 83fd9b9 | 2010-05-03 15:57:23 +0000 | [diff] [blame] | 474 | --------------- |
| 475 | Building values |
| 476 | --------------- |
| 477 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 478 | .. c:function:: PyObject* Py_BuildValue(const char *format, ...) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 479 | |
| 480 | Create a new value based on a format string similar to those accepted by the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 481 | :c:func:`PyArg_Parse\*` family of functions and a sequence of values. Returns |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 482 | the value or *NULL* in the case of an error; an exception will be raised if |
| 483 | *NULL* is returned. |
| 484 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 485 | :c:func:`Py_BuildValue` does not always build a tuple. It builds a tuple only if |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 486 | its format string contains two or more format units. If the format string is |
| 487 | empty, it returns ``None``; if it contains exactly one format unit, it returns |
| 488 | whatever object is described by that format unit. To force it to return a tuple |
| 489 | of size 0 or one, parenthesize the format string. |
| 490 | |
| 491 | When memory buffers are passed as parameters to supply data to build objects, as |
| 492 | for the ``s`` and ``s#`` formats, the required data is copied. Buffers provided |
| 493 | by the caller are never referenced by the objects created by |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 494 | :c:func:`Py_BuildValue`. In other words, if your code invokes :c:func:`malloc` |
| 495 | and passes the allocated memory to :c:func:`Py_BuildValue`, your code is |
| 496 | responsible for calling :c:func:`free` for that memory once |
| 497 | :c:func:`Py_BuildValue` returns. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 498 | |
| 499 | In the following description, the quoted form is the format unit; the entry in |
| 500 | (round) parentheses is the Python object type that the format unit will return; |
| 501 | and the entry in [square] brackets is the type of the C value(s) to be passed. |
| 502 | |
| 503 | The characters space, tab, colon and comma are ignored in format strings (but |
| 504 | not within format units such as ``s#``). This can be used to make long format |
| 505 | strings a tad more readable. |
| 506 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 507 | ``s`` (:class:`str` or ``None``) [char \*] |
Victor Stinner | 2aa3af4 | 2010-06-18 23:59:45 +0000 | [diff] [blame] | 508 | Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'`` |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 509 | encoding. If the C string pointer is *NULL*, ``None`` is used. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 510 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 511 | ``s#`` (:class:`str` or ``None``) [char \*, int] |
Victor Stinner | 2aa3af4 | 2010-06-18 23:59:45 +0000 | [diff] [blame] | 512 | Convert a C string and its length to a Python :class:`str` object using ``'utf-8'`` |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 513 | encoding. If the C string pointer is *NULL*, the length is ignored and |
| 514 | ``None`` is returned. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 515 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 516 | ``y`` (:class:`bytes`) [char \*] |
Benjamin Peterson | ffc9479 | 2008-10-21 21:10:07 +0000 | [diff] [blame] | 517 | This converts a C string to a Python :func:`bytes` object. If the C |
| 518 | string pointer is *NULL*, ``None`` is returned. |
| 519 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 520 | ``y#`` (:class:`bytes`) [char \*, int] |
Benjamin Peterson | ffc9479 | 2008-10-21 21:10:07 +0000 | [diff] [blame] | 521 | This converts a C string and its lengths to a Python object. If the C |
| 522 | string pointer is *NULL*, ``None`` is returned. |
| 523 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 524 | ``z`` (:class:`str` or ``None``) [char \*] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 525 | Same as ``s``. |
| 526 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 527 | ``z#`` (:class:`str` or ``None``) [char \*, int] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 528 | Same as ``s#``. |
| 529 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 530 | ``u`` (:class:`str`) [Py_UNICODE \*] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 531 | Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python |
| 532 | Unicode object. If the Unicode buffer pointer is *NULL*, ``None`` is returned. |
| 533 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 534 | ``u#`` (:class:`str`) [Py_UNICODE \*, int] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 535 | Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python |
| 536 | Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored |
| 537 | and ``None`` is returned. |
| 538 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 539 | ``U`` (:class:`str` or ``None``) [char \*] |
Victor Stinner | 7eeb5b5 | 2010-06-07 19:57:46 +0000 | [diff] [blame] | 540 | Same as ``s``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 541 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 542 | ``U#`` (:class:`str` or ``None``) [char \*, int] |
Victor Stinner | 7eeb5b5 | 2010-06-07 19:57:46 +0000 | [diff] [blame] | 543 | Same as ``s#``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 544 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 545 | ``i`` (:class:`int`) [int] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 546 | Convert a plain C :c:type:`int` to a Python integer object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 547 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 548 | ``b`` (:class:`int`) [char] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 549 | Convert a plain C :c:type:`char` to a Python integer object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 550 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 551 | ``h`` (:class:`int`) [short int] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 552 | Convert a plain C :c:type:`short int` to a Python integer object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 553 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 554 | ``l`` (:class:`int`) [long int] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 555 | Convert a C :c:type:`long int` to a Python integer object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 556 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 557 | ``B`` (:class:`int`) [unsigned char] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 558 | Convert a C :c:type:`unsigned char` to a Python integer object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 559 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 560 | ``H`` (:class:`int`) [unsigned short int] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 561 | Convert a C :c:type:`unsigned short int` to a Python integer object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 562 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 563 | ``I`` (:class:`int`) [unsigned int] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 564 | Convert a C :c:type:`unsigned int` to a Python integer object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 565 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 566 | ``k`` (:class:`int`) [unsigned long] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 567 | Convert a C :c:type:`unsigned long` to a Python integer object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 568 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 569 | ``L`` (:class:`int`) [PY_LONG_LONG] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 570 | Convert a C :c:type:`long long` to a Python integer object. Only available |
| 571 | on platforms that support :c:type:`long long` (or :c:type:`_int64` on |
Victor Stinner | 7909b00 | 2010-06-11 23:30:12 +0000 | [diff] [blame] | 572 | Windows). |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 573 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 574 | ``K`` (:class:`int`) [unsigned PY_LONG_LONG] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 575 | Convert a C :c:type:`unsigned long long` to a Python integer object. Only |
| 576 | available on platforms that support :c:type:`unsigned long long` (or |
| 577 | :c:type:`unsigned _int64` on Windows). |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 578 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 579 | ``n`` (:class:`int`) [Py_ssize_t] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 580 | Convert a C :c:type:`Py_ssize_t` to a Python integer. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 581 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 582 | ``c`` (:class:`bytes` of length 1) [char] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 583 | Convert a C :c:type:`int` representing a byte to a Python :class:`bytes` object of |
Benjamin Peterson | a921fb0 | 2009-04-03 22:18:11 +0000 | [diff] [blame] | 584 | length 1. |
| 585 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 586 | ``C`` (:class:`str` of length 1) [int] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 587 | Convert a C :c:type:`int` representing a character to Python :class:`str` |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 588 | object of length 1. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 589 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 590 | ``d`` (:class:`float`) [double] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 591 | Convert a C :c:type:`double` to a Python floating point number. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 592 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 593 | ``f`` (:class:`float`) [float] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 594 | Convert a C :c:type:`float` to a Python floating point number. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 595 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 596 | ``D`` (:class:`complex`) [Py_complex \*] |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 597 | Convert a C :c:type:`Py_complex` structure to a Python complex number. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 598 | |
| 599 | ``O`` (object) [PyObject \*] |
| 600 | Pass a Python object untouched (except for its reference count, which is |
| 601 | incremented by one). If the object passed in is a *NULL* pointer, it is assumed |
| 602 | that this was caused because the call producing the argument found an error and |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 603 | set an exception. Therefore, :c:func:`Py_BuildValue` will return *NULL* but won't |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 604 | raise an exception. If no exception has been raised yet, :exc:`SystemError` is |
| 605 | set. |
| 606 | |
| 607 | ``S`` (object) [PyObject \*] |
| 608 | Same as ``O``. |
| 609 | |
| 610 | ``N`` (object) [PyObject \*] |
| 611 | Same as ``O``, except it doesn't increment the reference count on the object. |
| 612 | Useful when the object is created by a call to an object constructor in the |
| 613 | argument list. |
| 614 | |
| 615 | ``O&`` (object) [*converter*, *anything*] |
| 616 | Convert *anything* to a Python object through a *converter* function. The |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 617 | function is called with *anything* (which should be compatible with :c:type:`void |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 618 | \*`) as its argument and should return a "new" Python object, or *NULL* if an |
| 619 | error occurred. |
| 620 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 621 | ``(items)`` (:class:`tuple`) [*matching-items*] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 622 | Convert a sequence of C values to a Python tuple with the same number of items. |
| 623 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 624 | ``[items]`` (:class:`list`) [*matching-items*] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 625 | Convert a sequence of C values to a Python list with the same number of items. |
| 626 | |
Victor Stinner | 69e25fa | 2010-06-07 21:20:41 +0000 | [diff] [blame] | 627 | ``{items}`` (:class:`dict`) [*matching-items*] |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 628 | Convert a sequence of C values to a Python dictionary. Each pair of consecutive |
| 629 | C values adds one item to the dictionary, serving as key and value, |
| 630 | respectively. |
| 631 | |
| 632 | If there is an error in the format string, the :exc:`SystemError` exception is |
| 633 | set and *NULL* returned. |
Benjamin Peterson | da10d3b | 2009-01-01 00:23:30 +0000 | [diff] [blame] | 634 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 635 | .. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs) |
Benjamin Peterson | da10d3b | 2009-01-01 00:23:30 +0000 | [diff] [blame] | 636 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 637 | Identical to :c:func:`Py_BuildValue`, except that it accepts a va_list |
Benjamin Peterson | da10d3b | 2009-01-01 00:23:30 +0000 | [diff] [blame] | 638 | rather than a variable number of arguments. |