diff options
Diffstat (limited to 'Doc/api')
| -rw-r--r-- | Doc/api/abstract.tex | 48 | ||||
| -rw-r--r-- | Doc/api/concrete.tex | 198 | ||||
| -rw-r--r-- | Doc/api/exceptions.tex | 11 | ||||
| -rw-r--r-- | Doc/api/init.tex | 2 | ||||
| -rw-r--r-- | Doc/api/newtypes.tex | 52 | ||||
| -rw-r--r-- | Doc/api/utilities.tex | 24 |
6 files changed, 168 insertions, 167 deletions
diff --git a/Doc/api/abstract.tex b/Doc/api/abstract.tex index 156583c..c543563 100644 --- a/Doc/api/abstract.tex +++ b/Doc/api/abstract.tex @@ -16,7 +16,7 @@ for which they do not apply, they will raise a Python exception. 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 @@ -24,7 +24,7 @@ for which they do not apply, they will raise a Python exception. \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 @@ -50,7 +50,7 @@ for which they do not apply, they will raise a Python exception. \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 @@ -67,7 +67,7 @@ for which they do not apply, they will raise a Python exception. \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}}. @@ -301,7 +301,7 @@ determination. \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} @@ -340,8 +340,8 @@ determination. \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 @@ -697,14 +697,14 @@ determination. \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} @@ -715,7 +715,7 @@ determination. \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}}. @@ -730,7 +730,7 @@ determination. \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 @@ -738,41 +738,41 @@ determination. \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}]}. @@ -821,7 +821,7 @@ determination. 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. @@ -834,7 +834,7 @@ determination. \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 @@ -860,7 +860,7 @@ determination. \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 @@ -986,7 +986,7 @@ else { \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 @@ -997,7 +997,7 @@ else { \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 @@ -1015,7 +1015,7 @@ else { \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 diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex index 3b12b5c..fd02ecd 100644 --- a/Doc/api/concrete.tex +++ b/Doc/api/concrete.tex @@ -65,7 +65,7 @@ This section describes Python type objects and the singleton object \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type, - int nitems} + Py_ssize_t nitems} \versionadded{2.2} \end{cfuncdesc} @@ -179,7 +179,7 @@ There is no \cfunction{PyNone_Check()} function for the same reason. \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. @@ -268,12 +268,12 @@ booleans. The following macros are available, however. 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} @@ -300,7 +300,7 @@ booleans. The following macros are available, however. \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, @@ -333,14 +333,14 @@ booleans. The following macros are available, however. \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 @@ -582,7 +582,7 @@ parameter and are called with a non-string parameter. \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. @@ -601,6 +601,7 @@ parameter and are called with a non-string parameter. \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.} @@ -617,11 +618,11 @@ parameter and are called with a non-string parameter. 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} @@ -647,7 +648,7 @@ parameter and are called with a non-string parameter. \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}. @@ -686,7 +687,7 @@ parameter and are called with a non-string parameter. 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 @@ -730,7 +731,7 @@ parameter and are called with a non-string parameter. \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 @@ -754,7 +755,7 @@ parameter and are called with a non-string parameter. \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 @@ -829,12 +830,12 @@ checks and to access internal read-only data of Unicode objects: \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} @@ -937,7 +938,7 @@ To create Unicode objects and access their basic sequence properties, 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 @@ -953,7 +954,7 @@ use these APIs: 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} @@ -996,14 +997,14 @@ following functions. Support is optimized if Python's own \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 @@ -1045,7 +1046,7 @@ following generic ones are documented for simplicity. 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 @@ -1057,7 +1058,7 @@ These are the generic codec APIs: \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 @@ -1083,7 +1084,7 @@ These are the generic codec APIs: 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 @@ -1091,9 +1092,9 @@ These are the UTF-8 codec APIs: \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 @@ -1102,7 +1103,7 @@ These are the UTF-8 codec APIs: \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 @@ -1120,7 +1121,7 @@ These are the UTF-8 codec APIs: 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 @@ -1147,10 +1148,10 @@ These are the UTF-16 codec APIs: \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 @@ -1161,7 +1162,7 @@ These are the UTF-16 codec APIs: \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 @@ -1198,7 +1199,7 @@ These are the UTF-16 codec APIs: 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 @@ -1206,8 +1207,7 @@ These are the ``Unicode Escape'' codec APIs: \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. @@ -1224,7 +1224,7 @@ These are the ``Unicode Escape'' codec APIs: 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 @@ -1232,7 +1232,7 @@ These are the ``Raw Unicode Escape'' codec APIs: \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 @@ -1252,7 +1252,7 @@ Latin-1 corresponds to the first 256 Unicode ordinals and only these 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 @@ -1260,7 +1260,7 @@ are accepted by the codecs during encoding. \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 @@ -1279,7 +1279,7 @@ These are the \ASCII{} codec APIs. Only 7-bit \ASCII{} data is 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 @@ -1287,7 +1287,7 @@ accepted. All other codes generate errors. \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 @@ -1327,7 +1327,7 @@ to contain those mappings which map characters to different code 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 @@ -1341,7 +1341,7 @@ points. \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 @@ -1360,7 +1360,7 @@ points. 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 @@ -1386,7 +1386,7 @@ just one. The target encoding is defined by the user settings on the 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 @@ -1394,7 +1394,7 @@ machine running the codec. \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 @@ -1424,7 +1424,7 @@ They all return \NULL{} or \code{-1} if an exception occurs. \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 @@ -1466,8 +1466,8 @@ They all return \NULL{} or \code{-1} if an exception occurs. \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 @@ -1475,10 +1475,10 @@ They all return \NULL{} or \code{-1} if an exception occurs. 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} @@ -1489,10 +1489,10 @@ They all return \NULL{} or \code{-1} if an exception occurs. 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. @@ -1501,7 +1501,7 @@ They all return \NULL{} or \code{-1} if an exception occurs. \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. @@ -1599,7 +1599,7 @@ format. \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 @@ -1613,15 +1613,15 @@ format. \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 @@ -1632,12 +1632,12 @@ format. 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 @@ -1671,11 +1671,11 @@ format. \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})} @@ -1693,38 +1693,38 @@ format. 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 @@ -1768,32 +1768,32 @@ format. \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 @@ -1801,7 +1801,7 @@ format. 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 @@ -1812,7 +1812,7 @@ format. \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 @@ -1828,7 +1828,7 @@ format. \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. @@ -1836,7 +1836,7 @@ format. \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 @@ -1934,7 +1934,7 @@ format. \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 @@ -1961,7 +1961,7 @@ format. \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} @@ -1984,12 +1984,12 @@ format. (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 @@ -2126,7 +2126,7 @@ implementation detail and may change in future releases of Python. 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} @@ -2175,7 +2175,7 @@ implementation detail and may change in future releases of Python. 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 @@ -2185,7 +2185,7 @@ implementation detail and may change in future releases of Python. 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. @@ -2313,7 +2313,7 @@ method objects. \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 @@ -2378,7 +2378,7 @@ There are only a few functions special to module objects. \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 @@ -2415,7 +2415,7 @@ There are only a few functions special to module objects. \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 @@ -2424,7 +2424,7 @@ There are only a few functions special to module objects. \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. @@ -2432,7 +2432,7 @@ There are only a few functions special to module objects. \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 @@ -2503,17 +2503,17 @@ They are found in the dictionary of type objects. \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} @@ -2563,8 +2563,8 @@ They are found in the dictionary of type objects. 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. @@ -2579,9 +2579,9 @@ do well to incorporate the source of \cfunction{PySlice_GetIndicesEx}, 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 diff --git a/Doc/api/exceptions.tex b/Doc/api/exceptions.tex index 784b936..b906172 100644 --- a/Doc/api/exceptions.tex +++ b/Doc/api/exceptions.tex @@ -113,7 +113,7 @@ for each thread. exception state.} \end{cfuncdesc} -\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message} +\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, const char *message} This is the most common way to set the error indicator. The first argument specifies the exception type; it is normally one of the standard exceptions, e.g. \cdata{PyExc_RuntimeError}. You need not @@ -184,7 +184,7 @@ for each thread. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type, - char *filename} + const char *filename} Similar to \cfunction{PyErr_SetFromErrno()}, with the additional behavior that if \var{filename} is not \NULL, it is passed to the constructor of \var{type} as a third parameter. In the case of @@ -217,7 +217,7 @@ for each thread. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErrWithFilename}{int ierr, - char *filename} + const char *filename} Similar to \cfunction{PyErr_SetFromWindowsErr()}, with the additional behavior that if \var{filename} is not \NULL, it is passed to the constructor of \exception{WindowsError} as a third @@ -275,8 +275,9 @@ for each thread. command line documentation. There is no C API for warning control. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message, - char *filename, int lineno, char *module, PyObject *registry} +\begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, + const char *message, const char *filename, int lineno, + const char *module, PyObject *registry} Issue a warning message with explicit control over all warning attributes. This is a straightforward wrapper around the Python function \function{warnings.warn_explicit()}, see there for more diff --git a/Doc/api/init.tex b/Doc/api/init.tex index 91a5c52..73d7bbe 100644 --- a/Doc/api/init.tex +++ b/Doc/api/init.tex @@ -331,7 +331,7 @@ \withsubitem{(in module sys)}{\ttindex{version}} \end{cfuncdesc} -\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv} +\begin{cfuncdesc}{void}{PySys_SetArgv}{int argc, char **argv} Set \code{sys.argv} based on \var{argc} and \var{argv}. These parameters are similar to those passed to the program's \cfunction{main()}\ttindex{main()} function with the difference that diff --git a/Doc/api/newtypes.tex b/Doc/api/newtypes.tex index 114c9bb..b7e25b9 100644 --- a/Doc/api/newtypes.tex +++ b/Doc/api/newtypes.tex @@ -11,7 +11,7 @@ defining new object types. \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} @@ -27,7 +27,7 @@ defining new object types. \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} @@ -42,7 +42,7 @@ defining new object types. \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 @@ -69,7 +69,7 @@ defining new object types. \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. @@ -170,13 +170,13 @@ These macros are used in the definition of \ctype{PyObject} and \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} @@ -383,7 +383,7 @@ objects) \emph{must} have the \member{ob_size} field. 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 @@ -421,7 +421,7 @@ Foo_Type.ob_type = &PyType_Type; 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. @@ -457,8 +457,8 @@ Foo_Type.ob_type = &PyType_Type; 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. @@ -1234,7 +1234,7 @@ int tp_init(PyObject *self, PyObject *args, PyObject *kwds) 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 @@ -1386,15 +1386,15 @@ The remaining fields are only defined if the feature test macro 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} @@ -1509,8 +1509,8 @@ to be able to test for its presence before using it.} \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 @@ -1520,8 +1520,8 @@ to be able to test for its presence before using it.} 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 @@ -1535,16 +1535,16 @@ to be able to test for its presence before using it.} % 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} @@ -1599,12 +1599,12 @@ Constructors for container types must conform to two rules: \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} @@ -1633,12 +1633,12 @@ pair of rules: \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 diff --git a/Doc/api/utilities.tex b/Doc/api/utilities.tex index 78526b8..094cbf3 100644 --- a/Doc/api/utilities.tex +++ b/Doc/api/utilities.tex @@ -8,7 +8,7 @@ values from C values. \section{Operating System Utilities \label{os}} -\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename} +\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, const char *filename} Return true (nonzero) if the standard I/O file \var{fp} with name \var{filename} is deemed interactive. This is the case for files for which \samp{isatty(fileno(\var{fp}))} is true. If the global @@ -91,7 +91,7 @@ values from C values. \section{Importing Modules \label{importing}} -\begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{char *name} +\begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{const char *name} This is a simplified interface to \cfunction{PyImport_ImportModuleEx()} below, leaving the \var{globals} and \var{locals} arguments set to \NULL. When the @@ -148,7 +148,7 @@ values from C values. case). \end{cfuncdesc} -\begin{cfuncdesc}{PyObject*}{PyImport_AddModule}{char *name} +\begin{cfuncdesc}{PyObject*}{PyImport_AddModule}{const char *name} Return the module object corresponding to a module name. The \var{name} argument may be of the form \code{package.module}. First check the modules dictionary if there's one there, and if not, @@ -369,7 +369,7 @@ Should only non-negative values be written using these routines? \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyMarshal_ReadObjectFromString}{char *string, - int len} + Py_ssize_t len} Return a Python object from the data stream in a character buffer containing \var{len} bytes pointed to by \var{string}. On error, sets the appropriate exception (\exception{EOFError} or @@ -687,21 +687,21 @@ format and the format must be exhausted. On success, the \cfunction{PyArg_Parse*()} functions return true, otherwise they return false and raise an appropriate exception. -\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format, +\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, const char *format, \moreargs} 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. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyArg_VaParse}{PyObject *args, char *format, +\begin{cfuncdesc}{int}{PyArg_VaParse}{PyObject *args, const char *format, va_list vargs} Identical to \cfunction{PyArg_ParseTuple()}, except that it accepts a va_list rather than a variable number of arguments. \end{cfuncdesc} \begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args, - PyObject *kw, char *format, char *keywords[], + PyObject *kw, const char *format, char *keywords[], \moreargs} Parse the parameters of a function that takes both positional and keyword parameters into local variables. Returns true on success; @@ -709,13 +709,13 @@ return false and raise an appropriate exception. \end{cfuncdesc} \begin{cfuncdesc}{int}{PyArg_VaParseTupleAndKeywords}{PyObject *args, - PyObject *kw, char *format, char *keywords[], + PyObject *kw, const char *format, char *keywords[], va_list vargs} Identical to \cfunction{PyArg_ParseTupleAndKeywords()}, except that it accepts a va_list rather than a variable number of arguments. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, char *format, +\begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, const char *format, \moreargs} Function used to deconstruct the argument lists of ``old-style'' functions --- these are functions which use the @@ -727,8 +727,8 @@ return false and raise an appropriate exception. purpose. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyArg_UnpackTuple}{PyObject *args, char *name, - int min, int max, \moreargs} +\begin{cfuncdesc}{int}{PyArg_UnpackTuple}{PyObject *args, const char *name, + Py_ssize_t min, Py_ssize_t max, \moreargs} 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 @@ -774,7 +774,7 @@ PyArg_ParseTuple(args, "O|O:ref", &object, &callback) \versionadded{2.2} \end{cfuncdesc} -\begin{cfuncdesc}{PyObject*}{Py_BuildValue}{char *format, +\begin{cfuncdesc}{PyObject*}{Py_BuildValue}{const char *format, \moreargs} Create a new value based on a format string similar to those accepted by the \cfunction{PyArg_Parse*()} family of functions and a |