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.pythonlabs.com/).
## 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.
---


About this document ...

genindex.html | api.html | Python/C API Reference Manual | contents.html | genindex.html
---
# About this document ...
Python/C API Reference Manual,
September 18, 2000, Release 1.6
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
---


6. Abstract Objects Layer

importing.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.


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
BeOpen PythonLabs
E-mail: python-docs@python.org
September 18, 2000
Release 1.6


10.5 Buffer Object Structures

sequence-structs.html | newTypes.html | genindex.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10.5 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.2.3 Buffer Objects

unicodeMethodsAndSlots.html | sequenceObjects.html | tupleObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.2.3 Buffer Objects
Python objects implemented in C can export a group of functions called
the ``buffer interface.'' These functions can
be used by an object to expose its data in a raw, byte-oriented
format. Clients of the object can use the buffer interface to access
the object data directly, without needing to copy it first.
Two examples of objects that support
the buffer interface are strings and arrays. The string object exposes
the character contents in the buffer interface's byte-oriented
form. An array can also expose its contents, but it should be noted
that array elements may be multi-byte values.
An example user of the buffer interface is the file object's
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 PyArgs_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.5 (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.2.2.1 Builtin Codecs

unicodeObjects.html | unicodeObjects.html | unicodeMethodsAndSlots.html | Python/C API Reference Manual | contents.html | genindex.html
---
### 7.2.2.1 Builtin 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 UTF-8.
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'' (ValueErrors are 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 excepted. 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
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.3 CObjects

moduleObjects.html | otherObjects.html | initialization.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.5.3 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.1 Common Object Structures

newTypes.html | newTypes.html | mapping-structs.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10.1 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


7.4.4 Complex Number Objects

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

mapping.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.


Contents

front.html | api.html | intro.html | Python/C API Reference Manual | genindex.html
---
## 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.
The following functions or macros are only for use within the
interpreter core: _Py_Dealloc(),
_Py_ForgetReference(), _Py_NewReference(), as
well as the global variable _Py_RefTotal.


7.3.1 Dictionary Objects

mapObjects.html | mapObjects.html | numericObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.3.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__ and
sys. 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/python1.5 (replacing 1.5 with the current
interpreter version) 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/python1.5. (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).
Sometimes, it is desirable to ``uninitialize'' Python. For instance,
the application may want to start over (make another call to
Py_Initialize()) or the application is simply done with its
use of Python and wants to free all memory allocated by Python. This
can be accomplished by calling Py_Finalize(). The function
Py_IsInitialized() returns
true if Python is currently in the initialized state. More
information about these functions is given in a later chapter.


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_Parse*() 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.
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
return 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 | moduleObjects.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.4.3 Floating Point Objects

longObjects.html | numericObjects.html | complexObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.4.3 Floating Point Objects


Front Matter

api.html | api.html | contents.html | Python/C API Reference Manual | contents.html | genindex.html
---
# Front Matter
BEOPEN.COM TERMS AND CONDITIONS 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 OPEN SOURCE LICENSE AGREEMENT
Python 1.6 is made available subject to the terms and conditions in
CNRI's License Agreement. This Agreement together with Python 1.6 may
be located on the Internet using the following unique, persistent
identifier (known as a handle): 1895.22/1012. This Agreement may also
be obtained from a proxy server on the Internet using the following
URL: http://hdl.handle.net/1895.22/1012.
CWI PERMISSIONS STATEMENT AND DISCLAIMER
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.
### 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

buffer-structs.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 | abstract.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>`, and
`<stdlib.h>` (if available).
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 <python1.5/Python.h>"; this will break on
multi-platform builds since the platform independent headers under
$prefix include the platform specific headers from
$exec_prefix.


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
BeOpen PythonLabs
E-mail: python-docs@python.org
September 18, 2000
Release 1.6


cObjects.html | api.html | threads.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 8. Initialization, Finalization, and Threads


7.4.1 Plain Integer Objects

numericObjects.html | numericObjects.html | longObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.4.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 that 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.2.5 List Objects

tupleObjects.html | sequenceObjects.html | mapObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.2.5 List Objects


7.4.2 Long Integer Objects

intObjects.html | numericObjects.html | floatObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.4.2 Long Integer Objects


7.3 Mapping Objects

listObjects.html | concrete.html | dictObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 7.3 Mapping Objects


10.2 Mapping Object Structures

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


6.4 Mapping Protocol

sequence.html | abstract.html | concrete.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 6.4 Mapping Protocol


9. Memory Management

threads.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;
```
With the second function set, the need to call
PyErr_NoMemory() is obviated:
```text

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

if (buf == NULL)
return NULL;
/* ...Do some I/O operation involving buf... */
res = PyString_FromString(buf);
Py_Free(buf); /* allocated with Py_Malloc */
return res;
```
The same code using the macro 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 three examples above, the buffer is always
manipulated via functions/macros 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() and
_PyObject_NewVar(), or with
their corresponding macros
PyObject_NEW() and
PyObject_NEW_VAR().


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.


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.2 Module Objects

fileObjects.html | otherObjects.html | cObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.5.2 Module Objects
There are only a few functions special to module objects.


10. Defining New Object Types

memoryExamples.html | api.html | common-structs.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10. Defining New Object Types
Py_InitModule (!!!)
PyArg_ParseTupleAndKeywords, PyArg_ParseTuple, PyArg_Parse
Py_BuildValue
DL_IMPORT
Py*_Check
_Py_NoneStruct


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
The `-X` command-line option will be removed in Python 1.6. All
exceptions built into Python or provided in the standard library will
be classes derived from Exception.
String exceptions will still be supported in the interpreter to allow
existing code to run unmodified, but this will also change in a future
release.


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


7.1.2 The None Object

typeObjects.html | fundamental.html | sequenceObjects.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.3 Number Object Structures

mapping-structs.html | newTypes.html | sequence-structs.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10.3 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.4 Numeric Objects

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


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 OS Utilities

utilities.html | utilities.html | processControl.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 5.1 OS Utilities


7.5 Other Objects

node45.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


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 calling a 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 (i.e.,
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 (i.e., 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.


10.4 Sequence Object Structures

number-structs.html | newTypes.html | buffer-structs.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 10.4 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.2 Sequence Objects

noneObject.html | concrete.html | stringObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
# 7.2 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.


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:
Note:
(1): This is a base class for other standard exceptions. If the
`-X` interpreter option is used, these will be tuples
containing the string exceptions which would have otherwise been
subclasses.


7.2.1 String Objects

sequenceObjects.html | sequenceObjects.html | unicodeObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.2.1 String Objects


initialization.html | initialization.html | memory.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
PyThreadState structure. 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).
Reversely, 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.2.4 Tuple Objects

bufferObjects.html | sequenceObjects.html | listObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.2.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.2.2.2 Methods and Slot Functions

builtinCodecs.html | unicodeObjects.html | bufferObjects.html | Python/C API Reference Manual | contents.html | genindex.html
---
### 7.2.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 in case an exception occurrs.


7.2.2 Unicode Objects

stringObjects.html | sequenceObjects.html | builtinCodecs.html | Python/C API Reference Manual | contents.html | genindex.html
---
## 7.2.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, such as
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.


About this document ...

node45.html | dist.html | Distributing Python Modules | contents.html
---
# 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.
---
node45.html | dist.html | Distributing Python Modules | contents.html
---


9.5 Creating a ``built'' distribution: the bdist command family

sdist-cmd.html | ref.html | node42.html | Distributing Python Modules | contents.html
---
## 9.5 Creating a ``built'' distribution: the
`bdist` command family


9.1.4 build_clib

build-ext-cmd.html | build-cmds.html | install-cmd.html | Distributing Python Modules | contents.html
---
### 9.1.4 `build_clib`


9.1.1 build

build-cmds.html | build-cmds.html | build-py-cmd.html | Distributing Python Modules | contents.html
---
### 9.1.1 `build`


9.1 Building modules: the build command family

ref.html | ref.html | build-cmd.html | Distributing Python Modules | contents.html
---
## 9.1 Building modules: the `build` command family


9.1.3 build_ext

build-py-cmd.html | build-cmds.html | build-clib-cmd.html | Distributing Python Modules | contents.html
---
### 9.1.3 `build_ext`


9.1.2 build_py

build-cmd.html | build-cmds.html | build-ext-cmd.html | Distributing Python Modules | contents.html
---
### 9.1.2 `build_py`


6 Creating Built Distributions

manifest-options.html | dist.html | examples.html | Distributing Python Modules | contents.html
---
# 6 Creating Built Distributions
A ``built distribution'' is what you're probably used to thinking of
either as a ``binary package'' or an ``installer'' (depending on your
background). It's not necessarily binary, though, because it might
contain only Python source code and/or byte-code; and we don't call it a
package, because that word is already spoken for in Python. (And
``installer'' is a term specific to the Windows world. ** do Mac
people use it? **)
A built distribution is how you make life as easy as possible for
installers of your module distribution: for users of RPM-based Linux
systems, it's a binary RPM; for Windows users, it's an executable
installer; for Debian-based Linux users, it's a Debian package; and so
forth. Obviously, no one person will be able to create built
distributions for every platform under the sun, so the Distutils is
designed to enable module developers to concentrate on their
specialty--writing code and creating source distributions--while an
intermediary species of packager springs up to turn source
distributions into built distributions for as many platforms as there
are packagers.
Of course, the module developer could be his own packager; or the
packager could be a volunteer ``out there'' somewhere who has access to
a platform which the original developer does not; or it could be
software periodically grabbing new source distributions and turning them
into built distributions for as many platforms as the software has
access to. Regardless of the nature of the beast, a packager uses the
setup script and the `bdist` command family to generate built
distributions.
As a simple example, if I run the following command in the Distutils
source tree:
```text

python setup.py bdist
```
then the Distutils builds my module distribution (the Distutils itself
in this case), does a ``fake'' installation (also in the build
directory), and creates the default type of built distribution for my
platform. Currently, the default format for built distributions is a
``dumb'' archive--tarball on Unix, ZIP file on Windows. (These are
called ``dumb'' built distributions, because they must be unpacked in a
specific location to work.)
Thus, the above command on a Unix system creates
Distutils-0.9.1.plat.tar.gz; unpacking this tarball
from the root of the filesystemq installs the Distutils just as though
you had downloaded the source distribution and run `python setup.py
install`. (Assuming that the target system has their Python
installation laid out the same as you do--another reason these are
called ``dumb'' distributions.) Obviously, for pure Python
distributions, this isn't a huge win--but for non-pure distributions,
which include extensions that would need to be compiled, it can mean the
difference between someone being able to use your extensions or not.
** filenames are inaccurate here! **
The `bdist` command has a --format option,
similar to the `sdist` command, which you can use to select the
types of built distribution to generate: for example,
```text

python setup.py bdist --format=zip
```
would, when run on a Unix system, create
Distutils-0.8.plat.zip--again, this archive would be
unpacked from the root directory to install the Distutils.
The available formats for built distributions are:
Notes:
(1): default on Unix
(2): default on Windows ** to-do! **
You don't have to use the `bdist` command with the
--formats option; you can also use the command that
directly implements the format you're interested in. Some of these
`bdist` ``sub-commands'' actually generate several similar
formats; for instance, the `bdist_dumb` command generates all
the ``dumb'' archive formats (`tar`, `ztar`, `gztar`, and
`zip`), and `bdist_rpm` generates both binary and source
RPMs. The `bdist` sub-commands, and the formats generated by
each, are:


9.3 Cleaning up: the clean command

install-scripts-cmd.html | ref.html | sdist-cmd.html | Distributing Python Modules | contents.html
---
## 9.3 Cleaning up: the `clean` command


2 Concepts & Terminology

intro.html | dist.html | simple-example.html | Distributing Python Modules | contents.html
---
# 2 Concepts & Terminology
Using the Distutils is quite simple, both for module developers and for
users/administrators installing third-party modules. As a developer,
your responsibilites (apart from writing solid, well-documented and
well-tested code, of course!) are:
- write a setup script (setup.py by convention)
- (optional) write a setup configuration file
- create a source distribution
- (optional) create one or more built (binary) distributions
Each of these tasks is covered in this document.
Not all module developers have access to a multitude of platforms, so
it's not always feasible to expect them to create a multitude of built
distributions. It is hoped that a class of intermediaries, called
packagers, will arise to address this need. Packagers will take
source distributions released by module developers, build them on one or
more platforms, and release the resulting built distributions. Thus,
users on the most popular platforms will be able to install most popular
Python module distributions in the most natural way for their platform,
without having to run a single setup script or compile a line of code.


Contents

dist.html | dist.html | intro.html | Distributing Python Modules
---
## Contents


3.3 Describing extension modules

listing-modules.html | setup-script.html | node11.html | Distributing Python Modules | contents.html
---
## 3.3 Describing extension modules
Just as writing Python extension modules is a bit more complicated than
writing pure Python modules, describing them to the Distutils is a bit
more complicated. Unlike pure modules, it's not enough just to list
modules or packages and expect the Distutils to go out and find the
right files; you have to specify the extension name, source file(s), and
any compile/link requirements (include directories, libraries to link
with, etc.).
All of this is done through another keyword argument to
setup(), the extensions option. extensions
is just a list of Extension instances, each of which describes a
single extension module. Suppose your distribution includes a single
extension, called foo and implemented by foo.c. If no
additional instructions to the compiler/linker are needed, describing
this extension is quite simple:
```text

Extension("foo", ["foo.c"])
```
The Extension class can be imported from
distutils.core, along with setup(). Thus, the setup
script for a module distribution that contains only this one extension
and nothing else might be:
```text

from distutils.core import setup, Extension
setup(name = "foo", version = "1.0",
extensions = [Extension("foo", ["foo.c"])])
```
The Extension class (actually, the underlying extension-building
machinery implemented by the `built_ext` command) supports a
great deal of flexibility in describing Python extensions, which is
explained in the following sections.


Distributing Python Modules

../index.html | contents.html | Distributing Python Modules | contents.html
---
# Distributing Python Modules
Greg Ward
E-mail: gward@python.net
### Abstract:
This document describes the Python Distribution Utilities
(``Distutils'') from the module developer's point-of-view, describing
how to use the Distutils to make Python modules and extensions easily
available to a wider audience with very little overhead for
build/release/install mechanics.


2.3 Distutils-specific terminology

python-terms.html | concepts.html | setup-script.html | Distributing Python Modules | contents.html
---
## 2.3 Distutils-specific terminology
The following terms apply more specifically to the domain of
distributing Python modules using the Distutils:
module distribution: a collection of Python modules distributed
together as a single downloadable resource and meant to be installed
en masse. Examples of some well-known module distributions are
Numeric Python, PyXML, PIL (the Python Imaging Library), or
mxDateTime. (This would be called a package, except that term
is already taken in the Python context: a single module distribution
may contain zero, one, or many Python packages.)
pure module distribution: a module distribution that contains only
pure Python modules and packages. Sometimes referred to as a ``pure
distribution.''
non-pure module distribution: a module distribution that contains
at least one extension module. Sometimes referred to as a ``non-pure
distribution.''
distribution root: the top-level directory of your source tree (or
source distribution); the directory where setup.py exists and
is run from


7 Examples

built-dist.html | dist.html | pure-mod.html | Distributing Python Modules | contents.html
---
# 7 Examples


8.1 Extending existing commands

extending.html | extending.html | new-commands.html | Distributing Python Modules | contents.html
---
## 8.1 Extending existing commands


8 Extending the Distutils

node25.html | dist.html | extend-existing.html | Distributing Python Modules | contents.html
---
# 8 Extending the Distutils


Distributing Python Modules


9.2 Installing modules: the install command family

build-clib-cmd.html | ref.html | install-lib-cmd.html | Distributing Python Modules | contents.html
---
## 9.2 Installing modules: the `install` command family
The install command ensures that the build commands have been run and then
runs the subcommands `install_lib`,
`install_data` and
`install_scripts`.


9.2.2 install_data

install-lib-cmd.html | install-cmd.html | install-scripts-cmd.html | Distributing Python Modules | contents.html
---
### 9.2.2 `install_data`
This command installs all data files provided with the distribution.


9.2.1 install_lib

install-cmd.html | install-cmd.html | install-data-cmd.html | Distributing Python Modules | contents.html
---
### 9.2.1 `install_lib`


9.2.3 install_scripts

install-data-cmd.html | install-cmd.html | clean-cmd.html | Distributing Python Modules | contents.html
---
### 9.2.3 `install_scripts`
This command installs all (Python) scripts in the distribution.


1 Introduction

contents.html | dist.html | concepts.html | Distributing Python Modules | contents.html
---
# 1 Introduction
In the past, Python module developers have not had much infrastructure
support for distributing modules, nor have Python users had much support
for installing and maintaining third-party modules. With the
introduction of the Python Distribution Utilities (Distutils for short)
in Python 1.6, this situation should start to improve.
This document only covers using the Distutils to distribute your Python
modules. Using the Distutils does not tie you to Python 1.6, though:
the Distutils work just fine with Python 1.5.2, and it is reasonable
(and expected to become commonplace) to expect users of Python 1.5.2 to
download and install the Distutils separately before they can install
your modules. Python 1.6 (or later) users, of course, won't have to add
anything to their Python installation in order to use the Distutils to
install third-party modules.
This document concentrates on the role of developer/distributor: if
you're looking for information on installing Python modules, you
should refer to the Installing Python
Modules (../inst/inst.html) manual.


3.2 Listing individual modules

listing-packages.html | setup-script.html | describing-extensions.html | Distributing Python Modules | contents.html
---
## 3.2 Listing individual modules
For a small module distribution, you might prefer to list all modules
rather than listing packages--especially the case of a single module
that goes in the ``root package'' (i.e., no package at all). This
simplest case was shown in section 2.1 (simple-example.html#simple-example); here is a
slightly more involved example:
```text

py_modules = ['mod1', 'pkg.mod2']
```
This describes two modules, one of them in the ``root'' package, the
other in the pkg package. Again, the default package/directory
layout implies that these two modules can be found in mod1.py and
pkg/mod2.py, and that pkg/__init__.py exists as well.
And again, you can override the package/directory correspondence using
the package_dir option.


3.1 Listing whole packages

setup-script.html | setup-script.html | listing-modules.html | Distributing Python Modules | contents.html
---
## 3.1 Listing whole packages
The packages option tells the Distutils to process (build,
distribute, install, etc.) all pure Python modules found in each package
mentioned in the packages list. In order to do this, of
course, there has to be a correspondence between package names and
directories in the filesystem. The default correspondence is the most
obvious one, i.e. package distutils is found in the directory
distutils relative to the distribution root. Thus, when you say
`packages = ['foo']` in your setup script, you are promising that
the Distutils will find a file foo/__init__.py (which might
be spelled differently on your system, but you get the idea) relative to
the directory where your setup script lives. (If you break this
promise, the Distutils will issue a warning but process the broken
package anyways.)
If you use a different convention to lay out your source directory,
that's no problem: you just have to supply the package_dir
option to tell the Distutils about your convention. For example, say
you keep all Python source under lib, so that modules in the
``root package'' (i.e., not in any package at all) are right in
lib, modules in the foo package are in lib/foo,
and so forth. Then you would put
```text

package_dir = {'': 'lib'}
```
in your setup script. (The keys to this dictionary are package names,
and an empty package name stands for the root package. The values are
directory names relative to your distribution root.) In this case, when
you say `packages = ['foo']`, you are promising that the file
lib/foo/__init__.py exists.
Another possible convention is to put the foo package right in
lib, the foo.bar package in lib/bar, etc. This
would be written in the setup script as
```text

package_dir = {'foo': 'lib'}
```
A `package : dir` entry in the package_dir
dictionary implicitly applies to all packages below package, so
the foo.bar case is automatically handled here. In this
example, having `packages = ['foo', 'foo.bar']` tells the Distutils
to look for lib/__init__.py and
lib/bar/__init__.py. (Keep in mind that although
package_dir applies recursively, you must explicitly list all
packages in packages: the Distutils will not recursively
scan your source tree looking for any directory with an
__init__.py file.)


5.2 Manifest-related options

manifest.html | source-dist.html | built-dist.html | Distributing Python Modules | contents.html
---
## 5.2 Manifest-related options
The normal course of operations for the `sdist` command is as
follows:
- if the manifest file, MANIFEST doesn't exist, read
MANIFEST.in and create the manifest
- if either MANIFEST.in or the setup script (setup.py)
are more recent than MANIFEST, recreate MANIFEST by
reading MANIFEST.in
- use the list of files now in MANIFEST (either just
generated or read in) to create the source distribution archive(s)
There are a couple of options that modify this behaviour.
First, you might want to force the manifest to be regenerated--for
example, if you have added or removed files or directories that match an
existing pattern in the manifest template, you should regenerate the
manifest:
```text

python setup.py sdist --force-manifest
```
Or, you might just want to (re)generate the manifest, but not create a
source distribution:
```text

python setup.py sdist --manifest-only
```
(--manifest-only implies --force-manifest.)
If you don't want to use the default file set, you can supply the
--no-defaults option. If you use
--no-defaults and don't supply a manifest template (or
it's empty, or nothing matches the patterns in it), then your source
distribution will be empty.


5.1 The manifest and manifest template

source-dist.html | source-dist.html | manifest-options.html | Distributing Python Modules | contents.html
---
## 5.1 The manifest and manifest template
Without any additional information, the `sdist` command puts a
minimal set of files into the source distribution:
- all Python source files implied by the py_modules and
packages options
- all C source files mentioned in the ext_modules or
libraries options (** getting C library sources currently
broken - no get_source_files() method in build_clib.py! **)
- anything that looks like a test script: test/test*.py
(currently, the Distutils don't do anything with test scripts except
include them in source distributions, but in the future there will be
a standard for testing Python module distributions)
- README.txt (or README) and setup.py
Sometimes this is enough, but usually you will want to specify
additional files to distribute. The typical way to do this is to write
a manifest template, called MANIFEST.in by default. The
`sdist` command processes this template and generates a manifest
file, MANIFEST. (If you prefer, you can skip the manifest
template and generate the manifest yourself: it just lists one file per
line.)
The manifest template has one command per line, where each command
specifies a set of files to include or exclude from the source
distribution. For an example, again we turn to the Distutils' own
manifest template:
```text

include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build
```
The meanings should be fairly clear: include all files in the
distribution root matching `*.txt`, all files anywhere under the
examples directory matching `*.txt` or `*.py`, and
exclude all directories matching `examples/sample?/build`. There
are several other commands available in the manifest template
mini-language; see section 9.4 (sdist-cmd.html#sdist-cmd).
The order of commands in the manifest template very much matters:
initially, we have the list of default files as described above, and
each command in the template adds to or removes from that list of files.
When we have fully processed the manifest template, we have our complete
list of files. This list is written to the manifest for future
reference, and then used to build the source distribution archive(s).
Following the Distutils' own manifest template, let's trace how the
`sdist` command will build the list of files to include in the
Distutils source distribution:
1. include all Python source files in the distutils and
distutils/command subdirectories (because packages
corresponding to those two directories were mentioned in the
packages option in the setup script)
2. include test/test*.py (always included)
3. include README.txt and setup.py (always included)
4. include *.txt in the distribution root (this will find
README.txt a second time, but such redundancies are weeded out
later)
5. in the sub-tree under examples, include anything matching
*.txt
6. in the sub-tree under examples, include anything matching
*.py
7. remove all files in the sub-trees starting at directories matching
examples/sample?/build--this may exclude files included by the
previous two steps, so it's important that the `prune` command in
the manifest template comes after the two `recursive-include` commands
Just like in the setup script, file and directory names in the manifest
template should always be slash-separated; the Distutils will take care
of converting them to the standard representation on your platform.
That way, the manifest template is portable across operating systems.


7.4 Multiple extension modules

single-ext.html | examples.html | node25.html | Distributing Python Modules | contents.html
---
## 7.4 Multiple extension modules


8.2 Writing new commands

extend-existing.html | extending.html | ref.html | Distributing Python Modules | contents.html
---
## 8.2 Writing new commands


3.3.1 Extension names and packages

describing-extensions.html | describing-extensions.html | node12.html | Distributing Python Modules | contents.html
---
### 3.3.1 Extension names and packages
The first argument to the Extension constructor is always the
name of the extension, including any package names. For example,
```text

Extension("foo", ["src/foo1.c", "src/foo2.c"])
```
describes an extension that lives in the root package, while
```text

Extension("pkg.foo", ["src/foo1.c", "src/foo2.c"])
```
describes the same extension in the pkg package. The source
files and resulting object code are identical in both cases; the only
difference is where in the filesystem (and therefore where in Python's
namespace hierarchy) the resulting extension lives.
If you have a number of extensions all in the same package (or all under
the same base package), use the ext_package keyword argument
to setup(). For example,
```text

setup(...
ext_package = "pkg",
extensions = [Extension("foo", ["foo.c"]),
Extension("subpkg.bar", ["bar.c"])]
)
```
will compile foo.c to the extension pkg.foo, and
bar.c to pkg.subpkg.bar.


3.3.2 Extension source files

node11.html | describing-extensions.html | node13.html | Distributing Python Modules | contents.html
---
### 3.3.2 Extension source files
The second argument to the Extension constructor is a list of
source files. Since the Distutils currently only support C/C++
extensions, these are normally C/C++ source files. (Be sure to use
appropriate extensions to distinguish C++ source files: .cc and
.cpp seem to be recognized by both Unix and Windows compilers.)
However, you can also include SWIG interface (.i) files in the
list; the `build_ext` command knows how to deal with SWIG
extensions: it will run SWIG on the interface file and compile the
resulting C/C++ file into your extension.
** SWIG support is rough around the edges and largely untested;
especially SWIG support of C++ extensions! Explain in more detail
here when the interface firms up. **
On some platforms, you can include non-source files that are processed
by the compiler and included in your extension. Currently, this just
means Windows resource files for Visual C++. ** get more detail on
this feature from Thomas Heller! **


3.3.3 Preprocessor options

node12.html | describing-extensions.html | node14.html | Distributing Python Modules | contents.html
---
### 3.3.3 Preprocessor options
Three optional arguments to Extension will help if you need to
specify include directories to search or preprocessor macros to
define/undefine: `include_dirs`, `define_macros`, and
`undef_macros`.
For example, if your extension requires header files in the
include directory under your distribution root, use the
`include_dirs` option:
```text

Extension("foo", ["foo.c"], include_dirs=["include"])
```
You can specify absolute directories there; if you know that your
extension will only be built on Unix systems with X11R6 installed to
/usr, you can get away with
```text

Extension("foo", ["foo.c"], include_dirs=["/usr/include/X11"])
```
You should avoid this sort of non-portable usage if you plan to
distribute your code: it's probably better to write your code to include
(e.g.) `<X11/Xlib.h>`.
If you need to include header files from some other Python extension,
you can take advantage of the fact that the Distutils install extension
header files in a consistent way. For example, the Numerical Python
header files are installed (on a standard Unix installation) to
/usr/local/include/python1.5/Numerical. (The exact location will
differ according to your platform and Python installation.) Since the
Python include directory--/usr/local/include/python1.5 in this
case--is always included in the search path when building Python
extensions, the best approach is to include (e.g.)
`<Numerical/arrayobject.h>`. If you insist on putting the
Numerical include directory right into your header search path,
though, you can find that directory using the Distutils
sysconfig module:
```text

from distutils.sysconfig import get_python_inc
incdir = os.path.join(get_python_inc(plat_specific=1), "Numerical")
setup(...,
Extension(..., include_dirs=[incdir]))
```
Even though this is quite portable--it will work on any Python
installation, regardless of platform--it's probably easier to just
write your C code in the sensible way.
You can define and undefine pre-processor macros with the
`define_macros` and `undef_macros` options.
`define_macros` takes a list of `(name, value)` tuples, where
`name` is the name of the macro to define (a string) and
`value` is its value: either a string or `None`. (Defining a
macro `FOO` to `None` is the equivalent of a bare
`#define FOO` in your C source: with most compilers, this sets
`FOO` to the string `1`.) `undef_macros` is just
a list of macros to undefine.
For example:
```text

Extension(...,
define_macros=[('NDEBUG', '1')],
('HAVE_STRFTIME', None),
undef_macros=['HAVE_FOO', 'HAVE_BAR'])
```
is the equivalent of having this at the top of every C source file:
```text

#define NDEBUG 1
#define HAVE_STRFTIME
#undef HAVE_FOO
#undef HAVE_BAR
```


3.3.4 Library options

node13.html | describing-extensions.html | setup-config.html | Distributing Python Modules | contents.html
---
### 3.3.4 Library options
You can also specify the libraries to link against when building your
extension, and the directories to search for those libraries. The
`libraries` option is a list of libraries to link against,
`library_dirs` is a list of directories to search for libraries at
link-time, and `runtime_library_dirs` is a list of directories to
search for shared (dynamically loaded) libraries at run-time.
For example, if you need to link against libraries known to be in the
standard library search path on target systems
```text

Extension(...,
libraries=["gdbm", "readline"])
```
If you need to link with libraries in a non-standard location, you'll
have to include the location in `library_dirs`:
```text

Extension(...,
library_dirs=["/usr/X11R6/lib"],
libraries=["X11", "Xt"])
```
(Again, this sort of non-portable construct should be avoided if you
intend to distribute your code.)
** still undocumented: extra_objects, extra_compile_args,
extra_link_args, export_symbols--none of which are frequently
needed, some of which might be completely unnecessary! **


7.5 Putting it all together

multiple-ext.html | examples.html | extending.html | Distributing Python Modules | contents.html
---
## 7.5 Putting it all together


9.5.1 blib

bdist-cmds.html | bdist-cmds.html | node43.html | Distributing Python Modules | contents.html
---
### 9.5.1 `blib`


9.5.2 blib_dumb

node42.html | bdist-cmds.html | node44.html | Distributing Python Modules | contents.html
---
### 9.5.2 `blib_dumb`


9.5.3 blib_rpm

node43.html | bdist-cmds.html | node45.html | Distributing Python Modules | contents.html
---
### 9.5.3 `blib_rpm`


9.5.4 blib_wise

node44.html | bdist-cmds.html | about.html | Distributing Python Modules | contents.html
---
### 9.5.4 `blib_wise`


examples.html | examples.html | pure-pkg.html | Distributing Python Modules | contents.html
---
## 7.1 Pure Python distribution (by module)


pure-mod.html | examples.html | single-ext.html | Distributing Python Modules | contents.html
---
## 7.2 Pure Python distribution (by package)


2.2 General Python terminology

simple-example.html | concepts.html | distutils-term.html | Distributing Python Modules | contents.html
---
## 2.2 General Python terminology
If you're reading this document, you probably have a good idea of what
modules, extensions, and so forth are. Nevertheless, just to be sure
that everyone is operating from a common starting point, we offer the
following glossary of common Python terms:
module: the basic unit of code reusability in Python: a block of
code imported by some other code. Three types of modules concern us
here: pure Python modules, extension modules, and packages.
pure Python module: a module written in Python and contained in a
single .py file (and possibly associated .pyc and/or
.pyo files). Sometimes referred to as a ``pure module.''
extension module: a module written in the low-level language of
the Python implemention: C/C++ for CPython, Java for JPython.
Typically contained in a single dynamically loadable pre-compiled
file, e.g. a shared object (.so) file for CPython extensions on
Unix, a DLL (given the .pyd extension) for CPython extensions
on Windows, or a Java class file for JPython extensions. (Note that
currently, the Distutils only handles C/C++ extensions for CPython.)
package: a module that contains other modules; typically contained
in a directory in the filesystem and distinguished from other
directories by the presence of a file __init__.py.
root package: the root of the hierarchy of packages. (This isn't
really a package, since it doesn't have an __init__.py
file. But we have to call it something.) The vast majority of the
standard library is in the root package, as are many small, standalone
third-party modules that don't belong to a larger module collection.
Unlike regular packages, modules in the root package can be found in
many directories: in fact, every directory listed in `sys.path` can contribute modules to the root package.


9 Reference

new-commands.html | dist.html | build-cmds.html | Distributing Python Modules | contents.html
---
# 9 Reference


9.4 Creating a source distribution: the sdist command

clean-cmd.html | ref.html | bdist-cmds.html | Distributing Python Modules | contents.html
---
## 9.4 Creating a source distribution: the `sdist` command
** fragment moved down from above: needs context! **
The manifest template commands are:
The patterns here are Unix-style ``glob'' patterns: `*` matches any
sequence of regular filename characters, `?` matches any single
regular filename character, and `[ range ]` matches any of the
characters in range (e.g., `a-z`, `a-zA-Z`,
`a-f0-9_.`). The definition of ``regular filename character'' is
platform-specific: on Unix it is anything except slash; on Windows
anything except backslash or colon; on Mac OS anything except colon.
** Windows and Mac OS support not there yet **


4 Writing the Setup Configuration File

node14.html | dist.html | source-dist.html | Distributing Python Modules | contents.html
---
# 4 Writing the Setup Configuration File
Often, it's not possible to write down everything needed to build a
distribution a priori. You need to get some information from the
user, or from the user's system, in order to proceed. For example, you
might include an optional extension module that provides an interface to
a particular C library. If that library is installed on the user's
system, then you can build your optional extension--but you need to
know where to find the header and library file. If it's not installed,
you need to know this so you can omit your optional extension.
The preferred way to do this, of course, would be for you to tell the
Distutils which optional features (C libraries, system calls, external
utilities, etc.) you're looking for, and it would inspect the user's
system and try to find them. This functionality may appear in a future
version of the Distutils, but it isn't there now. So, for the time
being, we rely on the user building and installing your software to
provide the necessary information. The vehicle for doing so is the
setup configuration file, setup.cfg.
** need more here! **