About the Python Documentation

./ | About the Python Documentation
Up:
Python Documentation Index (./)
---
## 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

./ | 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 | Nadim Ghaznavi | Piers Lauder | Nick Russo
Michael Abbott | Jonathan Giddy | Glyph Lefkowitz | Chris Ryland
Steve Alexander | Shelley Gooch | Marc-Andr Lemburg | Constantina S.
Jim Ahlstrom | Nathaniel Gray | Ulf A. Lindgren | Hugh Sasse
Fred Allen | Grant Griffin | Everett Lipman | Bob Savage
A. Amoroso | Thomas Guettler | Mirko Liss | Scott Schram
Pehr Anderson | Anders Hammarquist | Martin von Lwis | Neil Schemenauer
Oliver Andrich | Mark Hammond | Fredrik Lundh | Barry Scott
Jess Cea Avin | Harald Hanche-Olsen | Jeff MacDonald | Joakim Sernbrant
Daniel Barclay | Manus Hand | John Machin | Justin Sheehy
Chris Barker | Gerhard Hring | Andrew MacIntyre | Michael Simcich
Don Bashford | Travis B. Hartwell | Vladimir Marangozov | Ionel Simionescu
Anthony Baxter | Janko Hauser | Vincent Marchetti | Roy Smith
Bennett Benson | Bernhard Herzog | Laura Matson | Clay Spence
Jonathan Black | Magnus L. Hetland | Daniel May | Nicholas Spies
Robin Boerdijk | Konrad Hinsen | Doug Mennella | Tage Stabell-Kulo
Michal Bozon | Stefan Hoffmeister | Paolo Milani | Frank Stajano
Aaron Brancotti | Albert Hofkamp | Skip Montanaro | Anthony Starks
Keith Briggs | Gregor Hoffleit | Paul Moore | Greg Stein
Lee Busby | Steve Holden | Ross Moore | Peter Stoehr
Lorenzo M. Catucci | Thomas Holenstein | Sjoerd Mullender | Mark Summerfield
Mauro Cicognini | Gerrit Holl | Dale Nagata | Reuben Sumner
Gilles Civario | Rob Hooft | Ng Pheng Siong | Kalle Svensson
Mike Clarkson | Brian Hooper | Koray Oner | Jim Tittsler
Steve Clift | Randall Hopper | Denis S. Otkidach | Martijn Vries
Matthew Cowles | Michael Hudson | Zooko O'Whielacronx | Charles G. Waldman
Jeremy Craven | Jeremy Hylton | William Park | Greg Ward
Andrew Dalke | Roger Irwin | Joonas Paalasmaa | Barry Warsaw
Ben Darnell | 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
Hernan Martinez 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
Ben Gertzfield | Detlef Lannert | Donald Wallace Rouse II
---
./ | Acknowledgements


About this document ...

genindex.html | api.html | Python/C API Reference Manual | contents.html | genindex.html
---
# About this document ...
Python/C API Reference Manual,
December 21, 2001, Release 2.2
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, 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.
---
genindex.html | api.html | Python/C API Reference Manual | contents.html | genindex.html
---
Release 2.2, documentation updated on December 21, 2001.


6. Abstract Objects Layer

arg-parsing.html | api.html | object.html | Python/C API Reference Manual | contents.html | genindex.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
---
# 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
---
# 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
---
# Python/C API Reference Manual
Guido van Rossum
Fred L. Drake, Jr., editor
PythonLabs
Email: python-docs@python.org
Release 2.2
December 21, 2001


marshalling-utils.html | utilities.html | abstract.html | Python/C API Reference Manual | contents.html | genindex.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).


10.6 Buffer Object Structures

sequence-structs.html | newTypes.html | supporting-iteration.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10.6 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
---
## 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.6 (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
---
### 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
---
## 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
---
## 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 | mapping-structs.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10.2 Common Object Structures
PyObject, PyVarObject
PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
Typedefs:
unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
setattrofunc, cmpfunc, reprfunc, hashfunc
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 flags can have the following values. Only METH_VARARGS
and METH_KEYWORDS can be combined; the others can't.


7.2.4 Complex Number Objects

floatObjects.html | numericObjects.html | node37.html | Python/C API Reference Manual | contents.html | genindex.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

iterator.html | api.html | fundamental.html | Python/C API Reference Manual | contents.html | genindex.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
---
## 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)
  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. Defining New Object Types (newTypes.html)
  - 10.1 Allocating Objects on the Heap (allocating-objects.html)
  10.2 Common Object Structures (common-structs.html)
  10.3 Mapping Object Structures (mapping-structs.html)
  10.4 Number Object Structures (number-structs.html)
  10.5 Sequence Object Structures (sequence-structs.html)
  10.6 Buffer Object Structures (buffer-structs.html)
  10.7 Supporting the Iterator Protocol (supporting-iteration.html)
  10.8 Supporting Cyclic Garbarge Collection (supporting-cycle-detection.html)
  - 10.8.1 Example Cycle Collector Support (example-cycle-support.html)
  A. Reporting Bugs (reporting-bugs.html)
  B. History and License (node79.html)
  - B.1 History of the software (node80.html)
  B.2 Terms and conditions for accessing or otherwise using Python (node81.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
---
# 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
---
## 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
---
## 7.4.1 Dictionary Objects


1.4 Embedding Python

exceptions.html | intro.html | veryhigh.html | Python/C API Reference Manual | contents.html | genindex.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.2 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.2. (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).


10.8.1 Example Cycle Collector Support

supporting-cycle-detection.html | supporting-cycle-detection.html | reporting-bugs.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 10.8.1 Example Cycle Collector Support
This example shows only enough of the implementation of an extension
type to show how the garbage collector support needs to be added. It
shows the definition of the object structure, the
tp_traverse, tp_clear and tp_dealloc
implementations, the type structure, and a constructor -- the module
initialization needed to export the constructor to Python is not shown
as there are no special considerations there for the collector. To
make this interesting, assume that the module exposes ways for the
container field of the object to be modified. Note that
since no checks are made on the type of the object used to initialize
container, we have to assume that it may be a container.
```text

#include "Python.h"

typedef struct {
PyObject_HEAD
PyObject *container;
} MyObject;

static int
my_traverse(MyObject *self, visitproc visit, void *arg)
{
if (self->container != NULL)
return visit(self->container, arg);
else
return 0;
}

static int
my_clear(MyObject *self)
{
Py_XDECREF(self->container);
self->container = NULL;

return 0;
}

static void
my_dealloc(MyObject *self)
{
PyObject_GC_UnTrack((PyObject *) self);
Py_XDECREF(self->container);
PyObject_GC_Del(self);
}
```
```text

statichere PyTypeObject
MyObject_Type = {
PyObject_HEAD_INIT(NULL)
0,
"MyObject",
sizeof(MyObject),
0,
(destructor)my_dealloc, /* tp_dealloc */
0, /* tp_print */
0, /* tp_getattr */
0, /* tp_setattr */
0, /* tp_compare */
0, /* tp_repr */
0, /* tp_as_number */
0, /* tp_as_sequence */
0, /* tp_as_mapping */
0, /* tp_hash */
0, /* tp_call */
0, /* tp_str */
0, /* tp_getattro */
0, /* tp_setattro */
0, /* tp_as_buffer */
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC,
0, /* tp_doc */
(traverseproc)my_traverse, /* tp_traverse */
(inquiry)my_clear, /* tp_clear */
0, /* tp_richcompare */
0, /* tp_weaklistoffset */
};

/* This constructor should be made accessible from Python. */
static PyObject *
new_object(PyObject *unused, PyObject *args)
{
PyObject *container = NULL;
MyObject *result = NULL;

if (PyArg_ParseTuple(args, "|O:new_object", &container)) {
result = PyObject_GC_New(MyObject, &MyObject_Type);
if (result != NULL) {
result->container = container;
PyObject_GC_Track(result);
}
}
return (PyObject *) result;
}
```


4. Exception Handling

countingRefs.html | api.html | standardExceptions.html | Python/C API Reference Manual | contents.html | genindex.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 propogated, 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
---
# 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
---
## 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
---
## 7.2.3 Floating Point Objects


Front Matter

api.html | api.html | contents.html | Python/C API Reference Manual | contents.html | genindex.html
---
# Front Matter
Copyright © 2001 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
---
# 7.1 Fundamental Objects
This section describes Python type objects and the singleton object
`None`.


Index

node81.html | api.html | about.html | Python/C API Reference Manual | contents.html
---
## Index
---
_ (#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)
---
## _ (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
---
# 5.3 Importing Modules


1.1 Include Files

intro.html | intro.html | objects.html | Python/C API Reference Manual | contents.html | genindex.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.2/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
---
# Python/C API Reference Manual
Guido van Rossum
Fred L. Drake, Jr., editor
PythonLabs
Email: python-docs@python.org
Release 2.2
December 21, 2001


cell-objects.html | api.html | threads.html | Python/C API Reference Manual | contents.html | genindex.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
---
## 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
---
## 7.2.1 Plain Integer Objects


1. Introduction

contents.html | api.html | includes.html | Python/C API Reference Manual | contents.html | genindex.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
---
## 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 | concrete.html | Python/C API Reference Manual | contents.html | genindex.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:


7.3.5 List Objects

tupleObjects.html | sequenceObjects.html | mapObjects.html | Python/C API Reference Manual | contents.html | genindex.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
---
## 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
---
# 7.4 Mapping Objects


10.3 Mapping Object Structures

common-structs.html | newTypes.html | number-structs.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10.3 Mapping Object Structures


6.4 Mapping Protocol

sequence.html | abstract.html | iterator.html | Python/C API Reference Manual | contents.html | genindex.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
---
# 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
---
# 9. Memory Management


9.3 Examples

memoryInterface.html | memory.html | newTypes.html | Python/C API Reference Manual | contents.html | genindex.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
---
# 9.2 Memory Interface
The following function sets, modeled after the ANSI C standard, 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
---
# 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 on 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
---
## 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
---
## 7.5.4 Module Objects
There are only a few functions special to module objects.


10. Defining New Object Types

memoryExamples.html | api.html | allocating-objects.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10. 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
---
# 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 | node38.html | Python/C API Reference Manual | contents.html | genindex.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.


node37.html | complexObjects.html | sequenceObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
### 7.2.4.2 Complex Numbers as Python Objects


7.4.4.1 Complex Numbers as C Structures

complexObjects.html | complexObjects.html | node45.html | Python/C API Reference Manual | contents.html | genindex.html
---
### 7.4.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.


node44.html | complexObjects.html | otherObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
### 7.4.4.2 Complex Numbers as Python Objects


B. History and License

reporting-bugs.html | api.html | node80.html | Python/C API Reference Manual | contents.html | genindex.html
---
# B. History and License


B.1 History of the software

node79.html | node79.html | node81.html | Python/C API Reference Manual | contents.html | genindex.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 Zope Corporation (then Digital
Creations; 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. Digital Creations 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.


node80.html | node79.html | genindex.html | Python/C API Reference Manual | contents.html | genindex.html
---
# B.2 Terms and conditions for accessing or otherwise using Python
PSF LICENSE AGREEMENT FOR PYTHON 2.2
1. This LICENSE AGREEMENT is between the Python Software Foundation
(``PSF''), and the Individual or Organization (``Licensee'') accessing
and otherwise using Python 2.2 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.2 alone or in any derivative version, provided, however, that
PSF's License Agreement and PSF's notice of copyright, i.e.,
``Copyright © 2001 Python Software Foundation; All Rights
Reserved'' are retained in Python 2.2 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.2 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.2.
4. PSF is making Python 2.2 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.2 WILL
NOT INFRINGE ANY THIRD PARTY RIGHTS.
5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
2.2 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR
LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON
2.2, 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.2, 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
---
## 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.4 Number Object Structures

mapping-structs.html | newTypes.html | sequence-structs.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10.4 Number Object Structures


6.2 Number Protocol

object.html | abstract.html | sequence.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 6.2 Number Protocol


7.2 Numeric Objects

noneObject.html | concrete.html | intObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 7.2 Numeric Objects


6.1 Object Protocol

abstract.html | abstract.html | number.html | Python/C API Reference Manual | contents.html | genindex.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
---
# 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
---
# 5.1 Operating System Utilities


7.5 Other Objects

dictObjects.html | concrete.html | fileObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 7.5 Other Objects


5.2 Process Control

os.html | utilities.html | importing.html | Python/C API Reference Manual | contents.html | genindex.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
---
# 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
---
### 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
---
## 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.


A. Reporting Bugs

example-cycle-support.html | api.html | node79.html | Python/C API Reference Manual | contents.html | genindex.html
---
# A. Reporting Bugs
Python is a mature programming language which has established a
reputation for stability. In order to maintain this reputation, the
developers would like to know of any deficiencies you find in Python
or its documentation.
All bug reports should be submitted via the Python Bug Tracker on
SourceForge (http://sourceforge.net/bugs/?group_id=5470). The
bug tracker offers a Web form which allows pertinent information to be
entered and submitted to the developers.
Before submitting a report, please log into SourceForge if you are a
member; this will make it possible for the developers to contact you
for additional information if needed. If you are not a SourceForge
member but would not mind the developers contacting you, you may
include your email address in your bug description. In this case,
please realize that the information is publically available and cannot
be protected.
The first step in filing a report is to determine whether the problem
has already been reported. The advantage in doing so, aside from
saving the developers time, is that you learn what has been done to
fix it; it may be that the problem has already been fixed for the next
release, or additional information is needed (in which case you are
welcome to provide it if you can!). To do this, search the bug
database using the search box near the bottom of the page.
If the problem you're reporting is not already in the bug tracker, go
back to the Python Bug Tracker
(http://sourceforge.net/bugs/?group_id=5470). Select the
``Submit a Bug'' link at the top of the page to open the bug reporting
form.
The submission form has a number of fields. The only fields that are
required are the ``Summary'' and ``Details'' fields. For the summary,
enter a very short description of the problem; less than ten
words is good. In the Details field, describe the problem in detail,
including what you expected to happen and what did happen. Be sure to
include the version of Python you used, whether any extension modules
were involved, and what hardware and software platform you were using
(including version information as appropriate).
The only other field that you may want to set is the ``Category''
field, which allows you to place the bug report into a broad category
(such as ``Documentation'' or ``Library'').
Each bug report will be assigned to a developer who will determine
what needs to be done to correct the problem. If you have a
SourceForge account and logged in to report the problem, you will
receive an update each time action is taken on the bug.
See Also:


10.5 Sequence Object Structures

number-structs.html | newTypes.html | buffer-structs.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10.5 Sequence Object Structures


6.3 Sequence Protocol

number.html | abstract.html | mapping.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 6.3 Sequence Protocol


7.3 Sequence Objects

node38.html | concrete.html | stringObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 7.3 Sequence Objects
Generic operations on sequence objects were discussed in the previous
chapter; this section deals with the specific kinds of sequence
objects that are intrinsic to the Python language.


7.5.7 Slice Objects

descriptor-objects.html | otherObjects.html | weakref-objects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.5.7 Slice Objects


4.1 Standard Exceptions

exceptionHandling.html | exceptionHandling.html | node15.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 4.1 Standard Exceptions
All standard Python exceptions are available as global variables whose
names are "PyExc_" followed by the Python exception name. These
have the type PyObject*; they are all class objects. For
completeness, here are all the variables:
Notes:
(1): This is a base class for other standard exceptions.
(2): This is the same as weakref.ReferenceError.
(3): Only defined on Windows; protect code that uses this by testing that
the preprocessor macro `MS_WINDOWS` is defined.


7.3.1 String Objects

sequenceObjects.html | sequenceObjects.html | unicodeObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.3.1 String Objects
These functions raise TypeError when expecting a string
parameter and are called with a non-string parameter.


supporting-iteration.html | newTypes.html | example-cycle-support.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10.8 Supporting Cyclic Garbarge Collection
Python's support for detecting and collecting garbage which involves
circular references requires support from object types which are
``containers'' for other objects which may also be containers. Types
which do not store references to other objects, or which only store
references to atomic types (such as numbers or strings), do not need
to provide any explicit support for garbage collection.
To create a container type, the tp_flags field of the type
object must include the Py_TPFLAGS_HAVE_GC and provide an
implementation of the tp_traverse handler. If instances of the
type are mutable, a tp_clear implementation must also be
provided.
Constructors for container types must conform to two rules:
1. The memory for the object must be allocated using
PyObject_GC_New() or PyObject_GC_VarNew().
2. Once all the fields which may contain references to other
containers are initialized, it must call
PyObject_GC_Track().
Similarly, the deallocator for the object must conform to a similar
pair of rules:
1. Before fields which refer to other containers are invalidated,
PyObject_GC_UnTrack() must be called.
2. The object's memory must be deallocated using
PyObject_GC_Del().
The tp_traverse handler accepts a function parameter of this
type:
The tp_traverse handler must have the following type:
The tp_clear handler must be of the inquiry type, or
NULL if the object is immutable.


10.7 Supporting the Iterator Protocol

buffer-structs.html | newTypes.html | supporting-cycle-detection.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10.7 Supporting the Iterator Protocol


initialization.html | initialization.html | profiling.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 8.1 Thread State and the Global Interpreter Lock
The Python interpreter is not fully thread safe. In order to support
multi-threaded Python programs, there's a global lock that must be
held by the current thread before it can safely access Python objects.
Without the lock, even the simplest operations could cause problems in
a multi-threaded program: for example, when two threads simultaneously
increment the reference count of the same object, the reference count
could end up being incremented only once instead of twice.
Therefore, the rule exists that only the thread that has acquired the
global interpreter lock may operate on Python objects or call Python/C
API functions. In order to support multi-threaded Python programs,
the interpreter regularly releases and reacquires the lock -- by
default, every ten bytecode instructions (this can be changed with
sys.setcheckinterval()). The lock is also released and
reacquired around potentially blocking I/O operations like reading or
writing a file, so that other threads can run while the thread that
requests the I/O is waiting for the I/O operation to complete.
The Python interpreter needs to keep some bookkeeping information
separate per thread -- for this it uses a data structure called
PyThreadState. This is new in Python
1.5; in earlier versions, such state was stored in global variables,
and switching threads could cause problems. In particular, exception
handling is now thread safe, when the application uses
sys.exc_info() to access the exception last raised in the
current thread.
There's one global variable left, however: the pointer to the current
PyThreadStatestructure. While most
thread packages have a way to store ``per-thread global data,''
Python's internal platform independent thread abstraction doesn't
support this yet. Therefore, the current thread state must be
manipulated explicitly.
This is easy enough in most cases. Most code manipulating the global
interpreter lock has the following simple structure:
```text

Save the thread state in a local variable.
Release the interpreter lock.
...Do some blocking I/O operation...
Reacquire the interpreter lock.
Restore the thread state from the local variable.
```
This is so common that a pair of macros exists to simplify it:
```text

Py_BEGIN_ALLOW_THREADS
...Do some blocking I/O operation...
Py_END_ALLOW_THREADS
```
The `Py_BEGIN_ALLOW_THREADS`macro
opens a new block and declares a hidden local variable; the
`Py_END_ALLOW_THREADS`macro closes
the block. Another advantage of using these two macros is that when
Python is compiled without thread support, they are defined empty,
thus saving the thread state and lock manipulations.
When thread support is enabled, the block above expands to the
following code:
```text

PyThreadState *_save;

_save = PyEval_SaveThread();
...Do some blocking I/O operation...
PyEval_RestoreThread(_save);
```
Using even lower level primitives, we can get roughly the same effect
as follows:
```text

PyThreadState *_save;

_save = PyThreadState_Swap(NULL);
PyEval_ReleaseLock();
...Do some blocking I/O operation...
PyEval_AcquireLock();
PyThreadState_Swap(_save);
```
There are some subtle differences; in particular,
PyEval_RestoreThread()saves
and restores the value of the global variable
errno, since the lock manipulation does not
guarantee that errno is left alone. Also, when thread support
is disabled,
PyEval_SaveThread()and
PyEval_RestoreThread() don't manipulate the lock; in this
case, PyEval_ReleaseLock()and
PyEval_AcquireLock()are not
available. This is done so that dynamically loaded extensions
compiled with thread support enabled can be loaded by an interpreter
that was compiled with disabled thread support.
The global interpreter lock is used to protect the pointer to the
current thread state. When releasing the lock and saving the thread
state, the current thread state pointer must be retrieved before the
lock is released (since another thread could immediately acquire the
lock and store its own thread state in the global variable).
Conversely, when acquiring the lock and restoring the thread state,
the lock must be acquired before storing the thread state pointer.
Why am I going on with so much detail about this? Because when
threads are created from C, they don't have the global interpreter
lock, nor is there a thread state data structure for them. Such
threads must bootstrap themselves into existence, by first creating a
thread state data structure, then acquiring the lock, and finally
storing their thread state pointer, before they can start using the
Python/C API. When they are done, they should reset the thread state
pointer, release the lock, and finally free their thread state data
structure.
When creating a thread data structure, you need to provide an
interpreter state data structure. The interpreter state data
structure hold global data that is shared by all threads in an
interpreter, for example the module administration
(`sys.modules`). Depending on your needs, you can either create
a new interpreter state data structure, or share the interpreter state
data structure used by the Python main thread (to access the latter,
you must obtain the thread state and access its interp member;
this must be done by a thread that is created by Python or by the main
thread after Python is initialized).
The following macros are normally used without a trailing semicolon;
look for example usage in the Python source distribution.
All of the following functions are only available when thread support
is enabled at compile time, and must be called only when the
interpreter lock has been created.


7.3.4 Tuple Objects

bufferObjects.html | sequenceObjects.html | listObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.3.4 Tuple Objects


7.1.1 Type Objects

fundamental.html | fundamental.html | noneObject.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.1.1 Type Objects


1.2.2 Types

refcountDetails.html | objects.html | exceptions.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 1.2.2 Types
There are few other data types that play a significant role in
the Python/C API; most are simple C types such as int,
long, double and char*. A few structure types
are used to describe static tables used to list the functions exported
by a module or the data attributes of a new object type, and another
is used to describe the value of a complex number. These will
be discussed together with the functions that use them.


7.3.2.2 Methods and Slot Functions

builtinCodecs.html | unicodeObjects.html | bufferObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
### 7.3.2.2 Methods and Slot Functions
The following APIs are capable of handling Unicode objects and strings
on input (we refer to them as strings in the descriptions) and return
Unicode objects or integers as apporpriate.
They all return NULL or `-1` if an exception occurs.


7.3.2 Unicode Objects

stringObjects.html | sequenceObjects.html | builtinCodecs.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.3.2 Unicode Objects
These are the basic Unicode object types used for the Unicode
implementation in Python:
The following APIs are really C macros and can be used to do fast
checks and to access internal read-only data of Unicode objects:
Unicode provides many different character properties. The most often
needed ones are available through these macros which are mapped to C
functions depending on the Python configuration.
These APIs can be used for fast direct character conversions:
To create Unicode objects and access their basic sequence properties,
use these APIs:
If the platform supports wchar_t and provides a header file
wchar.h, Python can interface directly to this type using the
following functions. Support is optimized if Python's own
Py_UNICODE type is identical to the system's wchar_t.


5. Utilities

node15.html | api.html | os.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 5. Utilities
The functions in this chapter perform various utility tasks, ranging
from helping C code be more portable across platforms, using Python
modules from C, and parsing function arguments and constructing Python
values from C values.


2. The Very High Level Layer

embedding.html | api.html | countingRefs.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 2. The Very High Level Layer
The functions in this chapter will let you execute Python source code
given in a file or a buffer, but they will not let you interact in a
more detailed way with the interpreter.
Several of these functions accept a start symbol from the grammar as a
parameter. The available start symbols are Py_eval_input,
Py_file_input, and Py_single_input. These are
described following the functions which accept them as parameters.
Note also that several of these functions take FILE*
parameters. On particular issue which needs to be handled carefully
is that the FILE structure for different C libraries can be
different and incompatible. Under Windows (at least), it is possible
for dynamically linked extensions to actually use different libraries,
so care should be taken that FILE* parameters are only passed
to these functions if it is certain that they were created by the same
library that the Python runtime is using.


7.5.8 Weak Reference Objects

slice-objects.html | otherObjects.html | cObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.5.8 Weak Reference Objects
Python supports weak references as first-class objects. There
are two specific object types which directly implement weak
references. The first is a simple reference object, and the second
acts as a proxy for the original object as much as it can.


About this document ...

module-distutils.sysconfig.html | dist.html | Distributing Python Modules
---
# About this document ...
Distributing Python Modules
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, 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.
---
module-distutils.sysconfig.html | dist.html | Distributing Python Modules
---


About this document ...

sdist-cmd.html | dist.html | Distributing Python Modules
---
# About this document ...
Distributing Python Modules
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, 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.
---
sdist-cmd.html | dist.html | Distributing Python Modules
---