blob: 10247ab750d89b70121692920b07401f92d10ed1 [file] [log] [blame]
Fred Drake3adf79e2001-10-12 19:01:43 +00001\chapter{Concrete Objects Layer \label{concrete}}
2
3
4The functions in this chapter are specific to certain Python object
5types. Passing them an object of the wrong type is not a good idea;
6if you receive an object from a Python program and you are not sure
7that it has the right type, you must perform a type check first;
8for example, to check that an object is a dictionary, use
9\cfunction{PyDict_Check()}. The chapter is structured like the
10``family tree'' of Python object types.
11
12\warning{While the functions described in this chapter carefully check
13the type of the objects which are passed in, many of them do not check
14for \NULL{} being passed instead of a valid object. Allowing \NULL{}
15to be passed in can cause memory access violations and immediate
16termination of the interpreter.}
17
18
19\section{Fundamental Objects \label{fundamental}}
20
Tim Petersf582b822001-12-11 18:51:08 +000021This section describes Python type objects and the singleton object
Fred Drake3adf79e2001-10-12 19:01:43 +000022\code{None}.
23
24
25\subsection{Type Objects \label{typeObjects}}
26
27\obindex{type}
28\begin{ctypedesc}{PyTypeObject}
29 The C structure of the objects used to describe built-in types.
30\end{ctypedesc}
31
32\begin{cvardesc}{PyObject*}{PyType_Type}
33 This is the type object for type objects; it is the same object as
34 \code{types.TypeType} in the Python layer.
35 \withsubitem{(in module types)}{\ttindex{TypeType}}
36\end{cvardesc}
37
38\begin{cfuncdesc}{int}{PyType_Check}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +000039 Return true if the object \var{o} is a type object, including
40 instances of types derived from the standard type object. Return
Fred Drakee3c764b2002-04-10 17:52:52 +000041 false in all other cases.
42\end{cfuncdesc}
43
44\begin{cfuncdesc}{int}{PyType_CheckExact}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +000045 Return true if the object \var{o} is a type object, but not a
46 subtype of the standard type object. Return false in all other
Fred Drakee3c764b2002-04-10 17:52:52 +000047 cases.
48 \versionadded{2.2}
Fred Drake3adf79e2001-10-12 19:01:43 +000049\end{cfuncdesc}
50
51\begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature}
Georg Brandl99363b62005-09-03 07:27:26 +000052 Return true if the type object \var{o} sets the feature
Fred Drake3adf79e2001-10-12 19:01:43 +000053 \var{feature}. Type features are denoted by single bit flags.
54\end{cfuncdesc}
55
Fred Drakee3c764b2002-04-10 17:52:52 +000056\begin{cfuncdesc}{int}{PyType_IS_GC}{PyObject *o}
57 Return true if the type object includes support for the cycle
58 detector; this tests the type flag \constant{Py_TPFLAGS_HAVE_GC}.
59 \versionadded{2.0}
60\end{cfuncdesc}
61
Fred Drake3adf79e2001-10-12 19:01:43 +000062\begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b}
Georg Brandl99363b62005-09-03 07:27:26 +000063 Return true if \var{a} is a subtype of \var{b}.
Fred Drake3adf79e2001-10-12 19:01:43 +000064 \versionadded{2.2}
65\end{cfuncdesc}
66
67\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type,
Martin v. Löwis29fafd82006-03-01 05:16:03 +000068 Py_ssize_t nitems}
Fred Drake3adf79e2001-10-12 19:01:43 +000069 \versionadded{2.2}
70\end{cfuncdesc}
71
72\begin{cfuncdesc}{PyObject*}{PyType_GenericNew}{PyTypeObject *type,
73 PyObject *args, PyObject *kwds}
74 \versionadded{2.2}
75\end{cfuncdesc}
76
77\begin{cfuncdesc}{int}{PyType_Ready}{PyTypeObject *type}
Fred Drake28de8d42002-04-12 16:15:10 +000078 Finalize a type object. This should be called on all type objects
79 to finish their initialization. This function is responsible for
Georg Brandl99363b62005-09-03 07:27:26 +000080 adding inherited slots from a type's base class. Return \code{0}
81 on success, or return \code{-1} and sets an exception on error.
Fred Drake3adf79e2001-10-12 19:01:43 +000082 \versionadded{2.2}
83\end{cfuncdesc}
84
85
86\subsection{The None Object \label{noneObject}}
87
Fred Drake7a700b82004-01-01 05:43:53 +000088\obindex{None}
Fred Drake3adf79e2001-10-12 19:01:43 +000089Note that the \ctype{PyTypeObject} for \code{None} is not directly
90exposed in the Python/C API. Since \code{None} is a singleton,
91testing for object identity (using \samp{==} in C) is sufficient.
92There is no \cfunction{PyNone_Check()} function for the same reason.
93
94\begin{cvardesc}{PyObject*}{Py_None}
95 The Python \code{None} object, denoting lack of value. This object
Fred Drake6ccdccd2002-03-12 20:12:54 +000096 has no methods. It needs to be treated just like any other object
97 with respect to reference counts.
Fred Drake3adf79e2001-10-12 19:01:43 +000098\end{cvardesc}
99
Brett Cannon35d83602003-11-09 04:15:30 +0000100\begin{csimplemacrodesc}{Py_RETURN_NONE}
Georg Brandl99363b62005-09-03 07:27:26 +0000101 Properly handle returning \cdata{Py_None} from within a C function.
Brett Cannon35d83602003-11-09 04:15:30 +0000102\end{csimplemacrodesc}
103
Fred Drake3adf79e2001-10-12 19:01:43 +0000104
105\section{Numeric Objects \label{numericObjects}}
106
107\obindex{numeric}
108
109
110\subsection{Plain Integer Objects \label{intObjects}}
111
112\obindex{integer}
113\begin{ctypedesc}{PyIntObject}
114 This subtype of \ctype{PyObject} represents a Python integer
115 object.
116\end{ctypedesc}
117
118\begin{cvardesc}{PyTypeObject}{PyInt_Type}
Tim Petersf582b822001-12-11 18:51:08 +0000119 This instance of \ctype{PyTypeObject} represents the Python plain
Fred Drake3adf79e2001-10-12 19:01:43 +0000120 integer type. This is the same object as \code{types.IntType}.
121 \withsubitem{(in modules types)}{\ttindex{IntType}}
122\end{cvardesc}
123
Andrew M. Kuchling4eb1a002004-08-07 20:19:24 +0000124\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +0000125 Return true if \var{o} is of type \cdata{PyInt_Type} or a subtype
Fred Drake3adf79e2001-10-12 19:01:43 +0000126 of \cdata{PyInt_Type}.
127 \versionchanged[Allowed subtypes to be accepted]{2.2}
128\end{cfuncdesc}
129
Andrew M. Kuchling4eb1a002004-08-07 20:19:24 +0000130\begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +0000131 Return true if \var{o} is of type \cdata{PyInt_Type}, but not a
Fred Drake3adf79e2001-10-12 19:01:43 +0000132 subtype of \cdata{PyInt_Type}.
133 \versionadded{2.2}
134\end{cfuncdesc}
135
Skip Montanaro1ff49a72003-02-03 05:13:24 +0000136\begin{cfuncdesc}{PyObject*}{PyInt_FromString}{char *str, char **pend,
137 int base}
138 Return a new \ctype{PyIntObject} or \ctype{PyLongObject} based on the
139 string value in \var{str}, which is interpreted according to the radix in
Tim Peters9ddf40b2004-06-20 22:41:32 +0000140 \var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will point to
Skip Montanaro1ff49a72003-02-03 05:13:24 +0000141 the first character in \var{str} which follows the representation of the
142 number. If \var{base} is \code{0}, the radix will be determined based on
143 the leading characters of \var{str}: if \var{str} starts with \code{'0x'}
144 or \code{'0X'}, radix 16 will be used; if \var{str} starts with
145 \code{'0'}, radix 8 will be used; otherwise radix 10 will be used. If
146 \var{base} is not \code{0}, it must be between \code{2} and \code{36},
147 inclusive. Leading spaces are ignored. If there are no digits,
148 \exception{ValueError} will be raised. If the string represents a number
149 too large to be contained within the machine's \ctype{long int} type and
150 overflow warnings are being suppressed, a \ctype{PyLongObject} will be
151 returned. If overflow warnings are not being suppressed, \NULL{} will be
152 returned in this case.
153\end{cfuncdesc}
154
Fred Drake3adf79e2001-10-12 19:01:43 +0000155\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
Georg Brandl99363b62005-09-03 07:27:26 +0000156 Create a new integer object with a value of \var{ival}.
Fred Drake3adf79e2001-10-12 19:01:43 +0000157
158 The current implementation keeps an array of integer objects for all
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000159 integers between \code{-5} and \code{256}, when you create an int in
Fred Drake3adf79e2001-10-12 19:01:43 +0000160 that range you actually just get back a reference to the existing
161 object. So it should be possible to change the value of \code{1}. I
162 suspect the behaviour of Python in this case is undefined. :-)
163\end{cfuncdesc}
164
Martin v. Löwis3b197542006-03-01 05:47:11 +0000165\begin{cfuncdesc}{PyObject*}{PyInt_FromSsize_t}{Py_ssize_t ival}
166 Create a new integer object with a value of \var{ival}.
167 If the value exceeds \code{LONG_MAX}, a long integer object is
168 returned.
169
170 \versionadded{2.5}
171\end{cfuncdesc}
172
Fred Drake3adf79e2001-10-12 19:01:43 +0000173\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
174 Will first attempt to cast the object to a \ctype{PyIntObject}, if
Martin v. Löwis3b197542006-03-01 05:47:11 +0000175 it is not already one, and then return its value. If there is an
176 error, \code{-1} is returned, and the caller should check
177 \code{PyErr_Occurred()} to find out whether there was an error, or
178 whether the value just happened to be -1.
Fred Drake3adf79e2001-10-12 19:01:43 +0000179\end{cfuncdesc}
180
181\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
Georg Brandl99363b62005-09-03 07:27:26 +0000182 Return the value of the object \var{io}. No error checking is
Fred Drake3adf79e2001-10-12 19:01:43 +0000183 performed.
184\end{cfuncdesc}
185
Thomas Heller34d7f092003-04-23 19:51:05 +0000186\begin{cfuncdesc}{unsigned long}{PyInt_AsUnsignedLongMask}{PyObject *io}
187 Will first attempt to cast the object to a \ctype{PyIntObject} or
Fred Drakec22b2992003-04-23 20:38:41 +0000188 \ctype{PyLongObject}, if it is not already one, and then return its
Thomas Heller34d7f092003-04-23 19:51:05 +0000189 value as unsigned long. This function does not check for overflow.
190 \versionadded{2.3}
191\end{cfuncdesc}
192
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000193\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyInt_AsUnsignedLongLongMask}{PyObject *io}
Thomas Heller34d7f092003-04-23 19:51:05 +0000194 Will first attempt to cast the object to a \ctype{PyIntObject} or
Fred Drakec22b2992003-04-23 20:38:41 +0000195 \ctype{PyLongObject}, if it is not already one, and then return its
Thomas Heller34d7f092003-04-23 19:51:05 +0000196 value as unsigned long long, without checking for overflow.
197 \versionadded{2.3}
198\end{cfuncdesc}
199
Martin v. Löwis3b197542006-03-01 05:47:11 +0000200\begin{cfuncdesc}{Py_ssize_t}{PyInt_AsSsize_t}{PyObject *io}
201 Will first attempt to cast the object to a \ctype{PyIntObject} or
202 \ctype{PyLongObject}, if it is not already one, and then return its
203 value as \ctype{Py_ssize_t}.
204 \versionadded{2.5}
205\end{cfuncdesc}
206
Fred Drake3adf79e2001-10-12 19:01:43 +0000207\begin{cfuncdesc}{long}{PyInt_GetMax}{}
Georg Brandl99363b62005-09-03 07:27:26 +0000208 Return the system's idea of the largest integer it can handle
Fred Drake3adf79e2001-10-12 19:01:43 +0000209 (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system
210 header files).
211\end{cfuncdesc}
212
Fred Drake2be406b2004-08-03 16:02:35 +0000213\subsection{Boolean Objects \label{boolObjects}}
Skip Montanaro33ee76a2004-07-28 14:17:04 +0000214
215Booleans in Python are implemented as a subclass of integers. There
216are only two booleans, \constant{Py_False} and \constant{Py_True}. As
217such, the normal creation and deletion functions don't apply to
218booleans. The following macros are available, however.
219
Andrew M. Kuchling4eb1a002004-08-07 20:19:24 +0000220\begin{cfuncdesc}{int}{PyBool_Check}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +0000221 Return true if \var{o} is of type \cdata{PyBool_Type}.
Skip Montanaro33ee76a2004-07-28 14:17:04 +0000222 \versionadded{2.3}
223\end{cfuncdesc}
224
Skip Montanaro6d3db702004-07-29 02:16:04 +0000225\begin{cvardesc}{PyObject*}{Py_False}
226 The Python \code{False} object. This object has no methods. It needs to
227 be treated just like any other object with respect to reference counts.
228\end{cvardesc}
Skip Montanaro33ee76a2004-07-28 14:17:04 +0000229
Skip Montanaro6d3db702004-07-29 02:16:04 +0000230\begin{cvardesc}{PyObject*}{Py_True}
231 The Python \code{True} object. This object has no methods. It needs to
232 be treated just like any other object with respect to reference counts.
233\end{cvardesc}
234
235\begin{csimplemacrodesc}{Py_RETURN_FALSE}
236 Return \constant{Py_False} from a function, properly incrementing its
237 reference count.
238\versionadded{2.4}
239\end{csimplemacrodesc}
240
241\begin{csimplemacrodesc}{Py_RETURN_TRUE}
Andrew M. Kuchling4eb1a002004-08-07 20:19:24 +0000242 Return \constant{Py_True} from a function, properly incrementing its
243 reference count.
Skip Montanaro33ee76a2004-07-28 14:17:04 +0000244\versionadded{2.4}
Skip Montanaro6d3db702004-07-29 02:16:04 +0000245\end{csimplemacrodesc}
Skip Montanaro33ee76a2004-07-28 14:17:04 +0000246
Georg Brandl99363b62005-09-03 07:27:26 +0000247\begin{cfuncdesc}{PyObject*}{PyBool_FromLong}{long v}
Thomas Wouters477c8d52006-05-27 19:21:47 +0000248 Return a new reference to \constant{Py_True} or \constant{Py_False}
Georg Brandl99363b62005-09-03 07:27:26 +0000249 depending on the truth value of \var{v}.
Skip Montanaro33ee76a2004-07-28 14:17:04 +0000250\versionadded{2.3}
251\end{cfuncdesc}
Fred Drake3adf79e2001-10-12 19:01:43 +0000252
253\subsection{Long Integer Objects \label{longObjects}}
254
255\obindex{long integer}
256\begin{ctypedesc}{PyLongObject}
257 This subtype of \ctype{PyObject} represents a Python long integer
258 object.
259\end{ctypedesc}
260
261\begin{cvardesc}{PyTypeObject}{PyLong_Type}
262 This instance of \ctype{PyTypeObject} represents the Python long
263 integer type. This is the same object as \code{types.LongType}.
264 \withsubitem{(in modules types)}{\ttindex{LongType}}
265\end{cvardesc}
266
267\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +0000268 Return true if its argument is a \ctype{PyLongObject} or a subtype
Fred Drake3adf79e2001-10-12 19:01:43 +0000269 of \ctype{PyLongObject}.
270 \versionchanged[Allowed subtypes to be accepted]{2.2}
271\end{cfuncdesc}
272
273\begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +0000274 Return true if its argument is a \ctype{PyLongObject}, but not a
Fred Drake3adf79e2001-10-12 19:01:43 +0000275 subtype of \ctype{PyLongObject}.
276 \versionadded{2.2}
277\end{cfuncdesc}
278
279\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
Georg Brandl99363b62005-09-03 07:27:26 +0000280 Return a new \ctype{PyLongObject} object from \var{v}, or \NULL{}
Fred Drake3adf79e2001-10-12 19:01:43 +0000281 on failure.
282\end{cfuncdesc}
283
284\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
Georg Brandl99363b62005-09-03 07:27:26 +0000285 Return a new \ctype{PyLongObject} object from a C \ctype{unsigned
Fred Drake3adf79e2001-10-12 19:01:43 +0000286 long}, or \NULL{} on failure.
287\end{cfuncdesc}
288
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000289\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{PY_LONG_LONG v}
Georg Brandl99363b62005-09-03 07:27:26 +0000290 Return a new \ctype{PyLongObject} object from a C \ctype{long long},
Fred Drake3adf79e2001-10-12 19:01:43 +0000291 or \NULL{} on failure.
292\end{cfuncdesc}
293
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000294\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned PY_LONG_LONG v}
Georg Brandl99363b62005-09-03 07:27:26 +0000295 Return a new \ctype{PyLongObject} object from a C \ctype{unsigned
Fred Drake3adf79e2001-10-12 19:01:43 +0000296 long long}, or \NULL{} on failure.
297\end{cfuncdesc}
298
299\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
Georg Brandl99363b62005-09-03 07:27:26 +0000300 Return a new \ctype{PyLongObject} object from the integer part of
Fred Drake3adf79e2001-10-12 19:01:43 +0000301 \var{v}, or \NULL{} on failure.
302\end{cfuncdesc}
303
304\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
305 int base}
306 Return a new \ctype{PyLongObject} based on the string value in
307 \var{str}, which is interpreted according to the radix in
Tim Peters9ddf40b2004-06-20 22:41:32 +0000308 \var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will
Fred Drake3adf79e2001-10-12 19:01:43 +0000309 point to the first character in \var{str} which follows the
310 representation of the number. If \var{base} is \code{0}, the radix
Skip Montanaro1ff49a72003-02-03 05:13:24 +0000311 will be determined based on the leading characters of \var{str}: if
Fred Drake3adf79e2001-10-12 19:01:43 +0000312 \var{str} starts with \code{'0x'} or \code{'0X'}, radix 16 will be
313 used; if \var{str} starts with \code{'0'}, radix 8 will be used;
314 otherwise radix 10 will be used. If \var{base} is not \code{0}, it
315 must be between \code{2} and \code{36}, inclusive. Leading spaces
316 are ignored. If there are no digits, \exception{ValueError} will be
317 raised.
318\end{cfuncdesc}
319
320\begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u,
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000321 Py_ssize_t length, int base}
Fred Drake3adf79e2001-10-12 19:01:43 +0000322 Convert a sequence of Unicode digits to a Python long integer
323 value. The first parameter, \var{u}, points to the first character
324 of the Unicode string, \var{length} gives the number of characters,
325 and \var{base} is the radix for the conversion. The radix must be
326 in the range [2, 36]; if it is out of range, \exception{ValueError}
327 will be raised.
328 \versionadded{1.6}
329\end{cfuncdesc}
330
331\begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p}
332 Create a Python integer or long integer from the pointer \var{p}.
333 The pointer value can be retrieved from the resulting value using
334 \cfunction{PyLong_AsVoidPtr()}.
335 \versionadded{1.5.2}
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000336 \versionchanged[If the integer is larger than LONG_MAX,
337 a positive long integer is returned]{2.5}
338 \end{cfuncdesc}
Fred Drake3adf79e2001-10-12 19:01:43 +0000339
340\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
Georg Brandl99363b62005-09-03 07:27:26 +0000341 Return a C \ctype{long} representation of the contents of
Fred Drake3adf79e2001-10-12 19:01:43 +0000342 \var{pylong}. If \var{pylong} is greater than
343 \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError}
344 is raised.
345 \withsubitem{(built-in exception)}{\ttindex{OverflowError}}
346\end{cfuncdesc}
347
348\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
Georg Brandl99363b62005-09-03 07:27:26 +0000349 Return a C \ctype{unsigned long} representation of the contents of
Fred Drake3adf79e2001-10-12 19:01:43 +0000350 \var{pylong}. If \var{pylong} is greater than
351 \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an
352 \exception{OverflowError} is raised.
Tim Petersf582b822001-12-11 18:51:08 +0000353 \withsubitem{(built-in exception)}{\ttindex{OverflowError}}
Fred Drake3adf79e2001-10-12 19:01:43 +0000354\end{cfuncdesc}
355
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000356\begin{cfuncdesc}{PY_LONG_LONG}{PyLong_AsLongLong}{PyObject *pylong}
Fred Drake3adf79e2001-10-12 19:01:43 +0000357 Return a C \ctype{long long} from a Python long integer. If
358 \var{pylong} cannot be represented as a \ctype{long long}, an
359 \exception{OverflowError} will be raised.
360 \versionadded{2.2}
361\end{cfuncdesc}
362
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000363\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyLong_AsUnsignedLongLong}{PyObject
Fred Drake3adf79e2001-10-12 19:01:43 +0000364 *pylong}
365 Return a C \ctype{unsigned long long} from a Python long integer.
366 If \var{pylong} cannot be represented as an \ctype{unsigned long
367 long}, an \exception{OverflowError} will be raised if the value is
368 positive, or a \exception{TypeError} will be raised if the value is
369 negative.
370 \versionadded{2.2}
371\end{cfuncdesc}
372
Thomas Heller34d7f092003-04-23 19:51:05 +0000373\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLongMask}{PyObject *io}
374 Return a C \ctype{unsigned long} from a Python long integer, without
375 checking for overflow.
376 \versionadded{2.3}
377\end{cfuncdesc}
378
379\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLongLongMask}{PyObject *io}
380 Return a C \ctype{unsigned long long} from a Python long integer, without
381 checking for overflow.
382 \versionadded{2.3}
383\end{cfuncdesc}
384
Fred Drake3adf79e2001-10-12 19:01:43 +0000385\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
Georg Brandl99363b62005-09-03 07:27:26 +0000386 Return a C \ctype{double} representation of the contents of
Fred Drake3adf79e2001-10-12 19:01:43 +0000387 \var{pylong}. If \var{pylong} cannot be approximately represented
388 as a \ctype{double}, an \exception{OverflowError} exception is
389 raised and \code{-1.0} will be returned.
390\end{cfuncdesc}
391
392\begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong}
393 Convert a Python integer or long integer \var{pylong} to a C
394 \ctype{void} pointer. If \var{pylong} cannot be converted, an
395 \exception{OverflowError} will be raised. This is only assured to
396 produce a usable \ctype{void} pointer for values created with
397 \cfunction{PyLong_FromVoidPtr()}.
398 \versionadded{1.5.2}
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000399 \versionchanged[For values outside 0..LONG_MAX, both signed and
400 unsigned integers are acccepted]{2.5}
Fred Drake3adf79e2001-10-12 19:01:43 +0000401\end{cfuncdesc}
402
403
404\subsection{Floating Point Objects \label{floatObjects}}
405
406\obindex{floating point}
407\begin{ctypedesc}{PyFloatObject}
408 This subtype of \ctype{PyObject} represents a Python floating point
409 object.
410\end{ctypedesc}
411
412\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
413 This instance of \ctype{PyTypeObject} represents the Python floating
414 point type. This is the same object as \code{types.FloatType}.
415 \withsubitem{(in modules types)}{\ttindex{FloatType}}
416\end{cvardesc}
417
418\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +0000419 Return true if its argument is a \ctype{PyFloatObject} or a subtype
Fred Drake3adf79e2001-10-12 19:01:43 +0000420 of \ctype{PyFloatObject}.
421 \versionchanged[Allowed subtypes to be accepted]{2.2}
422\end{cfuncdesc}
423
424\begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +0000425 Return true if its argument is a \ctype{PyFloatObject}, but not a
Fred Drake3adf79e2001-10-12 19:01:43 +0000426 subtype of \ctype{PyFloatObject}.
427 \versionadded{2.2}
428\end{cfuncdesc}
429
Skip Montanaro1ff49a72003-02-03 05:13:24 +0000430\begin{cfuncdesc}{PyObject*}{PyFloat_FromString}{PyObject *str, char **pend}
Georg Brandl99363b62005-09-03 07:27:26 +0000431 Create a \ctype{PyFloatObject} object based on the string value in
Skip Montanaro1ff49a72003-02-03 05:13:24 +0000432 \var{str}, or \NULL{} on failure. The \var{pend} argument is ignored. It
433 remains only for backward compatibility.
Skip Montanaroae31e9b2003-02-03 03:56:36 +0000434\end{cfuncdesc}
435
Fred Drake3adf79e2001-10-12 19:01:43 +0000436\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
Georg Brandl99363b62005-09-03 07:27:26 +0000437 Create a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
Fred Drake3adf79e2001-10-12 19:01:43 +0000438 failure.
439\end{cfuncdesc}
440
441\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
Georg Brandl99363b62005-09-03 07:27:26 +0000442 Return a C \ctype{double} representation of the contents of
Fred Drake3adf79e2001-10-12 19:01:43 +0000443 \var{pyfloat}.
444\end{cfuncdesc}
445
446\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
Georg Brandl99363b62005-09-03 07:27:26 +0000447 Return a C \ctype{double} representation of the contents of
Fred Drake3adf79e2001-10-12 19:01:43 +0000448 \var{pyfloat}, but without error checking.
449\end{cfuncdesc}
450
451
452\subsection{Complex Number Objects \label{complexObjects}}
453
454\obindex{complex number}
455Python's complex number objects are implemented as two distinct types
456when viewed from the C API: one is the Python object exposed to
457Python programs, and the other is a C structure which represents the
458actual complex number value. The API provides functions for working
459with both.
460
461\subsubsection{Complex Numbers as C Structures}
462
463Note that the functions which accept these structures as parameters
464and return them as results do so \emph{by value} rather than
465dereferencing them through pointers. This is consistent throughout
466the API.
467
468\begin{ctypedesc}{Py_complex}
469 The C structure which corresponds to the value portion of a Python
470 complex number object. Most of the functions for dealing with
471 complex number objects use structures of this type as input or
472 output values, as appropriate. It is defined as:
473
474\begin{verbatim}
475typedef struct {
476 double real;
477 double imag;
478} Py_complex;
479\end{verbatim}
480\end{ctypedesc}
481
482\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
483 Return the sum of two complex numbers, using the C
484 \ctype{Py_complex} representation.
485\end{cfuncdesc}
486
487\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
488 Return the difference between two complex numbers, using the C
489 \ctype{Py_complex} representation.
490\end{cfuncdesc}
491
492\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
493 Return the negation of the complex number \var{complex}, using the C
494 \ctype{Py_complex} representation.
495\end{cfuncdesc}
496
497\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
498 Return the product of two complex numbers, using the C
499 \ctype{Py_complex} representation.
500\end{cfuncdesc}
501
502\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
503 Py_complex divisor}
504 Return the quotient of two complex numbers, using the C
505 \ctype{Py_complex} representation.
506\end{cfuncdesc}
507
508\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
509 Return the exponentiation of \var{num} by \var{exp}, using the C
510 \ctype{Py_complex} representation.
511\end{cfuncdesc}
512
513
514\subsubsection{Complex Numbers as Python Objects}
515
516\begin{ctypedesc}{PyComplexObject}
517 This subtype of \ctype{PyObject} represents a Python complex number
518 object.
519\end{ctypedesc}
520
521\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
522 This instance of \ctype{PyTypeObject} represents the Python complex
523 number type.
524\end{cvardesc}
525
526\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +0000527 Return true if its argument is a \ctype{PyComplexObject} or a
Fred Drake3adf79e2001-10-12 19:01:43 +0000528 subtype of \ctype{PyComplexObject}.
529 \versionchanged[Allowed subtypes to be accepted]{2.2}
530\end{cfuncdesc}
531
532\begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +0000533 Return true if its argument is a \ctype{PyComplexObject}, but not a
Fred Drake3adf79e2001-10-12 19:01:43 +0000534 subtype of \ctype{PyComplexObject}.
535 \versionadded{2.2}
536\end{cfuncdesc}
537
538\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
539 Create a new Python complex number object from a C
540 \ctype{Py_complex} value.
541\end{cfuncdesc}
542
543\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
Georg Brandl99363b62005-09-03 07:27:26 +0000544 Return a new \ctype{PyComplexObject} object from \var{real} and
Fred Drake3adf79e2001-10-12 19:01:43 +0000545 \var{imag}.
546\end{cfuncdesc}
547
548\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
Georg Brandl99363b62005-09-03 07:27:26 +0000549 Return the real part of \var{op} as a C \ctype{double}.
Fred Drake3adf79e2001-10-12 19:01:43 +0000550\end{cfuncdesc}
551
552\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
Georg Brandl99363b62005-09-03 07:27:26 +0000553 Return the imaginary part of \var{op} as a C \ctype{double}.
Fred Drake3adf79e2001-10-12 19:01:43 +0000554\end{cfuncdesc}
555
556\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
Georg Brandl99363b62005-09-03 07:27:26 +0000557 Return the \ctype{Py_complex} value of the complex number
Fred Drake3adf79e2001-10-12 19:01:43 +0000558 \var{op}.
559\end{cfuncdesc}
560
561
562
563\section{Sequence Objects \label{sequenceObjects}}
564
565\obindex{sequence}
Tim Petersf582b822001-12-11 18:51:08 +0000566Generic operations on sequence objects were discussed in the previous
567chapter; this section deals with the specific kinds of sequence
Fred Drake3adf79e2001-10-12 19:01:43 +0000568objects that are intrinsic to the Python language.
569
570
571\subsection{String Objects \label{stringObjects}}
572
573These functions raise \exception{TypeError} when expecting a string
574parameter and are called with a non-string parameter.
575
576\obindex{string}
577\begin{ctypedesc}{PyStringObject}
578 This subtype of \ctype{PyObject} represents a Python string object.
579\end{ctypedesc}
580
581\begin{cvardesc}{PyTypeObject}{PyString_Type}
582 This instance of \ctype{PyTypeObject} represents the Python string
583 type; it is the same object as \code{types.TypeType} in the Python
584 layer.
585 \withsubitem{(in module types)}{\ttindex{StringType}}.
586\end{cvardesc}
587
588\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +0000589 Return true if the object \var{o} is a string object or an instance
Fred Drake3adf79e2001-10-12 19:01:43 +0000590 of a subtype of the string type.
591 \versionchanged[Allowed subtypes to be accepted]{2.2}
592\end{cfuncdesc}
593
594\begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +0000595 Return true if the object \var{o} is a string object, but not an
Fred Drake3adf79e2001-10-12 19:01:43 +0000596 instance of a subtype of the string type.
597 \versionadded{2.2}
598\end{cfuncdesc}
599
600\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
Georg Brandl99363b62005-09-03 07:27:26 +0000601 Return a new string object with the value \var{v} on success, and
Tim Peters9ddf40b2004-06-20 22:41:32 +0000602 \NULL{} on failure. The parameter \var{v} must not be \NULL{}; it
Fred Drake32a35872001-12-06 20:38:15 +0000603 will not be checked.
Fred Drake3adf79e2001-10-12 19:01:43 +0000604\end{cfuncdesc}
605
606\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000607 Py_ssize_t len}
Georg Brandl99363b62005-09-03 07:27:26 +0000608 Return a new string object with the value \var{v} and length
Fred Drake3adf79e2001-10-12 19:01:43 +0000609 \var{len} on success, and \NULL{} on failure. If \var{v} is
Tim Peters9ddf40b2004-06-20 22:41:32 +0000610 \NULL{}, the contents of the string are uninitialized.
Fred Drake3adf79e2001-10-12 19:01:43 +0000611\end{cfuncdesc}
612
613\begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...}
Georg Brandl99363b62005-09-03 07:27:26 +0000614 Take a C \cfunction{printf()}-style \var{format} string and a
615 variable number of arguments, calculate the size of the resulting
616 Python string and return a string with the values formatted into
Fred Drake3adf79e2001-10-12 19:01:43 +0000617 it. The variable arguments must be C types and must correspond
618 exactly to the format characters in the \var{format} string. The
619 following format characters are allowed:
620
Thomas Wouters477c8d52006-05-27 19:21:47 +0000621 % This should be exactly the same as the table in PyErr_Format.
622 % One should just refer to the other.
623
624 % The descriptions for %zd and %zu are wrong, but the truth is complicated
625 % because not all compilers support the %z width modifier -- we fake it
626 % when necessary via interpolating PY_FORMAT_SIZE_T.
627
628 % %u, %lu, %zu should have "new in Python 2.5" blurbs.
629
Fred Drake3adf79e2001-10-12 19:01:43 +0000630 \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
631 \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
632 \lineiii{\%c}{int}{A single character, represented as an C int.}
633 \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
Thomas Wouters477c8d52006-05-27 19:21:47 +0000634 \lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
Fred Drake3adf79e2001-10-12 19:01:43 +0000635 \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
Thomas Wouters477c8d52006-05-27 19:21:47 +0000636 \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
637 \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
638 \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.}
Fred Drake3adf79e2001-10-12 19:01:43 +0000639 \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
640 \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
641 \lineiii{\%s}{char*}{A null-terminated C character array.}
642 \lineiii{\%p}{void*}{The hex representation of a C pointer.
643 Mostly equivalent to \code{printf("\%p")} except that it is
644 guaranteed to start with the literal \code{0x} regardless of
645 what the platform's \code{printf} yields.}
646 \end{tableiii}
Thomas Wouters477c8d52006-05-27 19:21:47 +0000647
648 An unrecognized format character causes all the rest of the format
649 string to be copied as-is to the result string, and any extra
650 arguments discarded.
Fred Drake3adf79e2001-10-12 19:01:43 +0000651\end{cfuncdesc}
652
653\begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format,
654 va_list vargs}
655 Identical to \function{PyString_FromFormat()} except that it takes
656 exactly two arguments.
657\end{cfuncdesc}
658
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000659\begin{cfuncdesc}{Py_ssize_t}{PyString_Size}{PyObject *string}
Georg Brandl99363b62005-09-03 07:27:26 +0000660 Return the length of the string in string object \var{string}.
Fred Drake3adf79e2001-10-12 19:01:43 +0000661\end{cfuncdesc}
662
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000663\begin{cfuncdesc}{Py_ssize_t}{PyString_GET_SIZE}{PyObject *string}
Fred Drake3adf79e2001-10-12 19:01:43 +0000664 Macro form of \cfunction{PyString_Size()} but without error
665 checking.
666\end{cfuncdesc}
667
668\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
Georg Brandl99363b62005-09-03 07:27:26 +0000669 Return a NUL-terminated representation of the contents of
Fred Drake3adf79e2001-10-12 19:01:43 +0000670 \var{string}. The pointer refers to the internal buffer of
671 \var{string}, not a copy. The data must not be modified in any way,
672 unless the string was just created using
673 \code{PyString_FromStringAndSize(NULL, \var{size})}.
Fred Drake4b247262002-10-22 20:20:20 +0000674 It must not be deallocated. If \var{string} is a Unicode object,
675 this function computes the default encoding of \var{string} and
676 operates on that. If \var{string} is not a string object at all,
677 \cfunction{PyString_AsString()} returns \NULL{} and raises
678 \exception{TypeError}.
Fred Drake3adf79e2001-10-12 19:01:43 +0000679\end{cfuncdesc}
680
681\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
682 Macro form of \cfunction{PyString_AsString()} but without error
Fred Drake4b247262002-10-22 20:20:20 +0000683 checking. Only string objects are supported; no Unicode objects
684 should be passed.
Fred Drake3adf79e2001-10-12 19:01:43 +0000685\end{cfuncdesc}
686
687\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
688 char **buffer,
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000689 Py_ssize_t *length}
Georg Brandl99363b62005-09-03 07:27:26 +0000690 Return a NUL-terminated representation of the contents of the
Fred Drake3adf79e2001-10-12 19:01:43 +0000691 object \var{obj} through the output variables \var{buffer} and
692 \var{length}.
693
694 The function accepts both string and Unicode objects as input. For
695 Unicode objects it returns the default encoded version of the
Tim Peters9ddf40b2004-06-20 22:41:32 +0000696 object. If \var{length} is \NULL{}, the resulting buffer may not
Fred Drake4b247262002-10-22 20:20:20 +0000697 contain NUL characters; if it does, the function returns \code{-1}
698 and a \exception{TypeError} is raised.
Fred Drake3adf79e2001-10-12 19:01:43 +0000699
700 The buffer refers to an internal string buffer of \var{obj}, not a
701 copy. The data must not be modified in any way, unless the string
702 was just created using \code{PyString_FromStringAndSize(NULL,
Fred Drake4b247262002-10-22 20:20:20 +0000703 \var{size})}. It must not be deallocated. If \var{string} is a
704 Unicode object, this function computes the default encoding of
705 \var{string} and operates on that. If \var{string} is not a string
Thomas Wouters477c8d52006-05-27 19:21:47 +0000706 object at all, \cfunction{PyString_AsStringAndSize()} returns
Georg Brandle53475d2005-09-28 12:53:12 +0000707 \code{-1} and raises \exception{TypeError}.
Fred Drake3adf79e2001-10-12 19:01:43 +0000708\end{cfuncdesc}
709
710\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
711 PyObject *newpart}
Georg Brandl99363b62005-09-03 07:27:26 +0000712 Create a new string object in \var{*string} containing the contents
Fred Drake3adf79e2001-10-12 19:01:43 +0000713 of \var{newpart} appended to \var{string}; the caller will own the
714 new reference. The reference to the old value of \var{string} will
715 be stolen. If the new string cannot be created, the old reference
716 to \var{string} will still be discarded and the value of
Tim Peters9ddf40b2004-06-20 22:41:32 +0000717 \var{*string} will be set to \NULL{}; the appropriate exception will
Fred Drake3adf79e2001-10-12 19:01:43 +0000718 be set.
719\end{cfuncdesc}
720
721\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
722 PyObject *newpart}
Georg Brandl99363b62005-09-03 07:27:26 +0000723 Create a new string object in \var{*string} containing the contents
Fred Drake3adf79e2001-10-12 19:01:43 +0000724 of \var{newpart} appended to \var{string}. This version decrements
725 the reference count of \var{newpart}.
726\end{cfuncdesc}
727
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000728\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, Py_ssize_t newsize}
Fred Drake3adf79e2001-10-12 19:01:43 +0000729 A way to resize a string object even though it is ``immutable''.
730 Only use this to build up a brand new string object; don't use this
Tim Peters5de98422002-04-27 18:44:32 +0000731 if the string may already be known in other parts of the code. It
732 is an error to call this function if the refcount on the input string
733 object is not one.
734 Pass the address of an existing string object as an lvalue (it may
735 be written into), and the new size desired. On success, \var{*string}
Fred Drake432425e2002-04-29 15:17:16 +0000736 holds the resized string object and \code{0} is returned; the address in
Tim Peters5de98422002-04-27 18:44:32 +0000737 \var{*string} may differ from its input value. If the
738 reallocation fails, the original string object at \var{*string} is
739 deallocated, \var{*string} is set to \NULL{}, a memory exception is set,
Fred Drake432425e2002-04-29 15:17:16 +0000740 and \code{-1} is returned.
Fred Drake3adf79e2001-10-12 19:01:43 +0000741\end{cfuncdesc}
742
743\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
744 PyObject *args}
Georg Brandl99363b62005-09-03 07:27:26 +0000745 Return a new string object from \var{format} and \var{args}.
Fred Drake3adf79e2001-10-12 19:01:43 +0000746 Analogous to \code{\var{format} \%\ \var{args}}. The \var{args}
747 argument must be a tuple.
748\end{cfuncdesc}
749
750\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
751 Intern the argument \var{*string} in place. The argument must be
752 the address of a pointer variable pointing to a Python string
753 object. If there is an existing interned string that is the same as
754 \var{*string}, it sets \var{*string} to it (decrementing the
755 reference count of the old string object and incrementing the
756 reference count of the interned string object), otherwise it leaves
757 \var{*string} alone and interns it (incrementing its reference
758 count). (Clarification: even though there is a lot of talk about
759 reference counts, think of this function as reference-count-neutral;
760 you own the object after the call if and only if you owned it before
761 the call.)
762\end{cfuncdesc}
763
764\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
765 A combination of \cfunction{PyString_FromString()} and
766 \cfunction{PyString_InternInPlace()}, returning either a new string
767 object that has been interned, or a new (``owned'') reference to an
768 earlier interned string object with the same value.
769\end{cfuncdesc}
770
771\begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000772 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +0000773 const char *encoding,
774 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +0000775 Create an object by decoding \var{size} bytes of the encoded
Fred Drake3adf79e2001-10-12 19:01:43 +0000776 buffer \var{s} using the codec registered for
777 \var{encoding}. \var{encoding} and \var{errors} have the same
778 meaning as the parameters of the same name in the
779 \function{unicode()} built-in function. The codec to be used is
Georg Brandl99363b62005-09-03 07:27:26 +0000780 looked up using the Python codec registry. Return \NULL{} if
Fred Drake3adf79e2001-10-12 19:01:43 +0000781 an exception was raised by the codec.
782\end{cfuncdesc}
783
784\begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str,
785 const char *encoding,
786 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +0000787 Decode a string object by passing it to the codec registered for
788 \var{encoding} and return the result as Python
Fred Drake3adf79e2001-10-12 19:01:43 +0000789 object. \var{encoding} and \var{errors} have the same meaning as the
790 parameters of the same name in the string \method{encode()} method.
791 The codec to be used is looked up using the Python codec registry.
Georg Brandl99363b62005-09-03 07:27:26 +0000792 Return \NULL{} if an exception was raised by the codec.
Fred Drake3adf79e2001-10-12 19:01:43 +0000793\end{cfuncdesc}
794
795\begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000796 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +0000797 const char *encoding,
798 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +0000799 Encode the \ctype{char} buffer of the given size by passing it to
800 the codec registered for \var{encoding} and return a Python object.
Fred Drake3adf79e2001-10-12 19:01:43 +0000801 \var{encoding} and \var{errors} have the same meaning as the
802 parameters of the same name in the string \method{encode()} method.
803 The codec to be used is looked up using the Python codec
Georg Brandl99363b62005-09-03 07:27:26 +0000804 registry. Return \NULL{} if an exception was raised by the
Fred Drake3adf79e2001-10-12 19:01:43 +0000805 codec.
806\end{cfuncdesc}
807
808\begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str,
809 const char *encoding,
810 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +0000811 Encode a string object using the codec registered for
812 \var{encoding} and return the result as Python object.
Fred Drake3adf79e2001-10-12 19:01:43 +0000813 \var{encoding} and \var{errors} have the same meaning as the
814 parameters of the same name in the string \method{encode()} method.
815 The codec to be used is looked up using the Python codec registry.
Georg Brandl99363b62005-09-03 07:27:26 +0000816 Return \NULL{} if an exception was raised by the codec.
Fred Drake3adf79e2001-10-12 19:01:43 +0000817\end{cfuncdesc}
818
819
820\subsection{Unicode Objects \label{unicodeObjects}}
821\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
822
823%--- Unicode Type -------------------------------------------------------
824
825These are the basic Unicode object types used for the Unicode
826implementation in Python:
827
828\begin{ctypedesc}{Py_UNICODE}
Marc-André Lemburgdf4f6e92005-10-10 19:08:41 +0000829 This type represents the storage type which is used by Python
830 internally as basis for holding Unicode ordinals. Python's default
831 builds use a 16-bit type for \ctype{Py_UNICODE} and store Unicode
832 values internally as UCS2. It is also possible to build a UCS4
833 version of Python (most recent Linux distributions come with UCS4
834 builds of Python). These builds then use a 32-bit type for
835 \ctype{Py_UNICODE} and store Unicode data internally as UCS4. On
836 platforms where \ctype{wchar_t} is available and compatible with the
837 chosen Python Unicode build variant, \ctype{Py_UNICODE} is a typedef
838 alias for \ctype{wchar_t} to enhance native platform compatibility.
839 On all other platforms, \ctype{Py_UNICODE} is a typedef alias for
840 either \ctype{unsigned short} (UCS2) or \ctype{unsigned long}
841 (UCS4).
Fred Drake3adf79e2001-10-12 19:01:43 +0000842\end{ctypedesc}
843
Marc-André Lemburgdf4f6e92005-10-10 19:08:41 +0000844Note that UCS2 and UCS4 Python builds are not binary compatible.
845Please keep this in mind when writing extensions or interfaces.
846
Fred Drake3adf79e2001-10-12 19:01:43 +0000847\begin{ctypedesc}{PyUnicodeObject}
848 This subtype of \ctype{PyObject} represents a Python Unicode object.
849\end{ctypedesc}
850
851\begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
852 This instance of \ctype{PyTypeObject} represents the Python Unicode
853 type.
854\end{cvardesc}
855
856The following APIs are really C macros and can be used to do fast
857checks and to access internal read-only data of Unicode objects:
858
859\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +0000860 Return true if the object \var{o} is a Unicode object or an
Fred Drake3adf79e2001-10-12 19:01:43 +0000861 instance of a Unicode subtype.
862 \versionchanged[Allowed subtypes to be accepted]{2.2}
863\end{cfuncdesc}
864
865\begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +0000866 Return true if the object \var{o} is a Unicode object, but not an
Fred Drake3adf79e2001-10-12 19:01:43 +0000867 instance of a subtype.
868 \versionadded{2.2}
869\end{cfuncdesc}
870
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000871\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_SIZE}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +0000872 Return the size of the object. \var{o} has to be a
Fred Drake3adf79e2001-10-12 19:01:43 +0000873 \ctype{PyUnicodeObject} (not checked).
874\end{cfuncdesc}
875
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000876\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +0000877 Return the size of the object's internal buffer in bytes. \var{o}
Fred Drake3adf79e2001-10-12 19:01:43 +0000878 has to be a \ctype{PyUnicodeObject} (not checked).
879\end{cfuncdesc}
880
881\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +0000882 Return a pointer to the internal \ctype{Py_UNICODE} buffer of the
Fred Drake3adf79e2001-10-12 19:01:43 +0000883 object. \var{o} has to be a \ctype{PyUnicodeObject} (not checked).
884\end{cfuncdesc}
885
886\begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +0000887 Return a pointer to the internal buffer of the object.
Fred Drake3adf79e2001-10-12 19:01:43 +0000888 \var{o} has to be a \ctype{PyUnicodeObject} (not checked).
889\end{cfuncdesc}
890
891% --- Unicode character properties ---------------------------------------
892
893Unicode provides many different character properties. The most often
894needed ones are available through these macros which are mapped to C
895functions depending on the Python configuration.
896
897\begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000898 Return 1 or 0 depending on whether \var{ch} is a whitespace
Fred Drake3adf79e2001-10-12 19:01:43 +0000899 character.
900\end{cfuncdesc}
901
902\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000903 Return 1 or 0 depending on whether \var{ch} is a lowercase character.
Fred Drake3adf79e2001-10-12 19:01:43 +0000904\end{cfuncdesc}
905
906\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000907 Return 1 or 0 depending on whether \var{ch} is an uppercase
Fred Drake3adf79e2001-10-12 19:01:43 +0000908 character.
909\end{cfuncdesc}
910
911\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000912 Return 1 or 0 depending on whether \var{ch} is a titlecase character.
Fred Drake3adf79e2001-10-12 19:01:43 +0000913\end{cfuncdesc}
914
915\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000916 Return 1 or 0 depending on whether \var{ch} is a linebreak character.
Fred Drake3adf79e2001-10-12 19:01:43 +0000917\end{cfuncdesc}
918
919\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000920 Return 1 or 0 depending on whether \var{ch} is a decimal character.
Fred Drake3adf79e2001-10-12 19:01:43 +0000921\end{cfuncdesc}
922
923\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000924 Return 1 or 0 depending on whether \var{ch} is a digit character.
Fred Drake3adf79e2001-10-12 19:01:43 +0000925\end{cfuncdesc}
926
927\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000928 Return 1 or 0 depending on whether \var{ch} is a numeric character.
Fred Drake3adf79e2001-10-12 19:01:43 +0000929\end{cfuncdesc}
930
931\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000932 Return 1 or 0 depending on whether \var{ch} is an alphabetic
Fred Drake3adf79e2001-10-12 19:01:43 +0000933 character.
934\end{cfuncdesc}
935
936\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000937 Return 1 or 0 depending on whether \var{ch} is an alphanumeric
Fred Drake3adf79e2001-10-12 19:01:43 +0000938 character.
939\end{cfuncdesc}
940
941These APIs can be used for fast direct character conversions:
942
943\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000944 Return the character \var{ch} converted to lower case.
Fred Drake3adf79e2001-10-12 19:01:43 +0000945\end{cfuncdesc}
946
947\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000948 Return the character \var{ch} converted to upper case.
Fred Drake3adf79e2001-10-12 19:01:43 +0000949\end{cfuncdesc}
950
951\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000952 Return the character \var{ch} converted to title case.
Fred Drake3adf79e2001-10-12 19:01:43 +0000953\end{cfuncdesc}
954
955\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000956 Return the character \var{ch} converted to a decimal positive
957 integer. Return \code{-1} if this is not possible. This macro
958 does not raise exceptions.
Fred Drake3adf79e2001-10-12 19:01:43 +0000959\end{cfuncdesc}
960
961\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
Georg Brandl99363b62005-09-03 07:27:26 +0000962 Return the character \var{ch} converted to a single digit integer.
963 Return \code{-1} if this is not possible. This macro does not raise
Fred Drake3adf79e2001-10-12 19:01:43 +0000964 exceptions.
965\end{cfuncdesc}
966
967\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch}
Thomas Wouters477c8d52006-05-27 19:21:47 +0000968 Return the character \var{ch} converted to a double.
Georg Brandl99363b62005-09-03 07:27:26 +0000969 Return \code{-1.0} if this is not possible. This macro does not raise
Fred Drake3adf79e2001-10-12 19:01:43 +0000970 exceptions.
971\end{cfuncdesc}
972
973% --- Plain Py_UNICODE ---------------------------------------------------
974
975To create Unicode objects and access their basic sequence properties,
976use these APIs:
977
978\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u,
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000979 Py_ssize_t size}
Fred Drake3adf79e2001-10-12 19:01:43 +0000980 Create a Unicode Object from the Py_UNICODE buffer \var{u} of the
981 given size. \var{u} may be \NULL{} which causes the contents to be
982 undefined. It is the user's responsibility to fill in the needed
983 data. The buffer is copied into the new object. If the buffer is
Tim Peters9ddf40b2004-06-20 22:41:32 +0000984 not \NULL{}, the return value might be a shared object. Therefore,
Fred Drake3adf79e2001-10-12 19:01:43 +0000985 modification of the resulting Unicode object is only allowed when
Tim Peters9ddf40b2004-06-20 22:41:32 +0000986 \var{u} is \NULL{}.
Fred Drake3adf79e2001-10-12 19:01:43 +0000987\end{cfuncdesc}
988
989\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode}
990 Return a read-only pointer to the Unicode object's internal
991 \ctype{Py_UNICODE} buffer, \NULL{} if \var{unicode} is not a Unicode
992 object.
993\end{cfuncdesc}
994
Martin v. Löwis29fafd82006-03-01 05:16:03 +0000995\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GetSize}{PyObject *unicode}
Fred Drake3adf79e2001-10-12 19:01:43 +0000996 Return the length of the Unicode object.
997\end{cfuncdesc}
998
999\begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj,
1000 const char *encoding,
1001 const char *errors}
1002 Coerce an encoded object \var{obj} to an Unicode object and return a
1003 reference with incremented refcount.
1004
1005 Coercion is done in the following way:
1006
1007\begin{enumerate}
1008\item Unicode objects are passed back as-is with incremented
1009 refcount. \note{These cannot be decoded; passing a non-\NULL{}
1010 value for encoding will result in a \exception{TypeError}.}
1011
1012\item String and other char buffer compatible objects are decoded
1013 according to the given encoding and using the error handling
1014 defined by errors. Both can be \NULL{} to have the interface
1015 use the default values (see the next section for details).
1016
1017\item All other objects cause an exception.
1018\end{enumerate}
1019
1020 The API returns \NULL{} if there was an error. The caller is
1021 responsible for decref'ing the returned objects.
1022\end{cfuncdesc}
1023
1024\begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj}
1025 Shortcut for \code{PyUnicode_FromEncodedObject(obj, NULL, "strict")}
1026 which is used throughout the interpreter whenever coercion to
1027 Unicode is needed.
1028\end{cfuncdesc}
1029
1030% --- wchar_t support for platforms which support it ---------------------
1031
1032If the platform supports \ctype{wchar_t} and provides a header file
1033wchar.h, Python can interface directly to this type using the
1034following functions. Support is optimized if Python's own
1035\ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}.
1036
1037\begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001038 Py_ssize_t size}
Thomas Heller541703b2002-04-29 17:28:43 +00001039 Create a Unicode object from the \ctype{wchar_t} buffer \var{w} of
Georg Brandl99363b62005-09-03 07:27:26 +00001040 the given size. Return \NULL{} on failure.
Fred Drake3adf79e2001-10-12 19:01:43 +00001041\end{cfuncdesc}
1042
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001043\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
Fred Drake3adf79e2001-10-12 19:01:43 +00001044 wchar_t *w,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001045 Py_ssize_t size}
Georg Brandl99363b62005-09-03 07:27:26 +00001046 Copy the Unicode object contents into the \ctype{wchar_t} buffer
Marc-André Lemburga9cadcd2004-11-22 13:02:31 +00001047 \var{w}. At most \var{size} \ctype{wchar_t} characters are copied
Georg Brandl99363b62005-09-03 07:27:26 +00001048 (excluding a possibly trailing 0-termination character). Return
Marc-André Lemburga9cadcd2004-11-22 13:02:31 +00001049 the number of \ctype{wchar_t} characters copied or -1 in case of an
1050 error. Note that the resulting \ctype{wchar_t} string may or may
1051 not be 0-terminated. It is the responsibility of the caller to make
1052 sure that the \ctype{wchar_t} string is 0-terminated in case this is
1053 required by the application.
Fred Drake3adf79e2001-10-12 19:01:43 +00001054\end{cfuncdesc}
1055
1056
1057\subsubsection{Built-in Codecs \label{builtinCodecs}}
1058
1059Python provides a set of builtin codecs which are written in C
1060for speed. All of these codecs are directly usable via the
1061following functions.
1062
1063Many of the following APIs take two arguments encoding and
1064errors. These parameters encoding and errors have the same semantics
1065as the ones of the builtin unicode() Unicode object constructor.
1066
1067Setting encoding to \NULL{} causes the default encoding to be used
1068which is \ASCII. The file system calls should use
1069\cdata{Py_FileSystemDefaultEncoding} as the encoding for file
1070names. This variable should be treated as read-only: On some systems,
1071it will be a pointer to a static string, on others, it will change at
Raymond Hettingercb2da432003-10-12 18:24:34 +00001072run-time (such as when the application invokes setlocale).
Fred Drake3adf79e2001-10-12 19:01:43 +00001073
1074Error handling is set by errors which may also be set to \NULL{}
1075meaning to use the default handling defined for the codec. Default
1076error handling for all builtin codecs is ``strict''
1077(\exception{ValueError} is raised).
1078
1079The codecs all use a similar interface. Only deviation from the
1080following generic ones are documented for simplicity.
1081
1082% --- Generic Codecs -----------------------------------------------------
1083
1084These are the generic codec APIs:
1085
1086\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001087 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001088 const char *encoding,
1089 const char *errors}
1090 Create a Unicode object by decoding \var{size} bytes of the encoded
1091 string \var{s}. \var{encoding} and \var{errors} have the same
1092 meaning as the parameters of the same name in the
1093 \function{unicode()} builtin function. The codec to be used is
Georg Brandl99363b62005-09-03 07:27:26 +00001094 looked up using the Python codec registry. Return \NULL{} if an
Fred Drake3adf79e2001-10-12 19:01:43 +00001095 exception was raised by the codec.
1096\end{cfuncdesc}
1097
1098\begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001099 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001100 const char *encoding,
1101 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001102 Encode the \ctype{Py_UNICODE} buffer of the given size and return
Fred Drake3adf79e2001-10-12 19:01:43 +00001103 a Python string object. \var{encoding} and \var{errors} have the
1104 same meaning as the parameters of the same name in the Unicode
1105 \method{encode()} method. The codec to be used is looked up using
Georg Brandl99363b62005-09-03 07:27:26 +00001106 the Python codec registry. Return \NULL{} if an exception was
Fred Drake3adf79e2001-10-12 19:01:43 +00001107 raised by the codec.
1108\end{cfuncdesc}
1109
1110\begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
1111 const char *encoding,
1112 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001113 Encode a Unicode object and return the result as Python string
Fred Drake3adf79e2001-10-12 19:01:43 +00001114 object. \var{encoding} and \var{errors} have the same meaning as the
1115 parameters of the same name in the Unicode \method{encode()} method.
1116 The codec to be used is looked up using the Python codec registry.
Georg Brandl99363b62005-09-03 07:27:26 +00001117 Return \NULL{} if an exception was raised by the codec.
Fred Drake3adf79e2001-10-12 19:01:43 +00001118\end{cfuncdesc}
1119
1120% --- UTF-8 Codecs -------------------------------------------------------
1121
1122These are the UTF-8 codec APIs:
1123
1124\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001125 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001126 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001127 Create a Unicode object by decoding \var{size} bytes of the UTF-8
1128 encoded string \var{s}. Return \NULL{} if an exception was raised
Fred Drake3adf79e2001-10-12 19:01:43 +00001129 by the codec.
1130\end{cfuncdesc}
1131
Walter Dörwald69652032004-09-07 20:24:22 +00001132\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8Stateful}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001133 Py_ssize_t size,
Walter Dörwald69652032004-09-07 20:24:22 +00001134 const char *errors,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001135 Py_ssize_t *consumed}
Georg Brandl99363b62005-09-03 07:27:26 +00001136 If \var{consumed} is \NULL{}, behave like \cfunction{PyUnicode_DecodeUTF8()}.
Walter Dörwald69652032004-09-07 20:24:22 +00001137 If \var{consumed} is not \NULL{}, trailing incomplete UTF-8 byte sequences
1138 will not be treated as an error. Those bytes will not be decoded and the
1139 number of bytes that have been decoded will be stored in \var{consumed}.
1140 \versionadded{2.4}
1141\end{cfuncdesc}
1142
Fred Drake3adf79e2001-10-12 19:01:43 +00001143\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001144 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001145 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001146 Encode the \ctype{Py_UNICODE} buffer of the given size using UTF-8
1147 and return a Python string object. Return \NULL{} if an exception
Fred Drake3adf79e2001-10-12 19:01:43 +00001148 was raised by the codec.
1149\end{cfuncdesc}
1150
1151\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
Georg Brandl99363b62005-09-03 07:27:26 +00001152 Encode a Unicode objects using UTF-8 and return the result as
1153 Python string object. Error handling is ``strict''. Return
Fred Drake3adf79e2001-10-12 19:01:43 +00001154 \NULL{} if an exception was raised by the codec.
1155\end{cfuncdesc}
1156
1157% --- UTF-16 Codecs ------------------------------------------------------ */
1158
1159These are the UTF-16 codec APIs:
1160
1161\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001162 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001163 const char *errors,
1164 int *byteorder}
Georg Brandl99363b62005-09-03 07:27:26 +00001165 Decode \var{length} bytes from a UTF-16 encoded buffer string and
1166 return the corresponding Unicode object. \var{errors} (if
Tim Peters9ddf40b2004-06-20 22:41:32 +00001167 non-\NULL{}) defines the error handling. It defaults to ``strict''.
Fred Drake3adf79e2001-10-12 19:01:43 +00001168
Tim Peters9ddf40b2004-06-20 22:41:32 +00001169 If \var{byteorder} is non-\NULL{}, the decoder starts decoding using
Fred Drake3adf79e2001-10-12 19:01:43 +00001170 the given byte order:
1171
1172\begin{verbatim}
1173 *byteorder == -1: little endian
1174 *byteorder == 0: native order
1175 *byteorder == 1: big endian
1176\end{verbatim}
1177
1178 and then switches according to all byte order marks (BOM) it finds
1179 in the input data. BOMs are not copied into the resulting Unicode
1180 string. After completion, \var{*byteorder} is set to the current
1181 byte order at the end of input data.
1182
Tim Peters9ddf40b2004-06-20 22:41:32 +00001183 If \var{byteorder} is \NULL{}, the codec starts in native order mode.
Fred Drake3adf79e2001-10-12 19:01:43 +00001184
Georg Brandl99363b62005-09-03 07:27:26 +00001185 Return \NULL{} if an exception was raised by the codec.
Fred Drake3adf79e2001-10-12 19:01:43 +00001186\end{cfuncdesc}
1187
Walter Dörwald69652032004-09-07 20:24:22 +00001188\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16Stateful}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001189 Py_ssize_t size,
Walter Dörwald69652032004-09-07 20:24:22 +00001190 const char *errors,
1191 int *byteorder,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001192 Py_ssize_t *consumed}
Georg Brandl99363b62005-09-03 07:27:26 +00001193 If \var{consumed} is \NULL{}, behave like
Walter Dörwald69652032004-09-07 20:24:22 +00001194 \cfunction{PyUnicode_DecodeUTF16()}. If \var{consumed} is not \NULL{},
1195 \cfunction{PyUnicode_DecodeUTF16Stateful()} will not treat trailing incomplete
Raymond Hettinger0c230b92005-08-17 10:05:22 +00001196 UTF-16 byte sequences (such as an odd number of bytes or a split surrogate pair)
Walter Dörwald69652032004-09-07 20:24:22 +00001197 as an error. Those bytes will not be decoded and the number of bytes that
1198 have been decoded will be stored in \var{consumed}.
1199 \versionadded{2.4}
1200\end{cfuncdesc}
1201
Fred Drake3adf79e2001-10-12 19:01:43 +00001202\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001203 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001204 const char *errors,
1205 int byteorder}
Georg Brandl99363b62005-09-03 07:27:26 +00001206 Return a Python string object holding the UTF-16 encoded value of
Fred Drake3adf79e2001-10-12 19:01:43 +00001207 the Unicode data in \var{s}. If \var{byteorder} is not \code{0},
1208 output is written according to the following byte order:
1209
1210\begin{verbatim}
1211 byteorder == -1: little endian
1212 byteorder == 0: native byte order (writes a BOM mark)
1213 byteorder == 1: big endian
1214\end{verbatim}
1215
1216 If byteorder is \code{0}, the output string will always start with
1217 the Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark
1218 is prepended.
1219
Martin v. Löwis9bc4f2d2004-06-03 09:55:28 +00001220 If \var{Py_UNICODE_WIDE} is defined, a single \ctype{Py_UNICODE}
1221 value may get represented as a surrogate pair. If it is not
1222 defined, each \ctype{Py_UNICODE} values is interpreted as an
1223 UCS-2 character.
Fred Drake3adf79e2001-10-12 19:01:43 +00001224
Georg Brandl99363b62005-09-03 07:27:26 +00001225 Return \NULL{} if an exception was raised by the codec.
Fred Drake3adf79e2001-10-12 19:01:43 +00001226\end{cfuncdesc}
1227
1228\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
Georg Brandl99363b62005-09-03 07:27:26 +00001229 Return a Python string using the UTF-16 encoding in native byte
Fred Drake3adf79e2001-10-12 19:01:43 +00001230 order. The string always starts with a BOM mark. Error handling is
Georg Brandl99363b62005-09-03 07:27:26 +00001231 ``strict''. Return \NULL{} if an exception was raised by the
Fred Drake3adf79e2001-10-12 19:01:43 +00001232 codec.
1233\end{cfuncdesc}
1234
1235% --- Unicode-Escape Codecs ----------------------------------------------
1236
Martin v. Löwis95cf84a2003-10-19 07:32:24 +00001237These are the ``Unicode Escape'' codec APIs:
Fred Drake3adf79e2001-10-12 19:01:43 +00001238
1239\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001240 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001241 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001242 Create a Unicode object by decoding \var{size} bytes of the
1243 Unicode-Escape encoded string \var{s}. Return \NULL{} if an
Fred Drake3adf79e2001-10-12 19:01:43 +00001244 exception was raised by the codec.
1245\end{cfuncdesc}
1246
1247\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001248 Py_ssize_t size}
Georg Brandl99363b62005-09-03 07:27:26 +00001249 Encode the \ctype{Py_UNICODE} buffer of the given size using
1250 Unicode-Escape and return a Python string object. Return \NULL{}
Fred Drake3adf79e2001-10-12 19:01:43 +00001251 if an exception was raised by the codec.
1252\end{cfuncdesc}
1253
1254\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
Georg Brandl99363b62005-09-03 07:27:26 +00001255 Encode a Unicode objects using Unicode-Escape and return the
Fred Drake3adf79e2001-10-12 19:01:43 +00001256 result as Python string object. Error handling is ``strict''.
Georg Brandl99363b62005-09-03 07:27:26 +00001257 Return \NULL{} if an exception was raised by the codec.
Fred Drake3adf79e2001-10-12 19:01:43 +00001258\end{cfuncdesc}
1259
1260% --- Raw-Unicode-Escape Codecs ------------------------------------------
1261
Martin v. Löwis95cf84a2003-10-19 07:32:24 +00001262These are the ``Raw Unicode Escape'' codec APIs:
Fred Drake3adf79e2001-10-12 19:01:43 +00001263
1264\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001265 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001266 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001267 Create a Unicode object by decoding \var{size} bytes of the
1268 Raw-Unicode-Escape encoded string \var{s}. Return \NULL{} if an
Fred Drake3adf79e2001-10-12 19:01:43 +00001269 exception was raised by the codec.
1270\end{cfuncdesc}
1271
1272\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001273 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001274 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001275 Encode the \ctype{Py_UNICODE} buffer of the given size using
1276 Raw-Unicode-Escape and return a Python string object. Return
Fred Drake3adf79e2001-10-12 19:01:43 +00001277 \NULL{} if an exception was raised by the codec.
1278\end{cfuncdesc}
1279
1280\begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
Georg Brandl99363b62005-09-03 07:27:26 +00001281 Encode a Unicode objects using Raw-Unicode-Escape and return the
Fred Drake3adf79e2001-10-12 19:01:43 +00001282 result as Python string object. Error handling is ``strict''.
Georg Brandl99363b62005-09-03 07:27:26 +00001283 Return \NULL{} if an exception was raised by the codec.
Fred Drake3adf79e2001-10-12 19:01:43 +00001284\end{cfuncdesc}
1285
Tim Petersf582b822001-12-11 18:51:08 +00001286% --- Latin-1 Codecs -----------------------------------------------------
Fred Drake3adf79e2001-10-12 19:01:43 +00001287
1288These are the Latin-1 codec APIs:
1289Latin-1 corresponds to the first 256 Unicode ordinals and only these
1290are accepted by the codecs during encoding.
1291
1292\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001293 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001294 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001295 Create a Unicode object by decoding \var{size} bytes of the Latin-1
1296 encoded string \var{s}. Return \NULL{} if an exception was raised
Fred Drake3adf79e2001-10-12 19:01:43 +00001297 by the codec.
1298\end{cfuncdesc}
1299
1300\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001301 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001302 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001303 Encode the \ctype{Py_UNICODE} buffer of the given size using
1304 Latin-1 and return a Python string object. Return \NULL{} if an
Fred Drake3adf79e2001-10-12 19:01:43 +00001305 exception was raised by the codec.
1306\end{cfuncdesc}
1307
1308\begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
Georg Brandl99363b62005-09-03 07:27:26 +00001309 Encode a Unicode objects using Latin-1 and return the result as
1310 Python string object. Error handling is ``strict''. Return
Fred Drake3adf79e2001-10-12 19:01:43 +00001311 \NULL{} if an exception was raised by the codec.
1312\end{cfuncdesc}
1313
Tim Petersf582b822001-12-11 18:51:08 +00001314% --- ASCII Codecs -------------------------------------------------------
Fred Drake3adf79e2001-10-12 19:01:43 +00001315
1316These are the \ASCII{} codec APIs. Only 7-bit \ASCII{} data is
1317accepted. All other codes generate errors.
1318
1319\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001320 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001321 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001322 Create a Unicode object by decoding \var{size} bytes of the
1323 \ASCII{} encoded string \var{s}. Return \NULL{} if an exception
Fred Drake3adf79e2001-10-12 19:01:43 +00001324 was raised by the codec.
1325\end{cfuncdesc}
1326
1327\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001328 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001329 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001330 Encode the \ctype{Py_UNICODE} buffer of the given size using
1331 \ASCII{} and return a Python string object. Return \NULL{} if an
Fred Drake3adf79e2001-10-12 19:01:43 +00001332 exception was raised by the codec.
1333\end{cfuncdesc}
1334
1335\begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
Georg Brandl99363b62005-09-03 07:27:26 +00001336 Encode a Unicode objects using \ASCII{} and return the result as
1337 Python string object. Error handling is ``strict''. Return
Fred Drake3adf79e2001-10-12 19:01:43 +00001338 \NULL{} if an exception was raised by the codec.
1339\end{cfuncdesc}
1340
Tim Petersf582b822001-12-11 18:51:08 +00001341% --- Character Map Codecs -----------------------------------------------
Fred Drake3adf79e2001-10-12 19:01:43 +00001342
1343These are the mapping codec APIs:
1344
1345This codec is special in that it can be used to implement many
1346different codecs (and this is in fact what was done to obtain most of
1347the standard codecs included in the \module{encodings} package). The
1348codec uses mapping to encode and decode characters.
1349
1350Decoding mappings must map single string characters to single Unicode
1351characters, integers (which are then interpreted as Unicode ordinals)
Tim Petersf582b822001-12-11 18:51:08 +00001352or None (meaning "undefined mapping" and causing an error).
Fred Drake3adf79e2001-10-12 19:01:43 +00001353
1354Encoding mappings must map single Unicode characters to single string
1355characters, integers (which are then interpreted as Latin-1 ordinals)
1356or None (meaning "undefined mapping" and causing an error).
1357
1358The mapping objects provided must only support the __getitem__ mapping
1359interface.
1360
1361If a character lookup fails with a LookupError, the character is
1362copied as-is meaning that its ordinal value will be interpreted as
1363Unicode or Latin-1 ordinal resp. Because of this, mappings only need
1364to contain those mappings which map characters to different code
1365points.
1366
1367\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001368 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001369 PyObject *mapping,
1370 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001371 Create a Unicode object by decoding \var{size} bytes of the encoded
1372 string \var{s} using the given \var{mapping} object. Return
Walter Dörwaldd1c1e102005-10-06 20:29:57 +00001373 \NULL{} if an exception was raised by the codec. If \var{mapping} is \NULL{}
1374 latin-1 decoding will be done. Else it can be a dictionary mapping byte or a
1375 unicode string, which is treated as a lookup table. Byte values greater
1376 that the length of the string and U+FFFE "characters" are treated as
1377 "undefined mapping".
1378 \versionchanged[Allowed unicode string as mapping argument]{2.4}
Fred Drake3adf79e2001-10-12 19:01:43 +00001379\end{cfuncdesc}
1380
1381\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001382 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001383 PyObject *mapping,
1384 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001385 Encode the \ctype{Py_UNICODE} buffer of the given size using the
1386 given \var{mapping} object and return a Python string object.
1387 Return \NULL{} if an exception was raised by the codec.
Fred Drake3adf79e2001-10-12 19:01:43 +00001388\end{cfuncdesc}
1389
1390\begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
1391 PyObject *mapping}
Georg Brandl99363b62005-09-03 07:27:26 +00001392 Encode a Unicode objects using the given \var{mapping} object and
1393 return the result as Python string object. Error handling is
1394 ``strict''. Return \NULL{} if an exception was raised by the
Fred Drake3adf79e2001-10-12 19:01:43 +00001395 codec.
1396\end{cfuncdesc}
1397
1398The following codec API is special in that maps Unicode to Unicode.
1399
1400\begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001401 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001402 PyObject *table,
1403 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001404 Translate a \ctype{Py_UNICODE} buffer of the given length by
1405 applying a character mapping \var{table} to it and return the
1406 resulting Unicode object. Return \NULL{} when an exception was
Fred Drake3adf79e2001-10-12 19:01:43 +00001407 raised by the codec.
1408
1409 The \var{mapping} table must map Unicode ordinal integers to Unicode
1410 ordinal integers or None (causing deletion of the character).
1411
Thomas Wouters477c8d52006-05-27 19:21:47 +00001412 Mapping tables need only provide the \method{__getitem__()}
Fred Drake3adf79e2001-10-12 19:01:43 +00001413 interface; dictionaries and sequences work well. Unmapped character
1414 ordinals (ones which cause a \exception{LookupError}) are left
1415 untouched and are copied as-is.
1416\end{cfuncdesc}
1417
1418% --- MBCS codecs for Windows --------------------------------------------
1419
1420These are the MBCS codec APIs. They are currently only available on
1421Windows and use the Win32 MBCS converters to implement the
1422conversions. Note that MBCS (or DBCS) is a class of encodings, not
1423just one. The target encoding is defined by the user settings on the
1424machine running the codec.
1425
1426\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001427 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001428 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001429 Create a Unicode object by decoding \var{size} bytes of the MBCS
1430 encoded string \var{s}. Return \NULL{} if an exception was
Fred Drake3adf79e2001-10-12 19:01:43 +00001431 raised by the codec.
1432\end{cfuncdesc}
1433
1434\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001435 Py_ssize_t size,
Fred Drake3adf79e2001-10-12 19:01:43 +00001436 const char *errors}
Georg Brandl99363b62005-09-03 07:27:26 +00001437 Encode the \ctype{Py_UNICODE} buffer of the given size using MBCS
1438 and return a Python string object. Return \NULL{} if an exception
Fred Drake3adf79e2001-10-12 19:01:43 +00001439 was raised by the codec.
1440\end{cfuncdesc}
1441
1442\begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
Georg Brandl99363b62005-09-03 07:27:26 +00001443 Encode a Unicode objects using MBCS and return the result as
1444 Python string object. Error handling is ``strict''. Return
Fred Drake3adf79e2001-10-12 19:01:43 +00001445 \NULL{} if an exception was raised by the codec.
1446\end{cfuncdesc}
1447
1448% --- Methods & Slots ----------------------------------------------------
1449
1450\subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
1451
1452The following APIs are capable of handling Unicode objects and strings
1453on input (we refer to them as strings in the descriptions) and return
Martin v. Löwis95cf84a2003-10-19 07:32:24 +00001454Unicode objects or integers as appropriate.
Fred Drake3adf79e2001-10-12 19:01:43 +00001455
1456They all return \NULL{} or \code{-1} if an exception occurs.
1457
1458\begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left,
1459 PyObject *right}
1460 Concat two strings giving a new Unicode string.
1461\end{cfuncdesc}
1462
1463\begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
1464 PyObject *sep,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001465 Py_ssize_t maxsplit}
Tim Peters9ddf40b2004-06-20 22:41:32 +00001466 Split a string giving a list of Unicode strings. If sep is \NULL{},
Fred Drake3adf79e2001-10-12 19:01:43 +00001467 splitting will be done at all whitespace substrings. Otherwise,
1468 splits occur at the given separator. At most \var{maxsplit} splits
1469 will be done. If negative, no limit is set. Separators are not
1470 included in the resulting list.
1471\end{cfuncdesc}
1472
1473\begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s,
Martin v. Löwis24b88812003-03-30 16:40:42 +00001474 int keepend}
Fred Drake3adf79e2001-10-12 19:01:43 +00001475 Split a Unicode string at line breaks, returning a list of Unicode
Martin v. Löwis24b88812003-03-30 16:40:42 +00001476 strings. CRLF is considered to be one line break. If \var{keepend}
1477 is 0, the Line break characters are not included in the resulting
1478 strings.
Fred Drake3adf79e2001-10-12 19:01:43 +00001479\end{cfuncdesc}
1480
1481\begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str,
1482 PyObject *table,
1483 const char *errors}
1484 Translate a string by applying a character mapping table to it and
1485 return the resulting Unicode object.
1486
1487 The mapping table must map Unicode ordinal integers to Unicode
1488 ordinal integers or None (causing deletion of the character).
1489
1490 Mapping tables need only provide the \method{__getitem__()}
1491 interface; dictionaries and sequences work well. Unmapped character
1492 ordinals (ones which cause a \exception{LookupError}) are left
1493 untouched and are copied as-is.
1494
1495 \var{errors} has the usual meaning for codecs. It may be \NULL{}
1496 which indicates to use the default error handling.
1497\end{cfuncdesc}
1498
1499\begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator,
1500 PyObject *seq}
1501 Join a sequence of strings using the given separator and return the
1502 resulting Unicode string.
1503\end{cfuncdesc}
1504
Raymond Hettinger8ef9b3e2004-12-10 17:12:32 +00001505\begin{cfuncdesc}{int}{PyUnicode_Tailmatch}{PyObject *str,
Fred Drake3adf79e2001-10-12 19:01:43 +00001506 PyObject *substr,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001507 Py_ssize_t start,
1508 Py_ssize_t end,
Fred Drake3adf79e2001-10-12 19:01:43 +00001509 int direction}
1510 Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at
1511 the given tail end (\var{direction} == -1 means to do a prefix
1512 match, \var{direction} == 1 a suffix match), 0 otherwise.
Thomas Wouters477c8d52006-05-27 19:21:47 +00001513 Return \code{-1} if an error occurred.
Fred Drake3adf79e2001-10-12 19:01:43 +00001514\end{cfuncdesc}
1515
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001516\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Find}{PyObject *str,
Fred Drake1d1e1db2002-06-20 22:07:04 +00001517 PyObject *substr,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001518 Py_ssize_t start,
1519 Py_ssize_t end,
Fred Drake1d1e1db2002-06-20 22:07:04 +00001520 int direction}
Fred Drake3adf79e2001-10-12 19:01:43 +00001521 Return the first position of \var{substr} in
1522 \var{str}[\var{start}:\var{end}] using the given \var{direction}
1523 (\var{direction} == 1 means to do a forward search,
Fred Drake1d1e1db2002-06-20 22:07:04 +00001524 \var{direction} == -1 a backward search). The return value is the
1525 index of the first match; a value of \code{-1} indicates that no
1526 match was found, and \code{-2} indicates that an error occurred and
1527 an exception has been set.
Fred Drake3adf79e2001-10-12 19:01:43 +00001528\end{cfuncdesc}
1529
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001530\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Count}{PyObject *str,
Fred Drake1d1e1db2002-06-20 22:07:04 +00001531 PyObject *substr,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001532 Py_ssize_t start,
1533 Py_ssize_t end}
Fred Drake1d1e1db2002-06-20 22:07:04 +00001534 Return the number of non-overlapping occurrences of \var{substr} in
Georg Brandl99363b62005-09-03 07:27:26 +00001535 \code{\var{str}[\var{start}:\var{end}]}. Return \code{-1} if an
Fred Drake1d1e1db2002-06-20 22:07:04 +00001536 error occurred.
Fred Drake3adf79e2001-10-12 19:01:43 +00001537\end{cfuncdesc}
1538
1539\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
1540 PyObject *substr,
1541 PyObject *replstr,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001542 Py_ssize_t maxcount}
Fred Drake3adf79e2001-10-12 19:01:43 +00001543 Replace at most \var{maxcount} occurrences of \var{substr} in
1544 \var{str} with \var{replstr} and return the resulting Unicode object.
1545 \var{maxcount} == -1 means replace all occurrences.
1546\end{cfuncdesc}
1547
1548\begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right}
1549 Compare two strings and return -1, 0, 1 for less than, equal, and
1550 greater than, respectively.
1551\end{cfuncdesc}
1552
1553\begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
1554 PyObject *args}
Georg Brandl99363b62005-09-03 07:27:26 +00001555 Return a new string object from \var{format} and \var{args}; this
Fred Drake3adf79e2001-10-12 19:01:43 +00001556 is analogous to \code{\var{format} \%\ \var{args}}. The
1557 \var{args} argument must be a tuple.
1558\end{cfuncdesc}
1559
1560\begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
1561 PyObject *element}
Georg Brandl99363b62005-09-03 07:27:26 +00001562 Check whether \var{element} is contained in \var{container} and
1563 return true or false accordingly.
Fred Drake3adf79e2001-10-12 19:01:43 +00001564
1565 \var{element} has to coerce to a one element Unicode
1566 string. \code{-1} is returned if there was an error.
1567\end{cfuncdesc}
1568
1569
1570\subsection{Buffer Objects \label{bufferObjects}}
1571\sectionauthor{Greg Stein}{gstein@lyra.org}
1572
1573\obindex{buffer}
1574Python objects implemented in C can export a group of functions called
1575the ``buffer\index{buffer interface} interface.'' These functions can
1576be used by an object to expose its data in a raw, byte-oriented
1577format. Clients of the object can use the buffer interface to access
1578the object data directly, without needing to copy it first.
1579
Tim Petersf582b822001-12-11 18:51:08 +00001580Two examples of objects that support
1581the buffer interface are strings and arrays. The string object exposes
Fred Drake3adf79e2001-10-12 19:01:43 +00001582the character contents in the buffer interface's byte-oriented
1583form. An array can also expose its contents, but it should be noted
1584that array elements may be multi-byte values.
1585
1586An example user of the buffer interface is the file object's
1587\method{write()} method. Any object that can export a series of bytes
1588through the buffer interface can be written to a file. There are a
Tim Petersf582b822001-12-11 18:51:08 +00001589number of format codes to \cfunction{PyArg_ParseTuple()} that operate
Fred Drake3adf79e2001-10-12 19:01:43 +00001590against an object's buffer interface, returning data from the target
1591object.
1592
1593More information on the buffer interface is provided in the section
Fred Drake54e62942001-12-11 19:40:16 +00001594``Buffer Object Structures'' (section~\ref{buffer-structs}), under
Fred Drake3adf79e2001-10-12 19:01:43 +00001595the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}.
1596
1597A ``buffer object'' is defined in the \file{bufferobject.h} header
1598(included by \file{Python.h}). These objects look very similar to
1599string objects at the Python programming level: they support slicing,
1600indexing, concatenation, and some other standard string
1601operations. However, their data can come from one of two sources: from
1602a block of memory, or from another object which exports the buffer
1603interface.
1604
1605Buffer objects are useful as a way to expose the data from another
1606object's buffer interface to the Python programmer. They can also be
1607used as a zero-copy slicing mechanism. Using their ability to
1608reference a block of memory, it is possible to expose any data to the
1609Python programmer quite easily. The memory could be a large, constant
1610array in a C extension, it could be a raw block of memory for
1611manipulation before passing to an operating system library, or it
1612could be used to pass around structured data in its native, in-memory
1613format.
1614
1615\begin{ctypedesc}{PyBufferObject}
1616 This subtype of \ctype{PyObject} represents a buffer object.
1617\end{ctypedesc}
1618
1619\begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
1620 The instance of \ctype{PyTypeObject} which represents the Python
1621 buffer type; it is the same object as \code{types.BufferType} in the
1622 Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}.
1623\end{cvardesc}
1624
1625\begin{cvardesc}{int}{Py_END_OF_BUFFER}
1626 This constant may be passed as the \var{size} parameter to
1627 \cfunction{PyBuffer_FromObject()} or
1628 \cfunction{PyBuffer_FromReadWriteObject()}. It indicates that the
1629 new \ctype{PyBufferObject} should refer to \var{base} object from
1630 the specified \var{offset} to the end of its exported buffer. Using
1631 this enables the caller to avoid querying the \var{base} object for
1632 its length.
1633\end{cvardesc}
1634
1635\begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p}
1636 Return true if the argument has type \cdata{PyBuffer_Type}.
1637\end{cfuncdesc}
1638
1639\begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001640 Py_ssize_t offset, Py_ssize_t size}
Fred Drake3adf79e2001-10-12 19:01:43 +00001641 Return a new read-only buffer object. This raises
1642 \exception{TypeError} if \var{base} doesn't support the read-only
1643 buffer protocol or doesn't provide exactly one buffer segment, or it
1644 raises \exception{ValueError} if \var{offset} is less than zero. The
1645 buffer will hold a reference to the \var{base} object, and the
1646 buffer's contents will refer to the \var{base} object's buffer
1647 interface, starting as position \var{offset} and extending for
1648 \var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then
1649 the new buffer's contents extend to the length of the \var{base}
1650 object's exported buffer data.
1651\end{cfuncdesc}
1652
1653\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001654 Py_ssize_t offset,
1655 Py_ssize_t size}
Fred Drake3adf79e2001-10-12 19:01:43 +00001656 Return a new writable buffer object. Parameters and exceptions are
1657 similar to those for \cfunction{PyBuffer_FromObject()}. If the
1658 \var{base} object does not export the writeable buffer protocol,
1659 then \exception{TypeError} is raised.
1660\end{cfuncdesc}
1661
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001662\begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, Py_ssize_t size}
Fred Drake3adf79e2001-10-12 19:01:43 +00001663 Return a new read-only buffer object that reads from a specified
1664 location in memory, with a specified size. The caller is
1665 responsible for ensuring that the memory buffer, passed in as
1666 \var{ptr}, is not deallocated while the returned buffer object
1667 exists. Raises \exception{ValueError} if \var{size} is less than
1668 zero. Note that \constant{Py_END_OF_BUFFER} may \emph{not} be
1669 passed for the \var{size} parameter; \exception{ValueError} will be
1670 raised in that case.
1671\end{cfuncdesc}
1672
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001673\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, Py_ssize_t size}
Fred Drake3adf79e2001-10-12 19:01:43 +00001674 Similar to \cfunction{PyBuffer_FromMemory()}, but the returned
1675 buffer is writable.
1676\end{cfuncdesc}
1677
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001678\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{Py_ssize_t size}
Georg Brandl99363b62005-09-03 07:27:26 +00001679 Return a new writable buffer object that maintains its own memory
Fred Drake3adf79e2001-10-12 19:01:43 +00001680 buffer of \var{size} bytes. \exception{ValueError} is returned if
Neil Schemenauerd68d3ee2004-06-08 02:58:50 +00001681 \var{size} is not zero or positive. Note that the memory buffer (as
1682 returned by \cfunction{PyObject_AsWriteBuffer()}) is not specifically
1683 aligned.
Fred Drake3adf79e2001-10-12 19:01:43 +00001684\end{cfuncdesc}
1685
1686
1687\subsection{Tuple Objects \label{tupleObjects}}
1688
1689\obindex{tuple}
1690\begin{ctypedesc}{PyTupleObject}
1691 This subtype of \ctype{PyObject} represents a Python tuple object.
1692\end{ctypedesc}
1693
1694\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
1695 This instance of \ctype{PyTypeObject} represents the Python tuple
1696 type; it is the same object as \code{types.TupleType} in the Python
1697 layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
1698\end{cvardesc}
1699
1700\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
1701 Return true if \var{p} is a tuple object or an instance of a subtype
1702 of the tuple type.
1703 \versionchanged[Allowed subtypes to be accepted]{2.2}
1704\end{cfuncdesc}
1705
1706\begin{cfuncdesc}{int}{PyTuple_CheckExact}{PyObject *p}
1707 Return true if \var{p} is a tuple object, but not an instance of a
1708 subtype of the tuple type.
1709 \versionadded{2.2}
1710\end{cfuncdesc}
1711
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001712\begin{cfuncdesc}{PyObject*}{PyTuple_New}{Py_ssize_t len}
Fred Drake3adf79e2001-10-12 19:01:43 +00001713 Return a new tuple object of size \var{len}, or \NULL{} on failure.
1714\end{cfuncdesc}
1715
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001716\begin{cfuncdesc}{PyObject*}{PyTuple_Pack}{Py_ssize_t n, \moreargs}
Raymond Hettingercb2da432003-10-12 18:24:34 +00001717 Return a new tuple object of size \var{n}, or \NULL{} on failure.
1718 The tuple values are initialized to the subsequent \var{n} C arguments
1719 pointing to Python objects. \samp{PyTuple_Pack(2, \var{a}, \var{b})}
1720 is equivalent to \samp{Py_BuildValue("(OO)", \var{a}, \var{b})}.
Tim Peters9ddf40b2004-06-20 22:41:32 +00001721 \versionadded{2.4}
Raymond Hettingercb2da432003-10-12 18:24:34 +00001722\end{cfuncdesc}
1723
Fred Drake3adf79e2001-10-12 19:01:43 +00001724\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00001725 Take a pointer to a tuple object, and return the size of that
Fred Drake3adf79e2001-10-12 19:01:43 +00001726 tuple.
1727\end{cfuncdesc}
1728
1729\begin{cfuncdesc}{int}{PyTuple_GET_SIZE}{PyObject *p}
1730 Return the size of the tuple \var{p}, which must be non-\NULL{} and
1731 point to a tuple; no error checking is performed.
1732\end{cfuncdesc}
1733
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001734\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, Py_ssize_t pos}
Georg Brandl99363b62005-09-03 07:27:26 +00001735 Return the object at position \var{pos} in the tuple pointed to by
1736 \var{p}. If \var{pos} is out of bounds, return \NULL{} and sets an
Fred Drake3adf79e2001-10-12 19:01:43 +00001737 \exception{IndexError} exception.
1738\end{cfuncdesc}
1739
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001740\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, Py_ssize_t pos}
Fred Drake3adf79e2001-10-12 19:01:43 +00001741 Like \cfunction{PyTuple_GetItem()}, but does no checking of its
1742 arguments.
1743\end{cfuncdesc}
1744
1745\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001746 Py_ssize_t low, Py_ssize_t high}
Georg Brandl99363b62005-09-03 07:27:26 +00001747 Take a slice of the tuple pointed to by \var{p} from \var{low} to
1748 \var{high} and return it as a new tuple.
Fred Drake3adf79e2001-10-12 19:01:43 +00001749\end{cfuncdesc}
1750
1751\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001752 Py_ssize_t pos, PyObject *o}
Georg Brandl99363b62005-09-03 07:27:26 +00001753 Insert a reference to object \var{o} at position \var{pos} of the
1754 tuple pointed to by \var{p}. Return \code{0} on success.
Fred Drake3adf79e2001-10-12 19:01:43 +00001755 \note{This function ``steals'' a reference to \var{o}.}
1756\end{cfuncdesc}
1757
1758\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001759 Py_ssize_t pos, PyObject *o}
Fred Drake3adf79e2001-10-12 19:01:43 +00001760 Like \cfunction{PyTuple_SetItem()}, but does no error checking, and
1761 should \emph{only} be used to fill in brand new tuples. \note{This
1762 function ``steals'' a reference to \var{o}.}
1763\end{cfuncdesc}
1764
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001765\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, Py_ssize_t newsize}
Fred Drake3adf79e2001-10-12 19:01:43 +00001766 Can be used to resize a tuple. \var{newsize} will be the new length
1767 of the tuple. Because tuples are \emph{supposed} to be immutable,
1768 this should only be used if there is only one reference to the
1769 object. Do \emph{not} use this if the tuple may already be known to
1770 some other part of the code. The tuple will always grow or shrink
1771 at the end. Think of this as destroying the old tuple and creating
1772 a new one, only more efficiently. Returns \code{0} on success.
1773 Client code should never assume that the resulting value of
1774 \code{*\var{p}} will be the same as before calling this function.
1775 If the object referenced by \code{*\var{p}} is replaced, the
1776 original \code{*\var{p}} is destroyed. On failure, returns
Tim Peters9ddf40b2004-06-20 22:41:32 +00001777 \code{-1} and sets \code{*\var{p}} to \NULL{}, and raises
Fred Drake3adf79e2001-10-12 19:01:43 +00001778 \exception{MemoryError} or
1779 \exception{SystemError}.
Tim Petersf582b822001-12-11 18:51:08 +00001780 \versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2}
Fred Drake3adf79e2001-10-12 19:01:43 +00001781\end{cfuncdesc}
1782
1783
1784\subsection{List Objects \label{listObjects}}
1785
1786\obindex{list}
1787\begin{ctypedesc}{PyListObject}
1788 This subtype of \ctype{PyObject} represents a Python list object.
1789\end{ctypedesc}
1790
1791\begin{cvardesc}{PyTypeObject}{PyList_Type}
1792 This instance of \ctype{PyTypeObject} represents the Python list
1793 type. This is the same object as \code{types.ListType}.
1794 \withsubitem{(in module types)}{\ttindex{ListType}}
1795\end{cvardesc}
1796
1797\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00001798 Return true if \var{p} is a list object or an instance of a
Andrew MacIntyre13cd8892003-12-25 23:57:52 +00001799 subtype of the list type.
1800 \versionchanged[Allowed subtypes to be accepted]{2.2}
1801\end{cfuncdesc}
1802
1803\begin{cfuncdesc}{int}{PyList_CheckExact}{PyObject *p}
1804 Return true if \var{p} is a list object, but not an instance of a
1805 subtype of the list type.
1806 \versionadded{2.2}
Fred Drake3adf79e2001-10-12 19:01:43 +00001807\end{cfuncdesc}
1808
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001809\begin{cfuncdesc}{PyObject*}{PyList_New}{Py_ssize_t len}
Georg Brandl99363b62005-09-03 07:27:26 +00001810 Return a new list of length \var{len} on success, or \NULL{} on
Fred Drake3adf79e2001-10-12 19:01:43 +00001811 failure.
1812\end{cfuncdesc}
1813
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001814\begin{cfuncdesc}{Py_ssize_t}{PyList_Size}{PyObject *list}
Georg Brandl99363b62005-09-03 07:27:26 +00001815 Return the length of the list object in \var{list}; this is
Fred Drake3adf79e2001-10-12 19:01:43 +00001816 equivalent to \samp{len(\var{list})} on a list object.
1817 \bifuncindex{len}
1818\end{cfuncdesc}
1819
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001820\begin{cfuncdesc}{Py_ssize_t}{PyList_GET_SIZE}{PyObject *list}
Fred Drake3adf79e2001-10-12 19:01:43 +00001821 Macro form of \cfunction{PyList_Size()} without error checking.
1822\end{cfuncdesc}
1823
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001824\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, Py_ssize_t index}
Georg Brandl99363b62005-09-03 07:27:26 +00001825 Return the object at position \var{pos} in the list pointed to by
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001826 \var{p}. The position must be positive, indexing from the end of the
1827 list is not supported. If \var{pos} is out of bounds, return \NULL{}
1828 and set an \exception{IndexError} exception.
Fred Drake3adf79e2001-10-12 19:01:43 +00001829\end{cfuncdesc}
1830
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001831\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, Py_ssize_t i}
Fred Drake3adf79e2001-10-12 19:01:43 +00001832 Macro form of \cfunction{PyList_GetItem()} without error checking.
1833\end{cfuncdesc}
1834
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001835\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, Py_ssize_t index,
Fred Drake3adf79e2001-10-12 19:01:43 +00001836 PyObject *item}
Georg Brandl99363b62005-09-03 07:27:26 +00001837 Set the item at index \var{index} in list to \var{item}. Return
Fred Drake3adf79e2001-10-12 19:01:43 +00001838 \code{0} on success or \code{-1} on failure. \note{This function
1839 ``steals'' a reference to \var{item} and discards a reference to an
1840 item already in the list at the affected position.}
1841\end{cfuncdesc}
1842
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001843\begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, Py_ssize_t i,
Fred Drake3adf79e2001-10-12 19:01:43 +00001844 PyObject *o}
1845 Macro form of \cfunction{PyList_SetItem()} without error checking.
1846 This is normally only used to fill in new lists where there is no
1847 previous content.
1848 \note{This function ``steals'' a reference to \var{item}, and,
1849 unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a
1850 reference to any item that it being replaced; any reference in
1851 \var{list} at position \var{i} will be leaked.}
1852\end{cfuncdesc}
1853
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001854\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, Py_ssize_t index,
Fred Drake3adf79e2001-10-12 19:01:43 +00001855 PyObject *item}
Georg Brandl99363b62005-09-03 07:27:26 +00001856 Insert the item \var{item} into list \var{list} in front of index
1857 \var{index}. Return \code{0} if successful; return \code{-1} and
1858 set an exception if unsuccessful. Analogous to
Fred Drake3adf79e2001-10-12 19:01:43 +00001859 \code{\var{list}.insert(\var{index}, \var{item})}.
1860\end{cfuncdesc}
1861
1862\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
Georg Brandl99363b62005-09-03 07:27:26 +00001863 Append the object \var{item} at the end of list \var{list}.
1864 Return \code{0} if successful; return \code{-1} and set an
Fred Drake3adf79e2001-10-12 19:01:43 +00001865 exception if unsuccessful. Analogous to
1866 \code{\var{list}.append(\var{item})}.
1867\end{cfuncdesc}
1868
1869\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001870 Py_ssize_t low, Py_ssize_t high}
Georg Brandl99363b62005-09-03 07:27:26 +00001871 Return a list of the objects in \var{list} containing the objects
1872 \emph{between} \var{low} and \var{high}. Return \NULL{} and set
Fred Drake3adf79e2001-10-12 19:01:43 +00001873 an exception if unsuccessful.
1874 Analogous to \code{\var{list}[\var{low}:\var{high}]}.
1875\end{cfuncdesc}
1876
1877\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001878 Py_ssize_t low, Py_ssize_t high,
Fred Drake3adf79e2001-10-12 19:01:43 +00001879 PyObject *itemlist}
Georg Brandl99363b62005-09-03 07:27:26 +00001880 Set the slice of \var{list} between \var{low} and \var{high} to the
Fred Drake3adf79e2001-10-12 19:01:43 +00001881 contents of \var{itemlist}. Analogous to
Raymond Hettinger9c7ed4c2003-10-26 17:20:07 +00001882 \code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}.
1883 The \var{itemlist} may be \NULL{}, indicating the assignment
1884 of an empty list (slice deletion).
Georg Brandl99363b62005-09-03 07:27:26 +00001885 Return \code{0} on success, \code{-1} on failure.
Fred Drake3adf79e2001-10-12 19:01:43 +00001886\end{cfuncdesc}
1887
1888\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
Georg Brandl99363b62005-09-03 07:27:26 +00001889 Sort the items of \var{list} in place. Return \code{0} on
Fred Drake3adf79e2001-10-12 19:01:43 +00001890 success, \code{-1} on failure. This is equivalent to
1891 \samp{\var{list}.sort()}.
1892\end{cfuncdesc}
1893
1894\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
Georg Brandl99363b62005-09-03 07:27:26 +00001895 Reverse the items of \var{list} in place. Return \code{0} on
Fred Drake3adf79e2001-10-12 19:01:43 +00001896 success, \code{-1} on failure. This is the equivalent of
1897 \samp{\var{list}.reverse()}.
1898\end{cfuncdesc}
1899
1900\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
Georg Brandl99363b62005-09-03 07:27:26 +00001901 Return a new tuple object containing the contents of \var{list};
Fred Drake3adf79e2001-10-12 19:01:43 +00001902 equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple}
1903\end{cfuncdesc}
1904
1905
1906\section{Mapping Objects \label{mapObjects}}
1907
1908\obindex{mapping}
1909
1910
1911\subsection{Dictionary Objects \label{dictObjects}}
1912
1913\obindex{dictionary}
1914\begin{ctypedesc}{PyDictObject}
1915 This subtype of \ctype{PyObject} represents a Python dictionary
1916 object.
1917\end{ctypedesc}
1918
1919\begin{cvardesc}{PyTypeObject}{PyDict_Type}
1920 This instance of \ctype{PyTypeObject} represents the Python
1921 dictionary type. This is exposed to Python programs as
1922 \code{types.DictType} and \code{types.DictionaryType}.
1923 \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}}
1924\end{cvardesc}
1925
1926\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00001927 Return true if \var{p} is a dict object or an instance of a
Andrew MacIntyre13cd8892003-12-25 23:57:52 +00001928 subtype of the dict type.
1929 \versionchanged[Allowed subtypes to be accepted]{2.2}
Fred Drake3adf79e2001-10-12 19:01:43 +00001930\end{cfuncdesc}
1931
Andrew MacIntyref72af652003-12-26 00:07:51 +00001932\begin{cfuncdesc}{int}{PyDict_CheckExact}{PyObject *p}
1933 Return true if \var{p} is a dict object, but not an instance of a
1934 subtype of the dict type.
1935 \versionadded{2.4}
1936\end{cfuncdesc}
1937
Fred Drake3adf79e2001-10-12 19:01:43 +00001938\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
Georg Brandl99363b62005-09-03 07:27:26 +00001939 Return a new empty dictionary, or \NULL{} on failure.
Fred Drake3adf79e2001-10-12 19:01:43 +00001940\end{cfuncdesc}
1941
1942\begin{cfuncdesc}{PyObject*}{PyDictProxy_New}{PyObject *dict}
1943 Return a proxy object for a mapping which enforces read-only
1944 behavior. This is normally used to create a proxy to prevent
1945 modification of the dictionary for non-dynamic class types.
1946 \versionadded{2.2}
1947\end{cfuncdesc}
1948
1949\begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00001950 Empty an existing dictionary of all key-value pairs.
Fred Drake3adf79e2001-10-12 19:01:43 +00001951\end{cfuncdesc}
1952
Raymond Hettingerbc0f2ab2003-11-25 21:12:14 +00001953\begin{cfuncdesc}{int}{PyDict_Contains}{PyObject *p, PyObject *key}
1954 Determine if dictionary \var{p} contains \var{key}. If an item
1955 in \var{p} is matches \var{key}, return \code{1}, otherwise return
1956 \code{0}. On error, return \code{-1}. This is equivalent to the
1957 Python expression \samp{\var{key} in \var{p}}.
Tim Peters9ddf40b2004-06-20 22:41:32 +00001958 \versionadded{2.4}
Raymond Hettingerbc0f2ab2003-11-25 21:12:14 +00001959\end{cfuncdesc}
1960
Fred Drake3adf79e2001-10-12 19:01:43 +00001961\begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00001962 Return a new dictionary that contains the same key-value pairs as
Fred Drake3adf79e2001-10-12 19:01:43 +00001963 \var{p}.
1964 \versionadded{1.6}
1965\end{cfuncdesc}
1966
1967\begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key,
1968 PyObject *val}
Georg Brandl99363b62005-09-03 07:27:26 +00001969 Insert \var{value} into the dictionary \var{p} with a key of
Fred Drake3adf79e2001-10-12 19:01:43 +00001970 \var{key}. \var{key} must be hashable; if it isn't,
1971 \exception{TypeError} will be raised.
Georg Brandl99363b62005-09-03 07:27:26 +00001972 Return \code{0} on success or \code{-1} on failure.
Fred Drake3adf79e2001-10-12 19:01:43 +00001973\end{cfuncdesc}
1974
1975\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00001976 const char *key,
Fred Drake3adf79e2001-10-12 19:01:43 +00001977 PyObject *val}
Georg Brandl99363b62005-09-03 07:27:26 +00001978 Insert \var{value} into the dictionary \var{p} using \var{key} as a
Fred Drake3adf79e2001-10-12 19:01:43 +00001979 key. \var{key} should be a \ctype{char*}. The key object is created
Georg Brandl99363b62005-09-03 07:27:26 +00001980 using \code{PyString_FromString(\var{key})}. Return \code{0} on
Fred Drake3adf79e2001-10-12 19:01:43 +00001981 success or \code{-1} on failure.
1982 \ttindex{PyString_FromString()}
1983\end{cfuncdesc}
1984
1985\begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key}
Georg Brandl99363b62005-09-03 07:27:26 +00001986 Remove the entry in dictionary \var{p} with key \var{key}.
Fred Drake3adf79e2001-10-12 19:01:43 +00001987 \var{key} must be hashable; if it isn't, \exception{TypeError} is
Georg Brandl99363b62005-09-03 07:27:26 +00001988 raised. Return \code{0} on success or \code{-1} on failure.
Fred Drake3adf79e2001-10-12 19:01:43 +00001989\end{cfuncdesc}
1990
1991\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key}
Georg Brandl99363b62005-09-03 07:27:26 +00001992 Remove the entry in dictionary \var{p} which has a key specified by
1993 the string \var{key}. Return \code{0} on success or \code{-1} on
Fred Drake3adf79e2001-10-12 19:01:43 +00001994 failure.
1995\end{cfuncdesc}
1996
1997\begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key}
Georg Brandl99363b62005-09-03 07:27:26 +00001998 Return the object from dictionary \var{p} which has a key
1999 \var{key}. Return \NULL{} if the key \var{key} is not present, but
Fred Drake3adf79e2001-10-12 19:01:43 +00002000 \emph{without} setting an exception.
2001\end{cfuncdesc}
2002
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002003\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, const char *key}
Fred Drake3adf79e2001-10-12 19:01:43 +00002004 This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is
2005 specified as a \ctype{char*}, rather than a \ctype{PyObject*}.
2006\end{cfuncdesc}
2007
2008\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00002009 Return a \ctype{PyListObject} containing all the items from the
Nicholas Bastin975e7252004-09-29 21:39:26 +00002010 dictionary, as in the dictionary method \method{items()} (see the
Fred Drake3adf79e2001-10-12 19:01:43 +00002011 \citetitle[../lib/lib.html]{Python Library Reference}).
2012\end{cfuncdesc}
2013
2014\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00002015 Return a \ctype{PyListObject} containing all the keys from the
Fred Drake3adf79e2001-10-12 19:01:43 +00002016 dictionary, as in the dictionary method \method{keys()} (see the
2017 \citetitle[../lib/lib.html]{Python Library Reference}).
2018\end{cfuncdesc}
2019
2020\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00002021 Return a \ctype{PyListObject} containing all the values from the
Fred Drake3adf79e2001-10-12 19:01:43 +00002022 dictionary \var{p}, as in the dictionary method \method{values()}
2023 (see the \citetitle[../lib/lib.html]{Python Library Reference}).
2024\end{cfuncdesc}
2025
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002026\begin{cfuncdesc}{Py_ssize_t}{PyDict_Size}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00002027 Return the number of items in the dictionary. This is equivalent
Fred Drake3adf79e2001-10-12 19:01:43 +00002028 to \samp{len(\var{p})} on a dictionary.\bifuncindex{len}
2029\end{cfuncdesc}
2030
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002031\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, Py_ssize_t *ppos,
Fred Drake3adf79e2001-10-12 19:01:43 +00002032 PyObject **pkey, PyObject **pvalue}
2033 Iterate over all key-value pairs in the dictionary \var{p}. The
2034 \ctype{int} referred to by \var{ppos} must be initialized to
2035 \code{0} prior to the first call to this function to start the
2036 iteration; the function returns true for each pair in the
2037 dictionary, and false once all pairs have been reported. The
2038 parameters \var{pkey} and \var{pvalue} should either point to
2039 \ctype{PyObject*} variables that will be filled in with each key and
Tim Peters9ddf40b2004-06-20 22:41:32 +00002040 value, respectively, or may be \NULL{}. Any references returned through
Raymond Hettinger54693242003-12-13 19:48:41 +00002041 them are borrowed. \var{ppos} should not be altered during iteration.
2042 Its value represents offsets within the internal dictionary structure,
2043 and since the structure is sparse, the offsets are not consecutive.
Fred Drake3adf79e2001-10-12 19:01:43 +00002044
2045 For example:
2046
2047\begin{verbatim}
2048PyObject *key, *value;
2049int pos = 0;
2050
2051while (PyDict_Next(self->dict, &pos, &key, &value)) {
2052 /* do something interesting with the values... */
2053 ...
2054}
2055\end{verbatim}
2056
2057 The dictionary \var{p} should not be mutated during iteration. It
2058 is safe (since Python 2.1) to modify the values of the keys as you
2059 iterate over the dictionary, but only so long as the set of keys
2060 does not change. For example:
2061
2062\begin{verbatim}
2063PyObject *key, *value;
2064int pos = 0;
2065
2066while (PyDict_Next(self->dict, &pos, &key, &value)) {
2067 int i = PyInt_AS_LONG(value) + 1;
2068 PyObject *o = PyInt_FromLong(i);
2069 if (o == NULL)
2070 return -1;
2071 if (PyDict_SetItem(self->dict, key, o) < 0) {
2072 Py_DECREF(o);
2073 return -1;
2074 }
2075 Py_DECREF(o);
2076}
2077\end{verbatim}
2078\end{cfuncdesc}
2079
2080\begin{cfuncdesc}{int}{PyDict_Merge}{PyObject *a, PyObject *b, int override}
Tim Petersf582b822001-12-11 18:51:08 +00002081 Iterate over mapping object \var{b} adding key-value pairs to dictionary
2082 \var{a}.
2083 \var{b} may be a dictionary, or any object supporting
2084 \function{PyMapping_Keys()} and \function{PyObject_GetItem()}.
2085 If \var{override} is true, existing pairs in \var{a} will
Fred Drake3adf79e2001-10-12 19:01:43 +00002086 be replaced if a matching key is found in \var{b}, otherwise pairs
2087 will only be added if there is not a matching key in \var{a}.
Tim Petersf582b822001-12-11 18:51:08 +00002088 Return \code{0} on success or \code{-1} if an exception was
Fred Drake3adf79e2001-10-12 19:01:43 +00002089 raised.
2090\versionadded{2.2}
2091\end{cfuncdesc}
2092
2093\begin{cfuncdesc}{int}{PyDict_Update}{PyObject *a, PyObject *b}
2094 This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C,
Tim Petersf582b822001-12-11 18:51:08 +00002095 or \code{\var{a}.update(\var{b})} in Python. Return \code{0} on
Fred Drake3adf79e2001-10-12 19:01:43 +00002096 success or \code{-1} if an exception was raised.
2097 \versionadded{2.2}
2098\end{cfuncdesc}
2099
Tim Petersf582b822001-12-11 18:51:08 +00002100\begin{cfuncdesc}{int}{PyDict_MergeFromSeq2}{PyObject *a, PyObject *seq2,
2101 int override}
2102 Update or merge into dictionary \var{a}, from the key-value pairs in
2103 \var{seq2}. \var{seq2} must be an iterable object producing
2104 iterable objects of length 2, viewed as key-value pairs. In case of
2105 duplicate keys, the last wins if \var{override} is true, else the
2106 first wins.
2107 Return \code{0} on success or \code{-1} if an exception
2108 was raised.
2109 Equivalent Python (except for the return value):
2110
2111\begin{verbatim}
2112def PyDict_MergeFromSeq2(a, seq2, override):
2113 for key, value in seq2:
2114 if override or key not in a:
2115 a[key] = value
2116\end{verbatim}
2117
2118 \versionadded{2.2}
2119\end{cfuncdesc}
Fred Drake3adf79e2001-10-12 19:01:43 +00002120
Fred Drake54e62942001-12-11 19:40:16 +00002121
Fred Drake3adf79e2001-10-12 19:01:43 +00002122\section{Other Objects \label{otherObjects}}
2123
2124\subsection{File Objects \label{fileObjects}}
2125
2126\obindex{file}
2127Python's built-in file objects are implemented entirely on the
2128\ctype{FILE*} support from the C standard library. This is an
2129implementation detail and may change in future releases of Python.
2130
2131\begin{ctypedesc}{PyFileObject}
2132 This subtype of \ctype{PyObject} represents a Python file object.
2133\end{ctypedesc}
2134
2135\begin{cvardesc}{PyTypeObject}{PyFile_Type}
2136 This instance of \ctype{PyTypeObject} represents the Python file
2137 type. This is exposed to Python programs as \code{types.FileType}.
2138 \withsubitem{(in module types)}{\ttindex{FileType}}
2139\end{cvardesc}
2140
2141\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00002142 Return true if its argument is a \ctype{PyFileObject} or a subtype
Fred Drake3adf79e2001-10-12 19:01:43 +00002143 of \ctype{PyFileObject}.
2144 \versionchanged[Allowed subtypes to be accepted]{2.2}
2145\end{cfuncdesc}
2146
2147\begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00002148 Return true if its argument is a \ctype{PyFileObject}, but not a
Fred Drake3adf79e2001-10-12 19:01:43 +00002149 subtype of \ctype{PyFileObject}.
2150 \versionadded{2.2}
2151\end{cfuncdesc}
2152
2153\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode}
Georg Brandl99363b62005-09-03 07:27:26 +00002154 On success, return a new file object that is opened on the file
Fred Drake3adf79e2001-10-12 19:01:43 +00002155 given by \var{filename}, with a file mode given by \var{mode}, where
2156 \var{mode} has the same semantics as the standard C routine
Georg Brandl99363b62005-09-03 07:27:26 +00002157 \cfunction{fopen()}\ttindex{fopen()}. On failure, return \NULL{}.
Fred Drake3adf79e2001-10-12 19:01:43 +00002158\end{cfuncdesc}
2159
2160\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp,
2161 char *name, char *mode,
2162 int (*close)(FILE*)}
Georg Brandl99363b62005-09-03 07:27:26 +00002163 Create a new \ctype{PyFileObject} from the already-open standard C
Fred Drake3adf79e2001-10-12 19:01:43 +00002164 file pointer, \var{fp}. The function \var{close} will be called
Georg Brandl99363b62005-09-03 07:27:26 +00002165 when the file should be closed. Return \NULL{} on failure.
Fred Drake3adf79e2001-10-12 19:01:43 +00002166\end{cfuncdesc}
2167
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002168\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00002169 Return the file object associated with \var{p} as a \ctype{FILE*}.
Fred Drake3adf79e2001-10-12 19:01:43 +00002170\end{cfuncdesc}
2171
2172\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n}
2173 Equivalent to \code{\var{p}.readline(\optional{\var{n}})}, this
2174 function reads one line from the object \var{p}. \var{p} may be a
2175 file object or any object with a \method{readline()} method. If
2176 \var{n} is \code{0}, exactly one line is read, regardless of the
2177 length of the line. If \var{n} is greater than \code{0}, no more
2178 than \var{n} bytes will be read from the file; a partial line can be
2179 returned. In both cases, an empty string is returned if the end of
2180 the file is reached immediately. If \var{n} is less than \code{0},
2181 however, one line is read regardless of length, but
2182 \exception{EOFError} is raised if the end of the file is reached
2183 immediately.
2184 \withsubitem{(built-in exception)}{\ttindex{EOFError}}
2185\end{cfuncdesc}
2186
2187\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00002188 Return the name of the file specified by \var{p} as a string
Fred Drake3adf79e2001-10-12 19:01:43 +00002189 object.
2190\end{cfuncdesc}
2191
2192\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
2193 Available on systems with \cfunction{setvbuf()}\ttindex{setvbuf()}
2194 only. This should only be called immediately after file object
2195 creation.
2196\end{cfuncdesc}
2197
Martin v. Löwis5467d4c2003-05-10 07:10:12 +00002198\begin{cfuncdesc}{int}{PyFile_Encoding}{PyFileObject *p, char *enc}
2199 Set the file's encoding for Unicode output to \var{enc}. Return
2200 1 on success and 0 on failure.
2201 \versionadded{2.3}
2202\end{cfuncdesc}
2203
Fred Drake3adf79e2001-10-12 19:01:43 +00002204\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag}
Georg Brandl99363b62005-09-03 07:27:26 +00002205 This function exists for internal use by the interpreter. Set the
Fred Drake3adf79e2001-10-12 19:01:43 +00002206 \member{softspace} attribute of \var{p} to \var{newflag} and
Georg Brandl99363b62005-09-03 07:27:26 +00002207 \withsubitem{(file attribute)}{\ttindex{softspace}}return the
Fred Drake3adf79e2001-10-12 19:01:43 +00002208 previous value. \var{p} does not have to be a file object for this
2209 function to work properly; any object is supported (thought its only
2210 interesting if the \member{softspace} attribute can be set). This
2211 function clears any errors, and will return \code{0} as the previous
2212 value if the attribute either does not exist or if there were errors
2213 in retrieving it. There is no way to detect errors from this
2214 function, but doing so should not be needed.
2215\end{cfuncdesc}
2216
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002217\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyObject *p,
Fred Drake3adf79e2001-10-12 19:01:43 +00002218 int flags}
Georg Brandl99363b62005-09-03 07:27:26 +00002219 Write object \var{obj} to file object \var{p}. The only supported
Fred Drake3adf79e2001-10-12 19:01:43 +00002220 flag for \var{flags} is
2221 \constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW}; if given, the
2222 \function{str()} of the object is written instead of the
Georg Brandl99363b62005-09-03 07:27:26 +00002223 \function{repr()}. Return \code{0} on success or \code{-1} on
Fred Drake3adf79e2001-10-12 19:01:43 +00002224 failure; the appropriate exception will be set.
2225\end{cfuncdesc}
2226
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002227\begin{cfuncdesc}{int}{PyFile_WriteString}{const char *s, PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00002228 Write string \var{s} to file object \var{p}. Return \code{0} on
Fred Drake3adf79e2001-10-12 19:01:43 +00002229 success or \code{-1} on failure; the appropriate exception will be
2230 set.
2231\end{cfuncdesc}
2232
2233
2234\subsection{Instance Objects \label{instanceObjects}}
2235
2236\obindex{instance}
2237There are very few functions specific to instance objects.
2238
2239\begin{cvardesc}{PyTypeObject}{PyInstance_Type}
2240 Type object for class instances.
2241\end{cvardesc}
2242
2243\begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj}
Georg Brandl99363b62005-09-03 07:27:26 +00002244 Return true if \var{obj} is an instance.
Fred Drake3adf79e2001-10-12 19:01:43 +00002245\end{cfuncdesc}
2246
2247\begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class,
2248 PyObject *arg,
2249 PyObject *kw}
2250 Create a new instance of a specific class. The parameters \var{arg}
2251 and \var{kw} are used as the positional and keyword parameters to
2252 the object's constructor.
2253\end{cfuncdesc}
2254
2255\begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class,
2256 PyObject *dict}
Neil Schemenauerc4932292005-06-18 17:54:13 +00002257 Create a new instance of a specific class without calling its
Fred Drake3adf79e2001-10-12 19:01:43 +00002258 constructor. \var{class} is the class of new object. The
2259 \var{dict} parameter will be used as the object's \member{__dict__};
Tim Peters9ddf40b2004-06-20 22:41:32 +00002260 if \NULL{}, a new dictionary will be created for the instance.
Fred Drake3adf79e2001-10-12 19:01:43 +00002261\end{cfuncdesc}
2262
2263
Georg Brandl9b743f52006-02-20 12:57:53 +00002264\subsection{Function Objects \label{function-objects}}
2265
2266\obindex{function}
2267There are a few functions specific to Python functions.
2268
2269\begin{ctypedesc}{PyFunctionObject}
2270 The C structure used for functions.
2271\end{ctypedesc}
2272
2273\begin{cvardesc}{PyTypeObject}{PyFunction_Type}
2274 This is an instance of \ctype{PyTypeObject} and represents the
2275 Python function type. It is exposed to Python programmers as
2276 \code{types.FunctionType}.
2277 \withsubitem{(in module types)}{\ttindex{MethodType}}
2278\end{cvardesc}
2279
2280\begin{cfuncdesc}{int}{PyFunction_Check}{PyObject *o}
2281 Return true if \var{o} is a function object (has type
2282 \cdata{PyFunction_Type}). The parameter must not be \NULL{}.
2283\end{cfuncdesc}
2284
2285\begin{cfuncdesc}{PyObject*}{PyFunction_New}{PyObject *code,
2286 PyObject *globals}
2287 Return a new function object associated with the code object
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00002288 \var{code}. \var{globals} must be a dictionary with the global
2289 variables accessible to the function.
Georg Brandl9b743f52006-02-20 12:57:53 +00002290
2291 The function's docstring, name and \var{__module__} are retrieved
2292 from the code object, the argument defaults and closure are set to
2293 \NULL{}.
2294\end{cfuncdesc}
2295
2296\begin{cfuncdesc}{PyObject*}{PyFunction_GetCode}{PyObject *op}
2297 Return the code object associated with the function object \var{op}.
2298\end{cfuncdesc}
2299
2300\begin{cfuncdesc}{PyObject*}{PyFunction_GetGlobals}{PyObject *op}
2301 Return the globals dictionary associated with the function object
2302 \var{op}.
2303\end{cfuncdesc}
2304
2305\begin{cfuncdesc}{PyObject*}{PyFunction_GetModule}{PyObject *op}
2306 Return the \var{__module__} attribute of the function object \var{op}.
2307 This is normally a string containing the module name, but can be set
2308 to any other object by Python code.
2309\end{cfuncdesc}
2310
2311\begin{cfuncdesc}{PyObject*}{PyFunction_GetDefaults}{PyObject *op}
2312 Return the argument default values of the function object \var{op}.
2313 This can be a tuple of arguments or \NULL{}.
2314\end{cfuncdesc}
2315
2316\begin{cfuncdesc}{int}{PyFunction_SetDefaults}{PyObject *op,
2317 PyObject *defaults}
2318 Set the argument default values for the function object \var{op}.
2319 \var{defaults} must be \var{Py_None} or a tuple.
2320
2321 Raises \exception{SystemError} and returns \code{-1} on failure.
2322\end{cfuncdesc}
2323
2324\begin{cfuncdesc}{PyObject*}{PyFunction_GetClosure}{PyObject *op}
2325 Return the closure associated with the function object \var{op}.
2326 This can be \NULL{} or a tuple of cell objects.
2327\end{cfuncdesc}
2328
2329\begin{cfuncdesc}{int}{PyFunction_SetClosure}{PyObject *op,
2330 PyObject *closure}
2331 Set the closure associated with the function object \var{op}.
2332 \var{closure} must be \var{Py_None} or a tuple of cell objects.
2333
2334 Raises \exception{SystemError} and returns \code{-1} on failure.
2335\end{cfuncdesc}
2336
2337
Fred Drake3adf79e2001-10-12 19:01:43 +00002338\subsection{Method Objects \label{method-objects}}
2339
2340\obindex{method}
2341There are some useful functions that are useful for working with
2342method objects.
2343
2344\begin{cvardesc}{PyTypeObject}{PyMethod_Type}
2345 This instance of \ctype{PyTypeObject} represents the Python method
2346 type. This is exposed to Python programs as \code{types.MethodType}.
2347 \withsubitem{(in module types)}{\ttindex{MethodType}}
2348\end{cvardesc}
2349
2350\begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o}
2351 Return true if \var{o} is a method object (has type
Tim Peters9ddf40b2004-06-20 22:41:32 +00002352 \cdata{PyMethod_Type}). The parameter must not be \NULL{}.
Fred Drake3adf79e2001-10-12 19:01:43 +00002353\end{cfuncdesc}
2354
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002355\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func,
Fred Drake3adf79e2001-10-12 19:01:43 +00002356 PyObject *self, PyObject *class}
2357 Return a new method object, with \var{func} being any callable
2358 object; this is the function that will be called when the method is
2359 called. If this method should be bound to an instance, \var{self}
2360 should be the instance and \var{class} should be the class of
2361 \var{self}, otherwise \var{self} should be \NULL{} and \var{class}
2362 should be the class which provides the unbound method..
2363\end{cfuncdesc}
2364
2365\begin{cfuncdesc}{PyObject*}{PyMethod_Class}{PyObject *meth}
2366 Return the class object from which the method \var{meth} was
2367 created; if this was created from an instance, it will be the class
2368 of the instance.
2369\end{cfuncdesc}
2370
2371\begin{cfuncdesc}{PyObject*}{PyMethod_GET_CLASS}{PyObject *meth}
2372 Macro version of \cfunction{PyMethod_Class()} which avoids error
2373 checking.
2374\end{cfuncdesc}
2375
2376\begin{cfuncdesc}{PyObject*}{PyMethod_Function}{PyObject *meth}
2377 Return the function object associated with the method \var{meth}.
2378\end{cfuncdesc}
2379
2380\begin{cfuncdesc}{PyObject*}{PyMethod_GET_FUNCTION}{PyObject *meth}
2381 Macro version of \cfunction{PyMethod_Function()} which avoids error
2382 checking.
2383\end{cfuncdesc}
2384
2385\begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth}
2386 Return the instance associated with the method \var{meth} if it is
Tim Peters9ddf40b2004-06-20 22:41:32 +00002387 bound, otherwise return \NULL{}.
Fred Drake3adf79e2001-10-12 19:01:43 +00002388\end{cfuncdesc}
2389
2390\begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth}
2391 Macro version of \cfunction{PyMethod_Self()} which avoids error
2392 checking.
2393\end{cfuncdesc}
2394
2395
2396\subsection{Module Objects \label{moduleObjects}}
2397
2398\obindex{module}
2399There are only a few functions special to module objects.
2400
2401\begin{cvardesc}{PyTypeObject}{PyModule_Type}
2402 This instance of \ctype{PyTypeObject} represents the Python module
2403 type. This is exposed to Python programs as
2404 \code{types.ModuleType}.
2405 \withsubitem{(in module types)}{\ttindex{ModuleType}}
2406\end{cvardesc}
2407
2408\begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00002409 Return true if \var{p} is a module object, or a subtype of a module
Fred Drake3adf79e2001-10-12 19:01:43 +00002410 object.
2411 \versionchanged[Allowed subtypes to be accepted]{2.2}
2412\end{cfuncdesc}
2413
2414\begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00002415 Return true if \var{p} is a module object, but not a subtype of
Fred Drake3adf79e2001-10-12 19:01:43 +00002416 \cdata{PyModule_Type}.
2417 \versionadded{2.2}
2418\end{cfuncdesc}
2419
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002420\begin{cfuncdesc}{PyObject*}{PyModule_New}{const char *name}
Fred Drake3adf79e2001-10-12 19:01:43 +00002421 Return a new module object with the \member{__name__} attribute set
2422 to \var{name}. Only the module's \member{__doc__} and
2423 \member{__name__} attributes are filled in; the caller is
2424 responsible for providing a \member{__file__} attribute.
2425 \withsubitem{(module attribute)}{
2426 \ttindex{__name__}\ttindex{__doc__}\ttindex{__file__}}
2427\end{cfuncdesc}
2428
2429\begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module}
2430 Return the dictionary object that implements \var{module}'s
2431 namespace; this object is the same as the \member{__dict__}
2432 attribute of the module object. This function never fails.
2433 \withsubitem{(module attribute)}{\ttindex{__dict__}}
Fred Drakef495ef72002-04-12 19:32:07 +00002434 It is recommended extensions use other \cfunction{PyModule_*()}
2435 and \cfunction{PyObject_*()} functions rather than directly
2436 manipulate a module's \member{__dict__}.
Fred Drake3adf79e2001-10-12 19:01:43 +00002437\end{cfuncdesc}
2438
2439\begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module}
2440 Return \var{module}'s \member{__name__} value. If the module does
2441 not provide one, or if it is not a string, \exception{SystemError}
2442 is raised and \NULL{} is returned.
2443 \withsubitem{(module attribute)}{\ttindex{__name__}}
2444 \withsubitem{(built-in exception)}{\ttindex{SystemError}}
2445\end{cfuncdesc}
2446
2447\begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module}
2448 Return the name of the file from which \var{module} was loaded using
2449 \var{module}'s \member{__file__} attribute. If this is not defined,
2450 or if it is not a string, raise \exception{SystemError} and return
Tim Peters9ddf40b2004-06-20 22:41:32 +00002451 \NULL{}.
Fred Drake3adf79e2001-10-12 19:01:43 +00002452 \withsubitem{(module attribute)}{\ttindex{__file__}}
2453 \withsubitem{(built-in exception)}{\ttindex{SystemError}}
2454\end{cfuncdesc}
2455
2456\begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002457 const char *name, PyObject *value}
Fred Drake3adf79e2001-10-12 19:01:43 +00002458 Add an object to \var{module} as \var{name}. This is a convenience
2459 function which can be used from the module's initialization
Georg Brandl99363b62005-09-03 07:27:26 +00002460 function. This steals a reference to \var{value}. Return
Fred Drake3adf79e2001-10-12 19:01:43 +00002461 \code{-1} on error, \code{0} on success.
2462 \versionadded{2.0}
2463\end{cfuncdesc}
2464
2465\begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002466 const char *name, long value}
Fred Drake3adf79e2001-10-12 19:01:43 +00002467 Add an integer constant to \var{module} as \var{name}. This
2468 convenience function can be used from the module's initialization
Georg Brandl99363b62005-09-03 07:27:26 +00002469 function. Return \code{-1} on error, \code{0} on success.
Fred Drake3adf79e2001-10-12 19:01:43 +00002470 \versionadded{2.0}
2471\end{cfuncdesc}
2472
2473\begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002474 const char *name, const char *value}
Fred Drake3adf79e2001-10-12 19:01:43 +00002475 Add a string constant to \var{module} as \var{name}. This
2476 convenience function can be used from the module's initialization
Georg Brandl99363b62005-09-03 07:27:26 +00002477 function. The string \var{value} must be null-terminated. Return
Fred Drake3adf79e2001-10-12 19:01:43 +00002478 \code{-1} on error, \code{0} on success.
2479 \versionadded{2.0}
2480\end{cfuncdesc}
2481
2482
2483\subsection{Iterator Objects \label{iterator-objects}}
2484
2485Python provides two general-purpose iterator objects. The first, a
2486sequence iterator, works with an arbitrary sequence supporting the
2487\method{__getitem__()} method. The second works with a callable
2488object and a sentinel value, calling the callable for each item in the
2489sequence, and ending the iteration when the sentinel value is
2490returned.
2491
2492\begin{cvardesc}{PyTypeObject}{PySeqIter_Type}
2493 Type object for iterator objects returned by
2494 \cfunction{PySeqIter_New()} and the one-argument form of the
2495 \function{iter()} built-in function for built-in sequence types.
2496 \versionadded{2.2}
2497\end{cvardesc}
2498
2499\begin{cfuncdesc}{int}{PySeqIter_Check}{op}
2500 Return true if the type of \var{op} is \cdata{PySeqIter_Type}.
2501 \versionadded{2.2}
2502\end{cfuncdesc}
2503
2504\begin{cfuncdesc}{PyObject*}{PySeqIter_New}{PyObject *seq}
2505 Return an iterator that works with a general sequence object,
2506 \var{seq}. The iteration ends when the sequence raises
2507 \exception{IndexError} for the subscripting operation.
2508 \versionadded{2.2}
2509\end{cfuncdesc}
2510
2511\begin{cvardesc}{PyTypeObject}{PyCallIter_Type}
2512 Type object for iterator objects returned by
2513 \cfunction{PyCallIter_New()} and the two-argument form of the
2514 \function{iter()} built-in function.
2515 \versionadded{2.2}
2516\end{cvardesc}
2517
2518\begin{cfuncdesc}{int}{PyCallIter_Check}{op}
2519 Return true if the type of \var{op} is \cdata{PyCallIter_Type}.
2520 \versionadded{2.2}
2521\end{cfuncdesc}
2522
2523\begin{cfuncdesc}{PyObject*}{PyCallIter_New}{PyObject *callable,
2524 PyObject *sentinel}
2525 Return a new iterator. The first parameter, \var{callable}, can be
2526 any Python callable object that can be called with no parameters;
2527 each call to it should return the next item in the iteration. When
2528 \var{callable} returns a value equal to \var{sentinel}, the
2529 iteration will be terminated.
2530 \versionadded{2.2}
2531\end{cfuncdesc}
2532
2533
2534\subsection{Descriptor Objects \label{descriptor-objects}}
2535
Fred Drake54e62942001-12-11 19:40:16 +00002536``Descriptors'' are objects that describe some attribute of an object.
2537They are found in the dictionary of type objects.
2538
Fred Drake3adf79e2001-10-12 19:01:43 +00002539\begin{cvardesc}{PyTypeObject}{PyProperty_Type}
Fred Drake54e62942001-12-11 19:40:16 +00002540 The type object for the built-in descriptor types.
Fred Drake3adf79e2001-10-12 19:01:43 +00002541 \versionadded{2.2}
2542\end{cvardesc}
2543
2544\begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002545 struct PyGetSetDef *getset}
Fred Drake3adf79e2001-10-12 19:01:43 +00002546 \versionadded{2.2}
2547\end{cfuncdesc}
2548
2549\begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002550 struct PyMemberDef *meth}
Fred Drake3adf79e2001-10-12 19:01:43 +00002551 \versionadded{2.2}
2552\end{cfuncdesc}
2553
2554\begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type,
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002555 struct PyMethodDef *meth}
Fred Drake3adf79e2001-10-12 19:01:43 +00002556 \versionadded{2.2}
2557\end{cfuncdesc}
2558
2559\begin{cfuncdesc}{PyObject*}{PyDescr_NewWrapper}{PyTypeObject *type,
2560 struct wrapperbase *wrapper,
2561 void *wrapped}
2562 \versionadded{2.2}
2563\end{cfuncdesc}
2564
Thomas Heller8178a222004-02-09 10:47:11 +00002565\begin{cfuncdesc}{PyObject*}{PyDescr_NewClassMethod}{PyTypeObject *type,
2566 PyMethodDef *method}
2567 \versionadded{2.3}
2568\end{cfuncdesc}
2569
Fred Drake3adf79e2001-10-12 19:01:43 +00002570\begin{cfuncdesc}{int}{PyDescr_IsData}{PyObject *descr}
Georg Brandl99363b62005-09-03 07:27:26 +00002571 Return true if the descriptor objects \var{descr} describes a data
Fred Drake3adf79e2001-10-12 19:01:43 +00002572 attribute, or false if it describes a method. \var{descr} must be a
2573 descriptor object; there is no error checking.
2574 \versionadded{2.2}
2575\end{cfuncdesc}
2576
2577\begin{cfuncdesc}{PyObject*}{PyWrapper_New}{PyObject *, PyObject *}
2578 \versionadded{2.2}
2579\end{cfuncdesc}
2580
2581
2582\subsection{Slice Objects \label{slice-objects}}
2583
2584\begin{cvardesc}{PyTypeObject}{PySlice_Type}
2585 The type object for slice objects. This is the same as
2586 \code{types.SliceType}.
2587 \withsubitem{(in module types)}{\ttindex{SliceType}}
2588\end{cvardesc}
2589
2590\begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob}
Georg Brandl99363b62005-09-03 07:27:26 +00002591 Return true if \var{ob} is a slice object; \var{ob} must not be
Tim Peters9ddf40b2004-06-20 22:41:32 +00002592 \NULL{}.
Fred Drake3adf79e2001-10-12 19:01:43 +00002593\end{cfuncdesc}
2594
2595\begin{cfuncdesc}{PyObject*}{PySlice_New}{PyObject *start, PyObject *stop,
2596 PyObject *step}
2597 Return a new slice object with the given values. The \var{start},
2598 \var{stop}, and \var{step} parameters are used as the values of the
2599 slice object attributes of the same names. Any of the values may be
Tim Peters9ddf40b2004-06-20 22:41:32 +00002600 \NULL{}, in which case the \code{None} will be used for the
Georg Brandl99363b62005-09-03 07:27:26 +00002601 corresponding attribute. Return \NULL{} if the new object could
Fred Drake3adf79e2001-10-12 19:01:43 +00002602 not be allocated.
2603\end{cfuncdesc}
2604
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002605\begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, Py_ssize_t length,
2606 Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step}
Michael W. Hudson5efaf7e2002-06-11 10:55:12 +00002607Retrieve the start, stop and step indices from the slice object
2608\var{slice}, assuming a sequence of length \var{length}. Treats
2609indices greater than \var{length} as errors.
2610
2611Returns 0 on success and -1 on error with no exception set (unless one
2612of the indices was not \constant{None} and failed to be converted to
2613an integer, in which case -1 is returned with an exception set).
2614
2615You probably do not want to use this function. If you want to use
2616slice objects in versions of Python prior to 2.3, you would probably
2617do well to incorporate the source of \cfunction{PySlice_GetIndicesEx},
2618suitably renamed, in the source of your extension.
2619\end{cfuncdesc}
2620
Martin v. Löwis29fafd82006-03-01 05:16:03 +00002621\begin{cfuncdesc}{int}{PySlice_GetIndicesEx}{PySliceObject *slice, Py_ssize_t length,
2622 Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step,
2623 Py_ssize_t *slicelength}
Michael W. Hudson5efaf7e2002-06-11 10:55:12 +00002624Usable replacement for \cfunction{PySlice_GetIndices}. Retrieve the
2625start, stop, and step indices from the slice object \var{slice}
2626assuming a sequence of length \var{length}, and store the length of
2627the slice in \var{slicelength}. Out of bounds indices are clipped in
2628a manner consistent with the handling of normal slices.
2629
2630Returns 0 on success and -1 on error with exception set.
2631
2632\versionadded{2.3}
Fred Drake3adf79e2001-10-12 19:01:43 +00002633\end{cfuncdesc}
2634
2635
2636\subsection{Weak Reference Objects \label{weakref-objects}}
2637
2638Python supports \emph{weak references} as first-class objects. There
2639are two specific object types which directly implement weak
2640references. The first is a simple reference object, and the second
2641acts as a proxy for the original object as much as it can.
2642
2643\begin{cfuncdesc}{int}{PyWeakref_Check}{ob}
2644 Return true if \var{ob} is either a reference or proxy object.
2645 \versionadded{2.2}
2646\end{cfuncdesc}
2647
2648\begin{cfuncdesc}{int}{PyWeakref_CheckRef}{ob}
2649 Return true if \var{ob} is a reference object.
2650 \versionadded{2.2}
2651\end{cfuncdesc}
2652
2653\begin{cfuncdesc}{int}{PyWeakref_CheckProxy}{ob}
2654 Return true if \var{ob} is a proxy object.
2655 \versionadded{2.2}
2656\end{cfuncdesc}
2657
2658\begin{cfuncdesc}{PyObject*}{PyWeakref_NewRef}{PyObject *ob,
2659 PyObject *callback}
2660 Return a weak reference object for the object \var{ob}. This will
2661 always return a new reference, but is not guaranteed to create a new
2662 object; an existing reference object may be returned. The second
2663 parameter, \var{callback}, can be a callable object that receives
2664 notification when \var{ob} is garbage collected; it should accept a
Raymond Hettinger5232f502004-03-25 08:51:36 +00002665 single parameter, which will be the weak reference object itself.
Tim Peters9ddf40b2004-06-20 22:41:32 +00002666 \var{callback} may also be \code{None} or \NULL{}. If \var{ob}
Fred Drake3adf79e2001-10-12 19:01:43 +00002667 is not a weakly-referencable object, or if \var{callback} is not
Tim Peters9ddf40b2004-06-20 22:41:32 +00002668 callable, \code{None}, or \NULL{}, this will return \NULL{} and
Fred Drake3adf79e2001-10-12 19:01:43 +00002669 raise \exception{TypeError}.
2670 \versionadded{2.2}
2671\end{cfuncdesc}
2672
2673\begin{cfuncdesc}{PyObject*}{PyWeakref_NewProxy}{PyObject *ob,
2674 PyObject *callback}
2675 Return a weak reference proxy object for the object \var{ob}. This
2676 will always return a new reference, but is not guaranteed to create
2677 a new object; an existing proxy object may be returned. The second
2678 parameter, \var{callback}, can be a callable object that receives
2679 notification when \var{ob} is garbage collected; it should accept a
Raymond Hettinger5232f502004-03-25 08:51:36 +00002680 single parameter, which will be the weak reference object itself.
Tim Peters9ddf40b2004-06-20 22:41:32 +00002681 \var{callback} may also be \code{None} or \NULL{}. If \var{ob} is not
Fred Drake3adf79e2001-10-12 19:01:43 +00002682 a weakly-referencable object, or if \var{callback} is not callable,
Tim Peters9ddf40b2004-06-20 22:41:32 +00002683 \code{None}, or \NULL{}, this will return \NULL{} and raise
Fred Drake3adf79e2001-10-12 19:01:43 +00002684 \exception{TypeError}.
2685 \versionadded{2.2}
2686\end{cfuncdesc}
2687
2688\begin{cfuncdesc}{PyObject*}{PyWeakref_GetObject}{PyObject *ref}
Georg Brandl99363b62005-09-03 07:27:26 +00002689 Return the referenced object from a weak reference, \var{ref}. If
Ka-Ping Yeebd379e92003-03-28 18:07:16 +00002690 the referent is no longer live, returns \code{None}.
Fred Drake3adf79e2001-10-12 19:01:43 +00002691 \versionadded{2.2}
2692\end{cfuncdesc}
2693
2694\begin{cfuncdesc}{PyObject*}{PyWeakref_GET_OBJECT}{PyObject *ref}
2695 Similar to \cfunction{PyWeakref_GetObject()}, but implemented as a
2696 macro that does no error checking.
2697 \versionadded{2.2}
2698\end{cfuncdesc}
2699
2700
2701\subsection{CObjects \label{cObjects}}
2702
2703\obindex{CObject}
2704Refer to \emph{Extending and Embedding the Python Interpreter},
Fred Drake54e62942001-12-11 19:40:16 +00002705section~1.12, ``Providing a C API for an Extension Module,'' for more
Fred Drake3adf79e2001-10-12 19:01:43 +00002706information on using these objects.
2707
2708
2709\begin{ctypedesc}{PyCObject}
2710 This subtype of \ctype{PyObject} represents an opaque value, useful
2711 for C extension modules who need to pass an opaque value (as a
2712 \ctype{void*} pointer) through Python code to other C code. It is
2713 often used to make a C function pointer defined in one module
2714 available to other modules, so the regular import mechanism can be
2715 used to access C APIs defined in dynamically loaded modules.
2716\end{ctypedesc}
2717
2718\begin{cfuncdesc}{int}{PyCObject_Check}{PyObject *p}
Martin v. Löwis01a74b22003-10-19 18:30:01 +00002719 Return true if its argument is a \ctype{PyCObject}.
Fred Drake3adf79e2001-10-12 19:01:43 +00002720\end{cfuncdesc}
2721
Tim Petersf582b822001-12-11 18:51:08 +00002722\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj,
Fred Drake54e62942001-12-11 19:40:16 +00002723 void (*destr)(void *)}
Martin v. Löwis01a74b22003-10-19 18:30:01 +00002724 Create a \ctype{PyCObject} from the \code{void *}\var{cobj}. The
Fred Drake3adf79e2001-10-12 19:01:43 +00002725 \var{destr} function will be called when the object is reclaimed,
Tim Peters9ddf40b2004-06-20 22:41:32 +00002726 unless it is \NULL{}.
Fred Drake3adf79e2001-10-12 19:01:43 +00002727\end{cfuncdesc}
2728
2729\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj,
2730 void* desc, void (*destr)(void *, void *)}
Martin v. Löwis01a74b22003-10-19 18:30:01 +00002731 Create a \ctype{PyCObject} from the \ctype{void *}\var{cobj}. The
Fred Drake3adf79e2001-10-12 19:01:43 +00002732 \var{destr} function will be called when the object is reclaimed.
2733 The \var{desc} argument can be used to pass extra callback data for
2734 the destructor function.
2735\end{cfuncdesc}
2736
2737\begin{cfuncdesc}{void*}{PyCObject_AsVoidPtr}{PyObject* self}
Martin v. Löwis01a74b22003-10-19 18:30:01 +00002738 Return the object \ctype{void *} that the \ctype{PyCObject}
Fred Drake3adf79e2001-10-12 19:01:43 +00002739 \var{self} was created with.
2740\end{cfuncdesc}
2741
2742\begin{cfuncdesc}{void*}{PyCObject_GetDesc}{PyObject* self}
Martin v. Löwis01a74b22003-10-19 18:30:01 +00002743 Return the description \ctype{void *} that the \ctype{PyCObject}
Fred Drake3adf79e2001-10-12 19:01:43 +00002744 \var{self} was created with.
2745\end{cfuncdesc}
Fred Drakecd8474e2001-11-26 21:29:17 +00002746
Martin v. Löwis01a74b22003-10-19 18:30:01 +00002747\begin{cfuncdesc}{int}{PyCObject_SetVoidPtr}{PyObject* self, void* cobj}
Tim Peters9ddf40b2004-06-20 22:41:32 +00002748 Set the void pointer inside \var{self} to \var{cobj}.
Martin v. Löwis01a74b22003-10-19 18:30:01 +00002749 The \ctype{PyCObject} must not have an associated destructor.
2750 Return true on success, false on failure.
2751\end{cfuncdesc}
2752
Fred Drakecd8474e2001-11-26 21:29:17 +00002753
2754\subsection{Cell Objects \label{cell-objects}}
2755
2756``Cell'' objects are used to implement variables referenced by
2757multiple scopes. For each such variable, a cell object is created to
2758store the value; the local variables of each stack frame that
2759references the value contains a reference to the cells from outer
2760scopes which also use that variable. When the value is accessed, the
2761value contained in the cell is used instead of the cell object
2762itself. This de-referencing of the cell object requires support from
2763the generated byte-code; these are not automatically de-referenced
2764when accessed. Cell objects are not likely to be useful elsewhere.
2765
Fred Drake54e62942001-12-11 19:40:16 +00002766\begin{ctypedesc}{PyCellObject}
2767 The C structure used for cell objects.
2768\end{ctypedesc}
2769
Fred Drakecd8474e2001-11-26 21:29:17 +00002770\begin{cvardesc}{PyTypeObject}{PyCell_Type}
Georg Brandl9b743f52006-02-20 12:57:53 +00002771 The type object corresponding to cell objects.
Fred Drakecd8474e2001-11-26 21:29:17 +00002772\end{cvardesc}
2773
2774\begin{cfuncdesc}{int}{PyCell_Check}{ob}
2775 Return true if \var{ob} is a cell object; \var{ob} must not be
Tim Peters9ddf40b2004-06-20 22:41:32 +00002776 \NULL{}.
Fred Drakecd8474e2001-11-26 21:29:17 +00002777\end{cfuncdesc}
2778
2779\begin{cfuncdesc}{PyObject*}{PyCell_New}{PyObject *ob}
2780 Create and return a new cell object containing the value \var{ob}.
Tim Peters9ddf40b2004-06-20 22:41:32 +00002781 The parameter may be \NULL{}.
Fred Drakecd8474e2001-11-26 21:29:17 +00002782\end{cfuncdesc}
2783
2784\begin{cfuncdesc}{PyObject*}{PyCell_Get}{PyObject *cell}
2785 Return the contents of the cell \var{cell}.
2786\end{cfuncdesc}
2787
2788\begin{cfuncdesc}{PyObject*}{PyCell_GET}{PyObject *cell}
2789 Return the contents of the cell \var{cell}, but without checking
Raymond Hettingerf4bb1f92003-08-23 03:38:11 +00002790 that \var{cell} is non-\NULL{} and a cell object.
Fred Drakecd8474e2001-11-26 21:29:17 +00002791\end{cfuncdesc}
2792
2793\begin{cfuncdesc}{int}{PyCell_Set}{PyObject *cell, PyObject *value}
2794 Set the contents of the cell object \var{cell} to \var{value}. This
2795 releases the reference to any current content of the cell.
Tim Peters9ddf40b2004-06-20 22:41:32 +00002796 \var{value} may be \NULL{}. \var{cell} must be non-\NULL{}; if it is
Fred Drakecd8474e2001-11-26 21:29:17 +00002797 not a cell object, \code{-1} will be returned. On success, \code{0}
2798 will be returned.
2799\end{cfuncdesc}
2800
2801\begin{cfuncdesc}{void}{PyCell_SET}{PyObject *cell, PyObject *value}
2802 Sets the value of the cell object \var{cell} to \var{value}. No
2803 reference counts are adjusted, and no checks are made for safety;
2804 \var{cell} must be non-\NULL{} and must be a cell object.
2805\end{cfuncdesc}
Martin v. Löwise440e472004-06-01 15:22:42 +00002806
2807
2808\subsection{Generator Objects \label{gen-objects}}
2809
2810Generator objects are what Python uses to implement generator iterators.
2811They are normally created by iterating over a function that yields values,
2812rather than explicitly calling \cfunction{PyGen_New}.
2813
2814\begin{ctypedesc}{PyGenObject}
2815 The C structure used for generator objects.
2816\end{ctypedesc}
2817
2818\begin{cvardesc}{PyTypeObject}{PyGen_Type}
2819 The type object corresponding to generator objects
2820\end{cvardesc}
2821
2822\begin{cfuncdesc}{int}{PyGen_Check}{ob}
2823 Return true if \var{ob} is a generator object; \var{ob} must not be
Tim Peters9ddf40b2004-06-20 22:41:32 +00002824 \NULL{}.
Martin v. Löwise440e472004-06-01 15:22:42 +00002825\end{cfuncdesc}
2826
2827\begin{cfuncdesc}{int}{PyGen_CheckExact}{ob}
2828 Return true if \var{ob}'s type is \var{PyGen_Type}
2829 is a generator object; \var{ob} must not be
Tim Peters9ddf40b2004-06-20 22:41:32 +00002830 \NULL{}.
Martin v. Löwise440e472004-06-01 15:22:42 +00002831\end{cfuncdesc}
2832
2833\begin{cfuncdesc}{PyObject*}{PyGen_New}{PyFrameObject *frame}
2834 Create and return a new generator object based on the \var{frame} object.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00002835 A reference to \var{frame} is stolen by this function.
Tim Peters9ddf40b2004-06-20 22:41:32 +00002836 The parameter must not be \NULL{}.
2837\end{cfuncdesc}
2838
2839
2840\subsection{DateTime Objects \label{datetime-objects}}
2841
2842Various date and time objects are supplied by the \module{datetime}
2843module. Before using any of these functions, the header file
2844\file{datetime.h} must be included in your source (note that this is
2845not include by \file{Python.h}), and macro \cfunction{PyDateTime_IMPORT()}
2846must be invoked. The macro arranges to put a pointer to a C structure
2847in a static variable \code{PyDateTimeAPI}, which is used by the following
Tim Peters183dabc2004-07-11 19:26:19 +00002848macros.
Tim Peters9ddf40b2004-06-20 22:41:32 +00002849
Tim Peters183dabc2004-07-11 19:26:19 +00002850Type-check macros:
2851
2852\begin{cfuncdesc}{int}{PyDate_Check}{PyObject *ob}
Tim Peters9ddf40b2004-06-20 22:41:32 +00002853 Return true if \var{ob} is of type \cdata{PyDateTime_DateType} or
2854 a subtype of \cdata{PyDateTime_DateType}. \var{ob} must not be
2855 \NULL{}.
2856 \versionadded{2.4}
2857\end{cfuncdesc}
2858
Tim Peters183dabc2004-07-11 19:26:19 +00002859\begin{cfuncdesc}{int}{PyDate_CheckExact}{PyObject *ob}
Tim Peters9ddf40b2004-06-20 22:41:32 +00002860 Return true if \var{ob} is of type \cdata{PyDateTime_DateType}.
2861 \var{ob} must not be \NULL{}.
2862 \versionadded{2.4}
2863\end{cfuncdesc}
2864
Tim Peters183dabc2004-07-11 19:26:19 +00002865\begin{cfuncdesc}{int}{PyDateTime_Check}{PyObject *ob}
Tim Peters9ddf40b2004-06-20 22:41:32 +00002866 Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType} or
2867 a subtype of \cdata{PyDateTime_DateTimeType}. \var{ob} must not be
2868 \NULL{}.
2869 \versionadded{2.4}
2870\end{cfuncdesc}
2871
Tim Peters183dabc2004-07-11 19:26:19 +00002872\begin{cfuncdesc}{int}{PyDateTime_CheckExact}{PyObject *ob}
Tim Peters9ddf40b2004-06-20 22:41:32 +00002873 Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType}.
2874 \var{ob} must not be \NULL{}.
2875 \versionadded{2.4}
2876\end{cfuncdesc}
2877
Tim Peters183dabc2004-07-11 19:26:19 +00002878\begin{cfuncdesc}{int}{PyTime_Check}{PyObject *ob}
Tim Peters9ddf40b2004-06-20 22:41:32 +00002879 Return true if \var{ob} is of type \cdata{PyDateTime_TimeType} or
2880 a subtype of \cdata{PyDateTime_TimeType}. \var{ob} must not be
2881 \NULL{}.
2882 \versionadded{2.4}
2883\end{cfuncdesc}
2884
Tim Peters183dabc2004-07-11 19:26:19 +00002885\begin{cfuncdesc}{int}{PyTime_CheckExact}{PyObject *ob}
Tim Peters9ddf40b2004-06-20 22:41:32 +00002886 Return true if \var{ob} is of type \cdata{PyDateTime_TimeType}.
2887 \var{ob} must not be \NULL{}.
2888 \versionadded{2.4}
2889\end{cfuncdesc}
2890
Tim Peters183dabc2004-07-11 19:26:19 +00002891\begin{cfuncdesc}{int}{PyDelta_Check}{PyObject *ob}
Tim Peters9ddf40b2004-06-20 22:41:32 +00002892 Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType} or
2893 a subtype of \cdata{PyDateTime_DeltaType}. \var{ob} must not be
2894 \NULL{}.
2895 \versionadded{2.4}
2896\end{cfuncdesc}
2897
Tim Peters183dabc2004-07-11 19:26:19 +00002898\begin{cfuncdesc}{int}{PyDelta_CheckExact}{PyObject *ob}
Tim Peters9ddf40b2004-06-20 22:41:32 +00002899 Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType}.
2900 \var{ob} must not be \NULL{}.
2901 \versionadded{2.4}
2902\end{cfuncdesc}
2903
Tim Peters183dabc2004-07-11 19:26:19 +00002904\begin{cfuncdesc}{int}{PyTZInfo_Check}{PyObject *ob}
Tim Peters9ddf40b2004-06-20 22:41:32 +00002905 Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType} or
2906 a subtype of \cdata{PyDateTime_TZInfoType}. \var{ob} must not be
2907 \NULL{}.
2908 \versionadded{2.4}
2909\end{cfuncdesc}
2910
Tim Peters183dabc2004-07-11 19:26:19 +00002911\begin{cfuncdesc}{int}{PyTZInfo_CheckExact}{PyObject *ob}
Tim Peters9ddf40b2004-06-20 22:41:32 +00002912 Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType}.
2913 \var{ob} must not be \NULL{}.
2914 \versionadded{2.4}
2915\end{cfuncdesc}
2916
Tim Peters183dabc2004-07-11 19:26:19 +00002917Macros to create objects:
2918
Tim Peters9ddf40b2004-06-20 22:41:32 +00002919\begin{cfuncdesc}{PyObject*}{PyDate_FromDate}{int year, int month, int day}
2920 Return a \code{datetime.date} object with the specified year, month
2921 and day.
2922 \versionadded{2.4}
2923\end{cfuncdesc}
2924
Brett Cannon5bbe6ad2005-02-17 05:17:17 +00002925\begin{cfuncdesc}{PyObject*}{PyDateTime_FromDateAndTime}{int year, int month,
Tim Peters9ddf40b2004-06-20 22:41:32 +00002926 int day, int hour, int minute, int second, int usecond}
2927 Return a \code{datetime.datetime} object with the specified year, month,
2928 day, hour, minute, second and microsecond.
2929 \versionadded{2.4}
2930\end{cfuncdesc}
2931
2932\begin{cfuncdesc}{PyObject*}{PyTime_FromTime}{int hour, int minute,
2933 int second, int usecond}
2934 Return a \code{datetime.time} object with the specified hour, minute,
2935 second and microsecond.
2936 \versionadded{2.4}
2937\end{cfuncdesc}
2938
2939\begin{cfuncdesc}{PyObject*}{PyDelta_FromDSU}{int days, int seconds,
2940 int useconds}
2941 Return a \code{datetime.timedelta} object representing the given number
2942 of days, seconds and microseconds. Normalization is performed so that
2943 the resulting number of microseconds and seconds lie in the ranges
2944 documented for \code{datetime.timedelta} objects.
2945 \versionadded{2.4}
2946\end{cfuncdesc}
2947
Tim Peters8ff9f9f2004-07-17 01:42:26 +00002948Macros to extract fields from date objects. The argument must be an
Tim Peters183dabc2004-07-11 19:26:19 +00002949instance of \cdata{PyDateTime_Date}, including subclasses (such as
2950\cdata{PyDateTime_DateTime}). The argument must not be \NULL{}, and
2951the type is not checked:
2952
2953\begin{cfuncdesc}{int}{PyDateTime_GET_YEAR}{PyDateTime_Date *o}
2954 Return the year, as a positive int.
2955 \versionadded{2.4}
2956\end{cfuncdesc}
2957
2958\begin{cfuncdesc}{int}{PyDateTime_GET_MONTH}{PyDateTime_Date *o}
2959 Return the month, as an int from 1 through 12.
2960 \versionadded{2.4}
2961\end{cfuncdesc}
2962
2963\begin{cfuncdesc}{int}{PyDateTime_GET_DAY}{PyDateTime_Date *o}
2964 Return the day, as an int from 1 through 31.
2965 \versionadded{2.4}
2966\end{cfuncdesc}
2967
Tim Peters8ff9f9f2004-07-17 01:42:26 +00002968Macros to extract fields from datetime objects. The argument must be an
Tim Peters183dabc2004-07-11 19:26:19 +00002969instance of \cdata{PyDateTime_DateTime}, including subclasses.
2970The argument must not be \NULL{}, and the type is not checked:
2971
2972\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_HOUR}{PyDateTime_DateTime *o}
Neal Norwitz7fdd92f2004-08-02 21:56:33 +00002973 Return the hour, as an int from 0 through 23.
Tim Peters183dabc2004-07-11 19:26:19 +00002974 \versionadded{2.4}
2975\end{cfuncdesc}
2976
2977\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MINUTE}{PyDateTime_DateTime *o}
2978 Return the minute, as an int from 0 through 59.
2979 \versionadded{2.4}
2980\end{cfuncdesc}
2981
2982\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_SECOND}{PyDateTime_DateTime *o}
2983 Return the second, as an int from 0 through 59.
2984 \versionadded{2.4}
2985\end{cfuncdesc}
2986
2987\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MICROSECOND}{PyDateTime_DateTime *o}
2988 Return the microsecond, as an int from 0 through 999999.
2989 \versionadded{2.4}
2990\end{cfuncdesc}
2991
Tim Peters8ff9f9f2004-07-17 01:42:26 +00002992Macros to extract fields from time objects. The argument must be an
Tim Peters183dabc2004-07-11 19:26:19 +00002993instance of \cdata{PyDateTime_Time}, including subclasses.
2994The argument must not be \NULL{}, and the type is not checked:
2995
2996\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_HOUR}{PyDateTime_Time *o}
Neal Norwitz7fdd92f2004-08-02 21:56:33 +00002997 Return the hour, as an int from 0 through 23.
Tim Peters183dabc2004-07-11 19:26:19 +00002998 \versionadded{2.4}
2999\end{cfuncdesc}
3000
3001\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MINUTE}{PyDateTime_Time *o}
3002 Return the minute, as an int from 0 through 59.
3003 \versionadded{2.4}
3004\end{cfuncdesc}
3005
3006\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_SECOND}{PyDateTime_Time *o}
3007 Return the second, as an int from 0 through 59.
3008 \versionadded{2.4}
3009\end{cfuncdesc}
3010
3011\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MICROSECOND}{PyDateTime_Time *o}
3012 Return the microsecond, as an int from 0 through 999999.
3013 \versionadded{2.4}
3014\end{cfuncdesc}
3015
3016Macros for the convenience of modules implementing the DB API:
3017
Tim Peters9ddf40b2004-06-20 22:41:32 +00003018\begin{cfuncdesc}{PyObject*}{PyDateTime_FromTimestamp}{PyObject *args}
3019 Create and return a new \code{datetime.datetime} object given an argument
3020 tuple suitable for passing to \code{datetime.datetime.fromtimestamp()}.
Tim Peters9ddf40b2004-06-20 22:41:32 +00003021 \versionadded{2.4}
3022\end{cfuncdesc}
3023
3024\begin{cfuncdesc}{PyObject*}{PyDate_FromTimestamp}{PyObject *args}
3025 Create and return a new \code{datetime.date} object given an argument
3026 tuple suitable for passing to \code{datetime.date.fromtimestamp()}.
Tim Peters9ddf40b2004-06-20 22:41:32 +00003027 \versionadded{2.4}
Martin v. Löwise440e472004-06-01 15:22:42 +00003028\end{cfuncdesc}
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003029
3030
3031\subsection{Set Objects \label{setObjects}}
Thomas Wouters477c8d52006-05-27 19:21:47 +00003032\sectionauthor{Raymond D. Hettinger}{python@rcn.com}
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003033
3034\obindex{set}
3035\obindex{frozenset}
3036\versionadded{2.5}
3037
3038This section details the public API for \class{set} and \class{frozenset}
3039objects. Any functionality not listed below is best accessed using the
Raymond Hettinger0c230b92005-08-17 10:05:22 +00003040either the abstract object protocol (including
Thomas Wouters477c8d52006-05-27 19:21:47 +00003041\cfunction{PyObject_CallMethod()}, \cfunction{PyObject_RichCompareBool()},
3042\cfunction{PyObject_Hash()}, \cfunction{PyObject_Repr()},
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003043\cfunction{PyObject_IsTrue()}, \cfunction{PyObject_Print()}, and
Raymond Hettinger0c230b92005-08-17 10:05:22 +00003044\cfunction{PyObject_GetIter()})
3045or the abstract number protocol (including
3046\cfunction{PyNumber_Add()}, \cfunction{PyNumber_Subtract()},
3047\cfunction{PyNumber_Or()}, \cfunction{PyNumber_Xor()},
Georg Brandlb518d8c2006-02-22 11:46:55 +00003048\cfunction{PyNumber_InPlaceAdd()}, \cfunction{PyNumber_InPlaceSubtract()},
3049\cfunction{PyNumber_InPlaceOr()}, and \cfunction{PyNumber_InPlaceXor()}).
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00003050
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003051\begin{ctypedesc}{PySetObject}
3052 This subtype of \ctype{PyObject} is used to hold the internal data for
3053 both \class{set} and \class{frozenset} objects. It is like a
3054 \ctype{PyDictObject} in that it is a fixed size for small sets
3055 (much like tuple storage) and will point to a separate, variable sized
3056 block of memory for medium and large sized sets (much like list storage).
3057 None of the fields of this structure should be considered public and
3058 are subject to change. All access should be done through the
Thomas Wouters477c8d52006-05-27 19:21:47 +00003059 documented API rather than by manipulating the values in the structure.
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003060
3061\end{ctypedesc}
3062
3063\begin{cvardesc}{PyTypeObject}{PySet_Type}
3064 This is an instance of \ctype{PyTypeObject} representing the Python
3065 \class{set} type.
3066\end{cvardesc}
3067
3068\begin{cvardesc}{PyTypeObject}{PyFrozenSet_Type}
3069 This is an instance of \ctype{PyTypeObject} representing the Python
3070 \class{frozenset} type.
3071\end{cvardesc}
3072
3073
3074The following type check macros work on pointers to any Python object.
3075Likewise, the constructor functions work with any iterable Python object.
3076
3077\begin{cfuncdesc}{int}{PyAnySet_Check}{PyObject *p}
Thomas Wouters477c8d52006-05-27 19:21:47 +00003078 Return true if \var{p} is a \class{set} object, a \class{frozenset}
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003079 object, or an instance of a subtype.
3080\end{cfuncdesc}
3081
3082\begin{cfuncdesc}{int}{PyAnySet_CheckExact}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00003083 Return true if \var{p} is a \class{set} object or a \class{frozenset}
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003084 object but not an instance of a subtype.
3085\end{cfuncdesc}
3086
3087\begin{cfuncdesc}{int}{PyFrozenSet_CheckExact}{PyObject *p}
Georg Brandl99363b62005-09-03 07:27:26 +00003088 Return true if \var{p} is a \class{frozenset} object
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003089 but not an instance of a subtype.
3090\end{cfuncdesc}
3091
3092\begin{cfuncdesc}{PyObject*}{PySet_New}{PyObject *iterable}
Georg Brandl99363b62005-09-03 07:27:26 +00003093 Return a new \class{set} containing objects returned by the
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003094 \var{iterable}. The \var{iterable} may be \NULL{} to create a
Georg Brandl99363b62005-09-03 07:27:26 +00003095 new empty set. Return the new set on success or \NULL{} on
3096 failure. Raise \exception{TypeError} if \var{iterable} is
Raymond Hettinger94fedf92005-08-17 12:23:45 +00003097 not actually iterable. The constructor is also useful for
3098 copying a set (\code{c=set(s)}).
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003099\end{cfuncdesc}
3100
3101\begin{cfuncdesc}{PyObject*}{PyFrozenSet_New}{PyObject *iterable}
Georg Brandl99363b62005-09-03 07:27:26 +00003102 Return a new \class{frozenset} containing objects returned by the
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003103 \var{iterable}. The \var{iterable} may be \NULL{} to create a
Georg Brandl99363b62005-09-03 07:27:26 +00003104 new empty frozenset. Return the new set on success or \NULL{} on
3105 failure. Raise \exception{TypeError} if \var{iterable} is
Raymond Hettingerc47e01d2005-08-16 10:44:15 +00003106 not actually iterable.
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003107\end{cfuncdesc}
3108
3109
3110The following functions and macros are available for instances of
3111\class{set} or \class{frozenset} or instances of their subtypes.
3112
3113\begin{cfuncdesc}{int}{PySet_Size}{PyObject *anyset}
Georg Brandl99363b62005-09-03 07:27:26 +00003114 Return the length of a \class{set} or \class{frozenset} object.
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003115 Equivalent to \samp{len(\var{anyset})}. Raises a
Raymond Hettingerc47e01d2005-08-16 10:44:15 +00003116 \exception{PyExc_SystemError} if \var{anyset} is not a \class{set},
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003117 \class{frozenset}, or an instance of a subtype.
3118 \bifuncindex{len}
3119\end{cfuncdesc}
3120
3121\begin{cfuncdesc}{int}{PySet_GET_SIZE}{PyObject *anyset}
3122 Macro form of \cfunction{PySet_Size()} without error checking.
3123\end{cfuncdesc}
3124
3125\begin{cfuncdesc}{int}{PySet_Contains}{PyObject *anyset, PyObject *key}
Georg Brandl99363b62005-09-03 07:27:26 +00003126 Return 1 if found, 0 if not found, and -1 if an error is
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003127 encountered. Unlike the Python \method{__contains__()} method, this
3128 function does not automatically convert unhashable sets into temporary
Georg Brandl99363b62005-09-03 07:27:26 +00003129 frozensets. Raise a \exception{TypeError} if the \var{key} is unhashable.
3130 Raise \exception{PyExc_SystemError} if \var{anyset} is not a \class{set},
Thomas Wouters477c8d52006-05-27 19:21:47 +00003131 \class{frozenset}, or an instance of a subtype.
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003132\end{cfuncdesc}
3133
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003134The following functions are available for instances of \class{set} or
3135its subtypes but not for instances of \class{frozenset} or its subtypes.
3136
3137\begin{cfuncdesc}{int}{PySet_Add}{PyObject *set, PyObject *key}
Georg Brandl99363b62005-09-03 07:27:26 +00003138 Add \var{key} to a \class{set} instance. Does not apply to
3139 \class{frozenset} instances. Return 0 on success or -1 on failure.
3140 Raise a \exception{TypeError} if the \var{key} is unhashable.
3141 Raise a \exception{MemoryError} if there is no room to grow.
3142 Raise a \exception{SystemError} if \var{set} is an not an instance
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003143 of \class{set} or its subtype.
3144\end{cfuncdesc}
3145
Raymond Hettingerc47e01d2005-08-16 10:44:15 +00003146\begin{cfuncdesc}{int}{PySet_Discard}{PyObject *set, PyObject *key}
Georg Brandl99363b62005-09-03 07:27:26 +00003147 Return 1 if found and removed, 0 if not found (no action taken),
Raymond Hettingerc47e01d2005-08-16 10:44:15 +00003148 and -1 if an error is encountered. Does not raise \exception{KeyError}
Georg Brandl99363b62005-09-03 07:27:26 +00003149 for missing keys. Raise a \exception{TypeError} if the \var{key} is
Raymond Hettingerc47e01d2005-08-16 10:44:15 +00003150 unhashable. Unlike the Python \method{discard()} method, this function
3151 does not automatically convert unhashable sets into temporary frozensets.
Georg Brandl99363b62005-09-03 07:27:26 +00003152 Raise \exception{PyExc_SystemError} if \var{set} is an not an instance
Thomas Wouters477c8d52006-05-27 19:21:47 +00003153 of \class{set} or its subtype.
Raymond Hettingerc47e01d2005-08-16 10:44:15 +00003154\end{cfuncdesc}
3155
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003156\begin{cfuncdesc}{PyObject*}{PySet_Pop}{PyObject *set}
Georg Brandl99363b62005-09-03 07:27:26 +00003157 Return a new reference to an arbitrary object in the \var{set},
3158 and removes the object from the \var{set}. Return \NULL{} on
3159 failure. Raise \exception{KeyError} if the set is empty.
3160 Raise a \exception{SystemError} if \var{set} is an not an instance
Thomas Wouters477c8d52006-05-27 19:21:47 +00003161 of \class{set} or its subtype.
Raymond Hettingerbeb31012005-08-16 03:47:52 +00003162\end{cfuncdesc}
3163
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00003164\begin{cfuncdesc}{int}{PySet_Clear}{PyObject *set}
3165 Empty an existing set of all elements.
3166\end{cfuncdesc}