\chapter{Concrete Objects Layer \label{concrete}}  The functions in this chapter are specific to certain Python objecttypes.  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 surethat 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 checkthe type of the objects which are passed in, many of them do not checkfor \NULL{} being passed instead of a valid object.  Allowing \NULL{}to be passed in can cause memory access violations and immediatetermination 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 directlyexposed 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.\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.  Thereare only two booleans, \constant{Py_False} and \constant{Py_True}.  Assuch, the normal creation and deletion functions don't apply tobooleans.  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, char **pend}  Create a \ctype{PyFloatObject} object based on the string value in  \var{str}, or \NULL{} on failure.  The \var{pend} argument is ignored.  It  remains only for backward compatibility.\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}.\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 typeswhen viewed from the C API:  one is the Python object exposed toPython programs, and the other is a C structure which represents theactual complex number value.  The API provides functions for workingwith both. \subsubsection{Complex Numbers as C Structures} Note that the functions which accept these structures as parametersand return them as results do so \emph{by value} rather thandereferencing them through pointers.  This is consistent throughoutthe 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}

Lines 1–500 of 3203. Load more