object is written instead of the \function{repr()}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name}
+\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, const char *attr_name}
Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
\code{0} otherwise. This is equivalent to the Python expression
\samp{hasattr(\var{o}, \var{attr_name})}. This function always
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o,
- char *attr_name}
+ const char *attr_name}
Retrieve an attribute named \var{attr_name} from object \var{o}.
Returns the attribute value on success, or \NULL{} on failure.
This is the equivalent of the Python expression
\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o,
- char *attr_name, PyObject *v}
+ const char *attr_name, PyObject *v}
Set the value of the attribute named \var{attr_name}, for object
\var{o}, to the value \var{v}. Returns \code{-1} on failure. This
is the equivalent of the Python statement
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name}
+\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, const char *attr_name}
Delete attribute named \var{attr_name}, for object \var{o}. Returns
\code{-1} on failure. This is the equivalent of the Python
statement: \samp{del \var{o}.\var{attr_name}}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
+\begin{cfuncdesc}{long}{PyObject_Hash}{PyObject *o}
Compute and return the hash value of an object \var{o}. On failure,
return \code{-1}. This is the equivalent of the Python expression
\samp{hash(\var{o})}.\bifuncindex{hash}
\versionadded{2.2}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
-\cfuncline{int}{PyObject_Size}{PyObject *o}
+\begin{cfuncdesc}{Py_ssize_t}{PyObject_Length}{PyObject *o}
+\cfuncline{Py_ssize_t}{PyObject_Size}{PyObject *o}
Return the length of object \var{o}. If the object \var{o} provides
either the sequence and mapping protocols, the sequence length is
returned. On error, \code{-1} is returned. This is the equivalent
\code{0} otherwise. This function always succeeds.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PySequence_Size}{PyObject *o}
+\begin{cfuncdesc}{Py_ssize_t}{PySequence_Size}{PyObject *o}
Returns the number of objects in sequence \var{o} on success, and
\code{-1} on failure. For objects that do not provide sequence
protocol, this is equivalent to the Python expression
\samp{len(\var{o})}.\bifuncindex{len}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o}
+\begin{cfuncdesc}{Py_ssize_t}{PySequence_Length}{PyObject *o}
Alternate name for \cfunction{PySequence_Size()}.
\end{cfuncdesc}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count}
+\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, Py_ssize_t count}
Return the result of repeating sequence object \var{o} \var{count}
times, or \NULL{} on failure. This is the equivalent of the Python
expression \samp{\var{o} * \var{count}}.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, int count}
+\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, Py_ssize_t count}
Return the result of repeating sequence object \var{o} \var{count}
times, or \NULL{} on failure. The operation is done \emph{in-place}
when \var{o} supports it. This is the equivalent of the Python
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i}
+\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, Py_ssize_t i}
Return the \var{i}th element of \var{o}, or \NULL{} on failure.
This is the equivalent of the Python expression
\samp{\var{o}[\var{i}]}.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2}
+\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, Py_ssize_t i1, Py_ssize_t i2}
Return the slice of sequence object \var{o} between \var{i1} and
\var{i2}, or \NULL{} on failure. This is the equivalent of the
Python expression \samp{\var{o}[\var{i1}:\var{i2}]}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v}
+\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, Py_ssize_t i, PyObject *v}
Assign object \var{v} to the \var{i}th element of \var{o}. Returns
\code{-1} on failure. This is the equivalent of the Python
statement \samp{\var{o}[\var{i}] = \var{v}}. This function \emph{does not}
steal a reference to \var{v}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
+\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, Py_ssize_t i}
Delete the \var{i}th element of object \var{o}. Returns \code{-1}
on failure. This is the equivalent of the Python statement
\samp{del \var{o}[\var{i}]}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1,
- int i2, PyObject *v}
+\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, Py_ssize_t i1,
+ Py_ssize_t i2, PyObject *v}
Assign the sequence object \var{v} to the slice in sequence object
\var{o} from \var{i1} to \var{i2}. This is the equivalent of the
Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
+\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, Py_ssize_t i1, Py_ssize_t i2}
Delete the slice in sequence object \var{o} from \var{i1} to
\var{i2}. Returns \code{-1} on failure. This is the equivalent of
the Python statement \samp{del \var{o}[\var{i1}:\var{i2}]}.
text.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i}
+\begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, Py_ssize_t i}
Return the \var{i}th element of \var{o}, assuming that \var{o} was
returned by \cfunction{PySequence_Fast()}, \var{o} is not \NULL,
and that \var{i} is within bounds.
\versionadded{2.4}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PySequence_ITEM}{PyObject *o, int i}
+\begin{cfuncdesc}{PyObject*}{PySequence_ITEM}{PyObject *o, Py_ssize_t i}
Return the \var{i}th element of \var{o} or \NULL{} on failure.
Macro form of \cfunction{PySequence_GetItem()} but without checking
that \cfunction{PySequence_Check(\var{o})} is true and without
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
+\begin{cfuncdesc}{Py_ssize_t}{PyMapping_Length}{PyObject *o}
Returns the number of keys in object \var{o} on success, and
\code{-1} on failure. For objects that do not provide mapping
protocol, this is equivalent to the Python expression
\begin{cfuncdesc}{int}{PyObject_AsCharBuffer}{PyObject *obj,
const char **buffer,
- int *buffer_len}
+ Py_ssize_t *buffer_len}
Returns a pointer to a read-only memory location useable as character-
based input. The \var{obj} argument must support the single-segment
character buffer interface. On success, returns \code{0}, sets
\begin{cfuncdesc}{int}{PyObject_AsReadBuffer}{PyObject *obj,
const void **buffer,
- int *buffer_len}
+ Py_ssize_t *buffer_len}
Returns a pointer to a read-only memory location containing
arbitrary data. The \var{obj} argument must support the
single-segment readable buffer interface. On success, returns
\begin{cfuncdesc}{int}{PyObject_AsWriteBuffer}{PyObject *obj,
void **buffer,
- int *buffer_len}
+ Py_ssize_t *buffer_len}
Returns a pointer to a writeable memory location. The \var{obj}
argument must support the single-segment, character buffer
interface. On success, returns \code{0}, sets \var{buffer} to the
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type,
- int nitems}
+ Py_ssize_t nitems}
\versionadded{2.2}
\end{cfuncdesc}
\versionadded{2.3}
\end{cfuncdesc}
-\begin{cfuncdesc}{unsigned long long}{PyInt_AsUnsignedLongLongMask}{PyObject *io}
+\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyInt_AsUnsignedLongLongMask}{PyObject *io}
Will first attempt to cast the object to a \ctype{PyIntObject} or
\ctype{PyLongObject}, if it is not already one, and then return its
value as unsigned long long, without checking for overflow.
long}, or \NULL{} on failure.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{long long v}
+\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{PY_LONG_LONG v}
Return a new \ctype{PyLongObject} object from a C \ctype{long long},
or \NULL{} on failure.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned long long v}
+\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned PY_LONG_LONG v}
Return a new \ctype{PyLongObject} object from a C \ctype{unsigned
long long}, or \NULL{} on failure.
\end{cfuncdesc}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u,
- int length, int base}
+ Py_ssize_t length, int base}
Convert a sequence of Unicode digits to a Python long integer
value. The first parameter, \var{u}, points to the first character
of the Unicode string, \var{length} gives the number of characters,
\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
\end{cfuncdesc}
-\begin{cfuncdesc}{long long}{PyLong_AsLongLong}{PyObject *pylong}
+\begin{cfuncdesc}{PY_LONG_LONG}{PyLong_AsLongLong}{PyObject *pylong}
Return a C \ctype{long long} from a Python long integer. If
\var{pylong} cannot be represented as a \ctype{long long}, an
\exception{OverflowError} will be raised.
\versionadded{2.2}
\end{cfuncdesc}
-\begin{cfuncdesc}{unsigned long long}{PyLong_AsUnsignedLongLong}{PyObject
+\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyLong_AsUnsignedLongLong}{PyObject
*pylong}
Return a C \ctype{unsigned long long} from a Python long integer.
If \var{pylong} cannot be represented as an \ctype{unsigned long
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
- int len}
+ Py_ssize_t len}
Return a new string object with the value \var{v} and length
\var{len} on success, and \NULL{} on failure. If \var{v} is
\NULL{}, the contents of the string are uninitialized.
\lineiii{\%c}{int}{A single character, represented as an C int.}
\lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
\lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
+ \lineiii{\%zd}{long}{Exactly equivalent to \code{printf("\%zd")}.}
\lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
\lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
\lineiii{\%s}{char*}{A null-terminated C character array.}
exactly two arguments.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
+\begin{cfuncdesc}{Py_ssize_t}{PyString_Size}{PyObject *string}
Return the length of the string in string object \var{string}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
+\begin{cfuncdesc}{Py_ssize_t}{PyString_GET_SIZE}{PyObject *string}
Macro form of \cfunction{PyString_Size()} but without error
checking.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
char **buffer,
- int *length}
+ Py_ssize_t *length}
Return a NUL-terminated representation of the contents of the
object \var{obj} through the output variables \var{buffer} and
\var{length}.
the reference count of \var{newpart}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
+\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, Py_ssize_t newsize}
A way to resize a string object even though it is ``immutable''.
Only use this to build up a brand new string object; don't use this
if the string may already be known in other parts of the code. It
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s,
- int size,
+ Py_ssize_t size,
const char *encoding,
const char *errors}
Create an object by decoding \var{size} bytes of the encoded
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s,
- int size,
+ Py_ssize_t size,
const char *encoding,
const char *errors}
Encode the \ctype{char} buffer of the given size by passing it to
\versionadded{2.2}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_SIZE}{PyObject *o}
Return the size of the object. \var{o} has to be a
\ctype{PyUnicodeObject} (not checked).
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
Return the size of the object's internal buffer in bytes. \var{o}
has to be a \ctype{PyUnicodeObject} (not checked).
\end{cfuncdesc}
use these APIs:
\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u,
- int size}
+ Py_ssize_t size}
Create a Unicode Object from the Py_UNICODE buffer \var{u} of the
given size. \var{u} may be \NULL{} which causes the contents to be
undefined. It is the user's responsibility to fill in the needed
object.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GetSize}{PyObject *unicode}
Return the length of the Unicode object.
\end{cfuncdesc}
\ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}.
\begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w,
- int size}
+ Py_ssize_t size}
Create a Unicode object from the \ctype{wchar_t} buffer \var{w} of
the given size. Return \NULL{} on failure.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
wchar_t *w,
- int size}
+ Py_ssize_t size}
Copy the Unicode object contents into the \ctype{wchar_t} buffer
\var{w}. At most \var{size} \ctype{wchar_t} characters are copied
(excluding a possibly trailing 0-termination character). Return
These are the generic codec APIs:
\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
- int size,
+ Py_ssize_t size,
const char *encoding,
const char *errors}
Create a Unicode object by decoding \var{size} bytes of the encoded
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s,
- int size,
+ Py_ssize_t size,
const char *encoding,
const char *errors}
Encode the \ctype{Py_UNICODE} buffer of the given size and return
These are the UTF-8 codec APIs:
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
- int size,
+ Py_ssize_t size,
const char *errors}
Create a Unicode object by decoding \var{size} bytes of the UTF-8
encoded string \var{s}. Return \NULL{} if an exception was raised
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8Stateful}{const char *s,
- int size,
+ Py_ssize_t size,
const char *errors,
- int *consumed}
+ Py_ssize_t *consumed}
If \var{consumed} is \NULL{}, behave like \cfunction{PyUnicode_DecodeUTF8()}.
If \var{consumed} is not \NULL{}, trailing incomplete UTF-8 byte sequences
will not be treated as an error. Those bytes will not be decoded and the
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s,
- int size,
+ 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
These are the UTF-16 codec APIs:
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
- int size,
+ Py_ssize_t size,
const char *errors,
int *byteorder}
Decode \var{length} bytes from a UTF-16 encoded buffer string and
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16Stateful}{const char *s,
- int size,
+ Py_ssize_t size,
const char *errors,
int *byteorder,
- int *consumed}
+ Py_ssize_t *consumed}
If \var{consumed} is \NULL{}, behave like
\cfunction{PyUnicode_DecodeUTF16()}. If \var{consumed} is not \NULL{},
\cfunction{PyUnicode_DecodeUTF16Stateful()} will not treat trailing incomplete
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s,
- int size,
+ Py_ssize_t size,
const char *errors,
int byteorder}
Return a Python string object holding the UTF-16 encoded value of
These are the ``Unicode Escape'' codec APIs:
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
- int size,
+ Py_ssize_t size,
const char *errors}
Create a Unicode object by decoding \var{size} bytes of the
Unicode-Escape encoded string \var{s}. Return \NULL{} if an
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s,
- int size,
- const char *errors}
+ Py_ssize_t size}
Encode the \ctype{Py_UNICODE} buffer of the given size using
Unicode-Escape and return a Python string object. Return \NULL{}
if an exception was raised by the codec.
These are the ``Raw Unicode Escape'' codec APIs:
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
- int size,
+ Py_ssize_t size,
const char *errors}
Create a Unicode object by decoding \var{size} bytes of the
Raw-Unicode-Escape encoded string \var{s}. Return \NULL{} if an
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s,
- int size,
+ Py_ssize_t size,
const char *errors}
Encode the \ctype{Py_UNICODE} buffer of the given size using
Raw-Unicode-Escape and return a Python string object. Return
are accepted by the codecs during encoding.
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
- int size,
+ Py_ssize_t size,
const char *errors}
Create a Unicode object by decoding \var{size} bytes of the Latin-1
encoded string \var{s}. Return \NULL{} if an exception was raised
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
- int size,
+ 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
accepted. All other codes generate errors.
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
- int size,
+ Py_ssize_t size,
const char *errors}
Create a Unicode object by decoding \var{size} bytes of the
\ASCII{} encoded string \var{s}. Return \NULL{} if an exception
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
- int size,
+ 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
points.
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
- int size,
+ Py_ssize_t size,
PyObject *mapping,
const char *errors}
Create a Unicode object by decoding \var{size} bytes of the encoded
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s,
- int size,
+ Py_ssize_t size,
PyObject *mapping,
const char *errors}
Encode the \ctype{Py_UNICODE} buffer of the given size using the
The following codec API is special in that maps Unicode to Unicode.
\begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s,
- int size,
+ Py_ssize_t size,
PyObject *table,
const char *errors}
Translate a \ctype{Py_UNICODE} buffer of the given length by
machine running the codec.
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
- int size,
+ Py_ssize_t size,
const char *errors}
Create a Unicode object by decoding \var{size} bytes of the MBCS
encoded string \var{s}. Return \NULL{} if an exception was
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
- int size,
+ Py_ssize_t size,
const char *errors}
Encode the \ctype{Py_UNICODE} buffer of the given size using MBCS
and return a Python string object. Return \NULL{} if an exception
\begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
PyObject *sep,
- int maxsplit}
+ Py_ssize_t maxsplit}
Split a string giving a list of Unicode strings. If sep is \NULL{},
splitting will be done at all whitespace substrings. Otherwise,
splits occur at the given separator. At most \var{maxsplit} splits
\begin{cfuncdesc}{int}{PyUnicode_Tailmatch}{PyObject *str,
PyObject *substr,
- int start,
- int end,
+ Py_ssize_t start,
+ Py_ssize_t end,
int direction}
Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at
the given tail end (\var{direction} == -1 means to do a prefix
Return \code{-1} if an error occurred.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyUnicode_Find}{PyObject *str,
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Find}{PyObject *str,
PyObject *substr,
- int start,
- int end,
+ Py_ssize_t start,
+ Py_ssize_t end,
int direction}
Return the first position of \var{substr} in
\var{str}[\var{start}:\var{end}] using the given \var{direction}
an exception has been set.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyUnicode_Count}{PyObject *str,
+\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Count}{PyObject *str,
PyObject *substr,
- int start,
- int end}
+ Py_ssize_t start,
+ Py_ssize_t end}
Return the number of non-overlapping occurrences of \var{substr} in
\code{\var{str}[\var{start}:\var{end}]}. Return \code{-1} if an
error occurred.
\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
PyObject *substr,
PyObject *replstr,
- int maxcount}
+ Py_ssize_t maxcount}
Replace at most \var{maxcount} occurrences of \var{substr} in
\var{str} with \var{replstr} and return the resulting Unicode object.
\var{maxcount} == -1 means replace all occurrences.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base,
- int offset, int size}
+ Py_ssize_t offset, Py_ssize_t size}
Return a new read-only buffer object. This raises
\exception{TypeError} if \var{base} doesn't support the read-only
buffer protocol or doesn't provide exactly one buffer segment, or it
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base,
- int offset,
- int size}
+ Py_ssize_t offset,
+ Py_ssize_t size}
Return a new writable buffer object. Parameters and exceptions are
similar to those for \cfunction{PyBuffer_FromObject()}. If the
\var{base} object does not export the writeable buffer protocol,
then \exception{TypeError} is raised.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, int size}
+\begin{cfuncdesc}{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
raised in that case.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, int size}
+\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, Py_ssize_t size}
Similar to \cfunction{PyBuffer_FromMemory()}, but the returned
buffer is writable.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{int size}
+\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{Py_ssize_t size}
Return a new writable buffer object that maintains its own memory
buffer of \var{size} bytes. \exception{ValueError} is returned if
\var{size} is not zero or positive. Note that the memory buffer (as
\versionadded{2.2}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len}
+\begin{cfuncdesc}{PyObject*}{PyTuple_New}{Py_ssize_t len}
Return a new tuple object of size \var{len}, or \NULL{} on failure.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyTuple_Pack}{int n, \moreargs}
+\begin{cfuncdesc}{PyObject*}{PyTuple_Pack}{Py_ssize_t n, \moreargs}
Return a new tuple object of size \var{n}, or \NULL{} on failure.
The tuple values are initialized to the subsequent \var{n} C arguments
pointing to Python objects. \samp{PyTuple_Pack(2, \var{a}, \var{b})}
point to a tuple; no error checking is performed.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, int pos}
+\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, Py_ssize_t pos}
Return the object at position \var{pos} in the tuple pointed to by
\var{p}. If \var{pos} is out of bounds, return \NULL{} and sets an
\exception{IndexError} exception.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, int pos}
+\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, Py_ssize_t pos}
Like \cfunction{PyTuple_GetItem()}, but does no checking of its
arguments.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p,
- int low, int high}
+ Py_ssize_t low, Py_ssize_t high}
Take a slice of the tuple pointed to by \var{p} from \var{low} to
\var{high} and return it as a new tuple.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p,
- int pos, PyObject *o}
+ Py_ssize_t pos, PyObject *o}
Insert a reference to object \var{o} at position \var{pos} of the
tuple pointed to by \var{p}. Return \code{0} on success.
\note{This function ``steals'' a reference to \var{o}.}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p,
- int pos, PyObject *o}
+ Py_ssize_t pos, PyObject *o}
Like \cfunction{PyTuple_SetItem()}, but does no error checking, and
should \emph{only} be used to fill in brand new tuples. \note{This
function ``steals'' a reference to \var{o}.}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, int newsize}
+\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, Py_ssize_t newsize}
Can be used to resize a tuple. \var{newsize} will be the new length
of the tuple. Because tuples are \emph{supposed} to be immutable,
this should only be used if there is only one reference to the
\versionadded{2.2}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyList_New}{int len}
+\begin{cfuncdesc}{PyObject*}{PyList_New}{Py_ssize_t len}
Return a new list of length \var{len} on success, or \NULL{} on
failure.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list}
+\begin{cfuncdesc}{Py_ssize_t}{PyList_Size}{PyObject *list}
Return the length of the list object in \var{list}; this is
equivalent to \samp{len(\var{list})} on a list object.
\bifuncindex{len}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
+\begin{cfuncdesc}{Py_ssize_t}{PyList_GET_SIZE}{PyObject *list}
Macro form of \cfunction{PyList_Size()} without error checking.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index}
+\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, Py_ssize_t index}
Return the object at position \var{pos} in the list pointed to by
\var{p}. If \var{pos} is out of bounds, return \NULL{} and set an
\exception{IndexError} exception.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i}
+\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, Py_ssize_t i}
Macro form of \cfunction{PyList_GetItem()} without error checking.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
+\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, Py_ssize_t index,
PyObject *item}
Set the item at index \var{index} in list to \var{item}. Return
\code{0} on success or \code{-1} on failure. \note{This function
item already in the list at the affected position.}
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, int i,
+\begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, Py_ssize_t i,
PyObject *o}
Macro form of \cfunction{PyList_SetItem()} without error checking.
This is normally only used to fill in new lists where there is no
\var{list} at position \var{i} will be leaked.}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,
+\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, Py_ssize_t index,
PyObject *item}
Insert the item \var{item} into list \var{list} in front of index
\var{index}. Return \code{0} if successful; return \code{-1} and
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
- int low, int high}
+ Py_ssize_t low, Py_ssize_t high}
Return a list of the objects in \var{list} containing the objects
\emph{between} \var{low} and \var{high}. Return \NULL{} and set
an exception if unsuccessful.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
- int low, int high,
+ Py_ssize_t low, Py_ssize_t high,
PyObject *itemlist}
Set the slice of \var{list} between \var{low} and \var{high} to the
contents of \var{itemlist}. Analogous to
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
- char *key,
+ const char *key,
PyObject *val}
Insert \var{value} into the dictionary \var{p} using \var{key} as a
key. \var{key} should be a \ctype{char*}. The key object is created
\emph{without} setting an exception.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, char *key}
+\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, const char *key}
This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is
specified as a \ctype{char*}, rather than a \ctype{PyObject*}.
\end{cfuncdesc}
(see the \citetitle[../lib/lib.html]{Python Library Reference}).
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyDict_Size}{PyObject *p}
+\begin{cfuncdesc}{Py_ssize_t}{PyDict_Size}{PyObject *p}
Return the number of items in the dictionary. This is equivalent
to \samp{len(\var{p})} on a dictionary.\bifuncindex{len}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, int *ppos,
+\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, Py_ssize_t *ppos,
PyObject **pkey, PyObject **pvalue}
Iterate over all key-value pairs in the dictionary \var{p}. The
\ctype{int} referred to by \var{ppos} must be initialized to
when the file should be closed. Return \NULL{} on failure.
\end{cfuncdesc}
-\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyFileObject *p}
+\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyObject *p}
Return the file object associated with \var{p} as a \ctype{FILE*}.
\end{cfuncdesc}
function, but doing so should not be needed.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
+\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyObject *p,
int flags}
Write object \var{obj} to file object \var{p}. The only supported
flag for \var{flags} is
failure; the appropriate exception will be set.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyFile_WriteString}{const char *s, PyFileObject *p}
+\begin{cfuncdesc}{int}{PyFile_WriteString}{const char *s, PyObject *p}
Write string \var{s} to file object \var{p}. Return \code{0} on
success or \code{-1} on failure; the appropriate exception will be
set.
\cdata{PyMethod_Type}). The parameter must not be \NULL{}.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func.
+\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func,
PyObject *self, PyObject *class}
Return a new method object, with \var{func} being any callable
object; this is the function that will be called when the method is
\versionadded{2.2}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PyModule_New}{char *name}
+\begin{cfuncdesc}{PyObject*}{PyModule_New}{const char *name}
Return a new module object with the \member{__name__} attribute set
to \var{name}. Only the module's \member{__doc__} and
\member{__name__} attributes are filled in; the caller is
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module,
- char *name, PyObject *value}
+ const char *name, PyObject *value}
Add an object to \var{module} as \var{name}. This is a convenience
function which can be used from the module's initialization
function. This steals a reference to \var{value}. Return
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module,
- char *name, long value}
+ const char *name, long value}
Add an integer constant to \var{module} as \var{name}. This
convenience function can be used from the module's initialization
function. Return \code{-1} on error, \code{0} on success.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module,
- char *name, char *value}
+ const char *name, const char *value}
Add a string constant to \var{module} as \var{name}. This
convenience function can be used from the module's initialization
function. The string \var{value} must be null-terminated. Return
\end{cvardesc}
\begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type,
- PyGetSetDef *getset}
+ struct PyGetSetDef *getset}
\versionadded{2.2}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type,
- PyMemberDef *meth}
+ struct PyMemberDef *meth}
\versionadded{2.2}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type,
- PyMethodDef *meth}
+ struct PyMethodDef *meth}
\versionadded{2.2}
\end{cfuncdesc}
not be allocated.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, int length,
- int *start, int *stop, int *step}
+\begin{cfuncdesc}{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
\var{slice}, assuming a sequence of length \var{length}. Treats
indices greater than \var{length} as errors.
suitably renamed, in the source of your extension.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PySlice_GetIndicesEx}{PySliceObject *slice, int length,
- int *start, int *stop, int *step,
- int *slicelength}
+\begin{cfuncdesc}{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 \cfunction{PySlice_GetIndices}. Retrieve the
start, stop, and step indices from the slice object \var{slice}
assuming a sequence of length \var{length}, and store the length of
\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, int size}
+\begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, Py_ssize_t size}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op}
\end{cfuncdesc}
\begin{cfuncdesc}{PyVarObject*}{PyObject_InitVar}{PyVarObject *op,
- PyTypeObject *type, int size}
+ PyTypeObject *type, Py_ssize_t size}
This does everything \cfunction{PyObject_Init()} does, and also
initializes the length information for a variable-size object.
\end{cfuncdesc}
\end{cfuncdesc}
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NewVar}{TYPE, PyTypeObject *type,
- int size}
+ Py_ssize_t size}
Allocate a new Python object using the C structure type \var{TYPE}
and the Python type object \var{type}. Fields not defined by the
Python object header are not initialized. The allocated memory
\end{cfuncdesc}
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW_VAR}{TYPE, PyTypeObject *type,
- int size}
+ Py_ssize_t size}
Macro version of \cfunction{PyObject_NewVar()}, to gain performance
at the expense of safety. This does not check \var{type} for a
\NULL{} value.
\csimplemacro{Py_TRACE_REFS}. By default, that macro is not
defined, and \csimplemacro{PyObject_HEAD} expands to:
\begin{verbatim}
- int ob_refcnt;
+ Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;
\end{verbatim}
When \csimplemacro{Py_TRACE_REFS} is defined, it expands to:
\begin{verbatim}
PyObject *_ob_next, *_ob_prev;
- int ob_refcnt;
+ Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;
\end{verbatim}
\end{csimplemacrodesc}
These fields are not inherited by subtypes.
\end{cmemberdesc}
-\begin{cmemberdesc}{PyObject}{int}{ob_refcnt}
+\begin{cmemberdesc}{PyObject}{Py_ssize_t}{ob_refcnt}
This is the type object's reference count, initialized to \code{1}
by the \code{PyObject_HEAD_INIT} macro. Note that for statically
allocated type objects, the type's instances (objects whose
and in 2.3 and beyond, it is inherited by subtypes.
\end{cmemberdesc}
-\begin{cmemberdesc}{PyVarObject}{int}{ob_size}
+\begin{cmemberdesc}{PyVarObject}{Py_ssize_t}{ob_size}
For statically allocated type objects, this should be initialized
to zero. For dynamically allocated type objects, this field has a
special internal meaning.
This field is not inherited by subtypes.
\end{cmemberdesc}
-\begin{cmemberdesc}{PyTypeObject}{int}{tp_basicsize}
-\cmemberline{PyTypeObject}{int}{tp_itemsize}
+\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_basicsize}
+\cmemberline{PyTypeObject}{Py_ssize_t}{tp_itemsize}
These fields allow calculating the size in bytes of instances of
the type.
The function signature is
\begin{verbatim}
-PyObject *tp_alloc(PyTypeObject *self, int nitems)
+PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)
\end{verbatim}
The purpose of this function is to separate memory allocation from
They are documented here for completeness. None of these fields are
inherited by subtypes.
-\begin{cmemberdesc}{PyTypeObject}{int}{tp_allocs}
+\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_allocs}
Number of allocations.
\end{cmemberdesc}
-\begin{cmemberdesc}{PyTypeObject}{int}{tp_frees}
+\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_frees}
Number of frees.
\end{cmemberdesc}
-\begin{cmemberdesc}{PyTypeObject}{int}{tp_maxalloc}
+\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_maxalloc}
Maximum simultaneously allocated objects.
\end{cmemberdesc}
\member{bf_getcharbuffer} slot is non-\NULL.
\end{datadesc}
-\begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc)
- (PyObject *self, int segment, void **ptrptr)}
+\begin{ctypedesc}[getreadbufferproc]{Py_ssize_t (*readbufferproc)
+ (PyObject *self, Py_ssize_t segment, void **ptrptr)}
Return a pointer to a readable segment of the buffer. This function
is allowed to raise an exception, in which case it must return
\code{-1}. The \var{segment} which is passed must be zero or
pointer to that memory.
\end{ctypedesc}
-\begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc)
- (PyObject *self, int segment, void **ptrptr)}
+\begin{ctypedesc}[getwritebufferproc]{Py_ssize_t (*writebufferproc)
+ (PyObject *self, Py_ssize_t segment, void **ptrptr)}
Return a pointer to a writable memory buffer in
\code{*\var{ptrptr}}, and the length of that segment as the function
return value. The memory buffer must correspond to buffer segment
% code.
\end{ctypedesc}
-\begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
- (PyObject *self, int *lenp)}
+\begin{ctypedesc}[getsegcountproc]{Py_ssize_t (*segcountproc)
+ (PyObject *self, Py_ssize_t *lenp)}
Return the number of memory segments which comprise the buffer. If
\var{lenp} is not \NULL, the implementation must report the sum of
the sizes (in bytes) of all segments in \code{*\var{lenp}}.
The function cannot fail.
\end{ctypedesc}
-\begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
- (PyObject *self, int segment, const char **ptrptr)}
+\begin{ctypedesc}[getcharbufferproc]{Py_ssize_t (*charbufferproc)
+ (PyObject *self, Py_ssize_t segment, const char **ptrptr)}
Return the size of the memory buffer in \var{ptrptr} for segment
\var{segment}. \code{*\var{ptrptr}} is set to the memory buffer.
\end{ctypedesc}
\end{cfuncdesc}
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_NewVar}{TYPE, PyTypeObject *type,
- int size}
+ Py_ssize_t size}
Analogous to \cfunction{PyObject_NewVar()} but for container objects
with the \constant{Py_TPFLAGS_HAVE_GC} flag set.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyVarObject *}{PyObject_GC_Resize}{PyVarObject *op, int}
+\begin{cfuncdesc}{PyVarObject *}{PyObject_GC_Resize}{PyVarObject *op, Py_ssize_t}
Resize an object allocated by \cfunction{PyObject_NewVar()}. Returns
the resized object or \NULL{} on failure.
\end{cfuncdesc}
\cfunction{PyObject_GC_Del()}.
\end{enumerate}
-\begin{cfuncdesc}{void}{PyObject_GC_Del}{PyObject *op}
+\begin{cfuncdesc}{void}{PyObject_GC_Del}{void *op}
Releases memory allocated to an object using
\cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_NewVar()}.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{PyObject *op}
+\begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{void *op}
Remove the object \var{op} from the set of container objects tracked
by the collector. Note that \cfunction{PyObject_GC_Track()} can be
called again on this object to add it back to the set of tracked
projects / python / commitdiff