cplusplus.html | intro.html | defining-new-types.html | Extending and Embedding the Python Interpreter | contents.html
Previous:
1.11 Writing Extensions in (cplusplus.html)
Up:
1. Extending Python with (intro.html)
Next:
2. Defining New Types (defining-new-types.html)
---
# 1.12 Providing a C API for an Extension Module
Many extension modules just provide new functions and types to be
used from Python, but sometimes the code in an extension module can
be useful for other extension modules. For example, an extension
module could implement a type ``collection'' which works like lists
without order. Just like the standard Python list type has a C API
which permits extension modules to create and manipulate lists, this
new collection type should have a set of C functions for direct
manipulation from other extension modules.
At first sight this seems easy: just write the functions (without
declaring them static, of course), provide an appropriate
header file, and document the C API. And in fact this would work if
all extension modules were always linked statically with the Python
interpreter. When modules are used as shared libraries, however, the
symbols defined in one module may not be visible to another module.
The details of visibility depend on the operating system; some systems
use one global namespace for the Python interpreter and all extension
modules (Windows, for example), whereas others require an explicit
list of imported symbols at module link time (AIX is one example), or
offer a choice of different strategies (most Unices). And even if
symbols are globally visible, the module whose functions one wishes to
call might not have been loaded yet!
Portability therefore requires not to make any assumptions about
symbol visibility. This means that all symbols in extension modules
should be declared static, except for the module's
initialization function, in order to avoid name clashes with other
extension modules (as discussed in section 1.4 (methodTable.html#methodTable)). And it
means that symbols that should be accessible from other
extension modules must be exported in a different way.
Python provides a special mechanism to pass C-level information
(pointers) from one extension module to another one: CObjects.
A CObject is a Python data type which stores a pointer (void
*). CObjects can only be created and accessed via their C API, but
they can be passed around like any other Python object. In particular,
they can be assigned to a name in an extension module's namespace.
Other extension modules can then import this module, retrieve the
value of this name, and then retrieve the pointer from the CObject.
There are many ways in which CObjects can be used to export the C API
of an extension module. Each name could get its own CObject, or all C
API pointers could be stored in an array whose address is published in
a CObject. And the various tasks of storing and retrieving the pointers
can be distributed in different ways between the module providing the
code and the client modules.
The following example demonstrates an approach that puts most of the
burden on the writer of the exporting module, which is appropriate
for commonly used library modules. It stores all C API pointers
(just one in the example!) in an array of void pointers which
becomes the value of a CObject. The header file corresponding to
the module provides a macro that takes care of importing the module
and retrieving its C API pointers; client modules only have to call
this macro before accessing the C API.
The exporting module is a modification of the spam module from
section 1.1 (simpleExample.html#simpleExample). The function spam.system()
does not call the C library function system() directly,
but a function PySpam_System(), which would of course do
something more complicated in reality (such as adding ``spam'' to
every command). This function PySpam_System() is also
exported to other extension modules.
The function PySpam_System() is a plain C function,
declared static like everything else:
```text

static int
PySpam_System(char *command)
{
return system(command);
}
```
The function spam_system() is modified in a trivial way:
```text

static PyObject *
spam_system(PyObject *self, PyObject *args)
{
char *command;
int sts;

if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
sts = PySpam_System(command);
return Py_BuildValue("i", sts);
}
```
In the beginning of the module, right after the line
```text

#include "Python.h"
```
two more lines must be added:
```text

#define SPAM_MODULE
#include "spammodule.h"
```
The `#define` is used to tell the header file that it is being
included in the exporting module, not a client module. Finally,
the module's initialization function must take care of initializing
the C API pointer array:
```text

PyMODINIT_FUNC
initspam(void)
{
PyObject *m;
static void *PySpam_API[PySpam_API_pointers];
PyObject *c_api_object;

m = Py_InitModule("spam", SpamMethods);

/* Initialize the C API pointer array */
PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;

/* Create a CObject containing the API pointer array's address */
c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);

if (c_api_object != NULL)
PyModule_AddObject(m, "_C_API", c_api_object);
}
```
Note that `PySpam_API` is declared static; otherwise
the pointer array would disappear when initspam() terminates!
The bulk of the work is in the header file spammodule.h,
which looks like this:
```text

#ifndef Py_SPAMMODULE_H
#define Py_SPAMMODULE_H
#ifdef __cplusplus
extern "C" {
#endif

/* Header file for spammodule */

/* C API functions */
#define PySpam_System_NUM 0
#define PySpam_System_RETURN int
#define PySpam_System_PROTO (char *command)

/* Total number of C API pointers */
#define PySpam_API_pointers 1

#ifdef SPAM_MODULE
/* This section is used when compiling spammodule.c */

static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;

#else
/* This section is used in modules that use spammodule's API */

static void **PySpam_API;

#define PySpam_System \
(*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])

/* Return -1 and set exception on error, 0 on success. */
static int
import_spam(void)
{
PyObject *module = PyImport_ImportModule("spam");

if (module != NULL) {
PyObject *c_api_object = PyObject_GetAttrString(module, "_C_API");
if (c_api_object == NULL)
return -1;
if (PyCObject_Check(c_api_object))
PySpam_API = (void **)PyCObject_AsVoidPtr(c_api_object);
Py_DECREF(c_api_object);
}
return 0;
}

#endif

#ifdef __cplusplus
}
#endif

#endif /* !defined(Py_SPAMMODULE_H) */
```
All that a client module must do in order to have access to the
function PySpam_System() is to call the function (or
rather macro) import_spam() in its initialization
function:
```text

PyMODINIT_FUNC
initclient(void)
{
PyObject *m;

Py_InitModule("client", ClientMethods);
if (import_spam() < 0)
return;
/* additional initialization can happen here */
}
```
The main disadvantage of this approach is that the file
spammodule.h is rather complicated. However, the
basic structure is the same for each function that is
exported, so it has to be learned only once.


4.1 A Cookbook Approach

building-on-windows.html | building-on-windows.html | dynamic-linking.html | Extending and Embedding the Python Interpreter | contents.html
Previous:
4. Building C and (building-on-windows.html)
Up:
4. Building C and (building-on-windows.html)
Next:
4.2 Differences Between Unix (dynamic-linking.html)
---
# 4.1 A Cookbook Approach
There are two approaches to building extension modules on Windows,
just as there are on Unix: use the distutils (module-distutils.html) package to
control the build process, or do things manually. The distutils
approach works well for most extensions; documentation on using
distutils (module-distutils.html) to build and package extension modules is
available in Distributing Python
Modules (../dist/dist.html). This section describes the manual approach to building
Python extensions written in C or C++.
To build extensions using these instructions, you need to have a copy
of the Python sources of the same version as your installed Python.
You will need Microsoft Visual C++ ``Developer Studio''; project
files are supplied for VC++ version 6, but you can use older
versions of VC++. The example files described here are distributed
with the Python sources in the PC\
example_nt\ directory.
1. Copy the example files
The example_nt directory is a subdirectory of the PC
directory, in order to keep all the PC-specific files under the
same directory in the source distribution. However, the
example_nt directory can't actually be used from this
location. You first need to copy or move it up one level, so that
example_nt is a sibling of the PC and Include
directories. Do all your work from within this new location.
2. Open the project
From VC++, use the File > Open Workspace
dialog (not File > Open!). Navigate to and
select the file example.dsw, in the copy of the
example_nt directory you made above. Click Open.
3. Build the example DLL
In order to check that everything is set up right, try building:
1. Select a configuration. This step is optional. Choose
Build > Select Active Configuration and
select either ``example - Win32 Release'' or ``example - Win32
Debug.'' If you skip this step, VC++ will use the Debug
configuration by default.
2. Build the DLL. Choose Build > Build
example_d.dll in Debug mode, or Build >
Build example.dll in Release mode. This creates all
intermediate and result files in a subdirectory called either
Debug or Release, depending on which
configuration you selected in the preceding step.
4. Testing the debug-mode DLL
Once the Debug build has succeeded, bring up a DOS box, and change
to the example_nt\Debug directory. You
should now be able to repeat the following session (`C>` is
the DOS prompt, `> > >` is the Python prompt; note that
build information and various debug output from Python may not
match this screen dump exactly):
```text

C>..\..\PCbuild\python_d
Adding parser accelerators ...
Done.
Python 2.2 (#28, Dec 19 2001, 23:26:37) [MSC 32 bit (Intel)] on win32
Type "copyright", "credits" or "license" for more information.
>>> import example
[4897 refs]
>>> example.foo()
Hello, world
[4903 refs]
>>>
```
Congratulations! You've successfully built your first Python
extension module.
5. Creating your own project
Choose a name and create a directory for it. Copy your C sources
into it. Note that the module source file name does not
necessarily have to match the module name, but the name of the
initialization function should match the module name -- you can
only import a module spam if its initialization function
is called initspam(), and it should call
Py_InitModule() with the string `"spam"` as its
first argument (use the minimal example.c in this directory
as a guide). By convention, it lives in a file called
spam.c or spammodule.c. The output file should be
called spam.dll or spam.pyd (the latter is supported
to avoid confusion with a system library spam.dll to which
your module could be a Python interface) in Release mode, or
spam_d.dll or spam_d.pyd in Debug mode.
Now your options are:
1. Copy example.dsw and example.dsp, rename
them to spam.*, and edit them by hand, or
2. Create a brand new project; instructions are below.
In either case, copy example_nt\example.def
to spam\spam.def, and edit the new
spam.def so its second line contains the string
``initspam`'. If you created a new project yourself, add the
file spam.def to the project now. (This is an annoying
little file with only two lines. An alternative approach is to
forget about the .def file, and add the option
/export:initspam somewhere to the Link settings, by
manually editing the setting in Project Options dialog).
6. Creating a brand new project
Use the File > New > Projects dialog to
create a new Project Workspace. Select ``Win32 Dynamic-Link
Library,'' enter the name ("spam"), and make sure the
Location is set to the spam directory you have created
(which should be a direct subdirectory of the Python build tree, a
sibling of Include and PC). Select Win32 as the
platform (in my version, this is the only choice). Make sure the
Create new workspace radio button is selected. Click OK.
Now open the Project > Settings dialog. You
only need to change a few settings. Make sure All Configurations
is selected from the Settings for: dropdown list. Select the
C/C++ tab. Choose the Preprocessor category in the popup menu
at the top. Type the following text in the entry box labeled
Addditional include directories:
```text

..\Include,..\PC
```
Then, choose the Input category in the Link tab, and enter
```text

..\PCbuild
```
in the text box labelled ``Additional library path.''
Now you need to add some mode-specific settings:
Select ``Win32 Release'' in the ``Settings for'' dropdown list.
Click the Link tab, choose the Input Category, and append
`pythonXY.lib` to the list in the ``Object/library modules''
box.
Select ``Win32 Debug'' in the ``Settings for'' dropdown list, and
append `pythonXY_d.lib` to the list in the ``Object/library
modules'' box. Then click the C/C++ tab, select ``Code
Generation'' from the Category dropdown list, and select ``Debug
Multithreaded DLL'' from the ``Use run-time library'' dropdown
list.
Select ``Win32 Release'' again from the ``Settings for'' dropdown
list. Select ``Multithreaded DLL'' from the ``Use run-time
library:'' dropdown list.
You should now create the file spam.def as instructed in the
previous section. Then chose the Insert > Files
into Project dialog. Set the pattern to `*.*` and select
both spam.c and spam.def and click OK. (Inserting
them one by one is fine too.)
If your module creates a new type, you may have trouble with this line:
```text

PyObject_HEAD_INIT(&PyType_Type)
```
Change it to:
```text

PyObject_HEAD_INIT(NULL)
```
and add the following to the module initialization function:
```text

MyObject_Type.ob_type = &PyType_Type;
```
Refer to section 3 of the
Python FAQ (http://www.python.org/doc/FAQ.html) for details
on why you must do this.


4.3 Using DLLs in Practice

dynamic-linking.html | building-on-windows.html | embedding.html | Extending and Embedding the Python Interpreter | contents.html
Previous:
4.2 Differences Between Unix (dynamic-linking.html)
Up:
4. Building C and (building-on-windows.html)
Next:
5. Embedding Python in (embedding.html)
---
# 4.3 Using DLLs in Practice
Windows Python is built in Microsoft Visual C++; using other
compilers may or may not work (though Borland seems to). The rest of
this section is MSVC++ specific.
When creating DLLs in Windows, you must pass pythonXY.lib to
the linker. To build two DLLs, spam and ni (which uses C functions
found in spam), you could use these commands:
```text

cl /LD /I/python/include spam.c ../libs/pythonXY.lib
cl /LD /I/python/include ni.c spam.lib ../libs/pythonXY.lib
```
The first command created three files: spam.obj,
spam.dll and spam.lib. Spam.dll does not contain
any Python functions (such as PyArg_ParseTuple()), but it
does know how to find the Python code thanks to pythonXY.lib.
The second command created ni.dll (and .obj and
.lib), which knows how to find the necessary functions from
spam, and also from the Python executable.
Not every identifier is exported to the lookup table. If you want any
other modules (including Python) to be able to see your identifiers,
you have to say "_declspec(dllexport)", as in "void
_declspec(dllexport) initspam(void)" or "PyObject
_declspec(dllexport) *NiGetSpamData(void)".


Python 2.3 Documentation - July 29, 2003

Python Documentation | modindex.html
---
# Python Documentation
Release 2.3
July 29, 2003
---
See About the Python Documentation (about.html)
for information on suggesting changes.


About this document ...

tweak-flags.html | inst.html | Installing Python Modules
Previous:
6 Building Extensions: Tips (tweak-flags.html)
Up:
Installing Python Modules (inst.html)
---
# About this document ...
Installing 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, either in the content or the presentation, please
report the bug at the Python Bug
Tracker (http://sourceforge.net/bugs/?group_id=5470) at SourceForge (http://sourceforge.net/).
Questions regarding how to use the information in this
document should be sent to the Python news group, comp.lang.python (news:comp.lang.python), or the Python mailing list (http://www.python.org/mailman/listinfo/python-list) (which is gated to the newsgroup and
carries the same content).
For any of these channels, please be sure not to send HTML email.
Thanks.
---
tweak-flags.html | inst.html | Installing Python Modules
Previous:
6 Building Extensions: Tips (tweak-flags.html)
Up:
Installing Python Modules (inst.html)
---


3 Alternate Installation

standard-install.html | inst.html | search-path.html | Installing Python Modules
Previous:
2 Standard Build and (standard-install.html)
Up:
Installing Python Modules (inst.html)
Next:
4 Custom Installation (search-path.html)
---
- 3.1 Alternate installation: Unix (the home scheme) (alt-install-windows.html#SECTION000310000000000000000)
  3.2 Alternate installation: Unix (the prefix scheme) (alt-install-windows.html#SECTION000320000000000000000)
  3.3 Alternate installation: Windows (alt-install-windows.html#SECTION000330000000000000000)
  3.4 Alternate installation: Mac OS 9 (alt-install-windows.html#SECTION000340000000000000000)
---
# 3 Alternate Installation
Often, it is necessary or desirable to install modules to a location
other than the standard location for third-party Python modules. For
example, on a Unix system you might not have permission to write to the
standard third-party module directory. Or you might wish to try out a
module before making it a standard part of your local Python
installation. This is especially true when upgrading a distribution
already present: you want to make sure your existing base of scripts
still works with the new version before actually upgrading.
The Distutils `install` command is designed to make installing
module distributions to an alternate location simple and painless. The
basic idea is that you supply a base directory for the installation, and
the `install` command picks a set of directories (called an
installation scheme) under this base directory in which to
install files. The details differ across platforms, so read whichever
of the following sections applies to you.
## 3.1 Alternate installation: Unix (the home scheme)
Under Unix, there are two ways to perform an alternate installation.
The ``prefix scheme'' is similar to how alternate installation works
under Windows and Mac OS, but is not necessarily the most useful way to
maintain a personal Python library. Hence, we document the more
convenient and commonly useful ``home scheme'' first.
The idea behind the ``home scheme'' is that you build and maintain a
personal stash of Python modules, probably under your home directory.
Installing a new module distribution is as simple as
```text

python setup.py install --home=<dir>
```
where you can supply any directory you like for the --home
option. Lazy typists can just type a tilde (`~`); the
`install` command will expand this to your home directory:
```text

python setup.py install --home=~
```
The --home option defines the installation base
directory. Files are installed to the following directories under the
installation base as follows:
## 3.2 Alternate installation: Unix (the prefix scheme)
The ``prefix scheme'' is useful when you wish to use one Python
installation to perform the build/install (i.e., to run the setup
script), but install modules into the third-party module directory of a
different Python installation (or something that looks like a different
Python installation). If this sounds a trifle unusual, it is--that's
why the ``home scheme'' comes first. However, there are at least two
known cases where the prefix scheme will be useful.
First, consider that many Linux distributions put Python in /usr,
rather than the more traditional /usr/local. This is entirely
appropriate, since in those cases Python is part of ``the system''
rather than a local add-on. However, if you are installing Python
modules from source, you probably want them to go in
/usr/local/lib/python2.X rather than
/usr/lib/python2.X. This can be done with
```text

/usr/bin/python setup.py install --prefix=/usr/local
```
Another possibility is a network filesystem where the name used to write
to a remote directory is different from the name used to read it: for
example, the Python interpreter accessed as /usr/local/bin/python
might search for modules in /usr/local/lib/python2.X,
but those modules would have to be installed to, say,
/mnt/@server/export/lib/python2.X. This
could be done with
```text

/usr/local/bin/python setup.py install --prefix=/mnt/@server/export
```
In either case, the --prefix option defines the
installation base, and the --exec-prefix option defines
the platform-specific installation base, which is used for
platform-specific files. (Currently, this just means non-pure module
distributions, but could be expanded to C libraries, binary executables,
etc.) If --exec-prefix is not supplied, it defaults to
--prefix. Files are installed as follows:
There is no requirement that --prefix or
--exec-prefix actually point to an alternate Python
installation; if the directories listed above do not already exist, they
are created at installation time.
Incidentally, the real reason the prefix scheme is important is simply
that a standard Unix installation uses the prefix scheme, but with
--prefix and --exec-prefix supplied by
Python itself as `sys.prefix` and `sys.exec_prefix`. Thus,
you might think you'll never use the prefix scheme, but every time you
run `python setup.py install` without any other options, you're
using it.
Note that installing extensions to an alternate Python installation has
no effect on how those extensions are built: in particular, the Python
header files (Python.h and friends) installed with the Python
interpreter used to run the setup script will be used in compiling
extensions. It is your responsibility to ensure that the interpreter
used to run extensions installed in this way is compatible with the
interpreter used to build them. The best way to do this is to ensure
that the two interpreters are the same version of Python (possibly
different builds, or possibly copies of the same build). (Of course, if
your --prefix and --exec-prefix don't even
point to an alternate Python installation, this is immaterial.)
## 3.3 Alternate installation: Windows
Since Windows has no conception of a user's home directory, and since
the standard Python installation under Windows is simpler than that
under Unix, there's no point in having separate --prefix
and --home options. Just use the --prefix
option to specify a base directory, e.g.
```text

python setup.py install --prefix="\Temp\Python"
```
to install modules to the
\Temp\Python directory on the
current drive.
The installation base is defined by the --prefix option;
the --exec-prefix option is not supported under Windows.
Files are installed as follows:
## 3.4 Alternate installation: Mac OS 9
Like Windows, Mac OS has no notion of home directories (or even of
users), and a fairly simple standard Python installation. Thus, only a
--prefix option is needed. It defines the installation
base, and files are installed under it as follows:
See section 2.1 (standard-install.html#platform-variations) for information on supplying
command-line arguments to the setup script with MacPython.


5 Distutils Configuration Files

search-path.html | inst.html | tweak-flags.html | Installing Python Modules
Previous:
4 Custom Installation (search-path.html)
Up:
Installing Python Modules (inst.html)
Next:
6 Building Extensions: Tips (tweak-flags.html)
---
- 5.1 Location and names of config files (config-syntax.html#SECTION000510000000000000000)
  5.2 Syntax of config files (config-syntax.html#SECTION000520000000000000000)
---
# 5 Distutils Configuration Files
As mentioned above, you can use Distutils configuration files to record
personal or site preferences for any Distutils options. That is, any
option to any command can be stored in one of two or three (depending on
your platform) configuration files, which will be consulted before the
command-line is parsed. This means that configuration files will
override default values, and the command-line will in turn override
configuration files. Furthermore, if multiple configuration files
apply, values from ``earlier'' files are overridden by ``later'' files.
## 5.1 Location and names of config files
The names and locations of the configuration files vary slightly across
platforms. On Unix, the three configuration files (in the order they
are processed) are:
On Windows, the configuration files are:
And on Mac OS, they are:
Notes:
(1): Strictly speaking, the system-wide configuration file lives
in the directory where the Distutils are installed; under Python 1.6
and later on Unix, this is as shown. For Python 1.5.2, the Distutils
will normally be installed to
prefix/lib/site-packages/python1.5/distutils,
so the system configuration file should be put there under Python
1.5.2.
(2): On Unix, if the HOME environment variable is not
defined, the user's home directory will be determined with the
getpwuid() function from the standard
pwd (../lib/module-pwd.html) module.
(3): I.e., in the current directory (usually the location of the
setup script).
(4): (See also note (1).) Under Python 1.6 and later, Python's
default ``installation prefix'' is C:\Python, so
the system configuration file is normally
C:\Python\Lib\distutils\distutils.cfg.
Under Python 1.5.2, the default prefix was
C:\Program Files\Python, and the
Distutils were not part of the standard library--so the system
configuration file would be
C:\Program Files\Python\distutils\distutils.cfg
in a standard Python 1.5.2 installation under Windows.
(5): On Windows, if the HOME environment variable is not
defined, no personal configuration file will be found or used. (In
other words, the Distutils make no attempt to guess your home
directory on Windows.)
(6): (See also notes (1) and (4).) The default installation
prefix is just Python:, so under Python 1.6 and later this is
normallyPython:Lib:distutils:distutils.cfg.
## 5.2 Syntax of config files
The Distutils configuration files all have the same syntax. The config
files are grouped into sections. There is one section for each Distutils
command, plus a `global` section for global options that affect
every command. Each section consists of one option per line, specified
as `option=value`.
For example, the following is a complete config file that just forces
all commands to run quietly by default:
```text

[global]
verbose=0
```
If this is installed as the system config file, it will affect all
processing of any Python module distribution by any user on the current
system. If it is installed as your personal config file (on systems
that support them), it will affect only module distributions processed
by you. And if it is used as the setup.cfg for a particular
module distribution, it affects only that distribution.
You could override the default ``build base'' directory and make the
`build*` commands always forcibly rebuild all files with the
following:
```text

[build]
build-base=blib
force=1
```
which corresponds to the command-line arguments
```text

python setup.py build --build-base=blib --force
```
except that including the `build` command on the command-line
means that command will be run. Including a particular command in
config files has no such implication; it only means that if the command
is run, the options in the config file will apply. (Or if other
commands that derive values from it are run, they will use the values in
the config file.)
You can find out the complete list of options for any command using the
--help option, e.g.:
```text

python setup.py build --help
```
and you can find out the complete list of global options by using
--help without a command:
```text

python setup.py --help
```
See also the ``Reference'' section of the ``Distributing Python
Modules'' manual.


Installing Python Modules

../index.html | trivial-install.html | Installing Python Modules
Up:
Python Documentation Index (../index.html)
Next:
1 Introduction (trivial-install.html)
---
# Installing Python Modules
Greg Ward
Email: distutils-sig@python.org
### Abstract:
This document describes the Python Distribution Utilities
(``Distutils'') from the end-user's point-of-view, describing how to
extend the capabilities of a standard Python installation by building
and installing third-party Python modules and extensions.


Installing Python Modules


4 Custom Installation

alt-install-windows.html | inst.html | config-syntax.html | Installing Python Modules
Previous:
3 Alternate Installation (alt-install-windows.html)
Up:
Installing Python Modules (inst.html)
Next:
5 Distutils Configuration Files (config-syntax.html)
---
- 4.1 Modifying Python's Search Path (search-path.html#SECTION000410000000000000000)
---
# 4 Custom Installation
Sometimes, the alternate installation schemes described in
section 3 (alt-install-windows.html#alt-install) just don't do what you want. You might
want to tweak just one or two directories while keeping everything under
the same base directory, or you might want to completely redefine the
installation scheme. In either case, you're creating a custom
installation scheme.
You probably noticed the column of ``override options'' in the tables
describing the alternate installation schemes above. Those options are
how you define a custom installation scheme. These override options can
be relative, absolute, or explicitly defined in terms of one of the
installation base directories. (There are two installation base
directories, and they are normally the same--they only differ when you
use the Unix ``prefix scheme'' and supply different
--prefix and --exec-prefix options.)
For example, say you're installing a module distribution to your home
directory under Unix--but you want scripts to go in
~/scripts rather than ~/bin.
As you might expect, you can override this directory with the
--install-scripts option; in this case, it makes most
sense to supply a relative path, which will be interpreted relative to
the installation base directory (your home directory, in this case):
```text

python setup.py install --home=~ --install-scripts=scripts
```
Another Unix example: suppose your Python installation was built and
installed with a prefix of /usr/local/python, so under a standard
installation scripts will wind up in /usr/local/python/bin. If
you want them in /usr/local/bin instead, you would supply this
absolute directory for the --install-scripts option:
```text

python setup.py install --install-scripts=/usr/local/bin
```
(This performs an installation using the ``prefix scheme,'' where the
prefix is whatever your Python interpreter was installed with--
/usr/local/python in this case.)
If you maintain Python on Windows, you might want third-party modules to
live in a subdirectory of prefix, rather than right in
prefix itself. This is almost as easy as customizing the
script installation directory--you just have to remember that there are
two types of modules to worry about, pure modules and non-pure modules
(i.e., modules from a non-pure distribution). For example:
```text

python setup.py install --install-purelib=Site --install-platlib=Site
```
The specified installation directories are relative to
prefix. Of course, you also have to ensure that these
directories are in Python's module search path, such as by putting a
.pth file in prefix. See section 4.1 (search-path.html#search-path)
to find out how to modify Python's search path.
If you want to define an entire installation scheme, you just have to
supply all of the installation directory options. The recommended way
to do this is to supply relative paths; for example, if you want to
maintain all Python module-related files under python in your
home directory, and you want a separate directory for each platform that
you use your home directory from, you might define the following
installation scheme:
```text

python setup.py install --home=~ \
--install-purelib=python/lib \
--install-platlib=python/lib.$PLAT \
--install-scripts=python/scripts
--install-data=python/data
```
or, equivalently,
```text

python setup.py install --home=~/python \
--install-purelib=lib \
--install-platlib='lib.$PLAT' \
--install-scripts=scripts
--install-data=data
```
`$PLAT` is not (necessarily) an environment variable--it will be
expanded by the Distutils as it parses your command line options, just
as it does when parsing your configuration file(s).
Obviously, specifying the entire installation scheme every time you
install a new module distribution would be very tedious. Thus, you can
put these options into your Distutils config file (see
section 5 (config-syntax.html#config-files)):
```text

[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data
```
or, equivalently,
```text

[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data
```
Note that these two are not equivalent if you supply a different
installation base directory when you run the setup script. For example,
```text

python setup.py --install-base=/tmp
```
would install pure modules to /tmp/python/lib in the first
case, and to /tmp/lib in the second case. (For the second
case, you probably want to supply an installation base of
/tmp/python.)
You probably noticed the use of `$HOME` and `$PLAT` in the
sample configuration file input. These are Distutils configuration
variables, which bear a strong resemblance to environment variables.
In fact, you can use environment variables in config files on
platforms that have such a notion but the Distutils additionally
define a few extra variables that may not be in your environment, such
as `$PLAT`. (And of course, on systems that don't have
environment variables, such as Mac OS 9, the configuration
variables supplied by the Distutils are the only ones you can use.)
See section 5 (config-syntax.html#config-files) for details.
## 4.1 Modifying Python's Search Path
When the Python interpreter executes an import statement, it
searches for both Python code and extension modules along a search
path. A default value for the path is configured into the Python
binary when the interpreter is built. You can determine the path by
importing the sys module and printing the value of
`sys.path`.
```text

$ python
Python 2.2 (#11, Oct 3 2002, 13:31:27)
[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
Type ``help'', ``copyright'', ``credits'' or ``license'' for more information.
>>> import sys
>>> sys.path
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
'/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
'/usr/local/lib/python2.3/site-packages']
>>>
```
The null string in `sys.path` represents the current working
directory.
The expected convention for locally installed packages is to put them
in the .../site-packages/ directory, but you may want to
install Python modules into some arbitrary directory. For example,
your site may have a convention of keeping all software related to the
web server under /www. Add-on Python modules might then belong
in /www/python, and in order to import them, this directory
must be added to `sys.path`. There are several different ways to
add the directory.
The most convenient way is to add a path configuration file to a
directory that's already on Python's path, usually to the
.../site-packages/ directory. Path configuration files have an
extension of .pth, and each line must contain a single path
that will be appended to `sys.path`. (Because the new paths are
appended to `sys.path`, modules in the added directories will not
override standard modules. This means you can't use this mechanism
for installing fixed versions of standard modules.)
Paths can be absolute or relative, in which case they're relative to
the directory containing the .pth file. Any directories added
to the search path will be scanned in turn for .pth files. See
site module"
>the
documentation for the site module (http://www.python.org/dev/doc/devel/lib/module-site.html) for more information.
A slightly less convenient way is to edit the site.py file in
Python's standard library, and modify `sys.path`. site.py
is automatically imported when the Python interpreter is executed,
unless the -S switch is supplied to suppress this
behaviour. So you could simply edit site.py and add two lines to it:
```text

import sys
sys.path.append('/www/python/')
```
However, if you reinstall the same major version of Python (perhaps
when upgrading from 2.2 to 2.2.2, for example) site.py will be
overwritten by the stock version. You'd have to remember that it was
modified and save a copy before doing the installation.
There are two environment variables that can modify `sys.path`.
PYTHONHOME sets an alternate value for the prefix of the
Python installation. For example, if PYTHONHOME is set to
"/www/python", the search path will be set to `['',
'/www/python/lib/python2.2/', '/www/python/lib/python2.3/plat-linux2',
...]`.
The PYTHONPATH variable can be set to a list of paths that
will be added to the beginning of `sys.path`. For example, if
PYTHONPATH is set to "/www/python:/opt/py", the search
path will begin with `['/www/python', '/opt/py']`. (Note that
directories must exist in order to be added to `sys.path`; the
site module removes paths that don't exist.)
Finally, `sys.path` is just a regular Python list, so any Python
application can modify it by adding or removing entries.


2 Standard Build and Install

trivial-install.html | inst.html | alt-install-windows.html | Installing Python Modules
Previous:
1 Introduction (trivial-install.html)
Up:
Installing Python Modules (inst.html)
Next:
3 Alternate Installation (alt-install-windows.html)
---
- 2.1 Platform variations (standard-install.html#SECTION000210000000000000000)
  2.2 Splitting the job up (standard-install.html#SECTION000220000000000000000)
  2.3 How building works (standard-install.html#SECTION000230000000000000000)
  2.4 How installation works (standard-install.html#SECTION000240000000000000000)
---
# 2 Standard Build and Install
As described in section 1.2 (trivial-install.html#new-standard), building and installing
a module distribution using the Distutils is usually one simple command:
```text

python setup.py install
```
On Unix, you'd run this command from a shell prompt; on Windows, you
have to open a command prompt window (``DOS box'') and do it there; on
Mac OS, things are a tad more complicated (see below).
## 2.1 Platform variations
You should always run the setup command from the distribution root
directory, i.e. the top-level subdirectory that the module source
distribution unpacks into. For example, if you've just downloaded a
module source distribution foo-1.0.tar.gz onto a
Unix system, the normal thing to do is:
```text

gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
cd foo-1.0
python setup.py install
```
On Windows, you'd probably download foo-1.0.zip. If you
downloaded the archive file to C:\Temp, then it
would unpack into C:\Temp\foo-1.0;
you can use either a archive manipulator with a grapical user interface
(such as WinZip) or a command-line tool (such as unzip or
pkunzip) to unpack the archive. Then, open a command prompt
window (``DOS box''), and run:
```text

cd c:\Temp\foo-1.0
python setup.py install
```
On Mac OS 9, you double-click the setup.py script. It will bring
up a dialog where you can select the `install` command. Then
selecting the `run` button will install your distribution.
The dialog is built dynamically, so all commands and options for this
specific distribution are listed.
## 2.2 Splitting the job up
Running `setup.py install` builds and installs all modules in one
run. If you prefer to work incrementally--especially useful if you
want to customize the build process, or if things are going wrong--you
can use the setup script to do one thing at a time. This is
particularly helpful when the build and install will be done by
different users--for example, you might want to build a module distribution
and hand it off to a system administrator for installation (or do it
yourself, with super-user privileges).
For example, you can build everything in one step, and then install
everything in a second step, by invoking the setup script twice:
```text

python setup.py build
python setup.py install
```
If you do this, you will notice that running the `install`
command first runs the `build` command, which--in this
case--quickly notices that it has nothing to do, since everything in
the build directory is up-to-date.
You may not need this ability to break things down often if all you do
is install modules downloaded off the 'net, but it's very handy for more
advanced tasks. If you get into distributing your own Python modules
and extensions, you'll run lots of individual Distutils commands on
their own.
## 2.3 How building works
As implied above, the `build` command is responsible for putting
the files to install into a build directory. By default, this is
build under the distribution root; if you're excessively
concerned with speed, or want to keep the source tree pristine, you can
change the build directory with the --build-base option.
For example:
```text

python setup.py build --build-base=/tmp/pybuild/foo-1.0
```
(Or you could do this permanently with a directive in your system or
personal Distutils configuration file; see
section 5 (config-syntax.html#config-files).) Normally, this isn't necessary.
The default layout for the build tree is as follows:
```text

--- build/ --- lib/
or
--- build/ --- lib.<plat>/
temp.<plat>/
```
where `<plat>` expands to a brief description of the current
OS/hardware platform and Python version. The first form, with just a
lib directory, is used for ``pure module distributions''--that
is, module distributions that include only pure Python modules. If a
module distribution contains any extensions (modules written in C/C++),
then the second form, with two `<plat>` directories, is used. In
that case, the temp.plat directory holds temporary
files generated by the compile/link process that don't actually get
installed. In either case, the lib (or
lib.plat) directory contains all Python modules (pure
Python and extensions) that will be installed.
In the future, more directories will be added to handle Python scripts,
documentation, binary executables, and whatever else is needed to handle
the job of installing Python modules and applications.
## 2.4 How installation works
After the `build` command runs (whether you run it explicitly,
or the `install` command does it for you), the work of the
`install` command is relatively simple: all it has to do is copy
everything under build/lib (or build/lib.plat)
to your chosen installation directory.
If you don't choose an installation directory--i.e., if you just run
`setup.py install`--then the `install` command installs to
the standard location for third-party Python modules. This location
varies by platform and by how you built/installed Python itself. On
Unix and Mac OS, it also depends on whether the module distribution
being installed is pure Python or contains extensions (``non-pure''):
Notes:
(1): Most Linux distributions include Python as a standard part of
the system, so prefix and exec-prefix are usually
both /usr on Linux. If you build Python yourself on Linux (or
any Unix-like system), the default prefix and
exec-prefix are /usr/local.
(2): The default installation directory on Windows was
C:\Program Files\Python under
Python 1.6a1, 1.5.2, and earlier.
prefix and exec-prefix stand for the directories
that Python is installed to, and where it finds its libraries at
run-time. They are always the same under Windows and Mac OS, and very
often the same under Unix. You can find out what your Python
installation uses for prefix and exec-prefix by
running Python in interactive mode and typing a few simple commands.
Under Unix, just type `python` at the shell prompt. Under
Windows, choose Start > Programs > Python
2.1 > Python (command line). Under Mac OS 9, start PythonInterpreter.
Once the interpreter is started, you type Python code at the
prompt. For example, on my Linux system, I type the three Python
statements shown below, and get the output as shown, to find out my
prefix and exec-prefix:
```text

Python 1.5.2 (#1, Apr 18 1999, 16:03:16) [GCC pgcc-2.91.60 19981201 (egcs-1.1.1 on linux2
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> import sys
>>> sys.prefix
'/usr'
>>> sys.exec_prefix
'/usr'
```
If you don't want to install modules to the standard location, or if you
don't have permission to write there, then you need to read about
alternate installations in section 3 (alt-install-windows.html#alt-install). If you want to
customize your installation directories more heavily, see
section 4 (search-path.html#custom-install) on custom installations.


1 Introduction

inst.html | inst.html | standard-install.html | Installing Python Modules
Previous:
Installing Python Modules (inst.html)
Up:
Installing Python Modules (inst.html)
Next:
2 Standard Build and (standard-install.html)
---
- 1.1 Best case: trivial installation (trivial-install.html#SECTION000110000000000000000)
  1.2 The new standard: Distutils (trivial-install.html#SECTION000120000000000000000)
---
# 1 Introduction
Although Python's extensive standard library covers many programming
needs, there often comes a time when you need to add some new
functionality to your Python installation in the form of third-party
modules. This might be necessary to support your own programming, or to
support an application that you want to use and that happens to be
written in Python.
In the past, there has been little support for adding third-party
modules to an existing Python installation. With the introduction of
the Python Distribution Utilities (Distutils for short) in Python 2.0,
this changed.
This document is aimed primarily at the people who need to install
third-party Python modules: end-users and system administrators who just
need to get some Python application running, and existing Python
programmers who want to add some new goodies to their toolbox. You
don't need to know Python to read this document; there will be some
brief forays into using Python's interactive mode to explore your
installation, but that's it. If you're looking for information on how
to distribute your own Python modules so that others may use them, see
the Distributing Python Modules (../dist/dist.html) manual.
## 1.1 Best case: trivial installation
In the best case, someone will have prepared a special version of the
module distribution you want to install that is targeted specifically at
your platform and is installed just like any other software on your
platform. For example, the module developer might make an executable
installer available for Windows users, an RPM package for users of
RPM-based Linux systems (Red Hat, SuSE, Mandrake, and many others), a
Debian package for users of Debian-based Linux systems, and so forth.
In that case, you would download the installer appropriate to your
platform and do the obvious thing with it: run it if it's an executable
installer, `rpm -install` it if it's an RPM, etc. You don't need
to run Python or a setup script, you don't need to compile
anything--you might not even need to read any instructions (although
it's always a good idea to do so anyways).
Of course, things will not always be that easy. You might be interested
in a module distribution that doesn't have an easy-to-use installer for
your platform. In that case, you'll have to start with the source
distribution released by the module's author/maintainer. Installing
from a source distribution is not too hard, as long as the modules are
packaged in the standard way. The bulk of this document is about
building and installing modules from standard source distributions.
## 1.2 The new standard: Distutils
If you download a module source distribution, you can tell pretty
quickly if it was packaged and distributed in the standard way, i.e.
using the Distutils. First, the distribution's name and version number
will be featured prominently in the name of the downloaded archive, e.g.
foo-1.0.tar.gz or widget-0.9.7.zip. Next, the archive
will unpack into a similarly-named directory: foo-1.0 or
widget-0.9.7. Additionally, the distribution will contain a
setup script setup.py, and a file named README.txt or possibly
just README, which should explain that building and installing the
module distribution is a simple matter of running
```text

python setup.py install
```
If all these things are true, then you already know how to build and
install the modules you've just downloaded: Run the command above.
Unless you need to install things in a non-standard way or customize the
build process, you don't really need this manual. Or rather, the above
command is everything you need to get out of this manual.


6 Building Extensions: Tips and Tricks

config-syntax.html | inst.html | about.html | Installing Python Modules
Previous:
5 Distutils Configuration Files (config-syntax.html)
Up:
Installing Python Modules (inst.html)
Next:
About this document ... (about.html)
---
- 6.1 Tweaking compiler/linker flags (tweak-flags.html#SECTION000610000000000000000)
  6.2 Using non-Microsoft compilers on Windows (tweak-flags.html#SECTION000620000000000000000)
  - 6.2.1 Borland C++ (tweak-flags.html#SECTION000621000000000000000)
  6.2.2 GNU C / Cygwin / MinGW (tweak-flags.html#SECTION000622000000000000000)
---
# 6 Building Extensions: Tips and Tricks
Whenever possible, the Distutils try to use the configuration
information made available by the Python interpreter used to run the
setup.py script. For example, the same compiler and linker
flags used to compile Python will also be used for compiling
extensions. Usually this will work well, but in complicated
situations this might be inappropriate. This section discusses how to
override the usual Distutils behaviour.
## 6.1 Tweaking compiler/linker flags
Compiling a Python extension written in C or C++will sometimes
require specifying custom flags for the compiler and linker in order
to use a particular library or produce a special kind of object code.
This is especially true if the extension hasn't been tested on your
platform, or if you're trying to cross-compile Python.
In the most general case, the extension author might have foreseen
that compiling the extensions would be complicated, and provided a
Setup file for you to edit. This will likely only be done if
the module distribution contains many separate extension modules, or
if they often require elaborate sets of compiler flags in order to work.
A Setup file, if present, is parsed in order to get a list of
extensions to build. Each line in a Setup describes a single
module. Lines have the following structure:
```text

module
... [
sourcefile
...] [
cpparg
...] [
library
...]
```
Let's examine each of the fields in turn.
- module is the name of the extension module to be built,
and should be a valid Python identifier. You can't just change
this in order to rename a module (edits to the source code would
also be needed), so this should be left alone.
- sourcefile is anything that's likely to be a source code
file, at least judging by the filename. Filenames ending in
.c are assumed to be written in C, filenames ending in
.C, .cc, and .c++ are assumed to be
C++, and filenames ending in .m or .mm are
assumed to be in Objective C.
- cpparg is an argument for the C preprocessor,
and is anything starting with -I, -D,
-U or -C.
- library is anything ending in .a or beginning with
-l or -L.
If a particular platform requires a special library on your platform,
you can add it by editing the Setup file and running
`python setup.py build`. For example, if the module defined by the line
```text

foo foomodule.c
```
must be linked with the math library libm.a on your platform,
simply add -lm to the line:
```text

foo foomodule.c -lm
```
Arbitrary switches intended for the compiler or the linker can be
supplied with the -Xcompiler arg and
-Xlinker arg options:
```text

foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
```
The next option after -Xcompiler and
-Xlinker will be appended to the proper command line, so
in the above example the compiler will be passed the -o32
option, and the linker will be passed -shared. If a
compiler option requires an argument, you'll have to supply multiple
-Xcompiler options; for example, to pass `-x c++` the
Setup file would have to contain
`-Xcompiler -x -Xcompiler c++`.
Compiler flags can also be supplied through setting the
CFLAGS environment variable. If set, the contents of
CFLAGS will be added to the compiler flags specified in the
Setup file.
## 6.2 Using non-Microsoft compilers on Windows
### 6.2.1 Borland C++
This subsection describes the necessary steps to use Distutils with the
Borland C++ compiler version 5.5.
First you have to know that Borland's object file format (OMF) is
different from the format used by the Python version you can download
from the Python or ActiveState Web site. (Python is built with
Microsoft Visual C++, which uses COFF as the object file format.)
For this reason you have to convert Python's library
python20.lib into the Borland format. You can do this as
follows:
```text

coff2omf python20.lib python20_bcpp.lib
```
The coff2omf program comes with the Borland compiler. The file
python20.lib is in the Libs directory of your Python
installation. If your extension uses other libraries (zlib,...) you
have to convert them too.
The converted files have to reside in the same directories as the
normal libraries.
How does Distutils manage to use these libraries with their changed
names? If the extension needs a library (eg. foo) Distutils
checks first if it finds a library with suffix _bcpp
(eg. foo_bcpp.lib) and then uses this library. In the case it
doesn't find such a special library it uses the default name
(foo.lib.)1 (#foot509)
To let Distutils compile your extension with Borland C++ you now have
to type:
```text

python setup.py build --compiler=bcpp
```
If you want to use the Borland C++ compiler as the default, you
could specify this in your personal or system-wide configuration file
for Distutils (see section 5 (config-syntax.html#config-files).)
See Also:
### 6.2.2 GNU C / Cygwin / MinGW
This section describes the necessary steps to use Distutils with the
GNU C/C++ compilers in their Cygwin and MinGW
distributions.2 (#foot603)For a Python interpreter that was built with Cygwin, everything should
work without any of these following steps.
These compilers require some special libraries.
This task is more complex than for Borland's C++, because there is no
program to convert the library.
First you have to create a list of symbols which the Python DLL exports.
(You can find a good program for this task at
http://starship.python.net/crew/kernr/mingw32/Notes.html, see at
PExports 0.42h there.)
```text

pexports python20.dll >python20.def
```
Then you can create from these information an import library for gcc.
```text

dlltool --dllname python20.dll --def python20.def --output-lib libpython20.a
```
The resulting library has to be placed in the same directory as
python20.lib. (Should be the libs directory under your
Python installation directory.)
If your extension uses other libraries (zlib,...) you might
have to convert them too.
The converted files have to reside in the same directories as the normal
libraries do.
To let Distutils compile your extension with Cygwin you now have to type
```text

python setup.py build --compiler=cygwin
```
and for Cygwin in no-cygwin mode3 (#foot604) or for MinGW type:
```text

python setup.py build --compiler=mingw32
```
If you want to use any of these options/compilers as default, you should
consider to write it in your personal or system-wide configuration file
for Distutils (see section 5 (config-syntax.html#config-files).)
See Also:


About this document ...

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


11.5.7 AbstractBasicAuthHandler Objects

http-password-mgr.html | module-urllib2.html | http-basic-auth-handler.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
11.5.6 HTTPPasswordMgr Objects (http-password-mgr.html)
Up:
11.5 urllib2 (module-urllib2.html)
Next:
11.5.8 HTTPBasicAuthHandler Objects (http-basic-auth-handler.html)
---
## 11.5.7 AbstractBasicAuthHandler Objects


proxy-basic-auth-handler.html | module-urllib2.html | http-digest-auth-handler.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
11.5.9 ProxyBasicAuthHandler Objects (proxy-basic-auth-handler.html)
Up:
11.5 urllib2 (module-urllib2.html)
Next:
11.5.11 HTTPDigestAuthHandler Objects (http-digest-auth-handler.html)
---
## 11.5.10 AbstractDigestAuthHandler Objects


12.11.2 AddressList Objects

message-objects.html | module-rfc822.html | module-base64.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
12.11.1 Message Objects (message-objects.html)
Up:
12.11 rfc822 (module-rfc822.html)
Next:
12.12 base64 (module-base64.html)
---
## 12.11.2 AddressList Objects
An AddressList instance has the following methods:
Finally, AddressList instances have one public instance variable:


20.1.1 Configuration Objects

module-al.html | module-al.html | al-port-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
20.1 al (module-al.html)
Up:
20.1 al (module-al.html)
Next:
20.1.2 Port Objects (al-port-objects.html)
---
## 20.1.1 Configuration Objects
Configuration objects returned by newconfig() have the
following methods:


20.1.2 Port Objects

al-config-objects.html | module-al.html | module-al-constants.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
20.1.1 Configuration Objects (al-config-objects.html)
Up:
20.1 al (module-al.html)
Next:
20.2 AL (module-al-constants.html)
---
## 20.1.2 Port Objects
Port objects, as returned by openport(), have the following
methods:


6. Generic Operating System Services

shlex-parsing-rules.html | lib.html | module-os.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
5.19.3 Parsing Rules (shlex-parsing-rules.html)
Up:
Python Library Reference (lib.html)
Next:
6.1 os (module-os.html)
---
# 6. Generic Operating System Services
The modules described in this chapter provide interfaces to operating
system features that are available on (almost) all operating systems,
such as files and a clock. The interfaces are generally modeled
after the Unix or C interfaces, but they are available on most
other systems as well. Here's an overview:


11.24.2 asynchat Example

node485.html | module-asynchat.html | netdata.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
11.24.1 asynchat - Auxiliary (node485.html)
Up:
11.24 asynchat (module-asynchat.html)
Next:
12. Internet Data Handling (netdata.html)
---
## 11.24.2 asynchat Example
The following partial example shows how HTTP requests can be read with
async_chat. A web server might create an http_request_handler object for
each incoming client connection. Notice that initially the
channel terminator is set to match the blank line at the end of the HTTP
headers, and a flag indicates that the headers are being read.
Once the headers have been read, if the request is of type POST
(indicating that further data are present in the input stream) then the
`Content-Length:` header is used to set a numeric terminator to
read the right amount of data from the channel.
The handle_request() method is called once all relevant input
has been marshalled, after setting the channel terminator to `None`
to ensure that any extraneous data sent by the web client are ignored.
```text

class http_request_handler(asynchat.async_chat):

def __init__(self, conn, addr, sessions, log):
asynchat.async_chat.__init__(self, conn=conn)
self.addr = addr
self.sessions = sessions
self.ibuffer = []
self.obuffer = ""
self.set_terminator("\r\n\r\n")
self.reading_headers = True
self.handling = False
self.cgi_data = None
self.log = log

def collect_incoming_data(self, data):
"""Buffer the data"""
self.ibuffer.append(data)

def found_terminator(self):
if self.reading_headers:
self.reading_headers = False
self.parse_headers("".join(self.ibuffer))
self.ibuffer = []
if self.op.upper() == "POST":
clen = self.headers.getheader("content-length")
self.set_terminator(int(clen))
else:
self.handling = True
self.set_terminator(None)
self.handle_request()
elif not self.handling:
self.set_terminator(None) # browsers sometimes over-send
self.cgi_data = parse(self.headers, "".join(self.ibuffer))
self.handling = True
self.ibuffer = []
self.handle_request()
```


module-asyncore.html | module-asyncore.html | module-asynchat.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
11.23 asyncore (module-asyncore.html)
Up:
11.23 asyncore (module-asyncore.html)
Next:
11.24 asynchat (module-asynchat.html)
---
## 11.23.1 asyncore Example basic HTTP client
As a basic example, below is a very basic HTTP client that uses the
dispatcher class to implement its socket handling:


3.5.1 atexit Example

module-atexit.html | module-atexit.html | module-types.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
3.5 atexit (module-atexit.html)
Up:
3.5 atexit (module-atexit.html)
Next:
3.6 types (module-types.html)
---
## 3.5.1 atexit Example
The following simple example demonstrates how a module can initialize
a counter from a file when it is imported and save the counter's
updated value automatically when the program terminates without
relying on the application making an explicit call into this module at
termination.
```text

try:
_count = int(open("/tmp/counter").read())
except IOError:
_count = 0

def incrcounter(n):
global _count
_count = _count + n

def savecounter():
open("/tmp/counter", "w").write("%d" % _count)

import atexit
atexit.register(savecounter)
```
Positional and keyword arguments may also be passed to
register() to be passed along to the registered function
when it is called:


13.12.6 The AttributesNS Interface

attributes-objects.html | module-xml.sax.xmlreader.html | module-xmllib.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
13.12.5 The Attributes Interface (attributes-objects.html)
Up:
13.12 xml.sax.xmlreader (module-xml.sax.xmlreader.html)
Next:
13.13 xmllib (module-xmllib.html)
---
## 13.12.6 The AttributesNS Interface
This interface is a subtype of the Attributes
interface (attributes-objects.html) (see
section 13.12.5 (attributes-objects.html#attributes-objects)). All methods supported by that
interface are also available on AttributesNS objects.
The following methods are also available:


13.12.5 The Attributes Interface

input-source-objects.html | module-xml.sax.xmlreader.html | attributes-ns-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
13.12.4 InputSource Objects (input-source-objects.html)
Up:
13.12 xml.sax.xmlreader (module-xml.sax.xmlreader.html)
Next:
13.12.6 The AttributesNS Interface (attributes-ns-objects.html)
---
## 13.12.5 The Attributes Interface
Attributes objects implement a portion of the mapping
protocol, including the methods copy(), get(),
has_key(), items(), keys(), and
values(). The following methods are also provided:


14.4.1 AU_read Objects

module-sunau.html | module-sunau.html | au-write-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
14.4 sunau (module-sunau.html)
Up:
14.4 sunau (module-sunau.html)
Next:
14.4.2 AU_write Objects (au-write-objects.html)
---
## 14.4.1 AU_read Objects
AU_read objects, as returned by open() above, have the
following methods:
The following two methods define a term ``position'' which is compatible
between them, and is otherwise implementation dependent.
The following two functions are defined for compatibility with the
aifc (module-aifc.html), and don't do anything interesting.


14.4.2 AU_write Objects

au-read-objects.html | module-sunau.html | module-wave.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
14.4.1 AU_read Objects (au-read-objects.html)
Up:
14.4 sunau (module-sunau.html)
Next:
14.5 wave (module-wave.html)
---
## 14.4.2 AU_write Objects
AU_write objects, as returned by open() above, have the
following methods:


21.1.1 Audio Device Objects

module-sunaudiodev.html | module-sunaudiodev.html | module-sunaudiodev-constants.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
21.1 sunaudiodev (module-sunaudiodev.html)
Up:
21.1 sunaudiodev (module-sunaudiodev.html)
Next:
21.2 SUNAUDIODEV (module-sunaudiodev-constants.html)
---
## 21.1.1 Audio Device Objects
The audio device objects are returned by open() define the
following methods (except `control` objects which only provide
getinfo(), setinfo(), fileno(), and
drain()):
The audio device supports asynchronous notification of various events,
through the SIGPOLL signal. Here's an example of how you might enable
this in Python:
```text

def handle_sigpoll(signum, frame):
print 'I got a SIGPOLL update'

import fcntl, signal, STROPTS

signal.signal(signal.SIGPOLL, handle_sigpoll)
fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)
```


11.5.3 BaseHandler Objects

opener-director-objects.html | module-urllib2.html | http-redirect-handler.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
11.5.2 OpenerDirector Objects (opener-director-objects.html)
Up:
11.5 urllib2 (module-urllib2.html)
Next:
11.5.4 HTTPRedirectHandler Objects (http-redirect-handler.html)
---
## 11.5.3 BaseHandler Objects
BaseHandler objects provide a couple of methods that are
directly useful, and others that are meant to be used by derived
classes. These are intended for direct use:
The following members and methods should only be used by classes
derived from BaseHandler:


11.20.4 Binary Objects

datetime-objects.html | module-xmlrpclib.html | fault-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
11.20.3 DateTime Objects (datetime-objects.html)
Up:
11.20 xmlrpclib (module-xmlrpclib.html)
Next:
11.20.5 Fault Objects (fault-objects.html)
---
## 11.20.4 Binary Objects
This class may initialized from string data (which may include NULs).
The primary acess to the content of a Binary object is
provided by an attribute:
Binary objects have the following methods, supported mainly
for internal use by the marshalling/unmarshalling code:
It also supports certain of Python's built-in operators through a
_cmp__() method.


12.14.1 Notes

module-binhex.html | module-binhex.html | module-quopri.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
12.14 binhex (module-binhex.html)
Up:
12.14 binhex (module-binhex.html)
Next:
12.15 quopri (module-quopri.html)
---
## 12.14.1 Notes
There is an alternative, more powerful interface to the coder and
decoder, see the source for details.
If you code or decode textfiles on non-Macintosh platforms they will
still use the Macintosh newline convention (carriage-return as end of
line).


5.9.1 Examples

module-bisect.html | module-bisect.html | module-heapq.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
5.9 bisect (module-bisect.html)
Up:
5.9 bisect (module-bisect.html)
Next:
5.10 heapq (module-heapq.html)
---
## 5.9.1 Examples
The bisect() function is generally useful for categorizing
numeric data. This example uses bisect() to look up a
letter grade for an exam total (say) based on a set of ordered numeric
breakpoints: 85 and up is an `A', 75..84 is a `B', etc.
```text

>>> grades = "FEDCBA"
>>> breakpoints = [30, 44, 66, 75, 85]
>>> from bisect import bisect
>>> def grade(total):
... return grades[bisect(breakpoints, total)]
...
>>> grade(66)
'C'
>>> map(grade, [33, 99, 77, 44, 12, 88])
['E', 'A', 'B', 'D', 'F', 'A']
```
The bisect module can be used with the Queue module to implement a priority
queue (example courtesy of Fredrik Lundh):


typesnumeric.html | typesnumeric.html | typeiter.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
2.2.4 Numeric Types (typesnumeric.html)
Up:
2.2.4 Numeric Types (typesnumeric.html)
Next:
2.2.5 Iterator Types (typeiter.html)
---
### 2.2.4.1 Bit-string Operations on Integer Types
Plain and long integer types support additional operations that make
sense only for bit-strings. Negative numbers are treated as their 2's
complement value (for long integers, this assumes a sufficiently large
number of bits that no overflow occurs during the operation).
The priorities of the binary bit-wise operations are all lower than
the numeric operations and higher than the comparisons; the unary
operation "~" has the same priority as the other unary numeric
operations ("+" and "-").
This table lists the bit-string operations sorted in ascending
priority (operations in the same box have the same priority):
Notes:
(1): Negative shift counts are illegal and cause a
ValueError to be raised.
(2): A left shift by n bits is equivalent to
multiplication by `pow(2, n )` without overflow check.
(3): A right shift by n bits is equivalent to
division by `pow(2, n )` without overflow check.


2.2.9.5 Code Objects

typesmethods.html | typesother.html | bltin-type-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
2.2.9.4 Methods (typesmethods.html)
Up:
2.2.9 Other Built-in Types (typesother.html)
Next:
2.2.9.6 Type Objects (bltin-type-objects.html)
---
### 2.2.9.5 Code Objects
Code objects are used by the implementation to represent
``pseudo-compiled'' executable Python code such as a function body.
They differ from function objects because they don't contain a
reference to their global execution environment. Code objects are
returned by the built-in compile() function and can be
extracted from function objects through their func_code
attribute.
A code object can be executed or evaluated by passing it (instead of a
source string) to the exec statement or the built-in
eval() function.
See the Python Reference Manual (../ref/ref.html) for more
information.


2.2.9.8 The Ellipsis Object

bltin-null-object.html | typesother.html | node29.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
2.2.9.7 The Null Object (bltin-null-object.html)
Up:
2.2.9 Other Built-in Types (typesother.html)
Next:
2.2.9.9 Boolean Values (node29.html)
---
### 2.2.9.8 The Ellipsis Object
This object is used by extended slice notation (see the
Python Reference Manual (../ref/ref.html)). It supports no
special operations. There is exactly one ellipsis object, named
Ellipsis (a built-in name).
It is written as `Ellipsis`.


2.2.8 File Objects

typesmapping.html | types.html | typesother.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
2.2.7 Mapping Types (typesmapping.html)
Up:
2.2 Built-in Types (types.html)
Next:
2.2.9 Other Built-in Types (typesother.html)
---
## 2.2.8 File Objects
File objects are implemented using C's `stdio`
package and can be created with the built-in constructor
file() described in section
2.1 (built-in-funcs.html#built-in-funcs), ``Built-in Functions.''2.10 (#foot3223)File objects are also returned
by some other built-in functions and methods, such as
os.popen() and os.fdopen() and the
makefile() method of socket objects.
When a file operation fails for an I/O-related reason, the exception
IOError is raised. This includes situations where the
operation is not defined for some reason, like seek() on a tty
device or writing a file opened for reading.
Files have the following methods:
Files support the iterator protocol. Each iteration returns the same
result as `file .readline()`, and iteration ends when the
readline() method returns an empty string.
File objects also offer a number of other interesting attributes.
These are not required for file-like objects, but should be
implemented if they make sense for the particular object.


2.2.9.7 The Null Object

bltin-type-objects.html | typesother.html | bltin-ellipsis-object.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
2.2.9.6 Type Objects (bltin-type-objects.html)
Up:
2.2.9 Other Built-in Types (typesother.html)
Next:
2.2.9.8 The Ellipsis Object (bltin-ellipsis-object.html)
---
### 2.2.9.7 The Null Object
This object is returned by functions that don't explicitly return a
value. It supports no special operations. There is exactly one null
object, named `None` (a built-in name).
It is written as `None`.


2.2.9.6 Type Objects

bltin-code-objects.html | typesother.html | bltin-null-object.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
2.2.9.5 Code Objects (bltin-code-objects.html)
Up:
2.2.9 Other Built-in Types (typesother.html)
Next:
2.2.9.7 The Null Object (bltin-null-object.html)
---
### 2.2.9.6 Type Objects
Type objects represent the various object types. An object's type is
accessed by the built-in function type(). There are no special
operations on types. The standard module types defines names
for all standard built-in types.
Types are written like this: `<type 'int'>`.


11.20.2 Boolean Objects

serverproxy-objects.html | module-xmlrpclib.html | datetime-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
11.20.1 ServerProxy Objects (serverproxy-objects.html)
Up:
11.20 xmlrpclib (module-xmlrpclib.html)
Next:
11.20.3 DateTime Objects (datetime-objects.html)
---
## 11.20.2 Boolean Objects
This class may be initialized from any Python value; the instance
returned depends only on its truth value. It supports various Python
operators through __cmp__(), __repr__(),
__int__(), and __nonzero__() methods, all
implemented in the obvious ways.
It also has the following method, supported mainly for internal use by
the unmarshalling code:


2.2.2 Boolean Operations

truth.html | types.html | comparisons.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
2.2.1 Truth Value Testing (truth.html)
Up:
2.2 Built-in Types (types.html)
Next:
2.2.3 Comparisons (comparisons.html)
---
## 2.2.2 Boolean Operations
These are the Boolean operations, ordered by ascending priority:
Notes:
(1): These only evaluate their second argument if needed for their outcome.
(2): "not" has a lower priority than non-Boolean operators, so
`not a == b` is interpreted as `not ( a == b )`, and `a == not b` is a syntax error.


11.1.1 Browser Controller Objects

module-webbrowser.html | module-webbrowser.html | module-cgi.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
11.1 webbrowser (module-webbrowser.html)
Up:
11.1 webbrowser (module-webbrowser.html)
Next:
11.2 cgi (module-cgi.html)
---
## 11.1.1 Browser Controller Objects
Browser controllers provide two methods which parallel two of the
module-level convenience functions:


7.13.1 Hash, BTree and Record Objects

module-bsddb.html | module-bsddb.html | module-dumbdbm.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
7.13 bsddb (module-bsddb.html)
Up:
7.13 bsddb (module-bsddb.html)
Next:
7.14 dumbdbm (module-dumbdbm.html)
---
## 7.13.1 Hash, BTree and Record Objects
Once instantiated, hash, btree and record objects support the following
methods:
Example:


2.1 Built-in Functions

builtin.html | builtin.html | types.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
2. Built-In Objects (builtin.html)
Up:
2. Built-In Objects (builtin.html)
Next:
2.2 Built-in Types (types.html)
---
# 2.1 Built-in Functions
The Python interpreter has a number of functions built into it that
are always available. They are listed here in alphabetical order.


2. Built-In Objects

intro.html | lib.html | built-in-funcs.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
1. Introduction (intro.html)
Up:
Python Library Reference (lib.html)
Next:
2.1 Built-in Functions (built-in-funcs.html)
---
# 2. Built-In Objects
Names for built-in exceptions and functions and a number of constants are
found in a separate
symbol table. This table is searched last when the interpreter looks
up the meaning of a name, so local and global
user-defined names can override built-in names. Built-in types are
described together here for easy reference.2.1 (#foot91)
The tables in this chapter document the priorities of operators by
listing them in order of ascending priority (within a table) and
grouping operators that have the same priority in the same box.
Binary operators of the same priority group from left to right.
(Unary operators group from right to left, but there you have no real
choice.) See chapter 5 of the Python
Reference Manual (../ref/ref.html) for the complete picture on operator priorities.
---
#### Footnotes
... reference.2.1 (builtin.html#tex2html1): Most descriptions sorely lack explanations of the exceptions
that may be raised -- this will be fixed in a future version of
this manual.


18.10.1 Python Byte Code Instructions

module-dis.html | module-dis.html | module-distutils.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
18.10 dis (module-dis.html)
Up:
18.10 dis (module-dis.html)
Next:
18.11 distutils (module-distutils.html)
---
## 18.10.1 Python Byte Code Instructions
The Python compiler currently generates the following byte code
instructions.
Unary Operations take the top of the stack, apply the operation, and
push the result back on the stack.
Binary operations remove the top of the stack (TOS) and the second top-most
stack item (TOS1) from the stack. They perform the operation, and put the
result back on the stack.
In-place operations are like binary operations, in that they remove TOS and
TOS1, and push the result back on the stack, but the operation is done
in-place when TOS1 supports it, and the resulting TOS may be (but does not
have to be) the original TOS1.
The slice opcodes take up to three parameters.
Slice assignment needs even an additional parameter. As any statement,
they put nothing on the stack.
Miscellaneous opcodes.
All of the following opcodes expect arguments. An argument is two
bytes, with the more significant byte last.


11.5.17 CacheFTPHandler Objects

ftp-handler-objects.html | module-urllib2.html | gopher-handler.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
11.5.16 FTPHandler Objects (ftp-handler-objects.html)
Up:
11.5 urllib2 (module-urllib2.html)
Next:
11.5.18 GopherHandler Objects (gopher-handler.html)
---
## 11.5.17 CacheFTPHandler Objects
CacheFTPHandler objects are FTPHandler objects with
the following additional methods:


20.3.2 Parser Objects

player-objects.html | module-cd.html | module-fl.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
20.3.1 Player Objects (player-objects.html)
Up:
20.3 cd (module-cd.html)
Next:
20.4 fl (module-fl.html)
---
## 20.3.2 Parser Objects
Parser objects (returned by createparser()) have the
following methods:


11.2.1 Introduction

module-cgi.html | module-cgi.html | node403.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
11.2 cgi (module-cgi.html)
Up:
11.2 cgi (module-cgi.html)
Next:
11.2.2 Using the cgi (node403.html)
---
## 11.2.1 Introduction
A CGI script is invoked by an HTTP server, usually to process user
input submitted through an HTML `<FORM>` or `<ISINDEX>` element.
Most often, CGI scripts live in the server's special cgi-bin
directory. The HTTP server places all sorts of information about the
request (such as the client's hostname, the requested URL, the query
string, and lots of other goodies) in the script's shell environment,
executes the script, and sends the script's output back to the client.
The script's input is connected to the client too, and sometimes the
form data is read this way; at other times the form data is passed via
the ``query string'' part of the URL. This module is intended
to take care of the different cases and provide a simpler interface to
the Python script. It also provides a number of utilities that help
in debugging scripts, and the latest addition is support for file
uploads from a form (if your browser supports it -- Grail 0.3 and
Netscape 2.0 do).
The output of a CGI script should consist of two sections, separated
by a blank line. The first section contains a number of headers,
telling the client what kind of data is following. Python code to
generate a minimal header section looks like this:
```text

print "Content-Type: text/html" # HTML is following
print # blank line, end of headers
```
The second section is usually HTML, which allows the client software
to display nicely formatted text with header, in-line images, etc.
Here's Python code that prints a simple piece of HTML:
```text

print "<TITLE>CGI script output</TITLE>"
print "<H1>This is my first CGI script</H1>"
print "Hello, world!"
```


11.2.6 Caring about security

node406.html | module-cgi.html | node408.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
11.2.5 Functions (node406.html)
Up:
11.2 cgi (module-cgi.html)
Next:
11.2.7 Installing your CGI (node408.html)
---
## 11.2.6 Caring about security
There's one important rule: if you invoke an external program (via the
os.system() or os.popen() functions. or others
with similar functionality), make very sure you don't pass arbitrary
strings received from the client to the shell. This is a well-known
security hole whereby clever hackers anywhere on the Web can exploit a
gullible CGI script to invoke arbitrary shell commands. Even parts of
the URL or field names cannot be trusted, since the request doesn't
have to come from your form!
To be on the safe side, if you must pass a string gotten from a form
to a shell command, you should make sure the string contains only
alphanumeric characters, dashes, underscores, and periods.


5.18.1 Cmd Objects

module-cmd.html | module-cmd.html | module-shlex.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
5.18 cmd (module-cmd.html)
Up:
5.18 cmd (module-cmd.html)
Next:
5.19 shlex (module-shlex.html)
---
## 5.18.1 Cmd Objects
A Cmd instance has the following methods:
Instances of Cmd subclasses have some public instance variables:


4.9.1.1 Codec Objects

node120.html | node120.html | stream-writer-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
4.9.1 Codec Base Classes (node120.html)
Up:
4.9.1 Codec Base Classes (node120.html)
Next:
4.9.1.2 StreamWriter Objects (stream-writer-objects.html)
---
### 4.9.1.1 Codec Objects
The Codec class defines these methods which also define the
function interfaces of the stateless encoder and decoder:
The StreamWriter and StreamReader classes provide
generic working interfaces which can be used to implement new
encodings submodules very easily. See encodings.utf_8 for an
example on how this is done.


2.2.3 Comparisons

boolean.html | types.html | typesnumeric.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
2.2.2 Boolean Operations (boolean.html)
Up:
2.2 Built-in Types (types.html)
Next:
2.2.4 Numeric Types (typesnumeric.html)
---
## 2.2.3 Comparisons
Comparison operations are supported by all objects. They all have the
same priority (which is higher than that of the Boolean operations).
Comparisons can be chained arbitrarily; for example, `x < y <= z` is equivalent to `x < y and y <= z`, except that y is evaluated only once (but
in both cases z is not evaluated at all when `x < y` is found to be false).
This table summarizes the comparison operations:
Notes:
(1): `<>` and `!=` are alternate spellings for the same operator.
`!=` is the preferred spelling; `<>` is obsolescent.
Objects of different types, except different numeric types and different string types, never
compare equal; such objects are ordered consistently but arbitrarily
(so that sorting a heterogeneous array yields a consistent result).
Furthermore, some types (for example, file objects) support only a
degenerate notion of comparison where any two objects of that type are
unequal. Again, such objects are ordered arbitrarily but
consistently. The `<`, `<=`, `>` and `>=`
operators will raise a TypeError exception when any operand
is a complex number.
Instances of a class normally compare as non-equal unless the class
defines the __cmp__() method. Refer to the
Python Reference Manual (../ref/customization.html) for
information on the use of this method to effect object comparisons.
Implementation note: Objects of different types except
numbers are ordered by their type names; objects of the same types
that don't support proper comparison are ordered by their address.
Two more operations with the same syntactic priority,
"in" and "not in", are supported
only by sequence types (below).


19. Python compiler package

module-distutils.html | lib.html | module-compiler.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
18.11 distutils (module-distutils.html)
Up:
Python Library Reference (lib.html)
Next:
19.1 The basic interface (module-compiler.html)
---
# 19. Python compiler package
The Python compiler package is a tool for analyzing Python source code
and generating Python bytecode. The compiler contains libraries to
generate an abstract syntax tree from Python source code and to
generate Python bytecode from the tree.
The compiler (module-compiler.html) package is a Python source to bytecode
translator written in Python. It uses the built-in parser and
standard parser (module-parser.html) module to generated a concrete syntax
tree. This tree is used to generate an abstract syntax tree (AST) and
then Python bytecode.
The full functionality of the package duplicates the builtin compiler
provided with the Python interpreter. It is intended to match its
behavior almost exactly. Why implement another compiler that does the
same thing? The package is useful for a variety of purposes. It can
be modified more easily than the builtin compiler. The AST it
generates is useful for analyzing Python source code.
This chapter explains how the various components of the
compiler (module-compiler.html) package work. It blends reference material with
a tutorial.
The following modules are part of the compiler (module-compiler.html) package:
compiler (module-compiler.html)
compiler.ast (module-compiler.ast.html)
compiler.visitor (module-compiler.visitor.html)


7.21.1 Completer Objects

module-rlcompleter.html | module-rlcompleter.html | unix.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
7.21 rlcompleter (module-rlcompleter.html)
Up:
7.21 rlcompleter (module-rlcompleter.html)
Next:
8. Unix Specific Services (unix.html)
---
## 7.21.1 Completer Objects
Completer objects have the following method:


7.5.3 Condition Objects

rlock-objects.html | module-threading.html | semaphore-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
7.5.2 RLock Objects (rlock-objects.html)
Up:
7.5 threading (module-threading.html)
Next:
7.5.4 Semaphore Objects (semaphore-objects.html)
---
## 7.5.3 Condition Objects
A condition variable is always associated with some kind of lock;
this can be passed in or one will be created by default. (Passing
one in is useful when several condition variables must share the
same lock.)
A condition variable has acquire() and release()
methods that call the corresponding methods of the associated lock.
It also has a wait() method, and notify() and
notifyAll() methods. These three must only be called when
the calling thread has acquired the lock.
The wait() method releases the lock, and then blocks until it
is awakened by a notify() or notifyAll() call for
the same condition variable in another thread. Once awakened, it
re-acquires the lock and returns. It is also possible to specify a
timeout.
The notify() method wakes up one of the threads waiting for
the condition variable, if any are waiting. The notifyAll()
method wakes up all threads waiting for the condition variable.
Note: the notify() and notifyAll() methods don't
release the lock; this means that the thread or threads awakened will
not return from their wait() call immediately, but only when
the thread that called notify() or notifyAll()
finally relinquishes ownership of the lock.
Tip: the typical programming style using condition variables uses the
lock to synchronize access to some shared state; threads that are
interested in a particular change of state call wait()
repeatedly until they see the desired state, while threads that modify
the state call notify() or notifyAll() when they
change the state in such a way that it could possibly be a desired
state for one of the waiters. For example, the following code is a
generic producer-consumer situation with unlimited buffer capacity:
```text

# Consume one item
cv.acquire()
while not an_item_is_available():
cv.wait()
get_an_available_item()
cv.release()

# Produce one item
cv.acquire()
make_an_item_available()
cv.notify()
cv.release()
```
To choose between notify() and notifyAll(), consider
whether one state change can be interesting for only one or several
waiting threads. E.g. in a typical producer-consumer situation,
adding one item to the buffer only needs to wake up one consumer
thread.


5.14.2 ConfigParser Objects

RawConfigParser-objects.html | module-ConfigParser.html | module-fileinput.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
5.14.1 RawConfigParser Objects (RawConfigParser-objects.html)
Up:
5.14 ConfigParser (module-ConfigParser.html)
Next:
5.15 fileinput (module-fileinput.html)
---
## 5.14.2 ConfigParser Objects
The ConfigParser class extends some methods of the
RawConfigParser interface, adding some optional arguments.


3.23.2 Interactive Console Objects

interpreter-objects.html | module-code.html | module-codeop.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
3.23.1 Interactive Interpreter Objects (interpreter-objects.html)
Up:
3.23 code (module-code.html)
Next:
3.24 codeop (module-codeop.html)
---
## 3.23.2 Interactive Console Objects
The InteractiveConsole class is a subclass of
InteractiveInterpreter, and so offers all the methods of the
interpreter objects as well as the following additions.


13.10.1 ContentHandler Objects

module-xml.sax.handler.html | module-xml.sax.handler.html | dtd-handler-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
13.10 xml.sax.handler (module-xml.sax.handler.html)
Up:
13.10 xml.sax.handler (module-xml.sax.handler.html)
Next:
13.10.2 DTDHandler Objects (dtd-handler-objects.html)
---
## 13.10.1 ContentHandler Objects
Users are expected to subclass ContentHandler to support their
application. The following methods are called by the parser on the
appropriate events in the input document: