.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: void _PyObject_Del(PyObject *op)
.. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
- Initialize a newly-allocated object *op* with its type and initial reference.
- Returns the initialized object. If *type* indicates that the object
- participates in the cyclic garbage detector, it is added to the detector's set
- of observed objects. Other fields of the object are not affected.
+ Initialize a newly-allocated object *op* with its type and initial
+ reference. Returns the initialized object. If *type* indicates that the
+ object participates in the cyclic garbage detector, it is added to the
+ detector's set of observed objects. Other fields of the object are not
+ affected.
.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
This does everything :cfunc:`PyObject_Init` does, and also initializes the
length information for a variable-size object.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
- Allocate a new Python object using the C structure type *TYPE* and the Python
- type object *type*. Fields not defined by the Python object header are not
- initialized; the object's reference count will be one. The size of the memory
- allocation is determined from the :attr:`tp_basicsize` field of the type object.
+ Allocate a new Python object using the C structure type *TYPE* and the
+ Python type object *type*. Fields not defined by the Python object header
+ are not initialized; the object's reference count will be one. The size of
+ the memory allocation is determined from the :attr:`tp_basicsize` field of
+ the type object.
.. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
- Allocate a new Python object using the C structure type *TYPE* and the Python
- type object *type*. Fields not defined by the Python object header are not
- initialized. The allocated memory allows for the *TYPE* structure plus *size*
- fields of the size given by the :attr:`tp_itemsize` field of *type*. This is
- useful for implementing objects like tuples, which are able to determine their
- size at construction time. Embedding the array of fields into the same
- allocation decreases the number of allocations, improving the memory management
- efficiency.
+ Allocate a new Python object using the C structure type *TYPE* and the
+ Python type object *type*. Fields not defined by the Python object header
+ are not initialized. The allocated memory allows for the *TYPE* structure
+ plus *size* fields of the size given by the :attr:`tp_itemsize` field of
+ *type*. This is useful for implementing objects like tuples, which are
+ able to determine their size at construction time. Embedding the array of
+ fields into the same allocation decreases the number of allocations,
+ improving the memory management efficiency.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
.. cfunction:: void PyObject_Del(PyObject *op)
Releases memory allocated to an object using :cfunc:`PyObject_New` or
- :cfunc:`PyObject_NewVar`. This is normally called from the :attr:`tp_dealloc`
- handler specified in the object's type. The fields of the object should not be
- accessed after this call as the memory is no longer a valid Python object.
+ :cfunc:`PyObject_NewVar`. This is normally called from the
+ :attr:`tp_dealloc` handler specified in the object's type. The fields of
+ the object should not be accessed after this call as the memory is no
+ longer a valid Python object.
.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)
- Create a new module object based on a name and table of functions, returning the
- new module object.
+ Create a new module object based on a name and table of functions,
+ returning the new module object.
.. versionchanged:: 2.3
- Older versions of Python did not support *NULL* as the value for the *methods*
- argument.
+ Older versions of Python did not support *NULL* as the value for the
+ *methods* argument.
.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)
- Create a new module object based on a name and table of functions, returning the
- new module object. If *doc* is non-*NULL*, it will be used to define the
- docstring for the module.
+ Create a new module object based on a name and table of functions,
+ returning the new module object. If *doc* is non-*NULL*, it will be used
+ to define the docstring for the module.
.. versionchanged:: 2.3
- Older versions of Python did not support *NULL* as the value for the *methods*
- argument.
+ Older versions of Python did not support *NULL* as the value for the
+ *methods* argument.
.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
- Create a new module object based on a name and table of functions, returning the
- new module object. If *doc* is non-*NULL*, it will be used to define the
- docstring for the module. If *self* is non-*NULL*, it will passed to the
- functions of the module as their (otherwise *NULL*) first parameter. (This was
- added as an experimental feature, and there are no known uses in the current
- version of Python.) For *apiver*, the only value which should be passed is
- defined by the constant :const:`PYTHON_API_VERSION`.
+ Create a new module object based on a name and table of functions,
+ returning the new module object. If *doc* is non-*NULL*, it will be used
+ to define the docstring for the module. If *self* is non-*NULL*, it will
+ passed to the functions of the module as their (otherwise *NULL*) first
+ parameter. (This was added as an experimental feature, and there are no
+ known uses in the current version of Python.) For *apiver*, the only value
+ which should be passed is defined by the constant
+ :const:`PYTHON_API_VERSION`.
.. note::
- Most uses of this function should probably be using the :cfunc:`Py_InitModule3`
- instead; only use this if you are sure you need it.
+ Most uses of this function should probably be using the
+ :cfunc:`Py_InitModule3` instead; only use this if you are sure you need
+ it.
.. versionchanged:: 2.3
- Older versions of Python did not support *NULL* as the value for the *methods*
- argument.
+ Older versions of Python did not support *NULL* as the value for the
+ *methods* argument.
.. cvar:: PyObject _Py_NoneStruct
- Object which is visible in Python as ``None``. This should only be accessed
- using the ``Py_None`` macro, which evaluates to a pointer to this object.
+ Object which is visible in Python as ``None``. This should only be
+ accessed using the ``Py_None`` macro, which evaluates to a pointer to this
+ object.
: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.
+: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.
+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.
+ 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.
``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :ctype:`Py_ssize_t`, see below)]
- 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 the raw internal
- data representation.
-
- 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.
+ 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 the raw internal data representation.
+
+ 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.
``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer \*]
- Similar to ``s#``, this code fills a Py_buffer structure provided by the caller.
- The buffer gets 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.
+ Similar to ``s#``, this code fills a Py_buffer structure provided by the
+ caller. The buffer gets 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.
.. versionadded:: 2.6
.. versionadded:: 2.6
``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.
+ 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.
+ 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.
``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 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.
+ 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.
+ 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.
+ 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 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.
+ :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.
``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
- 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.
+ 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.
``b`` (integer) [unsigned char]
Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
:ctype:`unsigned char`.
``B`` (integer) [unsigned char]
- Convert a Python integer to a tiny int without overflow checking, stored in a C
- :ctype:`unsigned char`.
+ Convert a Python integer to a tiny int without overflow checking, stored in
+ a C :ctype:`unsigned char`.
.. versionadded:: 2.3
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.
+ Convert a Python integer to a C :ctype:`unsigned short int`, without
+ overflow checking.
.. versionadded:: 2.3
Convert a Python integer to a C :ctype:`long int`.
``k`` (integer) [unsigned long]
- Convert a Python integer or long integer to a C :ctype:`unsigned long` without
- overflow checking.
+ Convert a Python integer or long integer to a C :ctype:`unsigned long`
+ without overflow checking.
.. versionadded:: 2.3
``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).
+ available on platforms that support :ctype:`long long` (or :ctype:`_int64`
+ on Windows).
``K`` (integer) [unsigned PY_LONG_LONG]
Convert a Python integer or long 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).
+ support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on
+ Windows).
.. versionadded:: 2.3
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*.
+ 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.
+ 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::
+ 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
- should raise an exception and leave the content of *address* unmodified.
+ :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 should raise an exception and leave the
+ content of *address* unmodified.
``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\*`.
+ :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\*`.
+ :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.
+ 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.
+ 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.
``w#`` (read-write character buffer) [char \*, Py_ssize_t]
Like ``s#``, but accepts any object which implements the read-write 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.
+ interface. The :ctype:`char \*` variable is set to point to the first byte
+ of the buffer, and the :ctype:`Py_ssize_t` 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 byte-oriented buffer) [Py_buffer \*]
This is to ``w`` what ``s*`` is to ``s``.
.. versionadded:: 2.6
``(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.
+ 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.
.. note::
- Prior to Python version 1.5.2, this format specifier only accepted a tuple
- containing the individual parameters, not an arbitrary sequence. Code which
- previously caused :exc:`TypeError` to be raised here may now proceed without an
- exception. This is not expected to be a problem for existing code.
+ Prior to Python version 1.5.2, this format specifier only accepted a
+ tuple containing the individual parameters, not an arbitrary sequence.
+ Code which previously caused :exc:`TypeError` to be raised here may now
+ proceed without an exception. This is not expected to be a problem for
+ existing code.
It is possible to pass Python long integers where integers are requested;
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).
+(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).
+ 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 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
- the error message *instead* of the default error message. ``:`` and ``;``
- mutually exclude each other.
+ The list of format units ends here; the string after the semicolon is used
+ as the error message *instead* of the default error message. ``:`` and
+ ``;`` mutually exclude each other.
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.
-
-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
+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.
+
+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.
.. 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.
+ 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.
+ 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[], ...)
.. 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.
+ 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::
+ 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)
return result;
}
- The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely equivalent to
- this call to :cfunc:`PyArg_ParseTuple`::
+ 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)
.. versionadded:: 2.2
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *min* and *max*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
.. 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
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
``z`` (string or ``None``) [char \*]
Same as ``s``.
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.
+ 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.
+ 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.
``i`` (integer) [int]
Convert a plain C :ctype:`int` to a Python integer object.
Convert a C :ctype:`unsigned short int` to a Python integer object.
``I`` (integer/long) [unsigned int]
- Convert a C :ctype:`unsigned int` to a Python integer object or a Python long
- integer object, if it is larger than ``sys.maxint``.
+ Convert a C :ctype:`unsigned int` to a Python integer object or a Python
+ long integer object, if it is larger than ``sys.maxint``.
``k`` (integer/long) [unsigned long]
- Convert a C :ctype:`unsigned long` to a Python integer object or a Python long
- integer object, if it is larger than ``sys.maxint``.
+ Convert a C :ctype:`unsigned long` to a Python integer object or a
+ Python long integer object, if it is larger than ``sys.maxint``.
``L`` (long) [PY_LONG_LONG]
- Convert a C :ctype:`long long` to a Python long integer object. Only available
- on platforms that support :ctype:`long long`.
+ Convert a C :ctype:`long long` to a Python long 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 long integer object. Only
- available on platforms that support :ctype:`unsigned long long`.
+ Convert a C :ctype:`unsigned long long` to a Python long 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 or long integer.
.. versionadded:: 2.5
``c`` (string of length 1) [char]
- Convert a C :ctype:`int` representing a character to a Python string of length
- 1.
+ Convert a C :ctype:`int` representing a character to a Python string of
+ length 1.
``d`` (float) [double]
Convert a C :ctype:`double` to a Python floating point 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ If there is an error in the format string, the :exc:`SystemError` exception
+ is set and *NULL* returned.
.. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
single: buffer interface
Python objects implemented in C can export a group of functions called the
-"buffer interface." These functions can be used by an object to expose its data
-in a raw, byte-oriented format. Clients of the object can use the buffer
-interface to access the object data directly, without needing to copy it first.
+"buffer interface." These functions can be used by an object to expose its
+data in a raw, byte-oriented format. Clients of the object can use the buffer
+interface to access the object data directly, without needing to copy it
+first.
Two examples of objects that support the buffer interface are strings and
arrays. The string object exposes the character contents in the buffer
:cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface,
returning data from the target object.
+Starting from version 1.6, Python has been providing Python-level buffer
+objects and a C-level buffer API so that any builtin or used-defined type can
+expose its characteristics. Both, however, have been deprecated because of
+various shortcomings, and have been officially removed in Python 3.0 in favour
+of a new C-level buffer API and a new Python-level object named
+:class:`memoryview`.
+
+The new buffer API has been backported to Python 2.6, and the
+:class:`memoryview` object has been backported to Python 2.7. It is strongly
+advised to use them rather than the old APIs, unless you are blocked from
+doing so for compatibility reasons.
+
+
+The new-style Py_buffer struct
+==============================
+
+
+.. ctype:: Py_buffer
+
+ .. cmember:: void *buf
+
+ A pointer to the start of the memory for the object.
+
+ .. cmember:: Py_ssize_t len
+ :noindex:
+
+ The total length of the memory in bytes.
+
+ .. cmember:: int readonly
+
+ An indicator of whether the buffer is read only.
+
+ .. cmember:: const char *format
+ :noindex:
+
+ A *NULL* terminated string in :mod:`struct` module style syntax giving
+ the contents of the elements available through the buffer. If this is
+ *NULL*, ``"B"`` (unsigned bytes) is assumed.
+
+ .. cmember:: int ndim
+
+ The number of dimensions the memory represents as a multi-dimensional
+ array. If it is 0, :cdata:`strides` and :cdata:`suboffsets` must be
+ *NULL*.
+
+ .. cmember:: Py_ssize_t *shape
+
+ An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the
+ shape of the memory as a multi-dimensional array. Note that
+ ``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to
+ :cdata:`len`.
+
+ .. cmember:: Py_ssize_t *strides
+
+ An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the
+ number of bytes to skip to get to a new element in each dimension.
+
+ .. cmember:: Py_ssize_t *suboffsets
+
+ An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim`. If these
+ suboffset numbers are greater than or equal to 0, then the value stored
+ along the indicated dimension is a pointer and the suboffset value
+ dictates how many bytes to add to the pointer after de-referencing. A
+ suboffset value that it negative indicates that no de-referencing should
+ occur (striding in a contiguous memory block).
+
+ Here is a function that returns a pointer to the element in an N-D array
+ pointed to by an N-dimesional index when there are both non-NULL strides
+ and suboffsets::
+
+ void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
+ Py_ssize_t *suboffsets, Py_ssize_t *indices) {
+ char *pointer = (char*)buf;
+ int i;
+ for (i = 0; i < ndim; i++) {
+ pointer += strides[i] * indices[i];
+ if (suboffsets[i] >=0 ) {
+ pointer = *((char**)pointer) + suboffsets[i];
+ }
+ }
+ return (void*)pointer;
+ }
+
+
+ .. cmember:: Py_ssize_t itemsize
+
+ This is a storage for the itemsize (in bytes) of each element of the
+ shared memory. It is technically un-necessary as it can be obtained
+ using :cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know
+ this information without parsing the format string and it is necessary
+ to know the itemsize for proper interpretation of striding. Therefore,
+ storing it is more convenient and faster.
+
+ .. cmember:: void *internal
+
+ This is for use internally by the exporting object. For example, this
+ might be re-cast as an integer by the exporter and used to store flags
+ about whether or not the shape, strides, and suboffsets arrays must be
+ freed when the buffer is released. The consumer should never alter this
+ value.
+
+
+Buffer related functions
+========================
+
+
+.. cfunction:: int PyObject_CheckBuffer(PyObject *obj)
+
+ Return 1 if *obj* supports the buffer interface otherwise 0.
+
+
+.. cfunction:: int PyObject_GetBuffer(PyObject *obj, PyObject *view, int flags)
+
+ Export *obj* into a :ctype:`Py_buffer`, *view*. These arguments must
+ never be *NULL*. The *flags* argument is a bit field indicating what
+ kind of buffer the caller is prepared to deal with and therefore what
+ kind of buffer the exporter is allowed to return. The buffer interface
+ allows for complicated memory sharing possibilities, but some caller may
+ not be able to handle all the complexibity but may want to see if the
+ exporter will let them take a simpler view to its memory.
+
+ Some exporters may not be able to share memory in every possible way and
+ may need to raise errors to signal to some consumers that something is
+ just not possible. These errors should be a :exc:`BufferError` unless
+ there is another error that is actually causing the problem. The
+ exporter can use flags information to simplify how much of the
+ :cdata:`Py_buffer` structure is filled in with non-default values and/or
+ raise an error if the object can't support a simpler view of its memory.
+
+ 0 is returned on success and -1 on error.
+
+ The following table gives possible values to the *flags* arguments.
+
+ +------------------------------+---------------------------------------------------+
+ | Flag | Description |
+ +==============================+===================================================+
+ | :cmacro:`PyBUF_SIMPLE` | This is the default flag state. The returned |
+ | | buffer may or may not have writable memory. The |
+ | | format of the data will be assumed to be unsigned |
+ | | bytes. This is a "stand-alone" flag constant. It |
+ | | never needs to be '|'d to the others. The exporter|
+ | | will raise an error if it cannot provide such a |
+ | | contiguous buffer of bytes. |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is |
+ | | not writable, then raise an error. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_STRIDES` | This implies :cmacro:`PyBUF_ND`. The returned |
+ | | buffer must provide strides information (i.e. the |
+ | | strides cannot be NULL). This would be used when |
+ | | the consumer can handle strided, discontiguous |
+ | | arrays. Handling strides automatically assumes |
+ | | you can handle shape. The exporter can raise an |
+ | | error if a strided representation of the data is |
+ | | not possible (i.e. without the suboffsets). |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_ND` | The returned buffer must provide shape |
+ | | information. The memory will be assumed C-style |
+ | | contiguous (last dimension varies the |
+ | | fastest). The exporter may raise an error if it |
+ | | cannot provide this kind of contiguous buffer. If |
+ | | this is not given then shape will be *NULL*. |
+ | | |
+ | | |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ |:cmacro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned |
+ |:cmacro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last |
+ |:cmacro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous |
+ | | (first dimension varies the fastest) or either |
+ | | one. All of these flags imply |
+ | | :cmacro:`PyBUF_STRIDES` and guarantee that the |
+ | | strides buffer info structure will be filled in |
+ | | correctly. |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_INDIRECT` | This flag indicates the returned buffer must have |
+ | | suboffsets information (which can be NULL if no |
+ | | suboffsets are needed). This can be used when |
+ | | the consumer can handle indirect array |
+ | | referencing implied by these suboffsets. This |
+ | | implies :cmacro:`PyBUF_STRIDES`. |
+ | | |
+ | | |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_FORMAT` | The returned buffer must have true format |
+ | | information if this flag is provided. This would |
+ | | be used when the consumer is going to be checking |
+ | | for what 'kind' of data is actually stored. An |
+ | | exporter should always be able to provide this |
+ | | information if requested. If format is not |
+ | | explicitly requested then the format must be |
+ | | returned as *NULL* (which means ``'B'``, or |
+ | | unsigned bytes) |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | |
+ | | PyBUF_WRITABLE)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | |
+ | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | |
+ | | PyBUF_FORMAT)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | |
+ | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | |
+ | | PyBUF_FORMAT)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | |
+ | | PyBUF_WRITABLE)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. |
+ | | |
+ +------------------------------+---------------------------------------------------+
+
+
+.. cfunction:: void PyBuffer_Release(PyObject *obj, Py_buffer *view)
+
+ Release the buffer *view* over *obj*. This shouldd be called when the buffer
+ is no longer being used as it may free memory from it.
+
+
+.. cfunction:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
+
+ Return the implied :cdata:`~Py_buffer.itemsize` from the struct-stype
+ :cdata:`~Py_buffer.format`.
+
+
+.. cfunction:: int PyObject_CopyToObject(PyObject *obj, void *buf, Py_ssize_t len, char fortran)
+
+ Copy *len* bytes of data pointed to by the contiguous chunk of memory
+ pointed to by *buf* into the buffer exported by obj. The buffer must of
+ course be writable. Return 0 on success and return -1 and raise an error
+ on failure. If the object does not have a writable buffer, then an error
+ is raised. If *fortran* is ``'F'``, then if the object is
+ multi-dimensional, then the data will be copied into the array in
+ Fortran-style (first dimension varies the fastest). If *fortran* is
+ ``'C'``, then the data will be copied into the array in C-style (last
+ dimension varies the fastest). If *fortran* is ``'A'``, then it does not
+ matter and the copy will be made in whatever way is more efficient.
+
+
+.. cfunction:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)
+
+ Return 1 if the memory defined by the *view* is C-style (*fortran* is
+ ``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one
+ (*fortran* is ``'A'``). Return 0 otherwise.
+
+
+.. cfunction:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char fortran)
+
+ Fill the *strides* array with byte-strides of a contiguous (C-style if
+ *fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'`` array of the
+ given shape with the given number of bytes per element.
+
+
+.. cfunction:: int PyBuffer_FillInfo(Py_buffer *view, void *buf, Py_ssize_t len, int readonly, int infoflags)
+
+ Fill in a buffer-info structure, *view*, correctly for an exporter that can
+ only share a contiguous chunk of memory of "unsigned bytes" of the given
+ length. Return 0 on success and -1 (with raising an error) on error.
+
+
+Old-style buffer objects
+========================
+
.. index:: single: PyBufferProcs
More information on the buffer interface is provided in the section
A "buffer object" is defined in the :file:`bufferobject.h` header (included by
:file:`Python.h`). These objects look very similar to string objects at the
Python programming level: they support slicing, indexing, concatenation, and
-some other standard string operations. However, their data can come from one of
-two sources: from a block of memory, or from another object which exports the
-buffer interface.
+some other standard string operations. However, their data can come from one
+of two sources: from a block of memory, or from another object which exports
+the buffer interface.
Buffer objects are useful as a way to expose the data from another object's
-buffer interface to the Python programmer. They can also be used as a zero-copy
-slicing mechanism. Using their ability to reference a block of memory, it is
-possible to expose any data to the Python programmer quite easily. The memory
-could be a large, constant array in a C extension, it could be a raw block of
-memory for manipulation before passing to an operating system library, or it
-could be used to pass around structured data in its native, in-memory format.
+buffer interface to the Python programmer. They can also be used as a
+zero-copy slicing mechanism. Using their ability to reference a block of
+memory, it is possible to expose any data to the Python programmer quite
+easily. The memory could be a large, constant array in a C extension, it could
+be a raw block of memory for manipulation before passing to an operating
+system library, or it could be used to pass around structured data in its
+native, in-memory format.
.. ctype:: PyBufferObject
This constant may be passed as the *size* parameter to
:cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It
- indicates that the new :ctype:`PyBufferObject` should refer to *base* object
- from the specified *offset* to the end of its exported buffer. Using this
- enables the caller to avoid querying the *base* object for its length.
+ indicates that the new :ctype:`PyBufferObject` should refer to *base*
+ object from the specified *offset* to the end of its exported buffer.
+ Using this enables the caller to avoid querying the *base* object for its
+ length.
.. cfunction:: int PyBuffer_Check(PyObject *p)
.. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
- Return a new read-only buffer object. This raises :exc:`TypeError` if *base*
- doesn't support the read-only buffer protocol or doesn't provide exactly one
- buffer segment, or it raises :exc:`ValueError` if *offset* is less than zero.
- The buffer will hold a reference to the *base* object, and the buffer's contents
- will refer to the *base* object's buffer interface, starting as position
- *offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`,
- then the new buffer's contents extend to the length of the *base* object's
- exported buffer data.
+ Return a new read-only buffer object. This raises :exc:`TypeError` if
+ *base* doesn't support the read-only buffer protocol or doesn't provide
+ exactly one buffer segment, or it raises :exc:`ValueError` if *offset* is
+ less than zero. The buffer will hold a reference to the *base* object, and
+ the buffer's contents will refer to the *base* object's buffer interface,
+ starting as position *offset* and extending for *size* bytes. If *size* is
+ :const:`Py_END_OF_BUFFER`, then the new buffer's contents extend to the
+ length of the *base* object's exported buffer data.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *offset* and *size*. This
+ might require changes in your code for properly supporting 64-bit
+ systems.
.. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
- Return a new writable buffer object. Parameters and exceptions are similar to
- those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not export
- the writeable buffer protocol, then :exc:`TypeError` is raised.
+ Return a new writable buffer object. Parameters and exceptions are similar
+ to those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not
+ export the writeable buffer protocol, then :exc:`TypeError` is raised.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *offset* and *size*. This
+ might require changes in your code for properly supporting 64-bit
+ systems.
.. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)
- Return a new read-only buffer object that reads from a specified location in
- memory, with a specified size. The caller is responsible for ensuring that the
- memory buffer, passed in as *ptr*, is not deallocated while the returned buffer
- object exists. Raises :exc:`ValueError` if *size* is less than zero. Note that
- :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter;
- :exc:`ValueError` will be raised in that case.
+ Return a new read-only buffer object that reads from a specified location
+ in memory, with a specified size. The caller is responsible for ensuring
+ that the memory buffer, passed in as *ptr*, is not deallocated while the
+ returned buffer object exists. Raises :exc:`ValueError` if *size* is less
+ than zero. Note that :const:`Py_END_OF_BUFFER` may *not* be passed for the
+ *size* parameter; :exc:`ValueError` will be raised in that case.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
- Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable.
+ Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is
+ writable.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)
Return a new writable buffer object that maintains its own memory buffer of
- *size* bytes. :exc:`ValueError` is returned if *size* is not zero or positive.
- Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is
- not specifically aligned.
+ *size* bytes. :exc:`ValueError` is returned if *size* is not zero or
+ positive. Note that the memory buffer (as returned by
+ :cfunc:`PyObject_AsWriteBuffer`) is not specifically aligned.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
single: DictType (in module types)
single: DictionaryType (in module types)
- This instance of :ctype:`PyTypeObject` represents the Python dictionary type.
- This is exposed to Python programs as ``dict`` and ``types.DictType``.
+ This instance of :ctype:`PyTypeObject` represents the Python dictionary
+ type. This is exposed to Python programs as ``dict`` and
+ ``types.DictType``.
.. cfunction:: int PyDict_Check(PyObject *p)
.. cfunction:: int PyDict_CheckExact(PyObject *p)
- Return true if *p* is a dict object, but not an instance of a subtype of the
- dict type.
+ Return true if *p* is a dict object, but not an instance of a subtype of
+ the dict type.
.. versionadded:: 2.4
.. cfunction:: PyObject* PyDictProxy_New(PyObject *dict)
- Return a proxy object for a mapping which enforces read-only behavior. This is
- normally used to create a proxy to prevent modification of the dictionary for
- non-dynamic class types.
+ Return a proxy object for a mapping which enforces read-only behavior.
+ This is normally used to create a proxy to prevent modification of the
+ dictionary for non-dynamic class types.
.. versionadded:: 2.2
.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)
- Determine if dictionary *p* contains *key*. If an item in *p* is matches *key*,
- return ``1``, otherwise return ``0``. On error, return ``-1``. This is
- equivalent to the Python expression ``key in p``.
+ Determine if dictionary *p* contains *key*. If an item in *p* is matches
+ *key*, return ``1``, otherwise return ``0``. On error, return ``-1``.
+ This is equivalent to the Python expression ``key in p``.
.. versionadded:: 2.4
.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
- :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return ``0``
- on success or ``-1`` on failure.
+ :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
+ ``0`` on success or ``-1`` on failure.
.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
.. index:: single: PyString_FromString()
- Insert *value* into the dictionary *p* using *key* as a key. *key* should be a
- :ctype:`char\*`. The key object is created using ``PyString_FromString(key)``.
- Return ``0`` on success or ``-1`` on failure.
+ Insert *value* into the dictionary *p* using *key* as a key. *key* should
+ be a :ctype:`char\*`. The key object is created using
+ ``PyString_FromString(key)``. Return ``0`` on success or ``-1`` on
+ failure.
.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key)
- Remove the entry in dictionary *p* with key *key*. *key* must be hashable; if it
- isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1`` on
- failure.
+ Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
+ if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``
+ on failure.
.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)
.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
- Return the object from dictionary *p* which has a key *key*. Return *NULL* if
- the key *key* is not present, but *without* setting an exception.
+ Return the object from dictionary *p* which has a key *key*. Return *NULL*
+ if the key *key* is not present, but *without* setting an exception.
.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
.. cfunction:: PyObject* PyDict_Items(PyObject *p)
- Return a :ctype:`PyListObject` containing all the items from the dictionary, as
- in the dictionary method :meth:`dict.items`.
+ Return a :ctype:`PyListObject` containing all the items from the
+ dictionary, as in the dictionary method :meth:`dict.items`.
.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
- Return a :ctype:`PyListObject` containing all the keys from the dictionary, as
- in the dictionary method :meth:`dict.keys`.
+ Return a :ctype:`PyListObject` containing all the keys from the dictionary,
+ as in the dictionary method :meth:`dict.keys`.
.. cfunction:: PyObject* PyDict_Values(PyObject *p)
- Return a :ctype:`PyListObject` containing all the values from the dictionary
- *p*, as in the dictionary method :meth:`dict.values`.
+ Return a :ctype:`PyListObject` containing all the values from the
+ dictionary *p*, as in the dictionary method :meth:`dict.values`.
.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p)
.. index:: builtin: len
- Return the number of items in the dictionary. This is equivalent to ``len(p)``
- on a dictionary.
+ Return the number of items in the dictionary. This is equivalent to
+ ``len(p)`` on a dictionary.
+
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int` type. This might require changes
+ in your code for properly supporting 64-bit systems.
.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
- Iterate over all key-value pairs in the dictionary *p*. The :ctype:`int`
- referred to by *ppos* must be initialized to ``0`` prior to the first call to
- this function to start the iteration; the function returns true for each pair in
- the dictionary, and false once all pairs have been reported. The parameters
- *pkey* and *pvalue* should either point to :ctype:`PyObject\*` variables that
- will be filled in with each key and value, respectively, or may be *NULL*. Any
- references returned through them are borrowed. *ppos* should not be altered
- during iteration. Its value represents offsets within the internal dictionary
- structure, and since the structure is sparse, the offsets are not consecutive.
+ Iterate over all key-value pairs in the dictionary *p*. The
+ :ctype:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``
+ prior to the first call to this function to start the iteration; the
+ function returns true for each pair in the dictionary, and false once all
+ pairs have been reported. The parameters *pkey* and *pvalue* should either
+ point to :ctype:`PyObject\*` variables that will be filled in with each key
+ and value, respectively, or may be *NULL*. Any references returned through
+ them are borrowed. *ppos* should not be altered during iteration. Its
+ value represents offsets within the internal dictionary structure, and
+ since the structure is sparse, the offsets are not consecutive.
For example::
...
}
- The dictionary *p* should not be mutated during iteration. It is safe (since
- Python 2.1) to modify the values of the keys as you iterate over the dictionary,
- but only so long as the set of keys does not change. For example::
+ The dictionary *p* should not be mutated during iteration. It is safe
+ (since Python 2.1) to modify the values of the keys as you iterate over the
+ dictionary, but only so long as the set of keys does not change. For
+ example::
PyObject *key, *value;
Py_ssize_t pos = 0;
Py_DECREF(o);
}
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int *` type for *ppos*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
- Iterate over mapping object *b* adding key-value pairs to dictionary *a*. *b*
- may be a dictionary, or any object supporting :func:`PyMapping_Keys` and
- :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* will be
- replaced if a matching key is found in *b*, otherwise pairs will only be added
- if there is not a matching key in *a*. Return ``0`` on success or ``-1`` if an
- exception was raised.
+ Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
+ *b* may be a dictionary, or any object supporting :func:`PyMapping_Keys`
+ and :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
+ will be replaced if a matching key is found in *b*, otherwise pairs will
+ only be added if there is not a matching key in *a*. Return ``0`` on
+ success or ``-1`` if an exception was raised.
.. versionadded:: 2.2
.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
- Update or merge into dictionary *a*, from the key-value pairs in *seq2*. *seq2*
- must be an iterable object producing iterable objects of length 2, viewed as
- key-value pairs. In case of duplicate keys, the last wins if *override* is
- true, else the first wins. Return ``0`` on success or ``-1`` if an exception was
- raised. Equivalent Python (except for the return value)::
+ Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
+ *seq2* must be an iterable object producing iterable objects of length 2,
+ viewed as key-value pairs. In case of duplicate keys, the last wins if
+ *override* is true, else the first wins. Return ``0`` on success or ``-1``
+ if an exception was raised. Equivalent Python (except for the return
+ value)::
def PyDict_MergeFromSeq2(a, seq2, override):
for key, value in seq2:
references requires support from object types which are "containers" for other
objects which may also be containers. Types which do not store references to
other objects, or which only store references to atomic types (such as numbers
-or strings), do not need to provide any explicit support for garbage collection.
+or strings), do not need to provide any explicit support for garbage
+collection.
.. An example showing the use of these interfaces can be found in "Supporting the
.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".
.. data:: Py_TPFLAGS_HAVE_GC
:noindex:
- Objects with a type with this flag set must conform with the rules documented
- here. For convenience these objects will be referred to as container objects.
+ Objects with a type with this flag set must conform with the rules
+ documented here. For convenience these objects will be referred to as
+ container objects.
Constructors for container types must conform to two rules:
-#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New` or
- :cfunc:`PyObject_GC_VarNew`.
+#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New`
+ or :cfunc:`PyObject_GC_VarNew`.
#. Once all the fields which may contain references to other containers are
initialized, it must call :cfunc:`PyObject_GC_Track`.
Analogous to :cfunc:`PyObject_NewVar` but for container objects with the
:const:`Py_TPFLAGS_HAVE_GC` flag set.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
-.. cfunction:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t)
- Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the resized
- object or *NULL* on failure.
+.. cfunction:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
+
+ Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the
+ resized object or *NULL* on failure.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *newsize*. This might
+ require changes in your code for properly supporting 64-bit systems.
.. cfunction:: void PyObject_GC_Track(PyObject *op)
- Adds the object *op* to the set of container objects tracked by the collector.
- The collector can run at unexpected times so objects must be valid while being
- tracked. This should be called once all the fields followed by the
- :attr:`tp_traverse` handler become valid, usually near the end of the
- constructor.
+ Adds the object *op* to the set of container objects tracked by the
+ collector. The collector can run at unexpected times so objects must be
+ valid while being tracked. This should be called once all the fields
+ followed by the :attr:`tp_traverse` handler become valid, usually near the
+ end of the constructor.
.. cfunction:: void _PyObject_GC_TRACK(PyObject *op)
.. cfunction:: void PyObject_GC_UnTrack(void *op)
Remove the object *op* from the set of container objects tracked by the
- collector. Note that :cfunc:`PyObject_GC_Track` can be called again on this
- object to add it back to the set of tracked objects. The deallocator
- (:attr:`tp_dealloc` handler) should call this for the object before any of the
- fields used by the :attr:`tp_traverse` handler become invalid.
+ collector. Note that :cfunc:`PyObject_GC_Track` can be called again on
+ this object to add it back to the set of tracked objects. The deallocator
+ (:attr:`tp_dealloc` handler) should call this for the object before any of
+ the fields used by the :attr:`tp_traverse` handler become invalid.
.. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op)
.. ctype:: int (*visitproc)(PyObject *object, void *arg)
- Type of the visitor function passed to the :attr:`tp_traverse` handler. The
- function should be called with an object to traverse as *object* and the third
- parameter to the :attr:`tp_traverse` handler as *arg*. The Python core uses
- several visitor functions to implement cyclic garbage detection; it's not
- expected that users will need to write their own visitor functions.
+ Type of the visitor function passed to the :attr:`tp_traverse` handler.
+ The function should be called with an object to traverse as *object* and
+ the third parameter to the :attr:`tp_traverse` handler as *arg*. The
+ Python core uses several visitor functions to implement cyclic garbage
+ detection; it's not expected that users will need to write their own
+ visitor functions.
The :attr:`tp_traverse` handler must have the following type:
Traversal function for a container object. Implementations must call the
*visit* function for each object directly contained by *self*, with the
- parameters to *visit* being the contained object and the *arg* value passed to
- the handler. The *visit* function must not be called with a *NULL* object
- argument. If *visit* returns a non-zero value that value should be returned
- immediately.
+ parameters to *visit* being the contained object and the *arg* value passed
+ to the handler. The *visit* function must not be called with a *NULL*
+ object argument. If *visit* returns a non-zero value that value should be
+ returned immediately.
To simplify writing :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is
provided. In order to use this macro, the :attr:`tp_traverse` implementation
.. cfunction:: void Py_VISIT(PyObject *o)
- Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns a
- non-zero value, then return it. Using this macro, :attr:`tp_traverse` handlers
- look like::
+ Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns
+ a non-zero value, then return it. Using this macro, :attr:`tp_traverse`
+ handlers look like::
static int
my_traverse(Noddy *self, visitproc visit, void *arg)
.. versionadded:: 2.4
-The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL* if
-the object is immutable.
+The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL*
+if the object is immutable.
.. ctype:: int (*inquiry)(PyObject *self)
- Drop references that may have created reference cycles. Immutable objects do
- not have to define this method since they can never directly create reference
- cycles. Note that the object must still be valid after calling this method
- (don't just call :cfunc:`Py_DECREF` on a reference). The collector will call
- this method if it detects that this object is involved in a reference cycle.
+ Drop references that may have created reference cycles. Immutable objects
+ do not have to define this method since they can never directly create
+ reference cycles. Note that the object must still be valid after calling
+ this method (don't just call :cfunc:`Py_DECREF` on a reference). The
+ collector will call this method if it detects that this object is involved
+ in a reference cycle.
global variable). Conversely, when acquiring the lock and restoring the thread
state, the lock must be acquired before storing the thread state pointer.
-Why am I going on with so much detail about this? Because when threads are
-created from C, they don't have the global interpreter lock, nor is there a
-thread state data structure for them. Such threads must bootstrap themselves
-into existence, by first creating a thread state data structure, then acquiring
-the lock, and finally storing their thread state pointer, before they can start
-using the Python/C API. When they are done, they should reset the thread state
-pointer, release the lock, and finally free their thread state data structure.
+It is important to note that when threads are created from C, they don't have
+the global interpreter lock, nor is there a thread state data structure for
+them. Such threads must bootstrap themselves into existence, by first
+creating a thread state data structure, then acquiring the lock, and finally
+storing their thread state pointer, before they can start using the Python/C
+API. When they are done, they should reset the thread state pointer, release
+the lock, and finally free their thread state data structure.
Beginning with version 2.3, threads can now take advantage of the
:cfunc:`PyGILState_\*` functions to do all of the above automatically. The
.. index:: single: ListType (in module types)
- This instance of :ctype:`PyTypeObject` represents the Python list type. This is
- the same object as ``list`` and ``types.ListType`` in the Python layer.
+ This instance of :ctype:`PyTypeObject` represents the Python list type.
+ This is the same object as ``list`` and ``types.ListType`` in the Python
+ layer.
.. cfunction:: int PyList_Check(PyObject *p)
.. cfunction:: int PyList_CheckExact(PyObject *p)
- Return true if *p* is a list object, but not an instance of a subtype of the
- list type.
+ Return true if *p* is a list object, but not an instance of a subtype of
+ the list type.
.. versionadded:: 2.2
.. note::
- If *length* is greater than zero, the returned list object's items are set to
- ``NULL``. Thus you cannot use abstract API functions such as
- :cfunc:`PySequence_SetItem` or expose the object to Python code before setting
- all items to a real object with :cfunc:`PyList_SetItem`.
+ If *length* is greater than zero, the returned list object's items are
+ set to ``NULL``. Thus you cannot use abstract API functions such as
+ :cfunc:`PySequence_SetItem` or expose the object to Python code before
+ setting all items to a real object with :cfunc:`PyList_SetItem`.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PyList_Size(PyObject *list)
Return the length of the list object in *list*; this is equivalent to
``len(list)`` on a list object.
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int`. This might require changes in
+ your code for properly supporting 64-bit systems.
+
.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
Macro form of :cfunc:`PyList_Size` without error checking.
+ .. versionchanged:: 2.5
+ This macro returned an :ctype:`int`. This might require changes in your
+ code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
- Return the object at position *pos* in the list pointed to by *p*. The position
- must be positive, indexing from the end of the list is not supported. If *pos*
- is out of bounds, return *NULL* and set an :exc:`IndexError` exception.
+ Return the object at position *pos* in the list pointed to by *p*. The
+ position must be positive, indexing from the end of the list is not
+ supported. If *pos* is out of bounds, return *NULL* and set an
+ :exc:`IndexError` exception.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` for *index*. This might require
+ changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
Macro form of :cfunc:`PyList_GetItem` without error checking.
+ .. versionchanged:: 2.5
+ This macro used an :ctype:`int` for *i*. This might require changes in
+ your code for properly supporting 64-bit systems.
+
.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
- Set the item at index *index* in list to *item*. Return ``0`` on success or
- ``-1`` on failure.
+ Set the item at index *index* in list to *item*. Return ``0`` on success
+ or ``-1`` on failure.
.. note::
- This function "steals" a reference to *item* and discards a reference to an item
- already in the list at the affected position.
+ This function "steals" a reference to *item* and discards a reference to
+ an item already in the list at the affected position.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` for *index*. This might require
+ changes in your code for properly supporting 64-bit systems.
.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
- Macro form of :cfunc:`PyList_SetItem` without error checking. This is normally
- only used to fill in new lists where there is no previous content.
+ Macro form of :cfunc:`PyList_SetItem` without error checking. This is
+ normally only used to fill in new lists where there is no previous content.
.. note::
- This function "steals" a reference to *item*, and, unlike
- :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it
- being replaced; any reference in *list* at position *i* will be leaked.
+ This macro "steals" a reference to *item*, and, unlike
+ :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that
+ it being replaced; any reference in *list* at position *i* will be
+ leaked.
+
+ .. versionchanged:: 2.5
+ This macro used an :ctype:`int` for *i*. This might require
+ changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
- Insert the item *item* into list *list* in front of index *index*. Return ``0``
- if successful; return ``-1`` and set an exception if unsuccessful. Analogous to
- ``list.insert(index, item)``.
+ Insert the item *item* into list *list* in front of index *index*. Return
+ ``0`` if successful; return ``-1`` and set an exception if unsuccessful.
+ Analogous to ``list.insert(index, item)``.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` for *index*. This might require
+ changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyList_Append(PyObject *list, PyObject *item)
- Append the object *item* at the end of list *list*. Return ``0`` if successful;
- return ``-1`` and set an exception if unsuccessful. Analogous to
- ``list.append(item)``.
+ Append the object *item* at the end of list *list*. Return ``0`` if
+ successful; return ``-1`` and set an exception if unsuccessful. Analogous
+ to ``list.append(item)``.
.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
- Return a list of the objects in *list* containing the objects *between* *low*
- and *high*. Return *NULL* and set an exception if unsuccessful. Analogous to
- ``list[low:high]``.
+ Return a list of the objects in *list* containing the objects *between*
+ *low* and *high*. Return *NULL* and set an exception if unsuccessful.
+ Analogous to ``list[low:high]``.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` for *low* and *high*. This might
+ require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
- Set the slice of *list* between *low* and *high* to the contents of *itemlist*.
- Analogous to ``list[low:high] = itemlist``. The *itemlist* may be *NULL*,
- indicating the assignment of an empty list (slice deletion). Return ``0`` on
- success, ``-1`` on failure.
+ Set the slice of *list* between *low* and *high* to the contents of
+ *itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may
+ be *NULL*, indicating the assignment of an empty list (slice deletion).
+ Return ``0`` on success, ``-1`` on failure.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` for *low* and *high*. This might
+ require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyList_Sort(PyObject *list)
- Sort the items of *list* in place. Return ``0`` on success, ``-1`` on failure.
- This is equivalent to ``list.sort()``.
+ Sort the items of *list* in place. Return ``0`` on success, ``-1`` on
+ failure. This is equivalent to ``list.sort()``.
.. cfunction:: int PyList_Reverse(PyObject *list)
.. versionadded:: 1.6
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` for *length*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
function always succeeds.
-.. cfunction:: Py_ssize_t PyMapping_Length(PyObject *o)
+.. cfunction:: Py_ssize_t PyMapping_Size(PyObject *o)
+ Py_ssize_t PyMapping_Length(PyObject *o)
.. index:: builtin: len
objects that do not provide mapping protocol, this is equivalent to the Python
expression ``len(o)``.
+ .. versionchanged:: 2.5
+ These functions returned an :ctype:`int` type. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PyMapping_DelItemString(PyObject *o, char *key)
Data marshalling support
========================
-These routines allow C code to work with serialized objects using the same data
-format as the :mod:`marshal` module. There are functions to write data into the
-serialization format, and additional functions that can be used to read the data
-back. Files used to store marshalled data must be opened in binary mode.
+These routines allow C code to work with serialized objects using the same
+data format as the :mod:`marshal` module. There are functions to write data
+into the serialization format, and additional functions that can be used to
+read the data back. Files used to store marshalled data must be opened in
+binary mode.
Numeric values are stored with the least significant byte first.
-The module supports two versions of the data format: version 0 is the historical
-version, version 1 (new in Python 2.4) shares interned strings in the file, and
-upon unmarshalling. Version 2 (new in Python 2.5) uses a binary format for
-floating point numbers.
-*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
+The module supports two versions of the data format: version 0 is the
+historical version, version 1 (new in Python 2.4) shares interned strings in
+the file, and upon unmarshalling. Version 2 (new in Python 2.5) uses a binary
+format for floating point numbers. *Py_MARSHAL_VERSION* indicates the current
+file format (currently 2).
.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
- Marshal a :ctype:`long` integer, *value*, to *file*. This will only write the
- least-significant 32 bits of *value*; regardless of the size of the native
- :ctype:`long` type.
+ Marshal a :ctype:`long` integer, *value*, to *file*. This will only write
+ the least-significant 32 bits of *value*; regardless of the size of the
+ native :ctype:`long` type.
.. versionchanged:: 2.4
*version* indicates the file format.
The following functions allow marshalled values to be read back in.
XXX What about error detection? It appears that reading past the end of the
-file will always result in a negative numeric value (where that's relevant), but
-it's not clear that negative values won't be handled properly when there's no
-error. What's the right way to tell? Should only non-negative values be written
-using these routines?
+file will always result in a negative numeric value (where that's relevant),
+but it's not clear that negative values won't be handled properly when there's
+no error. What's the right way to tell? Should only non-negative values be
+written using these routines?
.. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)
- Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for
- reading. Only a 32-bit value can be read in using this function, regardless of
- the native size of :ctype:`long`.
+ Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened
+ for reading. Only a 32-bit value can be read in using this function,
+ regardless of the native size of :ctype:`long`.
.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
- Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for
- reading. Only a 16-bit value can be read in using this function, regardless of
- the native size of :ctype:`short`.
+ Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened
+ for reading. Only a 16-bit value can be read in using this function,
+ regardless of the native size of :ctype:`short`.
.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
Return a Python object from the data stream in a :ctype:`FILE\*` opened for
- reading. Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function assumes
- that no further objects will be read from the file, allowing it to aggressively
- load file data into memory so that the de-serialization can operate from data in
- memory rather than reading a byte at a time from the file. Only use these
- variant if you are certain that you won't be reading anything else from the
- file. On error, sets the appropriate exception (:exc:`EOFError` or
- :exc:`TypeError`) and returns *NULL*.
+ reading. Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function
+ assumes that no further objects will be read from the file, allowing it to
+ aggressively load file data into memory so that the de-serialization can
+ operate from data in memory rather than reading a byte at a time from the
+ file. Only use these variant if you are certain that you won't be reading
+ anything else from the file. On error, sets the appropriate exception
+ (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
.. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
- Return a Python object from the data stream in a character buffer containing
- *len* bytes pointed to by *string*. On error, sets the appropriate exception
- (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
+ Return a Python object from the data stream in a character buffer
+ containing *len* bytes pointed to by *string*. On error, sets the
+ appropriate exception (:exc:`EOFError` or :exc:`TypeError`) and returns
+ *NULL*.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *len*. This might require
+ changes in your code for properly supporting 64-bit systems.
.. _abstract-buffer:
-Buffer Protocol
-===============
+Old Buffer Protocol
+===================
+
+
+This section describes the legacy buffer protocol, which has been introduced
+in Python 1.6. It is still supported but deprecated in the Python 2.x series.
+Python 3.0 introduces a new buffer protocol which fixes weaknesses and
+shortcomings of the protocol, and has been backported to Python 2.6. See
+:ref:`bufferobjects` for more information.
.. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a read-only memory location usable as character-based
input. The *obj* argument must support the single-segment character buffer
- interface. On success, returns ``0``, sets *buffer* to the memory location and
- *buffer_len* to the buffer length. Returns ``-1`` and sets a :exc:`TypeError`
- on error.
+ interface. On success, returns ``0``, sets *buffer* to the memory location
+ and *buffer_len* to the buffer length. Returns ``-1`` and sets a
+ :exc:`TypeError` on error.
.. versionadded:: 1.6
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int *` type for *buffer_len*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
- Returns a pointer to a read-only memory location containing arbitrary data. The
- *obj* argument must support the single-segment readable buffer interface. On
- success, returns ``0``, sets *buffer* to the memory location and *buffer_len* to
- the buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.
+ Returns a pointer to a read-only memory location containing arbitrary data.
+ The *obj* argument must support the single-segment readable buffer
+ interface. On success, returns ``0``, sets *buffer* to the memory location
+ and *buffer_len* to the buffer length. Returns ``-1`` and sets a
+ :exc:`TypeError` on error.
.. versionadded:: 1.6
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int *` type for *buffer_len*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a writeable memory location. The *obj* argument must
- support the single-segment, character buffer interface. On success, returns
- ``0``, sets *buffer* to the memory location and *buffer_len* to the buffer
- length. Returns ``-1`` and sets a :exc:`TypeError` on error.
+ support the single-segment, character buffer interface. On success,
+ returns ``0``, sets *buffer* to the memory location and *buffer_len* to the
+ buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.
.. versionadded:: 1.6
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int *` type for *buffer_len*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
and mapping protocols, the sequence length is returned. On error, ``-1`` is
returned. This is the equivalent to the Python expression ``len(o)``.
+ .. versionchanged:: 2.5
+ These functions returned an :ctype:`int` type. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
.. cfunction:: Py_ssize_t PySequence_Size(PyObject *o)
+ Py_ssize_t PySequence_Length(PyObject *o)
.. index:: builtin: len
For objects that do not provide sequence protocol, this is equivalent to the
Python expression ``len(o)``.
-
-.. cfunction:: Py_ssize_t PySequence_Length(PyObject *o)
-
- Alternate name for :cfunc:`PySequence_Size`.
+ .. versionchanged:: 2.5
+ These functions returned an :ctype:`int` type. This might require
+ changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
Return the result of repeating sequence object *o* *count* times, or *NULL* on
failure. This is the equivalent of the Python expression ``o * count``.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *count*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
failure. The operation is done *in-place* when *o* supports it. This is the
equivalent of the Python expression ``o *= count``.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *count*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
Return the *i*th element of *o*, or *NULL* on failure. This is the equivalent of
the Python expression ``o[i]``.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *i*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
failure. This is the equivalent of the Python expression ``o[i1:i2]``.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *i1* and *i2*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
is the equivalent of the Python statement ``o[i] = v``. This function *does
not* steal a reference to *v*.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *i*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
Delete the *i*th element of object *o*. Returns ``-1`` on failure. This is the
equivalent of the Python statement ``del o[i]``.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *i*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
*i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *i1* and *i2*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` on
failure. This is the equivalent of the Python statement ``del o[i1:i2]``.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *i1* and *i2*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
of keys for which ``o[key] == value``. On failure, return ``-1``. This is
equivalent to the Python expression ``o.count(value)``.
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int` type. This might require changes
+ in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PySequence_Contains(PyObject *o, PyObject *value)
Return the first index *i* for which ``o[i] == value``. On error, return
``-1``. This is equivalent to the Python expression ``o.index(value)``.
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int` type. This might require changes
+ in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PySequence_List(PyObject *o)
Return the *i*th element of *o*, assuming that *o* was returned by
:cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *i*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
.. versionadded:: 2.3
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *i*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a
:class:`set`, :class:`frozenset`, or an instance of a subtype.
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int`. This might require changes in
+ your code for properly supporting 64-bit systems.
+
.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
.. cfunction:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
Return a new slice object with the given values. The *start*, *stop*, and
- *step* parameters are used as the values of the slice object attributes of the
- same names. Any of the values may be *NULL*, in which case the ``None`` will be
- used for the corresponding attribute. Return *NULL* if the new object could not
- be allocated.
+ *step* parameters are used as the values of the slice object attributes of
+ the same names. Any of the values may be *NULL*, in which case the
+ ``None`` will be used for the corresponding attribute. Return *NULL* if
+ the new object could not be allocated.
.. cfunction:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
Retrieve the start, stop and step indices from the slice object *slice*,
- assuming a sequence of length *length*. Treats indices greater than *length* as
- errors.
+ assuming a sequence of length *length*. Treats indices greater than
+ *length* as errors.
- Returns 0 on success and -1 on error with no exception set (unless one of the
- indices was not :const:`None` and failed to be converted to an integer, in which
- case -1 is returned with an exception set).
+ Returns 0 on success and -1 on error with no exception set (unless one of
+ the indices was not :const:`None` and failed to be converted to an integer,
+ in which case -1 is returned with an exception set).
- You probably do not want to use this function. If you want to use slice objects
- in versions of Python prior to 2.3, you would probably do well to incorporate
- the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed, in the source of
- your extension.
+ You probably do not want to use this function. If you want to use slice
+ objects in versions of Python prior to 2.3, you would probably do well to
+ incorporate the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed,
+ in the source of your extension.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *length* and an
+ :ctype:`int *` type for *start*, *stop*, and *step*. This might require
+ changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
- Usable replacement for :cfunc:`PySlice_GetIndices`. Retrieve the start, stop,
- and step indices from the slice object *slice* assuming a sequence of length
- *length*, and store the length of the slice in *slicelength*. Out of bounds
- indices are clipped in a manner consistent with the handling of normal slices.
+ Usable replacement for :cfunc:`PySlice_GetIndices`. Retrieve the start,
+ stop, and step indices from the slice object *slice* assuming a sequence of
+ length *length*, and store the length of the slice in *slicelength*. Out
+ of bounds indices are clipped in a manner consistent with the handling of
+ normal slices.
Returns 0 on success and -1 on error with exception set.
.. versionadded:: 2.3
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *length* and an
+ :ctype:`int *` type for *start*, *stop*, *step*, and *slicelength*. This
+ might require changes in your code for properly supporting 64-bit
+ systems.
*len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of the
string are uninitialized.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *len*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyString_FromFormat(const char *format, ...)
Return the length of the string in string object *string*.
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int` type. This might require changes
+ in your code for properly supporting 64-bit systems.
+
.. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
Macro form of :cfunc:`PyString_Size` but without error checking.
+ .. versionchanged:: 2.5
+ This macro returned an :ctype:`int` type. This might require changes in
+ your code for properly supporting 64-bit systems.
+
.. cfunction:: char* PyString_AsString(PyObject *string)
*string* and operates on that. If *string* is not a string object at all,
:cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int *` type for *length*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart)
fails, the original string object at *\*string* is deallocated, *\*string* is
set to *NULL*, a memory exception is set, and ``-1`` is returned.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *newsize*. This might
+ require changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args)
The codec to be used is looked up using the Python codec registry. Return
*NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
:meth:`encode` method. The codec to be used is looked up using the Python codec
registry. Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
object types for Python. This section describes these structures and how they
are used.
-All Python objects ultimately share a small number of fields at the beginning of
-the object's representation in memory. These are represented by the
-:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn, by
-the expansions of some macros also used, whether directly or indirectly, in the
-definition of all other Python objects.
+All Python objects ultimately share a small number of fields at the beginning
+of the object's representation in memory. These are represented by the
+:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn,
+by the expansions of some macros also used, whether directly or indirectly, in
+the definition of all other Python objects.
.. ctype:: PyObject
- All object types are extensions of this type. This is a type which contains the
- information Python needs to treat a pointer to an object as an object. In a
- normal "release" build, it contains only the object's reference count and a
- pointer to the corresponding type object. It corresponds to the fields defined
- by the expansion of the ``PyObject_HEAD`` macro.
+ All object types are extensions of this type. This is a type which
+ contains the information Python needs to treat a pointer to an object as an
+ object. In a normal "release" build, it contains only the object's
+ reference count and a pointer to the corresponding type object. It
+ corresponds to the fields defined by the expansion of the ``PyObject_HEAD``
+ macro.
.. ctype:: PyVarObject
- This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size` field.
- This is only used for objects that have some notion of *length*. This type does
- not often appear in the Python/C API. It corresponds to the fields defined by
- the expansion of the ``PyObject_VAR_HEAD`` macro.
+ This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size`
+ field. This is only used for objects that have some notion of *length*.
+ This type does not often appear in the Python/C API. It corresponds to the
+ fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro.
These macros are used in the definition of :ctype:`PyObject` and
:ctype:`PyVarObject`:
This is a macro which expands to the declarations of the fields of the
:ctype:`PyObject` type; it is used when declaring new types which represent
- objects without a varying length. The specific fields it expands to depend on
- the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is not
- defined, and :cmacro:`PyObject_HEAD` expands to::
+ objects without a varying length. The specific fields it expands to depend
+ on the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is
+ not defined, and :cmacro:`PyObject_HEAD` expands to::
Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;
.. cmacro:: PyObject_VAR_HEAD
This is a macro which expands to the declarations of the fields of the
- :ctype:`PyVarObject` type; it is used when declaring new types which represent
- objects with a length that varies from instance to instance. This macro always
- expands to::
+ :ctype:`PyVarObject` type; it is used when declaring new types which
+ represent objects with a length that varies from instance to instance.
+ This macro always expands to::
PyObject_HEAD
Py_ssize_t ob_size;
Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own
expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`.
-PyObject_HEAD_INIT
+
+.. cmacro:: PyObject_HEAD_INIT(type)
+
+ This is a macro which expands to initialization values for a new
+ :ctype:`PyObject` type. This macro expands to::
+
+ _PyObject_EXTRA_INIT
+ 1, type,
+
+
+.. cmacro:: PyVarObject_HEAD_INIT(type, size)
+
+ This is a macro which expands to initialization values for a new
+ :ctype:`PyVarObject` type, including the :attr:`ob_size` field.
+ This macro expands to::
+
+ _PyObject_EXTRA_INIT
+ 1, type, size,
.. ctype:: PyCFunction
- Type of the functions used to implement most Python callables in C. Functions of
- this type take two :ctype:`PyObject\*` parameters and return one such value. If
- the return value is *NULL*, an exception shall have been set. If not *NULL*,
- the return value is interpreted as the return value of the function as exposed
- in Python. The function must return a new reference.
+ Type of the functions used to implement most Python callables in C.
+ Functions of this type take two :ctype:`PyObject\*` parameters and return
+ one such value. If the return value is *NULL*, an exception shall have
+ been set. If not *NULL*, the return value is interpreted as the return
+ value of the function as exposed in Python. The function must return a new
+ reference.
.. ctype:: PyMethodDef
.. data:: METH_VARARGS
This is the typical calling convention, where the methods have the type
- :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values. The
- first one is the *self* object for methods; for module functions, it has the
- value given to :cfunc:`Py_InitModule4` (or *NULL* if :cfunc:`Py_InitModule` was
- used). The second parameter (often called *args*) is a tuple object
- representing all arguments. This parameter is typically processed using
- :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`.
+ :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values.
+ The first one is the *self* object for methods; for module functions, it
+ has the value given to :cfunc:`Py_InitModule4` (or *NULL* if
+ :cfunc:`Py_InitModule` was used). The second parameter (often called
+ *args*) is a tuple object representing all arguments. This parameter is
+ typically processed using :cfunc:`PyArg_ParseTuple` or
+ :cfunc:`PyArg_UnpackTuple`.
.. data:: METH_KEYWORDS
- Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`. The
- function expects three parameters: *self*, *args*, and a dictionary of all the
- keyword arguments. The flag is typically combined with :const:`METH_VARARGS`,
- and the parameters are typically processed using
+ Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`.
+ The function expects three parameters: *self*, *args*, and a dictionary of
+ all the keyword arguments. The flag is typically combined with
+ :const:`METH_VARARGS`, and the parameters are typically processed using
:cfunc:`PyArg_ParseTupleAndKeywords`.
Methods without parameters don't need to check whether arguments are given if
they are listed with the :const:`METH_NOARGS` flag. They need to be of type
:ctype:`PyCFunction`. When used with object methods, the first parameter is
- typically named ``self`` and will hold a reference to the object instance. In
- all cases the second parameter will be *NULL*.
+ typically named ``self`` and will hold a reference to the object instance.
+ In all cases the second parameter will be *NULL*.
.. data:: METH_O
.. data:: METH_OLDARGS
This calling convention is deprecated. The method must be of type
- :ctype:`PyCFunction`. The second argument is *NULL* if no arguments are given,
- a single object if exactly one argument is given, and a tuple of objects if more
- than one argument is given. There is no way for a function using this
- convention to distinguish between a call with multiple arguments and a call with
- a tuple as the only argument.
+ :ctype:`PyCFunction`. The second argument is *NULL* if no arguments are
+ given, a single object if exactly one argument is given, and a tuple of
+ objects if more than one argument is given. There is no way for a function
+ using this convention to distinguish between a call with multiple arguments
+ and a call with a tuple as the only argument.
These two constants are not used to indicate the calling convention but the
binding when use with methods of classes. These may not be used for functions
.. index:: builtin: classmethod
- The method will be passed the type object as the first parameter rather than an
- instance of the type. This is used to create *class methods*, similar to what
- is created when using the :func:`classmethod` built-in function.
+ The method will be passed the type object as the first parameter rather
+ than an instance of the type. This is used to create *class methods*,
+ similar to what is created when using the :func:`classmethod` built-in
+ function.
.. versionadded:: 2.3
.. index:: builtin: staticmethod
- The method will be passed *NULL* as the first parameter rather than an instance
- of the type. This is used to create *static methods*, similar to what is
- created when using the :func:`staticmethod` built-in function.
+ The method will be passed *NULL* as the first parameter rather than an
+ instance of the type. This is used to create *static methods*, similar to
+ what is created when using the :func:`staticmethod` built-in function.
.. versionadded:: 2.3
The method will be loaded in place of existing definitions. Without
*METH_COEXIST*, the default is to skip repeated definitions. Since slot
- wrappers are loaded before the method table, the existence of a *sq_contains*
- slot, for example, would generate a wrapped method named :meth:`__contains__`
- and preclude the loading of a corresponding PyCFunction with the same name.
- With the flag defined, the PyCFunction will be loaded in place of the wrapper
- object and will co-exist with the slot. This is helpful because calls to
- PyCFunctions are optimized more than wrapper object calls.
+ wrappers are loaded before the method table, the existence of a
+ *sq_contains* slot, for example, would generate a wrapped method named
+ :meth:`__contains__` and preclude the loading of a corresponding
+ PyCFunction with the same name. With the flag defined, the PyCFunction
+ will be loaded in place of the wrapper object and will co-exist with the
+ slot. This is helpful because calls to PyCFunctions are optimized more
+ than wrapper object calls.
.. versionadded:: 2.4
.. cfunction:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)
- Return a bound method object for an extension type implemented in C. This can
- be useful in the implementation of a :attr:`tp_getattro` or :attr:`tp_getattr`
- handler that does not use the :cfunc:`PyObject_GenericGetAttr` function.
+ Return a bound method object for an extension type implemented in C. This
+ can be useful in the implementation of a :attr:`tp_getattro` or
+ :attr:`tp_getattr` handler that does not use the
+ :cfunc:`PyObject_GenericGetAttr` function.
Return a new tuple object of size *len*, or *NULL* on failure.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *len*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
.. versionadded:: 2.4
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *n*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: Py_ssize_t PyTuple_Size(PyObject *p)
Take a pointer to a tuple object, and return the size of that tuple.
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int` type. This might require changes
+ in your code for properly supporting 64-bit systems.
+
.. cfunction:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
no error checking is performed.
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int` type. This might require changes
+ in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *pos*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *pos*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
as a new tuple.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *low* and *high*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
This function "steals" a reference to *o*.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *pos*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
This function "steals" a reference to *o*.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *pos*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
.. versionchanged:: 2.2
Removed unused third parameter, *last_is_sticky*.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *newsize*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PyTuple_ClearFreeList(void)
.. versionadded:: 2.2
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *nitems*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
This field is not inherited by subtypes.
+ .. versionchanged:: 2.5
+ This field used to be an :ctype:`int` type. This might require changes
+ in your code for properly supporting 64-bit systems.
+
.. cmember:: PyTypeObject* PyObject.ob_type
Return the size of the object. *o* has to be a :ctype:`PyUnicodeObject` (not
checked).
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int` type. This might require changes
+ in your code for properly supporting 64-bit systems.
+
.. cfunction:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
Return the size of the object's internal buffer in bytes. *o* has to be a
:ctype:`PyUnicodeObject` (not checked).
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int` type. This might require changes
+ in your code for properly supporting 64-bit systems.
+
.. cfunction:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
Therefore, modification of the resulting Unicode object is only allowed when *u*
is *NULL*.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
Return the length of the Unicode object.
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int` type. This might require changes
+ in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
Create a Unicode object from the :ctype:`wchar_t` buffer *w* of the given size.
Return *NULL* on failure.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)
to make sure that the :ctype:`wchar_t` string is 0-terminated in case this is
required by the application.
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int` type and used an :ctype:`int`
+ type for *size*. This might require changes in your code for properly
+ supporting 64-bit systems.
+
.. _builtincodecs:
using the Python codec registry. Return *NULL* if an exception was raised by
the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)
looked up using the Python codec registry. Return *NULL* if an exception was
raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string
*s*. Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
.. versionadded:: 2.4
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-8 and return a
Python string object. Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
.. versionadded:: 2.4
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size* and an :ctype:`int *`
+ type for *consumed*. This might require changes in your code for
+ properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded
string *s*. Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
return a Python string object. Return *NULL* if an exception was raised by the
codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape
encoded string *s*. Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
and return a Python string object. Return *NULL* if an exception was raised by
the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string
*s*. Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :ctype:`Py_UNICODE` buffer of the given size using Latin-1 and return
a Python string object. Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
Create a Unicode object by decoding *size* bytes of the ASCII encoded string
*s*. Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :ctype:`Py_UNICODE` buffer of the given size using ASCII and return a
Python string object. Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
.. versionchanged:: 2.4
Allowed unicode string as mapping argument.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
*mapping* object and return a Python string object. Return *NULL* if an
exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
These are the MBCS codec APIs. They are currently only available on Windows and
use the Win32 MBCS converters to implement the conversions. Note that MBCS (or
DBCS) is a class of encodings, not just one. The target encoding is defined by
Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*.
Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)
Encode the :ctype:`Py_UNICODE` buffer of the given size using MBCS and return a
Python string object. Return *NULL* if an exception was raised by the codec.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
separator. At most *maxsplit* splits will be done. If negative, no limit is
set. Separators are not included in the resulting list.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *maxsplit*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
(*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match),
0 otherwise. Return ``-1`` if an error occurred.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *start* and *end*. This
+ might require changes in your code for properly supporting 64-bit
+ systems.
+
.. cfunction:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
``-1`` indicates that no match was found, and ``-2`` indicates that an error
occurred and an exception has been set.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *start* and *end*. This
+ might require changes in your code for properly supporting 64-bit
+ systems.
+
.. cfunction:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
Return the number of non-overlapping occurrences of *substr* in
``str[start:end]``. Return ``-1`` if an error occurred.
+ .. versionchanged:: 2.5
+ This function returned an :ctype:`int` type and used an :ctype:`int`
+ type for *start* and *end*. This might require changes in your code for
+ properly supporting 64-bit systems.
+
.. cfunction:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
return the resulting Unicode object. *maxcount* == -1 means replace all
occurrences.
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *maxcount*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
.. cfunction:: int PyUnicode_Compare(PyObject *left, PyObject *right)
# sendmail function takes 3 arguments: sender's address, recipient's address
# and message to send - here it is sent as one string.
s.sendmail(me, you, msg.as_string())
-s.close()
+s.quit()
fp.close()
else:
s = smtplib.SMTP()
- s.connect()
s.sendmail(opts.sender, opts.recipients, composed)
- s.close()
+ s.quit()
if __name__ == '__main__':
# Send the email via our own SMTP server.
s = smtplib.SMTP()
-s.connect()
s.sendmail(me, family, msg.as_string())
-s.close()
+s.quit()
# Send the message via our own SMTP server, but don't include the
# envelope header.
s = smtplib.SMTP()
-s.connect()
s.sendmail(me, [you], msg.as_string())
-s.close()
+s.quit()
projects / python / commitdiff