Lines Matching +full:python +full:- +full:format
3 .. _arg-parsing:
10 :ref:`extending-index`.
13 :c:func:`PyArg_ParseTupleAndKeywords`, and :c:func:`PyArg_Parse`, all use *format
15 format strings use the same syntax for each of these functions.
17 -----------------
19 -----------------
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
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
31 -------------------
37 Unless otherwise stated, buffers are not NUL-terminated.
52 * .. _c-arg-borrowed-buffer:
54 Other formats take a :class:`str` or a read-only :term:`bytes-like object`,
58 Python object, and shares the lifetime of this object.
64 but also some read-only objects such as :class:`memoryview` of
75 :file:`Python.h`. On Python 3.9 and older, the type of the length argument
83 variable whose address you pass. The C string is NUL-terminated.
84 The Python string must not contain embedded null code points; if it does,
86 to C strings using ``'utf-8'`` encoding. If this conversion fails, a
90 This format does not accept :term:`bytes-like objects
91 <bytes-like object>`. If you want to accept
93 preferable to use the ``O&`` format with :c:func:`PyUnicode_FSConverter`
98 were encountered in the Python string.
100 ``s*`` (:class:`str` or :term:`bytes-like object`) [Py_buffer]
101 This format accepts Unicode objects as well as bytes-like objects.
104 Unicode objects are converted to C strings using ``'utf-8'`` encoding.
106 ``s#`` (:class:`str`, read-only :term:`bytes-like object`) [const char \*, :c:type:`Py_ssize_t`]
107 Like ``s*``, except that it provides a :ref:`borrowed buffer <c-arg-borrowed-buffer>`.
111 to C strings using ``'utf-8'`` encoding.
114 Like ``s``, but the Python object may also be ``None``, in which case the C
117 ``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer]
118 Like ``s*``, but the Python object may also be ``None``, in which case the
121 ``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, :c:type:`Py_…
122 Like ``s#``, but the Python object may also be ``None``, in which case the C
125 ``y`` (read-only :term:`bytes-like object`) [const char \*]
126 This format converts a bytes-like object to a C pointer to a
127 :ref:`borrowed <c-arg-borrowed-buffer>` character string;
136 ``y*`` (:term:`bytes-like object`) [Py_buffer]
138 bytes-like objects. **This is the recommended way to accept
141 ``y#`` (read-only :term:`bytes-like object`) [const char \*, :c:type:`Py_ssize_t`]
142 This variant on ``s#`` doesn't accept Unicode objects, only bytes-like
146 Requires that the Python object is a :class:`bytes` object, without
151 Requires that the Python object is a :class:`bytearray` object, without
156 Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
161 The Python string must not contain embedded null code points; if it does,
166 were encountered in the Python string.
168 .. deprecated-removed:: 3.3 3.12
169 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
177 .. deprecated-removed:: 3.3 3.12
178 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
182 Like ``u``, but the Python object may also be ``None``, in which case the
185 .. deprecated-removed:: 3.3 3.12
186 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
190 Like ``u#``, but the Python object may also be ``None``, in which case the
193 .. deprecated-removed:: 3.3 3.12
194 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
198 Requires that the Python object is a Unicode object, without attempting
202 ``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
203 This format accepts any object which implements the read-write buffer
212 This format requires two arguments. The first is only used as input, and
214 NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
215 An exception is raised if the named encoding is not known to Python. The
232 Unlike the ``es`` format, this variant allows input data which contains NUL
237 NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
238 An exception is raised if the named encoding is not known to Python. The
252 If *\*buffer* points to a non-``NULL`` pointer (an already allocated buffer),
255 encoded data into the buffer and NUL-terminate it. If the buffer is not large
267 -------
270 Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
274 Convert a Python integer to a tiny int without overflow checking, stored in a C
278 Convert a Python integer to a C :c:expr:`short int`.
281 Convert a Python integer to a C :c:expr:`unsigned short int`, without overflow
285 Convert a Python integer to a plain C :c:expr:`int`.
288 Convert a Python integer to a C :c:expr:`unsigned int`, without overflow
292 Convert a Python integer to a C :c:expr:`long int`.
295 Convert a Python integer to a C :c:expr:`unsigned long` without
299 Convert a Python integer to a C :c:expr:`long long`.
302 Convert a Python integer to a C :c:expr:`unsigned long long`
306 Convert a Python integer to a C :c:type:`Py_ssize_t`.
309 Convert a Python byte, represented as a :class:`bytes` or
316 Convert a Python character, represented as a :class:`str` object of
320 Convert a Python floating point number to a C :c:expr:`float`.
323 Convert a Python floating point number to a C :c:expr:`double`.
326 Convert a Python complex number to a C :c:type:`Py_complex` structure.
329 -------------
332 Store a Python object (without any conversion) in a C object pointer. The C
337 Store a Python object in a C object pointer. This is similar to ``O``, but
338 takes two C arguments: the first is the address of a Python type object, the
340 the object pointer is stored. If the Python object does not have the required
346 Convert a Python object to a C variable through a *converter* function. This
353 where *object* is the Python object to be converted and *address* is the
372 This accepts any valid Python value. See :ref:`truth` for more
373 information about how Python tests values for truth.
377 ``(items)`` (:class:`tuple`) [*matching-items*]
378 The object must be a Python sequence whose length is the number of format units
379 in *items*. The C arguments must correspond to the individual format units in
380 *items*. Format units for sequences may be nested.
383 platform's :const:`LONG_MAX`) however no proper range checking is done --- the
386 in C --- your mileage may vary).
388 A few other characters have a meaning in a format string. These may not occur
392 Indicates that the remaining arguments in the Python argument list are optional.
394 their default value --- when an optional argument is not specified,
400 Indicates that the remaining arguments in the Python argument list are
401 keyword-only. Currently, all keyword-only arguments must also be optional
402 arguments, so ``|`` must always be specified before ``$`` in the format
408 The list of format units ends here; the string after the colon is used as the
413 The list of format units ends here; the string after the semicolon is used as
417 Note that any Python object references which are provided to the caller are
421 whose type is determined by the format string; these are used to store values
422 from the input tuple. There are a few cases, as described in the list of format
424 what is specified for the corresponding format unit in that case.
426 For the conversion to succeed, the *arg* object must match the format
427 and the format must be exhausted. On success, the
431 of the format units, the variables at the addresses corresponding to that
432 and the following format units are left untouched.
435 -------------
437 .. c:function:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
444 .. c:function:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
450 .. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, c…
454 ``NULL``-terminated array of keyword parameter names. Empty names denote
455 :ref:`positional-only parameters <positional-only_parameter>`.
460 Added support for :ref:`positional-only parameters
461 <positional-only_parameter>`.
464 .. c:function:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format,…
480 .. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...)
482 Function used to deconstruct the argument lists of "old-style" functions ---
484 method, which has been removed in Python 3. This is not recommended for use
493 A simpler form of parameter retrieval which does not use a format string to
530 ---------------
532 ---------------
534 .. c:function:: PyObject* Py_BuildValue(const char *format, ...)
536 Create a new value based on a format string similar to those accepted by the
542 its format string contains two or more format units. If the format string is
543 empty, it returns ``None``; if it contains exactly one format unit, it returns
544 whatever object is described by that format unit. To force it to return a tuple
545 of size 0 or one, parenthesize the format string.
555 In the following description, the quoted form is the format unit; the entry in
556 (round) parentheses is the Python object type that the format unit will return;
559 The characters space, tab, colon and comma are ignored in format strings (but
560 not within format units such as ``s#``). This can be used to make long format
564 Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
568 Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
573 This converts a C string to a Python :class:`bytes` object. If the C
577 This converts a C string and its lengths to a Python object. If the C
587 Convert a null-terminated :c:expr:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
588 data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``,
592 Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python
603 Convert a plain C :c:expr:`int` to a Python integer object.
606 Convert a plain C :c:expr:`char` to a Python integer object.
609 Convert a plain C :c:expr:`short int` to a Python integer object.
612 Convert a C :c:expr:`long int` to a Python integer object.
615 Convert a C :c:expr:`unsigned char` to a Python integer object.
618 Convert a C :c:expr:`unsigned short int` to a Python integer object.
621 Convert a C :c:expr:`unsigned int` to a Python integer object.
624 Convert a C :c:expr:`unsigned long` to a Python integer object.
627 Convert a C :c:expr:`long long` to a Python integer object.
630 Convert a C :c:expr:`unsigned long long` to a Python integer object.
633 Convert a C :c:type:`Py_ssize_t` to a Python integer.
636 Convert a C :c:expr:`int` representing a byte to a Python :class:`bytes` object of
640 Convert a C :c:expr:`int` representing a character to Python :class:`str`
644 Convert a C :c:expr:`double` to a Python floating point number.
647 Convert a C :c:expr:`float` to a Python floating point number.
650 Convert a C :c:type:`Py_complex` structure to a Python complex number.
653 Pass a Python object untouched (except for its reference count, which is
669 Convert *anything* to a Python object through a *converter* function. The
671 as its argument and should return a "new" Python object, or ``NULL`` if an
674 ``(items)`` (:class:`tuple`) [*matching-items*]
675 Convert a sequence of C values to a Python tuple with the same number of items.
677 ``[items]`` (:class:`list`) [*matching-items*]
678 Convert a sequence of C values to a Python list with the same number of items.
680 ``{items}`` (:class:`dict`) [*matching-items*]
681 Convert a sequence of C values to a Python dictionary. Each pair of consecutive
685 If there is an error in the format string, the :exc:`SystemError` exception is
688 .. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)