diff options
Diffstat (limited to 'Doc/api/concrete.tex')
| -rw-r--r-- | Doc/api/concrete.tex | 3326 |
1 files changed, 0 insertions, 3326 deletions
diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex deleted file mode 100644 index ddb19d0..0000000 --- a/Doc/api/concrete.tex +++ /dev/null @@ -1,3326 +0,0 @@ -\chapter{Concrete Objects Layer \label{concrete}} - - -The functions in this chapter are specific to certain Python object -types. Passing them an object of the wrong type is not a good idea; -if you receive an object from a Python program and you are not sure -that it has the right type, you must perform a type check first; -for example, to check that an object is a dictionary, use -\cfunction{PyDict_Check()}. The chapter is structured like the -``family tree'' of Python object types. - -\warning{While the functions described in this chapter carefully check -the type of the objects which are passed in, many of them do not check -for \NULL{} being passed instead of a valid object. Allowing \NULL{} -to be passed in can cause memory access violations and immediate -termination of the interpreter.} - - -\section{Fundamental Objects \label{fundamental}} - -This section describes Python type objects and the singleton object -\code{None}. - - -\subsection{Type Objects \label{typeObjects}} - -\obindex{type} -\begin{ctypedesc}{PyTypeObject} - The C structure of the objects used to describe built-in types. -\end{ctypedesc} - -\begin{cvardesc}{PyObject*}{PyType_Type} - This is the type object for type objects; it is the same object as - \code{type} and \code{types.TypeType} in the Python layer. - \withsubitem{(in module types)}{\ttindex{TypeType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyType_Check}{PyObject *o} - Return true if the object \var{o} is a type object, including - instances of types derived from the standard type object. Return - false in all other cases. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyType_CheckExact}{PyObject *o} - Return true if the object \var{o} is a type object, but not a - subtype of the standard type object. Return false in all other - cases. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature} - Return true if the type object \var{o} sets the feature - \var{feature}. Type features are denoted by single bit flags. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyType_IS_GC}{PyObject *o} - Return true if the type object includes support for the cycle - detector; this tests the type flag \constant{Py_TPFLAGS_HAVE_GC}. - \versionadded{2.0} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b} - Return true if \var{a} is a subtype of \var{b}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type, - Py_ssize_t nitems} - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyType_GenericNew}{PyTypeObject *type, - PyObject *args, PyObject *kwds} - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyType_Ready}{PyTypeObject *type} - Finalize a type object. This should be called on all type objects - to finish their initialization. This function is responsible for - adding inherited slots from a type's base class. Return \code{0} - on success, or return \code{-1} and sets an exception on error. - \versionadded{2.2} -\end{cfuncdesc} - - -\subsection{The None Object \label{noneObject}} - -\obindex{None} -Note that the \ctype{PyTypeObject} for \code{None} is not directly -exposed in the Python/C API. Since \code{None} is a singleton, -testing for object identity (using \samp{==} in C) is sufficient. -There is no \cfunction{PyNone_Check()} function for the same reason. - -\begin{cvardesc}{PyObject*}{Py_None} - The Python \code{None} object, denoting lack of value. This object - has no methods. It needs to be treated just like any other object - with respect to reference counts. -\end{cvardesc} - -\begin{csimplemacrodesc}{Py_RETURN_NONE} - Properly handle returning \cdata{Py_None} from within a C function. - \versionadded{2.4} -\end{csimplemacrodesc} - - -\section{Numeric Objects \label{numericObjects}} - -\obindex{numeric} - - -\subsection{Plain Integer Objects \label{intObjects}} - -\obindex{integer} -\begin{ctypedesc}{PyIntObject} - This subtype of \ctype{PyObject} represents a Python integer - object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyInt_Type} - This instance of \ctype{PyTypeObject} represents the Python plain - integer type. This is the same object as \code{int} and - \code{types.IntType}. - \withsubitem{(in modules types)}{\ttindex{IntType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *o} - Return true if \var{o} is of type \cdata{PyInt_Type} or a subtype - of \cdata{PyInt_Type}. - \versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject *o} - Return true if \var{o} is of type \cdata{PyInt_Type}, but not a - subtype of \cdata{PyInt_Type}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyInt_FromString}{char *str, char **pend, - int base} - Return a new \ctype{PyIntObject} or \ctype{PyLongObject} based on the - string value in \var{str}, which is interpreted according to the radix in - \var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will point to - the first character in \var{str} which follows the representation of the - number. If \var{base} is \code{0}, the radix will be determined based on - the leading characters of \var{str}: if \var{str} starts with \code{'0x'} - or \code{'0X'}, radix 16 will be used; if \var{str} starts with - \code{'0'}, radix 8 will be used; otherwise radix 10 will be used. If - \var{base} is not \code{0}, it must be between \code{2} and \code{36}, - inclusive. Leading spaces are ignored. If there are no digits, - \exception{ValueError} will be raised. If the string represents a number - too large to be contained within the machine's \ctype{long int} type and - overflow warnings are being suppressed, a \ctype{PyLongObject} will be - returned. If overflow warnings are not being suppressed, \NULL{} will be - returned in this case. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival} - Create a new integer object with a value of \var{ival}. - - The current implementation keeps an array of integer objects for all - integers between \code{-5} and \code{256}, when you create an int in - that range you actually just get back a reference to the existing - object. So it should be possible to change the value of \code{1}. I - suspect the behaviour of Python in this case is undefined. :-) -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyInt_FromSsize_t}{Py_ssize_t ival} - Create a new integer object with a value of \var{ival}. - If the value exceeds \code{LONG_MAX}, a long integer object is - returned. - - \versionadded{2.5} -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io} - Will first attempt to cast the object to a \ctype{PyIntObject}, if - it is not already one, and then return its value. If there is an - error, \code{-1} is returned, and the caller should check - \code{PyErr_Occurred()} to find out whether there was an error, or - whether the value just happened to be -1. -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io} - Return the value of the object \var{io}. No error checking is - performed. -\end{cfuncdesc} - -\begin{cfuncdesc}{unsigned long}{PyInt_AsUnsignedLongMask}{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. This function does not check for overflow. - \versionadded{2.3} -\end{cfuncdesc} - -\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. - \versionadded{2.3} -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_ssize_t}{PyInt_AsSsize_t}{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 \ctype{Py_ssize_t}. - \versionadded{2.5} -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_GetMax}{} - Return the system's idea of the largest integer it can handle - (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system - header files). -\end{cfuncdesc} - -\subsection{Boolean Objects \label{boolObjects}} - -Booleans in Python are implemented as a subclass of integers. There -are only two booleans, \constant{Py_False} and \constant{Py_True}. As -such, the normal creation and deletion functions don't apply to -booleans. The following macros are available, however. - -\begin{cfuncdesc}{int}{PyBool_Check}{PyObject *o} - Return true if \var{o} is of type \cdata{PyBool_Type}. - \versionadded{2.3} -\end{cfuncdesc} - -\begin{cvardesc}{PyObject*}{Py_False} - The Python \code{False} object. This object has no methods. It needs to - be treated just like any other object with respect to reference counts. -\end{cvardesc} - -\begin{cvardesc}{PyObject*}{Py_True} - The Python \code{True} object. This object has no methods. It needs to - be treated just like any other object with respect to reference counts. -\end{cvardesc} - -\begin{csimplemacrodesc}{Py_RETURN_FALSE} - Return \constant{Py_False} from a function, properly incrementing its - reference count. -\versionadded{2.4} -\end{csimplemacrodesc} - -\begin{csimplemacrodesc}{Py_RETURN_TRUE} - Return \constant{Py_True} from a function, properly incrementing its - reference count. -\versionadded{2.4} -\end{csimplemacrodesc} - -\begin{cfuncdesc}{PyObject*}{PyBool_FromLong}{long v} - Return a new reference to \constant{Py_True} or \constant{Py_False} - depending on the truth value of \var{v}. -\versionadded{2.3} -\end{cfuncdesc} - -\subsection{Long Integer Objects \label{longObjects}} - -\obindex{long integer} -\begin{ctypedesc}{PyLongObject} - This subtype of \ctype{PyObject} represents a Python long integer - object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyLong_Type} - This instance of \ctype{PyTypeObject} represents the Python long - integer type. This is the same object as \code{long} and - \code{types.LongType}. - \withsubitem{(in modules types)}{\ttindex{LongType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p} - Return true if its argument is a \ctype{PyLongObject} or a subtype - of \ctype{PyLongObject}. - \versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p} - Return true if its argument is a \ctype{PyLongObject}, but not a - subtype of \ctype{PyLongObject}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v} - Return a new \ctype{PyLongObject} object from \var{v}, or \NULL{} - on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v} - Return a new \ctype{PyLongObject} object from a C \ctype{unsigned - long}, or \NULL{} on failure. -\end{cfuncdesc} - -\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 PY_LONG_LONG v} - Return a new \ctype{PyLongObject} object from a C \ctype{unsigned - long long}, or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v} - Return a new \ctype{PyLongObject} object from the integer part of - \var{v}, or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend, - int base} - Return a new \ctype{PyLongObject} based on the string value in - \var{str}, which is interpreted according to the radix in - \var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will - point to the first character in \var{str} which follows the - representation of the number. If \var{base} is \code{0}, the radix - will be determined based on the leading characters of \var{str}: if - \var{str} starts with \code{'0x'} or \code{'0X'}, radix 16 will be - used; if \var{str} starts with \code{'0'}, radix 8 will be used; - otherwise radix 10 will be used. If \var{base} is not \code{0}, it - must be between \code{2} and \code{36}, inclusive. Leading spaces - are ignored. If there are no digits, \exception{ValueError} will be - raised. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u, - 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, - and \var{base} is the radix for the conversion. The radix must be - in the range [2, 36]; if it is out of range, \exception{ValueError} - will be raised. - \versionadded{1.6} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p} - Create a Python integer or long integer from the pointer \var{p}. - The pointer value can be retrieved from the resulting value using - \cfunction{PyLong_AsVoidPtr()}. - \versionadded{1.5.2} - \versionchanged[If the integer is larger than LONG_MAX, - a positive long integer is returned]{2.5} - \end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong} - Return a C \ctype{long} representation of the contents of - \var{pylong}. If \var{pylong} is greater than - \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError} - is raised. - \withsubitem{(built-in exception)}{\ttindex{OverflowError}} -\end{cfuncdesc} - -\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong} - Return a C \ctype{unsigned long} representation of the contents of - \var{pylong}. If \var{pylong} is greater than - \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an - \exception{OverflowError} is raised. - \withsubitem{(built-in exception)}{\ttindex{OverflowError}} -\end{cfuncdesc} - -\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 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 - long}, an \exception{OverflowError} will be raised if the value is - positive, or a \exception{TypeError} will be raised if the value is - negative. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLongMask}{PyObject *io} - Return a C \ctype{unsigned long} from a Python long integer, without - checking for overflow. - \versionadded{2.3} -\end{cfuncdesc} - -\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyLong_AsUnsignedLongLongMask}{PyObject *io} - Return a C \ctype{unsigned long long} from a Python long integer, without - checking for overflow. - \versionadded{2.3} -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong} - Return a C \ctype{double} representation of the contents of - \var{pylong}. If \var{pylong} cannot be approximately represented - as a \ctype{double}, an \exception{OverflowError} exception is - raised and \code{-1.0} will be returned. -\end{cfuncdesc} - -\begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong} - Convert a Python integer or long integer \var{pylong} to a C - \ctype{void} pointer. If \var{pylong} cannot be converted, an - \exception{OverflowError} will be raised. This is only assured to - produce a usable \ctype{void} pointer for values created with - \cfunction{PyLong_FromVoidPtr()}. - \versionadded{1.5.2} - \versionchanged[For values outside 0..LONG_MAX, both signed and - unsigned integers are acccepted]{2.5} -\end{cfuncdesc} - - -\subsection{Floating Point Objects \label{floatObjects}} - -\obindex{floating point} -\begin{ctypedesc}{PyFloatObject} - This subtype of \ctype{PyObject} represents a Python floating point - object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyFloat_Type} - This instance of \ctype{PyTypeObject} represents the Python floating - point type. This is the same object as \code{float} and - \code{types.FloatType}. - \withsubitem{(in modules types)}{\ttindex{FloatType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p} - Return true if its argument is a \ctype{PyFloatObject} or a subtype - of \ctype{PyFloatObject}. - \versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p} - Return true if its argument is a \ctype{PyFloatObject}, but not a - subtype of \ctype{PyFloatObject}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFloat_FromString}{PyObject *str} - Create a \ctype{PyFloatObject} object based on the string value in - \var{str}, or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v} - Create a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on - failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat} - Return a C \ctype{double} representation of the contents of - \var{pyfloat}. If \var{pyfloat} is not a Python floating point - object but has a \method{__float__} method, this method will first - be called to convert \var{pyfloat} into a float. -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat} - Return a C \ctype{double} representation of the contents of - \var{pyfloat}, but without error checking. -\end{cfuncdesc} - - -\subsection{Complex Number Objects \label{complexObjects}} - -\obindex{complex number} -Python's complex number objects are implemented as two distinct types -when viewed from the C API: one is the Python object exposed to -Python programs, and the other is a C structure which represents the -actual complex number value. The API provides functions for working -with both. - -\subsubsection{Complex Numbers as C Structures} - -Note that the functions which accept these structures as parameters -and return them as results do so \emph{by value} rather than -dereferencing them through pointers. This is consistent throughout -the API. - -\begin{ctypedesc}{Py_complex} - The C structure which corresponds to the value portion of a Python - complex number object. Most of the functions for dealing with - complex number objects use structures of this type as input or - output values, as appropriate. It is defined as: - -\begin{verbatim} -typedef struct { - double real; - double imag; -} Py_complex; -\end{verbatim} -\end{ctypedesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right} - Return the sum of two complex numbers, using the C - \ctype{Py_complex} representation. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right} - Return the difference between two complex numbers, using the C - \ctype{Py_complex} representation. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex} - Return the negation of the complex number \var{complex}, using the C - \ctype{Py_complex} representation. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right} - Return the product of two complex numbers, using the C - \ctype{Py_complex} representation. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend, - Py_complex divisor} - Return the quotient of two complex numbers, using the C - \ctype{Py_complex} representation. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp} - Return the exponentiation of \var{num} by \var{exp}, using the C - \ctype{Py_complex} representation. -\end{cfuncdesc} - - -\subsubsection{Complex Numbers as Python Objects} - -\begin{ctypedesc}{PyComplexObject} - This subtype of \ctype{PyObject} represents a Python complex number - object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyComplex_Type} - This instance of \ctype{PyTypeObject} represents the Python complex - number type. It is the same object as \code{complex} and - \code{types.ComplexType}. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p} - Return true if its argument is a \ctype{PyComplexObject} or a - subtype of \ctype{PyComplexObject}. - \versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p} - Return true if its argument is a \ctype{PyComplexObject}, but not a - subtype of \ctype{PyComplexObject}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v} - Create a new Python complex number object from a C - \ctype{Py_complex} value. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag} - Return a new \ctype{PyComplexObject} object from \var{real} and - \var{imag}. -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op} - Return the real part of \var{op} as a C \ctype{double}. -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op} - Return the imaginary part of \var{op} as a C \ctype{double}. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op} - Return the \ctype{Py_complex} value of the complex number \var{op}. - \versionchanged[If \var{op} is not a Python complex number object - but has a \method{__complex__} method, this method - will first be called to convert \var{op} to a Python - complex number object]{2.6} -\end{cfuncdesc} - - - -\section{Sequence Objects \label{sequenceObjects}} - -\obindex{sequence} -Generic operations on sequence objects were discussed in the previous -chapter; this section deals with the specific kinds of sequence -objects that are intrinsic to the Python language. - - -\subsection{String Objects \label{stringObjects}} - -These functions raise \exception{TypeError} when expecting a string -parameter and are called with a non-string parameter. - -\obindex{string} -\begin{ctypedesc}{PyStringObject} - This subtype of \ctype{PyObject} represents a Python string object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyString_Type} - This instance of \ctype{PyTypeObject} represents the Python string - type; it is the same object as \code{str} and \code{types.StringType} - in the Python layer. - \withsubitem{(in module types)}{\ttindex{StringType}}. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o} - Return true if the object \var{o} is a string object or an instance - of a subtype of the string type. - \versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o} - Return true if the object \var{o} is a string object, but not an - instance of a subtype of the string type. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v} - Return a new string object with a copy of the string \var{v} as value - on success, and \NULL{} on failure. The parameter \var{v} must not be - \NULL{}; it will not be checked. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v, - Py_ssize_t len} - Return a new string object with a copy of the string \var{v} as value - and length \var{len} on success, and \NULL{} on failure. If \var{v} is - \NULL{}, the contents of the string are uninitialized. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...} - Take a C \cfunction{printf()}-style \var{format} string and a - variable number of arguments, calculate the size of the resulting - Python string and return a string with the values formatted into - it. The variable arguments must be C types and must correspond - exactly to the format characters in the \var{format} string. The - following format characters are allowed: - - % This should be exactly the same as the table in PyErr_Format. - % One should just refer to the other. - - % The descriptions for %zd and %zu are wrong, but the truth is complicated - % because not all compilers support the %z width modifier -- we fake it - % when necessary via interpolating PY_FORMAT_SIZE_T. - - % %u, %lu, %zu should have "new in Python 2.5" blurbs. - - \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment} - \lineiii{\%\%}{\emph{n/a}}{The literal \% character.} - \lineiii{\%c}{int}{A single character, represented as an C int.} - \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.} - \lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.} - \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.} - \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.} - \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.} - \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.} - \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.} - \lineiii{\%p}{void*}{The hex representation of a C pointer. - Mostly equivalent to \code{printf("\%p")} except that it is - guaranteed to start with the literal \code{0x} regardless of - what the platform's \code{printf} yields.} - \end{tableiii} - - An unrecognized format character causes all the rest of the format - string to be copied as-is to the result string, and any extra - arguments discarded. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format, - va_list vargs} - Identical to \function{PyString_FromFormat()} except that it takes - exactly two arguments. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_ssize_t}{PyString_Size}{PyObject *string} - Return the length of the string in string object \var{string}. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_ssize_t}{PyString_GET_SIZE}{PyObject *string} - Macro form of \cfunction{PyString_Size()} but without error - checking. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string} - Return a NUL-terminated representation of the contents of - \var{string}. The pointer refers to the internal buffer of - \var{string}, not a copy. The data must not be modified in any way, - unless the string was just created using - \code{PyString_FromStringAndSize(NULL, \var{size})}. - It must not be deallocated. If \var{string} is a Unicode object, - this function computes the default encoding of \var{string} and - operates on that. If \var{string} is not a string object at all, - \cfunction{PyString_AsString()} returns \NULL{} and raises - \exception{TypeError}. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string} - Macro form of \cfunction{PyString_AsString()} but without error - checking. Only string objects are supported; no Unicode objects - should be passed. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj, - char **buffer, - 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 function accepts both string and Unicode objects as input. For - Unicode objects it returns the default encoded version of the - object. If \var{length} is \NULL{}, the resulting buffer may not - contain NUL characters; if it does, the function returns \code{-1} - and a \exception{TypeError} is raised. - - The buffer refers to an internal string buffer of \var{obj}, not a - copy. The data must not be modified in any way, unless the string - was just created using \code{PyString_FromStringAndSize(NULL, - \var{size})}. It must not be deallocated. If \var{string} is a - Unicode object, this function computes the default encoding of - \var{string} and operates on that. If \var{string} is not a string - object at all, \cfunction{PyString_AsStringAndSize()} returns - \code{-1} and raises \exception{TypeError}. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string, - PyObject *newpart} - Create a new string object in \var{*string} containing the contents - of \var{newpart} appended to \var{string}; the caller will own the - new reference. The reference to the old value of \var{string} will - be stolen. If the new string cannot be created, the old reference - to \var{string} will still be discarded and the value of - \var{*string} will be set to \NULL{}; the appropriate exception will - be set. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string, - PyObject *newpart} - Create a new string object in \var{*string} containing the contents - of \var{newpart} appended to \var{string}. This version decrements - the reference count of \var{newpart}. -\end{cfuncdesc} - -\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 - is an error to call this function if the refcount on the input string - object is not one. - Pass the address of an existing string object as an lvalue (it may - be written into), and the new size desired. On success, \var{*string} - holds the resized string object and \code{0} is returned; the address in - \var{*string} may differ from its input value. If the - reallocation fails, the original string object at \var{*string} is - deallocated, \var{*string} is set to \NULL{}, a memory exception is set, - and \code{-1} is returned. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format, - PyObject *args} - Return a new string object from \var{format} and \var{args}. - Analogous to \code{\var{format} \%\ \var{args}}. The \var{args} - argument must be a tuple. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string} - Intern the argument \var{*string} in place. The argument must be - the address of a pointer variable pointing to a Python string - object. If there is an existing interned string that is the same as - \var{*string}, it sets \var{*string} to it (decrementing the - reference count of the old string object and incrementing the - reference count of the interned string object), otherwise it leaves - \var{*string} alone and interns it (incrementing its reference - count). (Clarification: even though there is a lot of talk about - reference counts, think of this function as reference-count-neutral; - you own the object after the call if and only if you owned it before - the call.) -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v} - A combination of \cfunction{PyString_FromString()} and - \cfunction{PyString_InternInPlace()}, returning either a new string - object that has been interned, or a new (``owned'') reference to an - earlier interned string object with the same value. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s, - Py_ssize_t size, - const char *encoding, - const char *errors} - Create an object by decoding \var{size} bytes of the encoded - buffer \var{s} using the codec registered for - \var{encoding}. \var{encoding} and \var{errors} have the same - meaning as the parameters of the same name in the - \function{unicode()} built-in function. The codec to be used is - looked up using the Python codec registry. Return \NULL{} if - an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str, - const char *encoding, - const char *errors} - Decode a string object by passing it to the codec registered for - \var{encoding} and return the result as Python - object. \var{encoding} and \var{errors} have the same meaning as the - parameters of the same name in the string \method{encode()} method. - The codec to be used is looked up using the Python codec registry. - Return \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s, - Py_ssize_t size, - const char *encoding, - const char *errors} - Encode the \ctype{char} buffer of the given size by passing it to - the codec registered for \var{encoding} and return a Python object. - \var{encoding} and \var{errors} have the same meaning as the - parameters of the same name in the string \method{encode()} method. - The codec to be used is looked up using the Python codec - registry. Return \NULL{} if an exception was raised by the - codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str, - const char *encoding, - const char *errors} - Encode a string object using the codec registered for - \var{encoding} and return the result as Python object. - \var{encoding} and \var{errors} have the same meaning as the - parameters of the same name in the string \method{encode()} method. - The codec to be used is looked up using the Python codec registry. - Return \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - - -\subsection{Unicode Objects \label{unicodeObjects}} -\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com} - -%--- Unicode Type ------------------------------------------------------- - -These are the basic Unicode object types used for the Unicode -implementation in Python: - -\begin{ctypedesc}{Py_UNICODE} - This type represents the storage type which is used by Python - internally as basis for holding Unicode ordinals. Python's default - builds use a 16-bit type for \ctype{Py_UNICODE} and store Unicode - values internally as UCS2. It is also possible to build a UCS4 - version of Python (most recent Linux distributions come with UCS4 - builds of Python). These builds then use a 32-bit type for - \ctype{Py_UNICODE} and store Unicode data internally as UCS4. On - platforms where \ctype{wchar_t} is available and compatible with the - chosen Python Unicode build variant, \ctype{Py_UNICODE} is a typedef - alias for \ctype{wchar_t} to enhance native platform compatibility. - On all other platforms, \ctype{Py_UNICODE} is a typedef alias for - either \ctype{unsigned short} (UCS2) or \ctype{unsigned long} - (UCS4). -\end{ctypedesc} - -Note that UCS2 and UCS4 Python builds are not binary compatible. -Please keep this in mind when writing extensions or interfaces. - -\begin{ctypedesc}{PyUnicodeObject} - This subtype of \ctype{PyObject} represents a Python Unicode object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyUnicode_Type} - This instance of \ctype{PyTypeObject} represents the Python Unicode - type. It is exposed to Python code as \code{unicode} and - \code{types.UnicodeType}. -\end{cvardesc} - -The following APIs are really C macros and can be used to do fast -checks and to access internal read-only data of Unicode objects: - -\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o} - Return true if the object \var{o} is a Unicode object or an - instance of a Unicode subtype. - \versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o} - Return true if the object \var{o} is a Unicode object, but not an - instance of a subtype. - \versionadded{2.2} -\end{cfuncdesc} - -\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}{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} - -\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o} - Return a pointer to the internal \ctype{Py_UNICODE} buffer of the - object. \var{o} has to be a \ctype{PyUnicodeObject} (not checked). -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o} - Return a pointer to the internal buffer of the object. - \var{o} has to be a \ctype{PyUnicodeObject} (not checked). -\end{cfuncdesc} - -% --- Unicode character properties --------------------------------------- - -Unicode provides many different character properties. The most often -needed ones are available through these macros which are mapped to C -functions depending on the Python configuration. - -\begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch} - Return 1 or 0 depending on whether \var{ch} is a whitespace - character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch} - Return 1 or 0 depending on whether \var{ch} is a lowercase character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch} - Return 1 or 0 depending on whether \var{ch} is an uppercase - character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch} - Return 1 or 0 depending on whether \var{ch} is a titlecase character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch} - Return 1 or 0 depending on whether \var{ch} is a linebreak character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch} - Return 1 or 0 depending on whether \var{ch} is a decimal character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch} - Return 1 or 0 depending on whether \var{ch} is a digit character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch} - Return 1 or 0 depending on whether \var{ch} is a numeric character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch} - Return 1 or 0 depending on whether \var{ch} is an alphabetic - character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch} - Return 1 or 0 depending on whether \var{ch} is an alphanumeric - character. -\end{cfuncdesc} - -These APIs can be used for fast direct character conversions: - -\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch} - Return the character \var{ch} converted to lower case. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch} - Return the character \var{ch} converted to upper case. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch} - Return the character \var{ch} converted to title case. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch} - Return the character \var{ch} converted to a decimal positive - integer. Return \code{-1} if this is not possible. This macro - does not raise exceptions. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch} - Return the character \var{ch} converted to a single digit integer. - Return \code{-1} if this is not possible. This macro does not raise - exceptions. -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch} - Return the character \var{ch} converted to a double. - Return \code{-1.0} if this is not possible. This macro does not raise - exceptions. -\end{cfuncdesc} - -% --- Plain Py_UNICODE --------------------------------------------------- - -To create Unicode objects and access their basic sequence properties, -use these APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u, - 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 - data. The buffer is copied into the new object. If the buffer is - not \NULL{}, the return value might be a shared object. Therefore, - modification of the resulting Unicode object is only allowed when - \var{u} is \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_FromStringAndSize}{const char *u, - Py_ssize_t size} - Create a Unicode Object from the char buffer \var{u}. - The bytes will be interpreted as being UTF-8 encoded. - \var{u} may also be \NULL{} which causes the - contents to be undefined. It is the user's responsibility to fill - in the needed data. The buffer is copied into the new object. - If the buffer is not \NULL{}, the return value might be a shared object. - Therefore, modification of the resulting Unicode object is only allowed - when \var{u} is \NULL{}. - \versionadded{3.0} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_FromString}{const char*u} - Create a Unicode object from an UTF-8 encoded null-terminated - char buffer \var{u}. - \versionadded{3.0} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_FromFormat}{const char *format, ...} - Take a C \cfunction{printf()}-style \var{format} string and a - variable number of arguments, calculate the size of the resulting - Python unicode string and return a string with the values formatted into - it. The variable arguments must be C types and must correspond - exactly to the format characters in the \var{format} string. The - following format characters are allowed: - - % The descriptions for %zd and %zu are wrong, but the truth is complicated - % because not all compilers support the %z width modifier -- we fake it - % when necessary via interpolating PY_FORMAT_SIZE_T. - - \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment} - \lineiii{\%\%}{\emph{n/a}}{The literal \% character.} - \lineiii{\%c}{int}{A single character, represented as an C int.} - \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.} - \lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.} - \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.} - \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.} - \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.} - \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.} - \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.} - \lineiii{\%p}{void*}{The hex representation of a C pointer. - Mostly equivalent to \code{printf("\%p")} except that it is - guaranteed to start with the literal \code{0x} regardless of - what the platform's \code{printf} yields.} - \lineiii{\%U}{PyObject*}{A unicode object.} - \lineiii{\%V}{PyObject*, char *}{A unicode object (which may be \NULL{}) - and a null-terminated C character array as a second parameter (which - will be used, if the first parameter is \NULL{}).} - \lineiii{\%S}{PyObject*}{The result of calling \function{PyObject_Unicode()}.} - \lineiii{\%R}{PyObject*}{The result of calling \function{PyObject_Repr()}.} - \end{tableiii} - - An unrecognized format character causes all the rest of the format - string to be copied as-is to the result string, and any extra - arguments discarded. - \versionadded{3.0} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_FromFormatV}{const char *format, - va_list vargs} - Identical to \function{PyUnicode_FromFormat()} except that it takes - exactly two arguments. - \versionadded{3.0} -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode} - Return a read-only pointer to the Unicode object's internal - \ctype{Py_UNICODE} buffer, \NULL{} if \var{unicode} is not a Unicode - object. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GetSize}{PyObject *unicode} - Return the length of the Unicode object. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj, - const char *encoding, - const char *errors} - Coerce an encoded object \var{obj} to an Unicode object and return a - reference with incremented refcount. - - String and other char buffer compatible objects are decoded - according to the given encoding and using the error handling - defined by errors. Both can be \NULL{} to have the interface - use the default values (see the next section for details). - - All other objects, including Unicode objects, cause a - \exception{TypeError} to be set. - - The API returns \NULL{} if there was an error. The caller is - responsible for decref'ing the returned objects. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj} - Shortcut for \code{PyUnicode_FromEncodedObject(obj, NULL, "strict")} - which is used throughout the interpreter whenever coercion to - Unicode is needed. -\end{cfuncdesc} - -% --- wchar_t support for platforms which support it --------------------- - -If the platform supports \ctype{wchar_t} and provides a header file -wchar.h, Python can interface directly to this type using the -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, - 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}{Py_ssize_t}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode, - wchar_t *w, - 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 - the number of \ctype{wchar_t} characters copied or -1 in case of an - error. Note that the resulting \ctype{wchar_t} string may or may - not be 0-terminated. It is the responsibility of the caller to make - sure that the \ctype{wchar_t} string is 0-terminated in case this is - required by the application. -\end{cfuncdesc} - - -\subsubsection{Built-in Codecs \label{builtinCodecs}} - -Python provides a set of builtin codecs which are written in C -for speed. All of these codecs are directly usable via the -following functions. - -Many of the following APIs take two arguments encoding and -errors. These parameters encoding and errors have the same semantics -as the ones of the builtin unicode() Unicode object constructor. - -Setting encoding to \NULL{} causes the default encoding to be used -which is \ASCII. The file system calls should use -\cdata{Py_FileSystemDefaultEncoding} as the encoding for file -names. This variable should be treated as read-only: On some systems, -it will be a pointer to a static string, on others, it will change at -run-time (such as when the application invokes setlocale). - -Error handling is set by errors which may also be set to \NULL{} -meaning to use the default handling defined for the codec. Default -error handling for all builtin codecs is ``strict'' -(\exception{ValueError} is raised). - -The codecs all use a similar interface. Only deviation from the -following generic ones are documented for simplicity. - -% --- Generic Codecs ----------------------------------------------------- - -These are the generic codec APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s, - Py_ssize_t size, - const char *encoding, - const char *errors} - Create a Unicode object by decoding \var{size} bytes of the encoded - string \var{s}. \var{encoding} and \var{errors} have the same - meaning as the parameters of the same name in the - \function{unicode()} builtin function. The codec to be used is - looked up using the Python codec registry. Return \NULL{} if an - exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s, - Py_ssize_t size, - const char *encoding, - const char *errors} - Encode the \ctype{Py_UNICODE} buffer of the given size and return - a Python string object. \var{encoding} and \var{errors} have the - same meaning as the parameters of the same name in the Unicode - \method{encode()} method. The codec to be used is looked up using - the Python codec registry. Return \NULL{} if an exception was - raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode, - const char *encoding, - const char *errors} - Encode a Unicode object and return the result as Python string - object. \var{encoding} and \var{errors} have the same meaning as the - parameters of the same name in the Unicode \method{encode()} method. - The codec to be used is looked up using the Python codec registry. - Return \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -% --- UTF-8 Codecs ------------------------------------------------------- - -These are the UTF-8 codec APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s, - 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 - by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8Stateful}{const char *s, - Py_ssize_t size, - const char *errors, - 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 - number of bytes that have been decoded will be stored in \var{consumed}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s, - Py_ssize_t size, - const char *errors} - Encode the \ctype{Py_UNICODE} buffer of the given size using UTF-8 - and return a Python string object. Return \NULL{} if an exception - was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode} - Encode a Unicode objects using UTF-8 and return the result as - Python string object. Error handling is ``strict''. Return - \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -% --- UTF-16 Codecs ------------------------------------------------------ */ - -These are the UTF-16 codec APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s, - Py_ssize_t size, - const char *errors, - int *byteorder} - Decode \var{length} bytes from a UTF-16 encoded buffer string and - return the corresponding Unicode object. \var{errors} (if - non-\NULL{}) defines the error handling. It defaults to ``strict''. - - If \var{byteorder} is non-\NULL{}, the decoder starts decoding using - the given byte order: - -\begin{verbatim} - *byteorder == -1: little endian - *byteorder == 0: native order - *byteorder == 1: big endian -\end{verbatim} - - and then switches if the first two bytes of the input data are a byte order - mark (BOM) and the specified byte order is native order. This BOM is not - copied into the resulting Unicode string. After completion, \var{*byteorder} - is set to the current byte order at the. - - If \var{byteorder} is \NULL{}, the codec starts in native order mode. - - Return \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16Stateful}{const char *s, - Py_ssize_t size, - const char *errors, - int *byteorder, - 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 - UTF-16 byte sequences (such as an odd number of bytes or a split surrogate pair) - as an error. Those bytes will not be decoded and the number of bytes that - have been decoded will be stored in \var{consumed}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s, - Py_ssize_t size, - const char *errors, - int byteorder} - Return a Python string object holding the UTF-16 encoded value of - the Unicode data in \var{s}. If \var{byteorder} is not \code{0}, - output is written according to the following byte order: - -\begin{verbatim} - byteorder == -1: little endian - byteorder == 0: native byte order (writes a BOM mark) - byteorder == 1: big endian -\end{verbatim} - - If byteorder is \code{0}, the output string will always start with - the Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark - is prepended. - - If \var{Py_UNICODE_WIDE} is defined, a single \ctype{Py_UNICODE} - value may get represented as a surrogate pair. If it is not - defined, each \ctype{Py_UNICODE} values is interpreted as an - UCS-2 character. - - Return \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode} - Return a Python string using the UTF-16 encoding in native byte - order. The string always starts with a BOM mark. Error handling is - ``strict''. Return \NULL{} if an exception was raised by the - codec. -\end{cfuncdesc} - -% --- Unicode-Escape Codecs ---------------------------------------------- - -These are the ``Unicode Escape'' codec APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s, - 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 - exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s, - 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. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode} - Encode a Unicode objects using Unicode-Escape and return the - result as Python string object. Error handling is ``strict''. - Return \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -% --- Raw-Unicode-Escape Codecs ------------------------------------------ - -These are the ``Raw Unicode Escape'' codec APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s, - 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 - exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s, - 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 - \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode} - Encode a Unicode objects using Raw-Unicode-Escape and return the - result as Python string object. Error handling is ``strict''. - Return \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -% --- Latin-1 Codecs ----------------------------------------------------- - -These are the Latin-1 codec APIs: -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, - 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 - by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s, - Py_ssize_t size, - const char *errors} - Encode the \ctype{Py_UNICODE} buffer of the given size using - Latin-1 and return a Python string object. Return \NULL{} if an - exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode} - Encode a Unicode objects using Latin-1 and return the result as - Python string object. Error handling is ``strict''. Return - \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -% --- ASCII Codecs ------------------------------------------------------- - -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, - 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 - was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s, - Py_ssize_t size, - const char *errors} - Encode the \ctype{Py_UNICODE} buffer of the given size using - \ASCII{} and return a Python string object. Return \NULL{} if an - exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode} - Encode a Unicode objects using \ASCII{} and return the result as - Python string object. Error handling is ``strict''. Return - \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -% --- Character Map Codecs ----------------------------------------------- - -These are the mapping codec APIs: - -This codec is special in that it can be used to implement many -different codecs (and this is in fact what was done to obtain most of -the standard codecs included in the \module{encodings} package). The -codec uses mapping to encode and decode characters. - -Decoding mappings must map single string characters to single Unicode -characters, integers (which are then interpreted as Unicode ordinals) -or None (meaning "undefined mapping" and causing an error). - -Encoding mappings must map single Unicode characters to single string -characters, integers (which are then interpreted as Latin-1 ordinals) -or None (meaning "undefined mapping" and causing an error). - -The mapping objects provided must only support the __getitem__ mapping -interface. - -If a character lookup fails with a LookupError, the character is -copied as-is meaning that its ordinal value will be interpreted as -Unicode or Latin-1 ordinal resp. Because of this, mappings only need -to contain those mappings which map characters to different code -points. - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s, - Py_ssize_t size, - PyObject *mapping, - const char *errors} - Create a Unicode object by decoding \var{size} bytes of the encoded - string \var{s} using the given \var{mapping} object. Return - \NULL{} if an exception was raised by the codec. If \var{mapping} is \NULL{} - latin-1 decoding will be done. Else it can be a dictionary mapping byte or a - unicode string, which is treated as a lookup table. Byte values greater - that the length of the string and U+FFFE "characters" are treated as - "undefined mapping". - \versionchanged[Allowed unicode string as mapping argument]{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s, - Py_ssize_t size, - PyObject *mapping, - const char *errors} - Encode the \ctype{Py_UNICODE} buffer of the given size using the - given \var{mapping} object and return a Python string object. - Return \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode, - PyObject *mapping} - Encode a Unicode objects using the given \var{mapping} object and - return the result as Python string object. Error handling is - ``strict''. Return \NULL{} if an exception was raised by the - codec. -\end{cfuncdesc} - -The following codec API is special in that maps Unicode to Unicode. - -\begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s, - Py_ssize_t size, - PyObject *table, - const char *errors} - Translate a \ctype{Py_UNICODE} buffer of the given length by - applying a character mapping \var{table} to it and return the - resulting Unicode object. Return \NULL{} when an exception was - raised by the codec. - - The \var{mapping} table must map Unicode ordinal integers to Unicode - ordinal integers or None (causing deletion of the character). - - Mapping tables need only provide the \method{__getitem__()} - interface; dictionaries and sequences work well. Unmapped character - ordinals (ones which cause a \exception{LookupError}) are left - untouched and are copied as-is. -\end{cfuncdesc} - -% --- MBCS codecs for Windows -------------------------------------------- - -These are the MBCS codec APIs. They are currently only available on -Windows and use the Win32 MBCS converters to implement the -conversions. Note that MBCS (or DBCS) is a class of encodings, not -just one. The target encoding is defined by the user settings on the -machine running the codec. - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s, - 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 - raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCSStateful}{const char *s, - int size, - const char *errors, - int *consumed} - If \var{consumed} is \NULL{}, behave like - \cfunction{PyUnicode_DecodeMBCS()}. If \var{consumed} is not \NULL{}, - \cfunction{PyUnicode_DecodeMBCSStateful()} will not decode trailing lead - byte and the number of bytes that have been decoded will be stored in - \var{consumed}. - \versionadded{2.5} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s, - 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 - was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode} - Encode a Unicode objects using MBCS and return the result as - Python string object. Error handling is ``strict''. Return - \NULL{} if an exception was raised by the codec. -\end{cfuncdesc} - -% --- Methods & Slots ---------------------------------------------------- - -\subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}} - -The following APIs are capable of handling Unicode objects and strings -on input (we refer to them as strings in the descriptions) and return -Unicode objects or integers as appropriate. - -They all return \NULL{} or \code{-1} if an exception occurs. - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left, - PyObject *right} - Concat two strings giving a new Unicode string. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s, - PyObject *sep, - 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 - will be done. If negative, no limit is set. Separators are not - included in the resulting list. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s, - int keepend} - Split a Unicode string at line breaks, returning a list of Unicode - strings. CRLF is considered to be one line break. If \var{keepend} - is 0, the Line break characters are not included in the resulting - strings. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str, - PyObject *table, - const char *errors} - Translate a string by applying a character mapping table to it and - return the resulting Unicode object. - - The mapping table must map Unicode ordinal integers to Unicode - ordinal integers or None (causing deletion of the character). - - Mapping tables need only provide the \method{__getitem__()} - interface; dictionaries and sequences work well. Unmapped character - ordinals (ones which cause a \exception{LookupError}) are left - untouched and are copied as-is. - - \var{errors} has the usual meaning for codecs. It may be \NULL{} - which indicates to use the default error handling. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator, - PyObject *seq} - Join a sequence of strings using the given separator and return the - resulting Unicode string. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyUnicode_Tailmatch}{PyObject *str, - PyObject *substr, - 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 - match, \var{direction} == 1 a suffix match), 0 otherwise. - Return \code{-1} if an error occurred. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Find}{PyObject *str, - PyObject *substr, - 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} - (\var{direction} == 1 means to do a forward search, - \var{direction} == -1 a backward search). The return value is the - index of the first match; a value of \code{-1} indicates that no - match was found, and \code{-2} indicates that an error occurred and - an exception has been set. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Count}{PyObject *str, - PyObject *substr, - Py_ssize_t start, - Py_ssize_t end} - Return the number of non-overlapping occurrences of \var{substr} in - \code{\var{str}[\var{start}:\var{end}]}. Return \code{-1} if an - error occurred. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str, - PyObject *substr, - PyObject *replstr, - 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}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right} - Compare two strings and return -1, 0, 1 for less than, equal, and - greater than, respectively. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyUnicode_RichCompare}{PyObject *left, - PyObject *right, - int op} - - Rich compare two unicode strings and return one of the following: - \begin{itemize} - \item \code{NULL} in case an exception was raised - \item \constant{Py_True} or \constant{Py_False} for successful comparisons - \item \constant{Py_NotImplemented} in case the type combination is unknown - \end{itemize} - - Note that \constant{Py_EQ} and \constant{Py_NE} comparisons can cause a - \exception{UnicodeWarning} in case the conversion of the arguments to - Unicode fails with a \exception{UnicodeDecodeError}. - - Possible values for \var{op} are - \constant{Py_GT}, \constant{Py_GE}, \constant{Py_EQ}, - \constant{Py_NE}, \constant{Py_LT}, and \constant{Py_LE}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format, - PyObject *args} - Return a new string object from \var{format} and \var{args}; this - is analogous to \code{\var{format} \%\ \var{args}}. The - \var{args} argument must be a tuple. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container, - PyObject *element} - Check whether \var{element} is contained in \var{container} and - return true or false accordingly. - - \var{element} has to coerce to a one element Unicode - string. \code{-1} is returned if there was an error. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyUnicode_InternInPlace}{PyObject **string} - Intern the argument \var{*string} in place. The argument must be - the address of a pointer variable pointing to a Python unicode string - object. If there is an existing interned string that is the same as - \var{*string}, it sets \var{*string} to it (decrementing the - reference count of the old string object and incrementing the - reference count of the interned string object), otherwise it leaves - \var{*string} alone and interns it (incrementing its reference - count). (Clarification: even though there is a lot of talk about - reference counts, think of this function as reference-count-neutral; - you own the object after the call if and only if you owned it before - the call.) -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_InternFromString}{const char *v} - A combination of \cfunction{PyUnicode_FromString()} and - \cfunction{PyUnicode_InternInPlace()}, returning either a new unicode - string object that has been interned, or a new (``owned'') reference to - an earlier interned string object with the same value. -\end{cfuncdesc} - - -\subsection{Buffer Objects \label{bufferObjects}} -\sectionauthor{Greg Stein}{gstein@lyra.org} - -\obindex{buffer} -Python objects implemented in C can export a group of functions called -the ``buffer\index{buffer interface} interface.'' These functions can -be used by an object to expose its data in a raw, byte-oriented -format. Clients of the object can use the buffer interface to access -the object data directly, without needing to copy it first. - -Two examples of objects that support -the buffer interface are strings and arrays. The string object exposes -the character contents in the buffer interface's byte-oriented -form. An array can also expose its contents, but it should be noted -that array elements may be multi-byte values. - -An example user of the buffer interface is the file object's -\method{write()} method. Any object that can export a series of bytes -through the buffer interface can be written to a file. There are a -number of format codes to \cfunction{PyArg_ParseTuple()} that operate -against an object's buffer interface, returning data from the target -object. - -More information on the buffer interface is provided in the section -``Buffer Object Structures'' (section~\ref{buffer-structs}), under -the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}. - -A ``buffer object'' is defined in the \file{bufferobject.h} header -(included by \file{Python.h}). These objects look very similar to -string objects at the Python programming level: they support slicing, -indexing, concatenation, and some other standard string -operations. However, their data can come from one of two sources: from -a block of memory, or from another object which exports the buffer -interface. - -Buffer objects are useful as a way to expose the data from another -object's buffer interface to the Python programmer. They can also be -used as a zero-copy slicing mechanism. Using their ability to -reference a block of memory, it is possible to expose any data to the -Python programmer quite easily. The memory could be a large, constant -array in a C extension, it could be a raw block of memory for -manipulation before passing to an operating system library, or it -could be used to pass around structured data in its native, in-memory -format. - -\begin{ctypedesc}{PyBufferObject} - This subtype of \ctype{PyObject} represents a buffer object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyBuffer_Type} - The instance of \ctype{PyTypeObject} which represents the Python - buffer type; it is the same object as \code{buffer} and - \code{types.BufferType} in the Python layer. - \withsubitem{(in module types)}{\ttindex{BufferType}}. -\end{cvardesc} - -\begin{cvardesc}{int}{Py_END_OF_BUFFER} - This constant may be passed as the \var{size} parameter to - \cfunction{PyBuffer_FromObject()} or - \cfunction{PyBuffer_FromReadWriteObject()}. It indicates that the - new \ctype{PyBufferObject} should refer to \var{base} object from - the specified \var{offset} to the end of its exported buffer. Using - this enables the caller to avoid querying the \var{base} object for - its length. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p} - Return true if the argument has type \cdata{PyBuffer_Type}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base, - 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 - raises \exception{ValueError} if \var{offset} is less than zero. The - buffer will hold a reference to the \var{base} object, and the - buffer's contents will refer to the \var{base} object's buffer - interface, starting as position \var{offset} and extending for - \var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then - the new buffer's contents extend to the length of the \var{base} - object's exported buffer data. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base, - Py_ssize_t offset, - Py_ssize_t size} - Return a new writable buffer object. Parameters and exceptions are - similar to those for \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, 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 - \var{ptr}, is not deallocated while the returned buffer object - exists. Raises \exception{ValueError} if \var{size} is less than - zero. Note that \constant{Py_END_OF_BUFFER} may \emph{not} be - passed for the \var{size} parameter; \exception{ValueError} will be - raised in that case. -\end{cfuncdesc} - -\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}{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 - returned by \cfunction{PyObject_AsWriteBuffer()}) is not specifically - aligned. -\end{cfuncdesc} - - -\subsection{Tuple Objects \label{tupleObjects}} - -\obindex{tuple} -\begin{ctypedesc}{PyTupleObject} - This subtype of \ctype{PyObject} represents a Python tuple object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyTuple_Type} - This instance of \ctype{PyTypeObject} represents the Python tuple - type; it is the same object as \code{tuple} and \code{types.TupleType} - in the Python layer.\withsubitem{(in module types)}{\ttindex{TupleType}}. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p} - Return true if \var{p} is a tuple object or an instance of a subtype - of the tuple type. - \versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTuple_CheckExact}{PyObject *p} - Return true if \var{p} is a tuple object, but not an instance of a - subtype of the tuple type. - \versionadded{2.2} -\end{cfuncdesc} - -\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}{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})} - is equivalent to \samp{Py_BuildValue("(OO)", \var{a}, \var{b})}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p} - Take a pointer to a tuple object, and return the size of that - tuple. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTuple_GET_SIZE}{PyObject *p} - Return the size of the tuple \var{p}, which must be non-\NULL{} and - point to a tuple; no error checking is performed. -\end{cfuncdesc} - -\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, Py_ssize_t pos} - Like \cfunction{PyTuple_GetItem()}, but does no checking of its - arguments. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p, - 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, - 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, - 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, 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 - object. Do \emph{not} use this if the tuple may already be known to - some other part of the code. The tuple will always grow or shrink - at the end. Think of this as destroying the old tuple and creating - a new one, only more efficiently. Returns \code{0} on success. - Client code should never assume that the resulting value of - \code{*\var{p}} will be the same as before calling this function. - If the object referenced by \code{*\var{p}} is replaced, the - original \code{*\var{p}} is destroyed. On failure, returns - \code{-1} and sets \code{*\var{p}} to \NULL{}, and raises - \exception{MemoryError} or - \exception{SystemError}. - \versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2} -\end{cfuncdesc} - - -\subsection{List Objects \label{listObjects}} - -\obindex{list} -\begin{ctypedesc}{PyListObject} - This subtype of \ctype{PyObject} represents a Python list object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyList_Type} - This instance of \ctype{PyTypeObject} represents the Python list - type. This is the same object as \code{list} and \code{types.ListType} - in the Python layer.\withsubitem{(in module types)}{\ttindex{ListType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p} - Return true if \var{p} is a list object or an instance of a - subtype of the list type. - \versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_CheckExact}{PyObject *p} - Return true if \var{p} is a list object, but not an instance of a - subtype of the list type. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyList_New}{Py_ssize_t len} - Return a new list of length \var{len} on success, or \NULL{} on - failure. - \note{If \var{length} is greater than zero, the returned list object's - items are set to \code{NULL}. Thus you cannot use abstract - API functions such as \cfunction{PySequence_SetItem()} - or expose the object to Python code before setting all items to a - real object with \cfunction{PyList_SetItem()}.} -\end{cfuncdesc} - -\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}{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, Py_ssize_t index} - Return the object at position \var{pos} in the list pointed to by - \var{p}. The position must be positive, indexing from the end of the - list is not supported. 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, Py_ssize_t i} - Macro form of \cfunction{PyList_GetItem()} without error checking. -\end{cfuncdesc} - -\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 - ``steals'' a reference to \var{item} and discards a reference to an - item already in the list at the affected position.} -\end{cfuncdesc} - -\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 - previous content. - \note{This function ``steals'' a reference to \var{item}, and, - unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a - reference to any item that it being replaced; any reference in - \var{list} at position \var{i} will be leaked.} -\end{cfuncdesc} - -\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 - set an exception if unsuccessful. Analogous to - \code{\var{list}.insert(\var{index}, \var{item})}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item} - Append the object \var{item} at the end of list \var{list}. - Return \code{0} if successful; return \code{-1} and set an - exception if unsuccessful. Analogous to - \code{\var{list}.append(\var{item})}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list, - 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. - Analogous to \code{\var{list}[\var{low}:\var{high}]}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list, - 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 - \code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}. - The \var{itemlist} may be \NULL{}, indicating the assignment - of an empty list (slice deletion). - Return \code{0} on success, \code{-1} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list} - Sort the items of \var{list} in place. Return \code{0} on - success, \code{-1} on failure. This is equivalent to - \samp{\var{list}.sort()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list} - Reverse the items of \var{list} in place. Return \code{0} on - success, \code{-1} on failure. This is the equivalent of - \samp{\var{list}.reverse()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list} - Return a new tuple object containing the contents of \var{list}; - equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple} -\end{cfuncdesc} - - -\section{Mapping Objects \label{mapObjects}} - -\obindex{mapping} - - -\subsection{Dictionary Objects \label{dictObjects}} - -\obindex{dictionary} -\begin{ctypedesc}{PyDictObject} - This subtype of \ctype{PyObject} represents a Python dictionary - object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyDict_Type} - This instance of \ctype{PyTypeObject} represents the Python - dictionary type. This is exposed to Python programs as - \code{dict} and \code{types.DictType}. - \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p} - Return true if \var{p} is a dict object or an instance of a - subtype of the dict type. - \versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_CheckExact}{PyObject *p} - Return true if \var{p} is a dict object, but not an instance of a - subtype of the dict type. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDict_New}{} - Return a new empty dictionary, or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDictProxy_New}{PyObject *dict} - Return a proxy object for a mapping which enforces read-only - behavior. This is normally used to create a proxy to prevent - modification of the dictionary for non-dynamic class types. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p} - Empty an existing dictionary of all key-value pairs. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_Contains}{PyObject *p, PyObject *key} - Determine if dictionary \var{p} contains \var{key}. If an item - in \var{p} is matches \var{key}, return \code{1}, otherwise return - \code{0}. On error, return \code{-1}. This is equivalent to the - Python expression \samp{\var{key} in \var{p}}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p} - Return a new dictionary that contains the same key-value pairs as - \var{p}. - \versionadded{1.6} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key, - PyObject *val} - Insert \var{value} into the dictionary \var{p} with a key of - \var{key}. \var{key} must be hashable; if it isn't, - \exception{TypeError} will be raised. - Return \code{0} on success or \code{-1} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p, - 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 - using \code{PyString_FromString(\var{key})}. Return \code{0} on - success or \code{-1} on failure. - \ttindex{PyString_FromString()} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key} - Remove the entry in dictionary \var{p} with key \var{key}. - \var{key} must be hashable; if it isn't, \exception{TypeError} is - raised. Return \code{0} on success or \code{-1} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key} - Remove the entry in dictionary \var{p} which has a key specified by - the string \var{key}. Return \code{0} on success or \code{-1} on - failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key} - Return the object from dictionary \var{p} which has a key - \var{key}. Return \NULL{} if the key \var{key} is not present, but - \emph{without} setting an exception. -\end{cfuncdesc} - -\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} - -\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p} - Return a \ctype{PyListObject} containing all the items from the - dictionary, as in the dictionary method \method{items()} (see the - \citetitle[../lib/lib.html]{Python Library Reference}). -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p} - Return a \ctype{PyListObject} containing all the keys from the - dictionary, as in the dictionary method \method{keys()} (see the - \citetitle[../lib/lib.html]{Python Library Reference}). -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p} - Return a \ctype{PyListObject} containing all the values from the - dictionary \var{p}, as in the dictionary method \method{values()} - (see the \citetitle[../lib/lib.html]{Python Library Reference}). -\end{cfuncdesc} - -\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, 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 - \code{0} prior to the first call to this function to start the - iteration; the function returns true for each pair in the - dictionary, and false once all pairs have been reported. The - parameters \var{pkey} and \var{pvalue} should either point to - \ctype{PyObject*} variables that will be filled in with each key and - value, respectively, or may be \NULL{}. Any references returned through - them are borrowed. \var{ppos} should not be altered during iteration. - Its value represents offsets within the internal dictionary structure, - and since the structure is sparse, the offsets are not consecutive. - - For example: - -\begin{verbatim} -PyObject *key, *value; -Py_ssize_t pos = 0; - -while (PyDict_Next(self->dict, &pos, &key, &value)) { - /* do something interesting with the values... */ - ... -} -\end{verbatim} - - The dictionary \var{p} should not be mutated during iteration. It - is safe (since Python 2.1) to modify the values of the keys as you - iterate over the dictionary, but only so long as the set of keys - does not change. For example: - -\begin{verbatim} -PyObject *key, *value; -Py_ssize_t pos = 0; - -while (PyDict_Next(self->dict, &pos, &key, &value)) { - int i = PyInt_AS_LONG(value) + 1; - PyObject *o = PyInt_FromLong(i); - if (o == NULL) - return -1; - if (PyDict_SetItem(self->dict, key, o) < 0) { - Py_DECREF(o); - return -1; - } - Py_DECREF(o); -} -\end{verbatim} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_Merge}{PyObject *a, PyObject *b, int override} - Iterate over mapping object \var{b} adding key-value pairs to dictionary - \var{a}. - \var{b} may be a dictionary, or any object supporting - \function{PyMapping_Keys()} and \function{PyObject_GetItem()}. - If \var{override} is true, existing pairs in \var{a} will - be replaced if a matching key is found in \var{b}, otherwise pairs - will only be added if there is not a matching key in \var{a}. - Return \code{0} on success or \code{-1} if an exception was - raised. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_Update}{PyObject *a, PyObject *b} - This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C, - or \code{\var{a}.update(\var{b})} in Python. Return \code{0} on - success or \code{-1} if an exception was raised. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_MergeFromSeq2}{PyObject *a, PyObject *seq2, - int override} - Update or merge into dictionary \var{a}, from the key-value pairs in - \var{seq2}. \var{seq2} must be an iterable object producing - iterable objects of length 2, viewed as key-value pairs. In case of - duplicate keys, the last wins if \var{override} is true, else the - first wins. - Return \code{0} on success or \code{-1} if an exception - was raised. - Equivalent Python (except for the return value): - -\begin{verbatim} -def PyDict_MergeFromSeq2(a, seq2, override): - for key, value in seq2: - if override or key not in a: - a[key] = value -\end{verbatim} - - \versionadded{2.2} -\end{cfuncdesc} - - -\section{Other Objects \label{otherObjects}} - -\subsection{Class Objects \label{classObjects}} - -\obindex{class} -Note that the class objects described here represent old-style classes, -which will go away in Python 3. When creating new types for extension -modules, you will want to work with type objects (section -\ref{typeObjects}). - -\begin{ctypedesc}{PyClassObject} - The C structure of the objects used to describe built-in classes. -\end{ctypedesc} - -\begin{cvardesc}{PyObject*}{PyClass_Type} - This is the type object for class objects; it is the same object as - \code{types.ClassType} in the Python layer. - \withsubitem{(in module types)}{\ttindex{ClassType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyClass_Check}{PyObject *o} - Return true if the object \var{o} is a class object, including - instances of types derived from the standard class object. Return - false in all other cases. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyClass_IsSubclass}{PyObject *klass, PyObject *base} - Return true if \var{klass} is a subclass of \var{base}. Return false in - all other cases. -\end{cfuncdesc} - -\subsection{File Objects \label{fileObjects}} - -\obindex{file} -Python's built-in file objects are implemented entirely on the -\ctype{FILE*} support from the C standard library. This is an -implementation detail and may change in future releases of Python. - -\begin{ctypedesc}{PyFileObject} - This subtype of \ctype{PyObject} represents a Python file object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyFile_Type} - This instance of \ctype{PyTypeObject} represents the Python file - type. This is exposed to Python programs as \code{file} and - \code{types.FileType}. - \withsubitem{(in module types)}{\ttindex{FileType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p} - Return true if its argument is a \ctype{PyFileObject} or a subtype - of \ctype{PyFileObject}. - \versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p} - Return true if its argument is a \ctype{PyFileObject}, but not a - subtype of \ctype{PyFileObject}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode} - On success, return a new file object that is opened on the file - given by \var{filename}, with a file mode given by \var{mode}, where - \var{mode} has the same semantics as the standard C routine - \cfunction{fopen()}\ttindex{fopen()}. On failure, return \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, - char *name, char *mode, - int (*close)(FILE*)} - Create a new \ctype{PyFileObject} from the already-open standard C - file pointer, \var{fp}. The function \var{close} will be called - when the file should be closed. Return \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyObject *p} - Return the file object associated with \var{p} as a \ctype{FILE*}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n} - Equivalent to \code{\var{p}.readline(\optional{\var{n}})}, this - function reads one line from the object \var{p}. \var{p} may be a - file object or any object with a \method{readline()} method. If - \var{n} is \code{0}, exactly one line is read, regardless of the - length of the line. If \var{n} is greater than \code{0}, no more - than \var{n} bytes will be read from the file; a partial line can be - returned. In both cases, an empty string is returned if the end of - the file is reached immediately. If \var{n} is less than \code{0}, - however, one line is read regardless of length, but - \exception{EOFError} is raised if the end of the file is reached - immediately. - \withsubitem{(built-in exception)}{\ttindex{EOFError}} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p} - Return the name of the file specified by \var{p} as a string - object. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n} - Available on systems with \cfunction{setvbuf()}\ttindex{setvbuf()} - only. This should only be called immediately after file object - creation. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFile_Encoding}{PyFileObject *p, char *enc} - Set the file's encoding for Unicode output to \var{enc}. Return - 1 on success and 0 on failure. - \versionadded{2.3} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag} - This function exists for internal use by the interpreter. Set the - \member{softspace} attribute of \var{p} to \var{newflag} and - \withsubitem{(file attribute)}{\ttindex{softspace}}return the - previous value. \var{p} does not have to be a file object for this - function to work properly; any object is supported (thought its only - interesting if the \member{softspace} attribute can be set). This - function clears any errors, and will return \code{0} as the previous - value if the attribute either does not exist or if there were errors - in retrieving it. There is no way to detect errors from this - function, but doing so should not be needed. -\end{cfuncdesc} - -\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 - \constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW}; if given, the - \function{str()} of the object is written instead of the - \function{repr()}. Return \code{0} on success or \code{-1} on - failure; the appropriate exception will be set. -\end{cfuncdesc} - -\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. -\end{cfuncdesc} - - -\subsection{Instance Objects \label{instanceObjects}} - -\obindex{instance} -There are very few functions specific to instance objects. - -\begin{cvardesc}{PyTypeObject}{PyInstance_Type} - Type object for class instances. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj} - Return true if \var{obj} is an instance. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class, - PyObject *arg, - PyObject *kw} - Create a new instance of a specific class. The parameters \var{arg} - and \var{kw} are used as the positional and keyword parameters to - the object's constructor. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class, - PyObject *dict} - Create a new instance of a specific class without calling its - constructor. \var{class} is the class of new object. The - \var{dict} parameter will be used as the object's \member{__dict__}; - if \NULL{}, a new dictionary will be created for the instance. -\end{cfuncdesc} - - -\subsection{Function Objects \label{function-objects}} - -\obindex{function} -There are a few functions specific to Python functions. - -\begin{ctypedesc}{PyFunctionObject} - The C structure used for functions. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyFunction_Type} - This is an instance of \ctype{PyTypeObject} and represents the - Python function type. It is exposed to Python programmers as - \code{types.FunctionType}. - \withsubitem{(in module types)}{\ttindex{MethodType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyFunction_Check}{PyObject *o} - Return true if \var{o} is a function object (has type - \cdata{PyFunction_Type}). The parameter must not be \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFunction_New}{PyObject *code, - PyObject *globals} - Return a new function object associated with the code object - \var{code}. \var{globals} must be a dictionary with the global - variables accessible to the function. - - The function's docstring, name and \var{__module__} are retrieved - from the code object, the argument defaults and closure are set to - \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFunction_GetCode}{PyObject *op} - Return the code object associated with the function object \var{op}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFunction_GetGlobals}{PyObject *op} - Return the globals dictionary associated with the function object - \var{op}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFunction_GetModule}{PyObject *op} - Return the \var{__module__} attribute of the function object \var{op}. - This is normally a string containing the module name, but can be set - to any other object by Python code. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFunction_GetDefaults}{PyObject *op} - Return the argument default values of the function object \var{op}. - This can be a tuple of arguments or \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFunction_SetDefaults}{PyObject *op, - PyObject *defaults} - Set the argument default values for the function object \var{op}. - \var{defaults} must be \var{Py_None} or a tuple. - - Raises \exception{SystemError} and returns \code{-1} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFunction_GetClosure}{PyObject *op} - Return the closure associated with the function object \var{op}. - This can be \NULL{} or a tuple of cell objects. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFunction_SetClosure}{PyObject *op, - PyObject *closure} - Set the closure associated with the function object \var{op}. - \var{closure} must be \var{Py_None} or a tuple of cell objects. - - Raises \exception{SystemError} and returns \code{-1} on failure. -\end{cfuncdesc} - - -\subsection{Method Objects \label{method-objects}} - -\obindex{method} -There are some useful functions that are useful for working with -method objects. - -\begin{cvardesc}{PyTypeObject}{PyMethod_Type} - This instance of \ctype{PyTypeObject} represents the Python method - type. This is exposed to Python programs as \code{types.MethodType}. - \withsubitem{(in module types)}{\ttindex{MethodType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o} - Return true if \var{o} is a method object (has type - \cdata{PyMethod_Type}). The parameter must not be \NULL{}. -\end{cfuncdesc} - -\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 - called. If this method should be bound to an instance, \var{self} - should be the instance and \var{class} should be the class of - \var{self}, otherwise \var{self} should be \NULL{} and \var{class} - should be the class which provides the unbound method.. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_Class}{PyObject *meth} - Return the class object from which the method \var{meth} was - created; if this was created from an instance, it will be the class - of the instance. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_GET_CLASS}{PyObject *meth} - Macro version of \cfunction{PyMethod_Class()} which avoids error - checking. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_Function}{PyObject *meth} - Return the function object associated with the method \var{meth}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_GET_FUNCTION}{PyObject *meth} - Macro version of \cfunction{PyMethod_Function()} which avoids error - checking. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth} - Return the instance associated with the method \var{meth} if it is - bound, otherwise return \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth} - Macro version of \cfunction{PyMethod_Self()} which avoids error - checking. -\end{cfuncdesc} - - -\subsection{Module Objects \label{moduleObjects}} - -\obindex{module} -There are only a few functions special to module objects. - -\begin{cvardesc}{PyTypeObject}{PyModule_Type} - This instance of \ctype{PyTypeObject} represents the Python module - type. This is exposed to Python programs as - \code{types.ModuleType}. - \withsubitem{(in module types)}{\ttindex{ModuleType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p} - Return true if \var{p} is a module object, or a subtype of a module - object. - \versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p} - Return true if \var{p} is a module object, but not a subtype of - \cdata{PyModule_Type}. - \versionadded{2.2} -\end{cfuncdesc} - -\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 - responsible for providing a \member{__file__} attribute. - \withsubitem{(module attribute)}{ - \ttindex{__name__}\ttindex{__doc__}\ttindex{__file__}} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module} - Return the dictionary object that implements \var{module}'s - namespace; this object is the same as the \member{__dict__} - attribute of the module object. This function never fails. - \withsubitem{(module attribute)}{\ttindex{__dict__}} - It is recommended extensions use other \cfunction{PyModule_*()} - and \cfunction{PyObject_*()} functions rather than directly - manipulate a module's \member{__dict__}. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module} - Return \var{module}'s \member{__name__} value. If the module does - not provide one, or if it is not a string, \exception{SystemError} - is raised and \NULL{} is returned. - \withsubitem{(module attribute)}{\ttindex{__name__}} - \withsubitem{(built-in exception)}{\ttindex{SystemError}} -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module} - Return the name of the file from which \var{module} was loaded using - \var{module}'s \member{__file__} attribute. If this is not defined, - or if it is not a string, raise \exception{SystemError} and return - \NULL{}. - \withsubitem{(module attribute)}{\ttindex{__file__}} - \withsubitem{(built-in exception)}{\ttindex{SystemError}} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module, - 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 - \code{-1} on error, \code{0} on success. - \versionadded{2.0} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module, - 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. - \versionadded{2.0} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module, - 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 - \code{-1} on error, \code{0} on success. - \versionadded{2.0} -\end{cfuncdesc} - - -\subsection{Iterator Objects \label{iterator-objects}} - -Python provides two general-purpose iterator objects. The first, a -sequence iterator, works with an arbitrary sequence supporting the -\method{__getitem__()} method. The second works with a callable -object and a sentinel value, calling the callable for each item in the -sequence, and ending the iteration when the sentinel value is -returned. - -\begin{cvardesc}{PyTypeObject}{PySeqIter_Type} - Type object for iterator objects returned by - \cfunction{PySeqIter_New()} and the one-argument form of the - \function{iter()} built-in function for built-in sequence types. - \versionadded{2.2} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PySeqIter_Check}{op} - Return true if the type of \var{op} is \cdata{PySeqIter_Type}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySeqIter_New}{PyObject *seq} - Return an iterator that works with a general sequence object, - \var{seq}. The iteration ends when the sequence raises - \exception{IndexError} for the subscripting operation. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cvardesc}{PyTypeObject}{PyCallIter_Type} - Type object for iterator objects returned by - \cfunction{PyCallIter_New()} and the two-argument form of the - \function{iter()} built-in function. - \versionadded{2.2} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyCallIter_Check}{op} - Return true if the type of \var{op} is \cdata{PyCallIter_Type}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyCallIter_New}{PyObject *callable, - PyObject *sentinel} - Return a new iterator. The first parameter, \var{callable}, can be - any Python callable object that can be called with no parameters; - each call to it should return the next item in the iteration. When - \var{callable} returns a value equal to \var{sentinel}, the - iteration will be terminated. - \versionadded{2.2} -\end{cfuncdesc} - - -\subsection{Descriptor Objects \label{descriptor-objects}} - -``Descriptors'' are objects that describe some attribute of an object. -They are found in the dictionary of type objects. - -\begin{cvardesc}{PyTypeObject}{PyProperty_Type} - The type object for the built-in descriptor types. - \versionadded{2.2} -\end{cvardesc} - -\begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type, - struct PyGetSetDef *getset} - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type, - struct PyMemberDef *meth} - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type, - struct PyMethodDef *meth} - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDescr_NewWrapper}{PyTypeObject *type, - struct wrapperbase *wrapper, - void *wrapped} - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDescr_NewClassMethod}{PyTypeObject *type, - PyMethodDef *method} - \versionadded{2.3} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDescr_IsData}{PyObject *descr} - Return true if the descriptor objects \var{descr} describes a data - attribute, or false if it describes a method. \var{descr} must be a - descriptor object; there is no error checking. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyWrapper_New}{PyObject *, PyObject *} - \versionadded{2.2} -\end{cfuncdesc} - - -\subsection{Slice Objects \label{slice-objects}} - -\begin{cvardesc}{PyTypeObject}{PySlice_Type} - The type object for slice objects. This is the same as - \code{slice} and \code{types.SliceType}. - \withsubitem{(in module types)}{\ttindex{SliceType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob} - Return true if \var{ob} is a slice object; \var{ob} must not be - \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySlice_New}{PyObject *start, PyObject *stop, - PyObject *step} - Return a new slice object with the given values. The \var{start}, - \var{stop}, and \var{step} parameters are used as the values of the - slice object attributes of the same names. Any of the values may be - \NULL{}, in which case the \code{None} will be used for the - corresponding attribute. Return \NULL{} if the new object could - not be allocated. -\end{cfuncdesc} - -\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. - -Returns 0 on success and -1 on error with no exception set (unless one -of the indices was not \constant{None} and failed to be converted to -an integer, in which case -1 is returned with an exception set). - -You probably do not want to use this function. If you want to use -slice objects in versions of Python prior to 2.3, you would probably -do well to incorporate the source of \cfunction{PySlice_GetIndicesEx}, -suitably renamed, in the source of your extension. -\end{cfuncdesc} - -\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 -the slice in \var{slicelength}. Out of bounds indices are clipped in -a manner consistent with the handling of normal slices. - -Returns 0 on success and -1 on error with exception set. - -\versionadded{2.3} -\end{cfuncdesc} - - -\subsection{Weak Reference Objects \label{weakref-objects}} - -Python supports \emph{weak references} as first-class objects. There -are two specific object types which directly implement weak -references. The first is a simple reference object, and the second -acts as a proxy for the original object as much as it can. - -\begin{cfuncdesc}{int}{PyWeakref_Check}{ob} - Return true if \var{ob} is either a reference or proxy object. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyWeakref_CheckRef}{ob} - Return true if \var{ob} is a reference object. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyWeakref_CheckProxy}{ob} - Return true if \var{ob} is a proxy object. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyWeakref_NewRef}{PyObject *ob, - PyObject *callback} - Return a weak reference object for the object \var{ob}. This will - always return a new reference, but is not guaranteed to create a new - object; an existing reference object may be returned. The second - parameter, \var{callback}, can be a callable object that receives - notification when \var{ob} is garbage collected; it should accept a - single parameter, which will be the weak reference object itself. - \var{callback} may also be \code{None} or \NULL{}. If \var{ob} - is not a weakly-referencable object, or if \var{callback} is not - callable, \code{None}, or \NULL{}, this will return \NULL{} and - raise \exception{TypeError}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyWeakref_NewProxy}{PyObject *ob, - PyObject *callback} - Return a weak reference proxy object for the object \var{ob}. This - will always return a new reference, but is not guaranteed to create - a new object; an existing proxy object may be returned. The second - parameter, \var{callback}, can be a callable object that receives - notification when \var{ob} is garbage collected; it should accept a - single parameter, which will be the weak reference object itself. - \var{callback} may also be \code{None} or \NULL{}. If \var{ob} is not - a weakly-referencable object, or if \var{callback} is not callable, - \code{None}, or \NULL{}, this will return \NULL{} and raise - \exception{TypeError}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyWeakref_GetObject}{PyObject *ref} - Return the referenced object from a weak reference, \var{ref}. If - the referent is no longer live, returns \code{None}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyWeakref_GET_OBJECT}{PyObject *ref} - Similar to \cfunction{PyWeakref_GetObject()}, but implemented as a - macro that does no error checking. - \versionadded{2.2} -\end{cfuncdesc} - - -\subsection{CObjects \label{cObjects}} - -\obindex{CObject} -Refer to \emph{Extending and Embedding the Python Interpreter}, -section~1.12, ``Providing a C API for an Extension Module,'' for more -information on using these objects. - - -\begin{ctypedesc}{PyCObject} - This subtype of \ctype{PyObject} represents an opaque value, useful - for C extension modules who need to pass an opaque value (as a - \ctype{void*} pointer) through Python code to other C code. It is - often used to make a C function pointer defined in one module - available to other modules, so the regular import mechanism can be - used to access C APIs defined in dynamically loaded modules. -\end{ctypedesc} - -\begin{cfuncdesc}{int}{PyCObject_Check}{PyObject *p} - Return true if its argument is a \ctype{PyCObject}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj, - void (*destr)(void *)} - Create a \ctype{PyCObject} from the \code{void *}\var{cobj}. The - \var{destr} function will be called when the object is reclaimed, - unless it is \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj, - void* desc, void (*destr)(void *, void *)} - Create a \ctype{PyCObject} from the \ctype{void *}\var{cobj}. The - \var{destr} function will be called when the object is reclaimed. - The \var{desc} argument can be used to pass extra callback data for - the destructor function. -\end{cfuncdesc} - -\begin{cfuncdesc}{void*}{PyCObject_AsVoidPtr}{PyObject* self} - Return the object \ctype{void *} that the \ctype{PyCObject} - \var{self} was created with. -\end{cfuncdesc} - -\begin{cfuncdesc}{void*}{PyCObject_GetDesc}{PyObject* self} - Return the description \ctype{void *} that the \ctype{PyCObject} - \var{self} was created with. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyCObject_SetVoidPtr}{PyObject* self, void* cobj} - Set the void pointer inside \var{self} to \var{cobj}. - The \ctype{PyCObject} must not have an associated destructor. - Return true on success, false on failure. -\end{cfuncdesc} - - -\subsection{Cell Objects \label{cell-objects}} - -``Cell'' objects are used to implement variables referenced by -multiple scopes. For each such variable, a cell object is created to -store the value; the local variables of each stack frame that -references the value contains a reference to the cells from outer -scopes which also use that variable. When the value is accessed, the -value contained in the cell is used instead of the cell object -itself. This de-referencing of the cell object requires support from -the generated byte-code; these are not automatically de-referenced -when accessed. Cell objects are not likely to be useful elsewhere. - -\begin{ctypedesc}{PyCellObject} - The C structure used for cell objects. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyCell_Type} - The type object corresponding to cell objects. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyCell_Check}{ob} - Return true if \var{ob} is a cell object; \var{ob} must not be - \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyCell_New}{PyObject *ob} - Create and return a new cell object containing the value \var{ob}. - The parameter may be \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyCell_Get}{PyObject *cell} - Return the contents of the cell \var{cell}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyCell_GET}{PyObject *cell} - Return the contents of the cell \var{cell}, but without checking - that \var{cell} is non-\NULL{} and a cell object. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyCell_Set}{PyObject *cell, PyObject *value} - Set the contents of the cell object \var{cell} to \var{value}. This - releases the reference to any current content of the cell. - \var{value} may be \NULL{}. \var{cell} must be non-\NULL{}; if it is - not a cell object, \code{-1} will be returned. On success, \code{0} - will be returned. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyCell_SET}{PyObject *cell, PyObject *value} - Sets the value of the cell object \var{cell} to \var{value}. No - reference counts are adjusted, and no checks are made for safety; - \var{cell} must be non-\NULL{} and must be a cell object. -\end{cfuncdesc} - - -\subsection{Generator Objects \label{gen-objects}} - -Generator objects are what Python uses to implement generator iterators. -They are normally created by iterating over a function that yields values, -rather than explicitly calling \cfunction{PyGen_New}. - -\begin{ctypedesc}{PyGenObject} - The C structure used for generator objects. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyGen_Type} - The type object corresponding to generator objects -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyGen_Check}{ob} - Return true if \var{ob} is a generator object; \var{ob} must not be - \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyGen_CheckExact}{ob} - Return true if \var{ob}'s type is \var{PyGen_Type} - is a generator object; \var{ob} must not be - \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyGen_New}{PyFrameObject *frame} - Create and return a new generator object based on the \var{frame} object. - A reference to \var{frame} is stolen by this function. - The parameter must not be \NULL{}. -\end{cfuncdesc} - - -\subsection{DateTime Objects \label{datetime-objects}} - -Various date and time objects are supplied by the \module{datetime} -module. Before using any of these functions, the header file -\file{datetime.h} must be included in your source (note that this is -not included by \file{Python.h}), and the macro -\cfunction{PyDateTime_IMPORT} must be invoked. The macro puts a -pointer to a C structure into a static variable, -\code{PyDateTimeAPI}, that is used by the following macros. - -Type-check macros: - -\begin{cfuncdesc}{int}{PyDate_Check}{PyObject *ob} - Return true if \var{ob} is of type \cdata{PyDateTime_DateType} or - a subtype of \cdata{PyDateTime_DateType}. \var{ob} must not be - \NULL{}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDate_CheckExact}{PyObject *ob} - Return true if \var{ob} is of type \cdata{PyDateTime_DateType}. - \var{ob} must not be \NULL{}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDateTime_Check}{PyObject *ob} - Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType} or - a subtype of \cdata{PyDateTime_DateTimeType}. \var{ob} must not be - \NULL{}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDateTime_CheckExact}{PyObject *ob} - Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType}. - \var{ob} must not be \NULL{}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTime_Check}{PyObject *ob} - Return true if \var{ob} is of type \cdata{PyDateTime_TimeType} or - a subtype of \cdata{PyDateTime_TimeType}. \var{ob} must not be - \NULL{}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTime_CheckExact}{PyObject *ob} - Return true if \var{ob} is of type \cdata{PyDateTime_TimeType}. - \var{ob} must not be \NULL{}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDelta_Check}{PyObject *ob} - Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType} or - a subtype of \cdata{PyDateTime_DeltaType}. \var{ob} must not be - \NULL{}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDelta_CheckExact}{PyObject *ob} - Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType}. - \var{ob} must not be \NULL{}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTZInfo_Check}{PyObject *ob} - Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType} or - a subtype of \cdata{PyDateTime_TZInfoType}. \var{ob} must not be - \NULL{}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTZInfo_CheckExact}{PyObject *ob} - Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType}. - \var{ob} must not be \NULL{}. - \versionadded{2.4} -\end{cfuncdesc} - -Macros to create objects: - -\begin{cfuncdesc}{PyObject*}{PyDate_FromDate}{int year, int month, int day} - Return a \code{datetime.date} object with the specified year, month - and day. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDateTime_FromDateAndTime}{int year, int month, - int day, int hour, int minute, int second, int usecond} - Return a \code{datetime.datetime} object with the specified year, month, - day, hour, minute, second and microsecond. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyTime_FromTime}{int hour, int minute, - int second, int usecond} - Return a \code{datetime.time} object with the specified hour, minute, - second and microsecond. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDelta_FromDSU}{int days, int seconds, - int useconds} - Return a \code{datetime.timedelta} object representing the given number - of days, seconds and microseconds. Normalization is performed so that - the resulting number of microseconds and seconds lie in the ranges - documented for \code{datetime.timedelta} objects. - \versionadded{2.4} -\end{cfuncdesc} - -Macros to extract fields from date objects. The argument must be an -instance of \cdata{PyDateTime_Date}, including subclasses (such as -\cdata{PyDateTime_DateTime}). The argument must not be \NULL{}, and -the type is not checked: - -\begin{cfuncdesc}{int}{PyDateTime_GET_YEAR}{PyDateTime_Date *o} - Return the year, as a positive int. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDateTime_GET_MONTH}{PyDateTime_Date *o} - Return the month, as an int from 1 through 12. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDateTime_GET_DAY}{PyDateTime_Date *o} - Return the day, as an int from 1 through 31. - \versionadded{2.4} -\end{cfuncdesc} - -Macros to extract fields from datetime objects. The argument must be an -instance of \cdata{PyDateTime_DateTime}, including subclasses. -The argument must not be \NULL{}, and the type is not checked: - -\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_HOUR}{PyDateTime_DateTime *o} - Return the hour, as an int from 0 through 23. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MINUTE}{PyDateTime_DateTime *o} - Return the minute, as an int from 0 through 59. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_SECOND}{PyDateTime_DateTime *o} - Return the second, as an int from 0 through 59. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MICROSECOND}{PyDateTime_DateTime *o} - Return the microsecond, as an int from 0 through 999999. - \versionadded{2.4} -\end{cfuncdesc} - -Macros to extract fields from time objects. The argument must be an -instance of \cdata{PyDateTime_Time}, including subclasses. -The argument must not be \NULL{}, and the type is not checked: - -\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_HOUR}{PyDateTime_Time *o} - Return the hour, as an int from 0 through 23. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MINUTE}{PyDateTime_Time *o} - Return the minute, as an int from 0 through 59. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_SECOND}{PyDateTime_Time *o} - Return the second, as an int from 0 through 59. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MICROSECOND}{PyDateTime_Time *o} - Return the microsecond, as an int from 0 through 999999. - \versionadded{2.4} -\end{cfuncdesc} - -Macros for the convenience of modules implementing the DB API: - -\begin{cfuncdesc}{PyObject*}{PyDateTime_FromTimestamp}{PyObject *args} - Create and return a new \code{datetime.datetime} object given an argument - tuple suitable for passing to \code{datetime.datetime.fromtimestamp()}. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDate_FromTimestamp}{PyObject *args} - Create and return a new \code{datetime.date} object given an argument - tuple suitable for passing to \code{datetime.date.fromtimestamp()}. - \versionadded{2.4} -\end{cfuncdesc} - - -\subsection{Set Objects \label{setObjects}} -\sectionauthor{Raymond D. Hettinger}{python@rcn.com} - -\obindex{set} -\obindex{frozenset} -\versionadded{2.5} - -This section details the public API for \class{set} and \class{frozenset} -objects. Any functionality not listed below is best accessed using the -either the abstract object protocol (including -\cfunction{PyObject_CallMethod()}, \cfunction{PyObject_RichCompareBool()}, -\cfunction{PyObject_Hash()}, \cfunction{PyObject_Repr()}, -\cfunction{PyObject_IsTrue()}, \cfunction{PyObject_Print()}, and -\cfunction{PyObject_GetIter()}) -or the abstract number protocol (including -\cfunction{PyNumber_And()}, \cfunction{PyNumber_Subtract()}, -\cfunction{PyNumber_Or()}, \cfunction{PyNumber_Xor()}, -\cfunction{PyNumber_InPlaceAnd()}, \cfunction{PyNumber_InPlaceSubtract()}, -\cfunction{PyNumber_InPlaceOr()}, and \cfunction{PyNumber_InPlaceXor()}). - -\begin{ctypedesc}{PySetObject} - This subtype of \ctype{PyObject} is used to hold the internal data for - both \class{set} and \class{frozenset} objects. It is like a - \ctype{PyDictObject} in that it is a fixed size for small sets - (much like tuple storage) and will point to a separate, variable sized - block of memory for medium and large sized sets (much like list storage). - None of the fields of this structure should be considered public and - are subject to change. All access should be done through the - documented API rather than by manipulating the values in the structure. - -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PySet_Type} - This is an instance of \ctype{PyTypeObject} representing the Python - \class{set} type. -\end{cvardesc} - -\begin{cvardesc}{PyTypeObject}{PyFrozenSet_Type} - This is an instance of \ctype{PyTypeObject} representing the Python - \class{frozenset} type. -\end{cvardesc} - - -The following type check macros work on pointers to any Python object. -Likewise, the constructor functions work with any iterable Python object. - -\begin{cfuncdesc}{int}{PyAnySet_Check}{PyObject *p} - Return true if \var{p} is a \class{set} object, a \class{frozenset} - object, or an instance of a subtype. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyAnySet_CheckExact}{PyObject *p} - Return true if \var{p} is a \class{set} object or a \class{frozenset} - object but not an instance of a subtype. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFrozenSet_CheckExact}{PyObject *p} - Return true if \var{p} is a \class{frozenset} object - but not an instance of a subtype. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySet_New}{PyObject *iterable} - Return a new \class{set} containing objects returned by the - \var{iterable}. The \var{iterable} may be \NULL{} to create a - new empty set. Return the new set on success or \NULL{} on - failure. Raise \exception{TypeError} if \var{iterable} is - not actually iterable. The constructor is also useful for - copying a set (\code{c=set(s)}). -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFrozenSet_New}{PyObject *iterable} - Return a new \class{frozenset} containing objects returned by the - \var{iterable}. The \var{iterable} may be \NULL{} to create a - new empty frozenset. Return the new set on success or \NULL{} on - failure. Raise \exception{TypeError} if \var{iterable} is - not actually iterable. -\end{cfuncdesc} - - -The following functions and macros are available for instances of -\class{set} or \class{frozenset} or instances of their subtypes. - -\begin{cfuncdesc}{int}{PySet_Size}{PyObject *anyset} - Return the length of a \class{set} or \class{frozenset} object. - Equivalent to \samp{len(\var{anyset})}. Raises a - \exception{PyExc_SystemError} if \var{anyset} is not a \class{set}, - \class{frozenset}, or an instance of a subtype. - \bifuncindex{len} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySet_GET_SIZE}{PyObject *anyset} - Macro form of \cfunction{PySet_Size()} without error checking. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySet_Contains}{PyObject *anyset, PyObject *key} - Return 1 if found, 0 if not found, and -1 if an error is - encountered. Unlike the Python \method{__contains__()} method, this - function does not automatically convert unhashable sets into temporary - frozensets. Raise a \exception{TypeError} if the \var{key} is unhashable. - Raise \exception{PyExc_SystemError} if \var{anyset} is not a \class{set}, - \class{frozenset}, or an instance of a subtype. -\end{cfuncdesc} - -The following functions are available for instances of \class{set} or -its subtypes but not for instances of \class{frozenset} or its subtypes. - -\begin{cfuncdesc}{int}{PySet_Add}{PyObject *set, PyObject *key} - Add \var{key} to a \class{set} instance. Does not apply to - \class{frozenset} instances. Return 0 on success or -1 on failure. - Raise a \exception{TypeError} if the \var{key} is unhashable. - Raise a \exception{MemoryError} if there is no room to grow. - Raise a \exception{SystemError} if \var{set} is an not an instance - of \class{set} or its subtype. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySet_Discard}{PyObject *set, PyObject *key} - Return 1 if found and removed, 0 if not found (no action taken), - and -1 if an error is encountered. Does not raise \exception{KeyError} - for missing keys. Raise a \exception{TypeError} if the \var{key} is - unhashable. Unlike the Python \method{discard()} method, this function - does not automatically convert unhashable sets into temporary frozensets. - Raise \exception{PyExc_SystemError} if \var{set} is an not an instance - of \class{set} or its subtype. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySet_Pop}{PyObject *set} - Return a new reference to an arbitrary object in the \var{set}, - and removes the object from the \var{set}. Return \NULL{} on - failure. Raise \exception{KeyError} if the set is empty. - Raise a \exception{SystemError} if \var{set} is an not an instance - of \class{set} or its subtype. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySet_Clear}{PyObject *set} - Empty an existing set of all elements. -\end{cfuncdesc} |