2008-01-20 05:30:57 -04:00
|
|
|
.. highlightlang:: c
|
|
|
|
|
|
|
|
.. _arg-parsing:
|
|
|
|
|
|
|
|
Parsing arguments and building values
|
|
|
|
=====================================
|
|
|
|
|
|
|
|
These functions are useful when creating your own extensions functions and
|
|
|
|
methods. Additional information and examples are available in
|
|
|
|
:ref:`extending-index`.
|
|
|
|
|
|
|
|
The first three of these functions described, :cfunc:`PyArg_ParseTuple`,
|
|
|
|
:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use *format
|
|
|
|
strings* which are used to tell the function about the expected arguments. The
|
|
|
|
format strings use the same syntax for each of these functions.
|
|
|
|
|
|
|
|
A format string consists of zero or more "format units." A format unit
|
|
|
|
describes one Python object; it is usually a single character or a parenthesized
|
|
|
|
sequence of format units. With a few exceptions, a format unit that is not a
|
|
|
|
parenthesized sequence normally corresponds to a single address argument to
|
|
|
|
these functions. In the following description, the quoted form is the format
|
|
|
|
unit; the entry in (round) parentheses is the Python object type that matches
|
|
|
|
the format unit; and the entry in [square] brackets is the type of the C
|
|
|
|
variable(s) whose address should be passed.
|
|
|
|
|
|
|
|
``s`` (string or Unicode object) [const char \*]
|
|
|
|
Convert a Python string or Unicode object to a C pointer to a character string.
|
|
|
|
You must not provide storage for the string itself; a pointer to an existing
|
|
|
|
string is stored into the character pointer variable whose address you pass.
|
|
|
|
The C string is NUL-terminated. The Python string must not contain embedded NUL
|
|
|
|
bytes; if it does, a :exc:`TypeError` exception is raised. Unicode objects are
|
|
|
|
converted to C strings using the default encoding. If this conversion fails, a
|
|
|
|
:exc:`UnicodeError` is raised.
|
|
|
|
|
Merged revisions 67348,67355,67359,67362,67364-67365,67367-67368,67398,67423-67424,67432,67440-67441,67444-67445,67454-67455,67457-67458 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r67348 | benjamin.peterson | 2008-11-22 20:09:41 -0600 (Sat, 22 Nov 2008) | 1 line
raise a better error
........
r67355 | georg.brandl | 2008-11-23 13:17:25 -0600 (Sun, 23 Nov 2008) | 2 lines
#4392: fix parameter name.
........
r67359 | georg.brandl | 2008-11-23 15:57:30 -0600 (Sun, 23 Nov 2008) | 2 lines
#4399: fix typo.
........
r67362 | gregory.p.smith | 2008-11-23 18:41:43 -0600 (Sun, 23 Nov 2008) | 2 lines
Document PY_SSIZE_T_CLEAN for PyArg_ParseTuple.
........
r67364 | benjamin.peterson | 2008-11-23 19:16:29 -0600 (Sun, 23 Nov 2008) | 2 lines
replace reference to debugger-hooks
........
r67365 | benjamin.peterson | 2008-11-23 22:09:03 -0600 (Sun, 23 Nov 2008) | 1 line
#4396 make the parser module correctly validate the with syntax
........
r67367 | georg.brandl | 2008-11-24 10:16:07 -0600 (Mon, 24 Nov 2008) | 2 lines
Fix typo.
........
r67368 | georg.brandl | 2008-11-24 13:56:47 -0600 (Mon, 24 Nov 2008) | 2 lines
#4404: make clear what "path" is.
........
r67398 | benjamin.peterson | 2008-11-26 11:39:17 -0600 (Wed, 26 Nov 2008) | 1 line
fix typo in sqlite3 docs
........
r67423 | jesse.noller | 2008-11-28 12:59:35 -0600 (Fri, 28 Nov 2008) | 2 lines
issue4238: bsd support for cpu_count
........
r67424 | christian.heimes | 2008-11-28 13:33:33 -0600 (Fri, 28 Nov 2008) | 1 line
Retain copyright of processing examples. This was requested by a Debian maintainer during packaging of the multiprocessing package for 2.4/2.5
........
r67432 | benjamin.peterson | 2008-11-28 17:18:46 -0600 (Fri, 28 Nov 2008) | 1 line
SVN format 9 is the same it seems
........
r67440 | jeremy.hylton | 2008-11-28 17:42:59 -0600 (Fri, 28 Nov 2008) | 4 lines
Move definition int sval into branch of ifdef where it is used.
Otherwise, you get a warning about an undefined variable.
........
r67441 | jeremy.hylton | 2008-11-28 18:09:16 -0600 (Fri, 28 Nov 2008) | 2 lines
Reflow long lines.
........
r67444 | amaury.forgeotdarc | 2008-11-28 20:03:32 -0600 (Fri, 28 Nov 2008) | 2 lines
Fix a small typo in docstring
........
r67445 | benjamin.peterson | 2008-11-29 21:07:33 -0600 (Sat, 29 Nov 2008) | 1 line
StringIO.close() stops you from using the buffer, too
........
r67454 | benjamin.peterson | 2008-11-30 08:43:23 -0600 (Sun, 30 Nov 2008) | 1 line
note the version that works
........
r67455 | martin.v.loewis | 2008-11-30 13:28:27 -0600 (Sun, 30 Nov 2008) | 1 line
Issue #4365: Add crtassem.h constants to the msvcrt module.
........
r67457 | christian.heimes | 2008-11-30 15:16:28 -0600 (Sun, 30 Nov 2008) | 1 line
w# requires Py_ssize_t
........
r67458 | benjamin.peterson | 2008-11-30 15:46:16 -0600 (Sun, 30 Nov 2008) | 1 line
fix pyspecific extensions that were broken by Sphinx's grand renaming
........
2008-11-30 18:46:23 -04:00
|
|
|
Starting with Python 2.5 the type of the length argument can be
|
|
|
|
controlled by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before
|
|
|
|
including :file:`Python.h`. If the macro is defined, length is a
|
|
|
|
:ctype:`Py_ssize_t` rather than an int.
|
|
|
|
|
2008-08-13 12:53:07 -03:00
|
|
|
``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer \*]
|
2008-09-01 13:45:35 -03:00
|
|
|
This is similar to ``s``, but the code fills a :ctype:`Py_buffer` structure
|
|
|
|
provided by the caller. In this case the Python string may contain embedded
|
|
|
|
null bytes. Unicode objects pass back a pointer to the default encoded
|
|
|
|
string version of the object if such a conversion is possible. The
|
|
|
|
underlying buffer is locked, so that the caller can subsequently use the
|
|
|
|
buffer even inside a ``Py_BEGIN_ALLOW_THREADS`` block. **The caller is
|
|
|
|
responsible** for calling ``PyBuffer_Release`` with the structure after it
|
|
|
|
has processed the data.
|
2008-08-13 12:53:07 -03:00
|
|
|
|
2008-11-23 19:49:16 -04:00
|
|
|
``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int or :ctype:`Py_ssize_t`]
|
Merged revisions 67348,67355,67359,67362,67364-67365,67367-67368,67398,67423-67424,67432,67440-67441,67444-67445,67454-67455,67457-67458 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r67348 | benjamin.peterson | 2008-11-22 20:09:41 -0600 (Sat, 22 Nov 2008) | 1 line
raise a better error
........
r67355 | georg.brandl | 2008-11-23 13:17:25 -0600 (Sun, 23 Nov 2008) | 2 lines
#4392: fix parameter name.
........
r67359 | georg.brandl | 2008-11-23 15:57:30 -0600 (Sun, 23 Nov 2008) | 2 lines
#4399: fix typo.
........
r67362 | gregory.p.smith | 2008-11-23 18:41:43 -0600 (Sun, 23 Nov 2008) | 2 lines
Document PY_SSIZE_T_CLEAN for PyArg_ParseTuple.
........
r67364 | benjamin.peterson | 2008-11-23 19:16:29 -0600 (Sun, 23 Nov 2008) | 2 lines
replace reference to debugger-hooks
........
r67365 | benjamin.peterson | 2008-11-23 22:09:03 -0600 (Sun, 23 Nov 2008) | 1 line
#4396 make the parser module correctly validate the with syntax
........
r67367 | georg.brandl | 2008-11-24 10:16:07 -0600 (Mon, 24 Nov 2008) | 2 lines
Fix typo.
........
r67368 | georg.brandl | 2008-11-24 13:56:47 -0600 (Mon, 24 Nov 2008) | 2 lines
#4404: make clear what "path" is.
........
r67398 | benjamin.peterson | 2008-11-26 11:39:17 -0600 (Wed, 26 Nov 2008) | 1 line
fix typo in sqlite3 docs
........
r67423 | jesse.noller | 2008-11-28 12:59:35 -0600 (Fri, 28 Nov 2008) | 2 lines
issue4238: bsd support for cpu_count
........
r67424 | christian.heimes | 2008-11-28 13:33:33 -0600 (Fri, 28 Nov 2008) | 1 line
Retain copyright of processing examples. This was requested by a Debian maintainer during packaging of the multiprocessing package for 2.4/2.5
........
r67432 | benjamin.peterson | 2008-11-28 17:18:46 -0600 (Fri, 28 Nov 2008) | 1 line
SVN format 9 is the same it seems
........
r67440 | jeremy.hylton | 2008-11-28 17:42:59 -0600 (Fri, 28 Nov 2008) | 4 lines
Move definition int sval into branch of ifdef where it is used.
Otherwise, you get a warning about an undefined variable.
........
r67441 | jeremy.hylton | 2008-11-28 18:09:16 -0600 (Fri, 28 Nov 2008) | 2 lines
Reflow long lines.
........
r67444 | amaury.forgeotdarc | 2008-11-28 20:03:32 -0600 (Fri, 28 Nov 2008) | 2 lines
Fix a small typo in docstring
........
r67445 | benjamin.peterson | 2008-11-29 21:07:33 -0600 (Sat, 29 Nov 2008) | 1 line
StringIO.close() stops you from using the buffer, too
........
r67454 | benjamin.peterson | 2008-11-30 08:43:23 -0600 (Sun, 30 Nov 2008) | 1 line
note the version that works
........
r67455 | martin.v.loewis | 2008-11-30 13:28:27 -0600 (Sun, 30 Nov 2008) | 1 line
Issue #4365: Add crtassem.h constants to the msvcrt module.
........
r67457 | christian.heimes | 2008-11-30 15:16:28 -0600 (Sun, 30 Nov 2008) | 1 line
w# requires Py_ssize_t
........
r67458 | benjamin.peterson | 2008-11-30 15:46:16 -0600 (Sun, 30 Nov 2008) | 1 line
fix pyspecific extensions that were broken by Sphinx's grand renaming
........
2008-11-30 18:46:23 -04:00
|
|
|
This variant on ``s`` stores into two C variables, the first one a pointer to
|
|
|
|
a character string, the second one its length. In this case the Python
|
|
|
|
string may contain embedded null bytes. Unicode objects pass back a pointer
|
|
|
|
to the default encoded string version of the object if such a conversion is
|
|
|
|
possible. All other read-buffer compatible objects pass back a reference to
|
Merged revisions 68162,68166,68171,68176,68195-68196,68210,68232 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r68162 | ronald.oussoren | 2009-01-02 16:06:00 +0100 (Fri, 02 Jan 2009) | 3 lines
Fix for issue 4472 is incompatible with Cygwin, this patch
should fix that.
........
r68166 | benjamin.peterson | 2009-01-02 19:26:23 +0100 (Fri, 02 Jan 2009) | 1 line
document PyMemberDef
........
r68171 | georg.brandl | 2009-01-02 21:25:14 +0100 (Fri, 02 Jan 2009) | 3 lines
#4811: fix markup glitches (mostly remains of the conversion),
found by Gabriel Genellina.
........
r68176 | andrew.kuchling | 2009-01-02 22:00:35 +0100 (Fri, 02 Jan 2009) | 1 line
Add various items
........
r68195 | georg.brandl | 2009-01-03 14:45:15 +0100 (Sat, 03 Jan 2009) | 2 lines
Remove useless string literal.
........
r68196 | georg.brandl | 2009-01-03 15:29:53 +0100 (Sat, 03 Jan 2009) | 2 lines
Fix indentation.
........
r68210 | georg.brandl | 2009-01-03 20:10:12 +0100 (Sat, 03 Jan 2009) | 2 lines
Set eol-style correctly for mp_distributing.py.
........
r68232 | georg.brandl | 2009-01-03 22:52:16 +0100 (Sat, 03 Jan 2009) | 2 lines
Grammar fix.
........
2009-01-03 18:47:39 -04:00
|
|
|
the raw internal data representation. Since this format doesn't allow
|
|
|
|
writable buffer compatible objects like byte arrays, ``s*`` is to be
|
|
|
|
preferred.
|
Merged revisions 67348,67355,67359,67362,67364-67365,67367-67368,67398,67423-67424,67432,67440-67441,67444-67445,67454-67455,67457-67458 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r67348 | benjamin.peterson | 2008-11-22 20:09:41 -0600 (Sat, 22 Nov 2008) | 1 line
raise a better error
........
r67355 | georg.brandl | 2008-11-23 13:17:25 -0600 (Sun, 23 Nov 2008) | 2 lines
#4392: fix parameter name.
........
r67359 | georg.brandl | 2008-11-23 15:57:30 -0600 (Sun, 23 Nov 2008) | 2 lines
#4399: fix typo.
........
r67362 | gregory.p.smith | 2008-11-23 18:41:43 -0600 (Sun, 23 Nov 2008) | 2 lines
Document PY_SSIZE_T_CLEAN for PyArg_ParseTuple.
........
r67364 | benjamin.peterson | 2008-11-23 19:16:29 -0600 (Sun, 23 Nov 2008) | 2 lines
replace reference to debugger-hooks
........
r67365 | benjamin.peterson | 2008-11-23 22:09:03 -0600 (Sun, 23 Nov 2008) | 1 line
#4396 make the parser module correctly validate the with syntax
........
r67367 | georg.brandl | 2008-11-24 10:16:07 -0600 (Mon, 24 Nov 2008) | 2 lines
Fix typo.
........
r67368 | georg.brandl | 2008-11-24 13:56:47 -0600 (Mon, 24 Nov 2008) | 2 lines
#4404: make clear what "path" is.
........
r67398 | benjamin.peterson | 2008-11-26 11:39:17 -0600 (Wed, 26 Nov 2008) | 1 line
fix typo in sqlite3 docs
........
r67423 | jesse.noller | 2008-11-28 12:59:35 -0600 (Fri, 28 Nov 2008) | 2 lines
issue4238: bsd support for cpu_count
........
r67424 | christian.heimes | 2008-11-28 13:33:33 -0600 (Fri, 28 Nov 2008) | 1 line
Retain copyright of processing examples. This was requested by a Debian maintainer during packaging of the multiprocessing package for 2.4/2.5
........
r67432 | benjamin.peterson | 2008-11-28 17:18:46 -0600 (Fri, 28 Nov 2008) | 1 line
SVN format 9 is the same it seems
........
r67440 | jeremy.hylton | 2008-11-28 17:42:59 -0600 (Fri, 28 Nov 2008) | 4 lines
Move definition int sval into branch of ifdef where it is used.
Otherwise, you get a warning about an undefined variable.
........
r67441 | jeremy.hylton | 2008-11-28 18:09:16 -0600 (Fri, 28 Nov 2008) | 2 lines
Reflow long lines.
........
r67444 | amaury.forgeotdarc | 2008-11-28 20:03:32 -0600 (Fri, 28 Nov 2008) | 2 lines
Fix a small typo in docstring
........
r67445 | benjamin.peterson | 2008-11-29 21:07:33 -0600 (Sat, 29 Nov 2008) | 1 line
StringIO.close() stops you from using the buffer, too
........
r67454 | benjamin.peterson | 2008-11-30 08:43:23 -0600 (Sun, 30 Nov 2008) | 1 line
note the version that works
........
r67455 | martin.v.loewis | 2008-11-30 13:28:27 -0600 (Sun, 30 Nov 2008) | 1 line
Issue #4365: Add crtassem.h constants to the msvcrt module.
........
r67457 | christian.heimes | 2008-11-30 15:16:28 -0600 (Sun, 30 Nov 2008) | 1 line
w# requires Py_ssize_t
........
r67458 | benjamin.peterson | 2008-11-30 15:46:16 -0600 (Sun, 30 Nov 2008) | 1 line
fix pyspecific extensions that were broken by Sphinx's grand renaming
........
2008-11-30 18:46:23 -04:00
|
|
|
|
|
|
|
The type of the length argument (int or :ctype:`Py_ssize_t`) is controlled by
|
2008-11-23 19:49:16 -04:00
|
|
|
defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including
|
|
|
|
:file:`Python.h`. If the macro was defined, length is a :ctype:`Py_ssize_t`
|
Merged revisions 67348,67355,67359,67362,67364-67365,67367-67368,67398,67423-67424,67432,67440-67441,67444-67445,67454-67455,67457-67458 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r67348 | benjamin.peterson | 2008-11-22 20:09:41 -0600 (Sat, 22 Nov 2008) | 1 line
raise a better error
........
r67355 | georg.brandl | 2008-11-23 13:17:25 -0600 (Sun, 23 Nov 2008) | 2 lines
#4392: fix parameter name.
........
r67359 | georg.brandl | 2008-11-23 15:57:30 -0600 (Sun, 23 Nov 2008) | 2 lines
#4399: fix typo.
........
r67362 | gregory.p.smith | 2008-11-23 18:41:43 -0600 (Sun, 23 Nov 2008) | 2 lines
Document PY_SSIZE_T_CLEAN for PyArg_ParseTuple.
........
r67364 | benjamin.peterson | 2008-11-23 19:16:29 -0600 (Sun, 23 Nov 2008) | 2 lines
replace reference to debugger-hooks
........
r67365 | benjamin.peterson | 2008-11-23 22:09:03 -0600 (Sun, 23 Nov 2008) | 1 line
#4396 make the parser module correctly validate the with syntax
........
r67367 | georg.brandl | 2008-11-24 10:16:07 -0600 (Mon, 24 Nov 2008) | 2 lines
Fix typo.
........
r67368 | georg.brandl | 2008-11-24 13:56:47 -0600 (Mon, 24 Nov 2008) | 2 lines
#4404: make clear what "path" is.
........
r67398 | benjamin.peterson | 2008-11-26 11:39:17 -0600 (Wed, 26 Nov 2008) | 1 line
fix typo in sqlite3 docs
........
r67423 | jesse.noller | 2008-11-28 12:59:35 -0600 (Fri, 28 Nov 2008) | 2 lines
issue4238: bsd support for cpu_count
........
r67424 | christian.heimes | 2008-11-28 13:33:33 -0600 (Fri, 28 Nov 2008) | 1 line
Retain copyright of processing examples. This was requested by a Debian maintainer during packaging of the multiprocessing package for 2.4/2.5
........
r67432 | benjamin.peterson | 2008-11-28 17:18:46 -0600 (Fri, 28 Nov 2008) | 1 line
SVN format 9 is the same it seems
........
r67440 | jeremy.hylton | 2008-11-28 17:42:59 -0600 (Fri, 28 Nov 2008) | 4 lines
Move definition int sval into branch of ifdef where it is used.
Otherwise, you get a warning about an undefined variable.
........
r67441 | jeremy.hylton | 2008-11-28 18:09:16 -0600 (Fri, 28 Nov 2008) | 2 lines
Reflow long lines.
........
r67444 | amaury.forgeotdarc | 2008-11-28 20:03:32 -0600 (Fri, 28 Nov 2008) | 2 lines
Fix a small typo in docstring
........
r67445 | benjamin.peterson | 2008-11-29 21:07:33 -0600 (Sat, 29 Nov 2008) | 1 line
StringIO.close() stops you from using the buffer, too
........
r67454 | benjamin.peterson | 2008-11-30 08:43:23 -0600 (Sun, 30 Nov 2008) | 1 line
note the version that works
........
r67455 | martin.v.loewis | 2008-11-30 13:28:27 -0600 (Sun, 30 Nov 2008) | 1 line
Issue #4365: Add crtassem.h constants to the msvcrt module.
........
r67457 | christian.heimes | 2008-11-30 15:16:28 -0600 (Sun, 30 Nov 2008) | 1 line
w# requires Py_ssize_t
........
r67458 | benjamin.peterson | 2008-11-30 15:46:16 -0600 (Sun, 30 Nov 2008) | 1 line
fix pyspecific extensions that were broken by Sphinx's grand renaming
........
2008-11-30 18:46:23 -04:00
|
|
|
rather than an int. This behavior will change in a future Python version to
|
|
|
|
only support :ctype:`Py_ssize_t` and drop int support. It is best to always
|
|
|
|
define :cmacro:`PY_SSIZE_T_CLEAN`.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2008-09-01 13:45:35 -03:00
|
|
|
``y`` (bytes object) [const char \*]
|
|
|
|
This variant on ``s`` converts a Python bytes or bytearray object to a C
|
|
|
|
pointer to a character string. The bytes object must not contain embedded
|
|
|
|
NUL bytes; if it does, a :exc:`TypeError` exception is raised.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2008-08-13 12:53:07 -03:00
|
|
|
``y*`` (bytes object) [Py_buffer \*]
|
|
|
|
This is to ``s*`` as ``y`` is to ``s``.
|
|
|
|
|
2008-09-01 13:45:35 -03:00
|
|
|
``y#`` (bytes object) [const char \*, int]
|
|
|
|
This variant on ``s#`` stores into two C variables, the first one a pointer
|
|
|
|
to a character string, the second one its length. This only accepts bytes
|
|
|
|
objects, no byte arrays.
|
|
|
|
|
2008-01-20 05:30:57 -04:00
|
|
|
``z`` (string or ``None``) [const char \*]
|
|
|
|
Like ``s``, but the Python object may also be ``None``, in which case the C
|
|
|
|
pointer is set to *NULL*.
|
|
|
|
|
2008-08-13 12:53:07 -03:00
|
|
|
``z*`` (string or ``None`` or any buffer compatible object) [Py_buffer*]
|
|
|
|
This is to ``s*`` as ``z`` is to ``s``.
|
|
|
|
|
2008-09-01 13:45:35 -03:00
|
|
|
``z#`` (string or ``None`` or any read buffer compatible object) [const char \*, int]
|
|
|
|
This is to ``s#`` as ``z`` is to ``s``.
|
|
|
|
|
2008-01-20 05:30:57 -04:00
|
|
|
``u`` (Unicode object) [Py_UNICODE \*]
|
|
|
|
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
|
|
|
|
16-bit Unicode (UTF-16) data. As with ``s``, there is no need to provide
|
|
|
|
storage for the Unicode data buffer; a pointer to the existing Unicode data is
|
|
|
|
stored into the :ctype:`Py_UNICODE` pointer variable whose address you pass.
|
|
|
|
|
|
|
|
``u#`` (Unicode object) [Py_UNICODE \*, int]
|
|
|
|
This variant on ``u`` stores into two C variables, the first one a pointer to a
|
|
|
|
Unicode data buffer, the second one its length. Non-Unicode objects are handled
|
|
|
|
by interpreting their read-buffer pointer as pointer to a :ctype:`Py_UNICODE`
|
|
|
|
array.
|
|
|
|
|
|
|
|
``Z`` (Unicode or ``None``) [Py_UNICODE \*]
|
|
|
|
Like ``s``, but the Python object may also be ``None``, in which case the C
|
|
|
|
pointer is set to *NULL*.
|
|
|
|
|
|
|
|
``Z#`` (Unicode or ``None``) [Py_UNICODE \*, int]
|
|
|
|
This is to ``u#`` as ``Z`` is to ``u``.
|
|
|
|
|
|
|
|
``es`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
|
|
|
|
This variant on ``s`` is used for encoding Unicode and objects convertible to
|
|
|
|
Unicode into a character buffer. It only works for encoded data without embedded
|
|
|
|
NUL bytes.
|
|
|
|
|
|
|
|
This format requires two arguments. The first is only used as input, and
|
|
|
|
must be a :ctype:`const char\*` which points to the name of an encoding as a
|
|
|
|
NUL-terminated string, or *NULL*, in which case the default encoding is used.
|
|
|
|
An exception is raised if the named encoding is not known to Python. The
|
|
|
|
second argument must be a :ctype:`char\*\*`; the value of the pointer it
|
|
|
|
references will be set to a buffer with the contents of the argument text.
|
|
|
|
The text will be encoded in the encoding specified by the first argument.
|
|
|
|
|
|
|
|
:cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the
|
|
|
|
encoded data into this buffer and adjust *\*buffer* to reference the newly
|
|
|
|
allocated storage. The caller is responsible for calling :cfunc:`PyMem_Free` to
|
|
|
|
free the allocated buffer after use.
|
|
|
|
|
|
|
|
``et`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
|
|
|
|
Same as ``es`` except that 8-bit string objects are passed through without
|
|
|
|
recoding them. Instead, the implementation assumes that the string object uses
|
|
|
|
the encoding passed in as parameter.
|
|
|
|
|
|
|
|
``es#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
|
|
|
|
This variant on ``s#`` is used for encoding Unicode and objects convertible to
|
|
|
|
Unicode into a character buffer. Unlike the ``es`` format, this variant allows
|
|
|
|
input data which contains NUL characters.
|
|
|
|
|
|
|
|
It requires three arguments. The first is only used as input, and must be a
|
|
|
|
:ctype:`const char\*` which points to the name of an encoding as a
|
|
|
|
NUL-terminated string, or *NULL*, in which case the default encoding is used.
|
|
|
|
An exception is raised if the named encoding is not known to Python. The
|
|
|
|
second argument must be a :ctype:`char\*\*`; the value of the pointer it
|
|
|
|
references will be set to a buffer with the contents of the argument text.
|
|
|
|
The text will be encoded in the encoding specified by the first argument.
|
|
|
|
The third argument must be a pointer to an integer; the referenced integer
|
|
|
|
will be set to the number of bytes in the output buffer.
|
|
|
|
|
|
|
|
There are two modes of operation:
|
|
|
|
|
|
|
|
If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of
|
|
|
|
the needed size, copy the encoded data into this buffer and set *\*buffer* to
|
|
|
|
reference the newly allocated storage. The caller is responsible for calling
|
|
|
|
:cfunc:`PyMem_Free` to free the allocated buffer after usage.
|
|
|
|
|
|
|
|
If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
|
|
|
|
:cfunc:`PyArg_ParseTuple` will use this location as the buffer and interpret the
|
|
|
|
initial value of *\*buffer_length* as the buffer size. It will then copy the
|
|
|
|
encoded data into the buffer and NUL-terminate it. If the buffer is not large
|
|
|
|
enough, a :exc:`ValueError` will be set.
|
|
|
|
|
|
|
|
In both cases, *\*buffer_length* is set to the length of the encoded data
|
|
|
|
without the trailing NUL byte.
|
|
|
|
|
Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line
#6513: fix example code: warning categories are classes, not instances.
........
r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line
#6489: fix an ambiguity in getiterator() documentation.
........
r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line
remove docs for deprecated -p option
........
r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line
use bools
........
r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line
Fix arg types of et#.
........
r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line
Dont put "void" in signature for nullary functions.
........
r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line
#6571: add index entries for more operators.
........
r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line
#6593: fix link targets.
........
r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line
#6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line
Add a link to readline, and mention IPython and bpython.
........
r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line
Fix some markup and small factual glitches found by M. Markert.
........
r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line
Fix a few markup glitches.
........
r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line
Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better.
........
2009-07-29 16:54:39 -03:00
|
|
|
``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
|
2008-01-20 05:30:57 -04:00
|
|
|
Same as ``es#`` except that string objects are passed through without recoding
|
|
|
|
them. Instead, the implementation assumes that the string object uses the
|
|
|
|
encoding passed in as parameter.
|
|
|
|
|
Merged revisions 67952,67957-67958,67960-67961,67963,67973,67978,67995,68030,68057,68061 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r67952 | georg.brandl | 2008-12-27 11:42:40 -0600 (Sat, 27 Dec 2008) | 2 lines
#4752: actually use custom handler in example.
........
r67957 | georg.brandl | 2008-12-27 12:49:19 -0600 (Sat, 27 Dec 2008) | 2 lines
#4754: improve winsound documentation.
........
r67958 | georg.brandl | 2008-12-27 13:02:59 -0600 (Sat, 27 Dec 2008) | 2 lines
#4682: 'b' is actually unsigned char.
........
r67960 | georg.brandl | 2008-12-27 13:04:44 -0600 (Sat, 27 Dec 2008) | 2 lines
#4695: fix backslashery.
........
r67961 | georg.brandl | 2008-12-27 13:06:04 -0600 (Sat, 27 Dec 2008) | 2 lines
Use :samp: role.
........
r67963 | georg.brandl | 2008-12-27 13:11:15 -0600 (Sat, 27 Dec 2008) | 2 lines
#4671: document that pydoc imports modules.
........
r67973 | alexandre.vassalotti | 2008-12-27 20:58:22 -0600 (Sat, 27 Dec 2008) | 2 lines
Document Py_VaBuildValue.
........
r67978 | georg.brandl | 2008-12-28 05:58:49 -0600 (Sun, 28 Dec 2008) | 2 lines
#4731: clarify message about missing module prerequisites.
........
r67995 | benjamin.peterson | 2008-12-28 15:16:07 -0600 (Sun, 28 Dec 2008) | 1 line
#4763 PyErr_ExceptionMatches won't blow up with NULL arguments
........
r68030 | benjamin.peterson | 2008-12-29 15:38:14 -0600 (Mon, 29 Dec 2008) | 1 line
fix French
........
r68057 | vinay.sajip | 2008-12-30 01:01:25 -0600 (Tue, 30 Dec 2008) | 1 line
Minor documentation change relating to NullHandler.
........
r68061 | georg.brandl | 2008-12-30 04:15:49 -0600 (Tue, 30 Dec 2008) | 2 lines
#4778: attributes can't be called.
........
2008-12-31 20:23:30 -04:00
|
|
|
``b`` (integer) [unsigned char]
|
|
|
|
Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
|
|
|
|
:ctype:`unsigned char`.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
``B`` (integer) [unsigned char]
|
|
|
|
Convert a Python integer to a tiny int without overflow checking, stored in a C
|
|
|
|
:ctype:`unsigned char`.
|
|
|
|
|
|
|
|
``h`` (integer) [short int]
|
|
|
|
Convert a Python integer to a C :ctype:`short int`.
|
|
|
|
|
|
|
|
``H`` (integer) [unsigned short int]
|
|
|
|
Convert a Python integer to a C :ctype:`unsigned short int`, without overflow
|
|
|
|
checking.
|
|
|
|
|
|
|
|
``i`` (integer) [int]
|
|
|
|
Convert a Python integer to a plain C :ctype:`int`.
|
|
|
|
|
|
|
|
``I`` (integer) [unsigned int]
|
|
|
|
Convert a Python integer to a C :ctype:`unsigned int`, without overflow
|
|
|
|
checking.
|
|
|
|
|
|
|
|
``l`` (integer) [long int]
|
|
|
|
Convert a Python integer to a C :ctype:`long int`.
|
|
|
|
|
|
|
|
``k`` (integer) [unsigned long]
|
|
|
|
Convert a Python integer to a C :ctype:`unsigned long` without
|
|
|
|
overflow checking.
|
|
|
|
|
|
|
|
``L`` (integer) [PY_LONG_LONG]
|
|
|
|
Convert a Python integer to a C :ctype:`long long`. This format is only
|
|
|
|
available on platforms that support :ctype:`long long` (or :ctype:`_int64` on
|
|
|
|
Windows).
|
|
|
|
|
|
|
|
``K`` (integer) [unsigned PY_LONG_LONG]
|
|
|
|
Convert a Python integer to a C :ctype:`unsigned long long`
|
|
|
|
without overflow checking. This format is only available on platforms that
|
|
|
|
support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on Windows).
|
|
|
|
|
|
|
|
``n`` (integer) [Py_ssize_t]
|
|
|
|
Convert a Python integer to a C :ctype:`Py_ssize_t`.
|
|
|
|
|
|
|
|
``c`` (string of length 1) [char]
|
2009-04-01 21:33:55 -03:00
|
|
|
Convert a Python character, represented as a byte string of length 1, to a C
|
2008-01-20 05:30:57 -04:00
|
|
|
:ctype:`char`.
|
|
|
|
|
2009-04-01 21:33:55 -03:00
|
|
|
``C`` (string of length 1) [int]
|
2009-04-03 19:18:11 -03:00
|
|
|
Convert a Python character, represented as a unicode string of length 1, to a
|
2009-04-01 21:33:55 -03:00
|
|
|
C :ctype:`int`.
|
|
|
|
|
2008-01-20 05:30:57 -04:00
|
|
|
``f`` (float) [float]
|
|
|
|
Convert a Python floating point number to a C :ctype:`float`.
|
|
|
|
|
|
|
|
``d`` (float) [double]
|
|
|
|
Convert a Python floating point number to a C :ctype:`double`.
|
|
|
|
|
|
|
|
``D`` (complex) [Py_complex]
|
|
|
|
Convert a Python complex number to a C :ctype:`Py_complex` structure.
|
|
|
|
|
|
|
|
``O`` (object) [PyObject \*]
|
|
|
|
Store a Python object (without any conversion) in a C object pointer. The C
|
|
|
|
program thus receives the actual object that was passed. The object's reference
|
|
|
|
count is not increased. The pointer stored is not *NULL*.
|
|
|
|
|
|
|
|
``O!`` (object) [*typeobject*, PyObject \*]
|
|
|
|
Store a Python object in a C object pointer. This is similar to ``O``, but
|
|
|
|
takes two C arguments: the first is the address of a Python type object, the
|
|
|
|
second is the address of the C variable (of type :ctype:`PyObject\*`) into which
|
|
|
|
the object pointer is stored. If the Python object does not have the required
|
|
|
|
type, :exc:`TypeError` is raised.
|
|
|
|
|
|
|
|
``O&`` (object) [*converter*, *anything*]
|
|
|
|
Convert a Python object to a C variable through a *converter* function. This
|
|
|
|
takes two arguments: the first is a function, the second is the address of a C
|
|
|
|
variable (of arbitrary type), converted to :ctype:`void \*`. The *converter*
|
|
|
|
function in turn is called as follows::
|
|
|
|
|
|
|
|
status = converter(object, address);
|
|
|
|
|
|
|
|
where *object* is the Python object to be converted and *address* is the
|
|
|
|
:ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*` function.
|
|
|
|
The returned *status* should be ``1`` for a successful conversion and ``0`` if
|
|
|
|
the conversion has failed. When the conversion fails, the *converter* function
|
Merged revisions 61209-61214,61217-61222,61224-61226,61233-61237 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r61209 | georg.brandl | 2008-03-03 21:37:55 +0100 (Mon, 03 Mar 2008) | 2 lines
There are now sixteen isfoo functions.
........
r61210 | georg.brandl | 2008-03-03 21:39:00 +0100 (Mon, 03 Mar 2008) | 2 lines
15 -> 16, the 2nd
........
r61211 | georg.brandl | 2008-03-03 22:22:47 +0100 (Mon, 03 Mar 2008) | 2 lines
Actually import itertools.
........
r61212 | georg.brandl | 2008-03-03 22:31:50 +0100 (Mon, 03 Mar 2008) | 2 lines
Expand a bit on genexp scopes.
........
r61213 | raymond.hettinger | 2008-03-03 23:04:55 +0100 (Mon, 03 Mar 2008) | 1 line
Remove dependency on itertools -- a simple genexp suffices.
........
r61214 | raymond.hettinger | 2008-03-03 23:19:58 +0100 (Mon, 03 Mar 2008) | 1 line
Issue 2226: Callable checked for the wrong abstract method.
........
r61217 | andrew.kuchling | 2008-03-04 01:40:32 +0100 (Tue, 04 Mar 2008) | 1 line
Typo fix
........
r61218 | andrew.kuchling | 2008-03-04 02:30:10 +0100 (Tue, 04 Mar 2008) | 1 line
Grammar fix; markup fix
........
r61219 | andrew.kuchling | 2008-03-04 02:47:38 +0100 (Tue, 04 Mar 2008) | 1 line
Fix sentence fragment
........
r61220 | andrew.kuchling | 2008-03-04 02:48:26 +0100 (Tue, 04 Mar 2008) | 1 line
Typo fix
........
r61221 | andrew.kuchling | 2008-03-04 02:49:37 +0100 (Tue, 04 Mar 2008) | 1 line
Add versionadded tags
........
r61222 | andrew.kuchling | 2008-03-04 02:50:32 +0100 (Tue, 04 Mar 2008) | 1 line
Thesis night results: add various items
........
r61224 | raymond.hettinger | 2008-03-04 05:17:08 +0100 (Tue, 04 Mar 2008) | 1 line
Beef-up docs and tests for itertools. Fix-up end-case for product().
........
r61225 | georg.brandl | 2008-03-04 08:25:54 +0100 (Tue, 04 Mar 2008) | 2 lines
Fix some patch attributions.
........
r61226 | georg.brandl | 2008-03-04 08:33:30 +0100 (Tue, 04 Mar 2008) | 2 lines
#2230: document that PyArg_* leaves addresses alone on error.
........
r61233 | neal.norwitz | 2008-03-04 17:22:46 +0100 (Tue, 04 Mar 2008) | 3 lines
Close the file before trying to remove the directory so it works on Windows.
As reported by Trent Nelson on python-dev.
........
r61234 | thomas.heller | 2008-03-04 21:09:11 +0100 (Tue, 04 Mar 2008) | 9 lines
Merged changes from libffi3-branch.
The bundled libffi copy is now in sync with the recently released
libffi3.0.4 version, apart from some small changes to
Modules/_ctypes/libffi/configure.ac.
I gave up on using libffi3 files on os x.
Instead, static configuration with files from pyobjc is used.
........
r61235 | thomas.heller | 2008-03-04 21:21:42 +0100 (Tue, 04 Mar 2008) | 1 line
Try to fix the build for PY_LINUX.
........
r61236 | fred.drake | 2008-03-04 22:14:04 +0100 (Tue, 04 Mar 2008) | 2 lines
fix typo
........
r61237 | raymond.hettinger | 2008-03-04 23:29:44 +0100 (Tue, 04 Mar 2008) | 1 line
Fix refleak in chain().
........
2008-03-04 19:39:23 -04:00
|
|
|
should raise an exception and leave the content of *address* unmodified.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2009-05-29 11:47:46 -03:00
|
|
|
If the *converter* returns Py_CLEANUP_SUPPORTED, it may get called a second time
|
|
|
|
if the argument parsing eventually fails, giving the converter a chance to release
|
|
|
|
any memory that it had already allocated. In this second call, the *object* parameter
|
|
|
|
will be NULL; *address* will have the same value as in the original call.
|
|
|
|
|
|
|
|
.. versionchanged:: 3.1
|
|
|
|
Py_CLEANUP_SUPPORTED was added.
|
|
|
|
|
2008-01-20 05:30:57 -04:00
|
|
|
``S`` (string) [PyStringObject \*]
|
|
|
|
Like ``O`` but requires that the Python object is a string object. Raises
|
|
|
|
:exc:`TypeError` if the object is not a string object. The C variable may also
|
|
|
|
be declared as :ctype:`PyObject\*`.
|
|
|
|
|
|
|
|
``U`` (Unicode string) [PyUnicodeObject \*]
|
|
|
|
Like ``O`` but requires that the Python object is a Unicode object. Raises
|
|
|
|
:exc:`TypeError` if the object is not a Unicode object. The C variable may also
|
|
|
|
be declared as :ctype:`PyObject\*`.
|
|
|
|
|
|
|
|
``t#`` (read-only character buffer) [char \*, int]
|
|
|
|
Like ``s#``, but accepts any object which implements the read-only buffer
|
|
|
|
interface. The :ctype:`char\*` variable is set to point to the first byte of
|
|
|
|
the buffer, and the :ctype:`int` is set to the length of the buffer. Only
|
|
|
|
single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
|
|
|
|
others.
|
|
|
|
|
|
|
|
``w`` (read-write character buffer) [char \*]
|
|
|
|
Similar to ``s``, but accepts any object which implements the read-write buffer
|
|
|
|
interface. The caller must determine the length of the buffer by other means,
|
|
|
|
or use ``w#`` instead. Only single-segment buffer objects are accepted;
|
|
|
|
:exc:`TypeError` is raised for all others.
|
|
|
|
|
2008-09-01 13:45:35 -03:00
|
|
|
``w*`` (read-write byte-oriented buffer) [Py_buffer \*]
|
|
|
|
This is to ``w`` what ``s*`` is to ``s``.
|
|
|
|
|
2008-01-20 05:30:57 -04:00
|
|
|
``w#`` (read-write character buffer) [char \*, int]
|
|
|
|
Like ``s#``, but accepts any object which implements the read-write buffer
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
interface. The :ctype:`char \*` variable is set to point to the first byte
|
|
|
|
of the buffer, and the :ctype:`int` is set to the length of the buffer.
|
|
|
|
Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
|
|
|
|
for all others.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
``(items)`` (tuple) [*matching-items*]
|
|
|
|
The object must be a Python sequence whose length is the number of format units
|
|
|
|
in *items*. The C arguments must correspond to the individual format units in
|
|
|
|
*items*. Format units for sequences may be nested.
|
|
|
|
|
|
|
|
It is possible to pass "long" integers (integers whose value exceeds the
|
|
|
|
platform's :const:`LONG_MAX`) however no proper range checking is done --- the
|
|
|
|
most significant bits are silently truncated when the receiving field is too
|
|
|
|
small to receive the value (actually, the semantics are inherited from downcasts
|
|
|
|
in C --- your mileage may vary).
|
|
|
|
|
|
|
|
A few other characters have a meaning in a format string. These may not occur
|
|
|
|
inside nested parentheses. They are:
|
|
|
|
|
|
|
|
``|``
|
|
|
|
Indicates that the remaining arguments in the Python argument list are optional.
|
|
|
|
The C variables corresponding to optional arguments should be initialized to
|
|
|
|
their default value --- when an optional argument is not specified,
|
|
|
|
:cfunc:`PyArg_ParseTuple` does not touch the contents of the corresponding C
|
|
|
|
variable(s).
|
|
|
|
|
|
|
|
``:``
|
|
|
|
The list of format units ends here; the string after the colon is used as the
|
|
|
|
function name in error messages (the "associated value" of the exception that
|
|
|
|
:cfunc:`PyArg_ParseTuple` raises).
|
|
|
|
|
|
|
|
``;``
|
|
|
|
The list of format units ends here; the string after the semicolon is used as
|
Merged revisions 67889-67892,67895,67898,67904-67907,67912,67918,67920-67921,67923-67924,67926-67927,67930,67943 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
................
r67889 | benjamin.peterson | 2008-12-20 19:04:32 -0600 (Sat, 20 Dec 2008) | 1 line
sphinx.web is long gone
................
r67890 | benjamin.peterson | 2008-12-20 19:12:26 -0600 (Sat, 20 Dec 2008) | 1 line
update readme
................
r67891 | benjamin.peterson | 2008-12-20 19:14:47 -0600 (Sat, 20 Dec 2008) | 1 line
there are way too many places which need to have the current version added
................
r67892 | benjamin.peterson | 2008-12-20 19:29:32 -0600 (Sat, 20 Dec 2008) | 9 lines
Merged revisions 67809 via svnmerge from
svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3
........
r67809 | benjamin.peterson | 2008-12-15 21:54:45 -0600 (Mon, 15 Dec 2008) | 1 line
fix logic error
........
................
r67895 | neal.norwitz | 2008-12-21 08:28:32 -0600 (Sun, 21 Dec 2008) | 2 lines
Add Tarek for work on distutils.
................
r67898 | benjamin.peterson | 2008-12-21 15:00:53 -0600 (Sun, 21 Dec 2008) | 1 line
compute DISTVERSION with patchlevel.py
................
r67904 | benjamin.peterson | 2008-12-22 14:44:58 -0600 (Mon, 22 Dec 2008) | 1 line
less attitude
................
r67905 | benjamin.peterson | 2008-12-22 14:51:15 -0600 (Mon, 22 Dec 2008) | 1 line
fix #4720: the format to PyArg_ParseTupleAndKeywords can now start with '|'
................
r67906 | benjamin.peterson | 2008-12-22 14:52:53 -0600 (Mon, 22 Dec 2008) | 1 line
add NEWS note
................
r67907 | benjamin.peterson | 2008-12-22 16:12:19 -0600 (Mon, 22 Dec 2008) | 1 line
silence compiler warning
................
r67912 | georg.brandl | 2008-12-23 06:37:21 -0600 (Tue, 23 Dec 2008) | 2 lines
Fix missing "svn" command.
................
r67918 | georg.brandl | 2008-12-23 09:44:25 -0600 (Tue, 23 Dec 2008) | 2 lines
Markup fix.
................
r67920 | benjamin.peterson | 2008-12-23 14:09:28 -0600 (Tue, 23 Dec 2008) | 1 line
use a global variable, so the compiler doesn't optimize the assignment out
................
r67921 | benjamin.peterson | 2008-12-23 14:12:33 -0600 (Tue, 23 Dec 2008) | 1 line
make global static
................
r67923 | benjamin.peterson | 2008-12-24 09:10:27 -0600 (Wed, 24 Dec 2008) | 1 line
#4736 BufferRWPair.closed shouldn't try to call another property as a function
................
r67924 | benjamin.peterson | 2008-12-24 10:10:05 -0600 (Wed, 24 Dec 2008) | 1 line
pretend exceptions don't exist a while longer
................
r67926 | tarek.ziade | 2008-12-24 13:10:05 -0600 (Wed, 24 Dec 2008) | 1 line
fixed #4400 : distutils .pypirc default generated file was broken.
................
r67927 | benjamin.peterson | 2008-12-26 17:26:30 -0600 (Fri, 26 Dec 2008) | 1 line
python version is included in file name now
................
r67930 | hirokazu.yamamoto | 2008-12-26 22:19:48 -0600 (Fri, 26 Dec 2008) | 2 lines
Issue #4740: Use HIGHEST_PROTOCOL in pickle test.
(There is no behavior difference in 2.x because HIGHEST_PROTOCOL == 2)
................
r67943 | alexandre.vassalotti | 2008-12-27 04:02:59 -0600 (Sat, 27 Dec 2008) | 2 lines
Fix bogus unicode tests in pickletester.
................
2008-12-27 12:00:54 -04:00
|
|
|
the error message *instead* of the default error message. ``:`` and ``;``
|
|
|
|
mutually exclude each other.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
Note that any Python object references which are provided to the caller are
|
|
|
|
*borrowed* references; do not decrement their reference count!
|
|
|
|
|
|
|
|
Additional arguments passed to these functions must be addresses of variables
|
|
|
|
whose type is determined by the format string; these are used to store values
|
|
|
|
from the input tuple. There are a few cases, as described in the list of format
|
|
|
|
units above, where these parameters are used as input values; they should match
|
|
|
|
what is specified for the corresponding format unit in that case.
|
|
|
|
|
Merged revisions 61209-61214,61217-61222,61224-61226,61233-61237 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r61209 | georg.brandl | 2008-03-03 21:37:55 +0100 (Mon, 03 Mar 2008) | 2 lines
There are now sixteen isfoo functions.
........
r61210 | georg.brandl | 2008-03-03 21:39:00 +0100 (Mon, 03 Mar 2008) | 2 lines
15 -> 16, the 2nd
........
r61211 | georg.brandl | 2008-03-03 22:22:47 +0100 (Mon, 03 Mar 2008) | 2 lines
Actually import itertools.
........
r61212 | georg.brandl | 2008-03-03 22:31:50 +0100 (Mon, 03 Mar 2008) | 2 lines
Expand a bit on genexp scopes.
........
r61213 | raymond.hettinger | 2008-03-03 23:04:55 +0100 (Mon, 03 Mar 2008) | 1 line
Remove dependency on itertools -- a simple genexp suffices.
........
r61214 | raymond.hettinger | 2008-03-03 23:19:58 +0100 (Mon, 03 Mar 2008) | 1 line
Issue 2226: Callable checked for the wrong abstract method.
........
r61217 | andrew.kuchling | 2008-03-04 01:40:32 +0100 (Tue, 04 Mar 2008) | 1 line
Typo fix
........
r61218 | andrew.kuchling | 2008-03-04 02:30:10 +0100 (Tue, 04 Mar 2008) | 1 line
Grammar fix; markup fix
........
r61219 | andrew.kuchling | 2008-03-04 02:47:38 +0100 (Tue, 04 Mar 2008) | 1 line
Fix sentence fragment
........
r61220 | andrew.kuchling | 2008-03-04 02:48:26 +0100 (Tue, 04 Mar 2008) | 1 line
Typo fix
........
r61221 | andrew.kuchling | 2008-03-04 02:49:37 +0100 (Tue, 04 Mar 2008) | 1 line
Add versionadded tags
........
r61222 | andrew.kuchling | 2008-03-04 02:50:32 +0100 (Tue, 04 Mar 2008) | 1 line
Thesis night results: add various items
........
r61224 | raymond.hettinger | 2008-03-04 05:17:08 +0100 (Tue, 04 Mar 2008) | 1 line
Beef-up docs and tests for itertools. Fix-up end-case for product().
........
r61225 | georg.brandl | 2008-03-04 08:25:54 +0100 (Tue, 04 Mar 2008) | 2 lines
Fix some patch attributions.
........
r61226 | georg.brandl | 2008-03-04 08:33:30 +0100 (Tue, 04 Mar 2008) | 2 lines
#2230: document that PyArg_* leaves addresses alone on error.
........
r61233 | neal.norwitz | 2008-03-04 17:22:46 +0100 (Tue, 04 Mar 2008) | 3 lines
Close the file before trying to remove the directory so it works on Windows.
As reported by Trent Nelson on python-dev.
........
r61234 | thomas.heller | 2008-03-04 21:09:11 +0100 (Tue, 04 Mar 2008) | 9 lines
Merged changes from libffi3-branch.
The bundled libffi copy is now in sync with the recently released
libffi3.0.4 version, apart from some small changes to
Modules/_ctypes/libffi/configure.ac.
I gave up on using libffi3 files on os x.
Instead, static configuration with files from pyobjc is used.
........
r61235 | thomas.heller | 2008-03-04 21:21:42 +0100 (Tue, 04 Mar 2008) | 1 line
Try to fix the build for PY_LINUX.
........
r61236 | fred.drake | 2008-03-04 22:14:04 +0100 (Tue, 04 Mar 2008) | 2 lines
fix typo
........
r61237 | raymond.hettinger | 2008-03-04 23:29:44 +0100 (Tue, 04 Mar 2008) | 1 line
Fix refleak in chain().
........
2008-03-04 19:39:23 -04:00
|
|
|
For the conversion to succeed, the *arg* object must match the format
|
|
|
|
and the format must be exhausted. On success, the
|
|
|
|
:cfunc:`PyArg_Parse\*` functions return true, otherwise they return
|
|
|
|
false and raise an appropriate exception. When the
|
|
|
|
:cfunc:`PyArg_Parse\*` functions fail due to conversion failure in one
|
|
|
|
of the format units, the variables at the addresses corresponding to that
|
|
|
|
and the following format units are left untouched.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
|
|
|
|
.. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
|
|
|
|
|
|
|
|
Parse the parameters of a function that takes only positional parameters into
|
|
|
|
local variables. Returns true on success; on failure, it returns false and
|
|
|
|
raises the appropriate exception.
|
|
|
|
|
|
|
|
|
|
|
|
.. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
|
|
|
|
|
|
|
|
Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list rather
|
|
|
|
than a variable number of arguments.
|
|
|
|
|
|
|
|
|
|
|
|
.. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
|
|
|
|
|
|
|
|
Parse the parameters of a function that takes both positional and keyword
|
|
|
|
parameters into local variables. Returns true on success; on failure, it
|
|
|
|
returns false and raises the appropriate exception.
|
|
|
|
|
|
|
|
|
|
|
|
.. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
|
|
|
|
|
|
|
|
Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a
|
|
|
|
va_list rather than a variable number of arguments.
|
|
|
|
|
|
|
|
|
|
|
|
.. XXX deprecated, will be removed
|
|
|
|
.. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...)
|
|
|
|
|
|
|
|
Function used to deconstruct the argument lists of "old-style" functions ---
|
|
|
|
these are functions which use the :const:`METH_OLDARGS` parameter parsing
|
|
|
|
method. This is not recommended for use in parameter parsing in new code, and
|
|
|
|
most code in the standard interpreter has been modified to no longer use this
|
|
|
|
for that purpose. It does remain a convenient way to decompose other tuples,
|
|
|
|
however, and may continue to be used for that purpose.
|
|
|
|
|
|
|
|
|
|
|
|
.. cfunction:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
|
|
|
|
|
|
|
|
A simpler form of parameter retrieval which does not use a format string to
|
|
|
|
specify the types of the arguments. Functions which use this method to retrieve
|
|
|
|
their parameters should be declared as :const:`METH_VARARGS` in function or
|
|
|
|
method tables. The tuple containing the actual parameters should be passed as
|
|
|
|
*args*; it must actually be a tuple. The length of the tuple must be at least
|
|
|
|
*min* and no more than *max*; *min* and *max* may be equal. Additional
|
|
|
|
arguments must be passed to the function, each of which should be a pointer to a
|
|
|
|
:ctype:`PyObject\*` variable; these will be filled in with the values from
|
|
|
|
*args*; they will contain borrowed references. The variables which correspond
|
|
|
|
to optional parameters not given by *args* will not be filled in; these should
|
|
|
|
be initialized by the caller. This function returns true on success and false if
|
|
|
|
*args* is not a tuple or contains the wrong number of elements; an exception
|
|
|
|
will be set if there was a failure.
|
|
|
|
|
|
|
|
This is an example of the use of this function, taken from the sources for the
|
|
|
|
:mod:`_weakref` helper module for weak references::
|
|
|
|
|
|
|
|
static PyObject *
|
|
|
|
weakref_ref(PyObject *self, PyObject *args)
|
|
|
|
{
|
|
|
|
PyObject *object;
|
|
|
|
PyObject *callback = NULL;
|
|
|
|
PyObject *result = NULL;
|
|
|
|
|
|
|
|
if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
|
|
|
|
result = PyWeakref_NewRef(object, callback);
|
|
|
|
}
|
|
|
|
return result;
|
|
|
|
}
|
|
|
|
|
|
|
|
The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely equivalent to
|
|
|
|
this call to :cfunc:`PyArg_ParseTuple`::
|
|
|
|
|
|
|
|
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
|
|
|
|
|
|
|
|
|
|
|
|
.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
|
|
|
|
|
|
|
|
Create a new value based on a format string similar to those accepted by the
|
|
|
|
:cfunc:`PyArg_Parse\*` family of functions and a sequence of values. Returns
|
|
|
|
the value or *NULL* in the case of an error; an exception will be raised if
|
|
|
|
*NULL* is returned.
|
|
|
|
|
|
|
|
:cfunc:`Py_BuildValue` does not always build a tuple. It builds a tuple only if
|
|
|
|
its format string contains two or more format units. If the format string is
|
|
|
|
empty, it returns ``None``; if it contains exactly one format unit, it returns
|
|
|
|
whatever object is described by that format unit. To force it to return a tuple
|
|
|
|
of size 0 or one, parenthesize the format string.
|
|
|
|
|
|
|
|
When memory buffers are passed as parameters to supply data to build objects, as
|
|
|
|
for the ``s`` and ``s#`` formats, the required data is copied. Buffers provided
|
|
|
|
by the caller are never referenced by the objects created by
|
|
|
|
:cfunc:`Py_BuildValue`. In other words, if your code invokes :cfunc:`malloc`
|
|
|
|
and passes the allocated memory to :cfunc:`Py_BuildValue`, your code is
|
|
|
|
responsible for calling :cfunc:`free` for that memory once
|
|
|
|
:cfunc:`Py_BuildValue` returns.
|
|
|
|
|
|
|
|
In the following description, the quoted form is the format unit; the entry in
|
|
|
|
(round) parentheses is the Python object type that the format unit will return;
|
|
|
|
and the entry in [square] brackets is the type of the C value(s) to be passed.
|
|
|
|
|
|
|
|
The characters space, tab, colon and comma are ignored in format strings (but
|
|
|
|
not within format units such as ``s#``). This can be used to make long format
|
|
|
|
strings a tad more readable.
|
|
|
|
|
|
|
|
``s`` (string) [char \*]
|
|
|
|
Convert a null-terminated C string to a Python object. If the C string pointer
|
|
|
|
is *NULL*, ``None`` is used.
|
|
|
|
|
|
|
|
``s#`` (string) [char \*, int]
|
|
|
|
Convert a C string and its length to a Python object. If the C string pointer
|
|
|
|
is *NULL*, the length is ignored and ``None`` is returned.
|
|
|
|
|
2008-12-05 03:57:51 -04:00
|
|
|
``y`` (bytes) [char \*]
|
2008-10-21 18:10:07 -03:00
|
|
|
This converts a C string to a Python :func:`bytes` object. If the C
|
|
|
|
string pointer is *NULL*, ``None`` is returned.
|
|
|
|
|
|
|
|
``y#`` (bytes) [char \*, int]
|
|
|
|
This converts a C string and its lengths to a Python object. If the C
|
|
|
|
string pointer is *NULL*, ``None`` is returned.
|
|
|
|
|
2008-01-20 05:30:57 -04:00
|
|
|
``z`` (string or ``None``) [char \*]
|
|
|
|
Same as ``s``.
|
|
|
|
|
|
|
|
``z#`` (string or ``None``) [char \*, int]
|
|
|
|
Same as ``s#``.
|
|
|
|
|
|
|
|
``u`` (Unicode string) [Py_UNICODE \*]
|
|
|
|
Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
|
|
|
|
Unicode object. If the Unicode buffer pointer is *NULL*, ``None`` is returned.
|
|
|
|
|
|
|
|
``u#`` (Unicode string) [Py_UNICODE \*, int]
|
|
|
|
Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python
|
|
|
|
Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored
|
|
|
|
and ``None`` is returned.
|
|
|
|
|
|
|
|
``U`` (string) [char \*]
|
|
|
|
Convert a null-terminated C string to a Python unicode object. If the C string
|
|
|
|
pointer is *NULL*, ``None`` is used.
|
|
|
|
|
|
|
|
``U#`` (string) [char \*, int]
|
|
|
|
Convert a C string and its length to a Python unicode object. If the C string
|
|
|
|
pointer is *NULL*, the length is ignored and ``None`` is returned.
|
|
|
|
|
|
|
|
``i`` (integer) [int]
|
|
|
|
Convert a plain C :ctype:`int` to a Python integer object.
|
|
|
|
|
|
|
|
``b`` (integer) [char]
|
|
|
|
Convert a plain C :ctype:`char` to a Python integer object.
|
|
|
|
|
|
|
|
``h`` (integer) [short int]
|
|
|
|
Convert a plain C :ctype:`short int` to a Python integer object.
|
|
|
|
|
|
|
|
``l`` (integer) [long int]
|
|
|
|
Convert a C :ctype:`long int` to a Python integer object.
|
|
|
|
|
|
|
|
``B`` (integer) [unsigned char]
|
|
|
|
Convert a C :ctype:`unsigned char` to a Python integer object.
|
|
|
|
|
|
|
|
``H`` (integer) [unsigned short int]
|
|
|
|
Convert a C :ctype:`unsigned short int` to a Python integer object.
|
|
|
|
|
2009-01-17 06:21:23 -04:00
|
|
|
``I`` (integer) [unsigned int]
|
|
|
|
Convert a C :ctype:`unsigned int` to a Python integer object.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2009-01-17 06:21:23 -04:00
|
|
|
``k`` (integer) [unsigned long]
|
|
|
|
Convert a C :ctype:`unsigned long` to a Python integer object.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
``L`` (long) [PY_LONG_LONG]
|
|
|
|
Convert a C :ctype:`long long` to a Python integer object. Only available
|
|
|
|
on platforms that support :ctype:`long long`.
|
|
|
|
|
|
|
|
``K`` (long) [unsigned PY_LONG_LONG]
|
|
|
|
Convert a C :ctype:`unsigned long long` to a Python integer object. Only
|
|
|
|
available on platforms that support :ctype:`unsigned long long`.
|
|
|
|
|
|
|
|
``n`` (int) [Py_ssize_t]
|
|
|
|
Convert a C :ctype:`Py_ssize_t` to a Python integer.
|
|
|
|
|
|
|
|
``c`` (string of length 1) [char]
|
2009-04-03 19:18:11 -03:00
|
|
|
Convert a C :ctype:`int` representing a byte to a Python byte string of
|
|
|
|
length 1.
|
|
|
|
|
|
|
|
``C`` (string of length 1) [int]
|
|
|
|
Convert a C :ctype:`int` representing a character to Python unicode
|
|
|
|
string of length 1.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
``d`` (float) [double]
|
|
|
|
Convert a C :ctype:`double` to a Python floating point number.
|
|
|
|
|
|
|
|
``f`` (float) [float]
|
|
|
|
Same as ``d``.
|
|
|
|
|
|
|
|
``D`` (complex) [Py_complex \*]
|
|
|
|
Convert a C :ctype:`Py_complex` structure to a Python complex number.
|
|
|
|
|
|
|
|
``O`` (object) [PyObject \*]
|
|
|
|
Pass a Python object untouched (except for its reference count, which is
|
|
|
|
incremented by one). If the object passed in is a *NULL* pointer, it is assumed
|
|
|
|
that this was caused because the call producing the argument found an error and
|
|
|
|
set an exception. Therefore, :cfunc:`Py_BuildValue` will return *NULL* but won't
|
|
|
|
raise an exception. If no exception has been raised yet, :exc:`SystemError` is
|
|
|
|
set.
|
|
|
|
|
|
|
|
``S`` (object) [PyObject \*]
|
|
|
|
Same as ``O``.
|
|
|
|
|
|
|
|
``N`` (object) [PyObject \*]
|
|
|
|
Same as ``O``, except it doesn't increment the reference count on the object.
|
|
|
|
Useful when the object is created by a call to an object constructor in the
|
|
|
|
argument list.
|
|
|
|
|
|
|
|
``O&`` (object) [*converter*, *anything*]
|
|
|
|
Convert *anything* to a Python object through a *converter* function. The
|
|
|
|
function is called with *anything* (which should be compatible with :ctype:`void
|
|
|
|
\*`) as its argument and should return a "new" Python object, or *NULL* if an
|
|
|
|
error occurred.
|
|
|
|
|
|
|
|
``(items)`` (tuple) [*matching-items*]
|
|
|
|
Convert a sequence of C values to a Python tuple with the same number of items.
|
|
|
|
|
|
|
|
``[items]`` (list) [*matching-items*]
|
|
|
|
Convert a sequence of C values to a Python list with the same number of items.
|
|
|
|
|
|
|
|
``{items}`` (dictionary) [*matching-items*]
|
|
|
|
Convert a sequence of C values to a Python dictionary. Each pair of consecutive
|
|
|
|
C values adds one item to the dictionary, serving as key and value,
|
|
|
|
respectively.
|
|
|
|
|
|
|
|
If there is an error in the format string, the :exc:`SystemError` exception is
|
|
|
|
set and *NULL* returned.
|
Merged revisions 67952,67957-67958,67960-67961,67963,67973,67978,67995,68030,68057,68061 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r67952 | georg.brandl | 2008-12-27 11:42:40 -0600 (Sat, 27 Dec 2008) | 2 lines
#4752: actually use custom handler in example.
........
r67957 | georg.brandl | 2008-12-27 12:49:19 -0600 (Sat, 27 Dec 2008) | 2 lines
#4754: improve winsound documentation.
........
r67958 | georg.brandl | 2008-12-27 13:02:59 -0600 (Sat, 27 Dec 2008) | 2 lines
#4682: 'b' is actually unsigned char.
........
r67960 | georg.brandl | 2008-12-27 13:04:44 -0600 (Sat, 27 Dec 2008) | 2 lines
#4695: fix backslashery.
........
r67961 | georg.brandl | 2008-12-27 13:06:04 -0600 (Sat, 27 Dec 2008) | 2 lines
Use :samp: role.
........
r67963 | georg.brandl | 2008-12-27 13:11:15 -0600 (Sat, 27 Dec 2008) | 2 lines
#4671: document that pydoc imports modules.
........
r67973 | alexandre.vassalotti | 2008-12-27 20:58:22 -0600 (Sat, 27 Dec 2008) | 2 lines
Document Py_VaBuildValue.
........
r67978 | georg.brandl | 2008-12-28 05:58:49 -0600 (Sun, 28 Dec 2008) | 2 lines
#4731: clarify message about missing module prerequisites.
........
r67995 | benjamin.peterson | 2008-12-28 15:16:07 -0600 (Sun, 28 Dec 2008) | 1 line
#4763 PyErr_ExceptionMatches won't blow up with NULL arguments
........
r68030 | benjamin.peterson | 2008-12-29 15:38:14 -0600 (Mon, 29 Dec 2008) | 1 line
fix French
........
r68057 | vinay.sajip | 2008-12-30 01:01:25 -0600 (Tue, 30 Dec 2008) | 1 line
Minor documentation change relating to NullHandler.
........
r68061 | georg.brandl | 2008-12-30 04:15:49 -0600 (Tue, 30 Dec 2008) | 2 lines
#4778: attributes can't be called.
........
2008-12-31 20:23:30 -04:00
|
|
|
|
|
|
|
.. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
|
|
|
|
|
|
|
|
Identical to :cfunc:`Py_BuildValue`, except that it accepts a va_list
|
|
|
|
rather than a variable number of arguments.
|