About the Python Documentation

index.html | About the Python Documentation
Up:
Python Documentation Index (index.html)
---
## About the Python Documentation
The Python documentation was originally written by Guido van
Rossum, but has increasingly become a community effort over the
past several years. This growing collection of documents is
available in several formats, including typeset versions in PDF
and PostScript for printing, from the Python Web site (http://www.python.org/).
A list of contributors (acks.html) is available.
## Comments and Questions
General comments and questions regarding this document should
be sent by email to python-docs@python.org (mailto:python-docs@python.org). If you find specific errors in
this document, please report the bug at the Python Bug
Tracker (http://sourceforge.net/bugs/?group_id=5470) at SourceForge (http://sourceforge.net/).
Questions regarding how to use the information in this
document should be sent to the Python news group, comp.lang.python (news:comp.lang.python), or the Python mailing list (http://www.python.org/mailman/listinfo/python-list) (which is gated to the newsgroup and
carries the same content).
For any of these channels, please be sure not to send HTML email.
Thanks.
---


Acknowledgements

index.html | Acknowledgements
---
## Acknowledgements
These people have contributed in some way to the Python
documentation. This list is probably not complete -- if you feel that
you or anyone else should be on this list, please let us know (send
email to python-docs@python.org (mailto:python-docs@python.org)), and
we will be glad to correct the problem.
It is only with the input and contributions of the Python community
that Python has such wonderful documentation -- Thank You!
Aahz | Ben Gertzfield | Detlef Lannert | Donald Wallace Rouse II
Michael Abbott | Nadim Ghaznavi | Piers Lauder | Nick Russo
Steve Alexander | Jonathan Giddy | Glyph Lefkowitz | Chris Ryland
Jim Ahlstrom | Shelley Gooch | Marc-Andr Lemburg | Constantina S.
Fred Allen | Nathaniel Gray | Ulf A. Lindgren | Hugh Sasse
A. Amoroso | Grant Griffin | Everett Lipman | Bob Savage
Pehr Anderson | Thomas Guettler | Mirko Liss | Scott Schram
Oliver Andrich | Anders Hammarquist | Martin von Lwis | Neil Schemenauer
Jess Cea Avin | Mark Hammond | Fredrik Lundh | Barry Scott
Daniel Barclay | Harald Hanche-Olsen | Jeff MacDonald | Joakim Sernbrant
Chris Barker | Manus Hand | John Machin | Justin Sheehy
Don Bashford | Gerhard Hring | Andrew MacIntyre | Michael Simcich
Anthony Baxter | Travis B. Hartwell | Vladimir Marangozov | Ionel Simionescu
Bennett Benson | Janko Hauser | Vincent Marchetti | Roy Smith
Jonathan Black | Bernhard Herzog | Laura Matson | Clay Spence
Robin Boerdijk | Magnus L. Hetland | Daniel May | Nicholas Spies
Michal Bozon | Konrad Hinsen | Doug Mennella | Tage Stabell-Kulo
Aaron Brancotti | Stefan Hoffmeister | Paolo Milani | Frank Stajano
Keith Briggs | Albert Hofkamp | Skip Montanaro | Anthony Starks
Lee Busby | Gregor Hoffleit | Paul Moore | Greg Stein
Lorenzo M. Catucci | Steve Holden | Ross Moore | Peter Stoehr
Mauro Cicognini | Thomas Holenstein | Sjoerd Mullender | Mark Summerfield
Gilles Civario | Gerrit Holl | Dale Nagata | Reuben Sumner
Mike Clarkson | Rob Hooft | Ng Pheng Siong | Kalle Svensson
Steve Clift | Brian Hooper | Koray Oner | Jim Tittsler
Dave Cole | Randall Hopper | Tomas Oppelstrup | Ville Vainio
Matthew Cowles | Michael Hudson | Denis S. Otkidach | Martijn Vries
Jeremy Craven | Eric Huss | Zooko O'Whielacronx | Charles G. Waldman
Andrew Dalke | Jeremy Hylton | William Park | Greg Ward
Ben Darnell | Roger Irwin | Joonas Paalasmaa | Barry Warsaw
L. Peter Deutsch | Jack Jansen | Harri Pasanen | Corran Webster
Robert Donohue | Philip H. Jensen | Tim Peters | Glyn Webster
Fred L. Drake, Jr. | Pedro Diaz Jimenez | Christopher Petrilli | Bob Weiner
Jeff Epler | Lucas de Jonge | Justin D. Pettit | Eddy Welbourne
Michael Ernst | Andreas Jung | Chris Phoenix | Mats Wichmann
Blame Andy Eskilsson | Robert Kern | Franois Pinard | Gerry Wiener
Carey Evans | Jim Kerr | Paul Prescod | Timothy Wild
Martijn Faassen | Jan Kim | Eric S. Raymond | Blake Winton
Carl Feynman | Greg Kochanski | Edward K. Ream | Dan Wolfe
Hernn Martnez Foffani | Guido Kollerie | Sean Reifschneider | Steven Work
Stefan Franke | Peter A. Koren | Bernhard Reiter | Thomas Wouters
Jim Fulton | Daniel Kozan | Armin Rigo | Ka-Ping Yee
Peter Funk | Andrew M. Kuchling | Wes Rishel | Moshe Zadka
Lele Gaifax | Dave Kuhlman | Jim Roskind | Milan Zamazal
Matthew Gallagher | Erno Kuusela | Guido van Rossum | Cheng Zhang
---
index.html | Acknowledgements


About this document ...

genindex.html | api.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
Up:
Python/C API Reference Manual (api.html)
---
# About this document ...
Python/C API Reference Manual,
July 29, 2003, Release 2.3
This document was generated using the LaTeX2HTML (http://saftsack.fs.uni-bayreuth.de/~latex2ht/) translator.
LaTeX2HTML (http://saftsack.fs.uni-bayreuth.de/~latex2ht/) is Copyright ©
1993, 1994, 1995, 1996, 1997, Nikos
Drakos (http://cbl.leeds.ac.uk/nikos/personal.html), Computer Based Learning Unit, University of
Leeds, and Copyright © 1997, 1998, Ross
Moore (http://www.maths.mq.edu.au/~ross/), Mathematics Department, Macquarie University,
Sydney.
The application of LaTeX2HTML (http://saftsack.fs.uni-bayreuth.de/~latex2ht/) to the Python
documentation has been heavily tailored by Fred L. Drake,
Jr. Original navigation icons were contributed by Christopher
Petrilli.
---
## Comments and Questions
General comments and questions regarding this document should
be sent by email to python-docs@python.org (mailto:python-docs@python.org). If you find specific errors in
this document, either in the content or the presentation, please
report the bug at the Python Bug
Tracker (http://sourceforge.net/bugs/?group_id=5470) at SourceForge (http://sourceforge.net/).
Questions regarding how to use the information in this
document should be sent to the Python news group, comp.lang.python (news:comp.lang.python), or the Python mailing list (http://www.python.org/mailman/listinfo/python-list) (which is gated to the newsgroup and
carries the same content).
For any of these channels, please be sure not to send HTML email.
Thanks.


6.6 Buffer Protocol

iterator.html | abstract.html | concrete.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
6.5 Iterator Protocol (iterator.html)
Up:
6. Abstract Objects Layer (abstract.html)
Next:
7. Concrete Objects Layer (concrete.html)
---
# 6.6 Buffer Protocol


6. Abstract Objects Layer

arg-parsing.html | api.html | object.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
5.5 Parsing arguments and (arg-parsing.html)
Up:
Python/C API Reference Manual (api.html)
Next:
6.1 Object Protocol (object.html)
---
# 6. Abstract Objects Layer
The functions in this chapter interact with Python objects regardless
of their type, or with wide classes of object types (e.g. all
numerical types, or all sequence types). When used on object types
for which they do not apply, they will raise a Python exception.


8.3 Advanced Debugger Support

profiling.html | initialization.html | memory.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
8.2 Profiling and Tracing (profiling.html)
Up:
8. Initialization, Finalization, and (initialization.html)
Next:
9. Memory Management (memory.html)
---
# 8.3 Advanced Debugger Support
These functions are only intended to be used by advanced debugging
tools.


10.1 Allocating Objects on the Heap

newTypes.html | newTypes.html | common-structs.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
10. Object Implementation Support (newTypes.html)
Up:
10. Object Implementation Support (newTypes.html)
Next:
10.2 Common Object Structures (common-structs.html)
---
# 10.1 Allocating Objects on the Heap
DL_IMPORT


Python/C API Reference Manual

../index.html | front.html | Python/C API Reference Manual | contents.html | genindex.html
Up:
Python Documentation Index (../index.html)
Next:
Front Matter (front.html)
---
# Python/C API Reference Manual
Guido van Rossum
Fred L. Drake, Jr., editor
PythonLabs
Email: python-docs@python.org
Release 2.3
July 29, 2003


marshalling-utils.html | utilities.html | abstract.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
5.4 Data marshalling support (marshalling-utils.html)
Up:
5. Utilities (utilities.html)
Next:
6. Abstract Objects Layer (abstract.html)
---
# 5.5 Parsing arguments and building values
These functions are useful when creating your own extensions functions
and methods. Additional information and examples are available in
Extending and Embedding the Python
Interpreter (../ext/ext.html).
The first three of these functions described,
PyArg_ParseTuple(),
PyArg_ParseTupleAndKeywords(), and
PyArg_Parse(), all use format strings which are
used to tell the function about the expected arguments. The format
strings use the same syntax for each of these functions.
A format string consists of zero or more ``format units.'' A format
unit describes one Python object; it is usually a single character or
a parenthesized sequence of format units. With a few exceptions, a
format unit that is not a parenthesized sequence normally corresponds
to a single address argument to these functions. In the following
description, the quoted form is the format unit; the entry in (round)
parentheses is the Python object type that matches the format unit;
and the entry in [square] brackets is the type of the C variable(s)
whose address should be passed.
"s" (string or Unicode object) [char *]: Convert a Python string or Unicode object to a C pointer to a
character string. You must not provide storage for the string
itself; a pointer to an existing string is stored into the character
pointer variable whose address you pass. The C string is
NUL-terminated. The Python string must not contain embedded NUL
bytes; if it does, a TypeError exception is raised.
Unicode objects are converted to C strings using the default
encoding. If this conversion fails, a UnicodeError is
raised.
"s#" (string, Unicode or any read buffer compatible object)
[char *, int]: This variant on "s" stores into two C variables, the first one
a pointer to a character string, the second one its length. In this
case the Python string may contain embedded null bytes. Unicode
objects pass back a pointer to the default encoded string version of
the object if such a conversion is possible. All other read-buffer
compatible objects pass back a reference to the raw internal data
representation.
"z" (string or `None`) [char *]: Like "s", but the Python object may also be `None`, in
which case the C pointer is set to NULL.
"z#" (string or `None` or any read buffer
compatible object) [char *, int]: This is to "s#" as "z" is to "s".
"u" (Unicode object) [Py_UNICODE *]: Convert a Python Unicode object to a C pointer to a NUL-terminated
buffer of 16-bit Unicode (UTF-16) data. As with "s", there is
no need to provide storage for the Unicode data buffer; a pointer to
the existing Unicode data is stored into the Py_UNICODE
pointer variable whose address you pass.
"u#" (Unicode object) [Py_UNICODE *, int]: This variant on "u" stores into two C variables, the first one
a pointer to a Unicode data buffer, the second one its length.
Non-Unicode objects are handled by interpreting their read-buffer
pointer as pointer to a Py_UNICODE array.
"es" (string, Unicode object or character buffer
compatible object) [const char *encoding, char **buffer]: This variant on "s" is used for encoding Unicode and objects
convertible to Unicode into a character buffer. It only works for
encoded data without embedded NUL bytes.
This format requires two arguments. The first is only used as
input, and must be a char* which points to the name of an
encoding as a NUL-terminated string, or NULL, in which case the
default encoding is used. An exception is raised if the named
encoding is not known to Python. The second argument must be a
char**; the value of the pointer it references will be set
to a buffer with the contents of the argument text. The text will
be encoded in the encoding specified by the first argument.
PyArg_ParseTuple() will allocate a buffer of the needed
size, copy the encoded data into this buffer and adjust
*buffer to reference the newly allocated storage. The caller
is responsible for calling PyMem_Free() to free the
allocated buffer after use.
"et" (string, Unicode object or character buffer
compatible object) [const char *encoding, char **buffer]: Same as "es" except that 8-bit string objects are passed
through without recoding them. Instead, the implementation assumes
that the string object uses the encoding passed in as parameter.
"es#" (string, Unicode object or character buffer compatible
object) [const char *encoding, char **buffer, int *buffer_length]: This variant on "s#" is used for encoding Unicode and objects
convertible to Unicode into a character buffer. Unlike the
"es" format, this variant allows input data which contains NUL
characters.
It requires three arguments. The first is only used as input, and
must be a char* which points to the name of an encoding as a
NUL-terminated string, or NULL, in which case the default encoding
is used. An exception is raised if the named encoding is not known
to Python. The second argument must be a char**; the value
of the pointer it references will be set to a buffer with the
contents of the argument text. The text will be encoded in the
encoding specified by the first argument. The third argument must
be a pointer to an integer; the referenced integer will be set to
the number of bytes in the output buffer.
There are two modes of operation:
If *buffer points a NULL pointer, the function will
allocate a buffer of the needed size, copy the encoded data into
this buffer and set *buffer to reference the newly allocated
storage. The caller is responsible for calling
PyMem_Free() to free the allocated buffer after usage.
If *buffer points to a non-NULL pointer (an already
allocated buffer), PyArg_ParseTuple() will use this
location as the buffer and interpret the initial value of
*buffer_length as the buffer size. It will then copy the
encoded data into the buffer and NUL-terminate it. If the buffer
is not large enough, a ValueError will be set.
In both cases, *buffer_length is set to the length of the
encoded data without the trailing NUL byte.
"et#" (string, Unicode object or character buffer compatible
object) [const char *encoding, char **buffer]: Same as "es#" except that string objects are passed through
without recoding them. Instead, the implementation assumes that the
string object uses the encoding passed in as parameter.
"b" (integer) [char]: Convert a Python integer to a tiny int, stored in a C char.
"B" (integer) [unsigned char]: Convert a Python integer to a tiny int without overflow checking,
stored in a C unsigned char.
New in version 2.3.
"h" (integer) [short int]: Convert a Python integer to a C short int.
"H" (integer) [unsigned short int]: Convert a Python integer to a C unsigned short int, without
overflow checking.
New in version 2.3.
"i" (integer) [int]: Convert a Python integer to a plain C int.
"I" (integer) [unsigned int]: Convert a Python integer to a C unsigned int, without
overflow checking.
New in version 2.3.
"l" (integer) [long int]: Convert a Python integer to a C long int.
"k" (integer) [unsigned long]: Convert a Python integer to a C unsigned long without
overflow checking.
New in version 2.3.
"L" (integer) [PY_LONG_LONG]: Convert a Python integer to a C long long. This format is
only available on platforms that support long long (or
_int64 on Windows).
"K" (integer) [unsigned PY_LONG_LONG]: Convert a Python integer to a C unsigned long long
without overflow checking. This format is only available on
platforms that support unsigned long long (or
unsigned _int64 on Windows).
New in version 2.3.
"c" (string of length 1) [char]: Convert a Python character, represented as a string of length 1, to
a C char.
"f" (float) [float]: Convert a Python floating point number to a C float.
"d" (float) [double]: Convert a Python floating point number to a C double.
"D" (complex) [Py_complex]: Convert a Python complex number to a C Py_complex structure.
"O" (object) [PyObject *]: Store a Python object (without any conversion) in a C object
pointer. The C program thus receives the actual object that was
passed. The object's reference count is not increased. The pointer
stored is not NULL.
"O!" (object) [typeobject, PyObject *]: Store a Python object in a C object pointer. This is similar to
"O", but takes two C arguments: the first is the address of a
Python type object, the second is the address of the C variable (of
type PyObject*) into which the object pointer is stored. If
the Python object does not have the required type,
TypeError is raised.
"O&" (object) [converter, anything]: Convert a Python object to a C variable through a converter
function. This takes two arguments: the first is a function, the
second is the address of a C variable (of arbitrary type), converted
to void *. The converter function in turn is called
as follows:
status`=`converter`(`object,
address`);`
where object is the Python object to be converted and
address is the void* argument that was passed to the
PyArg_Parse*() function. The returned status
should be `1` for a successful conversion and `0` if the
conversion has failed. When the conversion fails, the
converter function should raise an exception.
"S" (string) [PyStringObject *]: Like "O" but requires that the Python object is a string
object. Raises TypeError if the object is not a string
object. The C variable may also be declared as PyObject*.
"U" (Unicode string) [PyUnicodeObject *]: Like "O" but requires that the Python object is a Unicode
object. Raises TypeError if the object is not a Unicode
object. The C variable may also be declared as PyObject*.
"t#" (read-only character buffer) [char *, int]: Like "s#", but accepts any object which implements the
read-only buffer interface. The char* variable is set to
point to the first byte of the buffer, and the int is set to
the length of the buffer. Only single-segment buffer objects are
accepted; TypeError is raised for all others.
"w" (read-write character buffer) [char *]: Similar to "s", but accepts any object which implements the
read-write buffer interface. The caller must determine the length
of the buffer by other means, or use "w#" instead. Only
single-segment buffer objects are accepted; TypeError is
raised for all others.
"w#" (read-write character buffer) [char *, int]: Like "s#", but accepts any object which implements the
read-write buffer interface. The char * variable is set to
point to the first byte of the buffer, and the int is set to
the length of the buffer. Only single-segment buffer objects are
accepted; TypeError is raised for all others.
"(items)" (tuple) [matching-items]: The object must be a Python sequence whose length is the number of
format units in items. The C arguments must correspond to the
individual format units in items. Format units for sequences
may be nested.
Note:
Prior to Python version 1.5.2, this format specifier only
accepted a tuple containing the individual parameters, not an
arbitrary sequence. Code which previously caused
TypeError to be raised here may now proceed without an
exception. This is not expected to be a problem for existing code.
It is possible to pass Python long integers where integers are
requested; however no proper range checking is done -- the most
significant bits are silently truncated when the receiving field is
too small to receive the value (actually, the semantics are inherited
from downcasts in C -- your mileage may vary).
A few other characters have a meaning in a format string. These may
not occur inside nested parentheses. They are:
"|": Indicates that the remaining arguments in the Python argument list
are optional. The C variables corresponding to optional arguments
should be initialized to their default value -- when an optional
argument is not specified, PyArg_ParseTuple() does not
touch the contents of the corresponding C variable(s).
":": The list of format units ends here; the string after the colon is
used as the function name in error messages (the ``associated
value'' of the exception that PyArg_ParseTuple()
raises).
";": The list of format units ends here; the string after the semicolon
is used as the error message instead of the default error
message. Clearly, ":" and ";" mutually exclude each
other.
Note that any Python object references which are provided to the
caller are borrowed references; do not decrement their
reference count!
Additional arguments passed to these functions must be addresses of
variables whose type is determined by the format string; these are
used to store values from the input tuple. There are a few cases, as
described in the list of format units above, where these parameters
are used as input values; they should match what is specified for the
corresponding format unit in that case.
For the conversion to succeed, the arg object must match the
format and the format must be exhausted. On success, the
PyArg_Parse*() functions return true, otherwise they
return false and raise an appropriate exception.


10.7 Buffer Object Structures

sequence-structs.html | newTypes.html | supporting-iteration.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
10.6 Sequence Object Structures (sequence-structs.html)
Up:
10. Object Implementation Support (newTypes.html)
Next:
10.8 Supporting the Iterator (supporting-iteration.html)
---
# 10.7 Buffer Object Structures
The buffer interface exports a model where an object can expose its
internal data as a set of chunks of data, where each chunk is
specified as a pointer/length pair. These chunks are called
segments and are presumed to be non-contiguous in memory.
If an object does not export the buffer interface, then its
tp_as_buffer member in the PyTypeObject structure
should be NULL. Otherwise, the tp_as_buffer will point to
a PyBufferProcs structure.
Note:
It is very important that your PyTypeObject structure
uses Py_TPFLAGS_DEFAULT for the value of the
tp_flags member rather than `0`. This tells the Python
runtime that your PyBufferProcs structure contains the
bf_getcharbuffer slot. Older versions of Python did not have
this member, so a new Python interpreter using an old extension needs
to be able to test for its presence before using it.


7.3.3 Buffer Objects

unicodeMethodsAndSlots.html | sequenceObjects.html | tupleObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.3.2.2 Methods and Slot (unicodeMethodsAndSlots.html)
Up:
7.3 Sequence Objects (sequenceObjects.html)
Next:
7.3.4 Tuple Objects (tupleObjects.html)
---
## 7.3.3 Buffer Objects
Python objects implemented in C can export a group of functions called
the ``bufferinterface.'' These functions can
be used by an object to expose its data in a raw, byte-oriented
format. Clients of the object can use the buffer interface to access
the object data directly, without needing to copy it first.
Two examples of objects that support
the buffer interface are strings and arrays. The string object exposes
the character contents in the buffer interface's byte-oriented
form. An array can also expose its contents, but it should be noted
that array elements may be multi-byte values.
An example user of the buffer interface is the file object's
write() method. Any object that can export a series of bytes
through the buffer interface can be written to a file. There are a
number of format codes to PyArg_ParseTuple() that operate
against an object's buffer interface, returning data from the target
object.
More information on the buffer interface is provided in the section
``Buffer Object Structures'' (section 10.7 (buffer-structs.html#buffer-structs)), under
the description for PyBufferProcs.
A ``buffer object'' is defined in the bufferobject.h header
(included by Python.h). These objects look very similar to
string objects at the Python programming level: they support slicing,
indexing, concatenation, and some other standard string
operations. However, their data can come from one of two sources: from
a block of memory, or from another object which exports the buffer
interface.
Buffer objects are useful as a way to expose the data from another
object's buffer interface to the Python programmer. They can also be
used as a zero-copy slicing mechanism. Using their ability to
reference a block of memory, it is possible to expose any data to the
Python programmer quite easily. The memory could be a large, constant
array in a C extension, it could be a raw block of memory for
manipulation before passing to an operating system library, or it
could be used to pass around structured data in its native, in-memory
format.


7.3.2.1 Built-in Codecs

unicodeObjects.html | unicodeObjects.html | unicodeMethodsAndSlots.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.3.2 Unicode Objects (unicodeObjects.html)
Up:
7.3.2 Unicode Objects (unicodeObjects.html)
Next:
7.3.2.2 Methods and Slot (unicodeMethodsAndSlots.html)
---
### 7.3.2.1 Built-in Codecs
Python provides a set of builtin codecs which are written in C
for speed. All of these codecs are directly usable via the
following functions.
Many of the following APIs take two arguments encoding and
errors. These parameters encoding and errors have the same semantics
as the ones of the builtin unicode() Unicode object constructor.
Setting encoding to NULL causes the default encoding to be used
which is ASCII. The file system calls should use
Py_FileSystemDefaultEncoding as the encoding for file
names. This variable should be treated as read-only: On some systems,
it will be a pointer to a static string, on others, it will change at
run-time, e.g. when the application invokes setlocale.
Error handling is set by errors which may also be set to NULL
meaning to use the default handling defined for the codec. Default
error handling for all builtin codecs is ``strict''
(ValueError is raised).
The codecs all use a similar interface. Only deviation from the
following generic ones are documented for simplicity.
These are the generic codec APIs:
These are the UTF-8 codec APIs:
These are the UTF-16 codec APIs:
These are the ``Unicode Esacpe'' codec APIs:
These are the ``Raw Unicode Esacpe'' codec APIs:
These are the Latin-1 codec APIs:
Latin-1 corresponds to the first 256 Unicode ordinals and only these
are accepted by the codecs during encoding.
These are the ASCII codec APIs. Only 7-bit ASCII data is
accepted. All other codes generate errors.
These are the mapping codec APIs:
This codec is special in that it can be used to implement many
different codecs (and this is in fact what was done to obtain most of
the standard codecs included in the encodings package). The
codec uses mapping to encode and decode characters.
Decoding mappings must map single string characters to single Unicode
characters, integers (which are then interpreted as Unicode ordinals)
or None (meaning "undefined mapping" and causing an error).
Encoding mappings must map single Unicode characters to single string
characters, integers (which are then interpreted as Latin-1 ordinals)
or None (meaning "undefined mapping" and causing an error).
The mapping objects provided must only support the __getitem__ mapping
interface.
If a character lookup fails with a LookupError, the character is
copied as-is meaning that its ordinal value will be interpreted as
Unicode or Latin-1 ordinal resp. Because of this, mappings only need
to contain those mappings which map characters to different code
points.
The following codec API is special in that maps Unicode to Unicode.
These are the MBCS codec APIs. They are currently only available on
Windows and use the Win32 MBCS converters to implement the
conversions. Note that MBCS (or DBCS) is a class of encodings, not
just one. The target encoding is defined by the user settings on the
machine running the codec.


7.5.10 Cell Objects

cObjects.html | otherObjects.html | initialization.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.5.9 CObjects (cObjects.html)
Up:
7.5 Other Objects (otherObjects.html)
Next:
8. Initialization, Finalization, and (initialization.html)
---
## 7.5.10 Cell Objects
``Cell'' objects are used to implement variables referenced by
multiple scopes. For each such variable, a cell object is created to
store the value; the local variables of each stack frame that
references the value contains a reference to the cells from outer
scopes which also use that variable. When the value is accessed, the
value contained in the cell is used instead of the cell object
itself. This de-referencing of the cell object requires support from
the generated byte-code; these are not automatically de-referenced
when accessed. Cell objects are not likely to be useful elsewhere.


7.5.9 CObjects

weakref-objects.html | otherObjects.html | cell-objects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.5.8 Weak Reference Objects (weakref-objects.html)
Up:
7.5 Other Objects (otherObjects.html)
Next:
7.5.10 Cell Objects (cell-objects.html)
---
## 7.5.9 CObjects
Refer to Extending and Embedding the Python Interpreter,
section 1.12, ``Providing a C API for an Extension Module,'' for more
information on using these objects.


10.2 Common Object Structures

allocating-objects.html | newTypes.html | type-structs.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
10.1 Allocating Objects on (allocating-objects.html)
Up:
10. Object Implementation Support (newTypes.html)
Next:
10.3 Type Objects (type-structs.html)
---
# 10.2 Common Object Structures
There are a large number of structures which are used in the
definition of object types for Python. This section describes these
structures and how they are used.
All Python objects ultimately share a small number of fields at the
beginning of the object's representation in memory. These are
represented by the PyObject and PyVarObject types,
which are defined, in turn, by the expansions of some macros also
used, whether directly or indirectly, in the definition of all other
Python objects.
These macros are used in the definition of PyObject and
PyVarObject:
PyObject_HEAD_INIT
The ml_meth is a C function pointer. The functions may be of
different types, but they always return PyObject*. If the
function is not of the PyCFunction, the compiler will require
a cast in the method table. Even though PyCFunction defines
the first parameter as PyObject*, it is common that the method
implementation uses a the specific C type of the self object.
The ml_flags field is a bitfield which can include the
following flags. The individual flags indicate either a calling
convention or a binding convention. Of the calling convention flags,
only METH_VARARGS and METH_KEYWORDS can be
combined (but note that METH_KEYWORDS alone is equivalent
to `METH_VARARGS | METH_KEYWORDS`).
Any of the calling convention flags can be combined with a
binding flag.
These two constants are not used to indicate the calling convention
but the binding when use with methods of classes. These may not be
used for functions defined for modules. At most one of these flags
may be set for any given method.


7.2.4 Complex Number Objects

floatObjects.html | numericObjects.html | node38.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.2.3 Floating Point Objects (floatObjects.html)
Up:
7.2 Numeric Objects (numericObjects.html)
Next:
7.2.4.1 Complex Numbers as (node38.html)
---
## 7.2.4 Complex Number Objects
Python's complex number objects are implemented as two distinct types
when viewed from the C API: one is the Python object exposed to
Python programs, and the other is a C structure which represents the
actual complex number value. The API provides functions for working
with both.


7. Concrete Objects Layer

abstract-buffer.html | api.html | fundamental.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
6.6 Buffer Protocol (abstract-buffer.html)
Up:
Python/C API Reference Manual (api.html)
Next:
7.1 Fundamental Objects (fundamental.html)
---
# 7. Concrete Objects Layer
The functions in this chapter are specific to certain Python object
types. Passing them an object of the wrong type is not a good idea;
if you receive an object from a Python program and you are not sure
that it has the right type, you must perform a type check first;
for example, to check that an object is a dictionary, use
PyDict_Check(). The chapter is structured like the
``family tree'' of Python object types.
Warning:
While the functions described in this chapter carefully check
the type of the objects which are passed in, many of them do not check
for NULL being passed instead of a valid object. Allowing NULL
to be passed in can cause memory access violations and immediate
termination of the interpreter.


Contents

front.html | api.html | intro.html | Python/C API Reference Manual | genindex.html
Previous:
Front Matter (front.html)
Up:
Python/C API Reference Manual (api.html)
Next:
1. Introduction (intro.html)
---
## Contents
Table of Contents
- Front Matter (front.html)
  1. Introduction (intro.html)
  - 1.1 Include Files (includes.html)
  1.2 Objects, Types and Reference Counts (objects.html)
  - 1.2.1 Reference Counts (refcounts.html)
  1.2.2 Types (types.html)
  1.3 Exceptions (exceptions.html)
  1.4 Embedding Python (embedding.html)
  2. The Very High Level Layer (veryhigh.html)
  3. Reference Counting (countingRefs.html)
  4. Exception Handling (exceptionHandling.html)
  - 4.1 Standard Exceptions (standardExceptions.html)
  4.2 Deprecation of String Exceptions (node15.html)
  5. Utilities (utilities.html)
  - 5.1 Operating System Utilities (os.html)
  5.2 Process Control (processControl.html)
  5.3 Importing Modules (importing.html)
  5.4 Data marshalling support (marshalling-utils.html)
  5.5 Parsing arguments and building values (arg-parsing.html)
  6. Abstract Objects Layer (abstract.html)
  - 6.1 Object Protocol (object.html)
  6.2 Number Protocol (number.html)
  6.3 Sequence Protocol (sequence.html)
  6.4 Mapping Protocol (mapping.html)
  6.5 Iterator Protocol (iterator.html)
  6.6 Buffer Protocol (abstract-buffer.html)
  7. Concrete Objects Layer (concrete.html)
  - 7.1 Fundamental Objects (fundamental.html)
  - 7.1.1 Type Objects (typeObjects.html)
  7.1.2 The None Object (noneObject.html)
  7.2 Numeric Objects (numericObjects.html)
  - 7.2.1 Plain Integer Objects (intObjects.html)
  7.2.2 Long Integer Objects (longObjects.html)
  7.2.3 Floating Point Objects (floatObjects.html)
  7.2.4 Complex Number Objects (complexObjects.html)
  7.3 Sequence Objects (sequenceObjects.html)
  - 7.3.1 String Objects (stringObjects.html)
  7.3.2 Unicode Objects (unicodeObjects.html)
  7.3.3 Buffer Objects (bufferObjects.html)
  7.3.4 Tuple Objects (tupleObjects.html)
  7.3.5 List Objects (listObjects.html)
  7.4 Mapping Objects (mapObjects.html)
  - 7.4.1 Dictionary Objects (dictObjects.html)
  7.5 Other Objects (otherObjects.html)
  - 7.5.1 File Objects (fileObjects.html)
  7.5.2 Instance Objects (instanceObjects.html)
  7.5.3 Method Objects (method-objects.html)
  7.5.4 Module Objects (moduleObjects.html)
  7.5.5 Iterator Objects (iterator-objects.html)
  7.5.6 Descriptor Objects (descriptor-objects.html)
  7.5.7 Slice Objects (slice-objects.html)
  7.5.8 Weak Reference Objects (weakref-objects.html)
  7.5.9 CObjects (cObjects.html)
  7.5.10 Cell Objects (cell-objects.html)
  8. Initialization, Finalization, and Threads (initialization.html)
  - 8.1 Thread State and the Global Interpreter Lock (threads.html)
  8.2 Profiling and Tracing (profiling.html)
  8.3 Advanced Debugger Support (advanced-debugging.html)
  9. Memory Management (memory.html)
  - 9.1 Overview (memoryOverview.html)
  9.2 Memory Interface (memoryInterface.html)
  9.3 Examples (memoryExamples.html)
  10. Object Implementation Support (newTypes.html)
  - 10.1 Allocating Objects on the Heap (allocating-objects.html)
  10.2 Common Object Structures (common-structs.html)
  10.3 Type Objects (type-structs.html)
  10.4 Mapping Object Structures (mapping-structs.html)
  10.5 Number Object Structures (number-structs.html)
  10.6 Sequence Object Structures (sequence-structs.html)
  10.7 Buffer Object Structures (buffer-structs.html)
  10.8 Supporting the Iterator Protocol (supporting-iteration.html)
  10.9 Supporting Cyclic Garbarge Collection (supporting-cycle-detection.html)
  A. Reporting Bugs (reporting-bugs.html)
  B. History and License (node80.html)
  - B.1 History of the software (node81.html)
  B.2 Terms and conditions for accessing or otherwise using Python (node82.html)
  About this document ... (about.html)
End of Table of Contents


3. Reference Counting

veryhigh.html | api.html | exceptionHandling.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
2. The Very High (veryhigh.html)
Up:
Python/C API Reference Manual (api.html)
Next:
4. Exception Handling (exceptionHandling.html)
---
# 3. Reference Counting
The macros in this section are used for managing reference counts
of Python objects.


7.5.6 Descriptor Objects

iterator-objects.html | otherObjects.html | slice-objects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.5.5 Iterator Objects (iterator-objects.html)
Up:
7.5 Other Objects (otherObjects.html)
Next:
7.5.7 Slice Objects (slice-objects.html)
---
## 7.5.6 Descriptor Objects
``Descriptors'' are objects that describe some attribute of an object.
They are found in the dictionary of type objects.


7.4.1 Dictionary Objects

mapObjects.html | mapObjects.html | otherObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.4 Mapping Objects (mapObjects.html)
Up:
7.4 Mapping Objects (mapObjects.html)
Next:
7.5 Other Objects (otherObjects.html)
---
## 7.4.1 Dictionary Objects


1.4 Embedding Python

exceptions.html | intro.html | veryhigh.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
1.3 Exceptions (exceptions.html)
Up:
1. Introduction (intro.html)
Next:
2. The Very High (veryhigh.html)
---
# 1.4 Embedding Python
The one important task that only embedders (as opposed to extension
writers) of the Python interpreter have to worry about is the
initialization, and possibly the finalization, of the Python
interpreter. Most functionality of the interpreter can only be used
after the interpreter has been initialized.
The basic initialization function is
Py_Initialize()
This initializes the table of loaded modules, and creates the
fundamental modules __builtin__
__main__ sys
and exceptions. It also initializes
the module search path (`sys.path`).
Py_Initialize() does not set the ``script argument list''
(`sys.argv`). If this variable is needed by Python code that
will be executed later, it must be set explicitly with a call to
`PySys_SetArgv( argc , argv )`subsequent to the call to
Py_Initialize().
On most systems (in particular, on Unix and Windows, although the
details are slightly different),
Py_Initialize() calculates the module search path based
upon its best guess for the location of the standard Python
interpreter executable, assuming that the Python library is found in a
fixed location relative to the Python interpreter executable. In
particular, it looks for a directory named
lib/python2.3 relative to the parent directory where
the executable named python is found on the shell command
search path (the environment variable PATH).
For instance, if the Python executable is found in
/usr/local/bin/python, it will assume that the libraries are in
/usr/local/lib/python2.3. (In fact, this particular path
is also the ``fallback'' location, used when no executable file named
python is found along PATH.) The user can override
this behavior by setting the environment variable PYTHONHOME,
or insert additional directories in front of the standard path by
setting PYTHONPATH.
The embedding application can steer the search by calling
`Py_SetProgramName( file )`before calling
Py_Initialize(). Note that PYTHONHOME still
overrides this and PYTHONPATH is still inserted in front of
the standard path. An application that requires total control has to
provide its own implementation of
Py_GetPath()
Py_GetPrefix()
Py_GetExecPrefix() and
Py_GetProgramFullPath()(all
defined in Modules/getpath.c).


4. Exception Handling

countingRefs.html | api.html | standardExceptions.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
3. Reference Counting (countingRefs.html)
Up:
Python/C API Reference Manual (api.html)
Next:
4.1 Standard Exceptions (standardExceptions.html)
---
# 4. Exception Handling
The functions described in this chapter will let you handle and raise Python
exceptions. It is important to understand some of the basics of
Python exception handling. It works somewhat like the
Unix errno variable: there is a global indicator (per
thread) of the last error that occurred. Most functions don't clear
this on success, but will set it to indicate the cause of the error on
failure. Most functions also return an error indicator, usually
NULL if they are supposed to return a pointer, or `-1` if they
return an integer (exception: the PyArg_*() functions
return `1` for success and `0` for failure).
When a function must fail because some function it called failed, it
generally doesn't set the error indicator; the function it called
already set it. It is responsible for either handling the error and
clearing the exception or returning after cleaning up any resources it
holds (such as object references or memory allocations); it should
not continue normally if it is not prepared to handle the
error. If returning due to an error, it is important to indicate to
the caller that an error has been set. If the error is not handled or
carefully propagated, additional calls into the Python/C API may not
behave as intended and may fail in mysterious ways.
The error indicator consists of three Python objects corresponding to
the Python variables `sys.exc_type`, `sys.exc_value` and
`sys.exc_traceback`. API functions exist to interact with the
error indicator in various ways. There is a separate error indicator
for each thread.


1.3 Exceptions

types.html | intro.html | embedding.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
1.2.2 Types (types.html)
Up:
1. Introduction (intro.html)
Next:
1.4 Embedding Python (embedding.html)
---
# 1.3 Exceptions
The Python programmer only needs to deal with exceptions if specific
error handling is required; unhandled exceptions are automatically
propagated to the caller, then to the caller's caller, and so on, until
they reach the top-level interpreter, where they are reported to the
user accompanied by a stack traceback.
For C programmers, however, error checking always has to be explicit.
All functions in the Python/C API can raise exceptions, unless an
explicit claim is made otherwise in a function's documentation. In
general, when a function encounters an error, it sets an exception,
discards any object references that it owns, and returns an
error indicator -- usually NULL or `-1`. A few functions
return a Boolean true/false result, with false indicating an error.
Very few functions return no explicit error indicator or have an
ambiguous return value, and require explicit testing for errors with
PyErr_Occurred()
Exception state is maintained in per-thread storage (this is
equivalent to using global storage in an unthreaded application). A
thread can be in one of two states: an exception has occurred, or not.
The function PyErr_Occurred() can be used to check for
this: it returns a borrowed reference to the exception type object
when an exception has occurred, and NULL otherwise. There are a
number of functions to set the exception state:
PyErr_SetString()is the most
common (though not the most general) function to set the exception
state, and PyErr_Clear()clears the
exception state.
The full exception state consists of three objects (all of which can
be NULL): the exception type, the corresponding exception
value, and the traceback. These have the same meanings as the Python
objects `sys.exc_type`, `sys.exc_value`, and
`sys.exc_traceback`; however, they are not the same: the Python
objects represent the last exception being handled by a Python
try ... except statement, while the C level
exception state only exists while an exception is being passed on
between C functions until it reaches the Python bytecode interpreter's
main loop, which takes care of transferring it to `sys.exc_type`
and friends.
Note that starting with Python 1.5, the preferred, thread-safe way to
access the exception state from Python code is to call the function
sys.exc_info(), which returns the per-thread exception state
for Python code. Also, the semantics of both ways to access the
exception state have changed so that a function which catches an
exception will save and restore its thread's exception state so as to
preserve the exception state of its caller. This prevents common bugs
in exception handling code caused by an innocent-looking function
overwriting the exception being handled; it also reduces the often
unwanted lifetime extension for objects that are referenced by the
stack frames in the traceback.
As a general principle, a function that calls another function to
perform some task should check whether the called function raised an
exception, and if so, pass the exception state on to its caller. It
should discard any object references that it owns, and return an
error indicator, but it should not set another exception --
that would overwrite the exception that was just raised, and lose
important information about the exact cause of the error.
A simple example of detecting exceptions and passing them on is shown
in the sum_sequence()example
above. It so happens that that example doesn't need to clean up any
owned references when it detects an error. The following example
function shows some error cleanup. First, to remind you why you like
Python, we show the equivalent Python code:
```text

def incr_item(dict, key):
try:
item = dict[key]
except KeyError:
item = 0
dict[key] = item + 1
```
Here is the corresponding C code, in all its glory:
```text

int
incr_item(PyObject *dict, PyObject *key)
{
/* Objects all initialized to NULL for Py_XDECREF */
PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
int rv = -1; /* Return value initialized to -1 (failure) */

item = PyObject_GetItem(dict, key);
if (item == NULL) {
/* Handle KeyError only: */
if (!PyErr_ExceptionMatches(PyExc_KeyError))
goto error;

/* Clear the error and use zero: */
PyErr_Clear();
item = PyInt_FromLong(0L);
if (item == NULL)
goto error;
}
const_one = PyInt_FromLong(1L);
if (const_one == NULL)
goto error;

incremented_item = PyNumber_Add(item, const_one);
if (incremented_item == NULL)
goto error;

if (PyObject_SetItem(dict, key, incremented_item) < 0)
goto error;
rv = 0; /* Success */
/* Continue with cleanup code */

error:
/* Cleanup code, shared by success and failure path */

/* Use Py_XDECREF() to ignore NULL references */
Py_XDECREF(item);
Py_XDECREF(const_one);
Py_XDECREF(incremented_item);

return rv; /* -1 for error, 0 for success */
}
```
This example represents an endorsed use of the goto statement
in C! It illustrates the use of
PyErr_ExceptionMatches()and
PyErr_Clear()to
handle specific exceptions, and the use of
Py_XDECREF()to
dispose of owned references that may be NULL (note the
"X" in the name; Py_DECREF() would crash when
confronted with a NULL reference). It is important that the
variables used to hold owned references are initialized to NULL for
this to work; likewise, the proposed return value is initialized to
`-1` (failure) and only set to success after the final call made
is successful.


7.5.1 File Objects

otherObjects.html | otherObjects.html | instanceObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.5 Other Objects (otherObjects.html)
Up:
7.5 Other Objects (otherObjects.html)
Next:
7.5.2 Instance Objects (instanceObjects.html)
---
## 7.5.1 File Objects
Python's built-in file objects are implemented entirely on the
FILE* support from the C standard library. This is an
implementation detail and may change in future releases of Python.


7.2.3 Floating Point Objects

longObjects.html | numericObjects.html | complexObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.2.2 Long Integer Objects (longObjects.html)
Up:
7.2 Numeric Objects (numericObjects.html)
Next:
7.2.4 Complex Number Objects (complexObjects.html)
---
## 7.2.3 Floating Point Objects


Front Matter

api.html | api.html | contents.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
Python/C API Reference Manual (api.html)
Up:
Python/C API Reference Manual (api.html)
Next:
---
# Front Matter
Copyright © 2001, 2002, 2003 Python Software Foundation.
All rights reserved.
Copyright © 2000 BeOpen.com.
All rights reserved.
Copyright © 1995-2000 Corporation for National Research Initiatives.
All rights reserved.
Copyright © 1991-1995 Stichting Mathematisch Centrum.
All rights reserved.
See the end of this document for complete license and permissions
information.
### Abstract:
This manual documents the API used by C and C++ programmers who
want to write extension modules or embed Python. It is a companion to
Extending and Embedding the Python
Interpreter (../ext/ext.html), which describes the general principles of extension
writing but does not document the API functions in detail.
Warning:
The current version of this document is incomplete. I hope
that it is nevertheless useful. I will continue to work on it, and
release new versions from time to time, independent from Python source
code releases.


7.1 Fundamental Objects

concrete.html | concrete.html | typeObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7. Concrete Objects Layer (concrete.html)
Up:
7. Concrete Objects Layer (concrete.html)
Next:
7.1.1 Type Objects (typeObjects.html)
---
# 7.1 Fundamental Objects
This section describes Python type objects and the singleton object
`None`.


Index

node82.html | api.html | about.html | Python/C API Reference Manual | contents.html
Previous:
B.2 Terms and conditions (node82.html)
Up:
Python/C API Reference Manual (api.html)
Next:
About this document ... (about.html)
---
## Index
---
Symbols (#letter-Symbols) |
_ (#letter-_) |
a (#letter-a) |
b (#letter-b) |
c (#letter-c) |
d (#letter-d) |
e (#letter-e) |
f (#letter-f) |
g (#letter-g) |
h (#letter-h) |
i (#letter-i) |
k (#letter-k) |
l (#letter-l) |
m (#letter-m) |
n (#letter-n) |
o (#letter-o) |
p (#letter-p) |
r (#letter-r) |
s (#letter-s) |
t (#letter-t) |
u (#letter-u) |
v (#letter-v)
---
## Symbols
---
## _ (underscore)
---
## A
---
## B
---
## C
---
## D
---
## E
---
## F
---
## G
---
## H
---
## I
---
## K
---
## L
---
## M
---
## N
---
## O
---
## P
---
## R
---
## S
---
## T
---
## U
---
## V


5.3 Importing Modules

processControl.html | utilities.html | marshalling-utils.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
5.2 Process Control (processControl.html)
Up:
5. Utilities (utilities.html)
Next:
5.4 Data marshalling support (marshalling-utils.html)
---
# 5.3 Importing Modules


1.1 Include Files

intro.html | intro.html | objects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
1. Introduction (intro.html)
Up:
1. Introduction (intro.html)
Next:
1.2 Objects, Types and (objects.html)
---
# 1.1 Include Files
All function, type and macro definitions needed to use the Python/C
API are included in your code by the following line:
```text

#include "Python.h"
```
This implies inclusion of the following standard headers:
`<stdio.h>`, `<string.h>`, `<errno.h>`,
`<limits.h>`, and `<stdlib.h>` (if available).
Since Python may define some pre-processor definitions which affect
the standard headers on some systems, you must include Python.h
before any standard headers are included.
All user visible names defined by Python.h (except those defined by
the included standard headers) have one of the prefixes "Py" or
"_Py". Names beginning with "_Py" are for internal use by
the Python implementation and should not be used by extension writers.
Structure member names do not have a reserved prefix.
Important: user code should never define names that begin
with "Py" or "_Py". This confuses the reader, and
jeopardizes the portability of the user code to future Python
versions, which may define additional names beginning with one of
these prefixes.
The header files are typically installed with Python. On Unix, these
are located in the directories
prefix/include/pythonversion/ and
exec_prefix/include/pythonversion/, where
prefix and exec_prefix are defined by the
corresponding parameters to Python's configure script and
version is `sys.version[:3]`. On Windows, the headers are
installed in prefix/include, where prefix is
the installation directory specified to the installer.
To include the headers, place both directories (if different) on your
compiler's search path for includes. Do not place the parent
directories on the search path and then use
"#include <python2.3/Python.h>"; this will break on
multi-platform builds since the platform independent headers under
prefix include the platform specific headers from
exec_prefix.
C++ users should note that though the API is defined entirely using
C, the header files do properly declare the entry points to be
`extern "C"`, so there is no need to do anything special to use
the API from C++.


Python/C API Reference Manual

../index.html | front.html | Python/C API Reference Manual | contents.html | genindex.html
Up:
Python Documentation Index (../index.html)
Next:
Front Matter (front.html)
---
# Python/C API Reference Manual
Guido van Rossum
Fred L. Drake, Jr., editor
PythonLabs
Email: python-docs@python.org
Release 2.3
July 29, 2003


cell-objects.html | api.html | threads.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.5.10 Cell Objects (cell-objects.html)
Up:
Python/C API Reference Manual (api.html)
Next:
8.1 Thread State and (threads.html)
---
# 8. Initialization, Finalization, and Threads


7.5.2 Instance Objects

fileObjects.html | otherObjects.html | method-objects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.5.1 File Objects (fileObjects.html)
Up:
7.5 Other Objects (otherObjects.html)
Next:
7.5.3 Method Objects (method-objects.html)
---
## 7.5.2 Instance Objects
There are very few functions specific to instance objects.


7.2.1 Plain Integer Objects

numericObjects.html | numericObjects.html | longObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.2 Numeric Objects (numericObjects.html)
Up:
7.2 Numeric Objects (numericObjects.html)
Next:
7.2.2 Long Integer Objects (longObjects.html)
---
## 7.2.1 Plain Integer Objects


1. Introduction

contents.html | api.html | includes.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
Up:
Python/C API Reference Manual (api.html)
Next:
1.1 Include Files (includes.html)
---
# 1. Introduction
The Application Programmer's Interface to Python gives C and
C++ programmers access to the Python interpreter at a variety of
levels. The API is equally usable from C++, but for brevity it is
generally referred to as the Python/C API. There are two
fundamentally different reasons for using the Python/C API. The first
reason is to write extension modules for specific purposes;
these are C modules that extend the Python interpreter. This is
probably the most common use. The second reason is to use Python as a
component in a larger application; this technique is generally
referred to as embedding Python in an application.
Writing an extension module is a relatively well-understood process,
where a ``cookbook'' approach works well. There are several tools
that automate the process to some extent. While people have embedded
Python in other applications since its early existence, the process of
embedding Python is less straightforward than writing an extension.
Many API functions are useful independent of whether you're embedding
or extending Python; moreover, most applications that embed Python
will need to provide a custom extension as well, so it's probably a
good idea to become familiar with writing an extension before
attempting to embed Python in a real application.


7.5.5 Iterator Objects

moduleObjects.html | otherObjects.html | descriptor-objects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.5.4 Module Objects (moduleObjects.html)
Up:
7.5 Other Objects (otherObjects.html)
Next:
7.5.6 Descriptor Objects (descriptor-objects.html)
---
## 7.5.5 Iterator Objects
Python provides two general-purpose iterator objects. The first, a
sequence iterator, works with an arbitrary sequence supporting the
__getitem__() method. The second works with a callable
object and a sentinel value, calling the callable for each item in the
sequence, and ending the iteration when the sentinel value is
returned.


6.5 Iterator Protocol

mapping.html | abstract.html | abstract-buffer.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
6.4 Mapping Protocol (mapping.html)
Up:
6. Abstract Objects Layer (abstract.html)
Next:
6.6 Buffer Protocol (abstract-buffer.html)
---
# 6.5 Iterator Protocol
New in version 2.2.
There are only a couple of functions specifically for working with
iterators.
To write a loop which iterates over an iterator, the C code should
look something like this:
```text

PyObject *iterator = PyObject_GetIter(obj);
PyObject *item;

if (iterator == NULL) {
/* propagate error */
}

while (item = PyIter_Next(iterator)) {
/* do something with item */
...
/* release reference when done */
Py_DECREF(item);
}

Py_DECREF(iterator);

if (PyErr_Occurred()) {
/* propagate error */
}
else {
/* continue doing useful work */
}
```


7.3.5 List Objects

tupleObjects.html | sequenceObjects.html | mapObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.3.4 Tuple Objects (tupleObjects.html)
Up:
7.3 Sequence Objects (sequenceObjects.html)
Next:
7.4 Mapping Objects (mapObjects.html)
---
## 7.3.5 List Objects


7.2.2 Long Integer Objects

intObjects.html | numericObjects.html | floatObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.2.1 Plain Integer Objects (intObjects.html)
Up:
7.2 Numeric Objects (numericObjects.html)
Next:
7.2.3 Floating Point Objects (floatObjects.html)
---
## 7.2.2 Long Integer Objects


7.4 Mapping Objects

listObjects.html | concrete.html | dictObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.3.5 List Objects (listObjects.html)
Up:
7. Concrete Objects Layer (concrete.html)
Next:
7.4.1 Dictionary Objects (dictObjects.html)
---
# 7.4 Mapping Objects


10.4 Mapping Object Structures

type-structs.html | newTypes.html | number-structs.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
10.3 Type Objects (type-structs.html)
Up:
10. Object Implementation Support (newTypes.html)
Next:
10.5 Number Object Structures (number-structs.html)
---
# 10.4 Mapping Object Structures


6.4 Mapping Protocol

sequence.html | abstract.html | iterator.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
6.3 Sequence Protocol (sequence.html)
Up:
6. Abstract Objects Layer (abstract.html)
Next:
6.5 Iterator Protocol (iterator.html)
---
# 6.4 Mapping Protocol


5.4 Data marshalling support

importing.html | utilities.html | arg-parsing.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
5.3 Importing Modules (importing.html)
Up:
5. Utilities (utilities.html)
Next:
5.5 Parsing arguments and (arg-parsing.html)
---
# 5.4 Data marshalling support
These routines allow C code to work with serialized objects using the
same data format as the marshal module. There are functions
to write data into the serialization format, and additional functions
that can be used to read the data back. Files used to store marshalled
data must be opened in binary mode.
Numeric values are stored with the least significant byte first.
The following functions allow marshalled values to be read back in.
XXX What about error detection? It appears that reading past the end
of the file will always result in a negative numeric value (where
that's relevant), but it's not clear that negative values won't be
handled properly when there's no error. What's the right way to tell?
Should only non-negative values be written using these routines?


9. Memory Management

advanced-debugging.html | api.html | memoryOverview.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
8.3 Advanced Debugger Support (advanced-debugging.html)
Up:
Python/C API Reference Manual (api.html)
Next:
9.1 Overview (memoryOverview.html)
---
# 9. Memory Management


9.3 Examples

memoryInterface.html | memory.html | newTypes.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
9.2 Memory Interface (memoryInterface.html)
Up:
9. Memory Management (memory.html)
Next:
10. Object Implementation Support (newTypes.html)
---
# 9.3 Examples
Here is the example from section 9.1 (memoryOverview.html#memoryOverview), rewritten so
that the I/O buffer is allocated from the Python heap by using the
first function set:
```text

PyObject *res;
char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */

if (buf == NULL)
return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyString_FromString(buf);
PyMem_Free(buf); /* allocated with PyMem_Malloc */
return res;
```
The same code using the type-oriented function set:
```text

PyObject *res;
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */

if (buf == NULL)
return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyString_FromString(buf);
PyMem_Del(buf); /* allocated with PyMem_New */
return res;
```
Note that in the two examples above, the buffer is always
manipulated via functions belonging to the same set. Indeed, it
is required to use the same memory API family for a given
memory block, so that the risk of mixing different allocators is
reduced to a minimum. The following code sequence contains two errors,
one of which is labeled as fatal because it mixes two different
allocators operating on different heaps.
```text

char *buf1 = PyMem_New(char, BUFSIZ);
char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */
free(buf2); /* Right -- allocated via malloc() */
free(buf1); /* Fatal -- should be PyMem_Del() */
```
In addition to the functions aimed at handling raw memory blocks from
the Python heap, objects in Python are allocated and released with
PyObject_New(), PyObject_NewVar() and
PyObject_Del(), or with their corresponding macros
PyObject_NEW(), PyObject_NEW_VAR() and
PyObject_DEL().


9.2 Memory Interface

memoryOverview.html | memory.html | memoryExamples.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
9.1 Overview (memoryOverview.html)
Up:
9. Memory Management (memory.html)
Next:
9.3 Examples (memoryExamples.html)
---
# 9.2 Memory Interface
The following function sets, modeled after the ANSI C standard,
but specifying behavior when requesting zero bytes,
are available for allocating and releasing memory from the Python heap:
The following type-oriented macros are provided for convenience. Note
that TYPE refers to any C type.
In addition, the following macro sets are provided for calling the
Python memory allocator directly, without involving the C API functions
listed above. However, note that their use does not preserve binary
compatibility accross Python versions and is therefore deprecated in
extension modules.
PyMem_MALLOC(), PyMem_REALLOC(), PyMem_FREE().
PyMem_NEW(), PyMem_RESIZE(), PyMem_DEL().


9.1 Overview

memory.html | memory.html | memoryInterface.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
9. Memory Management (memory.html)
Up:
9. Memory Management (memory.html)
Next:
9.2 Memory Interface (memoryInterface.html)
---
# 9.1 Overview
Memory management in Python involves a private heap containing all
Python objects and data structures. The management of this private
heap is ensured internally by the Python memory manager. The
Python memory manager has different components which deal with various
dynamic storage management aspects, like sharing, segmentation,
preallocation or caching.
At the lowest level, a raw memory allocator ensures that there is
enough room in the private heap for storing all Python-related data
by interacting with the memory manager of the operating system. On top
of the raw memory allocator, several object-specific allocators
operate on the same heap and implement distinct memory management
policies adapted to the peculiarities of every object type. For
example, integer objects are managed differently within the heap than
strings, tuples or dictionaries because integers imply different
storage requirements and speed/space tradeoffs. The Python memory
manager thus delegates some of the work to the object-specific
allocators, but ensures that the latter operate within the bounds of
the private heap.
It is important to understand that the management of the Python heap
is performed by the interpreter itself and that the user has no
control over it, even if she regularly manipulates object pointers to
memory blocks inside that heap. The allocation of heap space for
Python objects and other internal buffers is performed on demand by
the Python memory manager through the Python/C API functions listed in
this document.
To avoid memory corruption, extension writers should never try to
operate on Python objects with the functions exported by the C
library: malloc(),
calloc(),
realloc()and
free(). This will result in
mixed calls between the C allocator and the Python memory manager
with fatal consequences, because they implement different algorithms
and operate on different heaps. However, one may safely allocate and
release memory blocks with the C library allocator for individual
purposes, as shown in the following example:
```text

PyObject *res;
char *buf = (char *) malloc(BUFSIZ); /* for I/O */

if (buf == NULL)
return PyErr_NoMemory();
...Do some I/O operation involving buf...
res = PyString_FromString(buf);
free(buf); /* malloc'ed */
return res;
```
In this example, the memory request for the I/O buffer is handled by
the C library allocator. The Python memory manager is involved only
in the allocation of the string object returned as a result.
In most situations, however, it is recommended to allocate memory from
the Python heap specifically because the latter is under control of
the Python memory manager. For example, this is required when the
interpreter is extended with new object types written in C. Another
reason for using the Python heap is the desire to inform the
Python memory manager about the memory needs of the extension module.
Even when the requested memory is used exclusively for internal,
highly-specific purposes, delegating all memory requests to the Python
memory manager causes the interpreter to have a more accurate image of
its memory footprint as a whole. Consequently, under certain
circumstances, the Python memory manager may or may not trigger
appropriate actions, like garbage collection, memory compaction or
other preventive procedures. Note that by using the C library
allocator as shown in the previous example, the allocated memory for
the I/O buffer escapes completely the Python memory manager.


7.5.3 Method Objects

instanceObjects.html | otherObjects.html | moduleObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.5.2 Instance Objects (instanceObjects.html)
Up:
7.5 Other Objects (otherObjects.html)
Next:
7.5.4 Module Objects (moduleObjects.html)
---
## 7.5.3 Method Objects
There are some useful functions that are useful for working with
method objects.


7.5.4 Module Objects

method-objects.html | otherObjects.html | iterator-objects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.5.3 Method Objects (method-objects.html)
Up:
7.5 Other Objects (otherObjects.html)
Next:
7.5.5 Iterator Objects (iterator-objects.html)
---
## 7.5.4 Module Objects
There are only a few functions special to module objects.


10. Object Implementation Support

memoryExamples.html | api.html | allocating-objects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
9.3 Examples (memoryExamples.html)
Up:
Python/C API Reference Manual (api.html)
Next:
10.1 Allocating Objects on (allocating-objects.html)
---
# 10. Object Implementation Support
This chapter describes the functions, types, and macros used when
defining new object types.


4.2 Deprecation of String Exceptions

standardExceptions.html | exceptionHandling.html | utilities.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
4.1 Standard Exceptions (standardExceptions.html)
Up:
4. Exception Handling (exceptionHandling.html)
Next:
5. Utilities (utilities.html)
---
# 4.2 Deprecation of String Exceptions
All exceptions built into Python or provided in the standard library
are derived from Exception.


7.2.4.1 Complex Numbers as C Structures

complexObjects.html | complexObjects.html | node39.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.2.4 Complex Number Objects (complexObjects.html)
Up:
7.2.4 Complex Number Objects (complexObjects.html)
Next:
7.2.4.2 Complex Numbers as (node39.html)
---
### 7.2.4.1 Complex Numbers as C Structures
Note that the functions which accept these structures as parameters
and return them as results do so by value rather than
dereferencing them through pointers. This is consistent throughout
the API.


node38.html | complexObjects.html | sequenceObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.2.4.1 Complex Numbers as (node38.html)
Up:
7.2.4 Complex Number Objects (complexObjects.html)
Next:
7.3 Sequence Objects (sequenceObjects.html)
---
### 7.2.4.2 Complex Numbers as Python Objects


B. History and License

reporting-bugs.html | api.html | node81.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
A. Reporting Bugs (reporting-bugs.html)
Up:
Python/C API Reference Manual (api.html)
Next:
B.1 History of the (node81.html)
---
# B. History and License


B.1 History of the software

node80.html | node80.html | node82.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
B. History and License (node80.html)
Up:
B. History and License (node80.html)
Next:
B.2 Terms and conditions (node82.html)
---
# B.1 History of the software
Python was created in the early 1990s by Guido van Rossum at Stichting
Mathematisch Centrum (CWI, see http://www.cwi.nl/) in the Netherlands
as a successor of a language called ABC. Guido remains Python's
principal author, although it includes many contributions from others.
In 1995, Guido continued his work on Python at the Corporation for
National Research Initiatives (CNRI, see http://www.cnri.reston.va.us/)
in Reston, Virginia where he released several versions of the
software.
In May 2000, Guido and the Python core development team moved to
BeOpen.com to form the BeOpen PythonLabs team. In October of the same
year, the PythonLabs team moved to Digital Creations (now Zope
Corporation; see http://www.zope.com/). In 2001, the Python
Software Foundation (PSF, see http://www.python.org/psf/) was
formed, a non-profit organization created specifically to own
Python-related Intellectual Property. Zope Corporation is a
sponsoring member of the PSF.
All Python releases are Open Source (see
http://www.opensource.org/ for the Open Source Definition).
Historically, most, but not all, Python releases have also been
GPL-compatible; the table below summarizes the various releases.
Note:
GPL-compatible doesn't mean that we're distributing
Python under the GPL. All Python licenses, unlike the GPL, let you
distribute a modified version without making your changes open source.
The GPL-compatible licenses make it possible to combine Python with
other software that is released under the GPL; the others don't.
Thanks to the many outside volunteers who have worked under Guido's
direction to make these releases possible.


node81.html | node80.html | genindex.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
B.1 History of the (node81.html)
Up:
B. History and License (node80.html)
Next:
---
# B.2 Terms and conditions for accessing or otherwise using Python
PSF LICENSE AGREEMENT FOR PYTHON 2.3
1. This LICENSE AGREEMENT is between the Python Software Foundation
(``PSF''), and the Individual or Organization (``Licensee'') accessing
and otherwise using Python 2.3 software in source or binary
form and its associated documentation.
2. Subject to the terms and conditions of this License Agreement, PSF
hereby grants Licensee a nonexclusive, royalty-free, world-wide
license to reproduce, analyze, test, perform and/or display publicly,
prepare derivative works, distribute, and otherwise use Python
2.3 alone or in any derivative version, provided, however, that
PSF's License Agreement and PSF's notice of copyright, i.e.,
``Copyright © 2001-2003 Python Software Foundation; All
Rights Reserved'' are retained in Python 2.3 alone or in any
derivative version prepared by Licensee.
3. In the event Licensee prepares a derivative work that is based on
or incorporates Python 2.3 or any part thereof, and wants to
make the derivative work available to others as provided herein, then
Licensee hereby agrees to include in any such work a brief summary of
the changes made to Python 2.3.
4. PSF is making Python 2.3 available to Licensee on an ``AS IS''
basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.3 WILL
NOT INFRINGE ANY THIRD PARTY RIGHTS.
5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
2.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR
LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON
2.3, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE
POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
7. Nothing in this License Agreement shall be deemed to create any
relationship of agency, partnership, or joint venture between PSF and
Licensee. This License Agreement does not grant permission to use PSF
trademarks or trade name in a trademark sense to endorse or promote
products or services of Licensee, or any third party.
8. By copying, installing or otherwise using Python 2.3, Licensee
agrees to be bound by the terms and conditions of this License
Agreement.
BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0
BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1
1. This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an
office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the
Individual or Organization (``Licensee'') accessing and otherwise
using this software in source or binary form and its associated
documentation (``the Software'').
2. Subject to the terms and conditions of this BeOpen Python License
Agreement, BeOpen hereby grants Licensee a non-exclusive,
royalty-free, world-wide license to reproduce, analyze, test, perform
and/or display publicly, prepare derivative works, distribute, and
otherwise use the Software alone or in any derivative version,
provided, however, that the BeOpen Python License is retained in the
Software, alone or in any derivative version prepared by Licensee.
3. BeOpen is making the Software available to Licensee on an ``AS IS''
basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT
INFRINGE ANY THIRD PARTY RIGHTS.
4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE
SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS
AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY
DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
5. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
6. This License Agreement shall be governed by and interpreted in all
respects by the law of the State of California, excluding conflict of
law provisions. Nothing in this License Agreement shall be deemed to
create any relationship of agency, partnership, or joint venture
between BeOpen and Licensee. This License Agreement does not grant
permission to use BeOpen trademarks or trade names in a trademark
sense to endorse or promote products or services of Licensee, or any
third party. As an exception, the ``BeOpen Python'' logos available
at http://www.pythonlabs.com/logos.html may be used according to the
permissions granted on that web page.
7. By copying, installing or otherwise using the software, Licensee
agrees to be bound by the terms and conditions of this License
Agreement.
CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1
1. This LICENSE AGREEMENT is between the Corporation for National
Research Initiatives, having an office at 1895 Preston White Drive,
Reston, VA 20191 (``CNRI''), and the Individual or Organization
(``Licensee'') accessing and otherwise using Python 1.6.1 software in
source or binary form and its associated documentation.
2. Subject to the terms and conditions of this License Agreement, CNRI
hereby grants Licensee a nonexclusive, royalty-free, world-wide
license to reproduce, analyze, test, perform and/or display publicly,
prepare derivative works, distribute, and otherwise use Python 1.6.1
alone or in any derivative version, provided, however, that CNRI's
License Agreement and CNRI's notice of copyright, i.e., ``Copyright
© 1995-2001 Corporation for National Research Initiatives;
All Rights Reserved'' are retained in Python 1.6.1 alone or in any
derivative version prepared by Licensee. Alternately, in lieu of
CNRI's License Agreement, Licensee may substitute the following text
(omitting the quotes): ``Python 1.6.1 is made available subject to the
terms and conditions in CNRI's License Agreement. This Agreement
together with Python 1.6.1 may be located on the Internet using the
following unique, persistent identifier (known as a handle):
1895.22/1013. This Agreement may also be obtained from a proxy server
on the Internet using the following URL:
http://hdl.handle.net/1895.22/1013.''
3. In the event Licensee prepares a derivative work that is based on
or incorporates Python 1.6.1 or any part thereof, and wants to make
the derivative work available to others as provided herein, then
Licensee hereby agrees to include in any such work a brief summary of
the changes made to Python 1.6.1.
4. CNRI is making Python 1.6.1 available to Licensee on an ``AS IS''
basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT
INFRINGE ANY THIRD PARTY RIGHTS.
5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1,
OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
7. This License Agreement shall be governed by the federal
intellectual property law of the United States, including without
limitation the federal copyright law, and, to the extent such
U.S. federal law does not apply, by the law of the Commonwealth of
Virginia, excluding Virginia's conflict of law provisions.
Notwithstanding the foregoing, with regard to derivative works based
on Python 1.6.1 that incorporate non-separable material that was
previously distributed under the GNU General Public License (GPL), the
law of the Commonwealth of Virginia shall govern this License
Agreement only as to issues arising under or with respect to
Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this
License Agreement shall be deemed to create any relationship of
agency, partnership, or joint venture between CNRI and Licensee. This
License Agreement does not grant permission to use CNRI trademarks or
trade name in a trademark sense to endorse or promote products or
services of Licensee, or any third party.
8. By clicking on the ``ACCEPT'' button where indicated, or by copying,
installing or otherwise using Python 1.6.1, Licensee agrees to be
bound by the terms and conditions of this License Agreement.
ACCEPT
CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2
Copyright © 1991 - 1995, Stichting Mathematisch Centrum
Amsterdam, The Netherlands. All rights reserved.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Stichting Mathematisch
Centrum or CWI not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.
STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


7.1.2 The None Object

typeObjects.html | fundamental.html | numericObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.1.1 Type Objects (typeObjects.html)
Up:
7.1 Fundamental Objects (fundamental.html)
Next:
7.2 Numeric Objects (numericObjects.html)
---
## 7.1.2 The None Object
Note that the PyTypeObject for `None` is not directly
exposed in the Python/C API. Since `None` is a singleton,
testing for object identity (using "==" in C) is sufficient.
There is no PyNone_Check() function for the same reason.


10.5 Number Object Structures

mapping-structs.html | newTypes.html | sequence-structs.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
10.4 Mapping Object Structures (mapping-structs.html)
Up:
10. Object Implementation Support (newTypes.html)
Next:
10.6 Sequence Object Structures (sequence-structs.html)
---
# 10.5 Number Object Structures


6.2 Number Protocol

object.html | abstract.html | sequence.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
6.1 Object Protocol (object.html)
Up:
6. Abstract Objects Layer (abstract.html)
Next:
6.3 Sequence Protocol (sequence.html)
---
# 6.2 Number Protocol


7.2 Numeric Objects

noneObject.html | concrete.html | intObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.1.2 The None Object (noneObject.html)
Up:
7. Concrete Objects Layer (concrete.html)
Next:
7.2.1 Plain Integer Objects (intObjects.html)
---
# 7.2 Numeric Objects


6.1 Object Protocol

abstract.html | abstract.html | number.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
6. Abstract Objects Layer (abstract.html)
Up:
6. Abstract Objects Layer (abstract.html)
Next:
6.2 Number Protocol (number.html)
---
# 6.1 Object Protocol
Subclass determination is done in a fairly straightforward way, but
includes a wrinkle that implementors of extensions to the class system
may want to be aware of. If A and B are class
objects, B is a subclass of A if it inherits from
A either directly or indirectly. If either is not a class
object, a more general mechanism is used to determine the class
relationship of the two objects. When testing if B is a
subclass of A, if A is B,
PyObject_IsSubclass() returns true. If A and
B are different objects, B's __bases__ attribute
is searched in a depth-first fashion for A -- the presence of
the __bases__ attribute is considered sufficient for this
determination.


1.2 Objects, Types and Reference Counts

includes.html | intro.html | refcounts.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
1.1 Include Files (includes.html)
Up:
1. Introduction (intro.html)
Next:
1.2.1 Reference Counts (refcounts.html)
---
# 1.2 Objects, Types and Reference Counts
Most Python/C API functions have one or more arguments as well as a
return value of type PyObject*. This type is a pointer
to an opaque data type representing an arbitrary Python
object. Since all Python object types are treated the same way by the
Python language in most situations (e.g., assignments, scope rules,
and argument passing), it is only fitting that they should be
represented by a single C type. Almost all Python objects live on the
heap: you never declare an automatic or static variable of type
PyObject, only pointer variables of type PyObject* can
be declared. The sole exception are the type objects;
since these must never be deallocated, they are typically static
PyTypeObject objects.
All Python objects (even Python integers) have a type and a
reference count. An object's type determines what kind of object
it is (e.g., an integer, a list, or a user-defined function; there are
many more as explained in the Python
Reference Manual (../ref/ref.html)). For each of the well-known types there is a macro
to check whether an object is of that type; for instance,
"PyList_Check(a)" is true if (and only if) the object
pointed to by a is a Python list.


5.1 Operating System Utilities

utilities.html | utilities.html | processControl.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
5. Utilities (utilities.html)
Up:
5. Utilities (utilities.html)
Next:
5.2 Process Control (processControl.html)
---
# 5.1 Operating System Utilities


7.5 Other Objects

dictObjects.html | concrete.html | fileObjects.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
7.4.1 Dictionary Objects (dictObjects.html)
Up:
7. Concrete Objects Layer (concrete.html)
Next:
7.5.1 File Objects (fileObjects.html)
---
# 7.5 Other Objects


5.2 Process Control

os.html | utilities.html | importing.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
5.1 Operating System Utilities (os.html)
Up:
5. Utilities (utilities.html)
Next:
5.3 Importing Modules (importing.html)
---
# 5.2 Process Control


8.2 Profiling and Tracing

threads.html | initialization.html | advanced-debugging.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
8.1 Thread State and (threads.html)
Up:
8. Initialization, Finalization, and (initialization.html)
Next:
8.3 Advanced Debugger Support (advanced-debugging.html)
---
# 8.2 Profiling and Tracing
The Python interpreter provides some low-level support for attaching
profiling and execution tracing facilities. These are used for
profiling, debugging, and coverage analysis tools.
Starting with Python 2.2, the implementation of this facility was
substantially revised, and an interface from C was added. This C
interface allows the profiling or tracing code to avoid the overhead
of calling through Python-level callable objects, making a direct C
function call instead. The essential attributes of the facility have
not changed; the interface allows trace functions to be installed
per-thread, and the basic events reported to the trace function are
the same as had been reported to the Python-level trace functions in
previous versions.


1.2.1.1 Reference Count Details

refcounts.html | refcounts.html | types.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
1.2.1 Reference Counts (refcounts.html)
Up:
1.2.1 Reference Counts (refcounts.html)
Next:
1.2.2 Types (types.html)
---
### 1.2.1.1 Reference Count Details
The reference count behavior of functions in the Python/C API is best
explained in terms of ownership of references. Note that we
talk of owning references, never of owning objects; objects are always
shared! When a function owns a reference, it has to dispose of it
properly -- either by passing ownership on (usually to its caller) or
by calling Py_DECREF() or Py_XDECREF(). When
a function passes ownership of a reference on to its caller, the
caller is said to receive a new reference. When no ownership
is transferred, the caller is said to borrow the reference.
Nothing needs to be done for a borrowed reference.
Conversely, when a calling function passes it a reference to an
object, there are two possibilities: the function steals a
reference to the object, or it does not. Few functions steal
references; the two notable exceptions are
PyList_SetItem()and
PyTuple_SetItem() which
steal a reference to the item (but not to the tuple or list into which
the item is put!). These functions were designed to steal a reference
because of a common idiom for populating a tuple or list with newly
created objects; for example, the code to create the tuple `(1,
2, "three")` could look like this (forgetting about error handling for
the moment; a better way to code this is shown below):
```text

PyObject *t;

t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
PyTuple_SetItem(t, 2, PyString_FromString("three"));
```
Incidentally, PyTuple_SetItem() is the only way to
set tuple items; PySequence_SetItem() and
PyObject_SetItem() refuse to do this since tuples are an
immutable data type. You should only use
PyTuple_SetItem() for tuples that you are creating
yourself.
Equivalent code for populating a list can be written using
PyList_New() and PyList_SetItem(). Such code
can also use PySequence_SetItem(); this illustrates the
difference between the two (the extra Py_DECREF() calls):
```text

PyObject *l, *x;

l = PyList_New(3);
x = PyInt_FromLong(1L);
PySequence_SetItem(l, 0, x); Py_DECREF(x);
x = PyInt_FromLong(2L);
PySequence_SetItem(l, 1, x); Py_DECREF(x);
x = PyString_FromString("three");
PySequence_SetItem(l, 2, x); Py_DECREF(x);
```
You might find it strange that the ``recommended'' approach takes more
code. However, in practice, you will rarely use these ways of
creating and populating a tuple or list. There's a generic function,
Py_BuildValue(), that can create most common objects from
C values, directed by a format string. For example, the
above two blocks of code could be replaced by the following (which
also takes care of the error checking):
```text

PyObject *t, *l;

t = Py_BuildValue("(iis)", 1, 2, "three");
l = Py_BuildValue("[iis]", 1, 2, "three");
```
It is much more common to use PyObject_SetItem() and
friends with items whose references you are only borrowing, like
arguments that were passed in to the function you are writing. In
that case, their behaviour regarding reference counts is much saner,
since you don't have to increment a reference count so you can give a
reference away (``have it be stolen''). For example, this function
sets all items of a list (actually, any mutable sequence) to a given
item:
```text

int
set_all(PyObject *target, PyObject *item)
{
int i, n;

n = PyObject_Length(target);
if (n < 0)
return -1;
for (i = 0; i < n; i++) {
if (PyObject_SetItem(target, i, item) < 0)
return -1;
}
return 0;
}
```
The situation is slightly different for function return values.
While passing a reference to most functions does not change your
ownership responsibilities for that reference, many functions that
return a referece to an object give you ownership of the reference.
The reason is simple: in many cases, the returned object is created
on the fly, and the reference you get is the only reference to the
object. Therefore, the generic functions that return object
references, like PyObject_GetItem() and
PySequence_GetItem(), always return a new reference (the
caller becomes the owner of the reference).
It is important to realize that whether you own a reference returned
by a function depends on which function you call only -- the
plumage (the type of the type of the object passed as an
argument to the function) doesn't enter into it! Thus, if you
extract an item from a list using PyList_GetItem(), you
don't own the reference -- but if you obtain the same item from the
same list using PySequence_GetItem() (which happens to
take exactly the same arguments), you do own a reference to the
returned object.
Here is an example of how you could write a function that computes the
sum of the items in a list of integers; once using
PyList_GetItem() and once using
PySequence_GetItem()
```text

long
sum_list(PyObject *list)
{
int i, n;
long total = 0;
PyObject *item;

n = PyList_Size(list);
if (n < 0)
return -1; /* Not a list */
for (i = 0; i < n; i++) {
item = PyList_GetItem(list, i); /* Can't fail */
if (!PyInt_Check(item)) continue; /* Skip non-integers */
total += PyInt_AsLong(item);
}
return total;
}
```
```text

long
sum_sequence(PyObject *sequence)
{
int i, n;
long total = 0;
PyObject *item;
n = PySequence_Length(sequence);
if (n < 0)
return -1; /* Has no length */
for (i = 0; i < n; i++) {
item = PySequence_GetItem(sequence, i);
if (item == NULL)
return -1; /* Not a sequence, or other failure */
if (PyInt_Check(item))
total += PyInt_AsLong(item);
Py_DECREF(item); /* Discard reference ownership */
}
return total;
}
```


1.2.1 Reference Counts

objects.html | objects.html | refcountDetails.html | Python/C API Reference Manual | contents.html | genindex.html
Previous:
1.2 Objects, Types and (objects.html)
Up:
1.2 Objects, Types and (objects.html)
Next:
1.2.1.1 Reference Count Details (refcountDetails.html)
---
## 1.2.1 Reference Counts
The reference count is important because today's computers have a
finite (and often severely limited) memory size; it counts how many
different places there are that have a reference to an object. Such a
place could be another object, or a global (or static) C variable, or
a local variable in some C function. When an object's reference count
becomes zero, the object is deallocated. If it contains references to
other objects, their reference count is decremented. Those other
objects may be deallocated in turn, if this decrement makes their
reference count become zero, and so on. (There's an obvious problem
with objects that reference each other here; for now, the solution is
``don't do that.'')
Reference counts are always manipulated explicitly. The normal way is
to use the macro Py_INCREF()to
increment an object's reference count by one, and
Py_DECREF()to decrement it by
one. The Py_DECREF() macro is considerably more complex
than the incref one, since it must check whether the reference count
becomes zero and then cause the object's deallocator to be called.
The deallocator is a function pointer contained in the object's type
structure. The type-specific deallocator takes care of decrementing
the reference counts for other objects contained in the object if this
is a compound object type, such as a list, as well as performing any
additional finalization that's needed. There's no chance that the
reference count can overflow; at least as many bits are used to hold
the reference count as there are distinct memory locations in virtual
memory (assuming `sizeof(long) >= sizeof(char*)`). Thus, the
reference count increment is a simple operation.
It is not necessary to increment an object's reference count for every
local variable that contains a pointer to an object. In theory, the
object's reference count goes up by one when the variable is made to
point to it and it goes down by one when the variable goes out of
scope. However, these two cancel each other out, so at the end the
reference count hasn't changed. The only real reason to use the
reference count is to prevent the object from being deallocated as
long as our variable is pointing to it. If we know that there is at
least one other reference to the object that lives at least as long as
our variable, there is no need to increment the reference count
temporarily. An important situation where this arises is in objects
that are passed as arguments to C functions in an extension module
that are called from Python; the call mechanism guarantees to hold a
reference to every argument for the duration of the call.
However, a common pitfall is to extract an object from a list and
hold on to it for a while without incrementing its reference count.
Some other operation might conceivably remove the object from the
list, decrementing its reference count and possible deallocating it.
The real danger is that innocent-looking operations may invoke
arbitrary Python code which could do this; there is a code path which
allows control to flow back to the user from a Py_DECREF(),
so almost any operation is potentially dangerous.
A safe approach is to always use the generic operations (functions
whose name begins with "PyObject_", "PyNumber_",
"PySequence_" or "PyMapping_"). These operations always
increment the reference count of the object they return. This leaves
the caller with the responsibility to call
Py_DECREF() when they are done with the result; this soon
becomes second nature.