From 450a64f508edd764edfd6ab2363d5f9143ab91bb Mon Sep 17 00:00:00 2001
From: Matthias Klose <doko@ubuntu.com>
Date: Wed, 6 Jun 2018 00:25:44 +0200
Subject: [PATCH] * Remove the FAQ for Python2.
---
debian/changelog | 1 +
debian/rules | 42 -
faq/FAQ.ht | 19 -
faq/FAQ.html | 358 --------
faq/extending.ht | 467 ----------
faq/extending.html | 793 -----------------
faq/general.ht | 1460 ------------------------------
faq/general.html | 1675 ----------------------------------
faq/gui.ht | 173 ----
faq/gui.html | 516 -----------
faq/installed.ht | 61 --
faq/installed.html | 392 --------
faq/library.ht | 913 -------------------
faq/library.html | 1193 -------------------------
faq/programming.ht | 1756 ------------------------------------
faq/programming.html | 2025 ------------------------------------------
faq/windows.ht | 592 ------------
faq/windows.html | 912 -------------------
18 files changed, 1 insertion(+), 13347 deletions(-)
delete mode 100644 faq/FAQ.ht
delete mode 100644 faq/FAQ.html
delete mode 100644 faq/extending.ht
delete mode 100644 faq/extending.html
delete mode 100644 faq/general.ht
delete mode 100644 faq/general.html
delete mode 100644 faq/gui.ht
delete mode 100644 faq/gui.html
delete mode 100644 faq/installed.ht
delete mode 100644 faq/installed.html
delete mode 100644 faq/library.ht
delete mode 100644 faq/library.html
delete mode 100644 faq/programming.ht
delete mode 100644 faq/programming.html
delete mode 100644 faq/windows.ht
delete mode 100644 faq/windows.html
diff --git a/debian/changelog b/debian/changelog
index bed7929..34c0eef 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -5,6 +5,7 @@ python-defaults (2.7.15~rc1-2) UNRELEASED; urgency=medium
it. No changes for the "-all" packages.
* Update Vcs attributes.
* Remove Barry Warsaw as uploader.
+ * Remove the FAQ for Python2.
-- Matthias Klose <doko@debian.org> Wed, 06 Jun 2018 00:09:55 +0200
diff --git a/debian/rules b/debian/rules
index 304b6ba..246212e 100755
--- a/debian/rules
+++ b/debian/rules
@@ -89,34 +89,6 @@ endif
&& rm -f debian/control.tmp && exit 0; \
mv debian/control.tmp debian/control
-faqs = index general programming library extending windows gui installed
-get-faq:
- # Note: This rule is broken due to web site reorg at python.org
- rm -rf faq
- mkdir faq
- cd faq && \
- wget -nv $(foreach p,$(faqs),http://python.org/doc/faq/$(p).ht)
- sed 's,\<\([a-zA-Z0-9]*\.html\)\>,faq/\1,' faq/index.ht \
- | awk '/^Translations$$/ {exit} {print}' > faq/FAQ.ht
- ( \
- echo ''; \
- echo 'This is a local copy of the online FAQ located at'; \
- echo 'http://python.org/doc/faq.'; \
- echo "The copy was fetched and generated in `date '+%B %Y'`."; \
- ) >> faq/FAQ.ht
- rm -f faq/index.ht
-
-make-faq:
- set -e; \
- cd faq && \
- for p in *.ht; do \
- p=`basename $$p .ht`; \
- echo $(rst2html) $$p.ht $$p.html; \
- awk 'NR > 2' $$p.ht > $$p.ht2; \
- $(rst2html) $$p.ht2 $$p.html; \
- rm -f $$p.ht2; \
- done
-
MANPAGES ?= dh_python2.1 pycompile.1 pyclean.1
%.1: %.rst
@@ -165,23 +137,9 @@ install: build stamp-dh_python stamp-install
stamp-install: stamp-build control-file stamp-control
dh_testdir
dh_testroot
- dh_installdirs -ppython2 usr/share/doc/python2/faq
dh_installdirs -ppython usr/share/doc/python
dh_install
- set -e; \
- cd faq && \
- for p in *.ht; do \
- p=`basename $$p .ht`; \
- cp $$p.html ../debian/python2/usr/share/doc/python2/faq/; \
- done
- mv debian/python2/usr/share/doc/python2/faq/FAQ.html \
- debian/python2/usr/share/doc/python2/
- ln -sf ../python2/faq \
- debian/python/usr/share/doc/python/faq
- ln -sf ../python2/FAQ.html \
- debian/python/usr/share/doc/python/FAQ.html
-
touch stamp-install
stamp-dh_python:
diff --git a/faq/FAQ.ht b/faq/FAQ.ht
deleted file mode 100644
index cab69ed..0000000
--- a/faq/FAQ.ht
+++ /dev/null
@@ -1,19 +0,0 @@
-Title: Python Frequently Asked Question Lists
-Content-type: text/x-rst
-
-==========================================
-Python Frequently Asked Question Lists
-==========================================
-
-* `General Python FAQ <faq/general.html>`_
-* `Programming FAQ <faq/programming.html>`_
-* `Library and Extension FAQ <faq/library.html>`_
-* `Extending/Embedding FAQ <faq/extending.html>`_
-* `Windows FAQ <faq/windows.html>`_
-* `GUI Programming FAQ <faq/gui.html>`_
-* `"Why is Python Installed on my Computer?" FAQ <faq/installed.html>`_
-
-
-This is a local copy of the online FAQ located at
-http://python.org/doc/faq.
-The copy was fetched and generated in May 2007.
diff --git a/faq/FAQ.html b/faq/FAQ.html
deleted file mode 100644
index df156ce..0000000
--- a/faq/FAQ.html
+++ /dev/null
@@ -1,358 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
-<title>Python Frequently Asked Question Lists</title>
-<style type="text/css">
-
-/*
-:Author: David Goodger (goodger@python.org)
-:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
- border: 0 }
-
-table.borderless td, table.borderless th {
- /* Override padding for "table.docutils td" with "! important".
- The right padding separates the table cells. */
- padding: 0 0.5em 0 0 ! important }
-
-.first {
- /* Override more specific margin styles with "! important". */
- margin-top: 0 ! important }
-
-.last, .with-subtitle {
- margin-bottom: 0 ! important }
-
-.hidden {
- display: none }
-
-a.toc-backref {
- text-decoration: none ;
- color: black }
-
-blockquote.epigraph {
- margin: 2em 5em ; }
-
-dl.docutils dd {
- margin-bottom: 0.5em }
-
-object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
- overflow: hidden;
-}
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
- font-weight: bold }
-*/
-
-div.abstract {
- margin: 2em 5em }
-
-div.abstract p.topic-title {
- font-weight: bold ;
- text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
- margin: 2em ;
- border: medium outset ;
- padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title, .code .error {
- color: red ;
- font-weight: bold ;
- font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
- compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
- margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
- margin-top: 0.5em }
-*/
-
-div.dedication {
- margin: 2em 5em ;
- text-align: center ;
- font-style: italic }
-
-div.dedication p.topic-title {
- font-weight: bold ;
- font-style: normal }
-
-div.figure {
- margin-left: 2em ;
- margin-right: 2em }
-
-div.footer, div.header {
- clear: both;
- font-size: smaller }
-
-div.line-block {
- display: block ;
- margin-top: 1em ;
- margin-bottom: 1em }
-
-div.line-block div.line-block {
- margin-top: 0 ;
- margin-bottom: 0 ;
- margin-left: 1.5em }
-
-div.sidebar {
- margin: 0 0 0.5em 1em ;
- border: medium outset ;
- padding: 1em ;
- background-color: #ffffee ;
- width: 40% ;
- float: right ;
- clear: right }
-
-div.sidebar p.rubric {
- font-family: sans-serif ;
- font-size: medium }
-
-div.system-messages {
- margin: 5em }
-
-div.system-messages h1 {
- color: red }
-
-div.system-message {
- border: medium outset ;
- padding: 1em }
-
-div.system-message p.system-message-title {
- color: red ;
- font-weight: bold }
-
-div.topic {
- margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
- margin-top: 0.4em }
-
-h1.title {
- text-align: center }
-
-h2.subtitle {
- text-align: center }
-
-hr.docutils {
- width: 75% }
-
-img.align-left, .figure.align-left, object.align-left {
- clear: left ;
- float: left ;
- margin-right: 1em }
-
-img.align-right, .figure.align-right, object.align-right {
- clear: right ;
- float: right ;
- margin-left: 1em }
-
-img.align-center, .figure.align-center, object.align-center {
- display: block;
- margin-left: auto;
- margin-right: auto;
-}
-
-.align-left {
- text-align: left }
-
-.align-center {
- clear: both ;
- text-align: center }
-
-.align-right {
- text-align: right }
-
-/* reset inner alignment in figures */
-div.align-right {
- text-align: inherit }
-
-/* div.align-center * { */
-/* text-align: left } */
-
-ol.simple, ul.simple {
- margin-bottom: 1em }
-
-ol.arabic {
- list-style: decimal }
-
-ol.loweralpha {
- list-style: lower-alpha }
-
-ol.upperalpha {
- list-style: upper-alpha }
-
-ol.lowerroman {
- list-style: lower-roman }
-
-ol.upperroman {
- list-style: upper-roman }
-
-p.attribution {
- text-align: right ;
- margin-left: 50% }
-
-p.caption {
- font-style: italic }
-
-p.credits {
- font-style: italic ;
- font-size: smaller }
-
-p.label {
- white-space: nowrap }
-
-p.rubric {
- font-weight: bold ;
- font-size: larger ;
- color: maroon ;
- text-align: center }
-
-p.sidebar-title {
- font-family: sans-serif ;
- font-weight: bold ;
- font-size: larger }
-
-p.sidebar-subtitle {
- font-family: sans-serif ;
- font-weight: bold }
-
-p.topic-title {
- font-weight: bold }
-
-pre.address {
- margin-bottom: 0 ;
- margin-top: 0 ;
- font: inherit }
-
-pre.literal-block, pre.doctest-block, pre.math, pre.code {
- margin-left: 2em ;
- margin-right: 2em }
-
-pre.code .ln { color: grey; } /* line numbers */
-pre.code, code { background-color: #eeeeee }
-pre.code .comment, code .comment { color: #5C6576 }
-pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
-pre.code .literal.string, code .literal.string { color: #0C5404 }
-pre.code .name.builtin, code .name.builtin { color: #352B84 }
-pre.code .deleted, code .deleted { background-color: #DEB0A1}
-pre.code .inserted, code .inserted { background-color: #A3D289}
-
-span.classifier {
- font-family: sans-serif ;
- font-style: oblique }
-
-span.classifier-delimiter {
- font-family: sans-serif ;
- font-weight: bold }
-
-span.interpreted {
- font-family: sans-serif }
-
-span.option {
- white-space: nowrap }
-
-span.pre {
- white-space: pre }
-
-span.problematic {
- color: red }
-
-span.section-subtitle {
- /* font-size relative to parent (h1..h6 element) */
- font-size: 80% }
-
-table.citation {
- border-left: solid 1px gray;
- margin-left: 1px }
-
-table.docinfo {
- margin: 2em 4em }
-
-table.docutils {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
-
-table.footnote {
- border-left: solid 1px black;
- margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
- padding-left: 0.5em ;
- padding-right: 0.5em ;
- vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
- font-weight: bold ;
- text-align: left ;
- white-space: nowrap ;
- padding-left: 0 }
-
-/* "booktabs" style (no vertical lines) */
-table.docutils.booktabs {
- border: 0px;
- border-top: 2px solid;
- border-bottom: 2px solid;
- border-collapse: collapse;
-}
-table.docutils.booktabs * {
- border: 0px;
-}
-table.docutils.booktabs th {
- border-bottom: thin solid;
- text-align: left;
-}
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
- font-size: 100% }
-
-ul.auto-toc {
- list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="python-frequently-asked-question-lists">
-<h1 class="title">Python Frequently Asked Question Lists</h1>
-
-<ul class="simple">
-<li><a class="reference external" href="faq/general.html">General Python FAQ</a></li>
-<li><a class="reference external" href="faq/programming.html">Programming FAQ</a></li>
-<li><a class="reference external" href="faq/library.html">Library and Extension FAQ</a></li>
-<li><a class="reference external" href="faq/extending.html">Extending/Embedding FAQ</a></li>
-<li><a class="reference external" href="faq/windows.html">Windows FAQ</a></li>
-<li><a class="reference external" href="faq/gui.html">GUI Programming FAQ</a></li>
-<li><a class="reference external" href="faq/installed.html">"Why is Python Installed on my Computer?" FAQ</a></li>
-</ul>
-<p>This is a local copy of the online FAQ located at
-<a class="reference external" href="http://python.org/doc/faq">http://python.org/doc/faq</a>.
-The copy was fetched and generated in May 2007.</p>
-</div>
-</body>
-</html>
diff --git a/faq/extending.ht b/faq/extending.ht
deleted file mode 100644
index 101119c..0000000
--- a/faq/extending.ht
+++ /dev/null
@@ -1,467 +0,0 @@
-Title: Python Extending/Embedding FAQ
-Content-type: text/x-rst
-
-====================================
-Extending/Embedding FAQ
-====================================
-
-:Date: $Date: 2004-04-08 09:05:47 -0600 (Thu, 08 Apr 2004) $
-:Version: $Revision: 7294 $
-:Web site: http://www.python.org/
-
-.. contents::
-.. sectnum::
-
-
-Can I create my own functions in C?
-------------------------------------------
-Yes, you can create built-in modules containing functions,
-variables, exceptions and even new types in C. This is explained in
-the document "Extending and Embedding the Python Interpreter" (http://docs.python.org/ext/ext.html).
-
-Most intermediate or advanced Python books will also
-cover this topic.
-
-Can I create my own functions in C++?
---------------------------------------------
-Yes, using the C compatibility features found in C++.
-Place ``extern "C" { ... }`` around the Python include files and put
-``extern "C"`` before each function that is going to be called by the
-Python interpreter. Global or static C++ objects with constructors
-are probably not a good idea.
-
-Writing C is hard; are there any alternatives?
----------------------------------------------------
-
-There are a number of alternatives to writing your own C extensions,
-depending on what you're trying to do.
-
-If you need more speed, `Psyco <http://psyco.sourceforge.net/>`_ generates x86 assembly code
-from Python bytecode. You can use Psyco to compile the most
-time-critical functions in your code, and gain a significant
-improvement with very little effort, as long as you're running on a
-machine with an x86-compatible processor.
-
-`Pyrex <http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/>`_ is a compiler that accepts a slightly modified form of Python
-and generates the corresponding C code. Pyrex makes it possible to write
-an extension without having to learn Python's C API.
-
-If you need to interface to some C library for which no Python
-extension currently exists, you can try wrapping the library's data
-types and functions with a tool such as `SWIG <http://www.swig.org>`_.
-For C++ libraries, you can look at `SIP <http://www.riverbankcomputing.co.uk/sip/>`_, `CXX <http://cxx.sourceforge.net/>`_, `Boost
-<http://www.boost.org/libs/python/doc/index.html>`_, or `Weave <http://www.scipy.org/site_content/weave>`_.
-
-
-How can I execute arbitrary Python statements from C?
-------------------------------------------------------------
-The highest-level function to do this is ``PyRun_SimpleString()`` which takes
-a single string argument to be executed in the context of the module
-``__main__`` and returns 0 for success and -1 when an exception occurred
-(including ``SyntaxError``). If you want more control, use ``PyRun_String()``;
-see the source for ``PyRun_SimpleString()`` in Python/pythonrun.c.
-
-
-How can I evaluate an arbitrary Python expression from C?
-----------------------------------------------------------------
-Call the function ``PyRun_String()`` from the previous question with the
-start symbol ``Py_eval_input``; it
-parses an expression, evaluates it and returns its value.
-
-How do I extract C values from a Python object?
-------------------------------------------------------
-That depends on the object's type. If it's a tuple,
-``PyTupleSize(o)`` returns its length and ``PyTuple_GetItem(o, i)``
-returns its i'th item. Lists have similar functions, ``PyListSize(o)``
-and ``PyList_GetItem(o, i)``.
-
-For strings, ``PyString_Size(o)`` returns
-its length and ``PyString_AsString(o)`` a pointer to its value.
-Note that Python strings may contain null bytes so C's ``strlen()``
-should not be used.
-
-To test the type of an object, first make sure
-it isn't NULL, and then use ``PyString_Check(o)``, ``PyTuple_Check(o)``,
-``PyList_Check(o)``, etc.
-
-There is also a high-level API to Python objects which is
-provided by the so-called 'abstract' interface -- read
-``Include/abstract.h`` for further details. It allows
-interfacing with any kind of Python sequence
-using calls like ``PySequence_Length()``, ``PySequence_GetItem()``, etc.)
-as well as many other useful protocols.
-
-How do I use Py_BuildValue() to create a tuple of arbitrary length?
---------------------------------------------------------------------------
-You can't. Use ``t = PyTuple_New(n)`` instead, and fill it with
-objects using ``PyTuple_SetItem(t, i, o)`` -- note that this "eats" a
-reference count of ``o``, so you have to ``Py_INCREF`` it.
-Lists have similar functions ``PyList_New(n)`` and
-``PyList_SetItem(l, i, o)``. Note that you *must* set all the tuple items to
-some value before you pass the tuple to Python code --
-``PyTuple_New(n)`` initializes them to NULL, which isn't a valid Python
-value.
-
-How do I call an object's method from C?
------------------------------------------------
-The ``PyObject_CallMethod()`` function can be used to call an arbitrary
-method of an object. The parameters are the object, the name of the
-method to call, a format string like that used with ``Py_BuildValue()``, and the argument values::
-
- PyObject *
- PyObject_CallMethod(PyObject *object, char *method_name,
- char *arg_format, ...);
-
-This works for any object that has methods -- whether built-in or
-user-defined. You are responsible for eventually ``Py_DECREF``'ing the
-return value.
-
-To call, e.g., a file object's "seek" method with arguments 10, 0
-(assuming the file object pointer is "f")::
-
- res = PyObject_CallMethod(f, "seek", "(ii)", 10, 0);
- if (res == NULL) {
- ... an exception occurred ...
- }
- else {
- Py_DECREF(res);
- }
-
-Note that since ``PyObject_CallObject()`` *always* wants a tuple for the
-argument list, to call a function without arguments, pass "()" for the
-format, and to call a function with one argument, surround the argument
-in parentheses, e.g. "(i)".
-
-
-How do I catch the output from PyErr_Print() (or anything that prints to stdout/stderr)?
------------------------------------------------------------------------------------------------
-In Python code, define an object that supports the ``write()`` method.
-Assign this object to ``sys.stdout`` and ``sys.stderr``.
-Call print_error, or just allow the standard traceback mechanism to
-work. Then, the output will go wherever your ``write()`` method sends it.
-
-The easiest way to do this is to use the StringIO class in the standard
-library.
-
-Sample code and use for catching stdout::
-
- >>> class StdoutCatcher:
- ... def __init__(self):
- ... self.data = ''
- ... def write(self, stuff):
- ... self.data = self.data + stuff
- ...
- >>> import sys
- >>> sys.stdout = StdoutCatcher()
- >>> print 'foo'
- >>> print 'hello world!'
- >>> sys.stderr.write(sys.stdout.data)
- foo
- hello world!
-
-
-How do I access a module written in Python from C?
----------------------------------------------------------
-You can get a pointer to the module object as follows::
-
- module = PyImport_ImportModule("<modulename>");
-
-If the module hasn't been imported yet (i.e. it is not yet present in
-``sys.modules``), this initializes the module; otherwise it simply returns
-the value of ``sys.modules["<modulename>"]``. Note that it doesn't enter
-the module into any namespace -- it only ensures it has been
-initialized and is stored in ``sys.modules``.
-
-You can then access the module's attributes (i.e. any name defined in
-the module) as follows::
-
- attr = PyObject_GetAttrString(module, "<attrname>");
-
-Calling ``PyObject_SetAttrString()`` to assign to variables in the module also works.
-
-
-How do I interface to C++ objects from Python?
-------------------------------------------------------
-Depending on your requirements, there are many approaches. To do
-this manually, begin by reading `the "Extending and Embedding" document <http://docs.python.org/ext/ext.html>`_. Realize
-that for the Python run-time system, there isn't a whole lot of
-difference between C and C++ -- so the strategy of building a new Python
-type around a C structure (pointer) type will also work for C++
-objects.
-
-For C++ libraries, you can look at `SIP <http://www.riverbankcomputing.co.uk/sip/>`_, `CXX <http://cxx.sourceforge.net/>`_, `Boost
-<http://www.boost.org/libs/python/doc/index.html>`_, or `Weave <http://www.scipy.org/site_content/weave>`_.
-`SWIG <http://www.swig.org>`_ is a similar automated tool that only supports C libraries.
-
-
-I added a module using the Setup file and the make fails; why?
-----------------------------------------------------------------------
-
-Setup must end in a newline, if there is no newline there, the build
-process fails. (Fixing this requires some ugly shell script hackery,
-and this bug is so minor that it doesn't seem worth the effort.)
-
-How do I debug an extension?
-------------------------------------
-When using GDB with dynamically loaded extensions, you can't set a
-breakpoint in your extension until your extension is loaded.
-
-In your ``.gdbinit`` file (or interactively), add the command::
-
- br _PyImport_LoadDynamicModule
-
-Then, when you run GDB::
-
- $ gdb /local/bin/python
- gdb) run myscript.py
- gdb) continue # repeat until your extension is loaded
- gdb) finish # so that your extension is loaded
- gdb) br myfunction.c:50
- gdb) continue
-
-I want to compile a Python module on my Linux system, but some files are missing. Why?
--------------------------------------------------------------------------------------------------
-
-Most packaged versions of Python don't include the
-/usr/lib/python2.x/config/ directory, which contains various files required
-for compiling Python extensions.
-
-For Red Hat, install the python-devel RPM to get the necessary files.
-
-For Debian, run ``apt-get install python-dev``.
-
-
-What does "SystemError: _PyImport_FixupExtension: module yourmodule not loaded" mean?
--------------------------------------------------------------------------------------------------------
-This means that you have created an extension module named "yourmodule", but your module init function does not initialize with that name.
-
-Every module init function will have a line similar to::
-
- module = Py_InitModule("yourmodule", yourmodule_functions);
-
-If the string passed to this function is not the same name as your
-extenion module, the ``SystemError`` exception will be raised.
-
-
-How do I tell "incomplete input" from "invalid input"?
---------------------------------------------------------------------------------
-Sometimes you want to emulate the Python interactive interpreter's
-behavior, where it gives you a continuation prompt when the input
-is incomplete (e.g. you typed the start of an "if" statement
-or you didn't close your parentheses or triple string quotes),
-but it gives you a syntax error message immediately when the input
-is invalid.
-
-In Python you can use the ``codeop`` module, which approximates the
-parser's behavior sufficiently. IDLE uses this, for example.
-
-The easiest way to do it in C is to call ``PyRun_InteractiveLoop()``
-(perhaps in a separate thread) and let the Python interpreter handle
-the input for you. You can also set the ``PyOS_ReadlineFunctionPointer``
-to point at your custom input function. See ``Modules/readline.c`` and
-``Parser/myreadline.c`` for more hints.
-
-However sometimes you have to run the embedded Python interpreter in
-the same thread as your rest application and you can't allow the
-``PyRun_InteractiveLoop()`` to stop while waiting for user input. The
-one solution then is to call ``PyParser_ParseString()`` and test for
-``e.error`` equal to ``E_EOF``, which means the input is incomplete).
-Here's a sample code fragment, untested, inspired by code from Alex Farber::
-
- #include <Python.h>
- #include <node.h>
- #include <errcode.h>
- #include <grammar.h>
- #include <parsetok.h>
- #include <compile.h>
-
- int testcomplete(char *code)
- /* code should end in \n */
- /* return -1 for error, 0 for incomplete, 1 for complete */
- {
- node *n;
- perrdetail e;
-
- n = PyParser_ParseString(code, &_PyParser_Grammar,
- Py_file_input, &e);
- if (n == NULL) {
- if (e.error == E_EOF)
- return 0;
- return -1;
- }
-
- PyNode_Free(n);
- return 1;
- }
-
-Another solution is trying to compile the received string with
-``Py_CompileString()``. If it compiles without errors, try to execute the returned
-code object by calling ``PyEval_EvalCode()``. Otherwise save the input for
-later. If the compilation fails, find out if it's an error or just
-more input is required - by extracting the message string from the
-exception tuple and comparing it to the string "unexpected EOF while parsing".
-Here is a complete example using the GNU readline library (you may
-want to ignore SIGINT while calling readline())::
-
- #include <stdio.h>
- #include <readline.h>
-
- #include <Python.h>
- #include <object.h>
- #include <compile.h>
- #include <eval.h>
-
- int main (int argc, char* argv[])
- {
- int i, j, done = 0; /* lengths of line, code */
- char ps1[] = ">>> ";
- char ps2[] = "... ";
- char *prompt = ps1;
- char *msg, *line, *code = NULL;
- PyObject *src, *glb, *loc;
- PyObject *exc, *val, *trb, *obj, *dum;
-
- Py_Initialize ();
- loc = PyDict_New ();
- glb = PyDict_New ();
- PyDict_SetItemString (glb, "__builtins__", PyEval_GetBuiltins ());
-
- while (!done)
- {
- line = readline (prompt);
-
- if (NULL == line) /* CTRL-D pressed */
- {
- done = 1;
- }
- else
- {
- i = strlen (line);
-
- if (i > 0)
- add_history (line); /* save non-empty lines */
-
- if (NULL == code) /* nothing in code yet */
- j = 0;
- else
- j = strlen (code);
-
- code = realloc (code, i + j + 2);
- if (NULL == code) /* out of memory */
- exit (1);
-
- if (0 == j) /* code was empty, so */
- code[0] = '\0'; /* keep strncat happy */
-
- strncat (code, line, i); /* append line to code */
- code[i + j] = '\n'; /* append '\n' to code */
- code[i + j + 1] = '\0';
-
- src = Py_CompileString (code, "<stdin>", Py_single_input);
-
- if (NULL != src) /* compiled just fine - */
- {
- if (ps1 == prompt || /* ">>> " or */
- '\n' == code[i + j - 1]) /* "... " and double '\n' */
- { /* so execute it */
- dum = PyEval_EvalCode ((PyCodeObject *)src, glb, loc);
- Py_XDECREF (dum);
- Py_XDECREF (src);
- free (code);
- code = NULL;
- if (PyErr_Occurred ())
- PyErr_Print ();
- prompt = ps1;
- }
- } /* syntax error or E_EOF? */
- else if (PyErr_ExceptionMatches (PyExc_SyntaxError))
- {
- PyErr_Fetch (&exc, &val, &trb); /* clears exception! */
-
- if (PyArg_ParseTuple (val, "sO", &msg, &obj) &&
- !strcmp (msg, "unexpected EOF while parsing")) /* E_EOF */
- {
- Py_XDECREF (exc);
- Py_XDECREF (val);
- Py_XDECREF (trb);
- prompt = ps2;
- }
- else /* some other syntax error */
- {
- PyErr_Restore (exc, val, trb);
- PyErr_Print ();
- free (code);
- code = NULL;
- prompt = ps1;
- }
- }
- else /* some non-syntax error */
- {
- PyErr_Print ();
- free (code);
- code = NULL;
- prompt = ps1;
- }
-
- free (line);
- }
- }
-
- Py_XDECREF(glb);
- Py_XDECREF(loc);
- Py_Finalize();
- exit(0);
- }
-
-
-
-How do I find undefined g++ symbols __builtin_new or __pure_virtual?
------------------------------------------------------------------------------------
-
-To dynamically load g++ extension modules, you must recompile Python, relink it using g++ (change LINKCC in the python Modules Makefile), and link your extension module using g++ (e.g., "g++ -shared -o mymodule.so mymodule.o").
-
-
-Can I create an object class with some methods implemented in C and others in Python (e.g. through inheritance)?
------------------------------------------------------------------------------------------------------------------------------------------------------
-
-In Python 2.2, you can inherit from builtin classes such as int, list, dict, etc.
-
-The Boost Python Library (BPL, http://www.boost.org/libs/python/doc/index.html)
-provides a way of doing this from C++ (i.e. you can inherit from an
-extension class written in C++ using the BPL).
-
-When importing module X, why do I get "undefined symbol: PyUnicodeUCS2*"?
---------------------------------------------------------------------------------------------------
-
-You are using a version of Python that uses a 4-byte representation
-for Unicode characters, but some C extension module you are importing
-was compiled using a Python that uses a 2-byte representation for
-Unicode characters (the default).
-
-If instead the name of the undefined symbol starts with
-``PyUnicodeUCS4``, the problem is the reverse: Python was built using
-2-byte Unicode characters, and the extension module was compiled using
-a Python with 4-byte Unicode characters.
-
-This can easily occur when using pre-built extension packages. RedHat
-Linux 7.x, in particular, provided a "python2" binary that is compiled
-with 4-byte Unicode. This only causes the link failure if the extension
-uses any of the ``PyUnicode_*()`` functions. It is also a problem if an
-extension uses any of the Unicode-related format specifiers for
-``Py_BuildValue`` (or similar) or parameter specifications for
-``PyArg_ParseTuple()``.
-
-You can check the size of the Unicode character a Python interpreter is
-using by checking the value of sys.maxunicode::
-
- >>> import sys
- >>> if sys.maxunicode > 65535:
- ... print 'UCS4 build'
- ... else:
- ... print 'UCS2 build'
-
-The only way to solve this problem is to use extension modules compiled
-with a Python binary built using the same size for Unicode characters.
-
-
-
diff --git a/faq/extending.html b/faq/extending.html
deleted file mode 100644
index 8d35504..0000000
--- a/faq/extending.html
+++ /dev/null
@@ -1,793 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
-<title>Extending/Embedding FAQ</title>
-<meta name="date" content="2004-04-08" />
-<style type="text/css">
-
-/*
-:Author: David Goodger (goodger@python.org)
-:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
- border: 0 }
-
-table.borderless td, table.borderless th {
- /* Override padding for "table.docutils td" with "! important".
- The right padding separates the table cells. */
- padding: 0 0.5em 0 0 ! important }
-
-.first {
- /* Override more specific margin styles with "! important". */
- margin-top: 0 ! important }
-
-.last, .with-subtitle {
- margin-bottom: 0 ! important }
-
-.hidden {
- display: none }
-
-a.toc-backref {
- text-decoration: none ;
- color: black }
-
-blockquote.epigraph {
- margin: 2em 5em ; }
-
-dl.docutils dd {
- margin-bottom: 0.5em }
-
-object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
- overflow: hidden;
-}
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
- font-weight: bold }
-*/
-
-div.abstract {
- margin: 2em 5em }
-
-div.abstract p.topic-title {
- font-weight: bold ;
- text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
- margin: 2em ;
- border: medium outset ;
- padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title, .code .error {
- color: red ;
- font-weight: bold ;
- font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
- compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
- margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
- margin-top: 0.5em }
-*/
-
-div.dedication {
- margin: 2em 5em ;
- text-align: center ;
- font-style: italic }
-
-div.dedication p.topic-title {
- font-weight: bold ;
- font-style: normal }
-
-div.figure {
- margin-left: 2em ;
- margin-right: 2em }
-
-div.footer, div.header {
- clear: both;
- font-size: smaller }
-
-div.line-block {
- display: block ;
- margin-top: 1em ;
- margin-bottom: 1em }
-
-div.line-block div.line-block {
- margin-top: 0 ;
- margin-bottom: 0 ;
- margin-left: 1.5em }
-
-div.sidebar {
- margin: 0 0 0.5em 1em ;
- border: medium outset ;
- padding: 1em ;
- background-color: #ffffee ;
- width: 40% ;
- float: right ;
- clear: right }
-
-div.sidebar p.rubric {
- font-family: sans-serif ;
- font-size: medium }
-
-div.system-messages {
- margin: 5em }
-
-div.system-messages h1 {
- color: red }
-
-div.system-message {
- border: medium outset ;
- padding: 1em }
-
-div.system-message p.system-message-title {
- color: red ;
- font-weight: bold }
-
-div.topic {
- margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
- margin-top: 0.4em }
-
-h1.title {
- text-align: center }
-
-h2.subtitle {
- text-align: center }
-
-hr.docutils {
- width: 75% }
-
-img.align-left, .figure.align-left, object.align-left {
- clear: left ;
- float: left ;
- margin-right: 1em }
-
-img.align-right, .figure.align-right, object.align-right {
- clear: right ;
- float: right ;
- margin-left: 1em }
-
-img.align-center, .figure.align-center, object.align-center {
- display: block;
- margin-left: auto;
- margin-right: auto;
-}
-
-.align-left {
- text-align: left }
-
-.align-center {
- clear: both ;
- text-align: center }
-
-.align-right {
- text-align: right }
-
-/* reset inner alignment in figures */
-div.align-right {
- text-align: inherit }
-
-/* div.align-center * { */
-/* text-align: left } */
-
-ol.simple, ul.simple {
- margin-bottom: 1em }
-
-ol.arabic {
- list-style: decimal }
-
-ol.loweralpha {
- list-style: lower-alpha }
-
-ol.upperalpha {
- list-style: upper-alpha }
-
-ol.lowerroman {
- list-style: lower-roman }
-
-ol.upperroman {
- list-style: upper-roman }
-
-p.attribution {
- text-align: right ;
- margin-left: 50% }
-
-p.caption {
- font-style: italic }
-
-p.credits {
- font-style: italic ;
- font-size: smaller }
-
-p.label {
- white-space: nowrap }
-
-p.rubric {
- font-weight: bold ;
- font-size: larger ;
- color: maroon ;
- text-align: center }
-
-p.sidebar-title {
- font-family: sans-serif ;
- font-weight: bold ;
- font-size: larger }
-
-p.sidebar-subtitle {
- font-family: sans-serif ;
- font-weight: bold }
-
-p.topic-title {
- font-weight: bold }
-
-pre.address {
- margin-bottom: 0 ;
- margin-top: 0 ;
- font: inherit }
-
-pre.literal-block, pre.doctest-block, pre.math, pre.code {
- margin-left: 2em ;
- margin-right: 2em }
-
-pre.code .ln { color: grey; } /* line numbers */
-pre.code, code { background-color: #eeeeee }
-pre.code .comment, code .comment { color: #5C6576 }
-pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
-pre.code .literal.string, code .literal.string { color: #0C5404 }
-pre.code .name.builtin, code .name.builtin { color: #352B84 }
-pre.code .deleted, code .deleted { background-color: #DEB0A1}
-pre.code .inserted, code .inserted { background-color: #A3D289}
-
-span.classifier {
- font-family: sans-serif ;
- font-style: oblique }
-
-span.classifier-delimiter {
- font-family: sans-serif ;
- font-weight: bold }
-
-span.interpreted {
- font-family: sans-serif }
-
-span.option {
- white-space: nowrap }
-
-span.pre {
- white-space: pre }
-
-span.problematic {
- color: red }
-
-span.section-subtitle {
- /* font-size relative to parent (h1..h6 element) */
- font-size: 80% }
-
-table.citation {
- border-left: solid 1px gray;
- margin-left: 1px }
-
-table.docinfo {
- margin: 2em 4em }
-
-table.docutils {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
-
-table.footnote {
- border-left: solid 1px black;
- margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
- padding-left: 0.5em ;
- padding-right: 0.5em ;
- vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
- font-weight: bold ;
- text-align: left ;
- white-space: nowrap ;
- padding-left: 0 }
-
-/* "booktabs" style (no vertical lines) */
-table.docutils.booktabs {
- border: 0px;
- border-top: 2px solid;
- border-bottom: 2px solid;
- border-collapse: collapse;
-}
-table.docutils.booktabs * {
- border: 0px;
-}
-table.docutils.booktabs th {
- border-bottom: thin solid;
- text-align: left;
-}
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
- font-size: 100% }
-
-ul.auto-toc {
- list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="extending-embedding-faq">
-<h1 class="title">Extending/Embedding FAQ</h1>
-<table class="docinfo" frame="void" rules="none">
-<col class="docinfo-name" />
-<col class="docinfo-content" />
-<tbody valign="top">
-<tr><th class="docinfo-name">Date:</th>
-<td>2004-04-08</td></tr>
-<tr><th class="docinfo-name">Version:</th>
-<td>7294</td></tr>
-<tr class="field"><th class="docinfo-name">Web site:</th><td class="field-body"><a class="reference external" href="http://www.python.org/">http://www.python.org/</a></td>
-</tr>
-</tbody>
-</table>
-<div class="contents topic" id="contents">
-<p class="topic-title first">Contents</p>
-<ul class="auto-toc simple">
-<li><a class="reference internal" href="#can-i-create-my-own-functions-in-c" id="id7">1 Can I create my own functions in C?</a></li>
-<li><a class="reference internal" href="#id1" id="id8">2 Can I create my own functions in C++?</a></li>
-<li><a class="reference internal" href="#writing-c-is-hard-are-there-any-alternatives" id="id9">3 Writing C is hard; are there any alternatives?</a></li>
-<li><a class="reference internal" href="#how-can-i-execute-arbitrary-python-statements-from-c" id="id10">4 How can I execute arbitrary Python statements from C?</a></li>
-<li><a class="reference internal" href="#how-can-i-evaluate-an-arbitrary-python-expression-from-c" id="id11">5 How can I evaluate an arbitrary Python expression from C?</a></li>
-<li><a class="reference internal" href="#how-do-i-extract-c-values-from-a-python-object" id="id12">6 How do I extract C values from a Python object?</a></li>
-<li><a class="reference internal" href="#how-do-i-use-py-buildvalue-to-create-a-tuple-of-arbitrary-length" id="id13">7 How do I use Py_BuildValue() to create a tuple of arbitrary length?</a></li>
-<li><a class="reference internal" href="#how-do-i-call-an-object-s-method-from-c" id="id14">8 How do I call an object's method from C?</a></li>
-<li><a class="reference internal" href="#how-do-i-catch-the-output-from-pyerr-print-or-anything-that-prints-to-stdout-stderr" id="id15">9 How do I catch the output from PyErr_Print() (or anything that prints to stdout/stderr)?</a></li>
-<li><a class="reference internal" href="#how-do-i-access-a-module-written-in-python-from-c" id="id16">10 How do I access a module written in Python from C?</a></li>
-<li><a class="reference internal" href="#how-do-i-interface-to-c-objects-from-python" id="id17">11 How do I interface to C++ objects from Python?</a></li>
-<li><a class="reference internal" href="#i-added-a-module-using-the-setup-file-and-the-make-fails-why" id="id18">12 I added a module using the Setup file and the make fails; why?</a></li>
-<li><a class="reference internal" href="#how-do-i-debug-an-extension" id="id19">13 How do I debug an extension?</a></li>
-<li><a class="reference internal" href="#i-want-to-compile-a-python-module-on-my-linux-system-but-some-files-are-missing-why" id="id20">14 I want to compile a Python module on my Linux system, but some files are missing. Why?</a></li>
-<li><a class="reference internal" href="#what-does-systemerror-pyimport-fixupextension-module-yourmodule-not-loaded-mean" id="id21">15 What does "SystemError: _PyImport_FixupExtension: module yourmodule not loaded" mean?</a></li>
-<li><a class="reference internal" href="#how-do-i-tell-incomplete-input-from-invalid-input" id="id22">16 How do I tell "incomplete input" from "invalid input"?</a></li>
-<li><a class="reference internal" href="#how-do-i-find-undefined-g-symbols-builtin-new-or-pure-virtual" id="id23">17 How do I find undefined g++ symbols __builtin_new or __pure_virtual?</a></li>
-<li><a class="reference internal" href="#can-i-create-an-object-class-with-some-methods-implemented-in-c-and-others-in-python-e-g-through-inheritance" id="id24">18 Can I create an object class with some methods implemented in C and others in Python (e.g. through inheritance)?</a></li>
-<li><a class="reference internal" href="#when-importing-module-x-why-do-i-get-undefined-symbol-pyunicodeucs2" id="id25">19 When importing module X, why do I get "undefined symbol: PyUnicodeUCS2*"?</a></li>
-</ul>
-</div>
-<div class="section" id="can-i-create-my-own-functions-in-c">
-<h1><a class="toc-backref" href="#id7">1 Can I create my own functions in C?</a></h1>
-<p>Yes, you can create built-in modules containing functions,
-variables, exceptions and even new types in C. This is explained in
-the document "Extending and Embedding the Python Interpreter" (<a class="reference external" href="http://docs.python.org/ext/ext.html">http://docs.python.org/ext/ext.html</a>).</p>
-<p>Most intermediate or advanced Python books will also
-cover this topic.</p>
-</div>
-<div class="section" id="id1">
-<h1><a class="toc-backref" href="#id8">2 Can I create my own functions in C++?</a></h1>
-<p>Yes, using the C compatibility features found in C++.
-Place <tt class="docutils literal">extern "C" { ... }</tt> around the Python include files and put
-<tt class="docutils literal">extern "C"</tt> before each function that is going to be called by the
-Python interpreter. Global or static C++ objects with constructors
-are probably not a good idea.</p>
-</div>
-<div class="section" id="writing-c-is-hard-are-there-any-alternatives">
-<h1><a class="toc-backref" href="#id9">3 Writing C is hard; are there any alternatives?</a></h1>
-<p>There are a number of alternatives to writing your own C extensions,
-depending on what you're trying to do.</p>
-<p>If you need more speed, <a class="reference external" href="http://psyco.sourceforge.net/">Psyco</a> generates x86 assembly code
-from Python bytecode. You can use Psyco to compile the most
-time-critical functions in your code, and gain a significant
-improvement with very little effort, as long as you're running on a
-machine with an x86-compatible processor.</p>
-<p><a class="reference external" href="http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/">Pyrex</a> is a compiler that accepts a slightly modified form of Python
-and generates the corresponding C code. Pyrex makes it possible to write
-an extension without having to learn Python's C API.</p>
-<p>If you need to interface to some C library for which no Python
-extension currently exists, you can try wrapping the library's data
-types and functions with a tool such as <a class="reference external" href="http://www.swig.org">SWIG</a>.
-For C++ libraries, you can look at <a class="reference external" href="http://www.riverbankcomputing.co.uk/sip/">SIP</a>, <a class="reference external" href="http://cxx.sourceforge.net/">CXX</a>, <a class="reference external" href="http://www.boost.org/libs/python/doc/index.html">Boost</a>, or <a class="reference external" href="http://www.scipy.org/site_content/weave">Weave</a>.</p>
-</div>
-<div class="section" id="how-can-i-execute-arbitrary-python-statements-from-c">
-<h1><a class="toc-backref" href="#id10">4 How can I execute arbitrary Python statements from C?</a></h1>
-<p>The highest-level function to do this is <tt class="docutils literal">PyRun_SimpleString()</tt> which takes
-a single string argument to be executed in the context of the module
-<tt class="docutils literal">__main__</tt> and returns 0 for success and -1 when an exception occurred
-(including <tt class="docutils literal">SyntaxError</tt>). If you want more control, use <tt class="docutils literal">PyRun_String()</tt>;
-see the source for <tt class="docutils literal">PyRun_SimpleString()</tt> in Python/pythonrun.c.</p>
-</div>
-<div class="section" id="how-can-i-evaluate-an-arbitrary-python-expression-from-c">
-<h1><a class="toc-backref" href="#id11">5 How can I evaluate an arbitrary Python expression from C?</a></h1>
-<p>Call the function <tt class="docutils literal">PyRun_String()</tt> from the previous question with the
-start symbol <tt class="docutils literal">Py_eval_input</tt>; it
-parses an expression, evaluates it and returns its value.</p>
-</div>
-<div class="section" id="how-do-i-extract-c-values-from-a-python-object">
-<h1><a class="toc-backref" href="#id12">6 How do I extract C values from a Python object?</a></h1>
-<p>That depends on the object's type. If it's a tuple,
-<tt class="docutils literal">PyTupleSize(o)</tt> returns its length and <tt class="docutils literal">PyTuple_GetItem(o, i)</tt>
-returns its i'th item. Lists have similar functions, <tt class="docutils literal">PyListSize(o)</tt>
-and <tt class="docutils literal">PyList_GetItem(o, i)</tt>.</p>
-<p>For strings, <tt class="docutils literal">PyString_Size(o)</tt> returns
-its length and <tt class="docutils literal">PyString_AsString(o)</tt> a pointer to its value.
-Note that Python strings may contain null bytes so C's <tt class="docutils literal">strlen()</tt>
-should not be used.</p>
-<p>To test the type of an object, first make sure
-it isn't NULL, and then use <tt class="docutils literal">PyString_Check(o)</tt>, <tt class="docutils literal">PyTuple_Check(o)</tt>,
-<tt class="docutils literal">PyList_Check(o)</tt>, etc.</p>
-<p>There is also a high-level API to Python objects which is
-provided by the so-called 'abstract' interface -- read
-<tt class="docutils literal">Include/abstract.h</tt> for further details. It allows
-interfacing with any kind of Python sequence
-using calls like <tt class="docutils literal">PySequence_Length()</tt>, <tt class="docutils literal">PySequence_GetItem()</tt>, etc.)
-as well as many other useful protocols.</p>
-</div>
-<div class="section" id="how-do-i-use-py-buildvalue-to-create-a-tuple-of-arbitrary-length">
-<h1><a class="toc-backref" href="#id13">7 How do I use Py_BuildValue() to create a tuple of arbitrary length?</a></h1>
-<p>You can't. Use <tt class="docutils literal">t = PyTuple_New(n)</tt> instead, and fill it with
-objects using <tt class="docutils literal">PyTuple_SetItem(t, i, o)</tt> -- note that this "eats" a
-reference count of <tt class="docutils literal">o</tt>, so you have to <tt class="docutils literal">Py_INCREF</tt> it.
-Lists have similar functions <tt class="docutils literal">PyList_New(n)</tt> and
-<tt class="docutils literal">PyList_SetItem(l, i, o)</tt>. Note that you <em>must</em> set all the tuple items to
-some value before you pass the tuple to Python code --
-<tt class="docutils literal">PyTuple_New(n)</tt> initializes them to NULL, which isn't a valid Python
-value.</p>
-</div>
-<div class="section" id="how-do-i-call-an-object-s-method-from-c">
-<h1><a class="toc-backref" href="#id14">8 How do I call an object's method from C?</a></h1>
-<p>The <tt class="docutils literal">PyObject_CallMethod()</tt> function can be used to call an arbitrary
-method of an object. The parameters are the object, the name of the
-method to call, a format string like that used with <tt class="docutils literal">Py_BuildValue()</tt>, and the argument values:</p>
-<pre class="literal-block">
-PyObject *
-PyObject_CallMethod(PyObject *object, char *method_name,
- char *arg_format, ...);
-</pre>
-<p>This works for any object that has methods -- whether built-in or
-user-defined. You are responsible for eventually <tt class="docutils literal">Py_DECREF</tt>'ing the
-return value.</p>
-<p>To call, e.g., a file object's "seek" method with arguments 10, 0
-(assuming the file object pointer is "f"):</p>
-<pre class="literal-block">
-res = PyObject_CallMethod(f, "seek", "(ii)", 10, 0);
-if (res == NULL) {
- ... an exception occurred ...
-}
-else {
- Py_DECREF(res);
-}
-</pre>
-<p>Note that since <tt class="docutils literal">PyObject_CallObject()</tt> <em>always</em> wants a tuple for the
-argument list, to call a function without arguments, pass "()" for the
-format, and to call a function with one argument, surround the argument
-in parentheses, e.g. "(i)".</p>
-</div>
-<div class="section" id="how-do-i-catch-the-output-from-pyerr-print-or-anything-that-prints-to-stdout-stderr">
-<h1><a class="toc-backref" href="#id15">9 How do I catch the output from PyErr_Print() (or anything that prints to stdout/stderr)?</a></h1>
-<p>In Python code, define an object that supports the <tt class="docutils literal">write()</tt> method.
-Assign this object to <tt class="docutils literal">sys.stdout</tt> and <tt class="docutils literal">sys.stderr</tt>.
-Call print_error, or just allow the standard traceback mechanism to
-work. Then, the output will go wherever your <tt class="docutils literal">write()</tt> method sends it.</p>
-<p>The easiest way to do this is to use the StringIO class in the standard
-library.</p>
-<p>Sample code and use for catching stdout:</p>
-<pre class="literal-block">
->>> class StdoutCatcher:
-... def __init__(self):
-... self.data = ''
-... def write(self, stuff):
-... self.data = self.data + stuff
-...
->>> import sys
->>> sys.stdout = StdoutCatcher()
->>> print 'foo'
->>> print 'hello world!'
->>> sys.stderr.write(sys.stdout.data)
-foo
-hello world!
-</pre>
-</div>
-<div class="section" id="how-do-i-access-a-module-written-in-python-from-c">
-<h1><a class="toc-backref" href="#id16">10 How do I access a module written in Python from C?</a></h1>
-<p>You can get a pointer to the module object as follows:</p>
-<pre class="literal-block">
-module = PyImport_ImportModule("<modulename>");
-</pre>
-<p>If the module hasn't been imported yet (i.e. it is not yet present in
-<tt class="docutils literal">sys.modules</tt>), this initializes the module; otherwise it simply returns
-the value of <tt class="docutils literal"><span class="pre">sys.modules["<modulename>"]</span></tt>. Note that it doesn't enter
-the module into any namespace -- it only ensures it has been
-initialized and is stored in <tt class="docutils literal">sys.modules</tt>.</p>
-<p>You can then access the module's attributes (i.e. any name defined in
-the module) as follows:</p>
-<pre class="literal-block">
-attr = PyObject_GetAttrString(module, "<attrname>");
-</pre>
-<p>Calling <tt class="docutils literal">PyObject_SetAttrString()</tt> to assign to variables in the module also works.</p>
-</div>
-<div class="section" id="how-do-i-interface-to-c-objects-from-python">
-<h1><a class="toc-backref" href="#id17">11 How do I interface to C++ objects from Python?</a></h1>
-<p>Depending on your requirements, there are many approaches. To do
-this manually, begin by reading <a class="reference external" href="http://docs.python.org/ext/ext.html">the "Extending and Embedding" document</a>. Realize
-that for the Python run-time system, there isn't a whole lot of
-difference between C and C++ -- so the strategy of building a new Python
-type around a C structure (pointer) type will also work for C++
-objects.</p>
-<p>For C++ libraries, you can look at <a class="reference external" href="http://www.riverbankcomputing.co.uk/sip/">SIP</a>, <a class="reference external" href="http://cxx.sourceforge.net/">CXX</a>, <a class="reference external" href="http://www.boost.org/libs/python/doc/index.html">Boost</a>, or <a class="reference external" href="http://www.scipy.org/site_content/weave">Weave</a>.
-<a class="reference external" href="http://www.swig.org">SWIG</a> is a similar automated tool that only supports C libraries.</p>
-</div>
-<div class="section" id="i-added-a-module-using-the-setup-file-and-the-make-fails-why">
-<h1><a class="toc-backref" href="#id18">12 I added a module using the Setup file and the make fails; why?</a></h1>
-<p>Setup must end in a newline, if there is no newline there, the build
-process fails. (Fixing this requires some ugly shell script hackery,
-and this bug is so minor that it doesn't seem worth the effort.)</p>
-</div>
-<div class="section" id="how-do-i-debug-an-extension">
-<h1><a class="toc-backref" href="#id19">13 How do I debug an extension?</a></h1>
-<p>When using GDB with dynamically loaded extensions, you can't set a
-breakpoint in your extension until your extension is loaded.</p>
-<p>In your <tt class="docutils literal">.gdbinit</tt> file (or interactively), add the command:</p>
-<pre class="literal-block">
-br _PyImport_LoadDynamicModule
-</pre>
-<p>Then, when you run GDB:</p>
-<pre class="literal-block">
-$ gdb /local/bin/python
-gdb) run myscript.py
-gdb) continue # repeat until your extension is loaded
-gdb) finish # so that your extension is loaded
-gdb) br myfunction.c:50
-gdb) continue
-</pre>
-</div>
-<div class="section" id="i-want-to-compile-a-python-module-on-my-linux-system-but-some-files-are-missing-why">
-<h1><a class="toc-backref" href="#id20">14 I want to compile a Python module on my Linux system, but some files are missing. Why?</a></h1>
-<p>Most packaged versions of Python don't include the
-/usr/lib/python2.x/config/ directory, which contains various files required
-for compiling Python extensions.</p>
-<p>For Red Hat, install the python-devel RPM to get the necessary files.</p>
-<p>For Debian, run <tt class="docutils literal"><span class="pre">apt-get</span> install <span class="pre">python-dev</span></tt>.</p>
-</div>
-<div class="section" id="what-does-systemerror-pyimport-fixupextension-module-yourmodule-not-loaded-mean">
-<h1><a class="toc-backref" href="#id21">15 What does "SystemError: _PyImport_FixupExtension: module yourmodule not loaded" mean?</a></h1>
-<p>This means that you have created an extension module named "yourmodule", but your module init function does not initialize with that name.</p>
-<p>Every module init function will have a line similar to:</p>
-<pre class="literal-block">
-module = Py_InitModule("yourmodule", yourmodule_functions);
-</pre>
-<p>If the string passed to this function is not the same name as your
-extenion module, the <tt class="docutils literal">SystemError</tt> exception will be raised.</p>
-</div>
-<div class="section" id="how-do-i-tell-incomplete-input-from-invalid-input">
-<h1><a class="toc-backref" href="#id22">16 How do I tell "incomplete input" from "invalid input"?</a></h1>
-<p>Sometimes you want to emulate the Python interactive interpreter's
-behavior, where it gives you a continuation prompt when the input
-is incomplete (e.g. you typed the start of an "if" statement
-or you didn't close your parentheses or triple string quotes),
-but it gives you a syntax error message immediately when the input
-is invalid.</p>
-<p>In Python you can use the <tt class="docutils literal">codeop</tt> module, which approximates the
-parser's behavior sufficiently. IDLE uses this, for example.</p>
-<p>The easiest way to do it in C is to call <tt class="docutils literal">PyRun_InteractiveLoop()</tt>
-(perhaps in a separate thread) and let the Python interpreter handle
-the input for you. You can also set the <tt class="docutils literal">PyOS_ReadlineFunctionPointer</tt>
-to point at your custom input function. See <tt class="docutils literal">Modules/readline.c</tt> and
-<tt class="docutils literal">Parser/myreadline.c</tt> for more hints.</p>
-<p>However sometimes you have to run the embedded Python interpreter in
-the same thread as your rest application and you can't allow the
-<tt class="docutils literal">PyRun_InteractiveLoop()</tt> to stop while waiting for user input. The
-one solution then is to call <tt class="docutils literal">PyParser_ParseString()</tt> and test for
-<tt class="docutils literal">e.error</tt> equal to <tt class="docutils literal">E_EOF</tt>, which means the input is incomplete).
-Here's a sample code fragment, untested, inspired by code from Alex Farber:</p>
-<pre class="literal-block">
-#include <Python.h>
-#include <node.h>
-#include <errcode.h>
-#include <grammar.h>
-#include <parsetok.h>
-#include <compile.h>
-
-int testcomplete(char *code)
- /* code should end in \n */
- /* return -1 for error, 0 for incomplete, 1 for complete */
-{
- node *n;
- perrdetail e;
-
- n = PyParser_ParseString(code, &_PyParser_Grammar,
- Py_file_input, &e);
- if (n == NULL) {
- if (e.error == E_EOF)
- return 0;
- return -1;
- }
-
- PyNode_Free(n);
- return 1;
-}
-</pre>
-<p>Another solution is trying to compile the received string with
-<tt class="docutils literal">Py_CompileString()</tt>. If it compiles without errors, try to execute the returned
-code object by calling <tt class="docutils literal">PyEval_EvalCode()</tt>. Otherwise save the input for
-later. If the compilation fails, find out if it's an error or just
-more input is required - by extracting the message string from the
-exception tuple and comparing it to the string "unexpected EOF while parsing".
-Here is a complete example using the GNU readline library (you may
-want to ignore SIGINT while calling readline()):</p>
-<pre class="literal-block">
-#include <stdio.h>
-#include <readline.h>
-
-#include <Python.h>
-#include <object.h>
-#include <compile.h>
-#include <eval.h>
-
-int main (int argc, char* argv[])
-{
- int i, j, done = 0; /* lengths of line, code */
- char ps1[] = ">>> ";
- char ps2[] = "... ";
- char *prompt = ps1;
- char *msg, *line, *code = NULL;
- PyObject *src, *glb, *loc;
- PyObject *exc, *val, *trb, *obj, *dum;
-
- Py_Initialize ();
- loc = PyDict_New ();
- glb = PyDict_New ();
- PyDict_SetItemString (glb, "__builtins__", PyEval_GetBuiltins ());
-
- while (!done)
- {
- line = readline (prompt);
-
- if (NULL == line) /* CTRL-D pressed */
- {
- done = 1;
- }
- else
- {
- i = strlen (line);
-
- if (i > 0)
- add_history (line); /* save non-empty lines */
-
- if (NULL == code) /* nothing in code yet */
- j = 0;
- else
- j = strlen (code);
-
- code = realloc (code, i + j + 2);
- if (NULL == code) /* out of memory */
- exit (1);
-
- if (0 == j) /* code was empty, so */
- code[0] = '\0'; /* keep strncat happy */
-
- strncat (code, line, i); /* append line to code */
- code[i + j] = '\n'; /* append '\n' to code */
- code[i + j + 1] = '\0';
-
- src = Py_CompileString (code, "<stdin>", Py_single_input);
-
- if (NULL != src) /* compiled just fine - */
- {
- if (ps1 == prompt || /* ">>> " or */
- '\n' == code[i + j - 1]) /* "... " and double '\n' */
- { /* so execute it */
- dum = PyEval_EvalCode ((PyCodeObject *)src, glb, loc);
- Py_XDECREF (dum);
- Py_XDECREF (src);
- free (code);
- code = NULL;
- if (PyErr_Occurred ())
- PyErr_Print ();
- prompt = ps1;
- }
- } /* syntax error or E_EOF? */
- else if (PyErr_ExceptionMatches (PyExc_SyntaxError))
- {
- PyErr_Fetch (&exc, &val, &trb); /* clears exception! */
-
- if (PyArg_ParseTuple (val, "sO", &msg, &obj) &&
- !strcmp (msg, "unexpected EOF while parsing")) /* E_EOF */
- {
- Py_XDECREF (exc);
- Py_XDECREF (val);
- Py_XDECREF (trb);
- prompt = ps2;
- }
- else /* some other syntax error */
- {
- PyErr_Restore (exc, val, trb);
- PyErr_Print ();
- free (code);
- code = NULL;
- prompt = ps1;
- }
- }
- else /* some non-syntax error */
- {
- PyErr_Print ();
- free (code);
- code = NULL;
- prompt = ps1;
- }
-
- free (line);
- }
- }
-
- Py_XDECREF(glb);
- Py_XDECREF(loc);
- Py_Finalize();
- exit(0);
-}
-</pre>
-</div>
-<div class="section" id="how-do-i-find-undefined-g-symbols-builtin-new-or-pure-virtual">
-<h1><a class="toc-backref" href="#id23">17 How do I find undefined g++ symbols __builtin_new or __pure_virtual?</a></h1>
-<p>To dynamically load g++ extension modules, you must recompile Python, relink it using g++ (change LINKCC in the python Modules Makefile), and link your extension module using g++ (e.g., "g++ -shared -o mymodule.so mymodule.o").</p>
-</div>
-<div class="section" id="can-i-create-an-object-class-with-some-methods-implemented-in-c-and-others-in-python-e-g-through-inheritance">
-<h1><a class="toc-backref" href="#id24">18 Can I create an object class with some methods implemented in C and others in Python (e.g. through inheritance)?</a></h1>
-<p>In Python 2.2, you can inherit from builtin classes such as int, list, dict, etc.</p>
-<p>The Boost Python Library (BPL, <a class="reference external" href="http://www.boost.org/libs/python/doc/index.html">http://www.boost.org/libs/python/doc/index.html</a>)
-provides a way of doing this from C++ (i.e. you can inherit from an
-extension class written in C++ using the BPL).</p>
-</div>
-<div class="section" id="when-importing-module-x-why-do-i-get-undefined-symbol-pyunicodeucs2">
-<h1><a class="toc-backref" href="#id25">19 When importing module X, why do I get "undefined symbol: PyUnicodeUCS2*"?</a></h1>
-<p>You are using a version of Python that uses a 4-byte representation
-for Unicode characters, but some C extension module you are importing
-was compiled using a Python that uses a 2-byte representation for
-Unicode characters (the default).</p>
-<p>If instead the name of the undefined symbol starts with
-<tt class="docutils literal">PyUnicodeUCS4</tt>, the problem is the reverse: Python was built using
-2-byte Unicode characters, and the extension module was compiled using
-a Python with 4-byte Unicode characters.</p>
-<p>This can easily occur when using pre-built extension packages. RedHat
-Linux 7.x, in particular, provided a "python2" binary that is compiled
-with 4-byte Unicode. This only causes the link failure if the extension
-uses any of the <tt class="docutils literal"><span class="pre">PyUnicode_*()</span></tt> functions. It is also a problem if an
-extension uses any of the Unicode-related format specifiers for
-<tt class="docutils literal">Py_BuildValue</tt> (or similar) or parameter specifications for
-<tt class="docutils literal">PyArg_ParseTuple()</tt>.</p>
-<p>You can check the size of the Unicode character a Python interpreter is
-using by checking the value of sys.maxunicode:</p>
-<pre class="literal-block">
->>> import sys
->>> if sys.maxunicode > 65535:
-... print 'UCS4 build'
-... else:
-... print 'UCS2 build'
-</pre>
-<p>The only way to solve this problem is to use extension modules compiled
-with a Python binary built using the same size for Unicode characters.</p>
-</div>
-</div>
-</body>
-</html>
diff --git a/faq/general.ht b/faq/general.ht
deleted file mode 100644
index 751a40f..0000000
--- a/faq/general.ht
+++ /dev/null
@@ -1,1460 +0,0 @@
-Title: General Python FAQ
-Content-type: text/x-rst
-
-====================================
-General Python FAQ
-====================================
-
-:Date: $Date: 2006-02-26 06:15:13 +0100 (Sun, 26 Feb 2006) $
-:Version: $Revision: 8958 $
-:Web site: http://www.python.org/
-
-.. contents::
-.. sectnum::
-
-General Information
-=====================
-
-What is Python?
-----------------------
-
-Python is an interpreted, interactive, object-oriented programming
-language. It incorporates modules, exceptions, dynamic typing, very
-high level dynamic data types, and classes. Python combines
-remarkable power with very clear syntax. It has interfaces to many
-system calls and libraries, as well as to various window systems, and
-is extensible in C or C++. It is also usable as an extension language
-for applications that need a programmable interface. Finally, Python
-is portable: it runs on many Unix variants, on the Mac, and on PCs
-under MS-DOS, Windows, Windows NT, and OS/2.
-
-To find out more, start
-with the `Beginner's Guide to Python <http://www.python.org/moin/BeginnersGuide>`_.
-
-
-Why was Python created in the first place?
---------------------------------------------------
-Here's a *very* brief summary of what started it all, written
-by Guido van Rossum:
-
- I had extensive experience with implementing an interpreted language
- in the ABC group at CWI, and from working with this group I had
- learned a lot about language design. This is the origin of many
- Python features, including the use of indentation for statement
- grouping and the inclusion of very-high-level data types (although the
- details are all different in Python).
-
- I had a number of gripes about the ABC language, but also liked many
- of its features. It was impossible to extend the ABC language (or its
- implementation) to remedy my complaints -- in fact its lack of
- extensibility was one of its biggest problems. I had some experience
- with using Modula-2+ and talked with the designers of Modula-3 and
- read the Modula-3 report. Modula-3 is the origin of the syntax and
- semantics used for exceptions, and some other Python features.
-
- I was working in the Amoeba distributed operating system group at
- CWI. We needed a better way to do system administration than by
- writing either C programs or Bourne shell scripts, since Amoeba had
- its own system call interface which wasn't easily accessible from the
- Bourne shell. My experience with error handling in Amoeba made me
- acutely aware of the importance of exceptions as a programming
- language feature.
-
- It occurred to me that a scripting language with a syntax like ABC
- but with access to the Amoeba system calls would fill the need. I
- realized that it would be foolish to write an Amoeba-specific
- language, so I decided that I needed a language that was generally
- extensible.
-
- During the 1989 Christmas holidays, I had a lot of time on my hand,
- so I decided to give it a try. During the next year, while still
- mostly working on it in my own time, Python was used in the Amoeba
- project with increasing success, and the feedback from colleagues made
- me add many early improvements.
-
- In February 1991, after just over a year of development, I decided
- to post to USENET. The rest is in the Misc/HISTORY file.
-
-
-What is Python good for?
---------------------------------
-Python is a high-level general-purpose programming language
-that can be applied to many different classes of problems.
-
-The language comes with a large standard library that covers areas
-such as string processing (regular expressions, Unicode, calculating
-differences between files), Internet protocols (HTTP, FTP, SMTP,
-XML-RPC, POP, IMAP, CGI programming), software engineering (unit testing,
-logging, profiling, parsing Python code), and operating system
-interfaces (system calls, filesystems, TCP/IP sockets). Look at the
-table of contents for `the Library Reference
-<http://docs.python.org/lib/>`_ to get an idea of what's available.
-A wide variety of third-party extensions are also available.
-Consult `the Python Package Index <http://cheeseshop.python.org/pypi>`_ to find
-packages of interest to you.
-
-
-How does the Python version numbering scheme work?
-----------------------------------------------------------
-Python versions are numbered A.B.C or A.B. A is the major version
-number -- it is only incremented for really major changes in
-the language. B is the minor version number, incremented for less
-earth-shattering changes. C is the micro-level -- it is incremented
-for each bugfix release. See `PEP 6 <../../peps/pep-0006.html>`_
-for more information about bugfix releases.
-
-Not all releases are bugfix releases. In the run-up to a new major
-release, a series of development releases are made, denoted as alpha,
-beta, or release candidate. Alphas are early releases in which
-interfaces aren't yet finalized; it's not unexpected to see an
-interface change between two alpha releases. Betas are more stable,
-preserving existing interfaces but possibly adding new modules, and
-release candidates are frozen, making no changes except as needed to
-fix critical bugs.
-
-Alpha, beta and release candidate versions have an additional
-suffix. The suffix for an alpha version is "aN" for some small
-number N, the suffix for a beta version is "bN" for some small number
-N, and the suffix for a release candidate version is "cN" for some
-small number N. In other words, all versions labeled 2.0aN precede
-the versions labeled 2.0bN, which precede versions labeled 2.0cN, and
-*those* precede 2.0.
-
-You may also find version numbers with a "+" suffix, e.g. "2.2+".
-These are unreleased versions, built directly from the subversion trunk.
-In practice, after a final minor release is made, the subversion trunk is
-incremented to the next minor version, which becomes the "a0" version,
-e.g. "2.4a0".
-
-See also the documentation for ``sys.version``, ``sys.hexversion``, and
-``sys.version_info``.
-
-
-Are there copyright restrictions on the use of Python?
---------------------------------------------------------------
-
-Not really. You can do anything you want with the source, as long as
-you leave the copyrights in and display those copyrights in any
-documentation about Python that you produce. If you honor the
-copyright rules, it's OK to use Python for commercial use, to sell
-copies of Python in source or binary form (modified or unmodified), or
-to sell products that incorporate Python in some form. We would still
-like to know about all commercial use of Python, of course.
-
-See `the PSF license page <../../psf/license.html>`_
-to find further explanations and a link to the full text of the
-license.
-
-
-How do I obtain a copy of the Python source?
----------------------------------------------------
-
-The latest Python source distribution is always available from
-python.org, at http://www.python.org/download/. The latest
-development sources can be obtained via anonymous subversion from
-SourceForge, at http://svn.python.org/projects/python/trunk.
-
-The source distribution is a gzipped tar file containing the complete
-C source, LaTeX documentation, Python library modules, example
-programs, and several useful pieces of freely distributable software.
-This will compile and run out of the box on most UNIX platforms.
-
-Older versions of Python are also available from python.org.
-
-How do I get documentation on Python?
---------------------------------------------
-
-All documentation is available on-line, starting at
-http://www.python.org/doc/.
-
-The standard documentation for the current stable version of Python is
-also available at http://docs.python.org/.
-
-The LaTeX source for the documentation is part of the source
-distribution. If you don't have LaTeX, the latest Python
-documentation set is available by anonymous FTP in various formats
-such as PostScript and HTML. Visit the above URL for links to the
-current versions.
-
-
-I've never programmed before. Is there a Python tutorial?
------------------------------------------------------------------
-
-There are numerous tutorials and books available. Consult `the
-Beginner's Guide <http://www.python.org/moin/BeginnersGuide>`_ to find
-information for beginning Python programmers, including lists of
-tutorials.
-
-Are there other FTP sites that mirror the Python distribution?
----------------------------------------------------------------------
-
-Consult the list of python.org mirrors at http://www.python.org/Mirrors.html.
-
-Is there a newsgroup or mailing list devoted to Python?
---------------------------------------------------------------
-
-There is a newsgroup, comp.lang.python, and a mailing list,
-`python-list <http://mail.python.org/mailman/listinfo/python-list>`_.
-The newsgroup and mailing list are gatewayed into each other -- if you
-can read news it's unnecessary to subscribe to the mailing list.
-comp.lang.python is high-traffic, receiving hundreds of postings every day,
-and Usenet readers are often more able to cope with this volume.
-
-Announcements of new software releases and events can be found in
-comp.lang.python.announce, a low-traffic moderated list that receives
-about five postings per day.
-It's available as
-`the python-announce mailing list <http://mail.python.org/mailman/listinfo/python-announce-list>`_.
-
-More info about other mailing lists and newsgroups
-can be found at http://www.python.org/community/lists.html.
-
-How do I get a beta test version of Python?
----------------------------------------------------
-
-All releases, including alphas, betas and release candidates, are
-announced on the comp.lang.python and comp.lang.python.announce
-newsgroups. All announcements also appear on the Python
-home page, at http://www.python.org/; an RSS feed of news is available.
-
-You can also access the development version of Python through subversion.
-See http://www.python.org/dev/devfaq.html#subversion-svn for details.
-
-How do I submit bug reports and patches for Python?
-----------------------------------------------------------
-
-To report a bug or submit a patch, please use the relevant service
-from the Python project at SourceForge.
-
-Bugs: http://sourceforge.net/tracker/?group_id=5470&atid=105470
-
-Patches: http://sourceforge.net/tracker/?group_id=5470&atid=305470
-
-You must have a SourceForge account to report bugs; this makes it
-possible for us to contact you if we have follow-up questions. It
-will also enable SourceForge to send you updates as we act on your
-bug.
-
-For more information on how Python is developed, consult
-`the Python Developer's Guide <../../dev/>`_.
-
-Are there any published articles about Python that I can reference?
----------------------------------------------------------------------------
-It's probably best to reference your favorite book about Python.
-
-The very first article about Python is this very old article
-that's now quite outdated.
-
- Guido van Rossum and Jelke de Boer, "Interactively Testing Remote
- Servers Using the Python Programming Language", CWI Quarterly, Volume
- 4, Issue 4 (December 1991), Amsterdam, pp 283-303.
-
-
-
-Are there any books on Python?
--------------------------------------
-
-Yes, there are many, and more are being published. See
-the python.org Wiki at http://www.python.org/moin/PythonBooks for a list.
-
-You can also search online bookstores for "Python"
-and filter out the Monty Python references; or
-perhaps search for "Python" and "language".
-
-
-Where in the world is www.python.org located?
------------------------------------------------------
-
-It's currently in Amsterdam, graciously hosted by `XS4ALL
-<http://www.xs4all.nl>`_. Thanks to Thomas Wouters for his work in
-arranging python.org's hosting.
-
-Why is it called Python?
--------------------------------
-
-At the same time he began implementing Python, Guido van Rossum was
-also reading the published scripts from "Monty Python's Flying Circus"
-(a BBC comedy series from the seventies, in the unlikely case you
-didn't know). It occurred to him that he needed a name that was
-short, unique, and slightly mysterious, so he decided to call the
-language Python.
-
-
-
-Do I have to like "Monty Python's Flying Circus"?
--------------------------------------------------------------------
-
-No, but it helps. :)
-
-
-Python in the real world
-============================
-
-How stable is Python?
-----------------------------
-
-Very stable. New, stable releases have been coming out roughly every
-6 to 18 months since 1991, and this seems likely to continue.
-Currently there are usually around 18 months between major releases.
-
-With the introduction of retrospective "bugfix" releases the stability
-of existing releases is being improved. Bugfix releases, indicated by
-a third component of the version number (e.g. 2.1.3, 2.2.2), are
-managed for stability; only fixes for known problems are included in a
-bugfix release, and it's guaranteed that interfaces will remain the
-same throughout a series of bugfix releases.
-
-The `2.4.2 release <../../2.4.2/>`_ is the most stable
-version at this point in time.
-
-
-How many people are using Python?
-----------------------------------------
-
-Probably tens of thousands of users, though it's difficult to obtain
-an exact count. Python is available for free download, so there are
-no sales figures, and it's available from many different sites and
-packaged with many Linux distributions, so download statistics don't
-tell the whole story either. The comp.lang.python newsgroup is very
-active, but not all Python users post to the group or even read it.
-Overall there is no accurate estimate of the number of subscribers or
-Python users.
-
-Have any significant projects been done in Python?
----------------------------------------------------------
-
-See http://www.pythonology.org/success for a list of projects that
-use Python. Consulting the proceedings for `past Python conferences
-<../../workshops/>`_ will reveal contributions from
-many different companies and organizations.
-
-High-profile Python projects include `the Mailman mailing list manager
-<http://www.list.org>`_ and `the Zope application server
-<http://www.zope.org>`_. Several Linux distributions, most
-notably `Red Hat <http://www.redhat.com>`_, have written part or all
-of their installer and system administration software in Python. Companies
-that use Python internally include Google,
-Yahoo, and Industrial Light & Magic.
-
-
-What new developments are expected for Python in the future?
--------------------------------------------------------------------
-
-See http://www.python.org/peps for the Python Enhancement Proposals
-(PEPs). PEPs are design documents describing a suggested new feature
-for Python, providing a concise technical specification and a
-rationale.
-`PEP 1 <../../peps/pep-0001.html>`_
-explains the PEP process and PEP format; read it
-first if you want to submit a PEP.
-
-New developments are discussed on `the python-dev mailing list <http://mail.python.org/mailman/listinfo/python-dev/>`_.
-
-
-Is it reasonable to propose incompatible changes to Python?
-------------------------------------------------------------------
-
-In general, no. There are already millions of lines of Python code
-around the world, so any change in the language that invalidates more
-than a very small fraction of existing programs has to be frowned
-upon. Even if you can provide a conversion program, there still is
-the problem of updating all documentation; many books have been
-written about Python, and we don't want to invalidate them all at a
-single stroke.
-
-Providing a gradual upgrade path is necessary if a feature has to be
-changed. `PEP 5 <../../peps/pep-0005.html>`_
-describes the procedure followed for introducing backward-incompatible
-changes while minimizing disruption for users.
-
-
-What is the Python Software Foundation?
------------------------------------------
-
-The Python Software Foundation is an independent non-profit
-organization that holds the copyright on Python versions 2.1 and
-newer. The PSF's mission is to advance open source technology related
-to the Python programming language and to publicize the use of
-Python. The PSF's home page is at http://www.python.org/psf/.
-
-Donations to the PSF are tax-exempt in the US. If you use Python and
-find it helpful, please contribute via `the PSF donation page
-<../../psf/donations.html>`_.
-
-
-
-Is Python Y2K (Year 2000) Compliant?
---------------------------------------------
-As of August, 2003 no major problems have been reported and Y2K
-compliance seems to be a non-issue.
-
-Python does very few date calculations and for those it does perform relies
-on the C library functions. Python generally represents times either
-as seconds since 1970 or as a ``(year, month, day, ...)`` tuple where the
-year is expressed with four digits, which makes Y2K bugs unlikely. So
-as long as your C library is okay, Python should be okay. Of course,
-it's possible that a particular application written in Python
-makes assumptions about 2-digit years.
-
-Because Python is available free of charge, there are no absolute
-guarantees. If there *are* unforseen problems, liability is the
-user's problem rather than the developers', and there is nobody you can sue
-for damages. The Python copyright notice contains the following
-disclaimer:
-
- 4. PSF is making Python 2.3 available to Licensee on an "AS IS"
- basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
- IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
- DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
- FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.3 WILL NOT
- INFRINGE ANY THIRD PARTY RIGHTS.
-
- 5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
- 2.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
- A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.3,
- OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
-
-The good news is that *if* you encounter a problem, you have full
-source available to track it down and fix it. This is one advantage of
-an open source programming environment.
-
-
-Is Python a good language for beginning programmers?
------------------------------------------------------------------------
-
-Yes. If you want to discuss Python's use in education, then you may
-be interested in joining `the edu-sig mailing list <../../sigs/edu-sig>`_.
-
-It is still common to start students with a procedural (subset of a)
-statically typed language such as Pascal, C, or a subset of C++ or
-Java. Students may be better served by learning Python as their first
-language. Python has a very simple and consistent syntax and a large
-standard library and, most importantly, using Python in a beginning
-programming course permits students to concentrate on important
-programming skills such as problem decomposition and data type design.
-With Python, students can be quickly introduced to basic concepts such
-as loops and procedures. They can even probably work with
-user-defined objects in their very first course.
-
-For a student who has never programmed before, using a statically
-typed language seems unnatural. It presents additional complexity
-that the student must master and slows the pace of the course. The
-students are trying to learn to think like a computer, decompose
-problems, design consistent interfaces, and encapsulate data. While
-learning to use a statically typed language is important in the long
-term, it is not necessarily the best topic to address in the students'
-first programming course.
-
-Many other aspects of Python make it a good first language.
-Like Java, Python has a large standard library so that
-students can be assigned programming projects very early in the
-course that *do* something. Assignments aren't restricted to the
-standard four-function calculator and check balancing programs.
-By using the standard library, students can gain the satisfaction
-of working on realistic applications as they learn the fundamentals
-of programming. Using the standard library also teaches students
-about code reuse. Third-party modules such as PyGame are also helpful in
-extending the students' reach.
-
-Python's interactive interpreter enables students to
-test language features while they're programming. They can keep
-a window with the interpreter running while they enter their
-program's source in another window. If they can't remember the
-methods for a list, they can do something like this::
-
- >>> L = []
- >>> dir(L)
- ['append', 'count', 'extend', 'index', 'insert', 'pop', 'remove',
- 'reverse', 'sort']
- >>> help(L.append)
- Help on built-in function append:
-
- append(...)
- L.append(object) -- append object to end
- >>> L.append(1)
- >>> L
- [1]
-
-With the interpreter, documentation is never far from the
-student as he's programming.
-
-There are also good IDEs for Python. IDLE is a cross-platform IDE for
-Python that is written in Python using Tkinter. PythonWin is a
-Windows-specific IDE. Emacs users will be happy to know that there is
-a very good Python mode for Emacs. All of these programming
-environments provide syntax highlighting, auto-indenting, and access
-to the interactive interpreter while coding. Consult
-http://www.python.org/editors/ for a full list of Python editing
-environments.
-
-
-
-Upgrading Python
-=====================
-
-What is this bsddb185 module my application keeps complaining about?
---------------------------------------------------------------------
-
-Starting with Python2.3, the distribution includes the `PyBSDDB package
-<http://pybsddb.sf.net/>` as a replacement for the old bsddb module. It
-includes functions which provide backward compatibility at the API level,
-but requires a newer version of the underlying `Berkeley DB
-<http://www.sleepycat.com>`_ library. Files created with the older bsddb
-module can't be opened directly using the new module.
-
-Using your old version of Python and a pair of scripts which are part of
-Python 2.3 (db2pickle.py and pickle2db.py, in the Tools/scripts directory)
-you can convert your old database files to the new format. Using your old
-Python version, run the db2pickle.py script to convert it to a pickle,
-e.g.::
-
- python2.2 <pathto>/db2pickley.py database.db database.pck
-
-Rename your database file::
-
- mv database.db olddatabase.db
-
-Now convert the pickle file to a new format database::
-
- python2.3 <pathto>/pickle2db.py database.db database.pck
-
-The precise commands you use will vary depending on the particulars of your
-installation. For full details about operation of these two scripts check
-the doc string at the start of each one.
-
-
-Python's Design
-=====================
-
-Why does Python use indentation for grouping of statements?
------------------------------------------------------------
-
-Guido van Rossum believes that using indentation for grouping is extremely elegant
-and contributes a lot to the clarity of the average Python program. Most
-people learn to love this feature after awhile.
-
-Since there are no begin/end brackets there cannot be a disagreement between
-grouping perceived by the parser and the human reader. Occasionally C
-programmers will encounter a fragment of code like this::
-
- if (x <= y)
- x++;
- y--;
- z++;
-
-Only the ``x++`` statement is executed if the condition is true, but
-the indentation leads you to believe otherwise.
-Even experienced C programmers will sometimes
-stare a long time at it wondering why y is being decremented even for
-``x > y``.
-
-Because there are no begin/end brackets, Python is much less prone to
-coding-style conflicts. In C there are many different ways to place the
-braces. If you're used to reading
-and writing code that uses one style, you will feel at least slightly
-uneasy when reading (or being required to write) another style.
-
-Many coding styles place begin/end brackets on a line by themself. This
-makes programs considerably longer and wastes valuable screen space, making
-it harder to get a good overview of a program. Ideally, a function should
-fit on onescreen (say, 20-30 lines). 20 lines of Python can do
-a lot more work than 20 lines of C. This is not solely due to the lack of
-begin/end brackets -- the lack of declarations and the high-level data types
-are also responsible -- but the indentation-based syntax certainly helps.
-
-
-Why am I getting strange results with simple arithmetic operations?
--------------------------------------------------------------------
-
-See the next question.
-
-Why are floating point calculations so inaccurate?
---------------------------------------------------
-
-People are often very surprised by results like this::
-
- >>> 1.2-1.0
- 0.199999999999999996
-
-and think it is a bug in Python. It's not. It's a problem caused by
-the internal representation of floating point numbers, which uses a
-fixed number of binary digits to represent a decimal number. Some
-decimal numbers can't be represented exactly in binary, resulting in
-small roundoff errors.
-
-In decimal math, there are many numbers that can't be represented with a
-fixed number of decimal digits, e.g. 1/3 = 0.3333333333.......
-
-In base 2, 1/2 = 0.1, 1/4 = 0.01, 1/8 = 0.001, etc.
-.2 equals 2/10 equals 1/5, resulting in the binary fractional number
-0.001100110011001...
-
-Floating point numbers only have 32 or 64 bits of precision, so the digits are cut off at some point,
-and the resulting number is 0.199999999999999996 in decimal, not 0.2.
-
-A floating point's ``repr()`` function prints as many digits are
-necessary to make ``eval(repr(f)) == f`` true for any float f. The
-``str()`` function prints fewer digits and this often results in the
-more sensible number that was probably intended::
-
- >>> 0.2
- 0.20000000000000001
- >>> print 0.2
- 0.2
-
-Again, this has nothing to do with Python, but with the way the underlying C
-platform handles floating point numbers, and ultimately with the inaccuracy
-you'll always have when writing down numbers as a string of a fixed number
-of digits.
-
-One of the consequences of this is that it is dangerous to compare the
-result of some computation to a float with == ! Tiny inaccuracies may mean
-that == fails.
-Instead, you have to check that the difference between the
-two numbers is less than a certain threshold::
-
- epsilon = 0.0000000000001 # Tiny allowed error
- expected_result = 0.4
-
- if expected_result-epsilon <= computation() <= expected_result+epsilon:
- ...
-
-Please see the chapter on
-`floating point arithmetic <http://docs.python.org/tut/node16.html>`_
-in the Python tutorial for more information.
-
-
-Why are Python strings immutable?
----------------------------------
-
-There are several advantages.
-
-One is performance: knowing that a string is
-immutable makes it easy to lay it out at construction time -- fixed and
-unchanging storage requirements. This is also one of the reasons for the
-distinction between tuples and lists.
-
-The other is that strings in Python are considered as "elemental" as
-numbers. No amount of activity will change the value 8 to anything
-else, and in Python, no amount of activity will change the string
-"eight" to anything else.
-
-
-Why must 'self' be used explicitly in method definitions and calls?
--------------------------------------------------------------------
-
-The idea was borrowed from Modula-3. It turns out to be very useful,
-for a variety of reasons.
-
-First, it's more obvious that you are using a method or instance
-attribute instead of a local variable. Reading ``self.x`` or ``self.meth()``
-makes it absolutely clear that an instance variable or method is used even
-if you don't know the class definition by heart. In C++, you can sort of
-tell by the lack of a local variable declaration (assuming globals are rare
-or easily recognizable) -- but in Python, there are no local variable
-declarations, so you'd have to look up the class definition to be sure.
-Some C++ and Java coding standards call for instance attributes to have an
-``m_`` prefix, so this explicitness is still useful in those languages, too.
-
-Second, it means that no special syntax is necessary if you want to
-explicitly reference or call the method from a particular class. In C++, if
-you want to use a method from a base class which is overridden in a derived
-class, you have to use the :: operator -- in Python you can write
-baseclass.methodname(self, <argument list>). This is particularly useful
-for __init__() methods, and in general in cases where a derived class method
-wants to extend the base class method of the same name and thus has to call
-the base class method somehow.
-
-Finally, for instance variables it solves a syntactic problem with
-assignment: since local variables in Python are (by definition!) those
-variables to which a value assigned in a function body (and that aren't
-explicitly declared global), there has to be some way to tell the
-interpreter that an assignment was meant to assign to an instance variable
-instead of to a local variable, and it should preferably be syntactic (for
-efficiency reasons). C++ does this through declarations, but Python doesn't
-have declarations and it would be a pity having to introduce them just for
-this purpose. Using the explicit "self.var" solves this nicely. Similarly,
-for using instance variables, having to write "self.var" means that
-references to unqualified names inside a method don't have to search the
-instance's directories. To put it another way, local variables and
-instance variables live in two different namespaces, and you need to
-tell Python which namespace to use.
-
-
-Why can't I use an assignment in an expression?
--------------------------------------------------------
-
-Many people used to C or Perl complain that they want to
-use this C idiom::
-
- while (line = readline(f)) {
- ...do something with line...
- }
-
-where in Python you're forced to write this::
-
- while True:
- line = f.readline()
- if not line:
- break
- ...do something with line...
-
-The reason for not allowing assignment in Python expressions
-is a common, hard-to-find bug in those other languages,
-caused by this construct::
-
- if (x = 0) {
- ...error handling...
- }
- else {
- ...code that only works for nonzero x...
- }
-
-The error is a simple typo: ``x = 0``, which assigns 0 to the variable ``x``,
-was written while the comparison ``x == 0`` is certainly what was intended.
-
-Many alternatives have been proposed. Most are hacks that save some
-typing but use arbitrary or cryptic syntax or keywords,
-and fail the simple criterion for language change proposals:
-it should intuitively suggest the proper meaning to a human reader
-who has not yet been introduced to the construct.
-
-An interesting phenomenon is that most experienced Python programmers
-recognize the "while True" idiom and don't seem to be missing the
-assignment in expression construct much; it's only newcomers
-who express a strong desire to add this to the language.
-
-There's an alternative way of spelling this that seems
-attractive but is generally less robust than the "while True" solution::
-
- line = f.readline()
- while line:
- ...do something with line...
- line = f.readline()
-
-The problem with this is that if you change your mind about exactly
-how you get the next line (e.g. you want to change it into
-``sys.stdin.readline()``) you have to remember to change two places in
-your program -- the second occurrence is hidden at the bottom of the
-loop.
-
-The best approach is to use iterators, making it possible to loop
-through objects using the ``for`` statement. For example, in the
-current version of Python file objects support the iterator protocol, so you
-can now write simply::
-
- for line in f:
- ... do something with line...
-
-
-
-Why does Python use methods for some functionality (e.g. list.index()) but functions for other (e.g. len(list))?
-----------------------------------------------------------------------------------------------------------------
-
-The major reason is history. Functions were used for those operations
-that were generic for a group of types and which were intended to work
-even for objects that didn't have methods at all (e.g. tuples). It is
-also convenient to have a function that can readily be applied to an
-amorphous collection of objects when you use the functional features
-of Python (``map()``, ``apply()`` et al).
-
-In fact, implementing ``len()``, ``max()``, ``min()`` as a built-in
-function is actually less code than implementing them as methods for
-each type. One can quibble about individual cases but it's a part of
-Python, and it's too late to make such fundamental changes now. The
-functions have to remain to avoid massive code breakage.
-
-Note that for string operations Python has moved from external functions
-(the ``string`` module) to methods. However, ``len()`` is still a function.
-
-Why is join() a string method instead of a list or tuple method?
-----------------------------------------------------------------
-
-Strings became much more like other standard types starting in Python
-1.6, when methods were added which give the same functionality that
-has always been available using the functions of the string module.
-Most of these new methods have been widely accepted, but the one which
-appears to make some programmers feel uncomfortable is::
-
- ", ".join(['1', '2', '4', '8', '16'])
-
-which gives the result::
-
- "1, 2, 4, 8, 16"
-
-There are two usual arguments against this usage.
-
-The first runs along the lines of: "It looks really ugly using a method of a
-string literal (string constant)", to which the answer is that it might, but
-a string literal is just a fixed value. If the methods are to be allowed on
-names bound to strings there is no logical reason to make them unavailable
-on literals.
-
-The second objection is typically cast as: "I am really telling a sequence
-to join its members together with a string constant". Sadly, you aren't. For
-some reason there seems to be much less difficulty with having split() as a
-string method, since in that case it is easy to see that ::
-
- "1, 2, 4, 8, 16".split(", ")
-
-is an instruction to a string literal to return the substrings delimited by
-the given separator (or, by default, arbitrary runs of white space). In this
-case a Unicode string returns a list of Unicode strings, an ASCII string
-returns a list of ASCII strings, and everyone is happy.
-
-join() is a string method because in using it you are telling the separator
-string to iterate over an arbitrary sequence, forming string representations
-of each of the elements, and inserting itself between the elements'
-representations. This method can be used with any argument which obeys the
-rules for sequence objects, inluding any new classes you might define
-yourself.
-
-Because this is a string method it can work for Unicode strings as well as
-plain ASCII strings. If join() were a method of the sequence types then the
-sequence types would have to decide which type of string to return depending
-on the type of the separator.
-
-If none of these arguments persuade you, then for the moment you can
-continue to use the join() function from the string module, which allows you
-to write ::
-
- string.join(['1', '2', '4', '8', '16'], ", ")
-
-
-How fast are exceptions?
-------------------------
-
-A try/except block is extremely efficient. Actually executing an exception
-is expensive. In versions of Python prior to 2.0 it was common to use this
-idiom::
-
- try:
- value = dict[key]
- except KeyError:
- dict[key] = getvalue(key)
- value = dict[key]
-
-This only made sense when you expected the dict to have the key almost all
-the time. If that wasn't the case, you coded it like this::
-
- if dict.has_key(key):
- value = dict[key]
- else:
- dict[key] = getvalue(key)
- value = dict[key]
-
-(In Python 2.0 and higher, you can code this as
-``value = dict.setdefault(key, getvalue(key))``.)
-
-
-Why isn't there a switch or case statement in Python?
------------------------------------------------------
-
-You can do this easily enough with a sequence of ``if... elif... elif... else``.
-There have been some proposals for switch statement syntax, but there is no
-consensus (yet) on whether and how to do range tests. See `PEP 275
-<../../peps/pep-0275.html>`_ for complete details and
-the current status.
-
-For cases where you need to choose from a very large number of
-possibilities, you can create a dictionary mapping case values to
-functions to call. For example::
-
- def function_1 (...):
- ...
-
- functions = {'a': function_1,
- 'b': function_2,
- 'c': self.method_1, ...}
-
- func = functions[value]
- func()
-
-For calling methods on objects, you can simplify yet further by using
-the ``getattr()`` built-in to retrieve methods with a particular name::
-
- def visit_a (self, ...):
- ...
- ...
-
- def dispatch (self, value):
- method_name = 'visit_' + str(value)
- method = getattr(self, method_name)
- method()
-
-It's suggested that you use a prefix for the method names, such as
-``visit_`` in this example. Without such a prefix, if values are coming
-from an untrusted source, an attacker would be able to call any method
-on your object.
-
-
-Can't you emulate threads in the interpreter instead of relying on an OS-specific thread implementation?
---------------------------------------------------------------------------------------------------------
-
-Answer 1: Unfortunately, the interpreter pushes at least one C stack frame
-for each Python stack frame. Also, extensions can call back into Python at
-almost random moments. Therefore, a complete threads implementation
-requires thread support for C.
-
-Answer 2: Fortunately, there is `Stackless Python
-<http://www.stackless.com>`_, which has a completely redesigned interpreter
-loop that avoids the C stack. It's still experimental but looks very
-promising. Although it is binary compatible with standard Python, it's
-still unclear whether Stackless will make it into the core -- maybe it's
-just too revolutionary.
-
-
-Why can't lambda forms contain statements?
-------------------------------------------
-
-Python lambda forms cannot contain statements because Python's syntactic
-framework can't handle statements nested inside expressions. However, in
-Python, this is not a serious problem. Unlike lambda forms in other
-languages, where they add functionality, Python lambdas are only a shorthand
-notation if you're too lazy to define a function.
-
-Functions are already first class objects in Python, and can be declared in
-a local scope. Therefore the only advantage of using a lambda form instead
-of a locally-defined function is that you don't need to invent a name for
-the function -- but that's just a local variable to which the function
-object (which is exactly the same type of object that a lambda form yields)
-is assigned!
-
-
-Can Python be compiled to machine code, C or some other language?
------------------------------------------------------------------
-
-Not easily. Python's high level data types, dynamic typing of objects and
-run-time invocation of the interpreter (using ``eval()`` or ``exec``) together mean
-that a "compiled" Python program would probably consist mostly of calls into
-the Python run-time system, even for seemingly simple operations like
-``x+1``.
-
-Several projects described in the Python newsgroup or at past `Python
-conferences <../../workshops/>`_ have shown that this
-approach is feasible, although the speedups reached so far are only
-modest (e.g. 2x). Jython uses the same strategy for compiling to Java
-bytecode. (Jim Hugunin has demonstrated that in combination with
-whole-program analysis, speedups of 1000x are feasible for small demo
-programs. See the proceedings from the `1997 Python conference
-<../../workshops/1997-10/proceedings/>`_ for more
-information.)
-
-Internally, Python source code is always translated into a bytecode
-representation, and this bytecode is then executed by the Python
-virtual machine. In order to avoid the overhead of repeatedly parsing
-and translating modules that rarely change, this byte code is written
-into a file whose name ends in ".pyc" whenever a module is parsed.
-When the corresponding .py file is changed, it is parsed and
-translated again and the .pyc file is rewritten.
-
-There is no performance difference once the .pyc file has been loaded,
-as the bytecode read from the .pyc file is exactly the same as the
-bytecode created by direct translation. The only difference is that
-loading code from a .pyc file is faster than parsing and translating a
-.py file, so the presence of precompiled .pyc files improves the
-start-up time of Python scripts. If desired, the Lib/compileall.py
-module can be used to create valid .pyc files for a given set of
-modules.
-
-Note that the main script executed by Python, even if its filename
-ends in .py, is not compiled to a .pyc file. It is compiled to
-bytecode, but the bytecode is not saved to a file. Usually main
-scripts are quite short, so this doesn't cost much speed.
-
-There are also several programs which make it easier to intermingle
-Python and C code in various ways to increase performance. See, for
-example, `Psyco <http://psyco.sourceforge.net/>`_,
-`Pyrex <http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/>`_, `PyInline
-<http://pyinline.sourceforge.net/>`_, `Py2Cmod
-<http://sourceforge.net/projects/py2cmod/>`_, and `Weave
-<http://www.scipy.org/site_content/weave>`_.
-
-
-How does Python manage memory?
-------------------------------
-
-The details of Python memory management depend on the implementation.
-The standard C implementation of Python uses reference counting to
-detect inaccessible objects, and another mechanism to collect
-reference cycles, periodically executing a cycle detection algorithm
-which looks for inaccessible cycles and deletes the objects
-involved. The ``gc`` module provides functions to perform a garbage
-collection, obtain debugging statistics, and tune the collector's
-parameters.
-
-Jython relies on the Java runtime so the JVM's garbage collector is
-used. This difference can cause some subtle porting problems if your
-Python code depends on the behavior of the reference counting
-implementation.
-
-Sometimes objects get stuck in tracebacks temporarily and hence are not
-deallocated when you might expect. Clear the tracebacks with::
-
- import sys
- sys.exc_clear()
- sys.exc_traceback = sys.last_traceback = None
-
-Tracebacks are used for reporting errors, implementing debuggers and related
-things. They contain a portion of the program state extracted during the
-handling of an exception (usually the most recent exception).
-
-In the absence of circularities and tracebacks, Python programs need
-not explicitly manage memory.
-
-Why doesn't Python use a more traditional garbage collection scheme?
-For one thing, this is not a C standard feature and hence it's not
-portable. (Yes, we know about the Boehm GC library. It has bits of
-assembler code for *most* common platforms, not for all of them, and
-although it is mostly transparent, it isn't completely transparent;
-patches are required to get Python to work with it.)
-
-Traditional GC also becomes a problem when Python is embedded into other
-applications. While in a standalone Python it's fine to replace the
-standard malloc() and free() with versions provided by the GC library, an
-application embedding Python may want to have its *own* substitute for
-malloc() and free(), and may not want Python's. Right now, Python works
-with anything that implements malloc() and free() properly.
-
-In Jython, the following code (which is fine in CPython) will probably run
-out of file descriptors long before it runs out of memory::
-
- for file in <very long list of files>:
- f = open(file)
- c = f.read(1)
-
-Using the current reference counting and destructor scheme, each new
-assignment to f closes the previous file. Using GC, this is not
-guaranteed. If you want to write code that will work with any Python
-implementation, you should explicitly close the file; this will work
-regardless of GC::
-
- for file in <very long list of files>:
- f = open(file)
- c = f.read(1)
- f.close()
-
-
-Why isn't all memory freed when Python exits?
------------------------------------------------------
-
-Objects referenced from the global namespaces of
-Python modules are not always deallocated when Python exits.
-This may happen if there are circular references. There are also
-certain bits of memory that are allocated by the C library that are
-impossible to free (e.g. a tool like Purify will complain about
-these). Python is, however, aggressive about cleaning up memory on
-exit and does try to destroy every single object.
-
-If you want to force Python to delete certain things on deallocation
-use the ``sys.exitfunc()`` hook to run a function that will force
-those deletions.
-
-
-Why are there separate tuple and list data types?
--------------------------------------------------
-
-Lists and tuples, while similar in many respects, are generally used
-in fundamentally different ways. Tuples can be thought of as being
-similar to Pascal records or C structs; they're small collections of
-related data which may be of different types which are operated on as
-a group. For example, a Cartesian coordinate is appropriately
-represented as a tuple of two or three numbers.
-
-Lists, on the other hand, are more like arrays in other languages. They
-tend to hold a varying number of objects all of which have the same type and
-which are operated on one-by-one. For example, ``os.listdir('.')`` returns
-a list of strings representing the files in the current directory.
-Functions which operate on this output would generally not break if you
-added another file or two to the directory.
-
-Tuples are immutable, meaning that once a tuple has been created, you
-can't replace any of its elements with a new value. Lists are
-mutable, meaning that you can always change a list's elements. Only
-immutable elements can be used as dictionary keys, and hence only
-tuples and not lists can be used as keys.
-
-
-How are lists implemented?
---------------------------
-
-Python's lists are really variable-length arrays, not Lisp-style
-linked lists. The implementation uses a contiguous array of
-references to other objects, and keeps a pointer to this array and the
-array's length in a list head structure.
-
-This makes indexing a list ``a[i]`` an operation whose cost is independent of
-the size of the list or the value of the index.
-
-When items are appended or inserted, the array of references is resized.
-Some cleverness is applied to improve the performance of appending items
-repeatedly; when the array must be grown, some extra space is allocated so
-the next few times don't require an actual resize.
-
-
-How are dictionaries implemented?
------------------------------------------
-Python's dictionaries are implemented as resizable hash tables.
-Compared to B-trees, this gives better performance for lookup
-(the most common operation by far) under most circumstances,
-and the implementation is simpler.
-
-Dictionaries work by computing a hash code for each key stored in the
-dictionary using the ``hash()`` built-in function. The hash code
-varies widely depending on the key; for example, "Python" hashes to
--539294296 while "python", a string that differs by a single bit,
-hashes to 1142331976. The hash code is then used to calculate a
-location in an internal array where the value will be stored.
-Assuming that you're storing keys that all have different hash values,
-this means that dictionaries take constant time -- O(1), in computer
-science notation -- to retrieve a key. It also means that no sorted
-order of the keys is maintained, and traversing the array as the
-``.keys()`` and ``.items()`` do will output the dictionary's content
-in some arbitrary jumbled order.
-
-
-Why must dictionary keys be immutable?
-----------------------------------------------
-
-The hash table implementation of dictionaries uses a hash value
-calculated from the key value to find the key. If the key were a
-mutable object, its value could change, and thus its hash could also
-change. But since whoever changes the key object can't tell that it
-was being used as a dictionary key, it can't move the entry around in the
-dictionary. Then, when you try to look up the same object in the
-dictionary it won't be found because its hash value is different.
-If you tried to look up the old value it wouldn't be found either, because
-the value of the object found in that hash bin would be different.
-
-If you want a dictionary indexed with a list, simply convert the list
-to a tuple first; the function ``tuple(L)`` creates a tuple with the
-same entries as the list ``L``. Tuples are immutable and can
-therefore be used as dictionary keys.
-
-Some unacceptable solutions that have been proposed:
-
-- Hash lists by their address (object ID). This doesn't work because
- if you construct a new list with the same value it won't be found;
- e.g.::
-
- d = {[1,2]: '12'}
- print d[[1,2]]
-
- would raise a KeyError exception because the id of the ``[1,2]`` used in
- the second line differs from that in the first line. In other
- words, dictionary keys should be compared using ``==``, not using
- 'is'.
-
-- Make a copy when using a list as a key. This doesn't work because
- the list, being a mutable object, could contain a reference to
- itself, and then the copying code would run into an infinite loop.
-
-- Allow lists as keys but tell the user not to modify them. This
- would allow a class of hard-to-track bugs in programs when you forgot
- or modified a list by accident. It also
- invalidates an important invariant of
- dictionaries: every value in ``d.keys()`` is usable as a key of the
- dictionary.
-
-- Mark lists as read-only once they are used as a dictionary key. The
- problem is that it's not just the top-level object that could change
- its value; you could use a tuple containing a list as a key.
- Entering anything as a key into a dictionary would require marking
- all objects reachable from there as read-only -- and again,
- self-referential objects could cause an infinite loop.
-
-There is a trick to get around this if you need to, but
-use it at your own risk: You
-can wrap a mutable structure inside a class instance which
-has both a __cmp__ and a __hash__ method.
-You must then make sure that the hash value for all such wrapper objects
-that reside in a dictionary (or other hash based structure), remain
-fixed while the object is in the dictionary (or other structure).::
-
- class ListWrapper:
- def __init__(self, the_list):
- self.the_list = the_list
- def __cmp__(self, other):
- return self.the_list == other.the_list
- def __hash__(self):
- l = self.the_list
- result = 98767 - len(l)*555
- for i in range(len(l)):
- try:
- result = result + (hash(l[i]) % 9999999) * 1001 + i
- except:
- result = (result % 7777777) + i * 333
- return result
-
-Note that the hash computation is complicated by the
-possibility that some members of the list may be unhashable
-and also by the possibility of arithmetic overflow.
-
-Furthermore it must always be the case that if
-``o1 == o2`` (ie ``o1.__cmp__(o2)==0``) then ``hash(o1)==hash(o2)``
-(ie, ``o1.__hash__() == o2.__hash__()``), regardless of whether
-the object is in a dictionary or not.
-If you fail to meet these restrictions dictionaries and other
-hash based structures will misbehave.
-
-In the case of ListWrapper, whenever the wrapper
-object is in a dictionary the wrapped list must not change
-to avoid anomalies. Don't do this unless you are prepared
-to think hard about the requirements and the consequences
-of not meeting them correctly. Consider yourself warned.
-
-
-Why doesn't list.sort() return the sorted list?
--------------------------------------------------------
-
-In situations where performance matters, making a copy
-of the list just to sort it would be wasteful. Therefore,
-list.sort() sorts the list in place. In order to remind you
-of that fact, it does not return the sorted list. This way,
-you won't be fooled into accidentally overwriting a list
-when you need a sorted copy but also need to keep the
-unsorted version around.
-
-In Python 2.4 a new builtin - sorted() - has been added.
-This function creates a new list from a passed
-iterable, sorts it and returns it.
-
-As a result, here's the idiom to iterate over the keys of a
-dictionary in sorted order::
-
- for key in sorted(dict.iterkeys()):
- ...do whatever with dict[key]...
-
-Versions of Python prior to 2.4 need to use the following idiom::
-
- keys = dict.keys()
- keys.sort()
- for key in keys:
- ...do whatever with dict[key]...
-
-How do you specify and enforce an interface spec in Python?
--------------------------------------------------------------------
-
-An interface specification for a module as provided by languages such
-as C++ and Java describes the prototypes for the methods and functions
-of the module. Many feel that compile-time enforcement of interface
-specifications help in the construction of large programs. Python
-does not support interface specifications directly, but many of their
-advantages can be obtained by an appropriate test discipline for
-components, which can often be very easily accomplished in Python.
-There is also a tool, PyChecker, which can be used to find problems
-due to subclassing.
-
-A good test suite for a module can at once provide a regression test
-and serve as both a module interface specification and a set of
-examples. Many Python modules can be run as a script to provide a
-simple "self test." Even modules which use complex external
-interfaces can often be tested in isolation using trivial "stub"
-emulations of the external interface. The ``doctest`` and
-``unittest`` modules or third-party test frameworks can be used to construct
-exhaustive test suites that exercise every line of code in a module.
-
-An appropriate testing discipline can help build large complex
-applications in Python as well as having interface specifications
-would. In fact, it can be better because an interface specification
-cannot test certain properties of a program. For example, the
-``append()`` method is expected to add new elements to the end of some
-internal list; an interface specification cannot test that your
-``append()`` implementation will actually do this correctly, but it's
-trivial to check this property in a test suite.
-
-Writing test suites is very helpful, and you might want to design your
-code with an eye to making it easily tested. One increasingly popular
-technique, test-directed development, calls for writing parts of the
-test suite first, before you write any of the actual code. Of course
-Python allows you to be sloppy and not write test cases at all.
-
-
-Why are default values shared between objects?
-----------------------------------------------------------------
-
-This type of bug commonly bites neophyte programmers. Consider this function::
-
- def foo(D={}): # Danger: shared reference to one dict for all calls
- ... compute something ...
- D[key] = value
- return D
-
-The first time you call this function, ``D`` contains a single item.
-The second time, ``D`` contains two items because when ``foo()`` begins executing,
-``D`` starts out with an item already in it.
-
-It is often expected that a function call creates new objects for
-default values. This is not what happens. Default values are created
-exactly once, when the function is defined. If that object is
-changed, like the dictionary in this example, subsequent calls to the
-function will refer to this changed object.
-
-By definition, immutable objects such as numbers, strings, tuples, and
-``None``, are safe from change. Changes to mutable objects such as
-dictionaries, lists, and class instances can lead to confusion.
-
-Because of this feature, it is good programming practice to not use mutable
-objects as default values. Instead, use ``None`` as the default value
-and inside the function, check if the parameter is ``None`` and create a new list/dictionary/whatever
-if it is. For example, don't write::
-
- def foo(dict={}):
- ...
-
-but::
-
- def foo(dict=None):
- if dict is None:
- dict = {} # create a new dict for local namespace
-
-This feature can be useful. When you have a function that's time-consuming to compute,
-a common technique is to cache the parameters and the resulting value of each
-call to the function, and return the cached value if the same value is requested again.
-This is called "memoizing", and can be implemented like this::
-
- # Callers will never provide a third parameter for this function.
- def expensive (arg1, arg2, _cache={}):
- if _cache.has_key((arg1, arg2)):
- return _cache[(arg1, arg2)]
-
- # Calculate the value
- result = ... expensive computation ...
- _cache[(arg1, arg2)] = result # Store result in the cache
- return result
-
-You could use a global variable containing a dictionary instead of
-the default value; it's a matter of taste.
-
-Why is there no goto?
-------------------------
-
-You can use exceptions to provide a "structured goto"
-that even works across function calls. Many feel that exceptions
-can conveniently emulate all reasonable uses of the "go" or "goto"
-constructs of C, Fortran, and other languages. For example::
-
- class label: pass # declare a label
-
- try:
- ...
- if (condition): raise label() # goto label
- ...
- except label: # where to goto
- pass
- ...
-
-This doesn't allow you to jump into the middle of a loop, but
-that's usually considered an abuse of goto anyway. Use sparingly.
-
-
-Why do I get a SyntaxError for a 'continue' inside a 'try'?
--------------------------------------------------------------------
-
-This is an implementation limitation, caused by the extremely
-simple-minded way Python generates bytecode. The ``try`` block pushes
-something on the "block stack" which the ``continue`` would have to pop
-off again. The current code generator doesn't have the data
-structures around so that ``continue`` can generate the right code.
-
-Note that Jython doesn't have this restriction!
-
-
-Why can't raw strings (r-strings) end with a backslash?
----------------------------------------------------------------
-More precisely, they can't end with an odd number of backslashes:
-the unpaired backslash at the end escapes the closing quote character,
-leaving an unterminated string.
-
-Raw strings were designed to ease creating input for processors
-(chiefly regular expression engines) that want to do their own
-backslash escape processing. Such processors consider an unmatched
-trailing backslash to be an error anyway, so raw strings disallow
-that. In return, they allow you to pass on the string quote character
-by escaping it with a backslash. These rules work well when r-strings
-are used for their intended purpose.
-
-If you're trying to build Windows pathnames, note that all Windows
-system calls accept forward slashes too::
-
- f = open("/mydir/file.txt") # works fine!
-
-If you're trying to build a pathname for a DOS command, try e.g. one of ::
-
- dir = r"\this\is\my\dos\dir" "\\"
- dir = r"\this\is\my\dos\dir\ "[:-1]
- dir = "\\this\\is\\my\\dos\\dir\\"
-
-
-Why doesn't Python have a "with" statement like some other languages?
----------------------------------------------------------------------------------------
-Because such a construct would be ambiguous.
-
-Some languages, such as Object Pascal, Delphi, and C++, use static
-types. So it is possible to know, in an unambiguous way, what member
-is being assigned in a "with" clause. This is the main point - the
-compiler *always* knows the scope of every variable at compile time.
-
-Python uses dynamic types. It is impossible to know in advance which
-attribute will be referenced at runtime. Member attributes may be
-added or removed from objects on the fly. This would make it
-impossible to know, from a simple reading, what attribute is being
-referenced - a local one, a global one, or a member attribute.
-
-For instance, take the following incomplete snippet::
-
- def foo(a):
- with a:
- print x
-
-The snippet assumes that "a" must have a member attribute called "x".
-However, there is nothing in Python that guarantees that. What should
-happen if "a" is, let us say, an integer? And if I have a global
-variable named "x", will it end up being used inside the with block?
-As you see, the dynamic nature of Python makes such choices much
-harder.
-
-The primary benefit of "with" and similar language features (reduction
-of code volume) can, however, easily be achieved in Python by
-assignment. Instead of::
-
- function(args).dict[index][index].a = 21
- function(args).dict[index][index].b = 42
- function(args).dict[index][index].c = 63
-
-write this::
-
- ref = function(args).dict[index][index]
- ref.a = 21
- ref.b = 42
- ref.c = 63
-
-This also has the side-effect of increasing execution speed because
-name bindings are resolved at run-time in Python, and the second
-version only needs to perform the resolution once. If the referenced
-object does not have a, b and c attributes, of course, the end result
-is still a run-time exception.
-
-
-Why are colons required for the if/while/def/class statements?
---------------------------------------------------------------------
-
-The colon is required primarily to enhance readability (one of the
-results of the experimental ABC language). Consider this::
-
- if a==b
- print a
-
-versus ::
-
- if a==b:
- print a
-
-Notice how the second one is slightly easier to read. Notice further how
-a colon sets off the example in the second line of this FAQ answer; it's
-a standard usage in English.
-
-Another minor reason is that the colon makes it easier for editors
-with syntax highlighting; they can look for colons to decide when
-indentation needs to be increased instead of having to do a more
-elaborate parsing of the program text.
diff --git a/faq/general.html b/faq/general.html
deleted file mode 100644
index d1c2300..0000000
--- a/faq/general.html
+++ /dev/null
@@ -1,1675 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
-<title>General Python FAQ</title>
-<meta name="date" content="2006-02-26" />
-<style type="text/css">
-
-/*
-:Author: David Goodger (goodger@python.org)
-:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
- border: 0 }
-
-table.borderless td, table.borderless th {
- /* Override padding for "table.docutils td" with "! important".
- The right padding separates the table cells. */
- padding: 0 0.5em 0 0 ! important }
-
-.first {
- /* Override more specific margin styles with "! important". */
- margin-top: 0 ! important }
-
-.last, .with-subtitle {
- margin-bottom: 0 ! important }
-
-.hidden {
- display: none }
-
-a.toc-backref {
- text-decoration: none ;
- color: black }
-
-blockquote.epigraph {
- margin: 2em 5em ; }
-
-dl.docutils dd {
- margin-bottom: 0.5em }
-
-object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
- overflow: hidden;
-}
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
- font-weight: bold }
-*/
-
-div.abstract {
- margin: 2em 5em }
-
-div.abstract p.topic-title {
- font-weight: bold ;
- text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
- margin: 2em ;
- border: medium outset ;
- padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title, .code .error {
- color: red ;
- font-weight: bold ;
- font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
- compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
- margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
- margin-top: 0.5em }
-*/
-
-div.dedication {
- margin: 2em 5em ;
- text-align: center ;
- font-style: italic }
-
-div.dedication p.topic-title {
- font-weight: bold ;
- font-style: normal }
-
-div.figure {
- margin-left: 2em ;
- margin-right: 2em }
-
-div.footer, div.header {
- clear: both;
- font-size: smaller }
-
-div.line-block {
- display: block ;
- margin-top: 1em ;
- margin-bottom: 1em }
-
-div.line-block div.line-block {
- margin-top: 0 ;
- margin-bottom: 0 ;
- margin-left: 1.5em }
-
-div.sidebar {
- margin: 0 0 0.5em 1em ;
- border: medium outset ;
- padding: 1em ;
- background-color: #ffffee ;
- width: 40% ;
- float: right ;
- clear: right }
-
-div.sidebar p.rubric {
- font-family: sans-serif ;
- font-size: medium }
-
-div.system-messages {
- margin: 5em }
-
-div.system-messages h1 {
- color: red }
-
-div.system-message {
- border: medium outset ;
- padding: 1em }
-
-div.system-message p.system-message-title {
- color: red ;
- font-weight: bold }
-
-div.topic {
- margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
- margin-top: 0.4em }
-
-h1.title {
- text-align: center }
-
-h2.subtitle {
- text-align: center }
-
-hr.docutils {
- width: 75% }
-
-img.align-left, .figure.align-left, object.align-left {
- clear: left ;
- float: left ;
- margin-right: 1em }
-
-img.align-right, .figure.align-right, object.align-right {
- clear: right ;
- float: right ;
- margin-left: 1em }
-
-img.align-center, .figure.align-center, object.align-center {
- display: block;
- margin-left: auto;
- margin-right: auto;
-}
-
-.align-left {
- text-align: left }
-
-.align-center {
- clear: both ;
- text-align: center }
-
-.align-right {
- text-align: right }
-
-/* reset inner alignment in figures */
-div.align-right {
- text-align: inherit }
-
-/* div.align-center * { */
-/* text-align: left } */
-
-ol.simple, ul.simple {
- margin-bottom: 1em }
-
-ol.arabic {
- list-style: decimal }
-
-ol.loweralpha {
- list-style: lower-alpha }
-
-ol.upperalpha {
- list-style: upper-alpha }
-
-ol.lowerroman {
- list-style: lower-roman }
-
-ol.upperroman {
- list-style: upper-roman }
-
-p.attribution {
- text-align: right ;
- margin-left: 50% }
-
-p.caption {
- font-style: italic }
-
-p.credits {
- font-style: italic ;
- font-size: smaller }
-
-p.label {
- white-space: nowrap }
-
-p.rubric {
- font-weight: bold ;
- font-size: larger ;
- color: maroon ;
- text-align: center }
-
-p.sidebar-title {
- font-family: sans-serif ;
- font-weight: bold ;
- font-size: larger }
-
-p.sidebar-subtitle {
- font-family: sans-serif ;
- font-weight: bold }
-
-p.topic-title {
- font-weight: bold }
-
-pre.address {
- margin-bottom: 0 ;
- margin-top: 0 ;
- font: inherit }
-
-pre.literal-block, pre.doctest-block, pre.math, pre.code {
- margin-left: 2em ;
- margin-right: 2em }
-
-pre.code .ln { color: grey; } /* line numbers */
-pre.code, code { background-color: #eeeeee }
-pre.code .comment, code .comment { color: #5C6576 }
-pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
-pre.code .literal.string, code .literal.string { color: #0C5404 }
-pre.code .name.builtin, code .name.builtin { color: #352B84 }
-pre.code .deleted, code .deleted { background-color: #DEB0A1}
-pre.code .inserted, code .inserted { background-color: #A3D289}
-
-span.classifier {
- font-family: sans-serif ;
- font-style: oblique }
-
-span.classifier-delimiter {
- font-family: sans-serif ;
- font-weight: bold }
-
-span.interpreted {
- font-family: sans-serif }
-
-span.option {
- white-space: nowrap }
-
-span.pre {
- white-space: pre }
-
-span.problematic {
- color: red }
-
-span.section-subtitle {
- /* font-size relative to parent (h1..h6 element) */
- font-size: 80% }
-
-table.citation {
- border-left: solid 1px gray;
- margin-left: 1px }
-
-table.docinfo {
- margin: 2em 4em }
-
-table.docutils {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
-
-table.footnote {
- border-left: solid 1px black;
- margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
- padding-left: 0.5em ;
- padding-right: 0.5em ;
- vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
- font-weight: bold ;
- text-align: left ;
- white-space: nowrap ;
- padding-left: 0 }
-
-/* "booktabs" style (no vertical lines) */
-table.docutils.booktabs {
- border: 0px;
- border-top: 2px solid;
- border-bottom: 2px solid;
- border-collapse: collapse;
-}
-table.docutils.booktabs * {
- border: 0px;
-}
-table.docutils.booktabs th {
- border-bottom: thin solid;
- text-align: left;
-}
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
- font-size: 100% }
-
-ul.auto-toc {
- list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="general-python-faq">
-<h1 class="title">General Python FAQ</h1>
-<table class="docinfo" frame="void" rules="none">
-<col class="docinfo-name" />
-<col class="docinfo-content" />
-<tbody valign="top">
-<tr><th class="docinfo-name">Date:</th>
-<td>2006-02-26</td></tr>
-<tr><th class="docinfo-name">Version:</th>
-<td>8958</td></tr>
-<tr class="field"><th class="docinfo-name">Web site:</th><td class="field-body"><a class="reference external" href="http://www.python.org/">http://www.python.org/</a></td>
-</tr>
-</tbody>
-</table>
-<div class="contents topic" id="contents">
-<p class="topic-title first">Contents</p>
-<ul class="auto-toc simple">
-<li><a class="reference internal" href="#general-information" id="id1">1 General Information</a><ul class="auto-toc">
-<li><a class="reference internal" href="#what-is-python" id="id2">1.1 What is Python?</a></li>
-<li><a class="reference internal" href="#why-was-python-created-in-the-first-place" id="id3">1.2 Why was Python created in the first place?</a></li>
-<li><a class="reference internal" href="#what-is-python-good-for" id="id4">1.3 What is Python good for?</a></li>
-<li><a class="reference internal" href="#how-does-the-python-version-numbering-scheme-work" id="id5">1.4 How does the Python version numbering scheme work?</a></li>
-<li><a class="reference internal" href="#are-there-copyright-restrictions-on-the-use-of-python" id="id6">1.5 Are there copyright restrictions on the use of Python?</a></li>
-<li><a class="reference internal" href="#how-do-i-obtain-a-copy-of-the-python-source" id="id7">1.6 How do I obtain a copy of the Python source?</a></li>
-<li><a class="reference internal" href="#how-do-i-get-documentation-on-python" id="id8">1.7 How do I get documentation on Python?</a></li>
-<li><a class="reference internal" href="#i-ve-never-programmed-before-is-there-a-python-tutorial" id="id9">1.8 I've never programmed before. Is there a Python tutorial?</a></li>
-<li><a class="reference internal" href="#are-there-other-ftp-sites-that-mirror-the-python-distribution" id="id10">1.9 Are there other FTP sites that mirror the Python distribution?</a></li>
-<li><a class="reference internal" href="#is-there-a-newsgroup-or-mailing-list-devoted-to-python" id="id11">1.10 Is there a newsgroup or mailing list devoted to Python?</a></li>
-<li><a class="reference internal" href="#how-do-i-get-a-beta-test-version-of-python" id="id12">1.11 How do I get a beta test version of Python?</a></li>
-<li><a class="reference internal" href="#how-do-i-submit-bug-reports-and-patches-for-python" id="id13">1.12 How do I submit bug reports and patches for Python?</a></li>
-<li><a class="reference internal" href="#are-there-any-published-articles-about-python-that-i-can-reference" id="id14">1.13 Are there any published articles about Python that I can reference?</a></li>
-<li><a class="reference internal" href="#are-there-any-books-on-python" id="id15">1.14 Are there any books on Python?</a></li>
-<li><a class="reference internal" href="#where-in-the-world-is-www-python-org-located" id="id16">1.15 Where in the world is www.python.org located?</a></li>
-<li><a class="reference internal" href="#why-is-it-called-python" id="id17">1.16 Why is it called Python?</a></li>
-<li><a class="reference internal" href="#do-i-have-to-like-monty-python-s-flying-circus" id="id18">1.17 Do I have to like "Monty Python's Flying Circus"?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#python-in-the-real-world" id="id19">2 Python in the real world</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-stable-is-python" id="id20">2.1 How stable is Python?</a></li>
-<li><a class="reference internal" href="#how-many-people-are-using-python" id="id21">2.2 How many people are using Python?</a></li>
-<li><a class="reference internal" href="#have-any-significant-projects-been-done-in-python" id="id22">2.3 Have any significant projects been done in Python?</a></li>
-<li><a class="reference internal" href="#what-new-developments-are-expected-for-python-in-the-future" id="id23">2.4 What new developments are expected for Python in the future?</a></li>
-<li><a class="reference internal" href="#is-it-reasonable-to-propose-incompatible-changes-to-python" id="id24">2.5 Is it reasonable to propose incompatible changes to Python?</a></li>
-<li><a class="reference internal" href="#what-is-the-python-software-foundation" id="id25">2.6 What is the Python Software Foundation?</a></li>
-<li><a class="reference internal" href="#is-python-y2k-year-2000-compliant" id="id26">2.7 Is Python Y2K (Year 2000) Compliant?</a></li>
-<li><a class="reference internal" href="#is-python-a-good-language-for-beginning-programmers" id="id27">2.8 Is Python a good language for beginning programmers?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#upgrading-python" id="id28">3 Upgrading Python</a><ul class="auto-toc">
-<li><a class="reference internal" href="#what-is-this-bsddb185-module-my-application-keeps-complaining-about" id="id29">3.1 What is this bsddb185 module my application keeps complaining about?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#python-s-design" id="id30">4 Python's Design</a><ul class="auto-toc">
-<li><a class="reference internal" href="#why-does-python-use-indentation-for-grouping-of-statements" id="id31">4.1 Why does Python use indentation for grouping of statements?</a></li>
-<li><a class="reference internal" href="#why-am-i-getting-strange-results-with-simple-arithmetic-operations" id="id32">4.2 Why am I getting strange results with simple arithmetic operations?</a></li>
-<li><a class="reference internal" href="#why-are-floating-point-calculations-so-inaccurate" id="id33">4.3 Why are floating point calculations so inaccurate?</a></li>
-<li><a class="reference internal" href="#why-are-python-strings-immutable" id="id34">4.4 Why are Python strings immutable?</a></li>
-<li><a class="reference internal" href="#why-must-self-be-used-explicitly-in-method-definitions-and-calls" id="id35">4.5 Why must 'self' be used explicitly in method definitions and calls?</a></li>
-<li><a class="reference internal" href="#why-can-t-i-use-an-assignment-in-an-expression" id="id36">4.6 Why can't I use an assignment in an expression?</a></li>
-<li><a class="reference internal" href="#why-does-python-use-methods-for-some-functionality-e-g-list-index-but-functions-for-other-e-g-len-list" id="id37">4.7 Why does Python use methods for some functionality (e.g. list.index()) but functions for other (e.g. len(list))?</a></li>
-<li><a class="reference internal" href="#why-is-join-a-string-method-instead-of-a-list-or-tuple-method" id="id38">4.8 Why is join() a string method instead of a list or tuple method?</a></li>
-<li><a class="reference internal" href="#how-fast-are-exceptions" id="id39">4.9 How fast are exceptions?</a></li>
-<li><a class="reference internal" href="#why-isn-t-there-a-switch-or-case-statement-in-python" id="id40">4.10 Why isn't there a switch or case statement in Python?</a></li>
-<li><a class="reference internal" href="#can-t-you-emulate-threads-in-the-interpreter-instead-of-relying-on-an-os-specific-thread-implementation" id="id41">4.11 Can't you emulate threads in the interpreter instead of relying on an OS-specific thread implementation?</a></li>
-<li><a class="reference internal" href="#why-can-t-lambda-forms-contain-statements" id="id42">4.12 Why can't lambda forms contain statements?</a></li>
-<li><a class="reference internal" href="#can-python-be-compiled-to-machine-code-c-or-some-other-language" id="id43">4.13 Can Python be compiled to machine code, C or some other language?</a></li>
-<li><a class="reference internal" href="#how-does-python-manage-memory" id="id44">4.14 How does Python manage memory?</a></li>
-<li><a class="reference internal" href="#why-isn-t-all-memory-freed-when-python-exits" id="id45">4.15 Why isn't all memory freed when Python exits?</a></li>
-<li><a class="reference internal" href="#why-are-there-separate-tuple-and-list-data-types" id="id46">4.16 Why are there separate tuple and list data types?</a></li>
-<li><a class="reference internal" href="#how-are-lists-implemented" id="id47">4.17 How are lists implemented?</a></li>
-<li><a class="reference internal" href="#how-are-dictionaries-implemented" id="id48">4.18 How are dictionaries implemented?</a></li>
-<li><a class="reference internal" href="#why-must-dictionary-keys-be-immutable" id="id49">4.19 Why must dictionary keys be immutable?</a></li>
-<li><a class="reference internal" href="#why-doesn-t-list-sort-return-the-sorted-list" id="id50">4.20 Why doesn't list.sort() return the sorted list?</a></li>
-<li><a class="reference internal" href="#how-do-you-specify-and-enforce-an-interface-spec-in-python" id="id51">4.21 How do you specify and enforce an interface spec in Python?</a></li>
-<li><a class="reference internal" href="#why-are-default-values-shared-between-objects" id="id52">4.22 Why are default values shared between objects?</a></li>
-<li><a class="reference internal" href="#why-is-there-no-goto" id="id53">4.23 Why is there no goto?</a></li>
-<li><a class="reference internal" href="#why-do-i-get-a-syntaxerror-for-a-continue-inside-a-try" id="id54">4.24 Why do I get a SyntaxError for a 'continue' inside a 'try'?</a></li>
-<li><a class="reference internal" href="#why-can-t-raw-strings-r-strings-end-with-a-backslash" id="id55">4.25 Why can't raw strings (r-strings) end with a backslash?</a></li>
-<li><a class="reference internal" href="#why-doesn-t-python-have-a-with-statement-like-some-other-languages" id="id56">4.26 Why doesn't Python have a "with" statement like some other languages?</a></li>
-<li><a class="reference internal" href="#why-are-colons-required-for-the-if-while-def-class-statements" id="id57">4.27 Why are colons required for the if/while/def/class statements?</a></li>
-</ul>
-</li>
-</ul>
-</div>
-<div class="section" id="general-information">
-<h1><a class="toc-backref" href="#id1">1 General Information</a></h1>
-<div class="section" id="what-is-python">
-<h2><a class="toc-backref" href="#id2">1.1 What is Python?</a></h2>
-<p>Python is an interpreted, interactive, object-oriented programming
-language. It incorporates modules, exceptions, dynamic typing, very
-high level dynamic data types, and classes. Python combines
-remarkable power with very clear syntax. It has interfaces to many
-system calls and libraries, as well as to various window systems, and
-is extensible in C or C++. It is also usable as an extension language
-for applications that need a programmable interface. Finally, Python
-is portable: it runs on many Unix variants, on the Mac, and on PCs
-under MS-DOS, Windows, Windows NT, and OS/2.</p>
-<p>To find out more, start
-with the <a class="reference external" href="http://www.python.org/moin/BeginnersGuide">Beginner's Guide to Python</a>.</p>
-</div>
-<div class="section" id="why-was-python-created-in-the-first-place">
-<h2><a class="toc-backref" href="#id3">1.2 Why was Python created in the first place?</a></h2>
-<p>Here's a <em>very</em> brief summary of what started it all, written
-by Guido van Rossum:</p>
-<blockquote>
-<p>I had extensive experience with implementing an interpreted language
-in the ABC group at CWI, and from working with this group I had
-learned a lot about language design. This is the origin of many
-Python features, including the use of indentation for statement
-grouping and the inclusion of very-high-level data types (although the
-details are all different in Python).</p>
-<p>I had a number of gripes about the ABC language, but also liked many
-of its features. It was impossible to extend the ABC language (or its
-implementation) to remedy my complaints -- in fact its lack of
-extensibility was one of its biggest problems. I had some experience
-with using Modula-2+ and talked with the designers of Modula-3 and
-read the Modula-3 report. Modula-3 is the origin of the syntax and
-semantics used for exceptions, and some other Python features.</p>
-<p>I was working in the Amoeba distributed operating system group at
-CWI. We needed a better way to do system administration than by
-writing either C programs or Bourne shell scripts, since Amoeba had
-its own system call interface which wasn't easily accessible from the
-Bourne shell. My experience with error handling in Amoeba made me
-acutely aware of the importance of exceptions as a programming
-language feature.</p>
-<p>It occurred to me that a scripting language with a syntax like ABC
-but with access to the Amoeba system calls would fill the need. I
-realized that it would be foolish to write an Amoeba-specific
-language, so I decided that I needed a language that was generally
-extensible.</p>
-<p>During the 1989 Christmas holidays, I had a lot of time on my hand,
-so I decided to give it a try. During the next year, while still
-mostly working on it in my own time, Python was used in the Amoeba
-project with increasing success, and the feedback from colleagues made
-me add many early improvements.</p>
-<p>In February 1991, after just over a year of development, I decided
-to post to USENET. The rest is in the Misc/HISTORY file.</p>
-</blockquote>
-</div>
-<div class="section" id="what-is-python-good-for">
-<h2><a class="toc-backref" href="#id4">1.3 What is Python good for?</a></h2>
-<p>Python is a high-level general-purpose programming language
-that can be applied to many different classes of problems.</p>
-<p>The language comes with a large standard library that covers areas
-such as string processing (regular expressions, Unicode, calculating
-differences between files), Internet protocols (HTTP, FTP, SMTP,
-XML-RPC, POP, IMAP, CGI programming), software engineering (unit testing,
-logging, profiling, parsing Python code), and operating system
-interfaces (system calls, filesystems, TCP/IP sockets). Look at the
-table of contents for <a class="reference external" href="http://docs.python.org/lib/">the Library Reference</a> to get an idea of what's available.
-A wide variety of third-party extensions are also available.
-Consult <a class="reference external" href="http://cheeseshop.python.org/pypi">the Python Package Index</a> to find
-packages of interest to you.</p>
-</div>
-<div class="section" id="how-does-the-python-version-numbering-scheme-work">
-<h2><a class="toc-backref" href="#id5">1.4 How does the Python version numbering scheme work?</a></h2>
-<p>Python versions are numbered A.B.C or A.B. A is the major version
-number -- it is only incremented for really major changes in
-the language. B is the minor version number, incremented for less
-earth-shattering changes. C is the micro-level -- it is incremented
-for each bugfix release. See <a class="reference external" href="../../peps/pep-0006.html">PEP 6</a>
-for more information about bugfix releases.</p>
-<p>Not all releases are bugfix releases. In the run-up to a new major
-release, a series of development releases are made, denoted as alpha,
-beta, or release candidate. Alphas are early releases in which
-interfaces aren't yet finalized; it's not unexpected to see an
-interface change between two alpha releases. Betas are more stable,
-preserving existing interfaces but possibly adding new modules, and
-release candidates are frozen, making no changes except as needed to
-fix critical bugs.</p>
-<p>Alpha, beta and release candidate versions have an additional
-suffix. The suffix for an alpha version is "aN" for some small
-number N, the suffix for a beta version is "bN" for some small number
-N, and the suffix for a release candidate version is "cN" for some
-small number N. In other words, all versions labeled 2.0aN precede
-the versions labeled 2.0bN, which precede versions labeled 2.0cN, and
-<em>those</em> precede 2.0.</p>
-<p>You may also find version numbers with a "+" suffix, e.g. "2.2+".
-These are unreleased versions, built directly from the subversion trunk.
-In practice, after a final minor release is made, the subversion trunk is
-incremented to the next minor version, which becomes the "a0" version,
-e.g. "2.4a0".</p>
-<p>See also the documentation for <tt class="docutils literal">sys.version</tt>, <tt class="docutils literal">sys.hexversion</tt>, and
-<tt class="docutils literal">sys.version_info</tt>.</p>
-</div>
-<div class="section" id="are-there-copyright-restrictions-on-the-use-of-python">
-<h2><a class="toc-backref" href="#id6">1.5 Are there copyright restrictions on the use of Python?</a></h2>
-<p>Not really. You can do anything you want with the source, as long as
-you leave the copyrights in and display those copyrights in any
-documentation about Python that you produce. If you honor the
-copyright rules, it's OK to use Python for commercial use, to sell
-copies of Python in source or binary form (modified or unmodified), or
-to sell products that incorporate Python in some form. We would still
-like to know about all commercial use of Python, of course.</p>
-<p>See <a class="reference external" href="../../psf/license.html">the PSF license page</a>
-to find further explanations and a link to the full text of the
-license.</p>
-</div>
-<div class="section" id="how-do-i-obtain-a-copy-of-the-python-source">
-<h2><a class="toc-backref" href="#id7">1.6 How do I obtain a copy of the Python source?</a></h2>
-<p>The latest Python source distribution is always available from
-python.org, at <a class="reference external" href="http://www.python.org/download/">http://www.python.org/download/</a>. The latest
-development sources can be obtained via anonymous subversion from
-SourceForge, at <a class="reference external" href="http://svn.python.org/projects/python/trunk">http://svn.python.org/projects/python/trunk</a>.</p>
-<p>The source distribution is a gzipped tar file containing the complete
-C source, LaTeX documentation, Python library modules, example
-programs, and several useful pieces of freely distributable software.
-This will compile and run out of the box on most UNIX platforms.</p>
-<p>Older versions of Python are also available from python.org.</p>
-</div>
-<div class="section" id="how-do-i-get-documentation-on-python">
-<h2><a class="toc-backref" href="#id8">1.7 How do I get documentation on Python?</a></h2>
-<p>All documentation is available on-line, starting at
-<a class="reference external" href="http://www.python.org/doc/">http://www.python.org/doc/</a>.</p>
-<p>The standard documentation for the current stable version of Python is
-also available at <a class="reference external" href="http://docs.python.org/">http://docs.python.org/</a>.</p>
-<p>The LaTeX source for the documentation is part of the source
-distribution. If you don't have LaTeX, the latest Python
-documentation set is available by anonymous FTP in various formats
-such as PostScript and HTML. Visit the above URL for links to the
-current versions.</p>
-</div>
-<div class="section" id="i-ve-never-programmed-before-is-there-a-python-tutorial">
-<h2><a class="toc-backref" href="#id9">1.8 I've never programmed before. Is there a Python tutorial?</a></h2>
-<p>There are numerous tutorials and books available. Consult <a class="reference external" href="http://www.python.org/moin/BeginnersGuide">the
-Beginner's Guide</a> to find
-information for beginning Python programmers, including lists of
-tutorials.</p>
-</div>
-<div class="section" id="are-there-other-ftp-sites-that-mirror-the-python-distribution">
-<h2><a class="toc-backref" href="#id10">1.9 Are there other FTP sites that mirror the Python distribution?</a></h2>
-<p>Consult the list of python.org mirrors at <a class="reference external" href="http://www.python.org/Mirrors.html">http://www.python.org/Mirrors.html</a>.</p>
-</div>
-<div class="section" id="is-there-a-newsgroup-or-mailing-list-devoted-to-python">
-<h2><a class="toc-backref" href="#id11">1.10 Is there a newsgroup or mailing list devoted to Python?</a></h2>
-<p>There is a newsgroup, comp.lang.python, and a mailing list,
-<a class="reference external" href="http://mail.python.org/mailman/listinfo/python-list">python-list</a>.
-The newsgroup and mailing list are gatewayed into each other -- if you
-can read news it's unnecessary to subscribe to the mailing list.
-comp.lang.python is high-traffic, receiving hundreds of postings every day,
-and Usenet readers are often more able to cope with this volume.</p>
-<p>Announcements of new software releases and events can be found in
-comp.lang.python.announce, a low-traffic moderated list that receives
-about five postings per day.
-It's available as
-<a class="reference external" href="http://mail.python.org/mailman/listinfo/python-announce-list">the python-announce mailing list</a>.</p>
-<p>More info about other mailing lists and newsgroups
-can be found at <a class="reference external" href="http://www.python.org/community/lists.html">http://www.python.org/community/lists.html</a>.</p>
-</div>
-<div class="section" id="how-do-i-get-a-beta-test-version-of-python">
-<h2><a class="toc-backref" href="#id12">1.11 How do I get a beta test version of Python?</a></h2>
-<p>All releases, including alphas, betas and release candidates, are
-announced on the comp.lang.python and comp.lang.python.announce
-newsgroups. All announcements also appear on the Python
-home page, at <a class="reference external" href="http://www.python.org/">http://www.python.org/</a>; an RSS feed of news is available.</p>
-<p>You can also access the development version of Python through subversion.
-See <a class="reference external" href="http://www.python.org/dev/devfaq.html#subversion-svn">http://www.python.org/dev/devfaq.html#subversion-svn</a> for details.</p>
-</div>
-<div class="section" id="how-do-i-submit-bug-reports-and-patches-for-python">
-<h2><a class="toc-backref" href="#id13">1.12 How do I submit bug reports and patches for Python?</a></h2>
-<p>To report a bug or submit a patch, please use the relevant service
-from the Python project at SourceForge.</p>
-<p>Bugs: <a class="reference external" href="http://sourceforge.net/tracker/?group_id=5470&atid=105470">http://sourceforge.net/tracker/?group_id=5470&atid=105470</a></p>
-<p>Patches: <a class="reference external" href="http://sourceforge.net/tracker/?group_id=5470&atid=305470">http://sourceforge.net/tracker/?group_id=5470&atid=305470</a></p>
-<p>You must have a SourceForge account to report bugs; this makes it
-possible for us to contact you if we have follow-up questions. It
-will also enable SourceForge to send you updates as we act on your
-bug.</p>
-<p>For more information on how Python is developed, consult
-<a class="reference external" href="../../dev/">the Python Developer's Guide</a>.</p>
-</div>
-<div class="section" id="are-there-any-published-articles-about-python-that-i-can-reference">
-<h2><a class="toc-backref" href="#id14">1.13 Are there any published articles about Python that I can reference?</a></h2>
-<p>It's probably best to reference your favorite book about Python.</p>
-<p>The very first article about Python is this very old article
-that's now quite outdated.</p>
-<blockquote>
-Guido van Rossum and Jelke de Boer, "Interactively Testing Remote
-Servers Using the Python Programming Language", CWI Quarterly, Volume
-4, Issue 4 (December 1991), Amsterdam, pp 283-303.</blockquote>
-</div>
-<div class="section" id="are-there-any-books-on-python">
-<h2><a class="toc-backref" href="#id15">1.14 Are there any books on Python?</a></h2>
-<p>Yes, there are many, and more are being published. See
-the python.org Wiki at <a class="reference external" href="http://www.python.org/moin/PythonBooks">http://www.python.org/moin/PythonBooks</a> for a list.</p>
-<p>You can also search online bookstores for "Python"
-and filter out the Monty Python references; or
-perhaps search for "Python" and "language".</p>
-</div>
-<div class="section" id="where-in-the-world-is-www-python-org-located">
-<h2><a class="toc-backref" href="#id16">1.15 Where in the world is www.python.org located?</a></h2>
-<p>It's currently in Amsterdam, graciously hosted by <a class="reference external" href="http://www.xs4all.nl">XS4ALL</a>. Thanks to Thomas Wouters for his work in
-arranging python.org's hosting.</p>
-</div>
-<div class="section" id="why-is-it-called-python">
-<h2><a class="toc-backref" href="#id17">1.16 Why is it called Python?</a></h2>
-<p>At the same time he began implementing Python, Guido van Rossum was
-also reading the published scripts from "Monty Python's Flying Circus"
-(a BBC comedy series from the seventies, in the unlikely case you
-didn't know). It occurred to him that he needed a name that was
-short, unique, and slightly mysterious, so he decided to call the
-language Python.</p>
-</div>
-<div class="section" id="do-i-have-to-like-monty-python-s-flying-circus">
-<h2><a class="toc-backref" href="#id18">1.17 Do I have to like "Monty Python's Flying Circus"?</a></h2>
-<p>No, but it helps. :)</p>
-</div>
-</div>
-<div class="section" id="python-in-the-real-world">
-<h1><a class="toc-backref" href="#id19">2 Python in the real world</a></h1>
-<div class="section" id="how-stable-is-python">
-<h2><a class="toc-backref" href="#id20">2.1 How stable is Python?</a></h2>
-<p>Very stable. New, stable releases have been coming out roughly every
-6 to 18 months since 1991, and this seems likely to continue.
-Currently there are usually around 18 months between major releases.</p>
-<p>With the introduction of retrospective "bugfix" releases the stability
-of existing releases is being improved. Bugfix releases, indicated by
-a third component of the version number (e.g. 2.1.3, 2.2.2), are
-managed for stability; only fixes for known problems are included in a
-bugfix release, and it's guaranteed that interfaces will remain the
-same throughout a series of bugfix releases.</p>
-<p>The <a class="reference external" href="../../2.4.2/">2.4.2 release</a> is the most stable
-version at this point in time.</p>
-</div>
-<div class="section" id="how-many-people-are-using-python">
-<h2><a class="toc-backref" href="#id21">2.2 How many people are using Python?</a></h2>
-<p>Probably tens of thousands of users, though it's difficult to obtain
-an exact count. Python is available for free download, so there are
-no sales figures, and it's available from many different sites and
-packaged with many Linux distributions, so download statistics don't
-tell the whole story either. The comp.lang.python newsgroup is very
-active, but not all Python users post to the group or even read it.
-Overall there is no accurate estimate of the number of subscribers or
-Python users.</p>
-</div>
-<div class="section" id="have-any-significant-projects-been-done-in-python">
-<h2><a class="toc-backref" href="#id22">2.3 Have any significant projects been done in Python?</a></h2>
-<p>See <a class="reference external" href="http://www.pythonology.org/success">http://www.pythonology.org/success</a> for a list of projects that
-use Python. Consulting the proceedings for <a class="reference external" href="../../workshops/">past Python conferences</a> will reveal contributions from
-many different companies and organizations.</p>
-<p>High-profile Python projects include <a class="reference external" href="http://www.list.org">the Mailman mailing list manager</a> and <a class="reference external" href="http://www.zope.org">the Zope application server</a>. Several Linux distributions, most
-notably <a class="reference external" href="http://www.redhat.com">Red Hat</a>, have written part or all
-of their installer and system administration software in Python. Companies
-that use Python internally include Google,
-Yahoo, and Industrial Light & Magic.</p>
-</div>
-<div class="section" id="what-new-developments-are-expected-for-python-in-the-future">
-<h2><a class="toc-backref" href="#id23">2.4 What new developments are expected for Python in the future?</a></h2>
-<p>See <a class="reference external" href="http://www.python.org/peps">http://www.python.org/peps</a> for the Python Enhancement Proposals
-(PEPs). PEPs are design documents describing a suggested new feature
-for Python, providing a concise technical specification and a
-rationale.
-<a class="reference external" href="../../peps/pep-0001.html">PEP 1</a>
-explains the PEP process and PEP format; read it
-first if you want to submit a PEP.</p>
-<p>New developments are discussed on <a class="reference external" href="http://mail.python.org/mailman/listinfo/python-dev/">the python-dev mailing list</a>.</p>
-</div>
-<div class="section" id="is-it-reasonable-to-propose-incompatible-changes-to-python">
-<h2><a class="toc-backref" href="#id24">2.5 Is it reasonable to propose incompatible changes to Python?</a></h2>
-<p>In general, no. There are already millions of lines of Python code
-around the world, so any change in the language that invalidates more
-than a very small fraction of existing programs has to be frowned
-upon. Even if you can provide a conversion program, there still is
-the problem of updating all documentation; many books have been
-written about Python, and we don't want to invalidate them all at a
-single stroke.</p>
-<p>Providing a gradual upgrade path is necessary if a feature has to be
-changed. <a class="reference external" href="../../peps/pep-0005.html">PEP 5</a>
-describes the procedure followed for introducing backward-incompatible
-changes while minimizing disruption for users.</p>
-</div>
-<div class="section" id="what-is-the-python-software-foundation">
-<h2><a class="toc-backref" href="#id25">2.6 What is the Python Software Foundation?</a></h2>
-<p>The Python Software Foundation is an independent non-profit
-organization that holds the copyright on Python versions 2.1 and
-newer. The PSF's mission is to advance open source technology related
-to the Python programming language and to publicize the use of
-Python. The PSF's home page is at <a class="reference external" href="http://www.python.org/psf/">http://www.python.org/psf/</a>.</p>
-<p>Donations to the PSF are tax-exempt in the US. If you use Python and
-find it helpful, please contribute via <a class="reference external" href="../../psf/donations.html">the PSF donation page</a>.</p>
-</div>
-<div class="section" id="is-python-y2k-year-2000-compliant">
-<h2><a class="toc-backref" href="#id26">2.7 Is Python Y2K (Year 2000) Compliant?</a></h2>
-<p>As of August, 2003 no major problems have been reported and Y2K
-compliance seems to be a non-issue.</p>
-<p>Python does very few date calculations and for those it does perform relies
-on the C library functions. Python generally represents times either
-as seconds since 1970 or as a <tt class="docutils literal">(year, month, day, <span class="pre">...)</span></tt> tuple where the
-year is expressed with four digits, which makes Y2K bugs unlikely. So
-as long as your C library is okay, Python should be okay. Of course,
-it's possible that a particular application written in Python
-makes assumptions about 2-digit years.</p>
-<p>Because Python is available free of charge, there are no absolute
-guarantees. If there <em>are</em> unforseen problems, liability is the
-user's problem rather than the developers', and there is nobody you can sue
-for damages. The Python copyright notice contains the following
-disclaimer:</p>
-<blockquote>
-<p>4. PSF is making Python 2.3 available to Licensee on an "AS IS"
-basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
-IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
-DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
-FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.3 WILL NOT
-INFRINGE ANY THIRD PARTY RIGHTS.</p>
-<p>5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
-2.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
-A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.3,
-OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.</p>
-</blockquote>
-<p>The good news is that <em>if</em> you encounter a problem, you have full
-source available to track it down and fix it. This is one advantage of
-an open source programming environment.</p>
-</div>
-<div class="section" id="is-python-a-good-language-for-beginning-programmers">
-<h2><a class="toc-backref" href="#id27">2.8 Is Python a good language for beginning programmers?</a></h2>
-<p>Yes. If you want to discuss Python's use in education, then you may
-be interested in joining <a class="reference external" href="../../sigs/edu-sig">the edu-sig mailing list</a>.</p>
-<p>It is still common to start students with a procedural (subset of a)
-statically typed language such as Pascal, C, or a subset of C++ or
-Java. Students may be better served by learning Python as their first
-language. Python has a very simple and consistent syntax and a large
-standard library and, most importantly, using Python in a beginning
-programming course permits students to concentrate on important
-programming skills such as problem decomposition and data type design.
-With Python, students can be quickly introduced to basic concepts such
-as loops and procedures. They can even probably work with
-user-defined objects in their very first course.</p>
-<p>For a student who has never programmed before, using a statically
-typed language seems unnatural. It presents additional complexity
-that the student must master and slows the pace of the course. The
-students are trying to learn to think like a computer, decompose
-problems, design consistent interfaces, and encapsulate data. While
-learning to use a statically typed language is important in the long
-term, it is not necessarily the best topic to address in the students'
-first programming course.</p>
-<p>Many other aspects of Python make it a good first language.
-Like Java, Python has a large standard library so that
-students can be assigned programming projects very early in the
-course that <em>do</em> something. Assignments aren't restricted to the
-standard four-function calculator and check balancing programs.
-By using the standard library, students can gain the satisfaction
-of working on realistic applications as they learn the fundamentals
-of programming. Using the standard library also teaches students
-about code reuse. Third-party modules such as PyGame are also helpful in
-extending the students' reach.</p>
-<p>Python's interactive interpreter enables students to
-test language features while they're programming. They can keep
-a window with the interpreter running while they enter their
-program's source in another window. If they can't remember the
-methods for a list, they can do something like this:</p>
-<pre class="literal-block">
->>> L = []
->>> dir(L)
-['append', 'count', 'extend', 'index', 'insert', 'pop', 'remove',
-'reverse', 'sort']
->>> help(L.append)
-Help on built-in function append:
-
-append(...)
- L.append(object) -- append object to end
->>> L.append(1)
->>> L
-[1]
-</pre>
-<p>With the interpreter, documentation is never far from the
-student as he's programming.</p>
-<p>There are also good IDEs for Python. IDLE is a cross-platform IDE for
-Python that is written in Python using Tkinter. PythonWin is a
-Windows-specific IDE. Emacs users will be happy to know that there is
-a very good Python mode for Emacs. All of these programming
-environments provide syntax highlighting, auto-indenting, and access
-to the interactive interpreter while coding. Consult
-<a class="reference external" href="http://www.python.org/editors/">http://www.python.org/editors/</a> for a full list of Python editing
-environments.</p>
-</div>
-</div>
-<div class="section" id="upgrading-python">
-<h1><a class="toc-backref" href="#id28">3 Upgrading Python</a></h1>
-<div class="section" id="what-is-this-bsddb185-module-my-application-keeps-complaining-about">
-<h2><a class="toc-backref" href="#id29">3.1 What is this bsddb185 module my application keeps complaining about?</a></h2>
-<p>Starting with Python2.3, the distribution includes the <cite>PyBSDDB package
-<http://pybsddb.sf.net/></cite> as a replacement for the old bsddb module. It
-includes functions which provide backward compatibility at the API level,
-but requires a newer version of the underlying <a class="reference external" href="http://www.sleepycat.com">Berkeley DB</a> library. Files created with the older bsddb
-module can't be opened directly using the new module.</p>
-<p>Using your old version of Python and a pair of scripts which are part of
-Python 2.3 (db2pickle.py and pickle2db.py, in the Tools/scripts directory)
-you can convert your old database files to the new format. Using your old
-Python version, run the db2pickle.py script to convert it to a pickle,
-e.g.:</p>
-<pre class="literal-block">
-python2.2 <pathto>/db2pickley.py database.db database.pck
-</pre>
-<p>Rename your database file:</p>
-<pre class="literal-block">
-mv database.db olddatabase.db
-</pre>
-<p>Now convert the pickle file to a new format database:</p>
-<pre class="literal-block">
-python2.3 <pathto>/pickle2db.py database.db database.pck
-</pre>
-<p>The precise commands you use will vary depending on the particulars of your
-installation. For full details about operation of these two scripts check
-the doc string at the start of each one.</p>
-</div>
-</div>
-<div class="section" id="python-s-design">
-<h1><a class="toc-backref" href="#id30">4 Python's Design</a></h1>
-<div class="section" id="why-does-python-use-indentation-for-grouping-of-statements">
-<h2><a class="toc-backref" href="#id31">4.1 Why does Python use indentation for grouping of statements?</a></h2>
-<p>Guido van Rossum believes that using indentation for grouping is extremely elegant
-and contributes a lot to the clarity of the average Python program. Most
-people learn to love this feature after awhile.</p>
-<p>Since there are no begin/end brackets there cannot be a disagreement between
-grouping perceived by the parser and the human reader. Occasionally C
-programmers will encounter a fragment of code like this:</p>
-<pre class="literal-block">
-if (x <= y)
- x++;
- y--;
-z++;
-</pre>
-<p>Only the <tt class="docutils literal">x++</tt> statement is executed if the condition is true, but
-the indentation leads you to believe otherwise.
-Even experienced C programmers will sometimes
-stare a long time at it wondering why y is being decremented even for
-<tt class="docutils literal">x > y</tt>.</p>
-<p>Because there are no begin/end brackets, Python is much less prone to
-coding-style conflicts. In C there are many different ways to place the
-braces. If you're used to reading
-and writing code that uses one style, you will feel at least slightly
-uneasy when reading (or being required to write) another style.</p>
-<p>Many coding styles place begin/end brackets on a line by themself. This
-makes programs considerably longer and wastes valuable screen space, making
-it harder to get a good overview of a program. Ideally, a function should
-fit on onescreen (say, 20-30 lines). 20 lines of Python can do
-a lot more work than 20 lines of C. This is not solely due to the lack of
-begin/end brackets -- the lack of declarations and the high-level data types
-are also responsible -- but the indentation-based syntax certainly helps.</p>
-</div>
-<div class="section" id="why-am-i-getting-strange-results-with-simple-arithmetic-operations">
-<h2><a class="toc-backref" href="#id32">4.2 Why am I getting strange results with simple arithmetic operations?</a></h2>
-<p>See the next question.</p>
-</div>
-<div class="section" id="why-are-floating-point-calculations-so-inaccurate">
-<h2><a class="toc-backref" href="#id33">4.3 Why are floating point calculations so inaccurate?</a></h2>
-<p>People are often very surprised by results like this:</p>
-<pre class="literal-block">
->>> 1.2-1.0
-0.199999999999999996
-</pre>
-<p>and think it is a bug in Python. It's not. It's a problem caused by
-the internal representation of floating point numbers, which uses a
-fixed number of binary digits to represent a decimal number. Some
-decimal numbers can't be represented exactly in binary, resulting in
-small roundoff errors.</p>
-<p>In decimal math, there are many numbers that can't be represented with a
-fixed number of decimal digits, e.g. 1/3 = 0.3333333333.......</p>
-<p>In base 2, 1/2 = 0.1, 1/4 = 0.01, 1/8 = 0.001, etc.
-.2 equals 2/10 equals 1/5, resulting in the binary fractional number
-0.001100110011001...</p>
-<p>Floating point numbers only have 32 or 64 bits of precision, so the digits are cut off at some point,
-and the resulting number is 0.199999999999999996 in decimal, not 0.2.</p>
-<p>A floating point's <tt class="docutils literal">repr()</tt> function prints as many digits are
-necessary to make <tt class="docutils literal">eval(repr(f)) == f</tt> true for any float f. The
-<tt class="docutils literal">str()</tt> function prints fewer digits and this often results in the
-more sensible number that was probably intended:</p>
-<pre class="literal-block">
->>> 0.2
-0.20000000000000001
->>> print 0.2
-0.2
-</pre>
-<p>Again, this has nothing to do with Python, but with the way the underlying C
-platform handles floating point numbers, and ultimately with the inaccuracy
-you'll always have when writing down numbers as a string of a fixed number
-of digits.</p>
-<p>One of the consequences of this is that it is dangerous to compare the
-result of some computation to a float with == ! Tiny inaccuracies may mean
-that == fails.
-Instead, you have to check that the difference between the
-two numbers is less than a certain threshold:</p>
-<pre class="literal-block">
-epsilon = 0.0000000000001 # Tiny allowed error
-expected_result = 0.4
-
-if expected_result-epsilon <= computation() <= expected_result+epsilon:
- ...
-</pre>
-<p>Please see the chapter on
-<a class="reference external" href="http://docs.python.org/tut/node16.html">floating point arithmetic</a>
-in the Python tutorial for more information.</p>
-</div>
-<div class="section" id="why-are-python-strings-immutable">
-<h2><a class="toc-backref" href="#id34">4.4 Why are Python strings immutable?</a></h2>
-<p>There are several advantages.</p>
-<p>One is performance: knowing that a string is
-immutable makes it easy to lay it out at construction time -- fixed and
-unchanging storage requirements. This is also one of the reasons for the
-distinction between tuples and lists.</p>
-<p>The other is that strings in Python are considered as "elemental" as
-numbers. No amount of activity will change the value 8 to anything
-else, and in Python, no amount of activity will change the string
-"eight" to anything else.</p>
-</div>
-<div class="section" id="why-must-self-be-used-explicitly-in-method-definitions-and-calls">
-<h2><a class="toc-backref" href="#id35">4.5 Why must 'self' be used explicitly in method definitions and calls?</a></h2>
-<p>The idea was borrowed from Modula-3. It turns out to be very useful,
-for a variety of reasons.</p>
-<p>First, it's more obvious that you are using a method or instance
-attribute instead of a local variable. Reading <tt class="docutils literal">self.x</tt> or <tt class="docutils literal">self.meth()</tt>
-makes it absolutely clear that an instance variable or method is used even
-if you don't know the class definition by heart. In C++, you can sort of
-tell by the lack of a local variable declaration (assuming globals are rare
-or easily recognizable) -- but in Python, there are no local variable
-declarations, so you'd have to look up the class definition to be sure.
-Some C++ and Java coding standards call for instance attributes to have an
-<tt class="docutils literal">m_</tt> prefix, so this explicitness is still useful in those languages, too.</p>
-<p>Second, it means that no special syntax is necessary if you want to
-explicitly reference or call the method from a particular class. In C++, if
-you want to use a method from a base class which is overridden in a derived
-class, you have to use the :: operator -- in Python you can write
-baseclass.methodname(self, <argument list>). This is particularly useful
-for __init__() methods, and in general in cases where a derived class method
-wants to extend the base class method of the same name and thus has to call
-the base class method somehow.</p>
-<p>Finally, for instance variables it solves a syntactic problem with
-assignment: since local variables in Python are (by definition!) those
-variables to which a value assigned in a function body (and that aren't
-explicitly declared global), there has to be some way to tell the
-interpreter that an assignment was meant to assign to an instance variable
-instead of to a local variable, and it should preferably be syntactic (for
-efficiency reasons). C++ does this through declarations, but Python doesn't
-have declarations and it would be a pity having to introduce them just for
-this purpose. Using the explicit "self.var" solves this nicely. Similarly,
-for using instance variables, having to write "self.var" means that
-references to unqualified names inside a method don't have to search the
-instance's directories. To put it another way, local variables and
-instance variables live in two different namespaces, and you need to
-tell Python which namespace to use.</p>
-</div>
-<div class="section" id="why-can-t-i-use-an-assignment-in-an-expression">
-<h2><a class="toc-backref" href="#id36">4.6 Why can't I use an assignment in an expression?</a></h2>
-<p>Many people used to C or Perl complain that they want to
-use this C idiom:</p>
-<pre class="literal-block">
-while (line = readline(f)) {
- ...do something with line...
-}
-</pre>
-<p>where in Python you're forced to write this:</p>
-<pre class="literal-block">
-while True:
- line = f.readline()
- if not line:
- break
- ...do something with line...
-</pre>
-<p>The reason for not allowing assignment in Python expressions
-is a common, hard-to-find bug in those other languages,
-caused by this construct:</p>
-<pre class="literal-block">
-if (x = 0) {
- ...error handling...
-}
-else {
- ...code that only works for nonzero x...
-}
-</pre>
-<p>The error is a simple typo: <tt class="docutils literal">x = 0</tt>, which assigns 0 to the variable <tt class="docutils literal">x</tt>,
-was written while the comparison <tt class="docutils literal">x == 0</tt> is certainly what was intended.</p>
-<p>Many alternatives have been proposed. Most are hacks that save some
-typing but use arbitrary or cryptic syntax or keywords,
-and fail the simple criterion for language change proposals:
-it should intuitively suggest the proper meaning to a human reader
-who has not yet been introduced to the construct.</p>
-<p>An interesting phenomenon is that most experienced Python programmers
-recognize the "while True" idiom and don't seem to be missing the
-assignment in expression construct much; it's only newcomers
-who express a strong desire to add this to the language.</p>
-<p>There's an alternative way of spelling this that seems
-attractive but is generally less robust than the "while True" solution:</p>
-<pre class="literal-block">
-line = f.readline()
-while line:
- ...do something with line...
- line = f.readline()
-</pre>
-<p>The problem with this is that if you change your mind about exactly
-how you get the next line (e.g. you want to change it into
-<tt class="docutils literal">sys.stdin.readline()</tt>) you have to remember to change two places in
-your program -- the second occurrence is hidden at the bottom of the
-loop.</p>
-<p>The best approach is to use iterators, making it possible to loop
-through objects using the <tt class="docutils literal">for</tt> statement. For example, in the
-current version of Python file objects support the iterator protocol, so you
-can now write simply:</p>
-<pre class="literal-block">
-for line in f:
- ... do something with line...
-</pre>
-</div>
-<div class="section" id="why-does-python-use-methods-for-some-functionality-e-g-list-index-but-functions-for-other-e-g-len-list">
-<h2><a class="toc-backref" href="#id37">4.7 Why does Python use methods for some functionality (e.g. list.index()) but functions for other (e.g. len(list))?</a></h2>
-<p>The major reason is history. Functions were used for those operations
-that were generic for a group of types and which were intended to work
-even for objects that didn't have methods at all (e.g. tuples). It is
-also convenient to have a function that can readily be applied to an
-amorphous collection of objects when you use the functional features
-of Python (<tt class="docutils literal">map()</tt>, <tt class="docutils literal">apply()</tt> et al).</p>
-<p>In fact, implementing <tt class="docutils literal">len()</tt>, <tt class="docutils literal">max()</tt>, <tt class="docutils literal">min()</tt> as a built-in
-function is actually less code than implementing them as methods for
-each type. One can quibble about individual cases but it's a part of
-Python, and it's too late to make such fundamental changes now. The
-functions have to remain to avoid massive code breakage.</p>
-<p>Note that for string operations Python has moved from external functions
-(the <tt class="docutils literal">string</tt> module) to methods. However, <tt class="docutils literal">len()</tt> is still a function.</p>
-</div>
-<div class="section" id="why-is-join-a-string-method-instead-of-a-list-or-tuple-method">
-<h2><a class="toc-backref" href="#id38">4.8 Why is join() a string method instead of a list or tuple method?</a></h2>
-<p>Strings became much more like other standard types starting in Python
-1.6, when methods were added which give the same functionality that
-has always been available using the functions of the string module.
-Most of these new methods have been widely accepted, but the one which
-appears to make some programmers feel uncomfortable is:</p>
-<pre class="literal-block">
-", ".join(['1', '2', '4', '8', '16'])
-</pre>
-<p>which gives the result:</p>
-<pre class="literal-block">
-"1, 2, 4, 8, 16"
-</pre>
-<p>There are two usual arguments against this usage.</p>
-<p>The first runs along the lines of: "It looks really ugly using a method of a
-string literal (string constant)", to which the answer is that it might, but
-a string literal is just a fixed value. If the methods are to be allowed on
-names bound to strings there is no logical reason to make them unavailable
-on literals.</p>
-<p>The second objection is typically cast as: "I am really telling a sequence
-to join its members together with a string constant". Sadly, you aren't. For
-some reason there seems to be much less difficulty with having split() as a
-string method, since in that case it is easy to see that</p>
-<pre class="literal-block">
-"1, 2, 4, 8, 16".split(", ")
-</pre>
-<p>is an instruction to a string literal to return the substrings delimited by
-the given separator (or, by default, arbitrary runs of white space). In this
-case a Unicode string returns a list of Unicode strings, an ASCII string
-returns a list of ASCII strings, and everyone is happy.</p>
-<p>join() is a string method because in using it you are telling the separator
-string to iterate over an arbitrary sequence, forming string representations
-of each of the elements, and inserting itself between the elements'
-representations. This method can be used with any argument which obeys the
-rules for sequence objects, inluding any new classes you might define
-yourself.</p>
-<p>Because this is a string method it can work for Unicode strings as well as
-plain ASCII strings. If join() were a method of the sequence types then the
-sequence types would have to decide which type of string to return depending
-on the type of the separator.</p>
-<p>If none of these arguments persuade you, then for the moment you can
-continue to use the join() function from the string module, which allows you
-to write</p>
-<pre class="literal-block">
-string.join(['1', '2', '4', '8', '16'], ", ")
-</pre>
-</div>
-<div class="section" id="how-fast-are-exceptions">
-<h2><a class="toc-backref" href="#id39">4.9 How fast are exceptions?</a></h2>
-<p>A try/except block is extremely efficient. Actually executing an exception
-is expensive. In versions of Python prior to 2.0 it was common to use this
-idiom:</p>
-<pre class="literal-block">
-try:
- value = dict[key]
-except KeyError:
- dict[key] = getvalue(key)
- value = dict[key]
-</pre>
-<p>This only made sense when you expected the dict to have the key almost all
-the time. If that wasn't the case, you coded it like this:</p>
-<pre class="literal-block">
-if dict.has_key(key):
- value = dict[key]
-else:
- dict[key] = getvalue(key)
- value = dict[key]
-</pre>
-<p>(In Python 2.0 and higher, you can code this as
-<tt class="docutils literal">value = dict.setdefault(key, getvalue(key))</tt>.)</p>
-</div>
-<div class="section" id="why-isn-t-there-a-switch-or-case-statement-in-python">
-<h2><a class="toc-backref" href="#id40">4.10 Why isn't there a switch or case statement in Python?</a></h2>
-<p>You can do this easily enough with a sequence of <tt class="docutils literal"><span class="pre">if...</span> <span class="pre">elif...</span> <span class="pre">elif...</span> else</tt>.
-There have been some proposals for switch statement syntax, but there is no
-consensus (yet) on whether and how to do range tests. See <a class="reference external" href="../../peps/pep-0275.html">PEP 275</a> for complete details and
-the current status.</p>
-<p>For cases where you need to choose from a very large number of
-possibilities, you can create a dictionary mapping case values to
-functions to call. For example:</p>
-<pre class="literal-block">
-def function_1 (...):
- ...
-
-functions = {'a': function_1,
- 'b': function_2,
- 'c': self.method_1, ...}
-
-func = functions[value]
-func()
-</pre>
-<p>For calling methods on objects, you can simplify yet further by using
-the <tt class="docutils literal">getattr()</tt> built-in to retrieve methods with a particular name:</p>
-<pre class="literal-block">
-def visit_a (self, ...):
- ...
-...
-
-def dispatch (self, value):
- method_name = 'visit_' + str(value)
- method = getattr(self, method_name)
- method()
-</pre>
-<p>It's suggested that you use a prefix for the method names, such as
-<tt class="docutils literal">visit_</tt> in this example. Without such a prefix, if values are coming
-from an untrusted source, an attacker would be able to call any method
-on your object.</p>
-</div>
-<div class="section" id="can-t-you-emulate-threads-in-the-interpreter-instead-of-relying-on-an-os-specific-thread-implementation">
-<h2><a class="toc-backref" href="#id41">4.11 Can't you emulate threads in the interpreter instead of relying on an OS-specific thread implementation?</a></h2>
-<p>Answer 1: Unfortunately, the interpreter pushes at least one C stack frame
-for each Python stack frame. Also, extensions can call back into Python at
-almost random moments. Therefore, a complete threads implementation
-requires thread support for C.</p>
-<p>Answer 2: Fortunately, there is <a class="reference external" href="http://www.stackless.com">Stackless Python</a>, which has a completely redesigned interpreter
-loop that avoids the C stack. It's still experimental but looks very
-promising. Although it is binary compatible with standard Python, it's
-still unclear whether Stackless will make it into the core -- maybe it's
-just too revolutionary.</p>
-</div>
-<div class="section" id="why-can-t-lambda-forms-contain-statements">
-<h2><a class="toc-backref" href="#id42">4.12 Why can't lambda forms contain statements?</a></h2>
-<p>Python lambda forms cannot contain statements because Python's syntactic
-framework can't handle statements nested inside expressions. However, in
-Python, this is not a serious problem. Unlike lambda forms in other
-languages, where they add functionality, Python lambdas are only a shorthand
-notation if you're too lazy to define a function.</p>
-<p>Functions are already first class objects in Python, and can be declared in
-a local scope. Therefore the only advantage of using a lambda form instead
-of a locally-defined function is that you don't need to invent a name for
-the function -- but that's just a local variable to which the function
-object (which is exactly the same type of object that a lambda form yields)
-is assigned!</p>
-</div>
-<div class="section" id="can-python-be-compiled-to-machine-code-c-or-some-other-language">
-<h2><a class="toc-backref" href="#id43">4.13 Can Python be compiled to machine code, C or some other language?</a></h2>
-<p>Not easily. Python's high level data types, dynamic typing of objects and
-run-time invocation of the interpreter (using <tt class="docutils literal">eval()</tt> or <tt class="docutils literal">exec</tt>) together mean
-that a "compiled" Python program would probably consist mostly of calls into
-the Python run-time system, even for seemingly simple operations like
-<tt class="docutils literal">x+1</tt>.</p>
-<p>Several projects described in the Python newsgroup or at past <a class="reference external" href="../../workshops/">Python
-conferences</a> have shown that this
-approach is feasible, although the speedups reached so far are only
-modest (e.g. 2x). Jython uses the same strategy for compiling to Java
-bytecode. (Jim Hugunin has demonstrated that in combination with
-whole-program analysis, speedups of 1000x are feasible for small demo
-programs. See the proceedings from the <a class="reference external" href="../../workshops/1997-10/proceedings/">1997 Python conference</a> for more
-information.)</p>
-<p>Internally, Python source code is always translated into a bytecode
-representation, and this bytecode is then executed by the Python
-virtual machine. In order to avoid the overhead of repeatedly parsing
-and translating modules that rarely change, this byte code is written
-into a file whose name ends in ".pyc" whenever a module is parsed.
-When the corresponding .py file is changed, it is parsed and
-translated again and the .pyc file is rewritten.</p>
-<p>There is no performance difference once the .pyc file has been loaded,
-as the bytecode read from the .pyc file is exactly the same as the
-bytecode created by direct translation. The only difference is that
-loading code from a .pyc file is faster than parsing and translating a
-.py file, so the presence of precompiled .pyc files improves the
-start-up time of Python scripts. If desired, the Lib/compileall.py
-module can be used to create valid .pyc files for a given set of
-modules.</p>
-<p>Note that the main script executed by Python, even if its filename
-ends in .py, is not compiled to a .pyc file. It is compiled to
-bytecode, but the bytecode is not saved to a file. Usually main
-scripts are quite short, so this doesn't cost much speed.</p>
-<p>There are also several programs which make it easier to intermingle
-Python and C code in various ways to increase performance. See, for
-example, <a class="reference external" href="http://psyco.sourceforge.net/">Psyco</a>,
-<a class="reference external" href="http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/">Pyrex</a>, <a class="reference external" href="http://pyinline.sourceforge.net/">PyInline</a>, <a class="reference external" href="http://sourceforge.net/projects/py2cmod/">Py2Cmod</a>, and <a class="reference external" href="http://www.scipy.org/site_content/weave">Weave</a>.</p>
-</div>
-<div class="section" id="how-does-python-manage-memory">
-<h2><a class="toc-backref" href="#id44">4.14 How does Python manage memory?</a></h2>
-<p>The details of Python memory management depend on the implementation.
-The standard C implementation of Python uses reference counting to
-detect inaccessible objects, and another mechanism to collect
-reference cycles, periodically executing a cycle detection algorithm
-which looks for inaccessible cycles and deletes the objects
-involved. The <tt class="docutils literal">gc</tt> module provides functions to perform a garbage
-collection, obtain debugging statistics, and tune the collector's
-parameters.</p>
-<p>Jython relies on the Java runtime so the JVM's garbage collector is
-used. This difference can cause some subtle porting problems if your
-Python code depends on the behavior of the reference counting
-implementation.</p>
-<p>Sometimes objects get stuck in tracebacks temporarily and hence are not
-deallocated when you might expect. Clear the tracebacks with:</p>
-<pre class="literal-block">
-import sys
-sys.exc_clear()
-sys.exc_traceback = sys.last_traceback = None
-</pre>
-<p>Tracebacks are used for reporting errors, implementing debuggers and related
-things. They contain a portion of the program state extracted during the
-handling of an exception (usually the most recent exception).</p>
-<p>In the absence of circularities and tracebacks, Python programs need
-not explicitly manage memory.</p>
-<p>Why doesn't Python use a more traditional garbage collection scheme?
-For one thing, this is not a C standard feature and hence it's not
-portable. (Yes, we know about the Boehm GC library. It has bits of
-assembler code for <em>most</em> common platforms, not for all of them, and
-although it is mostly transparent, it isn't completely transparent;
-patches are required to get Python to work with it.)</p>
-<p>Traditional GC also becomes a problem when Python is embedded into other
-applications. While in a standalone Python it's fine to replace the
-standard malloc() and free() with versions provided by the GC library, an
-application embedding Python may want to have its <em>own</em> substitute for
-malloc() and free(), and may not want Python's. Right now, Python works
-with anything that implements malloc() and free() properly.</p>
-<p>In Jython, the following code (which is fine in CPython) will probably run
-out of file descriptors long before it runs out of memory:</p>
-<pre class="literal-block">
-for file in <very long list of files>:
- f = open(file)
- c = f.read(1)
-</pre>
-<p>Using the current reference counting and destructor scheme, each new
-assignment to f closes the previous file. Using GC, this is not
-guaranteed. If you want to write code that will work with any Python
-implementation, you should explicitly close the file; this will work
-regardless of GC:</p>
-<pre class="literal-block">
-for file in <very long list of files>:
- f = open(file)
- c = f.read(1)
- f.close()
-</pre>
-</div>
-<div class="section" id="why-isn-t-all-memory-freed-when-python-exits">
-<h2><a class="toc-backref" href="#id45">4.15 Why isn't all memory freed when Python exits?</a></h2>
-<p>Objects referenced from the global namespaces of
-Python modules are not always deallocated when Python exits.
-This may happen if there are circular references. There are also
-certain bits of memory that are allocated by the C library that are
-impossible to free (e.g. a tool like Purify will complain about
-these). Python is, however, aggressive about cleaning up memory on
-exit and does try to destroy every single object.</p>
-<p>If you want to force Python to delete certain things on deallocation
-use the <tt class="docutils literal">sys.exitfunc()</tt> hook to run a function that will force
-those deletions.</p>
-</div>
-<div class="section" id="why-are-there-separate-tuple-and-list-data-types">
-<h2><a class="toc-backref" href="#id46">4.16 Why are there separate tuple and list data types?</a></h2>
-<p>Lists and tuples, while similar in many respects, are generally used
-in fundamentally different ways. Tuples can be thought of as being
-similar to Pascal records or C structs; they're small collections of
-related data which may be of different types which are operated on as
-a group. For example, a Cartesian coordinate is appropriately
-represented as a tuple of two or three numbers.</p>
-<p>Lists, on the other hand, are more like arrays in other languages. They
-tend to hold a varying number of objects all of which have the same type and
-which are operated on one-by-one. For example, <tt class="docutils literal"><span class="pre">os.listdir('.')</span></tt> returns
-a list of strings representing the files in the current directory.
-Functions which operate on this output would generally not break if you
-added another file or two to the directory.</p>
-<p>Tuples are immutable, meaning that once a tuple has been created, you
-can't replace any of its elements with a new value. Lists are
-mutable, meaning that you can always change a list's elements. Only
-immutable elements can be used as dictionary keys, and hence only
-tuples and not lists can be used as keys.</p>
-</div>
-<div class="section" id="how-are-lists-implemented">
-<h2><a class="toc-backref" href="#id47">4.17 How are lists implemented?</a></h2>
-<p>Python's lists are really variable-length arrays, not Lisp-style
-linked lists. The implementation uses a contiguous array of
-references to other objects, and keeps a pointer to this array and the
-array's length in a list head structure.</p>
-<p>This makes indexing a list <tt class="docutils literal">a[i]</tt> an operation whose cost is independent of
-the size of the list or the value of the index.</p>
-<p>When items are appended or inserted, the array of references is resized.
-Some cleverness is applied to improve the performance of appending items
-repeatedly; when the array must be grown, some extra space is allocated so
-the next few times don't require an actual resize.</p>
-</div>
-<div class="section" id="how-are-dictionaries-implemented">
-<h2><a class="toc-backref" href="#id48">4.18 How are dictionaries implemented?</a></h2>
-<p>Python's dictionaries are implemented as resizable hash tables.
-Compared to B-trees, this gives better performance for lookup
-(the most common operation by far) under most circumstances,
-and the implementation is simpler.</p>
-<p>Dictionaries work by computing a hash code for each key stored in the
-dictionary using the <tt class="docutils literal">hash()</tt> built-in function. The hash code
-varies widely depending on the key; for example, "Python" hashes to
--539294296 while "python", a string that differs by a single bit,
-hashes to 1142331976. The hash code is then used to calculate a
-location in an internal array where the value will be stored.
-Assuming that you're storing keys that all have different hash values,
-this means that dictionaries take constant time -- O(1), in computer
-science notation -- to retrieve a key. It also means that no sorted
-order of the keys is maintained, and traversing the array as the
-<tt class="docutils literal">.keys()</tt> and <tt class="docutils literal">.items()</tt> do will output the dictionary's content
-in some arbitrary jumbled order.</p>
-</div>
-<div class="section" id="why-must-dictionary-keys-be-immutable">
-<h2><a class="toc-backref" href="#id49">4.19 Why must dictionary keys be immutable?</a></h2>
-<p>The hash table implementation of dictionaries uses a hash value
-calculated from the key value to find the key. If the key were a
-mutable object, its value could change, and thus its hash could also
-change. But since whoever changes the key object can't tell that it
-was being used as a dictionary key, it can't move the entry around in the
-dictionary. Then, when you try to look up the same object in the
-dictionary it won't be found because its hash value is different.
-If you tried to look up the old value it wouldn't be found either, because
-the value of the object found in that hash bin would be different.</p>
-<p>If you want a dictionary indexed with a list, simply convert the list
-to a tuple first; the function <tt class="docutils literal">tuple(L)</tt> creates a tuple with the
-same entries as the list <tt class="docutils literal">L</tt>. Tuples are immutable and can
-therefore be used as dictionary keys.</p>
-<p>Some unacceptable solutions that have been proposed:</p>
-<ul>
-<li><p class="first">Hash lists by their address (object ID). This doesn't work because
-if you construct a new list with the same value it won't be found;
-e.g.:</p>
-<pre class="literal-block">
-d = {[1,2]: '12'}
-print d[[1,2]]
-</pre>
-<p>would raise a KeyError exception because the id of the <tt class="docutils literal">[1,2]</tt> used in
-the second line differs from that in the first line. In other
-words, dictionary keys should be compared using <tt class="docutils literal">==</tt>, not using
-'is'.</p>
-</li>
-<li><p class="first">Make a copy when using a list as a key. This doesn't work because
-the list, being a mutable object, could contain a reference to
-itself, and then the copying code would run into an infinite loop.</p>
-</li>
-<li><p class="first">Allow lists as keys but tell the user not to modify them. This
-would allow a class of hard-to-track bugs in programs when you forgot
-or modified a list by accident. It also
-invalidates an important invariant of
-dictionaries: every value in <tt class="docutils literal">d.keys()</tt> is usable as a key of the
-dictionary.</p>
-</li>
-<li><p class="first">Mark lists as read-only once they are used as a dictionary key. The
-problem is that it's not just the top-level object that could change
-its value; you could use a tuple containing a list as a key.
-Entering anything as a key into a dictionary would require marking
-all objects reachable from there as read-only -- and again,
-self-referential objects could cause an infinite loop.</p>
-</li>
-</ul>
-<p>There is a trick to get around this if you need to, but
-use it at your own risk: You
-can wrap a mutable structure inside a class instance which
-has both a __cmp__ and a __hash__ method.
-You must then make sure that the hash value for all such wrapper objects
-that reside in a dictionary (or other hash based structure), remain
-fixed while the object is in the dictionary (or other structure).:</p>
-<pre class="literal-block">
-class ListWrapper:
- def __init__(self, the_list):
- self.the_list = the_list
- def __cmp__(self, other):
- return self.the_list == other.the_list
- def __hash__(self):
- l = self.the_list
- result = 98767 - len(l)*555
- for i in range(len(l)):
- try:
- result = result + (hash(l[i]) % 9999999) * 1001 + i
- except:
- result = (result % 7777777) + i * 333
- return result
-</pre>
-<p>Note that the hash computation is complicated by the
-possibility that some members of the list may be unhashable
-and also by the possibility of arithmetic overflow.</p>
-<p>Furthermore it must always be the case that if
-<tt class="docutils literal">o1 == o2</tt> (ie <tt class="docutils literal"><span class="pre">o1.__cmp__(o2)==0</span></tt>) then <tt class="docutils literal"><span class="pre">hash(o1)==hash(o2)</span></tt>
-(ie, <tt class="docutils literal">o1.__hash__() == o2.__hash__()</tt>), regardless of whether
-the object is in a dictionary or not.
-If you fail to meet these restrictions dictionaries and other
-hash based structures will misbehave.</p>
-<p>In the case of ListWrapper, whenever the wrapper
-object is in a dictionary the wrapped list must not change
-to avoid anomalies. Don't do this unless you are prepared
-to think hard about the requirements and the consequences
-of not meeting them correctly. Consider yourself warned.</p>
-</div>
-<div class="section" id="why-doesn-t-list-sort-return-the-sorted-list">
-<h2><a class="toc-backref" href="#id50">4.20 Why doesn't list.sort() return the sorted list?</a></h2>
-<p>In situations where performance matters, making a copy
-of the list just to sort it would be wasteful. Therefore,
-list.sort() sorts the list in place. In order to remind you
-of that fact, it does not return the sorted list. This way,
-you won't be fooled into accidentally overwriting a list
-when you need a sorted copy but also need to keep the
-unsorted version around.</p>
-<p>In Python 2.4 a new builtin - sorted() - has been added.
-This function creates a new list from a passed
-iterable, sorts it and returns it.</p>
-<p>As a result, here's the idiom to iterate over the keys of a
-dictionary in sorted order:</p>
-<pre class="literal-block">
-for key in sorted(dict.iterkeys()):
- ...do whatever with dict[key]...
-</pre>
-<p>Versions of Python prior to 2.4 need to use the following idiom:</p>
-<pre class="literal-block">
-keys = dict.keys()
-keys.sort()
-for key in keys:
- ...do whatever with dict[key]...
-</pre>
-</div>
-<div class="section" id="how-do-you-specify-and-enforce-an-interface-spec-in-python">
-<h2><a class="toc-backref" href="#id51">4.21 How do you specify and enforce an interface spec in Python?</a></h2>
-<p>An interface specification for a module as provided by languages such
-as C++ and Java describes the prototypes for the methods and functions
-of the module. Many feel that compile-time enforcement of interface
-specifications help in the construction of large programs. Python
-does not support interface specifications directly, but many of their
-advantages can be obtained by an appropriate test discipline for
-components, which can often be very easily accomplished in Python.
-There is also a tool, PyChecker, which can be used to find problems
-due to subclassing.</p>
-<p>A good test suite for a module can at once provide a regression test
-and serve as both a module interface specification and a set of
-examples. Many Python modules can be run as a script to provide a
-simple "self test." Even modules which use complex external
-interfaces can often be tested in isolation using trivial "stub"
-emulations of the external interface. The <tt class="docutils literal">doctest</tt> and
-<tt class="docutils literal">unittest</tt> modules or third-party test frameworks can be used to construct
-exhaustive test suites that exercise every line of code in a module.</p>
-<p>An appropriate testing discipline can help build large complex
-applications in Python as well as having interface specifications
-would. In fact, it can be better because an interface specification
-cannot test certain properties of a program. For example, the
-<tt class="docutils literal">append()</tt> method is expected to add new elements to the end of some
-internal list; an interface specification cannot test that your
-<tt class="docutils literal">append()</tt> implementation will actually do this correctly, but it's
-trivial to check this property in a test suite.</p>
-<p>Writing test suites is very helpful, and you might want to design your
-code with an eye to making it easily tested. One increasingly popular
-technique, test-directed development, calls for writing parts of the
-test suite first, before you write any of the actual code. Of course
-Python allows you to be sloppy and not write test cases at all.</p>
-</div>
-<div class="section" id="why-are-default-values-shared-between-objects">
-<h2><a class="toc-backref" href="#id52">4.22 Why are default values shared between objects?</a></h2>
-<p>This type of bug commonly bites neophyte programmers. Consider this function:</p>
-<pre class="literal-block">
-def foo(D={}): # Danger: shared reference to one dict for all calls
- ... compute something ...
- D[key] = value
- return D
-</pre>
-<p>The first time you call this function, <tt class="docutils literal">D</tt> contains a single item.
-The second time, <tt class="docutils literal">D</tt> contains two items because when <tt class="docutils literal">foo()</tt> begins executing,
-<tt class="docutils literal">D</tt> starts out with an item already in it.</p>
-<p>It is often expected that a function call creates new objects for
-default values. This is not what happens. Default values are created
-exactly once, when the function is defined. If that object is
-changed, like the dictionary in this example, subsequent calls to the
-function will refer to this changed object.</p>
-<p>By definition, immutable objects such as numbers, strings, tuples, and
-<tt class="docutils literal">None</tt>, are safe from change. Changes to mutable objects such as
-dictionaries, lists, and class instances can lead to confusion.</p>
-<p>Because of this feature, it is good programming practice to not use mutable
-objects as default values. Instead, use <tt class="docutils literal">None</tt> as the default value
-and inside the function, check if the parameter is <tt class="docutils literal">None</tt> and create a new list/dictionary/whatever
-if it is. For example, don't write:</p>
-<pre class="literal-block">
-def foo(dict={}):
- ...
-</pre>
-<p>but:</p>
-<pre class="literal-block">
-def foo(dict=None):
- if dict is None:
- dict = {} # create a new dict for local namespace
-</pre>
-<p>This feature can be useful. When you have a function that's time-consuming to compute,
-a common technique is to cache the parameters and the resulting value of each
-call to the function, and return the cached value if the same value is requested again.
-This is called "memoizing", and can be implemented like this:</p>
-<pre class="literal-block">
-# Callers will never provide a third parameter for this function.
-def expensive (arg1, arg2, _cache={}):
- if _cache.has_key((arg1, arg2)):
- return _cache[(arg1, arg2)]
-
- # Calculate the value
- result = ... expensive computation ...
- _cache[(arg1, arg2)] = result # Store result in the cache
- return result
-</pre>
-<p>You could use a global variable containing a dictionary instead of
-the default value; it's a matter of taste.</p>
-</div>
-<div class="section" id="why-is-there-no-goto">
-<h2><a class="toc-backref" href="#id53">4.23 Why is there no goto?</a></h2>
-<p>You can use exceptions to provide a "structured goto"
-that even works across function calls. Many feel that exceptions
-can conveniently emulate all reasonable uses of the "go" or "goto"
-constructs of C, Fortran, and other languages. For example:</p>
-<pre class="literal-block">
-class label: pass # declare a label
-
-try:
- ...
- if (condition): raise label() # goto label
- ...
-except label: # where to goto
- pass
-...
-</pre>
-<p>This doesn't allow you to jump into the middle of a loop, but
-that's usually considered an abuse of goto anyway. Use sparingly.</p>
-</div>
-<div class="section" id="why-do-i-get-a-syntaxerror-for-a-continue-inside-a-try">
-<h2><a class="toc-backref" href="#id54">4.24 Why do I get a SyntaxError for a 'continue' inside a 'try'?</a></h2>
-<p>This is an implementation limitation, caused by the extremely
-simple-minded way Python generates bytecode. The <tt class="docutils literal">try</tt> block pushes
-something on the "block stack" which the <tt class="docutils literal">continue</tt> would have to pop
-off again. The current code generator doesn't have the data
-structures around so that <tt class="docutils literal">continue</tt> can generate the right code.</p>
-<p>Note that Jython doesn't have this restriction!</p>
-</div>
-<div class="section" id="why-can-t-raw-strings-r-strings-end-with-a-backslash">
-<h2><a class="toc-backref" href="#id55">4.25 Why can't raw strings (r-strings) end with a backslash?</a></h2>
-<p>More precisely, they can't end with an odd number of backslashes:
-the unpaired backslash at the end escapes the closing quote character,
-leaving an unterminated string.</p>
-<p>Raw strings were designed to ease creating input for processors
-(chiefly regular expression engines) that want to do their own
-backslash escape processing. Such processors consider an unmatched
-trailing backslash to be an error anyway, so raw strings disallow
-that. In return, they allow you to pass on the string quote character
-by escaping it with a backslash. These rules work well when r-strings
-are used for their intended purpose.</p>
-<p>If you're trying to build Windows pathnames, note that all Windows
-system calls accept forward slashes too:</p>
-<pre class="literal-block">
-f = open("/mydir/file.txt") # works fine!
-</pre>
-<p>If you're trying to build a pathname for a DOS command, try e.g. one of</p>
-<pre class="literal-block">
-dir = r"\this\is\my\dos\dir" "\\"
-dir = r"\this\is\my\dos\dir\ "[:-1]
-dir = "\\this\\is\\my\\dos\\dir\\"
-</pre>
-</div>
-<div class="section" id="why-doesn-t-python-have-a-with-statement-like-some-other-languages">
-<h2><a class="toc-backref" href="#id56">4.26 Why doesn't Python have a "with" statement like some other languages?</a></h2>
-<p>Because such a construct would be ambiguous.</p>
-<p>Some languages, such as Object Pascal, Delphi, and C++, use static
-types. So it is possible to know, in an unambiguous way, what member
-is being assigned in a "with" clause. This is the main point - the
-compiler <em>always</em> knows the scope of every variable at compile time.</p>
-<p>Python uses dynamic types. It is impossible to know in advance which
-attribute will be referenced at runtime. Member attributes may be
-added or removed from objects on the fly. This would make it
-impossible to know, from a simple reading, what attribute is being
-referenced - a local one, a global one, or a member attribute.</p>
-<p>For instance, take the following incomplete snippet:</p>
-<pre class="literal-block">
-def foo(a):
- with a:
- print x
-</pre>
-<p>The snippet assumes that "a" must have a member attribute called "x".
-However, there is nothing in Python that guarantees that. What should
-happen if "a" is, let us say, an integer? And if I have a global
-variable named "x", will it end up being used inside the with block?
-As you see, the dynamic nature of Python makes such choices much
-harder.</p>
-<p>The primary benefit of "with" and similar language features (reduction
-of code volume) can, however, easily be achieved in Python by
-assignment. Instead of:</p>
-<pre class="literal-block">
-function(args).dict[index][index].a = 21
-function(args).dict[index][index].b = 42
-function(args).dict[index][index].c = 63
-</pre>
-<p>write this:</p>
-<pre class="literal-block">
-ref = function(args).dict[index][index]
-ref.a = 21
-ref.b = 42
-ref.c = 63
-</pre>
-<p>This also has the side-effect of increasing execution speed because
-name bindings are resolved at run-time in Python, and the second
-version only needs to perform the resolution once. If the referenced
-object does not have a, b and c attributes, of course, the end result
-is still a run-time exception.</p>
-</div>
-<div class="section" id="why-are-colons-required-for-the-if-while-def-class-statements">
-<h2><a class="toc-backref" href="#id57">4.27 Why are colons required for the if/while/def/class statements?</a></h2>
-<p>The colon is required primarily to enhance readability (one of the
-results of the experimental ABC language). Consider this:</p>
-<pre class="literal-block">
-if a==b
- print a
-</pre>
-<p>versus</p>
-<pre class="literal-block">
-if a==b:
- print a
-</pre>
-<p>Notice how the second one is slightly easier to read. Notice further how
-a colon sets off the example in the second line of this FAQ answer; it's
-a standard usage in English.</p>
-<p>Another minor reason is that the colon makes it easier for editors
-with syntax highlighting; they can look for colons to decide when
-indentation needs to be increased instead of having to do a more
-elaborate parsing of the program text.</p>
-</div>
-</div>
-</div>
-</body>
-</html>
diff --git a/faq/gui.ht b/faq/gui.ht
deleted file mode 100644
index d68d969..0000000
--- a/faq/gui.ht
+++ /dev/null
@@ -1,173 +0,0 @@
-Title: Graphic User Interface FAQ
-Content-type: text/x-rst
-
-====================================
-Graphic User Interface FAQ
-====================================
-
-:Date: $Date: 2003-09-04 18:00:23 -0600 (Thu, 04 Sep 2003) $
-:Version: $Revision: 6607 $
-:Web site: http://www.python.org/
-
-.. contents::
-.. sectnum::
-
-General GUI Questions
-============================
-
-What platform-independent GUI toolkits exist for Python?
-----------------------------------------------------------------
-Depending on what platform(s) you are aiming at, there are several.
-
-Tkinter
-''''''''''''
-
-Standard builds of Python include an object-oriented interface to the
-Tcl/Tk widget set, called Tkinter. This is probably the easiest to
-install and use. For more info about Tk, including pointers to the
-source, see the Tcl/Tk home page at http://www.tcl.tk. Tcl/Tk is
-fully portable to the MacOS, Windows, and Unix platforms.
-
-wxWindows
-'''''''''''''
-
-
-wxWindows is a portable GUI class library written in C++ that's a
-portable interface to various platform-specific libraries; wxPython is
-a Python interface to wxWindows. wxWindows supports Windows and MacOS;
-on Unix variants, it supports both GTk+ and Motif toolkits.
-wxWindows preserves the look and feel of the underlying graphics
-toolkit, and there is quite a rich widget set and collection of GDI
-classes. See `the wxWindows page <http://www.wxwindows.org>`_ for more
-details.
-
-`wxPython <http://alldunn.com/wxPython>`_ is an extension module that
-wraps many of the wxWindows C++ classes, and is quickly gaining
-popularity amongst Python developers. You can get wxPython as part of
-the source or CVS distribution of wxWindows, or directly from its home
-page.
-
-
-Qt
-''''''
-
-There are bindings available for the Qt toolkit (`PyQt
-<http://www.riverbankcomputing.co.uk/pyqt/>`_) and for KDE (PyKDE).
-If you're writing open source software, you don't need to pay for
-PyQt, but if you want to write proprietary applications, you must buy
-a PyQt license from `Riverbank Computing
-<http://www.riverbankcomputing.co.uk>`_ and a Qt license from
-`Trolltech <http://www.trolltech.com>`_.
-
-GTk+
-'''''''''''
-
-PyGTk bindings for the `GTk+ toolkit <http://www.gtk.org>`_ have been
-implemented by by James Henstridge; see
-ftp://ftp.gtk.org/pub/gtk/python/.
-
-FLTK
-'''''''''''
-
-Python bindings for `the FLTK toolkit <http://www.fltk.org>`_, a simple yet powerful
-and mature cross-platform windowing system, are available from `the
-PyFLTK project <http://pyfltk.sourceforge.net>`_.
-
-
-FOX
-'''''''''''
-
-A wrapper for `the FOX toolkit <http://www.fox-toolkit.org/>`_
-called `FXpy <http://fxpy.sourceforge.net/>`_ is available.
-FOX supports both Unix variants and Windows.
-
-
-OpenGL
-'''''''''''''
-
-For OpenGL bindings, see `PyOpenGL <http://pyopengl.sourceforge.net>`_.
-
-
-What platform-specific GUI toolkits exist for Python?
-----------------------------------------------------------------
-
-`The Mac port <http://www.python.org/download/download_mac.html>`_ by
-Jack Jansen has a rich and ever-growing set of modules that support
-the native Mac toolbox calls. The port includes support for MacOS9
-and MacOS X's Carbon libraries. By installing the `PyObjc Objective-C
-bridge <http://pyobjc.sourceforge.net>`_, Python programs can use
-MacOS X's Cocoa libraries. See the documentation that comes with the
-Mac port.
-
-`Pythonwin <http://www.python.org/windows>`_ by Mark Hammond
-includes an interface to the Microsoft Foundation
-Classes and a Python programming environment using it that's written
-mostly in Python.
-
-
-Tkinter questions
-=====================
-
-How do I freeze Tkinter applications?
----------------------------------------------
-
-Freeze is a tool to create stand-alone applications. When freezing
-Tkinter applications, the applications will not be truly stand-alone,
-as the application will still need the Tcl and Tk libraries.
-
-One solution is to ship the application with the tcl and tk libraries,
-and point to them at run-time using the TCL_LIBRARY and TK_LIBRARY
-environment variables.
-
-To get truly stand-alone applications, the Tcl scripts that form
-the library have to be integrated into the application as well. One
-tool supporting that is SAM (stand-alone modules), which is part
-of the Tix distribution (http://tix.mne.com). Build Tix with SAM
-enabled, perform the appropriate call to Tclsam_init etc inside
-Python's Modules/tkappinit.c, and link with libtclsam
-and libtksam (you might include the Tix libraries as well).
-
-
-Can I have Tk events handled while waiting for I/O?
------------------------------------------------------------
-Yes, and you don't even need threads! But you'll have to
-restructure your I/O code a bit. Tk has the equivalent of Xt's
-XtAddInput() call, which allows you to register a callback function
-which will be called from the Tk mainloop when I/O is possible on a
-file descriptor. Here's what you need::
-
- from Tkinter import tkinter
- tkinter.createfilehandler(file, mask, callback)
-
-The file may be a Python file or socket object (actually, anything
-with a fileno() method), or an integer file descriptor. The mask is
-one of the constants tkinter.READABLE or tkinter.WRITABLE. The
-callback is called as follows::
-
- callback(file, mask)
-
-You must unregister the callback when you're done, using ::
-
- tkinter.deletefilehandler(file)
-
-Note: since you don't know *how many bytes* are available for reading,
-you can't use the Python file object's read or readline methods, since
-these will insist on reading a predefined number of bytes. For
-sockets, the recv() or recvfrom() methods will work fine; for other
-files, use os.read(file.fileno(), maxbytecount).
-
-
-I can't get key bindings to work in Tkinter: why?
----------------------------------------------------
-An often-heard complaint is that event handlers bound to events
-with the bind() method don't get handled even when the appropriate
-key is pressed.
-
-The most common cause is that the widget to which the binding applies
-doesn't have "keyboard focus". Check out the Tk documentation
-for the focus command. Usually a widget is given the keyboard
-focus by clicking in it (but not for labels; see the takefocus
-option).
-
-
-
diff --git a/faq/gui.html b/faq/gui.html
deleted file mode 100644
index 8e92621..0000000
--- a/faq/gui.html
+++ /dev/null
@@ -1,516 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
-<title>Graphic User Interface FAQ</title>
-<meta name="date" content="2003-09-04" />
-<style type="text/css">
-
-/*
-:Author: David Goodger (goodger@python.org)
-:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
- border: 0 }
-
-table.borderless td, table.borderless th {
- /* Override padding for "table.docutils td" with "! important".
- The right padding separates the table cells. */
- padding: 0 0.5em 0 0 ! important }
-
-.first {
- /* Override more specific margin styles with "! important". */
- margin-top: 0 ! important }
-
-.last, .with-subtitle {
- margin-bottom: 0 ! important }
-
-.hidden {
- display: none }
-
-a.toc-backref {
- text-decoration: none ;
- color: black }
-
-blockquote.epigraph {
- margin: 2em 5em ; }
-
-dl.docutils dd {
- margin-bottom: 0.5em }
-
-object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
- overflow: hidden;
-}
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
- font-weight: bold }
-*/
-
-div.abstract {
- margin: 2em 5em }
-
-div.abstract p.topic-title {
- font-weight: bold ;
- text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
- margin: 2em ;
- border: medium outset ;
- padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title, .code .error {
- color: red ;
- font-weight: bold ;
- font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
- compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
- margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
- margin-top: 0.5em }
-*/
-
-div.dedication {
- margin: 2em 5em ;
- text-align: center ;
- font-style: italic }
-
-div.dedication p.topic-title {
- font-weight: bold ;
- font-style: normal }
-
-div.figure {
- margin-left: 2em ;
- margin-right: 2em }
-
-div.footer, div.header {
- clear: both;
- font-size: smaller }
-
-div.line-block {
- display: block ;
- margin-top: 1em ;
- margin-bottom: 1em }
-
-div.line-block div.line-block {
- margin-top: 0 ;
- margin-bottom: 0 ;
- margin-left: 1.5em }
-
-div.sidebar {
- margin: 0 0 0.5em 1em ;
- border: medium outset ;
- padding: 1em ;
- background-color: #ffffee ;
- width: 40% ;
- float: right ;
- clear: right }
-
-div.sidebar p.rubric {
- font-family: sans-serif ;
- font-size: medium }
-
-div.system-messages {
- margin: 5em }
-
-div.system-messages h1 {
- color: red }
-
-div.system-message {
- border: medium outset ;
- padding: 1em }
-
-div.system-message p.system-message-title {
- color: red ;
- font-weight: bold }
-
-div.topic {
- margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
- margin-top: 0.4em }
-
-h1.title {
- text-align: center }
-
-h2.subtitle {
- text-align: center }
-
-hr.docutils {
- width: 75% }
-
-img.align-left, .figure.align-left, object.align-left {
- clear: left ;
- float: left ;
- margin-right: 1em }
-
-img.align-right, .figure.align-right, object.align-right {
- clear: right ;
- float: right ;
- margin-left: 1em }
-
-img.align-center, .figure.align-center, object.align-center {
- display: block;
- margin-left: auto;
- margin-right: auto;
-}
-
-.align-left {
- text-align: left }
-
-.align-center {
- clear: both ;
- text-align: center }
-
-.align-right {
- text-align: right }
-
-/* reset inner alignment in figures */
-div.align-right {
- text-align: inherit }
-
-/* div.align-center * { */
-/* text-align: left } */
-
-ol.simple, ul.simple {
- margin-bottom: 1em }
-
-ol.arabic {
- list-style: decimal }
-
-ol.loweralpha {
- list-style: lower-alpha }
-
-ol.upperalpha {
- list-style: upper-alpha }
-
-ol.lowerroman {
- list-style: lower-roman }
-
-ol.upperroman {
- list-style: upper-roman }
-
-p.attribution {
- text-align: right ;
- margin-left: 50% }
-
-p.caption {
- font-style: italic }
-
-p.credits {
- font-style: italic ;
- font-size: smaller }
-
-p.label {
- white-space: nowrap }
-
-p.rubric {
- font-weight: bold ;
- font-size: larger ;
- color: maroon ;
- text-align: center }
-
-p.sidebar-title {
- font-family: sans-serif ;
- font-weight: bold ;
- font-size: larger }
-
-p.sidebar-subtitle {
- font-family: sans-serif ;
- font-weight: bold }
-
-p.topic-title {
- font-weight: bold }
-
-pre.address {
- margin-bottom: 0 ;
- margin-top: 0 ;
- font: inherit }
-
-pre.literal-block, pre.doctest-block, pre.math, pre.code {
- margin-left: 2em ;
- margin-right: 2em }
-
-pre.code .ln { color: grey; } /* line numbers */
-pre.code, code { background-color: #eeeeee }
-pre.code .comment, code .comment { color: #5C6576 }
-pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
-pre.code .literal.string, code .literal.string { color: #0C5404 }
-pre.code .name.builtin, code .name.builtin { color: #352B84 }
-pre.code .deleted, code .deleted { background-color: #DEB0A1}
-pre.code .inserted, code .inserted { background-color: #A3D289}
-
-span.classifier {
- font-family: sans-serif ;
- font-style: oblique }
-
-span.classifier-delimiter {
- font-family: sans-serif ;
- font-weight: bold }
-
-span.interpreted {
- font-family: sans-serif }
-
-span.option {
- white-space: nowrap }
-
-span.pre {
- white-space: pre }
-
-span.problematic {
- color: red }
-
-span.section-subtitle {
- /* font-size relative to parent (h1..h6 element) */
- font-size: 80% }
-
-table.citation {
- border-left: solid 1px gray;
- margin-left: 1px }
-
-table.docinfo {
- margin: 2em 4em }
-
-table.docutils {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
-
-table.footnote {
- border-left: solid 1px black;
- margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
- padding-left: 0.5em ;
- padding-right: 0.5em ;
- vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
- font-weight: bold ;
- text-align: left ;
- white-space: nowrap ;
- padding-left: 0 }
-
-/* "booktabs" style (no vertical lines) */
-table.docutils.booktabs {
- border: 0px;
- border-top: 2px solid;
- border-bottom: 2px solid;
- border-collapse: collapse;
-}
-table.docutils.booktabs * {
- border: 0px;
-}
-table.docutils.booktabs th {
- border-bottom: thin solid;
- text-align: left;
-}
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
- font-size: 100% }
-
-ul.auto-toc {
- list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="graphic-user-interface-faq">
-<h1 class="title">Graphic User Interface FAQ</h1>
-<table class="docinfo" frame="void" rules="none">
-<col class="docinfo-name" />
-<col class="docinfo-content" />
-<tbody valign="top">
-<tr><th class="docinfo-name">Date:</th>
-<td>2003-09-04</td></tr>
-<tr><th class="docinfo-name">Version:</th>
-<td>6607</td></tr>
-<tr class="field"><th class="docinfo-name">Web site:</th><td class="field-body"><a class="reference external" href="http://www.python.org/">http://www.python.org/</a></td>
-</tr>
-</tbody>
-</table>
-<div class="contents topic" id="contents">
-<p class="topic-title first">Contents</p>
-<ul class="auto-toc simple">
-<li><a class="reference internal" href="#general-gui-questions" id="id1">1 General GUI Questions</a><ul class="auto-toc">
-<li><a class="reference internal" href="#what-platform-independent-gui-toolkits-exist-for-python" id="id2">1.1 What platform-independent GUI toolkits exist for Python?</a><ul class="auto-toc">
-<li><a class="reference internal" href="#tkinter" id="id3">1.1.1 Tkinter</a></li>
-<li><a class="reference internal" href="#wxwindows" id="id4">1.1.2 wxWindows</a></li>
-<li><a class="reference internal" href="#qt" id="id5">1.1.3 Qt</a></li>
-<li><a class="reference internal" href="#gtk" id="id6">1.1.4 GTk+</a></li>
-<li><a class="reference internal" href="#fltk" id="id7">1.1.5 FLTK</a></li>
-<li><a class="reference internal" href="#fox" id="id8">1.1.6 FOX</a></li>
-<li><a class="reference internal" href="#opengl" id="id9">1.1.7 OpenGL</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#what-platform-specific-gui-toolkits-exist-for-python" id="id10">1.2 What platform-specific GUI toolkits exist for Python?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#tkinter-questions" id="id11">2 Tkinter questions</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-do-i-freeze-tkinter-applications" id="id12">2.1 How do I freeze Tkinter applications?</a></li>
-<li><a class="reference internal" href="#can-i-have-tk-events-handled-while-waiting-for-i-o" id="id13">2.2 Can I have Tk events handled while waiting for I/O?</a></li>
-<li><a class="reference internal" href="#i-can-t-get-key-bindings-to-work-in-tkinter-why" id="id14">2.3 I can't get key bindings to work in Tkinter: why?</a></li>
-</ul>
-</li>
-</ul>
-</div>
-<div class="section" id="general-gui-questions">
-<h1><a class="toc-backref" href="#id1">1 General GUI Questions</a></h1>
-<div class="section" id="what-platform-independent-gui-toolkits-exist-for-python">
-<h2><a class="toc-backref" href="#id2">1.1 What platform-independent GUI toolkits exist for Python?</a></h2>
-<p>Depending on what platform(s) you are aiming at, there are several.</p>
-<div class="section" id="tkinter">
-<h3><a class="toc-backref" href="#id3">1.1.1 Tkinter</a></h3>
-<p>Standard builds of Python include an object-oriented interface to the
-Tcl/Tk widget set, called Tkinter. This is probably the easiest to
-install and use. For more info about Tk, including pointers to the
-source, see the Tcl/Tk home page at <a class="reference external" href="http://www.tcl.tk">http://www.tcl.tk</a>. Tcl/Tk is
-fully portable to the MacOS, Windows, and Unix platforms.</p>
-</div>
-<div class="section" id="wxwindows">
-<h3><a class="toc-backref" href="#id4">1.1.2 wxWindows</a></h3>
-<p>wxWindows is a portable GUI class library written in C++ that's a
-portable interface to various platform-specific libraries; wxPython is
-a Python interface to wxWindows. wxWindows supports Windows and MacOS;
-on Unix variants, it supports both GTk+ and Motif toolkits.
-wxWindows preserves the look and feel of the underlying graphics
-toolkit, and there is quite a rich widget set and collection of GDI
-classes. See <a class="reference external" href="http://www.wxwindows.org">the wxWindows page</a> for more
-details.</p>
-<p><a class="reference external" href="http://alldunn.com/wxPython">wxPython</a> is an extension module that
-wraps many of the wxWindows C++ classes, and is quickly gaining
-popularity amongst Python developers. You can get wxPython as part of
-the source or CVS distribution of wxWindows, or directly from its home
-page.</p>
-</div>
-<div class="section" id="qt">
-<h3><a class="toc-backref" href="#id5">1.1.3 Qt</a></h3>
-<p>There are bindings available for the Qt toolkit (<a class="reference external" href="http://www.riverbankcomputing.co.uk/pyqt/">PyQt</a>) and for KDE (PyKDE).
-If you're writing open source software, you don't need to pay for
-PyQt, but if you want to write proprietary applications, you must buy
-a PyQt license from <a class="reference external" href="http://www.riverbankcomputing.co.uk">Riverbank Computing</a> and a Qt license from
-<a class="reference external" href="http://www.trolltech.com">Trolltech</a>.</p>
-</div>
-<div class="section" id="gtk">
-<h3><a class="toc-backref" href="#id6">1.1.4 GTk+</a></h3>
-<p>PyGTk bindings for the <a class="reference external" href="http://www.gtk.org">GTk+ toolkit</a> have been
-implemented by by James Henstridge; see
-<a class="reference external" href="ftp://ftp.gtk.org/pub/gtk/python/">ftp://ftp.gtk.org/pub/gtk/python/</a>.</p>
-</div>
-<div class="section" id="fltk">
-<h3><a class="toc-backref" href="#id7">1.1.5 FLTK</a></h3>
-<p>Python bindings for <a class="reference external" href="http://www.fltk.org">the FLTK toolkit</a>, a simple yet powerful
-and mature cross-platform windowing system, are available from <a class="reference external" href="http://pyfltk.sourceforge.net">the
-PyFLTK project</a>.</p>
-</div>
-<div class="section" id="fox">
-<h3><a class="toc-backref" href="#id8">1.1.6 FOX</a></h3>
-<p>A wrapper for <a class="reference external" href="http://www.fox-toolkit.org/">the FOX toolkit</a>
-called <a class="reference external" href="http://fxpy.sourceforge.net/">FXpy</a> is available.
-FOX supports both Unix variants and Windows.</p>
-</div>
-<div class="section" id="opengl">
-<h3><a class="toc-backref" href="#id9">1.1.7 OpenGL</a></h3>
-<p>For OpenGL bindings, see <a class="reference external" href="http://pyopengl.sourceforge.net">PyOpenGL</a>.</p>
-</div>
-</div>
-<div class="section" id="what-platform-specific-gui-toolkits-exist-for-python">
-<h2><a class="toc-backref" href="#id10">1.2 What platform-specific GUI toolkits exist for Python?</a></h2>
-<p><a class="reference external" href="http://www.python.org/download/download_mac.html">The Mac port</a> by
-Jack Jansen has a rich and ever-growing set of modules that support
-the native Mac toolbox calls. The port includes support for MacOS9
-and MacOS X's Carbon libraries. By installing the <a class="reference external" href="http://pyobjc.sourceforge.net">PyObjc Objective-C
-bridge</a>, Python programs can use
-MacOS X's Cocoa libraries. See the documentation that comes with the
-Mac port.</p>
-<p><a class="reference external" href="http://www.python.org/windows">Pythonwin</a> by Mark Hammond
-includes an interface to the Microsoft Foundation
-Classes and a Python programming environment using it that's written
-mostly in Python.</p>
-</div>
-</div>
-<div class="section" id="tkinter-questions">
-<h1><a class="toc-backref" href="#id11">2 Tkinter questions</a></h1>
-<div class="section" id="how-do-i-freeze-tkinter-applications">
-<h2><a class="toc-backref" href="#id12">2.1 How do I freeze Tkinter applications?</a></h2>
-<p>Freeze is a tool to create stand-alone applications. When freezing
-Tkinter applications, the applications will not be truly stand-alone,
-as the application will still need the Tcl and Tk libraries.</p>
-<p>One solution is to ship the application with the tcl and tk libraries,
-and point to them at run-time using the TCL_LIBRARY and TK_LIBRARY
-environment variables.</p>
-<p>To get truly stand-alone applications, the Tcl scripts that form
-the library have to be integrated into the application as well. One
-tool supporting that is SAM (stand-alone modules), which is part
-of the Tix distribution (<a class="reference external" href="http://tix.mne.com">http://tix.mne.com</a>). Build Tix with SAM
-enabled, perform the appropriate call to Tclsam_init etc inside
-Python's Modules/tkappinit.c, and link with libtclsam
-and libtksam (you might include the Tix libraries as well).</p>
-</div>
-<div class="section" id="can-i-have-tk-events-handled-while-waiting-for-i-o">
-<h2><a class="toc-backref" href="#id13">2.2 Can I have Tk events handled while waiting for I/O?</a></h2>
-<p>Yes, and you don't even need threads! But you'll have to
-restructure your I/O code a bit. Tk has the equivalent of Xt's
-XtAddInput() call, which allows you to register a callback function
-which will be called from the Tk mainloop when I/O is possible on a
-file descriptor. Here's what you need:</p>
-<pre class="literal-block">
-from Tkinter import tkinter
-tkinter.createfilehandler(file, mask, callback)
-</pre>
-<p>The file may be a Python file or socket object (actually, anything
-with a fileno() method), or an integer file descriptor. The mask is
-one of the constants tkinter.READABLE or tkinter.WRITABLE. The
-callback is called as follows:</p>
-<pre class="literal-block">
-callback(file, mask)
-</pre>
-<p>You must unregister the callback when you're done, using</p>
-<pre class="literal-block">
-tkinter.deletefilehandler(file)
-</pre>
-<p>Note: since you don't know <em>how many bytes</em> are available for reading,
-you can't use the Python file object's read or readline methods, since
-these will insist on reading a predefined number of bytes. For
-sockets, the recv() or recvfrom() methods will work fine; for other
-files, use os.read(file.fileno(), maxbytecount).</p>
-</div>
-<div class="section" id="i-can-t-get-key-bindings-to-work-in-tkinter-why">
-<h2><a class="toc-backref" href="#id14">2.3 I can't get key bindings to work in Tkinter: why?</a></h2>
-<p>An often-heard complaint is that event handlers bound to events
-with the bind() method don't get handled even when the appropriate
-key is pressed.</p>
-<p>The most common cause is that the widget to which the binding applies
-doesn't have "keyboard focus". Check out the Tk documentation
-for the focus command. Usually a widget is given the keyboard
-focus by clicking in it (but not for labels; see the takefocus
-option).</p>
-</div>
-</div>
-</div>
-</body>
-</html>
diff --git a/faq/installed.ht b/faq/installed.ht
deleted file mode 100644
index a82ab50..0000000
--- a/faq/installed.ht
+++ /dev/null
@@ -1,61 +0,0 @@
-Title: "Why is Python Installed on my Computer?" FAQ
-Content-type: text/x-rst
-
-=====================================================
-"Why is Python Installed on my Computer?" FAQ
-=====================================================
-
-What is Python?
-----------------------
-
-Python is a programming language. It's used for many different
-applications. It's used in some high schools and colleges as an
-introductory programming language because Python is easy to learn, but
-it's also used by professional software developers at places such as Google,
-NASA, and Industrial Light & Magic.
-
-If you're curious about finding out more about Python, start with the
-`Beginner's Guide to Python <http://www.python.org/moin/BeginnersGuide>`_.
-
-
-Why is Python installed on my machine?
---------------------------------------------------
-
-If you find Python installed on your system but don't remember
-installing it, there are several possible ways it could have gotten
-there.
-
-* Perhaps another user on the computer wanted to learn programming
- and installed it; you'll have to figure out who's been using the machine
- and might have installed it.
-* A third-party application installed on the machine might have been written
- in Python and included a Python installation. For a home computer,
- the most common such application is
- `PySol <http://www.oberhumer.com/opensource/pysol/>`_,
- a solitaire game that includes over 200 different games and variations.
-* Some Windows machines also have Python installed. At this writing we're
- aware of computers from Hewlett-Packard and Compaq that include Python.
- Apparently some of HP/Compaq's administrative tools are written in Python.
-* All Apple computers running Mac OS X have Python installed; it's included
- in the base installation.
-
-
-Can I delete Python?
-----------------------------
-
-That depends on where Python came from.
-
-If someone installed it deliberately, you can remove it without
-hurting anything. On Windows, use the Add/Remove Programs icon in the
-Control Panel.
-
-If Python was installed by a third-party application, you can also
-remove it, but that application will no longer work. You should probably
-use that application's uninstaller rather than removing Python directly.
-
-If Python came with your operating system, removing it is not
-recommended. If you remove it, whatever tools were written in Python
-will no longer run, and some of them might be important to you.
-Reinstalling the whole system would then be required to fix things
-again.
-
diff --git a/faq/installed.html b/faq/installed.html
deleted file mode 100644
index 3a86833..0000000
--- a/faq/installed.html
+++ /dev/null
@@ -1,392 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
-<title>"Why is Python Installed on my Computer?" FAQ</title>
-<style type="text/css">
-
-/*
-:Author: David Goodger (goodger@python.org)
-:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
- border: 0 }
-
-table.borderless td, table.borderless th {
- /* Override padding for "table.docutils td" with "! important".
- The right padding separates the table cells. */
- padding: 0 0.5em 0 0 ! important }
-
-.first {
- /* Override more specific margin styles with "! important". */
- margin-top: 0 ! important }
-
-.last, .with-subtitle {
- margin-bottom: 0 ! important }
-
-.hidden {
- display: none }
-
-a.toc-backref {
- text-decoration: none ;
- color: black }
-
-blockquote.epigraph {
- margin: 2em 5em ; }
-
-dl.docutils dd {
- margin-bottom: 0.5em }
-
-object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
- overflow: hidden;
-}
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
- font-weight: bold }
-*/
-
-div.abstract {
- margin: 2em 5em }
-
-div.abstract p.topic-title {
- font-weight: bold ;
- text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
- margin: 2em ;
- border: medium outset ;
- padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title, .code .error {
- color: red ;
- font-weight: bold ;
- font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
- compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
- margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
- margin-top: 0.5em }
-*/
-
-div.dedication {
- margin: 2em 5em ;
- text-align: center ;
- font-style: italic }
-
-div.dedication p.topic-title {
- font-weight: bold ;
- font-style: normal }
-
-div.figure {
- margin-left: 2em ;
- margin-right: 2em }
-
-div.footer, div.header {
- clear: both;
- font-size: smaller }
-
-div.line-block {
- display: block ;
- margin-top: 1em ;
- margin-bottom: 1em }
-
-div.line-block div.line-block {
- margin-top: 0 ;
- margin-bottom: 0 ;
- margin-left: 1.5em }
-
-div.sidebar {
- margin: 0 0 0.5em 1em ;
- border: medium outset ;
- padding: 1em ;
- background-color: #ffffee ;
- width: 40% ;
- float: right ;
- clear: right }
-
-div.sidebar p.rubric {
- font-family: sans-serif ;
- font-size: medium }
-
-div.system-messages {
- margin: 5em }
-
-div.system-messages h1 {
- color: red }
-
-div.system-message {
- border: medium outset ;
- padding: 1em }
-
-div.system-message p.system-message-title {
- color: red ;
- font-weight: bold }
-
-div.topic {
- margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
- margin-top: 0.4em }
-
-h1.title {
- text-align: center }
-
-h2.subtitle {
- text-align: center }
-
-hr.docutils {
- width: 75% }
-
-img.align-left, .figure.align-left, object.align-left {
- clear: left ;
- float: left ;
- margin-right: 1em }
-
-img.align-right, .figure.align-right, object.align-right {
- clear: right ;
- float: right ;
- margin-left: 1em }
-
-img.align-center, .figure.align-center, object.align-center {
- display: block;
- margin-left: auto;
- margin-right: auto;
-}
-
-.align-left {
- text-align: left }
-
-.align-center {
- clear: both ;
- text-align: center }
-
-.align-right {
- text-align: right }
-
-/* reset inner alignment in figures */
-div.align-right {
- text-align: inherit }
-
-/* div.align-center * { */
-/* text-align: left } */
-
-ol.simple, ul.simple {
- margin-bottom: 1em }
-
-ol.arabic {
- list-style: decimal }
-
-ol.loweralpha {
- list-style: lower-alpha }
-
-ol.upperalpha {
- list-style: upper-alpha }
-
-ol.lowerroman {
- list-style: lower-roman }
-
-ol.upperroman {
- list-style: upper-roman }
-
-p.attribution {
- text-align: right ;
- margin-left: 50% }
-
-p.caption {
- font-style: italic }
-
-p.credits {
- font-style: italic ;
- font-size: smaller }
-
-p.label {
- white-space: nowrap }
-
-p.rubric {
- font-weight: bold ;
- font-size: larger ;
- color: maroon ;
- text-align: center }
-
-p.sidebar-title {
- font-family: sans-serif ;
- font-weight: bold ;
- font-size: larger }
-
-p.sidebar-subtitle {
- font-family: sans-serif ;
- font-weight: bold }
-
-p.topic-title {
- font-weight: bold }
-
-pre.address {
- margin-bottom: 0 ;
- margin-top: 0 ;
- font: inherit }
-
-pre.literal-block, pre.doctest-block, pre.math, pre.code {
- margin-left: 2em ;
- margin-right: 2em }
-
-pre.code .ln { color: grey; } /* line numbers */
-pre.code, code { background-color: #eeeeee }
-pre.code .comment, code .comment { color: #5C6576 }
-pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
-pre.code .literal.string, code .literal.string { color: #0C5404 }
-pre.code .name.builtin, code .name.builtin { color: #352B84 }
-pre.code .deleted, code .deleted { background-color: #DEB0A1}
-pre.code .inserted, code .inserted { background-color: #A3D289}
-
-span.classifier {
- font-family: sans-serif ;
- font-style: oblique }
-
-span.classifier-delimiter {
- font-family: sans-serif ;
- font-weight: bold }
-
-span.interpreted {
- font-family: sans-serif }
-
-span.option {
- white-space: nowrap }
-
-span.pre {
- white-space: pre }
-
-span.problematic {
- color: red }
-
-span.section-subtitle {
- /* font-size relative to parent (h1..h6 element) */
- font-size: 80% }
-
-table.citation {
- border-left: solid 1px gray;
- margin-left: 1px }
-
-table.docinfo {
- margin: 2em 4em }
-
-table.docutils {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
-
-table.footnote {
- border-left: solid 1px black;
- margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
- padding-left: 0.5em ;
- padding-right: 0.5em ;
- vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
- font-weight: bold ;
- text-align: left ;
- white-space: nowrap ;
- padding-left: 0 }
-
-/* "booktabs" style (no vertical lines) */
-table.docutils.booktabs {
- border: 0px;
- border-top: 2px solid;
- border-bottom: 2px solid;
- border-collapse: collapse;
-}
-table.docutils.booktabs * {
- border: 0px;
-}
-table.docutils.booktabs th {
- border-bottom: thin solid;
- text-align: left;
-}
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
- font-size: 100% }
-
-ul.auto-toc {
- list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="why-is-python-installed-on-my-computer-faq">
-<h1 class="title">"Why is Python Installed on my Computer?" FAQ</h1>
-
-<div class="section" id="what-is-python">
-<h1>What is Python?</h1>
-<p>Python is a programming language. It's used for many different
-applications. It's used in some high schools and colleges as an
-introductory programming language because Python is easy to learn, but
-it's also used by professional software developers at places such as Google,
-NASA, and Industrial Light & Magic.</p>
-<p>If you're curious about finding out more about Python, start with the
-<a class="reference external" href="http://www.python.org/moin/BeginnersGuide">Beginner's Guide to Python</a>.</p>
-</div>
-<div class="section" id="why-is-python-installed-on-my-machine">
-<h1>Why is Python installed on my machine?</h1>
-<p>If you find Python installed on your system but don't remember
-installing it, there are several possible ways it could have gotten
-there.</p>
-<ul class="simple">
-<li>Perhaps another user on the computer wanted to learn programming
-and installed it; you'll have to figure out who's been using the machine
-and might have installed it.</li>
-<li>A third-party application installed on the machine might have been written
-in Python and included a Python installation. For a home computer,
-the most common such application is
-<a class="reference external" href="http://www.oberhumer.com/opensource/pysol/">PySol</a>,
-a solitaire game that includes over 200 different games and variations.</li>
-<li>Some Windows machines also have Python installed. At this writing we're
-aware of computers from Hewlett-Packard and Compaq that include Python.
-Apparently some of HP/Compaq's administrative tools are written in Python.</li>
-<li>All Apple computers running Mac OS X have Python installed; it's included
-in the base installation.</li>
-</ul>
-</div>
-<div class="section" id="can-i-delete-python">
-<h1>Can I delete Python?</h1>
-<p>That depends on where Python came from.</p>
-<p>If someone installed it deliberately, you can remove it without
-hurting anything. On Windows, use the Add/Remove Programs icon in the
-Control Panel.</p>
-<p>If Python was installed by a third-party application, you can also
-remove it, but that application will no longer work. You should probably
-use that application's uninstaller rather than removing Python directly.</p>
-<p>If Python came with your operating system, removing it is not
-recommended. If you remove it, whatever tools were written in Python
-will no longer run, and some of them might be important to you.
-Reinstalling the whole system would then be required to fix things
-again.</p>
-</div>
-</div>
-</body>
-</html>
diff --git a/faq/library.ht b/faq/library.ht
deleted file mode 100644
index 7c9959a..0000000
--- a/faq/library.ht
+++ /dev/null
@@ -1,913 +0,0 @@
-Title: Python Library and Extension FAQ
-Content-type: text/x-rst
-
-====================================
-Python Library and Extension FAQ
-====================================
-
-:Date: $Date: 2005-12-16 19:21:20 -0700 (Fri, 16 Dec 2005) $
-:Version: $Revision: 8684 $
-:Web site: http://www.python.org/
-
-.. contents::
-.. sectnum::
-
-General Library Questions
-===============================
-
-How do I find a module or application to perform task X?
--------------------------------------------------------------
-
-Check `the Library Reference <http://www.python.org/doc/lib/>`_ to see
-if there's a relevant standard library module. (Eventually you'll
-learn what's in the standard library and will able to skip this step.)
-
-Search the `Python Package Index <http://cheeseshop.python.org/pypi>`_.
-
-Next, check the `Vaults of Parnassus <http://www.vex.net/parnassus/>`_,
-an older index of packages.
-
-Finally, try `Google <http://www.google.com>`_ or other Web search
-engine. Searching for "Python" plus a keyword or two for your topic
-of interest will usually find something helpful.
-
-
-Where is the math.py (socket.py, regex.py, etc.) source file?
----------------------------------------------------------------------
-If you can't find a source file for a module it may be a builtin
-or dynamically loaded module implemented in C, C++ or other
-compiled language. In this case you may not have the source
-file or it may be something like mathmodule.c, somewhere in
-a C source directory (not on the Python Path).
-
-There are (at least) three kinds of modules in Python:
-
-1) modules written in Python (.py);
-2) modules written in C and dynamically loaded (.dll, .pyd, .so, .sl, etc);
-3) modules written in C and linked with the interpreter; to get a list
- of these, type::
-
- import sys
- print sys.builtin_module_names
-
-How do I make a Python script executable on Unix?
----------------------------------------------------------
-
-You need to do two things: the script file's mode must be executable
-and the first line must begin with ``#!`` followed by the path of
-the Python interpreter.
-
-The first is done by executing ``chmod +x scriptfile`` or perhaps
-``chmod 755 scriptfile``.
-
-The second can be done in a number of ways. The most straightforward
-way is to write ::
-
- #!/usr/local/bin/python
-
-as the very first line of your file, using the pathname for where the
-Python interpreter is installed on your platform.
-
-If you would like the script to be independent of where the Python
-interpreter lives, you can use the "env" program. Almost all
-Unix variants support the following, assuming the python interpreter
-is in a directory on the user's $PATH::
-
- #! /usr/bin/env python
-
-*Don't* do this for CGI scripts. The $PATH variable for
-CGI scripts is often very minimal, so you need to use the actual
-absolute pathname of the interpreter.
-
-Occasionally, a user's environment is so full that the /usr/bin/env
-program fails; or there's no env program at all.
-In that case, you can try the following hack (due to Alex Rezinsky)::
-
- #! /bin/sh
- """:"
- exec python $0 ${1+"$@"}
- """
-
-The minor disadvantage is that this defines the script's __doc__ string.
-However, you can fix that by adding ::
-
- __doc__ = """...Whatever..."""
-
-
-
-Is there a curses/termcap package for Python?
-----------------------------------------------------
-
-For Unix variants: The standard Python source distribution comes with
-a curses module in the Modules/ subdirectory, though it's not compiled
-by default (note that this is not available in the Windows
-distribution -- there is no curses module for Windows).
-
-The curses module supports basic curses features as well as many
-additional functions from ncurses and SYSV curses such as colour,
-alternative character set support, pads, and mouse support. This means
-the module isn't compatible with operating systems that only
-have BSD curses, but there don't seem to be any currently maintained
-OSes that fall into this category.
-
-For Windows: use `the consolelib module <http://effbot.org/zone/console-index.htm>`_.
-
-
-Is there an equivalent to C's onexit() in Python?
---------------------------------------------------------
-
-`The atexit module
-<http://www.python.org/doc/lib/module-atexit.html>`_ provides a
-register function that is similar to C's onexit.
-
-Why don't my signal handlers work?
---------------------------------------------
-The most common problem is that the signal handler is declared
-with the wrong argument list. It is called as ::
-
- handler(signum, frame)
-
-so it should be declared with two arguments::
-
- def handler(signum, frame):
- ...
-
-
-
-
-
-
-Common tasks
-=================
-
-How do I test a Python program or component?
-----------------------------------------------------
-
-Python comes with two testing frameworks. The `doctest module
-<http://www.python.org/doc/lib/module-doctest.html>`_ finds examples
-in the docstrings for a module and runs them, comparing the output
-with the expected output given in the docstring.
-
-The `unittest module
-<http://www.python.org/doc/lib/module-unittest.html>`_ is a fancier
-testing framework modelled on Java and Smalltalk testing frameworks.
-
-For testing, it helps to write the program so that it may be easily
-tested by using good modular design. Your program should have almost
-all functionality encapsulated in either functions or class methods --
-and this sometimes has the surprising and delightful effect of making
-the program run faster (because local variable accesses are faster
-than global accesses). Furthermore the program should avoid depending
-on mutating global variables, since this makes testing much more
-difficult to do.
-
-The "global main logic" of your program may be as simple
-as ::
-
- if __name__=="__main__":
- main_logic()
-
-at the bottom of the main module of your program.
-
-Once your program is organized as a tractable collection
-of functions and class behaviours you should write test
-functions that exercise the behaviours. A test suite
-can be associated with each module which automates
-a sequence of tests. This sounds like a lot of work, but
-since Python is so terse and flexible it's surprisingly easy.
-You can make coding much more pleasant and fun by
-writing your test functions in parallel with the "production
-code", since this makes it easy to find bugs and even
-design flaws earlier.
-
-"Support modules" that are not intended to be the main module of a
-program may include a self-test of the module. ::
-
- if __name__ == "__main__":
- self_test()
-
-Even programs that interact with complex external interfaces may be
-tested when the external interfaces are unavailable by using "fake"
-interfaces implemented in Python.
-
-How do I create documentation from doc strings?
--------------------------------------------------------
-
-The `pydoc module <http://www.python.org/doc/lib/module-pydoc.html>`_
-can create HTML from the doc strings in your Python source code. An
-alternative is `pythondoc
-<http://starship.python.net/crew/danilo/pythondoc/>`_.
-
-
-How do I get a single keypress at a time?
------------------------------------------------
-
-For Unix variants:There are several solutions.
-It's straightforward to do this using curses, but curses is a
-fairly large module to learn. Here's a solution without curses::
-
- import termios, fcntl, sys, os
- fd = sys.stdin.fileno()
-
- oldterm = termios.tcgetattr(fd)
- newattr = termios.tcgetattr(fd)
- newattr[3] = newattr[3] & ~termios.ICANON & ~termios.ECHO
- termios.tcsetattr(fd, termios.TCSANOW, newattr)
-
- oldflags = fcntl.fcntl(fd, fcntl.F_GETFL)
- fcntl.fcntl(fd, fcntl.F_SETFL, oldflags | os.O_NONBLOCK)
-
- try:
- while 1:
- try:
- c = sys.stdin.read(1)
- print "Got character", `c`
- except IOError: pass
- finally:
- termios.tcsetattr(fd, termios.TCSAFLUSH, oldterm)
- fcntl.fcntl(fd, fcntl.F_SETFL, oldflags)
-
-You need the ``termios`` and the ``fcntl`` module for any of this to work,
-and I've only tried it on Linux, though it should work elsewhere.
-In this code, characters are read and printed one at a time.
-
-``termios.tcsetattr()`` turns off stdin's echoing and disables canonical
-mode. ``fcntl.fnctl()`` is used to obtain stdin's file descriptor flags
-and modify them for non-blocking mode. Since reading stdin when it is
-empty results in an ``IOError``, this error is caught and ignored.
-
-
-Threads
-=============
-
-How do I program using threads?
----------------------------------
-
-Be sure to use `the threading module
-<http://www.python.org/doc/lib/module-threading.html>`_ and not the
-``thread`` module. The ``threading`` module builds convenient
-abstractions on top of the low-level primitives provided by the
-``thread`` module.
-
-Aahz has a set of slides from his threading tutorial that are helpful;
-see http://starship.python.net/crew/aahz/OSCON2001/.
-
-
-None of my threads seem to run: why?
--------------------------------------------
-
-As soon as the main thread exits, all threads are killed. Your main
-thread is running too quickly, giving the threads no time to do any work.
-
-A simple fix is to add a sleep to the end of the program
-that's long enough for all the threads to finish::
-
- import threading, time
-
- def thread_task(name, n):
- for i in range(n): print name, i
-
- for i in range(10):
- T = threading.Thread(target=thread_task, args=(str(i), i))
- T.start()
-
- time.sleep(10) # <----------------------------!
-
-But now (on many platforms) the threads don't run in parallel,
-but appear to run sequentially, one at a time! The reason is
-that the OS thread scheduler doesn't start a new thread until
-the previous thread is blocked.
-
-A simple fix is to add a tiny sleep to the start of the run
-function::
-
- def thread_task(name, n):
- time.sleep(0.001) # <---------------------!
- for i in range(n): print name, i
-
- for i in range(10):
- T = threading.Thread(target=thread_task, args=(str(i), i))
- T.start()
-
- time.sleep(10)
-
-Instead of trying to guess how long a ``time.sleep()`` delay will be
-enough, it's better to use some kind of semaphore mechanism. One idea
-is to use the `Queue module
-<http://www.python.org/doc/lib/module-Queue.html>`_ to create a queue
-object, let each thread append a token to the queue when it finishes,
-and let the main thread read as many tokens from the queue as there
-are threads.
-
-
-
-How do I parcel out work among a bunch of worker threads?
-----------------------------------------------------------------
-
-Use the `Queue module
-<http://www.python.org/doc/lib/module-Queue.html>`_ to create a queue
-containing a list of jobs. The ``Queue`` class maintains a list of
-objects with ``.put(obj)`` to add an item to the queue and ``.get()``
-to return an item. The class will take care of the locking necessary
-to ensure that each job is handed out exactly once.
-
-Here's a trivial example::
-
- import threading, Queue, time
-
- # The worker thread gets jobs off the queue. When the queue is empty, it
- # assumes there will be no more work and exits.
- # (Realistically workers will run until terminated.)
- def worker ():
- print 'Running worker'
- time.sleep(0.1)
- while True:
- try:
- arg = q.get(block=False)
- except Queue.Empty:
- print 'Worker', threading.currentThread(),
- print 'queue empty'
- break
- else:
- print 'Worker', threading.currentThread(),
- print 'running with argument', arg
- time.sleep(0.5)
-
- # Create queue
- q = Queue.Queue()
-
- # Start a pool of 5 workers
- for i in range(5):
- t = threading.Thread(target=worker, name='worker %i' % (i+1))
- t.start()
-
- # Begin adding work to the queue
- for i in range(50):
- q.put(i)
-
- # Give threads time to run
- print 'Main thread sleeping'
- time.sleep(5)
-
-When run, this will produce the following output:
-
- Running worker
- Running worker
- Running worker
- Running worker
- Running worker
- Main thread sleeping
- Worker <Thread(worker 1, started)> running with argument 0
- Worker <Thread(worker 2, started)> running with argument 1
- Worker <Thread(worker 3, started)> running with argument 2
- Worker <Thread(worker 4, started)> running with argument 3
- Worker <Thread(worker 5, started)> running with argument 4
- Worker <Thread(worker 1, started)> running with argument 5
- ...
-
-Consult the module's documentation for more details; the ``Queue``
-class provides a featureful interface.
-
-
-What kinds of global value mutation are thread-safe?
-------------------------------------------------------------
-
-A global interpreter lock (GIL) is used internally to ensure that only
-one thread runs in the Python VM at a time. In general, Python offers
-to switch among threads only between bytecode instructions; how
-frequently it switches can be set via ``sys.setcheckinterval()``.
-Each bytecode instruction and therefore all the C implementation code
-reached from each instruction is therefore atomic from the point of view of a Python program.
-
-In theory, this means an exact accounting requires an exact
-understanding of the PVM bytecode implementation. In practice, it
-means that operations on shared variables of builtin data types (ints,
-lists, dicts, etc) that "look atomic" really are.
-
-For example, the following operations are all atomic (L, L1, L2 are lists, D, D1, D2 are dicts, x, y
-are objects, i, j are ints)::
-
- L.append(x)
- L1.extend(L2)
- x = L[i]
- x = L.pop()
- L1[i:j] = L2
- L.sort()
- x = y
- x.field = y
- D[x] = y
- D1.update(D2)
- D.keys()
-
-These aren't::
-
- i = i+1
- L.append(L[-1])
- L[i] = L[j]
- D[x] = D[x] + 1
-
-Operations that replace other objects may invoke those other
-objects' ``__del__`` method when their reference count reaches zero, and
-that can affect things. This is especially true for the mass updates
-to dictionaries and lists. When in doubt, use a mutex!
-
-Can't we get rid of the Global Interpreter Lock?
---------------------------------------------------------
-
-The Global Interpreter Lock (GIL) is often seen as a hindrance to
-Python's deployment on high-end multiprocessor server machines,
-because a multi-threaded Python program effectively only uses one CPU,
-due to the insistence that (almost) all Python code can only run while
-the GIL is held.
-
-Back in the days of Python 1.5, Greg Stein actually implemented a
-comprehensive patch set (the "free threading" patches) that removed
-the GIL and replaced it with fine-grained locking. Unfortunately, even
-on Windows (where locks are very efficient) this ran ordinary Python
-code about twice as slow as the interpreter using the GIL. On Linux
-the performance loss was even worse because pthread locks aren't as
-efficient.
-
-Since then, the idea of getting rid of the GIL has occasionally come
-up but nobody has found a way to deal with the expected slowdown, and
-users who don't use threads would not be happy if their code ran at
-half at the speed. Greg's free threading patch set has not been kept
-up-to-date for later Python versions.
-
-This doesn't mean that you can't make good use of Python on multi-CPU
-machines! You just have to be creative with dividing the work up
-between multiple *processes* rather than multiple *threads*.
-Judicious use of C extensions will also help; if you use a C extension
-to perform a time-consuming task, the extension can release the GIL
-while the thread of execution is in the C code and allow other threads
-to get some work done.
-
-It has been suggested that the GIL should be a per-interpreter-state
-lock rather than truly global; interpreters then wouldn't be able to
-share objects. Unfortunately, this isn't likely to happen either. It
-would be a tremendous amount of work, because many object
-implementations currently have global state. For example, small
-integers and short strings are cached; these caches would have to be
-moved to the interpreter state. Other object types have their own
-free list; these free lists would have to be moved to the interpreter
-state. And so on.
-
-And I doubt that it can even be done in finite time, because the same
-problem exists for 3rd party extensions. It is likely that 3rd party
-extensions are being written at a faster rate than you can convert
-them to store all their global state in the interpreter state.
-
-And finally, once you have multiple interpreters not sharing any
-state, what have you gained over running each interpreter
-in a separate process?
-
-
-Input and Output
-=========================
-
-How do I delete a file? (And other file questions...)
----------------------------------------------------------
-
-Use ``os.remove(filename)`` or ``os.unlink(filename)``; for
-documentation, see `the POSIX module
-<http://www.python.org/doc/lib/module-posix.html>`_. The two
-functions are identical; ``unlink()`` is simply the name of the Unix
-system call for this function.
-
-To remove a directory, use ``os.rmdir()``; use ``os.mkdir()`` to
-create one. ``os.makedirs(path)`` will create any intermediate
-directories in ``path`` that don't exist. ``os.removedirs(path)`` will
-remove intermediate directories as long as they're empty; if you want
-to delete an entire directory tree and its contents, use
-``shutil.rmtree()``.
-
-To rename a file, use ``os.rename(old_path, new_path)``.
-
-To truncate a file, open it using ``f = open(filename, "r+")``, and use
-``f.truncate(offset)``; offset defaults to the current seek position.
-There's also ```os.ftruncate(fd, offset)`` for files opened with ``os.open()``,
-where ``fd`` is the file descriptor (a small integer).
-
-The ``shutil`` module also contains a number of functions to work on files
-including ``copyfile``, ``copytree``, and ``rmtree``.
-
-How do I copy a file?
------------------------------
-
-The ``shutil`` module contains a ``copyfile()`` function. Note that
-on MacOS 9 it doesn't copy the resource fork and Finder info.
-
-
-How do I read (or write) binary data?
----------------------------------------------
-
-or complex data formats, it's best to use `the struct module
-<http://www.python.org/doc/lib/module-struct.html>`_. It allows you
-to take a string containing binary data (usually numbers) and convert
-it to Python objects; and vice versa.
-
-For example, the following code reads two 2-byte integers
-and one 4-byte integer in big-endian format from a file::
-
- import struct
-
- f = open(filename, "rb") # Open in binary mode for portability
- s = f.read(8)
- x, y, z = struct.unpack(">hhl", s)
-
-The '>' in the format string forces big-endian data; the letter
-'h' reads one "short integer" (2 bytes), and 'l' reads one
-"long integer" (4 bytes) from the string.
-
-For data that is more regular (e.g. a homogeneous list of ints or
-thefloats), you can also use `the array module <http://www.python.org/doc/lib/module-array.html>`_.
-
-I can't seem to use os.read() on a pipe created with os.popen(); why?
-------------------------------------------------------------------------
-
-``os.read()`` is a low-level function which takes a file descriptor, a
-small integer representing the opened file. ``os.popen()`` creates a
-high-level file object, the same type returned by the builtin
-``open()`` function. Thus, to read n bytes from a pipe p created with
-``os.popen()``, you need to use ``p.read(n)``.
-
-How do I run a subprocess with pipes connected to both input and output?
---------------------------------------------------------------------------------
-Use `the popen2 module
-<http://www.python.org/doc/lib/module-popen2.html>`_. For example::
-
- import popen2
- fromchild, tochild = popen2.popen2("command")
- tochild.write("input\n")
- tochild.flush()
- output = fromchild.readline()
-
-Warning: in general it is unwise to do this because you can easily
-cause a deadlock where your process is blocked waiting for output from
-the child while the child is blocked waiting for input from you. This
-can be caused because the parent expects the child to output more text
-than it does, or it can be caused by data being stuck in stdio buffers
-due to lack of flushing. The Python parent can of course explicitly
-flush the data it sends to the child before it reads any output, but
-if the child is a naive C program it may have been written to never
-explicitly flush its output, even if it is interactive, since flushing
-is normally automatic.
-
-Note that a deadlock is also possible if you use ``popen3`` to read
-stdout and stderr. If one of the two is too large for the internal
-buffer (increasing the buffer size does not help) and you ``read()``
-the other one first, there is a deadlock, too.
-
-Note on a bug in popen2: unless your program calls ``wait()``
-or ``waitpid()``, finished child processes are never removed,
-and eventually calls to popen2 will fail because of a limit on
-the number of child processes. Calling ``os.waitpid`` with the
-``os.WNOHANG`` option can prevent this; a good place to insert such
-a call would be before calling ``popen2`` again.
-
-In many cases, all you really need is to run some data through a
-command and get the result back. Unless the amount of data is very
-large, the easiest way to do this is to write it to a temporary file
-and run the command with that temporary file as input. The `standard
-module tempfile <http://www.python.org/doc/lib/module-tempfile.html>`_
-exports a ``mktemp()`` function to generate unique temporary file names. ::
-
- import tempfile
- import os
- class Popen3:
- """
- This is a deadlock-safe version of popen that returns
- an object with errorlevel, out (a string) and err (a string).
- (capturestderr may not work under windows.)
- Example: print Popen3('grep spam','\n\nhere spam\n\n').out
- """
- def __init__(self,command,input=None,capturestderr=None):
- outfile=tempfile.mktemp()
- command="( %s ) > %s" % (command,outfile)
- if input:
- infile=tempfile.mktemp()
- open(infile,"w").write(input)
- command=command+" <"+infile
- if capturestderr:
- errfile=tempfile.mktemp()
- command=command+" 2>"+errfile
- self.errorlevel=os.system(command) >> 8
- self.out=open(outfile,"r").read()
- os.remove(outfile)
- if input:
- os.remove(infile)
- if capturestderr:
- self.err=open(errfile,"r").read()
- os.remove(errfile)
-
-Note that many interactive programs (e.g. vi) don't work well with
-pipes substituted for standard input and output. You will have to use
-pseudo ttys ("ptys") instead of pipes. Or you can use a Python
-interface to Don Libes' "expect" library. A Python extension that
-interfaces to expect is called "expy" and available from
-http://expectpy.sourceforge.net. A pure Python solution that works
-like expect is ` pexpect <http://pexpect.sourceforge.net>`_.
-
-
-How do I access the serial (RS232) port?
-------------------------------------------------
-For Win32, POSIX (Linux, BSD, etc.), Jython:
-
- http://pyserial.sourceforge.net
-
-For Unix, see a Usenet post by Mitch Chapman:
-
- http://groups.google.com/groups?selm=34A04430.CF9@ohioee.com
-
-
-Why doesn't closing sys.stdout (stdin, stderr) really close it?
------------------------------------------------------------------------
-
-Python file objects are a high-level layer of abstraction on top of C
-streams, which in turn are a medium-level layer of abstraction on top
-of (among other things) low-level C file descriptors.
-
-For most file objects you create in Python via the builtin ``file``
-constructor, ``f.close()`` marks the Python file object as being closed
-from Python's point of view, and also arranges to close the underlying
-C stream. This also happens automatically in f's destructor, when f
-becomes garbage.
-
-But stdin, stdout and stderr are treated specially by Python, because
-of the special status also given to them by C. Running
-``sys.stdout.close()`` marks the Python-level file object as being
-closed, but does *not* close the associated C stream.
-
-To close the underlying C stream for one of these three, you should
-first be sure that's what you really want to do (e.g., you may confuse
-extension modules trying to do I/O). If it is, use
-os.close::
-
- os.close(0) # close C's stdin stream
- os.close(1) # close C's stdout stream
- os.close(2) # close C's stderr stream
-
-
-
-Network/Internet Programming
-=======================================
-
-What WWW tools are there for Python?
---------------------------------------------
-
-See the chapters titled `"Internet Protocols and Support"
-<http://www.python.org/doc/lib/internet.html>`_ and `"Internet Data
-Handling" <http://www.python.org/doc/lib/netdata.html>`_ in the
-Library Reference Manual. Python has many modules that will help you
-build server-side and client-side web systems.
-
-A summary of available frameworks is maintained by Paul Boddie at
-http://www.python.org/cgi-bin/moinmoin/WebProgramming .
-
-Cameron Laird maintains a useful set of pages about Python web technologies at
-http://phaseit.net/claird/comp.lang.python/web_python.html.
-
-The `Web Programming topic guide <http://www.python.org/topics/web/>`_
-also points to many useful resources.
-
-
-How can I mimic CGI form submission (METHOD=POST)?
-----------------------------------------------------------
-I would like to retrieve web pages that are the result of POSTing a
-form. Is there existing code that would let me do this easily?
-
-Yes. Here's a simple example that uses httplib::
-
- #!/usr/local/bin/python
-
- import httplib, sys, time
-
- ### build the query string
- qs = "First=Josephine&MI=Q&Last=Public"
-
- ### connect and send the server a path
- httpobj = httplib.HTTP('www.some-server.out-there', 80)
- httpobj.putrequest('POST', '/cgi-bin/some-cgi-script')
- ### now generate the rest of the HTTP headers...
- httpobj.putheader('Accept', '*/*')
- httpobj.putheader('Connection', 'Keep-Alive')
- httpobj.putheader('Content-type', 'application/x-www-form-urlencoded')
- httpobj.putheader('Content-length', '%d' % len(qs))
- httpobj.endheaders()
- httpobj.send(qs)
- ### find out what the server said in response...
- reply, msg, hdrs = httpobj.getreply()
- if reply != 200:
- sys.stdout.write(httpobj.getfile().read())
-
-Note that in general for URL-encoded POST operations, query
-strings must be quoted by using ``urllib.quote()``. For example to send name="Guy
-Steele, Jr."::
-
- >>> from urllib import quote
- >>> x = quote("Guy Steele, Jr.")
- >>> x
- 'Guy%20Steele,%20Jr.'
- >>> query_string = "name="+x
- >>> query_string
- 'name=Guy%20Steele,%20Jr.'
-
-
-What module should I use to help with generating HTML?
---------------------------------------------------------------
-
-There are many different modules available:
-
-* HTMLgen is a class library of objects corresponding to all the HTML
- 3.2 markup tags. It's used when you are writing in Python and wish
- to synthesize HTML pages for generating a web or for CGI forms, etc.
-* DocumentTemplate and Zope Page Templates are two different systems that are
- part of Zope.
-* Quixote's PTL uses Python syntax to assemble strings of text.
-
-Consult the `Web Programming topic guide
-<http://www.python.org/topics/web/>`_ for more links.
-
-
-How do I send mail from a Python script?
-------------------------------------------------
-
-Use `the standard library module smtplib
-<http://www.python.org/doc/lib/module-smtplib.html>`_.
-
-Here's a very simple interactive mail sender that uses it. This
-method will work on any host that supports an SMTP listener. ::
-
- import sys, smtplib
-
- fromaddr = raw_input("From: ")
- toaddrs = raw_input("To: ").split(',')
- print "Enter message, end with ^D:"
- msg = ''
- while 1:
- line = sys.stdin.readline()
- if not line:
- break
- msg = msg + line
-
- # The actual mail send
- server = smtplib.SMTP('localhost')
- server.sendmail(fromaddr, toaddrs, msg)
- server.quit()
-
-A Unix-only alternative uses sendmail. The location of the
-sendmail program varies between systems; sometimes it is
-``/usr/lib/sendmail``, sometime ``/usr/sbin/sendmail``. The sendmail
-manual page will help you out. Here's some sample code::
-
- SENDMAIL = "/usr/sbin/sendmail" # sendmail location
- import os
- p = os.popen("%s -t -i" % SENDMAIL, "w")
- p.write("To: receiver@example.com\n")
- p.write("Subject: test\n")
- p.write("\n") # blank line separating headers from body
- p.write("Some text\n")
- p.write("some more text\n")
- sts = p.close()
- if sts != 0:
- print "Sendmail exit status", sts
-
-
-How do I avoid blocking in the connect() method of a socket?
---------------------------------------------------------------------------
-The select module is commonly used to help with asynchronous
-I/O on sockets.
-
-To prevent the TCP connect from blocking, you can set the socket to
-non-blocking mode. Then when you do the ``connect()``, you will
-either connect immediately (unlikely) or get an exception that
-contains the error number as ``.errno``. ``errno.EINPROGRESS``
-indicates that the connection is in progress, but hasn't finished yet.
-Different OSes will return different values, so you're going to have
-to check what's returned on your system.
-
-You can use the ``connect_ex()`` method to avoid creating an
-exception. It will just return the errno value. To poll, you can
-call ``connect_ex()`` again later -- 0 or ``errno.EISCONN`` indicate
-that you're connected -- or you can pass this socket to select to
-check if it's writeable.
-
-
-Databases
-=====================
-
-Are there any interfaces to database packages in Python?
-----------------------------------------------------------------
-
-Yes.
-
-Python 2.3 includes the ``bsddb`` package which provides an interface
-to the `BerkeleyDB
-<http://www.python.org/doc/lib/module-bsddb.html>`_ library.
-Interfaces to disk-based hashes such as `DBM
-<http://www.python.org/doc/lib/module-dbm.html>`_ and `GDBM
-<http://www.python.org/doc/lib/module-gdbm.html>`_ are also included
-with standard Python.
-
-Support for most relational databases is available. See the `Database
-Topic Guide <http://www.python.org/topics/database>`_ for details.
-
-
-How do you implement persistent objects in Python?
-------------------------------------------------------------
-
-The `pickle library module
-<http://www.python.org/doc/lib/module-pickle.html>`_ solves this in a
-very general way (though you still can't store things like open files,
-sockets or windows), and the `shelve library module
-<http://www.python.org/doc/lib/module-shelve.html>`_ uses pickle and
-(g)dbm to create persistent mappings containing arbitrary Python
-objects. For better performance, you can use
-`the cPickle module <http://www.python.org/doc/lib/module-cPickle.html>`_.
-
-A more awkward way of doing things is to use pickle's little sister,
-marshal. `The marshal module
-<http://www.python.org/doc/lib/module-marshal.html>`_ provides very
-fast ways to store noncircular basic Python types to files and
-strings, and back again. Although marshal does not do fancy things
-like store instances or handle shared references properly, it does run
-extremely fast. For example loading a half megabyte of data may take
-less than a third of a second. This often beats doing something more
-complex and general such as using gdbm with pickle/shelve.
-
-
-Why is cPickle so slow?
---------------------------------
-
-The default format used by the pickle module is a slow one that
-results in readable pickles. Making it the default, but it would
-break backward compatibility::
-
- largeString = 'z' * (100 * 1024)
- myPickle = cPickle.dumps(largeString, protocol=1)
-
-
-
-
-If my program crashes with a bsddb (or anydbm) database open, it gets corrupted. How come?
---------------------------------------------------------------------------------------------------
-
-Databases opened for write access with the bsddb module (and often by
-the anydbm module, since it will preferentially use bsddb) must
-explicitly be closed using the ``.close()`` method of the database. The
-underlying library caches database contents which need to be
-converted to on-disk form and written.
-
-If you have initialized a new bsddb database but not written anything to
-it before the program crashes, you will often wind up with a zero-length
-file and encounter an exception the next time the file is opened.
-
-
-I tried to open Berkeley DB file, but bsddb produces bsddb.error: (22, 'Invalid argument'). Help! How can I restore my data?
-------------------------------------------------------------------------------------------------------------------------------------
-
-Don't panic! Your data is probably intact. The most frequent cause
-for the error is that you tried to open an earlier Berkeley DB file
-with a later version of the Berkeley DB library.
-
-Many Linux systems now have all three versions of Berkeley DB
-available. If you are migrating from version 1 to a newer version use
-db_dump185 to dump a plain text version of the database.
-If you are migrating from version 2 to version 3 use db2_dump to create
-a plain text version of the database. In either case, use db_load to
-create a new native database for the latest version installed on your
-computer. If you have version 3 of Berkeley DB installed, you should
-be able to use db2_load to create a native version 2 database.
-
-You should move away from Berkeley DB version 1 files because
-the hash file code contains known bugs that can corrupt your data.
-
-
-Mathematics and Numerics
-================================
-
-How do I generate random numbers in Python?
----------------------------------------------------
-The `standard module random <http://www.python.org/doc/lib/module-random.html>`_ implements a random number
-generator. Usage is simple::
-
- import random
- random.random()
-
-This returns a random floating point number in the range [0, 1).
-
-There are also many other specialized generators in this module, such
-as:
-
-* ``randrange(a, b)`` chooses an integer in the range [a, b).
-* ``uniform(a, b)`` chooses a floating point number in the range [a, b).
-* ``normalvariate(mean, sdev)`` samples the normal (Gaussian) distribution.
-
-Some higher-level functions operate on sequences directly, such as:
-
-* ``choice(S)`` chooses random element from a given sequence
-* ``shuffle(L)`` shuffles a list in-place, i.e. permutes it randomly
-
-There's also a ``Random`` class you can instantiate
-to create independent multiple random number generators.
-
diff --git a/faq/library.html b/faq/library.html
deleted file mode 100644
index 3d9ea4a..0000000
--- a/faq/library.html
+++ /dev/null
@@ -1,1193 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
-<title>Python Library and Extension FAQ</title>
-<meta name="date" content="2005-12-16" />
-<style type="text/css">
-
-/*
-:Author: David Goodger (goodger@python.org)
-:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
- border: 0 }
-
-table.borderless td, table.borderless th {
- /* Override padding for "table.docutils td" with "! important".
- The right padding separates the table cells. */
- padding: 0 0.5em 0 0 ! important }
-
-.first {
- /* Override more specific margin styles with "! important". */
- margin-top: 0 ! important }
-
-.last, .with-subtitle {
- margin-bottom: 0 ! important }
-
-.hidden {
- display: none }
-
-a.toc-backref {
- text-decoration: none ;
- color: black }
-
-blockquote.epigraph {
- margin: 2em 5em ; }
-
-dl.docutils dd {
- margin-bottom: 0.5em }
-
-object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
- overflow: hidden;
-}
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
- font-weight: bold }
-*/
-
-div.abstract {
- margin: 2em 5em }
-
-div.abstract p.topic-title {
- font-weight: bold ;
- text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
- margin: 2em ;
- border: medium outset ;
- padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title, .code .error {
- color: red ;
- font-weight: bold ;
- font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
- compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
- margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
- margin-top: 0.5em }
-*/
-
-div.dedication {
- margin: 2em 5em ;
- text-align: center ;
- font-style: italic }
-
-div.dedication p.topic-title {
- font-weight: bold ;
- font-style: normal }
-
-div.figure {
- margin-left: 2em ;
- margin-right: 2em }
-
-div.footer, div.header {
- clear: both;
- font-size: smaller }
-
-div.line-block {
- display: block ;
- margin-top: 1em ;
- margin-bottom: 1em }
-
-div.line-block div.line-block {
- margin-top: 0 ;
- margin-bottom: 0 ;
- margin-left: 1.5em }
-
-div.sidebar {
- margin: 0 0 0.5em 1em ;
- border: medium outset ;
- padding: 1em ;
- background-color: #ffffee ;
- width: 40% ;
- float: right ;
- clear: right }
-
-div.sidebar p.rubric {
- font-family: sans-serif ;
- font-size: medium }
-
-div.system-messages {
- margin: 5em }
-
-div.system-messages h1 {
- color: red }
-
-div.system-message {
- border: medium outset ;
- padding: 1em }
-
-div.system-message p.system-message-title {
- color: red ;
- font-weight: bold }
-
-div.topic {
- margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
- margin-top: 0.4em }
-
-h1.title {
- text-align: center }
-
-h2.subtitle {
- text-align: center }
-
-hr.docutils {
- width: 75% }
-
-img.align-left, .figure.align-left, object.align-left {
- clear: left ;
- float: left ;
- margin-right: 1em }
-
-img.align-right, .figure.align-right, object.align-right {
- clear: right ;
- float: right ;
- margin-left: 1em }
-
-img.align-center, .figure.align-center, object.align-center {
- display: block;
- margin-left: auto;
- margin-right: auto;
-}
-
-.align-left {
- text-align: left }
-
-.align-center {
- clear: both ;
- text-align: center }
-
-.align-right {
- text-align: right }
-
-/* reset inner alignment in figures */
-div.align-right {
- text-align: inherit }
-
-/* div.align-center * { */
-/* text-align: left } */
-
-ol.simple, ul.simple {
- margin-bottom: 1em }
-
-ol.arabic {
- list-style: decimal }
-
-ol.loweralpha {
- list-style: lower-alpha }
-
-ol.upperalpha {
- list-style: upper-alpha }
-
-ol.lowerroman {
- list-style: lower-roman }
-
-ol.upperroman {
- list-style: upper-roman }
-
-p.attribution {
- text-align: right ;
- margin-left: 50% }
-
-p.caption {
- font-style: italic }
-
-p.credits {
- font-style: italic ;
- font-size: smaller }
-
-p.label {
- white-space: nowrap }
-
-p.rubric {
- font-weight: bold ;
- font-size: larger ;
- color: maroon ;
- text-align: center }
-
-p.sidebar-title {
- font-family: sans-serif ;
- font-weight: bold ;
- font-size: larger }
-
-p.sidebar-subtitle {
- font-family: sans-serif ;
- font-weight: bold }
-
-p.topic-title {
- font-weight: bold }
-
-pre.address {
- margin-bottom: 0 ;
- margin-top: 0 ;
- font: inherit }
-
-pre.literal-block, pre.doctest-block, pre.math, pre.code {
- margin-left: 2em ;
- margin-right: 2em }
-
-pre.code .ln { color: grey; } /* line numbers */
-pre.code, code { background-color: #eeeeee }
-pre.code .comment, code .comment { color: #5C6576 }
-pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
-pre.code .literal.string, code .literal.string { color: #0C5404 }
-pre.code .name.builtin, code .name.builtin { color: #352B84 }
-pre.code .deleted, code .deleted { background-color: #DEB0A1}
-pre.code .inserted, code .inserted { background-color: #A3D289}
-
-span.classifier {
- font-family: sans-serif ;
- font-style: oblique }
-
-span.classifier-delimiter {
- font-family: sans-serif ;
- font-weight: bold }
-
-span.interpreted {
- font-family: sans-serif }
-
-span.option {
- white-space: nowrap }
-
-span.pre {
- white-space: pre }
-
-span.problematic {
- color: red }
-
-span.section-subtitle {
- /* font-size relative to parent (h1..h6 element) */
- font-size: 80% }
-
-table.citation {
- border-left: solid 1px gray;
- margin-left: 1px }
-
-table.docinfo {
- margin: 2em 4em }
-
-table.docutils {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
-
-table.footnote {
- border-left: solid 1px black;
- margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
- padding-left: 0.5em ;
- padding-right: 0.5em ;
- vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
- font-weight: bold ;
- text-align: left ;
- white-space: nowrap ;
- padding-left: 0 }
-
-/* "booktabs" style (no vertical lines) */
-table.docutils.booktabs {
- border: 0px;
- border-top: 2px solid;
- border-bottom: 2px solid;
- border-collapse: collapse;
-}
-table.docutils.booktabs * {
- border: 0px;
-}
-table.docutils.booktabs th {
- border-bottom: thin solid;
- text-align: left;
-}
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
- font-size: 100% }
-
-ul.auto-toc {
- list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="python-library-and-extension-faq">
-<h1 class="title">Python Library and Extension FAQ</h1>
-<table class="docinfo" frame="void" rules="none">
-<col class="docinfo-name" />
-<col class="docinfo-content" />
-<tbody valign="top">
-<tr><th class="docinfo-name">Date:</th>
-<td>2005-12-16</td></tr>
-<tr><th class="docinfo-name">Version:</th>
-<td>8684</td></tr>
-<tr class="field"><th class="docinfo-name">Web site:</th><td class="field-body"><a class="reference external" href="http://www.python.org/">http://www.python.org/</a></td>
-</tr>
-</tbody>
-</table>
-<div class="contents topic" id="contents">
-<p class="topic-title first">Contents</p>
-<ul class="auto-toc simple">
-<li><a class="reference internal" href="#general-library-questions" id="id3">1 General Library Questions</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-do-i-find-a-module-or-application-to-perform-task-x" id="id4">1.1 How do I find a module or application to perform task X?</a></li>
-<li><a class="reference internal" href="#where-is-the-math-py-socket-py-regex-py-etc-source-file" id="id5">1.2 Where is the math.py (socket.py, regex.py, etc.) source file?</a></li>
-<li><a class="reference internal" href="#how-do-i-make-a-python-script-executable-on-unix" id="id6">1.3 How do I make a Python script executable on Unix?</a></li>
-<li><a class="reference internal" href="#is-there-a-curses-termcap-package-for-python" id="id7">1.4 Is there a curses/termcap package for Python?</a></li>
-<li><a class="reference internal" href="#is-there-an-equivalent-to-c-s-onexit-in-python" id="id8">1.5 Is there an equivalent to C's onexit() in Python?</a></li>
-<li><a class="reference internal" href="#why-don-t-my-signal-handlers-work" id="id9">1.6 Why don't my signal handlers work?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#common-tasks" id="id10">2 Common tasks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-do-i-test-a-python-program-or-component" id="id11">2.1 How do I test a Python program or component?</a></li>
-<li><a class="reference internal" href="#how-do-i-create-documentation-from-doc-strings" id="id12">2.2 How do I create documentation from doc strings?</a></li>
-<li><a class="reference internal" href="#how-do-i-get-a-single-keypress-at-a-time" id="id13">2.3 How do I get a single keypress at a time?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#threads" id="id14">3 Threads</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-do-i-program-using-threads" id="id15">3.1 How do I program using threads?</a></li>
-<li><a class="reference internal" href="#none-of-my-threads-seem-to-run-why" id="id16">3.2 None of my threads seem to run: why?</a></li>
-<li><a class="reference internal" href="#how-do-i-parcel-out-work-among-a-bunch-of-worker-threads" id="id17">3.3 How do I parcel out work among a bunch of worker threads?</a></li>
-<li><a class="reference internal" href="#what-kinds-of-global-value-mutation-are-thread-safe" id="id18">3.4 What kinds of global value mutation are thread-safe?</a></li>
-<li><a class="reference internal" href="#can-t-we-get-rid-of-the-global-interpreter-lock" id="id19">3.5 Can't we get rid of the Global Interpreter Lock?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#input-and-output" id="id20">4 Input and Output</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-do-i-delete-a-file-and-other-file-questions" id="id21">4.1 How do I delete a file? (And other file questions...)</a></li>
-<li><a class="reference internal" href="#how-do-i-copy-a-file" id="id22">4.2 How do I copy a file?</a></li>
-<li><a class="reference internal" href="#how-do-i-read-or-write-binary-data" id="id23">4.3 How do I read (or write) binary data?</a></li>
-<li><a class="reference internal" href="#i-can-t-seem-to-use-os-read-on-a-pipe-created-with-os-popen-why" id="id24">4.4 I can't seem to use os.read() on a pipe created with os.popen(); why?</a></li>
-<li><a class="reference internal" href="#how-do-i-run-a-subprocess-with-pipes-connected-to-both-input-and-output" id="id25">4.5 How do I run a subprocess with pipes connected to both input and output?</a></li>
-<li><a class="reference internal" href="#how-do-i-access-the-serial-rs232-port" id="id26">4.6 How do I access the serial (RS232) port?</a></li>
-<li><a class="reference internal" href="#why-doesn-t-closing-sys-stdout-stdin-stderr-really-close-it" id="id27">4.7 Why doesn't closing sys.stdout (stdin, stderr) really close it?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#network-internet-programming" id="id28">5 Network/Internet Programming</a><ul class="auto-toc">
-<li><a class="reference internal" href="#what-www-tools-are-there-for-python" id="id29">5.1 What WWW tools are there for Python?</a></li>
-<li><a class="reference internal" href="#how-can-i-mimic-cgi-form-submission-method-post" id="id30">5.2 How can I mimic CGI form submission (METHOD=POST)?</a></li>
-<li><a class="reference internal" href="#what-module-should-i-use-to-help-with-generating-html" id="id31">5.3 What module should I use to help with generating HTML?</a></li>
-<li><a class="reference internal" href="#how-do-i-send-mail-from-a-python-script" id="id32">5.4 How do I send mail from a Python script?</a></li>
-<li><a class="reference internal" href="#how-do-i-avoid-blocking-in-the-connect-method-of-a-socket" id="id33">5.5 How do I avoid blocking in the connect() method of a socket?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#databases" id="id34">6 Databases</a><ul class="auto-toc">
-<li><a class="reference internal" href="#are-there-any-interfaces-to-database-packages-in-python" id="id35">6.1 Are there any interfaces to database packages in Python?</a></li>
-<li><a class="reference internal" href="#how-do-you-implement-persistent-objects-in-python" id="id36">6.2 How do you implement persistent objects in Python?</a></li>
-<li><a class="reference internal" href="#why-is-cpickle-so-slow" id="id37">6.3 Why is cPickle so slow?</a></li>
-<li><a class="reference internal" href="#if-my-program-crashes-with-a-bsddb-or-anydbm-database-open-it-gets-corrupted-how-come" id="id38">6.4 If my program crashes with a bsddb (or anydbm) database open, it gets corrupted. How come?</a></li>
-<li><a class="reference internal" href="#i-tried-to-open-berkeley-db-file-but-bsddb-produces-bsddb-error-22-invalid-argument-help-how-can-i-restore-my-data" id="id39">6.5 I tried to open Berkeley DB file, but bsddb produces bsddb.error: (22, 'Invalid argument'). Help! How can I restore my data?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#mathematics-and-numerics" id="id40">7 Mathematics and Numerics</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-do-i-generate-random-numbers-in-python" id="id41">7.1 How do I generate random numbers in Python?</a></li>
-</ul>
-</li>
-</ul>
-</div>
-<div class="section" id="general-library-questions">
-<h1><a class="toc-backref" href="#id3">1 General Library Questions</a></h1>
-<div class="section" id="how-do-i-find-a-module-or-application-to-perform-task-x">
-<h2><a class="toc-backref" href="#id4">1.1 How do I find a module or application to perform task X?</a></h2>
-<p>Check <a class="reference external" href="http://www.python.org/doc/lib/">the Library Reference</a> to see
-if there's a relevant standard library module. (Eventually you'll
-learn what's in the standard library and will able to skip this step.)</p>
-<p>Search the <a class="reference external" href="http://cheeseshop.python.org/pypi">Python Package Index</a>.</p>
-<p>Next, check the <a class="reference external" href="http://www.vex.net/parnassus/">Vaults of Parnassus</a>,
-an older index of packages.</p>
-<p>Finally, try <a class="reference external" href="http://www.google.com">Google</a> or other Web search
-engine. Searching for "Python" plus a keyword or two for your topic
-of interest will usually find something helpful.</p>
-</div>
-<div class="section" id="where-is-the-math-py-socket-py-regex-py-etc-source-file">
-<h2><a class="toc-backref" href="#id5">1.2 Where is the math.py (socket.py, regex.py, etc.) source file?</a></h2>
-<p>If you can't find a source file for a module it may be a builtin
-or dynamically loaded module implemented in C, C++ or other
-compiled language. In this case you may not have the source
-file or it may be something like mathmodule.c, somewhere in
-a C source directory (not on the Python Path).</p>
-<p>There are (at least) three kinds of modules in Python:</p>
-<ol class="arabic">
-<li><p class="first">modules written in Python (.py);</p>
-</li>
-<li><p class="first">modules written in C and dynamically loaded (.dll, .pyd, .so, .sl, etc);</p>
-</li>
-<li><p class="first">modules written in C and linked with the interpreter; to get a list
-of these, type:</p>
-<pre class="literal-block">
-import sys
-print sys.builtin_module_names
-</pre>
-</li>
-</ol>
-</div>
-<div class="section" id="how-do-i-make-a-python-script-executable-on-unix">
-<h2><a class="toc-backref" href="#id6">1.3 How do I make a Python script executable on Unix?</a></h2>
-<p>You need to do two things: the script file's mode must be executable
-and the first line must begin with <tt class="docutils literal">#!</tt> followed by the path of
-the Python interpreter.</p>
-<p>The first is done by executing <tt class="docutils literal">chmod +x scriptfile</tt> or perhaps
-<tt class="docutils literal">chmod 755 scriptfile</tt>.</p>
-<p>The second can be done in a number of ways. The most straightforward
-way is to write</p>
-<pre class="literal-block">
-#!/usr/local/bin/python
-</pre>
-<p>as the very first line of your file, using the pathname for where the
-Python interpreter is installed on your platform.</p>
-<p>If you would like the script to be independent of where the Python
-interpreter lives, you can use the "env" program. Almost all
-Unix variants support the following, assuming the python interpreter
-is in a directory on the user's $PATH:</p>
-<pre class="literal-block">
-#! /usr/bin/env python
-</pre>
-<p><em>Don't</em> do this for CGI scripts. The $PATH variable for
-CGI scripts is often very minimal, so you need to use the actual
-absolute pathname of the interpreter.</p>
-<p>Occasionally, a user's environment is so full that the /usr/bin/env
-program fails; or there's no env program at all.
-In that case, you can try the following hack (due to Alex Rezinsky):</p>
-<pre class="literal-block">
-#! /bin/sh
-""":"
-exec python $0 ${1+"$@"}
-"""
-</pre>
-<p>The minor disadvantage is that this defines the script's __doc__ string.
-However, you can fix that by adding</p>
-<pre class="literal-block">
-__doc__ = """...Whatever..."""
-</pre>
-</div>
-<div class="section" id="is-there-a-curses-termcap-package-for-python">
-<h2><a class="toc-backref" href="#id7">1.4 Is there a curses/termcap package for Python?</a></h2>
-<p>For Unix variants: The standard Python source distribution comes with
-a curses module in the Modules/ subdirectory, though it's not compiled
-by default (note that this is not available in the Windows
-distribution -- there is no curses module for Windows).</p>
-<p>The curses module supports basic curses features as well as many
-additional functions from ncurses and SYSV curses such as colour,
-alternative character set support, pads, and mouse support. This means
-the module isn't compatible with operating systems that only
-have BSD curses, but there don't seem to be any currently maintained
-OSes that fall into this category.</p>
-<p>For Windows: use <a class="reference external" href="http://effbot.org/zone/console-index.htm">the consolelib module</a>.</p>
-</div>
-<div class="section" id="is-there-an-equivalent-to-c-s-onexit-in-python">
-<h2><a class="toc-backref" href="#id8">1.5 Is there an equivalent to C's onexit() in Python?</a></h2>
-<p><a class="reference external" href="http://www.python.org/doc/lib/module-atexit.html">The atexit module</a> provides a
-register function that is similar to C's onexit.</p>
-</div>
-<div class="section" id="why-don-t-my-signal-handlers-work">
-<h2><a class="toc-backref" href="#id9">1.6 Why don't my signal handlers work?</a></h2>
-<p>The most common problem is that the signal handler is declared
-with the wrong argument list. It is called as</p>
-<pre class="literal-block">
-handler(signum, frame)
-</pre>
-<p>so it should be declared with two arguments:</p>
-<pre class="literal-block">
-def handler(signum, frame):
- ...
-</pre>
-</div>
-</div>
-<div class="section" id="common-tasks">
-<h1><a class="toc-backref" href="#id10">2 Common tasks</a></h1>
-<div class="section" id="how-do-i-test-a-python-program-or-component">
-<h2><a class="toc-backref" href="#id11">2.1 How do I test a Python program or component?</a></h2>
-<p>Python comes with two testing frameworks. The <a class="reference external" href="http://www.python.org/doc/lib/module-doctest.html">doctest module</a> finds examples
-in the docstrings for a module and runs them, comparing the output
-with the expected output given in the docstring.</p>
-<p>The <a class="reference external" href="http://www.python.org/doc/lib/module-unittest.html">unittest module</a> is a fancier
-testing framework modelled on Java and Smalltalk testing frameworks.</p>
-<p>For testing, it helps to write the program so that it may be easily
-tested by using good modular design. Your program should have almost
-all functionality encapsulated in either functions or class methods --
-and this sometimes has the surprising and delightful effect of making
-the program run faster (because local variable accesses are faster
-than global accesses). Furthermore the program should avoid depending
-on mutating global variables, since this makes testing much more
-difficult to do.</p>
-<p>The "global main logic" of your program may be as simple
-as</p>
-<pre class="literal-block">
-if __name__=="__main__":
- main_logic()
-</pre>
-<p>at the bottom of the main module of your program.</p>
-<p>Once your program is organized as a tractable collection
-of functions and class behaviours you should write test
-functions that exercise the behaviours. A test suite
-can be associated with each module which automates
-a sequence of tests. This sounds like a lot of work, but
-since Python is so terse and flexible it's surprisingly easy.
-You can make coding much more pleasant and fun by
-writing your test functions in parallel with the "production
-code", since this makes it easy to find bugs and even
-design flaws earlier.</p>
-<p>"Support modules" that are not intended to be the main module of a
-program may include a self-test of the module.</p>
-<pre class="literal-block">
-if __name__ == "__main__":
- self_test()
-</pre>
-<p>Even programs that interact with complex external interfaces may be
-tested when the external interfaces are unavailable by using "fake"
-interfaces implemented in Python.</p>
-</div>
-<div class="section" id="how-do-i-create-documentation-from-doc-strings">
-<h2><a class="toc-backref" href="#id12">2.2 How do I create documentation from doc strings?</a></h2>
-<p>The <a class="reference external" href="http://www.python.org/doc/lib/module-pydoc.html">pydoc module</a>
-can create HTML from the doc strings in your Python source code. An
-alternative is <a class="reference external" href="http://starship.python.net/crew/danilo/pythondoc/">pythondoc</a>.</p>
-</div>
-<div class="section" id="how-do-i-get-a-single-keypress-at-a-time">
-<h2><a class="toc-backref" href="#id13">2.3 How do I get a single keypress at a time?</a></h2>
-<p>For Unix variants:There are several solutions.
-It's straightforward to do this using curses, but curses is a
-fairly large module to learn. Here's a solution without curses:</p>
-<pre class="literal-block">
-import termios, fcntl, sys, os
-fd = sys.stdin.fileno()
-
-oldterm = termios.tcgetattr(fd)
-newattr = termios.tcgetattr(fd)
-newattr[3] = newattr[3] & ~termios.ICANON & ~termios.ECHO
-termios.tcsetattr(fd, termios.TCSANOW, newattr)
-
-oldflags = fcntl.fcntl(fd, fcntl.F_GETFL)
-fcntl.fcntl(fd, fcntl.F_SETFL, oldflags | os.O_NONBLOCK)
-
-try:
- while 1:
- try:
- c = sys.stdin.read(1)
- print "Got character", `c`
- except IOError: pass
-finally:
- termios.tcsetattr(fd, termios.TCSAFLUSH, oldterm)
- fcntl.fcntl(fd, fcntl.F_SETFL, oldflags)
-</pre>
-<p>You need the <tt class="docutils literal">termios</tt> and the <tt class="docutils literal">fcntl</tt> module for any of this to work,
-and I've only tried it on Linux, though it should work elsewhere.
-In this code, characters are read and printed one at a time.</p>
-<p><tt class="docutils literal">termios.tcsetattr()</tt> turns off stdin's echoing and disables canonical
-mode. <tt class="docutils literal">fcntl.fnctl()</tt> is used to obtain stdin's file descriptor flags
-and modify them for non-blocking mode. Since reading stdin when it is
-empty results in an <tt class="docutils literal">IOError</tt>, this error is caught and ignored.</p>
-</div>
-</div>
-<div class="section" id="threads">
-<h1><a class="toc-backref" href="#id14">3 Threads</a></h1>
-<div class="section" id="how-do-i-program-using-threads">
-<h2><a class="toc-backref" href="#id15">3.1 How do I program using threads?</a></h2>
-<p>Be sure to use <a class="reference external" href="http://www.python.org/doc/lib/module-threading.html">the threading module</a> and not the
-<tt class="docutils literal">thread</tt> module. The <tt class="docutils literal">threading</tt> module builds convenient
-abstractions on top of the low-level primitives provided by the
-<tt class="docutils literal">thread</tt> module.</p>
-<p>Aahz has a set of slides from his threading tutorial that are helpful;
-see <a class="reference external" href="http://starship.python.net/crew/aahz/OSCON2001/">http://starship.python.net/crew/aahz/OSCON2001/</a>.</p>
-</div>
-<div class="section" id="none-of-my-threads-seem-to-run-why">
-<h2><a class="toc-backref" href="#id16">3.2 None of my threads seem to run: why?</a></h2>
-<p>As soon as the main thread exits, all threads are killed. Your main
-thread is running too quickly, giving the threads no time to do any work.</p>
-<p>A simple fix is to add a sleep to the end of the program
-that's long enough for all the threads to finish:</p>
-<pre class="literal-block">
-import threading, time
-
-def thread_task(name, n):
- for i in range(n): print name, i
-
-for i in range(10):
- T = threading.Thread(target=thread_task, args=(str(i), i))
- T.start()
-
-time.sleep(10) # <----------------------------!
-</pre>
-<p>But now (on many platforms) the threads don't run in parallel,
-but appear to run sequentially, one at a time! The reason is
-that the OS thread scheduler doesn't start a new thread until
-the previous thread is blocked.</p>
-<p>A simple fix is to add a tiny sleep to the start of the run
-function:</p>
-<pre class="literal-block">
-def thread_task(name, n):
- time.sleep(0.001) # <---------------------!
- for i in range(n): print name, i
-
-for i in range(10):
- T = threading.Thread(target=thread_task, args=(str(i), i))
- T.start()
-
-time.sleep(10)
-</pre>
-<p>Instead of trying to guess how long a <tt class="docutils literal">time.sleep()</tt> delay will be
-enough, it's better to use some kind of semaphore mechanism. One idea
-is to use the <a class="reference external" href="http://www.python.org/doc/lib/module-Queue.html">Queue module</a> to create a queue
-object, let each thread append a token to the queue when it finishes,
-and let the main thread read as many tokens from the queue as there
-are threads.</p>
-</div>
-<div class="section" id="how-do-i-parcel-out-work-among-a-bunch-of-worker-threads">
-<h2><a class="toc-backref" href="#id17">3.3 How do I parcel out work among a bunch of worker threads?</a></h2>
-<p>Use the <a class="reference external" href="http://www.python.org/doc/lib/module-Queue.html">Queue module</a> to create a queue
-containing a list of jobs. The <tt class="docutils literal">Queue</tt> class maintains a list of
-objects with <tt class="docutils literal">.put(obj)</tt> to add an item to the queue and <tt class="docutils literal">.get()</tt>
-to return an item. The class will take care of the locking necessary
-to ensure that each job is handed out exactly once.</p>
-<p>Here's a trivial example:</p>
-<pre class="literal-block">
-import threading, Queue, time
-
-# The worker thread gets jobs off the queue. When the queue is empty, it
-# assumes there will be no more work and exits.
-# (Realistically workers will run until terminated.)
-def worker ():
- print 'Running worker'
- time.sleep(0.1)
- while True:
- try:
- arg = q.get(block=False)
- except Queue.Empty:
- print 'Worker', threading.currentThread(),
- print 'queue empty'
- break
- else:
- print 'Worker', threading.currentThread(),
- print 'running with argument', arg
- time.sleep(0.5)
-
-# Create queue
-q = Queue.Queue()
-
-# Start a pool of 5 workers
-for i in range(5):
- t = threading.Thread(target=worker, name='worker %i' % (i+1))
- t.start()
-
-# Begin adding work to the queue
-for i in range(50):
- q.put(i)
-
-# Give threads time to run
-print 'Main thread sleeping'
-time.sleep(5)
-</pre>
-<p>When run, this will produce the following output:</p>
-<blockquote>
-Running worker
-Running worker
-Running worker
-Running worker
-Running worker
-Main thread sleeping
-Worker <Thread(worker 1, started)> running with argument 0
-Worker <Thread(worker 2, started)> running with argument 1
-Worker <Thread(worker 3, started)> running with argument 2
-Worker <Thread(worker 4, started)> running with argument 3
-Worker <Thread(worker 5, started)> running with argument 4
-Worker <Thread(worker 1, started)> running with argument 5
-...</blockquote>
-<p>Consult the module's documentation for more details; the <tt class="docutils literal">Queue</tt>
-class provides a featureful interface.</p>
-</div>
-<div class="section" id="what-kinds-of-global-value-mutation-are-thread-safe">
-<h2><a class="toc-backref" href="#id18">3.4 What kinds of global value mutation are thread-safe?</a></h2>
-<p>A global interpreter lock (GIL) is used internally to ensure that only
-one thread runs in the Python VM at a time. In general, Python offers
-to switch among threads only between bytecode instructions; how
-frequently it switches can be set via <tt class="docutils literal">sys.setcheckinterval()</tt>.
-Each bytecode instruction and therefore all the C implementation code
-reached from each instruction is therefore atomic from the point of view of a Python program.</p>
-<p>In theory, this means an exact accounting requires an exact
-understanding of the PVM bytecode implementation. In practice, it
-means that operations on shared variables of builtin data types (ints,
-lists, dicts, etc) that "look atomic" really are.</p>
-<p>For example, the following operations are all atomic (L, L1, L2 are lists, D, D1, D2 are dicts, x, y
-are objects, i, j are ints):</p>
-<pre class="literal-block">
-L.append(x)
-L1.extend(L2)
-x = L[i]
-x = L.pop()
-L1[i:j] = L2
-L.sort()
-x = y
-x.field = y
-D[x] = y
-D1.update(D2)
-D.keys()
-</pre>
-<p>These aren't:</p>
-<pre class="literal-block">
-i = i+1
-L.append(L[-1])
-L[i] = L[j]
-D[x] = D[x] + 1
-</pre>
-<p>Operations that replace other objects may invoke those other
-objects' <tt class="docutils literal">__del__</tt> method when their reference count reaches zero, and
-that can affect things. This is especially true for the mass updates
-to dictionaries and lists. When in doubt, use a mutex!</p>
-</div>
-<div class="section" id="can-t-we-get-rid-of-the-global-interpreter-lock">
-<h2><a class="toc-backref" href="#id19">3.5 Can't we get rid of the Global Interpreter Lock?</a></h2>
-<p>The Global Interpreter Lock (GIL) is often seen as a hindrance to
-Python's deployment on high-end multiprocessor server machines,
-because a multi-threaded Python program effectively only uses one CPU,
-due to the insistence that (almost) all Python code can only run while
-the GIL is held.</p>
-<p>Back in the days of Python 1.5, Greg Stein actually implemented a
-comprehensive patch set (the "free threading" patches) that removed
-the GIL and replaced it with fine-grained locking. Unfortunately, even
-on Windows (where locks are very efficient) this ran ordinary Python
-code about twice as slow as the interpreter using the GIL. On Linux
-the performance loss was even worse because pthread locks aren't as
-efficient.</p>
-<p>Since then, the idea of getting rid of the GIL has occasionally come
-up but nobody has found a way to deal with the expected slowdown, and
-users who don't use threads would not be happy if their code ran at
-half at the speed. Greg's free threading patch set has not been kept
-up-to-date for later Python versions.</p>
-<p>This doesn't mean that you can't make good use of Python on multi-CPU
-machines! You just have to be creative with dividing the work up
-between multiple <em>processes</em> rather than multiple <em>threads</em>.
-Judicious use of C extensions will also help; if you use a C extension
-to perform a time-consuming task, the extension can release the GIL
-while the thread of execution is in the C code and allow other threads
-to get some work done.</p>
-<p>It has been suggested that the GIL should be a per-interpreter-state
-lock rather than truly global; interpreters then wouldn't be able to
-share objects. Unfortunately, this isn't likely to happen either. It
-would be a tremendous amount of work, because many object
-implementations currently have global state. For example, small
-integers and short strings are cached; these caches would have to be
-moved to the interpreter state. Other object types have their own
-free list; these free lists would have to be moved to the interpreter
-state. And so on.</p>
-<p>And I doubt that it can even be done in finite time, because the same
-problem exists for 3rd party extensions. It is likely that 3rd party
-extensions are being written at a faster rate than you can convert
-them to store all their global state in the interpreter state.</p>
-<p>And finally, once you have multiple interpreters not sharing any
-state, what have you gained over running each interpreter
-in a separate process?</p>
-</div>
-</div>
-<div class="section" id="input-and-output">
-<h1><a class="toc-backref" href="#id20">4 Input and Output</a></h1>
-<div class="section" id="how-do-i-delete-a-file-and-other-file-questions">
-<h2><a class="toc-backref" href="#id21">4.1 How do I delete a file? (And other file questions...)</a></h2>
-<p>Use <tt class="docutils literal">os.remove(filename)</tt> or <tt class="docutils literal">os.unlink(filename)</tt>; for
-documentation, see <a class="reference external" href="http://www.python.org/doc/lib/module-posix.html">the POSIX module</a>. The two
-functions are identical; <tt class="docutils literal">unlink()</tt> is simply the name of the Unix
-system call for this function.</p>
-<p>To remove a directory, use <tt class="docutils literal">os.rmdir()</tt>; use <tt class="docutils literal">os.mkdir()</tt> to
-create one. <tt class="docutils literal">os.makedirs(path)</tt> will create any intermediate
-directories in <tt class="docutils literal">path</tt> that don't exist. <tt class="docutils literal">os.removedirs(path)</tt> will
-remove intermediate directories as long as they're empty; if you want
-to delete an entire directory tree and its contents, use
-<tt class="docutils literal">shutil.rmtree()</tt>.</p>
-<p>To rename a file, use <tt class="docutils literal">os.rename(old_path, new_path)</tt>.</p>
-<p>To truncate a file, open it using <tt class="docutils literal">f = open(filename, <span class="pre">"r+")</span></tt>, and use
-<tt class="docutils literal">f.truncate(offset)</tt>; offset defaults to the current seek position.
-There's also <tt class="docutils literal">`os.ftruncate(fd, offset)</tt> for files opened with <tt class="docutils literal">os.open()</tt>,
-where <tt class="docutils literal">fd</tt> is the file descriptor (a small integer).</p>
-<p>The <tt class="docutils literal">shutil</tt> module also contains a number of functions to work on files
-including <tt class="docutils literal">copyfile</tt>, <tt class="docutils literal">copytree</tt>, and <tt class="docutils literal">rmtree</tt>.</p>
-</div>
-<div class="section" id="how-do-i-copy-a-file">
-<h2><a class="toc-backref" href="#id22">4.2 How do I copy a file?</a></h2>
-<p>The <tt class="docutils literal">shutil</tt> module contains a <tt class="docutils literal">copyfile()</tt> function. Note that
-on MacOS 9 it doesn't copy the resource fork and Finder info.</p>
-</div>
-<div class="section" id="how-do-i-read-or-write-binary-data">
-<h2><a class="toc-backref" href="#id23">4.3 How do I read (or write) binary data?</a></h2>
-<p>or complex data formats, it's best to use <a class="reference external" href="http://www.python.org/doc/lib/module-struct.html">the struct module</a>. It allows you
-to take a string containing binary data (usually numbers) and convert
-it to Python objects; and vice versa.</p>
-<p>For example, the following code reads two 2-byte integers
-and one 4-byte integer in big-endian format from a file:</p>
-<pre class="literal-block">
-import struct
-
-f = open(filename, "rb") # Open in binary mode for portability
-s = f.read(8)
-x, y, z = struct.unpack(">hhl", s)
-</pre>
-<p>The '>' in the format string forces big-endian data; the letter
-'h' reads one "short integer" (2 bytes), and 'l' reads one
-"long integer" (4 bytes) from the string.</p>
-<p>For data that is more regular (e.g. a homogeneous list of ints or
-thefloats), you can also use <a class="reference external" href="http://www.python.org/doc/lib/module-array.html">the array module</a>.</p>
-</div>
-<div class="section" id="i-can-t-seem-to-use-os-read-on-a-pipe-created-with-os-popen-why">
-<h2><a class="toc-backref" href="#id24">4.4 I can't seem to use os.read() on a pipe created with os.popen(); why?</a></h2>
-<p><tt class="docutils literal">os.read()</tt> is a low-level function which takes a file descriptor, a
-small integer representing the opened file. <tt class="docutils literal">os.popen()</tt> creates a
-high-level file object, the same type returned by the builtin
-<tt class="docutils literal">open()</tt> function. Thus, to read n bytes from a pipe p created with
-<tt class="docutils literal">os.popen()</tt>, you need to use <tt class="docutils literal">p.read(n)</tt>.</p>
-</div>
-<div class="section" id="how-do-i-run-a-subprocess-with-pipes-connected-to-both-input-and-output">
-<h2><a class="toc-backref" href="#id25">4.5 How do I run a subprocess with pipes connected to both input and output?</a></h2>
-<p>Use <a class="reference external" href="http://www.python.org/doc/lib/module-popen2.html">the popen2 module</a>. For example:</p>
-<pre class="literal-block">
-import popen2
-fromchild, tochild = popen2.popen2("command")
-tochild.write("input\n")
-tochild.flush()
-output = fromchild.readline()
-</pre>
-<p>Warning: in general it is unwise to do this because you can easily
-cause a deadlock where your process is blocked waiting for output from
-the child while the child is blocked waiting for input from you. This
-can be caused because the parent expects the child to output more text
-than it does, or it can be caused by data being stuck in stdio buffers
-due to lack of flushing. The Python parent can of course explicitly
-flush the data it sends to the child before it reads any output, but
-if the child is a naive C program it may have been written to never
-explicitly flush its output, even if it is interactive, since flushing
-is normally automatic.</p>
-<p>Note that a deadlock is also possible if you use <tt class="docutils literal">popen3</tt> to read
-stdout and stderr. If one of the two is too large for the internal
-buffer (increasing the buffer size does not help) and you <tt class="docutils literal">read()</tt>
-the other one first, there is a deadlock, too.</p>
-<p>Note on a bug in popen2: unless your program calls <tt class="docutils literal">wait()</tt>
-or <tt class="docutils literal">waitpid()</tt>, finished child processes are never removed,
-and eventually calls to popen2 will fail because of a limit on
-the number of child processes. Calling <tt class="docutils literal">os.waitpid</tt> with the
-<tt class="docutils literal">os.WNOHANG</tt> option can prevent this; a good place to insert such
-a call would be before calling <tt class="docutils literal">popen2</tt> again.</p>
-<p>In many cases, all you really need is to run some data through a
-command and get the result back. Unless the amount of data is very
-large, the easiest way to do this is to write it to a temporary file
-and run the command with that temporary file as input. The <a class="reference external" href="http://www.python.org/doc/lib/module-tempfile.html">standard
-module tempfile</a>
-exports a <tt class="docutils literal">mktemp()</tt> function to generate unique temporary file names.</p>
-<pre class="literal-block">
-import tempfile
-import os
-class Popen3:
- """
- This is a deadlock-safe version of popen that returns
- an object with errorlevel, out (a string) and err (a string).
- (capturestderr may not work under windows.)
- Example: print Popen3('grep spam','\n\nhere spam\n\n').out
- """
- def __init__(self,command,input=None,capturestderr=None):
- outfile=tempfile.mktemp()
- command="( %s ) > %s" % (command,outfile)
- if input:
- infile=tempfile.mktemp()
- open(infile,"w").write(input)
- command=command+" <"+infile
- if capturestderr:
- errfile=tempfile.mktemp()
- command=command+" 2>"+errfile
- self.errorlevel=os.system(command) >> 8
- self.out=open(outfile,"r").read()
- os.remove(outfile)
- if input:
- os.remove(infile)
- if capturestderr:
- self.err=open(errfile,"r").read()
- os.remove(errfile)
-</pre>
-<p>Note that many interactive programs (e.g. vi) don't work well with
-pipes substituted for standard input and output. You will have to use
-pseudo ttys ("ptys") instead of pipes. Or you can use a Python
-interface to Don Libes' "expect" library. A Python extension that
-interfaces to expect is called "expy" and available from
-<a class="reference external" href="http://expectpy.sourceforge.net">http://expectpy.sourceforge.net</a>. A pure Python solution that works
-like expect is ` pexpect <<a class="reference external" href="http://pexpect.sourceforge.net">http://pexpect.sourceforge.net</a>>`_.</p>
-</div>
-<div class="section" id="how-do-i-access-the-serial-rs232-port">
-<h2><a class="toc-backref" href="#id26">4.6 How do I access the serial (RS232) port?</a></h2>
-<p>For Win32, POSIX (Linux, BSD, etc.), Jython:</p>
-<blockquote>
-<a class="reference external" href="http://pyserial.sourceforge.net">http://pyserial.sourceforge.net</a></blockquote>
-<p>For Unix, see a Usenet post by Mitch Chapman:</p>
-<blockquote>
-<a class="reference external" href="http://groups.google.com/groups?selm=34A04430.CF9@ohioee.com">http://groups.google.com/groups?selm=34A04430.CF9@ohioee.com</a></blockquote>
-</div>
-<div class="section" id="why-doesn-t-closing-sys-stdout-stdin-stderr-really-close-it">
-<h2><a class="toc-backref" href="#id27">4.7 Why doesn't closing sys.stdout (stdin, stderr) really close it?</a></h2>
-<p>Python file objects are a high-level layer of abstraction on top of C
-streams, which in turn are a medium-level layer of abstraction on top
-of (among other things) low-level C file descriptors.</p>
-<p>For most file objects you create in Python via the builtin <tt class="docutils literal">file</tt>
-constructor, <tt class="docutils literal">f.close()</tt> marks the Python file object as being closed
-from Python's point of view, and also arranges to close the underlying
-C stream. This also happens automatically in f's destructor, when f
-becomes garbage.</p>
-<p>But stdin, stdout and stderr are treated specially by Python, because
-of the special status also given to them by C. Running
-<tt class="docutils literal">sys.stdout.close()</tt> marks the Python-level file object as being
-closed, but does <em>not</em> close the associated C stream.</p>
-<p>To close the underlying C stream for one of these three, you should
-first be sure that's what you really want to do (e.g., you may confuse
-extension modules trying to do I/O). If it is, use
-os.close:</p>
-<pre class="literal-block">
-os.close(0) # close C's stdin stream
-os.close(1) # close C's stdout stream
-os.close(2) # close C's stderr stream
-</pre>
-</div>
-</div>
-<div class="section" id="network-internet-programming">
-<h1><a class="toc-backref" href="#id28">5 Network/Internet Programming</a></h1>
-<div class="section" id="what-www-tools-are-there-for-python">
-<h2><a class="toc-backref" href="#id29">5.1 What WWW tools are there for Python?</a></h2>
-<p>See the chapters titled <a class="reference external" href="http://www.python.org/doc/lib/internet.html">"Internet Protocols and Support"</a> and <a class="reference external" href="http://www.python.org/doc/lib/netdata.html">"Internet Data
-Handling"</a> in the
-Library Reference Manual. Python has many modules that will help you
-build server-side and client-side web systems.</p>
-<p>A summary of available frameworks is maintained by Paul Boddie at
-<a class="reference external" href="http://www.python.org/cgi-bin/moinmoin/WebProgramming">http://www.python.org/cgi-bin/moinmoin/WebProgramming</a> .</p>
-<p>Cameron Laird maintains a useful set of pages about Python web technologies at
-<a class="reference external" href="http://phaseit.net/claird/comp.lang.python/web_python.html">http://phaseit.net/claird/comp.lang.python/web_python.html</a>.</p>
-<p>The <a class="reference external" href="http://www.python.org/topics/web/">Web Programming topic guide</a>
-also points to many useful resources.</p>
-</div>
-<div class="section" id="how-can-i-mimic-cgi-form-submission-method-post">
-<h2><a class="toc-backref" href="#id30">5.2 How can I mimic CGI form submission (METHOD=POST)?</a></h2>
-<p>I would like to retrieve web pages that are the result of POSTing a
-form. Is there existing code that would let me do this easily?</p>
-<p>Yes. Here's a simple example that uses httplib:</p>
-<pre class="literal-block">
-#!/usr/local/bin/python
-
-import httplib, sys, time
-
-### build the query string
-qs = "First=Josephine&MI=Q&Last=Public"
-
-### connect and send the server a path
-httpobj = httplib.HTTP('www.some-server.out-there', 80)
-httpobj.putrequest('POST', '/cgi-bin/some-cgi-script')
-### now generate the rest of the HTTP headers...
-httpobj.putheader('Accept', '*/*')
-httpobj.putheader('Connection', 'Keep-Alive')
-httpobj.putheader('Content-type', 'application/x-www-form-urlencoded')
-httpobj.putheader('Content-length', '%d' % len(qs))
-httpobj.endheaders()
-httpobj.send(qs)
-### find out what the server said in response...
-reply, msg, hdrs = httpobj.getreply()
-if reply != 200:
- sys.stdout.write(httpobj.getfile().read())
-</pre>
-<p>Note that in general for URL-encoded POST operations, query
-strings must be quoted by using <tt class="docutils literal">urllib.quote()</tt>. For example to send name="Guy
-Steele, Jr.":</p>
-<pre class="literal-block">
->>> from urllib import quote
->>> x = quote("Guy Steele, Jr.")
->>> x
-'Guy%20Steele,%20Jr.'
->>> query_string = "name="+x
->>> query_string
-'name=Guy%20Steele,%20Jr.'
-</pre>
-</div>
-<div class="section" id="what-module-should-i-use-to-help-with-generating-html">
-<h2><a class="toc-backref" href="#id31">5.3 What module should I use to help with generating HTML?</a></h2>
-<p>There are many different modules available:</p>
-<ul class="simple">
-<li>HTMLgen is a class library of objects corresponding to all the HTML
-3.2 markup tags. It's used when you are writing in Python and wish
-to synthesize HTML pages for generating a web or for CGI forms, etc.</li>
-<li>DocumentTemplate and Zope Page Templates are two different systems that are
-part of Zope.</li>
-<li>Quixote's PTL uses Python syntax to assemble strings of text.</li>
-</ul>
-<p>Consult the <a class="reference external" href="http://www.python.org/topics/web/">Web Programming topic guide</a> for more links.</p>
-</div>
-<div class="section" id="how-do-i-send-mail-from-a-python-script">
-<h2><a class="toc-backref" href="#id32">5.4 How do I send mail from a Python script?</a></h2>
-<p>Use <a class="reference external" href="http://www.python.org/doc/lib/module-smtplib.html">the standard library module smtplib</a>.</p>
-<p>Here's a very simple interactive mail sender that uses it. This
-method will work on any host that supports an SMTP listener.</p>
-<pre class="literal-block">
-import sys, smtplib
-
-fromaddr = raw_input("From: ")
-toaddrs = raw_input("To: ").split(',')
-print "Enter message, end with ^D:"
-msg = ''
-while 1:
- line = sys.stdin.readline()
- if not line:
- break
- msg = msg + line
-
-# The actual mail send
-server = smtplib.SMTP('localhost')
-server.sendmail(fromaddr, toaddrs, msg)
-server.quit()
-</pre>
-<p>A Unix-only alternative uses sendmail. The location of the
-sendmail program varies between systems; sometimes it is
-<tt class="docutils literal">/usr/lib/sendmail</tt>, sometime <tt class="docutils literal">/usr/sbin/sendmail</tt>. The sendmail
-manual page will help you out. Here's some sample code:</p>
-<pre class="literal-block">
-SENDMAIL = "/usr/sbin/sendmail" # sendmail location
-import os
-p = os.popen("%s -t -i" % SENDMAIL, "w")
-p.write("To: receiver@example.com\n")
-p.write("Subject: test\n")
-p.write("\n") # blank line separating headers from body
-p.write("Some text\n")
-p.write("some more text\n")
-sts = p.close()
-if sts != 0:
- print "Sendmail exit status", sts
-</pre>
-</div>
-<div class="section" id="how-do-i-avoid-blocking-in-the-connect-method-of-a-socket">
-<h2><a class="toc-backref" href="#id33">5.5 How do I avoid blocking in the connect() method of a socket?</a></h2>
-<p>The select module is commonly used to help with asynchronous
-I/O on sockets.</p>
-<p>To prevent the TCP connect from blocking, you can set the socket to
-non-blocking mode. Then when you do the <tt class="docutils literal">connect()</tt>, you will
-either connect immediately (unlikely) or get an exception that
-contains the error number as <tt class="docutils literal">.errno</tt>. <tt class="docutils literal">errno.EINPROGRESS</tt>
-indicates that the connection is in progress, but hasn't finished yet.
-Different OSes will return different values, so you're going to have
-to check what's returned on your system.</p>
-<p>You can use the <tt class="docutils literal">connect_ex()</tt> method to avoid creating an
-exception. It will just return the errno value. To poll, you can
-call <tt class="docutils literal">connect_ex()</tt> again later -- 0 or <tt class="docutils literal">errno.EISCONN</tt> indicate
-that you're connected -- or you can pass this socket to select to
-check if it's writeable.</p>
-</div>
-</div>
-<div class="section" id="databases">
-<h1><a class="toc-backref" href="#id34">6 Databases</a></h1>
-<div class="section" id="are-there-any-interfaces-to-database-packages-in-python">
-<h2><a class="toc-backref" href="#id35">6.1 Are there any interfaces to database packages in Python?</a></h2>
-<p>Yes.</p>
-<p>Python 2.3 includes the <tt class="docutils literal">bsddb</tt> package which provides an interface
-to the <a class="reference external" href="http://www.python.org/doc/lib/module-bsddb.html">BerkeleyDB</a> library.
-Interfaces to disk-based hashes such as <a class="reference external" href="http://www.python.org/doc/lib/module-dbm.html">DBM</a> and <a class="reference external" href="http://www.python.org/doc/lib/module-gdbm.html">GDBM</a> are also included
-with standard Python.</p>
-<p>Support for most relational databases is available. See the <a class="reference external" href="http://www.python.org/topics/database">Database
-Topic Guide</a> for details.</p>
-</div>
-<div class="section" id="how-do-you-implement-persistent-objects-in-python">
-<h2><a class="toc-backref" href="#id36">6.2 How do you implement persistent objects in Python?</a></h2>
-<p>The <a class="reference external" href="http://www.python.org/doc/lib/module-pickle.html">pickle library module</a> solves this in a
-very general way (though you still can't store things like open files,
-sockets or windows), and the <a class="reference external" href="http://www.python.org/doc/lib/module-shelve.html">shelve library module</a> uses pickle and
-(g)dbm to create persistent mappings containing arbitrary Python
-objects. For better performance, you can use
-<a class="reference external" href="http://www.python.org/doc/lib/module-cPickle.html">the cPickle module</a>.</p>
-<p>A more awkward way of doing things is to use pickle's little sister,
-marshal. <a class="reference external" href="http://www.python.org/doc/lib/module-marshal.html">The marshal module</a> provides very
-fast ways to store noncircular basic Python types to files and
-strings, and back again. Although marshal does not do fancy things
-like store instances or handle shared references properly, it does run
-extremely fast. For example loading a half megabyte of data may take
-less than a third of a second. This often beats doing something more
-complex and general such as using gdbm with pickle/shelve.</p>
-</div>
-<div class="section" id="why-is-cpickle-so-slow">
-<h2><a class="toc-backref" href="#id37">6.3 Why is cPickle so slow?</a></h2>
-<p>The default format used by the pickle module is a slow one that
-results in readable pickles. Making it the default, but it would
-break backward compatibility:</p>
-<pre class="literal-block">
-largeString = 'z' * (100 * 1024)
-myPickle = cPickle.dumps(largeString, protocol=1)
-</pre>
-</div>
-<div class="section" id="if-my-program-crashes-with-a-bsddb-or-anydbm-database-open-it-gets-corrupted-how-come">
-<h2><a class="toc-backref" href="#id38">6.4 If my program crashes with a bsddb (or anydbm) database open, it gets corrupted. How come?</a></h2>
-<p>Databases opened for write access with the bsddb module (and often by
-the anydbm module, since it will preferentially use bsddb) must
-explicitly be closed using the <tt class="docutils literal">.close()</tt> method of the database. The
-underlying library caches database contents which need to be
-converted to on-disk form and written.</p>
-<p>If you have initialized a new bsddb database but not written anything to
-it before the program crashes, you will often wind up with a zero-length
-file and encounter an exception the next time the file is opened.</p>
-</div>
-<div class="section" id="i-tried-to-open-berkeley-db-file-but-bsddb-produces-bsddb-error-22-invalid-argument-help-how-can-i-restore-my-data">
-<h2><a class="toc-backref" href="#id39">6.5 I tried to open Berkeley DB file, but bsddb produces bsddb.error: (22, 'Invalid argument'). Help! How can I restore my data?</a></h2>
-<p>Don't panic! Your data is probably intact. The most frequent cause
-for the error is that you tried to open an earlier Berkeley DB file
-with a later version of the Berkeley DB library.</p>
-<p>Many Linux systems now have all three versions of Berkeley DB
-available. If you are migrating from version 1 to a newer version use
-db_dump185 to dump a plain text version of the database.
-If you are migrating from version 2 to version 3 use db2_dump to create
-a plain text version of the database. In either case, use db_load to
-create a new native database for the latest version installed on your
-computer. If you have version 3 of Berkeley DB installed, you should
-be able to use db2_load to create a native version 2 database.</p>
-<p>You should move away from Berkeley DB version 1 files because
-the hash file code contains known bugs that can corrupt your data.</p>
-</div>
-</div>
-<div class="section" id="mathematics-and-numerics">
-<h1><a class="toc-backref" href="#id40">7 Mathematics and Numerics</a></h1>
-<div class="section" id="how-do-i-generate-random-numbers-in-python">
-<h2><a class="toc-backref" href="#id41">7.1 How do I generate random numbers in Python?</a></h2>
-<p>The <a class="reference external" href="http://www.python.org/doc/lib/module-random.html">standard module random</a> implements a random number
-generator. Usage is simple:</p>
-<pre class="literal-block">
-import random
-random.random()
-</pre>
-<p>This returns a random floating point number in the range [0, 1).</p>
-<p>There are also many other specialized generators in this module, such
-as:</p>
-<ul class="simple">
-<li><tt class="docutils literal">randrange(a, b)</tt> chooses an integer in the range [a, b).</li>
-<li><tt class="docutils literal">uniform(a, b)</tt> chooses a floating point number in the range [a, b).</li>
-<li><tt class="docutils literal">normalvariate(mean, sdev)</tt> samples the normal (Gaussian) distribution.</li>
-</ul>
-<p>Some higher-level functions operate on sequences directly, such as:</p>
-<ul class="simple">
-<li><tt class="docutils literal">choice(S)</tt> chooses random element from a given sequence</li>
-<li><tt class="docutils literal">shuffle(L)</tt> shuffles a list in-place, i.e. permutes it randomly</li>
-</ul>
-<p>There's also a <tt class="docutils literal">Random</tt> class you can instantiate
-to create independent multiple random number generators.</p>
-</div>
-</div>
-</div>
-</body>
-</html>
diff --git a/faq/programming.ht b/faq/programming.ht
deleted file mode 100644
index 3ecc6ed..0000000
--- a/faq/programming.ht
+++ /dev/null
@@ -1,1756 +0,0 @@
-Title: Python Programming FAQ
-Content-type: text/x-rst
-
-====================================
-Programming FAQ
-====================================
-
-:Date: $Date: 2005-12-21 22:00:52 -0700 (Wed, 21 Dec 2005) $
-:Version: $Revision: 8721 $
-:Web site: http://www.python.org/
-
-.. contents::
-.. sectnum::
-
-General Questions
-===========================
-
-Is there a source code level debugger with breakpoints, single-stepping, etc.?
--------------------------------------------------------------------------------
-Yes.
-
-The pdb module is a simple but adequate console-mode debugger for
-Python. It is part of the standard Python library, and is `documented
-in the Library Reference Manual
-<http://docs.python.org/lib/module-pdb.html>`_. You can
-also write your own debugger by using the code for pdb as an example.
-
-The IDLE interactive development environment, which is part of the
-standard Python distribution (normally available as Tools/scripts/idle),
-includes a graphical debugger. There is documentation for the IDLE
-debugger at http://www.python.org/idle/doc/idle2.html#Debugger
-
-PythonWin is a Python IDE that includes a GUI debugger based on pdb.
-The Pythonwin debugger colors breakpoints and has quite a few cool
-features such as debugging non-Pythonwin programs. A reference can be
-found at http://www.python.org/windows/pythonwin/. Recent versions of
-PythonWin are available as a part of the ActivePython distribution
-(see http://www.activestate.com/Products/ActivePython/index.html).
-
-`Boa Constructor <http://boa-constructor.sourceforge.net/>`_ is an IDE
-and GUI builder that uses wxPython. It offers visual frame creation
-and manipulation, an object
-inspector, many views on the source like object browsers, inheritance
-hierarchies, doc string generated html documentation, an advanced
-debugger, integrated help, and Zope support.
-
-`Eric3 <http://www.die-offenbachs.de/detlev/eric3.html>`_ is an IDE
-built on PyQt and the Scintilla editing component.
-
-Pydb is a version of the standard Python debugger pdb, modified for
-use with DDD (Data Display Debugger), a popular graphical debugger
-front end. Pydb can be found at
-http://packages.debian.org/unstable/devel/pydb.html> and DDD can be
-found at http://www.gnu.org/software/ddd.
-
-There are a number of commmercial Python IDEs that include graphical
-debuggers. They include:
-
-* Wing IDE (http://wingide.com)
-* Komodo IDE (http://www.activestate.com/Products/Komodo)
-
-
-
-Is there a tool to help find bugs or perform static analysis?
-----------------------------------------------------------------------
-Yes.
-
-PyChecker is a static analysis tool that finds bugs in Python source
-code and warns about code complexity and style. You can get PyChecker
-from http://pychecker.sf.net.
-
-`Pylint <http://www.logilab.org/projects/pylint>`_ is another tool
-that checks if a module satisfies a coding standard, and also makes it
-possible to write plug-ins to add a custom feature. In addition to
-the bug checking that PyChecker performs, Pylint offers some
-additional features such as checking line length, whether variable
-names are well-formed according to your coding standard, whether
-declared interfaces are fully implemented, and more.
-http://www.logilab.org/projects/pylint/documentation provides a full
-list of Pylint's features.
-
-
-How can I create a stand-alone binary from a Python script?
--------------------------------------------------------------------
-You don't need the ability to compile Python to C code if all you
-want is a stand-alone program that users can download and run without
-having to install the Python distribution first. There are a number
-of tools that determine the set of modules required by a program and
-bind these modules together with a Python binary to produce a single
-executable.
-
-One is to use the freeze tool, which is included in the Python
-source tree as ``Tools/freeze``. It converts Python byte
-code to C arrays; a C compiler you can embed all
-your modules into a new program, which is then linked
-with the standard Python modules.
-
-It works by scanning your source recursively for import statements (in
-both forms) and looking for the modules in the standard Python path as
-well as in the source directory (for built-in modules). It then turns
-the bytecode for modules written in Python into C code (array
-initializers that can be turned into code objects using the marshal
-module) and creates a custom-made config file that only contains those
-built-in modules which are actually used in the program. It then
-compiles the generated C code and links it with the rest of the Python
-interpreter to form a self-contained binary which acts exactly like
-your script.
-
-Obviously, freeze requires a C compiler. There are several other
-utilities which don't. The first is Gordon McMillan's installer at
-
- http://www.mcmillan-inc.com/install1.html
-
-which works on Windows, Linux and at least some forms of Unix.
-
-Another is Thomas Heller's py2exe (Windows only) at
-
- http://starship.python.net/crew/theller/py2exe
-
-A third is Christian Tismer's `SQFREEZE
-<http://starship.python.net/crew/pirx>`_ which appends the byte code
-to a specially-prepared Python interpreter that can find the byte
-code in the executable. It's possible that a similar approach will
-be added to Python 2.4, due out some time in 2004.
-
-Other tools include Fredrik Lundh's `Squeeze
-<http://www.pythonware.com/products/python/squeeze>`_ and Anthony
-Tuininga's `cx_Freeze
-<http://starship.python.net/crew/atuining/cx_Freeze/index.html>`_.
-
-
-Are there coding standards or a style guide for Python programs?
-------------------------------------------------------------------------
-Yes. The coding style required for standard library modules
-is documented as `PEP 8 <../../peps/pep-0008.html>`_.
-
-My program is too slow. How do I speed it up?
-----------------------------------------------------
-
-That's a tough one, in general. There are many tricks to speed up
-Python code; consider rewriting parts in C as a last resort.
-
-In some cases it's possible to automatically translate Python to C or
-x86 assembly language, meaning that you don't have to modify your code
-to gain increased speed.
-
-`Pyrex <http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/>`_ can
-compile a slightly modified version of Python code into a C extension,
-and can be used on many different platforms.
-
-`Psyco <http://psyco.sourceforge.net>`_ is a just-in-time compiler
-that translates Python code into x86 assembly language. If you can
-use it, Psyco can provide dramatic speedups for critical functions.
-
-The rest of this answer will discuss various tricks for squeezing a
-bit more speed out of Python code. *Never* apply any optimization
-tricks unless you know you need them, after profiling has indicated
-that a particular function is the heavily executed hot spot in the
-code. Optimizations almost always make the code less clear, and you
-shouldn't pay the costs of reduced clarity (increased development
-time, greater likelihood of bugs) unless the resulting performance
-benefit is worth it.
-
-There is a page on the wiki devoted to `performance tips <http://wiki.python.org/moin/PythonSpeed/PerformanceTips>`_.
-
-Guido van Rossum has written up an anecdote related to optimization at
-http://www.python.org/doc/essays/list2str.html.
-
-One thing to notice is that function and (especially) method calls are
-rather expensive; if you have designed a purely OO interface with lots
-of tiny functions that don't do much more than get or set an instance
-variable or call another method, you might consider using a more
-direct way such as directly accessing instance variables. Also see the
-standard module "profile" (`described in the Library Reference manual
-<http://docs.python.org/lib/module-profile.html>`_) which
-makes it possible to find out where your program is spending most of
-its time (if you have some patience -- the profiling itself can slow
-your program down by an order of magnitude).
-
-Remember that many standard optimization heuristics you
-may know from other programming experience may well apply
-to Python. For example it may be faster to send output to output
-devices using larger writes rather than smaller ones in order to
-reduce the overhead of kernel system calls. Thus CGI scripts
-that write all output in "one shot" may be faster than
-those that write lots of small pieces of output.
-
-Also, be sure to use Python's core features where appropriate.
-For example, slicing allows programs to chop up
-lists and other sequence objects in a single tick of the interpreter's
-mainloop using highly optimized C implementations. Thus to
-get the same effect as::
-
- L2 = []
- for i in range[3]:
- L2.append(L1[i])
-
-it is much shorter and far faster to use ::
-
- L2 = list(L1[:3]) # "list" is redundant if L1 is a list.
-
-Note that the functionally-oriented builtins such as
-``map()``, ``zip()``, and friends can be a convenient
-accelerator for loops that perform a single task. For example to pair the elements of two
-lists together::
-
- >>> zip([1,2,3], [4,5,6])
- [(1, 4), (2, 5), (3, 6)]
-
-or to compute a number of sines::
-
- >>> map( math.sin, (1,2,3,4))
- [0.841470984808, 0.909297426826, 0.14112000806, -0.756802495308]
-
-The operation completes very quickly in such cases.
-
-Other examples include the ``join()`` and ``split()``
-methods of string objects. For example if s1..s7 are large (10K+) strings then
-``"".join([s1,s2,s3,s4,s5,s6,s7])` may be far faster than
-the more obvious ``s1+s2+s3+s4+s5+s6+s7``, since the "summation"
-will compute many subexpressions, whereas ``join()`` does all the
-copying in one pass. For manipulating strings, use
-the ``replace()`` method on string objects. Use
-regular expressions only when you're not dealing with constant string patterns.
-Consider using the string formatting operations
-``string % tuple`` and ``string % dictionary``.
-
-Be sure to use the ``list.sort()`` builtin method to do sorting, and see
-the `sorting mini-HOWTO <http://wiki.python.org/moin/HowTo/Sorting>`_ for examples of moderately advanced usage.
-``list.sort()`` beats other techniques for sorting in all but the most
-extreme circumstances.
-
-Another common trick is to "push loops into functions or methods."
-For example suppose you have a program that runs slowly and you
-use the profiler to determine that a Python function ``ff()``
-is being called lots of times. If you notice that ``ff ()``::
-
- def ff(x):
- ...do something with x computing result...
- return result
-
-tends to be called in loops like::
-
- list = map(ff, oldlist)
-
-or::
-
- for x in sequence:
- value = ff(x)
- ...do something with value...
-
-then you can often eliminate function call overhead by rewriting
-``ff()`` to::
-
- def ffseq(seq):
- resultseq = []
- for x in seq:
- ...do something with x computing result...
- resultseq.append(result)
- return resultseq
-
-and rewrite the two examples to ``list = ffseq(oldlist)`` and to::
-
- for value in ffseq(sequence):
- ...do something with value...
-
-Single calls to ff(x) translate to ffseq([x])[0] with little
-penalty. Of course this technique is not always appropriate
-and there are other variants which you can figure out.
-
-You can gain some performance by explicitly storing the results of
-a function or method lookup into a local variable. A loop like::
-
- for key in token:
- dict[key] = dict.get(key, 0) + 1
-
-resolves dict.get every iteration. If the method isn't going to
-change, a slightly faster implementation is::
-
- dict_get = dict.get # look up the method once
- for key in token:
- dict[key] = dict_get(key, 0) + 1
-
-Default arguments can be used to determine values once, at
-compile time instead of at run time. This can only be done for
-functions or objects which will not be changed during program
-execution, such as replacing ::
-
- def degree_sin(deg):
- return math.sin(deg * math.pi / 180.0)
-
-with ::
-
- def degree_sin(deg, factor = math.pi/180.0, sin = math.sin):
- return sin(deg * factor)
-
-Because this trick uses default arguments for terms which should
-not be changed, it should only be used when you are not concerned
-with presenting a possibly confusing API to your users.
-
-
-Core Language
-==================
-
-How do you set a global variable in a function?
-----------------------------------------------------------
-Did you do something like this? ::
-
- x = 1 # make a global
-
- def f():
- print x # try to print the global
- ...
- for j in range(100):
- if q>3:
- x=4
-
-Any variable assigned in a function is local to that function.
-unless it is specifically declared global. Since a value is bound
-to ``x`` as the last statement of the function body, the compiler
-assumes that ``x`` is local. Consequently the ``print x``
-attempts to print an uninitialized local variable and will
-trigger a ``NameError``.
-
-The solution is to insert an explicit global declaration at the start
-of the function::
-
- def f():
- global x
- print x # try to print the global
- ...
- for j in range(100):
- if q>3:
- x=4
-
-
-In this case, all references to ``x`` are interpreted as references
-to the ``x`` from the module namespace.
-
-What are the rules for local and global variables in Python?
---------------------------------------------------------------------------
-
-In Python, variables that are only referenced inside a function are
-implicitly global. If a variable is assigned a new value anywhere
-within the function's body, it's assumed to be a local. If a variable
-is ever assigned a new value inside the function, the variable is
-implicitly local, and you need to explicitly declare it as 'global'.
-
-Though a bit surprising at first, a moment's consideration explains
-this. On one hand, requiring ``global`` for assigned variables provides
-a bar against unintended side-effects. On the other hand, if ``global``
-was required for all global references, you'd be using ``global`` all the
-time. You'd have to declare as global every reference to a
-builtin function or to a component of an imported module. This
-clutter would defeat the usefulness of the ``global`` declaration for
-identifying side-effects.
-
-
-How do I share global variables across modules?
-------------------------------------------------
-
-The canonical way to share information across modules within a single
-program is to create a special module (often called config or cfg).
-Just import the config module in all modules of your application; the
-module then becomes available as a global name. Because there is only
-one instance of each module, any changes made to the module object get
-reflected everywhere. For example:
-
-config.py::
-
- x = 0 # Default value of the 'x' configuration setting
-
-mod.py::
-
- import config
- config.x = 1
-
-main.py::
-
- import config
- import mod
- print config.x
-
-Note that using a module is also the basis for implementing the
-Singleton design pattern, for the same reason.
-
-
-What are the "best practices" for using import in a module?
-------------------------------------------------------------------------------
-
-In general, don't use ``from modulename import *``.
-Doing so clutters the importer's namespace. Some people avoid this idiom
-even with the few modules that were designed to be imported in this
-manner. Modules designed in this manner include ``Tkinter``,
-and ``threading``.
-
-Import modules at the top of a file. Doing so makes it clear what
-other modules your code requires and avoids questions of whether the
-module name is in scope. Using one import per line makes it easy to
-add and delete module imports, but using multiple imports per line
-uses less screen space.
-
-It's good practice if you import modules in the following order:
-
-1. standard libary modules -- e.g. ``sys``, ``os``, ``getopt``, ``re``)
-2. third-party library modules (anything installed in Python's
- site-packages directory) -- e.g. mx.DateTime, ZODB, PIL.Image, etc.
-3. locally-developed modules
-
-Never use relative package imports. If you're writing code that's
-in the ``package.sub.m1`` module and want to import ``package.sub.m2``,
-do not just write ``import m2``, even though it's legal.
-Write ``from package.sub import m2`` instead. Relative imports can lead to a
-module being initialized twice, leading to confusing bugs.
-
-It is sometimes necessary to move imports to a function or class to
-avoid problems with circular imports. Gordon McMillan says:
-
- Circular imports are fine where both modules use the "import <module>"
- form of import. They fail when the 2nd module wants to grab a name
- out of the first ("from module import name") and the import is at
- the top level. That's because names in the 1st are not yet available,
- because the first module is busy importing the 2nd.
-
-In this case, if the second module is only used in one function, then the
-import can easily be moved into that function. By the time the import
-is called, the first module will have finished initializing, and the
-second module can do its import.
-
-It may also be necessary to move imports out of the top level of code
-if some of the modules are platform-specific. In that case, it may
-not even be possible to import all of the modules at the top of the
-file. In this case, importing the correct modules in the
-corresponding platform-specific code is a good option.
-
-Only move imports into a local scope, such as inside a function
-definition, if it's necessary to solve a problem such as avoiding a
-circular import or are trying to reduce the initialization time of a
-module. This technique is especially helpful if many of the imports
-are unnecessary depending on how the program executes. You may also
-want to move imports into a function if the modules are only ever used
-in that function. Note that loading a module the first time may be
-expensive because of the one time initialization of the module, but
-loading a module multiple times is virtually free, costing only a couple of
-dictionary lookups. Even if the module name has gone out of scope,
-the module is probably available in sys.modules.
-
-If only instances of a specific class use a module, then it is
-reasonable to import the module in the class's ``__init__`` method and
-then assign the module to an instance variable so that the module is
-always available (via that instance variable) during the life of the
-object. Note that to delay an import until the class is instantiated,
-the import must be inside a method. Putting the import inside the
-class but outside of any method still causes the import to occur when
-the module is initialized.
-
-How can I pass optional or keyword parameters from one function to another?
--------------------------------------------------------------------------------
-
-Collect the arguments using the ``*`` and ``**`` specifiers in the function's
-parameter list; this gives you the positional arguments as a tuple
-and the keyword arguments as a dictionary. You can
-then pass these arguments when calling another function by using
-``*`` and ``**``::
-
-
- def f(x, *tup, **kwargs):
- ...
- kwargs['width']='14.3c'
- ...
- g(x, *tup, **kwargs)
-
-In the unlikely case that you care about Python
-versions older than 2.0, use 'apply'::
-
- def f(x, *tup, **kwargs):
- ...
- kwargs['width']='14.3c'
- ...
- apply(g, (x,)+tup, kwargs)
-
-
-
-How do I write a function with output parameters (call by reference)?
------------------------------------------------------------------------------
-
-Remember that arguments are passed by assignment in Python. Since
-assignment just creates references to objects, there's no alias
-between an argument name in the caller and callee, and so no
-call-by-reference per se. You can achieve the desired effect in a
-number of ways.
-
-1) By returning a tuple of the results::
-
- def func2(a, b):
- a = 'new-value' # a and b are local names
- b = b + 1 # assigned to new objects
- return a, b # return new values
-
- x, y = 'old-value', 99
- x, y = func2(x, y)
- print x, y # output: new-value 100
-
- This is almost always the clearest solution.
-
-2) By using global variables. This isn't thread-safe, and is not
- recommended.
-
-3) By passing a mutable (changeable in-place) object::
-
- def func1(a):
- a[0] = 'new-value' # 'a' references a mutable list
- a[1] = a[1] + 1 # changes a shared object
-
- args = ['old-value', 99]
- func1(args)
- print args[0], args[1] # output: new-value 100
-
-4) By passing in a dictionary that gets mutated::
-
- def func3(args):
- args['a'] = 'new-value' # args is a mutable dictionary
- args['b'] = args['b'] + 1 # change it in-place
-
- args = {'a':' old-value', 'b': 99}
- func3(args)
- print args['a'], args['b']
-
-5) Or bundle up values in a class instance::
-
- class callByRef:
- def __init__(self, **args):
- for (key, value) in args.items():
- setattr(self, key, value)
-
- def func4(args):
- args.a = 'new-value' # args is a mutable callByRef
- args.b = args.b + 1 # change object in-place
-
- args = callByRef(a='old-value', b=99)
- func4(args)
- print args.a, args.b
-
-
- There's almost never a good reason to get this complicated.
-
-Your best choice is to return a tuple containing the multiple results.
-
-How do you make a higher order function in Python?
-----------------------------------------------------------
-You have two choices: you can use nested scopes
-or you can use callable objects. For example, suppose you wanted to
-define ``linear(a,b)`` which returns a function ``f(x)`` that computes the
-value ``a*x+b``. Using nested scopes::
-
- def linear(a,b):
- def result(x):
- return a*x + b
- return result
-
-Or using a callable object::
-
- class linear:
- def __init__(self, a, b):
- self.a, self.b = a,b
- def __call__(self, x):
- return self.a * x + self.b
-
-In both cases::
-
- taxes = linear(0.3,2)
-
-gives a callable object where taxes(10e6) == 0.3 * 10e6 + 2.
-
-The callable object approach has the disadvantage that it is a bit
-slower and results in slightly longer code. However, note that a
-collection of callables can share their signature via inheritance::
-
- class exponential(linear):
- # __init__ inherited
- def __call__(self, x):
- return self.a * (x ** self.b)
-
-Object can encapsulate state for several methods::
-
- class counter:
- value = 0
- def set(self, x): self.value = x
- def up(self): self.value=self.value+1
- def down(self): self.value=self.value-1
-
- count = counter()
- inc, dec, reset = count.up, count.down, count.set
-
-Here ``inc()``, ``dec()`` and ``reset()`` act like functions which share the
-same counting variable.
-
-
-How do I copy an object in Python?
-------------------------------------------
-
-In general, try copy.copy() or copy.deepcopy() for the general case. Not all
-objects can be copied, but most can.
-
-Some objects can be copied more easily.
-Dictionaries have a ``copy()`` method::
-
- newdict = olddict.copy()
-
-Sequences can be copied by slicing::
-
- new_l = l[:]
-
-
-How can I find the methods or attributes of an object?
---------------------------------------------------------------
-For an instance x of a user-defined class, ``dir(x)`` returns an
-alphabetized list of the names containing the instance attributes and
-methods and attributes defined by its class.
-
-
-How can my code discover the name of an object?
--------------------------------------------------------
-
-Generally speaking, it can't, because objects don't really have
-names. Essentially, assignment always binds a name to a value; The
-same is true of ``def`` and ``class`` statements, but in that case the
-value is a callable. Consider the following code::
-
- class A:
- pass
-
- B = A
-
- a = B()
- b = a
- print b
- <__main__.A instance at 016D07CC>
- print a
- <__main__.A instance at 016D07CC>
-
-
-Arguably the class has a name: even though it is bound to two names
-and invoked through the name B the created instance is still reported
-as an instance of class A. However, it is impossible to say whether
-the instance's name is a or b, since both names are bound to the same
-value.
-
-Generally speaking it should not be necessary for your code to "know
-the names" of particular values. Unless you are deliberately writing
-introspective programs, this is usually an indication that a change of
-approach might be beneficial.
-
-In comp.lang.python, Fredrik Lundh once gave an excellent analogy in
-answer to this question:
-
- The same way as you get the name of that cat you found on your
- porch: the cat (object) itself cannot tell you its name, and it
- doesn't really care -- so the only way to find out what it's called
- is to ask all your neighbours (namespaces) if it's their cat
- (object)...
-
- ....and don't be surprised if you'll find that it's known by many
- names, or no name at all!
-
-
-
-Is there an equivalent of C's "?:" ternary operator?
-----------------------------------------------------------------------
-No. In many cases you can mimic a?b:c with "a and b or
-c", but there's a flaw: if b is zero (or empty, or None -- anything
-that tests false) then c will be selected instead. In many cases you
-can prove by looking at the code that this can't happen (e.g. because
-b is a constant or has a type that can never be false), but in general
-this can be a problem.
-
-Tim Peters (who wishes it was Steve Majewski) suggested the following
-solution: (a and [b] or [c])[0]. Because [b] is a singleton list it
-is never false, so the wrong path is never taken; then applying [0] to
-the whole thing gets the b or c that you really wanted. Ugly, but it
-gets you there in the rare cases where it is really inconvenient to
-rewrite your code using 'if'.
-
-The best course is usually to write a simple ``if...else`` statement.
-Another solution is to implement the "?:" operator as a function::
-
- def q(cond,on_true,on_false):
- if cond:
- if not isfunction(on_true): return on_true
- else: return apply(on_true)
- else:
- if not isfunction(on_false): return on_false
- else: return apply(on_false)
-
-In most cases you'll pass b and c directly: ``q(a,b,c)``. To avoid
-evaluating b or c when they shouldn't be, encapsulate them within a
-lambda function, e.g.: ``q(a,lambda: b, lambda: c)``.
-
-It has been asked *why* Python has no if-then-else expression.
-There are several answers: many languages do
-just fine without one; it can easily lead to less readable code;
-no sufficiently "Pythonic" syntax has been discovered; a search
-of the standard library found remarkably few places where using an
-if-then-else expression would make the code more understandable.
-
-In 2002, `PEP 308 <../../peps/pep-0308.html>`_ was
-written proposing several possible syntaxes and the community was
-asked to vote on the issue. The vote was inconclusive. Most people
-liked one of the syntaxes, but also hated other syntaxes; many votes
-implied that people preferred no ternary operator
-rather than having a syntax they hated.
-
-Is it possible to write obfuscated one-liners in Python?
-----------------------------------------------------------------
-Yes. Usually this is done by nesting `lambda` within `lambda`.
-See the following three examples, due to Ulf Bartelt::
-
- # Primes < 1000
- print filter(None,map(lambda y:y*reduce(lambda x,y:x*y!=0,
- map(lambda x,y=y:y%x,range(2,int(pow(y,0.5)+1))),1),range(2,1000)))
-
- # First 10 Fibonacci numbers
- print map(lambda x,f=lambda x,f:(x<=1) or (f(x-1,f)+f(x-2,f)): f(x,f),
- range(10))
-
- # Mandelbrot set
- print (lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+y,map(lambda y,
- Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,Sy=Sy,L=lambda yc,Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,i=IM,
- Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro,
- i=i,Sx=Sx,F=lambda xc,yc,x,y,k,f=lambda xc,yc,x,y,k,f:(k<=0)or (x*x+y*y
- >=4.0) or 1+f(xc,yc,x*x-y*y+xc,2.0*x*y+yc,k-1,f):f(xc,yc,x,y,k,f):chr(
- 64+F(Ru+x*(Ro-Ru)/Sx,yc,0,0,i)),range(Sx))):L(Iu+y*(Io-Iu)/Sy),range(Sy
- ))))(-2.1, 0.7, -1.2, 1.2, 30, 80, 24)
- # \___ ___ \___ ___ | | |__ lines on screen
- # V V | |______ columns on screen
- # | | |__________ maximum of "iterations"
- # | |_________________ range on y axis
- # |____________________________ range on x axis
-
-Don't try this at home, kids!
-
-
-Numbers and strings
-==========================
-
-How do I specify hexadecimal and octal integers?
---------------------------------------------------------
-
-To specify an octal digit, precede the octal value with a zero. For
-example, to set the variable "a" to the octal value "10" (8 in
-decimal), type::
-
- >>> a = 010
- >>> a
- 8
-
-Hexadecimal is just as easy. Simply precede the hexadecimal number with a
-zero, and then a lower or uppercase "x". Hexadecimal digits can be specified
-in lower or uppercase. For example, in the Python interpreter::
-
- >>> a = 0xa5
- >>> a
- 165
- >>> b = 0XB2
- >>> b
- 178
-
-
-Why does -22 / 10 return -3?
-----------------------------------
-
-It's primarily driven by the desire that ``i%j`` have the same sign as
-``j``. If you want that, and also want::
-
- i == (i/j)*j + (i%j)
-
-then integer division has to return the floor. C also requres that identity
-to hold, and then compilers that truncate ``i/j`` need to make ``i%j`` have
-the same sign as ``i``.
-
-There are few real use cases for ``i%j`` when ``j`` is negative. When ``j``
-is positive, there are many, and in virtually all of them it's more useful
-for ``i%j`` to be ``>= 0``. If the clock says 10 now, what did it say 200
-hours ago? ``-190 % 12 == 2`` is useful; ``-190 % 12 == -10`` is a bug
-waiting to bite.
-
-How do I convert a string to a number?
-----------------------------------------------
-
-For integers, use the built-in ``int()`` type constructor,
-e.g. int('144') == 144. Similarly, ``float()`` converts to
-floating-point, e.g. ``float('144') == 144.0``.
-
-By default, these interpret the number as decimal, so that
-``int('0144') == 144`` and ``int('0x144')`` raises
-``ValueError``. ``int(string, base)`` takes the base to convert from
-as a second optional argument, so ``int('0x144', 16) == 324``. If the
-base is specified as 0, the number is interpreted using Python's
-rules: a leading '0' indicates octal, and '0x' indicates a hex number.
-
-Do not use the built-in function ``eval()`` if all you need is to
-convert strings to numbers. ``eval()`` will be significantly slower
-and it presents a security risk: someone could pass you a Python
-expression that might have unwanted side effects. For example,
-someone could pass ``__import__('os').system("rm -rf $HOME")`` which
-would erase your home directory.
-
-``eval()`` also has the effect of interpreting numbers as Python
-expressions, so that e.g. eval('09') gives a syntax error because Python
-regards numbers starting with '0' as octal (base 8).
-
-
-How do I convert a number to a string?
-----------------------------------------------
-
-To convert, e.g., the number 144 to the string '144', use the built-in
-function ``str()``. If you want a hexadecimal or octal
-representation, use the built-in functions ``hex()`` or ``oct()``.
-For fancy formatting, use `the % operator <../../doc/lib/typesseq-strings.html>`_ on strings, e.g. ``"%04d" % 144``
-yields '0144' and ``"%.3f" % (1/3.0)`` yields '0.333'. See the library
-reference manual for details.
-
-How do I modify a string in place?
-------------------------------------------
-
-You can't, because strings are immutable. If you need an object with
-this ability, try converting the string to a list or use the array
-module::
-
- >>> s = "Hello, world"
- >>> a = list(s)
- >>> print a
- ['H', 'e', 'l', 'l', 'o', ',', ' ', 'w', 'o', 'r', 'l', 'd']
- >>> a[7:] = list("there!")
- >>> ''.join(a)
- 'Hello, there!'
-
- >>> import array
- >>> a = array.array('c', s)
- >>> print a
- array('c', 'Hello, world')
- >>> a[0] = 'y' ; print a
- array('c', 'yello world')
- >>> a.tostring()
- 'yello, world'
-
-
-
-How do I use strings to call functions/methods?
-----------------------------------------------------------
-
-There are various techniques.
-
-* The best is to use a dictionary that maps strings to functions. The
- primary advantage of this technique is that the strings do not need
- to match the names of the functions. This is also the primary
- technique used to emulate a case construct::
-
- def a():
- pass
-
- def b():
- pass
-
- dispatch = {'go': a, 'stop': b} # Note lack of parens for funcs
-
- dispatch[get_input()]() # Note trailing parens to call function
-
-* Use the built-in function ``getattr()``::
-
- import foo
- getattr(foo, 'bar')()
-
- Note that getattr() works on any object, including classes, class
- instances, modules, and so on.
-
- This is used in several places in the standard library, like
- this::
-
- class Foo:
- def do_foo(self):
- ...
-
- def do_bar(self):
- ...
-
- f = getattr(foo_instance, 'do_' + opname)
- f()
-
-
-* Use ``locals()`` or ``eval()`` to resolve the function name::
-
- def myFunc():
- print "hello"
-
- fname = "myFunc"
-
- f = locals()[fname]
- f()
-
- f = eval(fname)
- f()
-
- Note: Using ``eval()`` is slow and dangerous. If you don't have absolute control
- over the contents of the string, someone could pass a string that
- resulted in an arbitrary function being executed.
-
-Is there an equivalent to Perl's chomp() for removing trailing newlines from strings?
---------------------------------------------------------------------------------------------
-
-Starting with Python 2.2, you can use ``S.rstrip("\r\n")`` to remove
-all occurances of any line terminator from the end of the string ``S``
-without removing other trailing whitespace. If the string ``S``
-represents more than one line, with several empty lines at the end,
-the line terminators for all the blank lines will be removed::
-
- >>> lines = ("line 1 \r\n"
- ... "\r\n"
- ... "\r\n")
- >>> lines.rstrip("\n\r")
- "line 1 "
-
-Since this is typically only desired when reading text one line at a
-time, using ``S.rstrip()`` this way works well.
-
-For older versions of Python, There are two partial substitutes:
-
-- If you want to remove all trailing whitespace, use the ``rstrip()``
- method of string objects. This removes all trailing whitespace, not
- just a single newline.
-
-- Otherwise, if there is only one line in the string ``S``, use
- ``S.splitlines()[0]``.
-
-
-Is there a scanf() or sscanf() equivalent?
---------------------------------------------------
-Not as such.
-
-For simple input parsing, the easiest approach is usually to split the
-line into whitespace-delimited words using the ``split()`` method of
-string objects and then convert decimal strings to numeric values using
-``int()`` or ``float()``. ``split()`` supports an optional "sep"
-parameter which is useful if the line uses something other than
-whitespace as a separator.
-
-For more complicated input parsing, regular expressions
-more powerful than C's ``sscanf()`` and better suited for the task.
-
-
-What does 'UnicodeError: ASCII [decoding,encoding] error: ordinal not in range(128)' mean?
------------------------------------------------------------------------------------------------------
-This error indicates that your Python installation can handle
-only 7-bit ASCII strings. There are a couple ways to fix or
-work around the problem.
-
-If your programs must handle data in arbitary character set encodings,
-the environment the application runs in will generally identify the
-encoding of the data it is handing you. You need to convert the input
-to Unicode data using that encoding. For example, a program that
-handles email or web input will typically find character set encoding
-information in Content-Type headers. This can then be used to
-properly convert input data to Unicode. Assuming the string referred
-to by ``value`` is encoded as UTF-8::
-
- value = unicode(value, "utf-8")
-
-will return a Unicode object. If the data is not correctly encoded as
-UTF-8, the above call will raise a ``UnicodeError`` exception.
-
-If you only want strings coverted to Unicode which have non-ASCII
-data, you can try converting them first assuming an ASCII encoding,
-and then generate Unicode objects if that fails::
-
- try:
- x = unicode(value, "ascii")
- except UnicodeError:
- value = unicode(value, "utf-8")
- else:
- # value was valid ASCII data
- pass
-
-It's possible to set a default encoding in a file called ``sitecustomize.py``
-that's part of the Python library. However, this isn't recommended because changing the Python-wide default encoding may cause third-party extension modules to fail.
-
-Note that on Windows, there is an encoding known as "mbcs", which uses
-an encoding specific to your current locale. In many cases, and
-particularly when working with COM, this may be an appropriate default
-encoding to use.
-
-
-Sequences (Tuples/Lists)
-=================================
-
-How do I convert between tuples and lists?
-------------------------------------------------
-
-The function ``tuple(seq)`` converts any sequence (actually, any
-iterable) into a tuple with the same items in the same order.
-
-For example, ``tuple([1, 2, 3])`` yields ``(1, 2, 3)`` and ``tuple('abc')``
-yields ``('a', 'b', 'c')``. If the argument is
-a tuple, it does not make a copy but returns the same object, so
-it is cheap to call ``tuple()`` when you aren't sure that an object
-is already a tuple.
-
-The function ``list(seq)`` converts any sequence or iterable into a list with
-the same items in the same order.
-For example, ``list((1, 2, 3))`` yields ``[1, 2, 3]`` and ``list('abc')``
-yields ``['a', 'b', 'c']``. If the argument is a list,
-it makes a copy just like ``seq[:]`` would.
-
-What's a negative index?
---------------------------------------------------------------------
-Python sequences are indexed with positive numbers and
-negative numbers. For positive numbers 0 is the first index
-1 is the second index and so forth. For negative indices -1
-is the last index and -2 is the pentultimate (next to last) index
-and so forth. Think of ``seq[-n]`` as the same as ``seq[len(seq)-n]``.
-
-Using negative indices can be very convenient. For example ``S[:-1]``
-is all of the string except for its last character, which is useful
-for removing the trailing newline from a string.
-
-
-How do I iterate over a sequence in reverse order?
----------------------------------------------------------
-If it is a list, the fastest solution is ::
-
- list.reverse()
- try:
- for x in list:
- "do something with x"
- finally:
- list.reverse()
-
-This has the disadvantage that while you are in the loop, the list
-is temporarily reversed. If you don't like this, you can make a copy.
-This appears expensive but is actually faster than other solutions::
-
- rev = list[:]
- rev.reverse()
- for x in rev:
- <do something with x>
-
-If it's not a list, a more general but slower solution is::
-
- for i in range(len(sequence)-1, -1, -1):
- x = sequence[i]
- <do something with x>
-
-A more elegant solution, is to define a class which acts as a sequence
-and yields the elements in reverse order (solution due to Steve
-Majewski)::
-
- class Rev:
- def __init__(self, seq):
- self.forw = seq
- def __len__(self):
- return len(self.forw)
- def __getitem__(self, i):
- return self.forw[-(i + 1)]
-
-You can now simply write::
-
- for x in Rev(list):
- <do something with x>
-
-Unfortunately, this solution is slowest of all, due to the method
-call overhead.
-
-With Python 2.3, you can use an extended slice syntax::
-
- for x in sequence[::-1]:
- <do something with x>
-
-How do you remove duplicates from a list?
--------------------------------------------------
-See the Python Cookbook for a long discussion of many ways to do this:
-
- http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52560
-
-If you don't mind reordering the list, sort it and then scan from the
-end of the list, deleting duplicates as you go::
-
- if List:
- List.sort()
- last = List[-1]
- for i in range(len(List)-2, -1, -1):
- if last==List[i]: del List[i]
- else: last=List[i]
-
-If all elements of the list may be used as
-dictionary keys (i.e. they are all hashable)
-this is often faster ::
-
- d = {}
- for x in List: d[x]=x
- List = d.values()
-
-How do you make an array in Python?
-----------------------------------------------------
-Use a list::
-
- ["this", 1, "is", "an", "array"]
-
-Lists are equivalent to C or Pascal arrays in their time complexity;
-the primary difference is that a Python list can contain objects of
-many different types.
-
-The ``array`` module also provides methods for creating arrays of
-fixed types with compact representations, but they are slower to index
-than lists. Also note that the Numeric extensions and others define
-array-like structures with various characteristics as well.
-
-To get Lisp-style linked lists, you can emulate cons cells using tuples::
-
- lisp_list = ("like", ("this", ("example", None) ) )
-
-If mutability is desired, you could use lists instead of tuples. Here
-the analogue of lisp car is ``lisp_list[0]`` and the analogue of cdr
-is ``lisp_list[1]``. Only do this if you're sure you really need to,
-because it's usually a lot slower than using Python lists.
-
-How do I create a multidimensional list?
----------------------------------------------------------------
-You probably tried to make a multidimensional array like this::
-
- A = [[None] * 2] * 3
-
-This looks correct if you print it::
-
- >>> A
- [[None, None], [None, None], [None, None]]
-
-But when you assign a value, it shows up in multiple places:
-
- >>> A[0][0] = 5
- >>> A
- [[5, None], [5, None], [5, None]]
-
-The reason is that replicating a list with ``*`` doesn't create copies, it only creates references to the existing objects. The ``*3``
-creates a list containing 3 references to the same list of length
-two. Changes to one row will show in all rows, which is almost certainly
-not what you want.
-
-The suggested approach is to create a list of the desired length first
-and then fill in each element with a newly created list::
-
- A = [None]*3
- for i in range(3):
- A[i] = [None] * 2
-
-This generates a list containing 3 different lists of length two.
-You can also use a list comprehension::
-
- w,h = 2,3
- A = [ [None]*w for i in range(h) ]
-
-Or, you can use an extension that provides a matrix datatype; `Numeric
-Python <http://www.pfdubois.com/numpy/>`_ is the best known.
-
-
-How do I apply a method to a sequence of objects?
---------------------------------------------------------------------------
-
-Use a list comprehension::
-
- result = [obj.method() for obj in List]
-
-More generically, you can try the following function::
-
- def method_map(objects, method, arguments):
- """method_map([a,b], "meth", (1,2)) gives [a.meth(1,2), b.meth(1,2)]"""
- nobjects = len(objects)
- methods = map(getattr, objects, [method]*nobjects)
- return map(apply, methods, [arguments]*nobjects)
-
-
-Dictionaries
-==================
-
-How can I get a dictionary to display its keys in a consistent order?
------------------------------------------------------------------------------
-
-You can't. Dictionaries store their keys in an unpredictable order,
-so the display order of a dictionary's elements will be similarly
-unpredictable.
-
-This can be frustrating if you want to save a printable version to a
-file, make some changes and then compare it with some other printed
-dictionary. In this case, use the ``pprint`` module to pretty-print
-the dictionary; the items will be presented in order sorted by the key.
-
-A more complicated solution is to subclass ``UserDict.UserDict``
-to create a ``SortedDict`` class that prints itself in a predictable order.
-Here's one simpleminded implementation of such a class::
-
- import UserDict, string
-
- class SortedDict(UserDict.UserDict):
- def __repr__(self):
- result = []
- append = result.append
- keys = self.data.keys()
- keys.sort()
- for k in keys:
- append("%s: %s" % (`k`, `self.data[k]`))
- return "{%s}" % string.join(result, ", ")
-
- ___str__ = __repr__
-
-
-This will work for many common situations you might encounter, though
-it's far from a perfect solution. The largest flaw is that if some
-values in the dictionary are also dictionaries, their values won't be
-presented in any particular order.
-
-I want to do a complicated sort: can you do a Schwartzian Transform in Python?
---------------------------------------------------------------------------------------
-
-Yes, it's quite simple with list comprehensions.
-
-The technique, attributed to Randal Schwartz of the Perl community,
-sorts the elements of a list by a metric which maps each element to
-its "sort value". To sort a list of strings by their uppercase
-values::
-
- tmp1 = [ (x.upper(), x) for x in L ] # Schwartzian transform
- tmp1.sort()
- Usorted = [ x[1] for x in tmp1 ]
-
-To sort by the integer value of a subfield extending from positions 10-15
-in each string::
-
- tmp2 = [ (int(s[10:15]), s) for s in L ] # Schwartzian transform
- tmp2.sort()
- Isorted = [ x[1] for x in tmp2 ]
-
-Note that Isorted may also be computed by ::
-
- def intfield(s):
- return int(s[10:15])
-
- def Icmp(s1, s2):
- return cmp(intfield(s1), intfield(s2))
-
- Isorted = L[:]
- Isorted.sort(Icmp)
-
-but since this method calls ``intfield()`` many times for each element
-of L, it is slower than the Schwartzian Transform.
-
-
-How can I sort one list by values from another list?
-------------------------------------------------------------
-
-Merge them into a single list of tuples, sort the resulting list,
-and then pick out the element you want. ::
-
- >>> list1 = ["what", "I'm", "sorting", "by"]
- >>> list2 = ["something", "else", "to", "sort"]
- >>> pairs = zip(list1, list2)
- >>> pairs
- [('what', 'something'), ("I'm", 'else'), ('sorting', 'to'), ('by', 'sort')]
- >>> pairs.sort()
- >>> result = [ x[1] for x in pairs ]
- >>> result
- ['else', 'sort', 'to', 'something']
-
-An alternative for the last step is::
-
- result = []
- for p in pairs: result.append(p[1])
-
-If you find this more legible, you might prefer to use this instead of
-the final list comprehension. However, it is almost twice as slow for
-long lists. Why? First, the ``append()`` operation has to reallocate
-memory, and while it uses some tricks to avoid doing that each time,
-it still has to do it occasionally, and that costs quite a bit.
-Second, the expression "result.append" requires an extra attribute
-lookup, and third, there's a speed reduction from having to make
-all those function calls.
-
-
-Objects
-=============
-
-What is a class?
-------------------------
-A class is the particular object type created by executing
-a class statement. Class objects are used as templates to create
-instance objects, which embody both the data
-(attributes) and code (methods) specific to a datatype.
-
-A class can be based on one or more other classes, called its base
-class(es). It then inherits the attributes and methods of its base
-classes. This allows an object model to be successively refined by
-inheritance. You might have a generic ``Mailbox`` class that provides
-basic accessor methods for a mailbox, and subclasses such as
-``MboxMailbox``, ``MaildirMailbox``, ``OutlookMailbox`` that handle
-various specific mailbox formats.
-
-
-What is a method?
--------------------------
-
-A method is a function on some object ``x`` that you normally call as
-``x.name(arguments...)``. Methods are defined as functions inside the
-class definition::
-
- class C:
- def meth (self, arg):
- return arg*2 + self.attribute
-
-What is self?
----------------------
-
-Self is merely a conventional name for the first argument of a method.
-A method defined as ``meth(self, a, b, c)`` should be called as
-``x.meth(a, b, c)`` for some instance ``x`` of the class in which the
-definition occurs; the called method will think it is called as
-``meth(x, a, b, c)``.
-
-See also
-`Why must 'self' be used explicitly in method definitions and calls?
-<general.html#why-must-self-be-used-explicitly-in-method-definitions-and-calls>`_
-
-How do I check if an object is an instance of a given class or of a subclass of it?
--------------------------------------------------------------------------------------------
-
-Use the built-in function ``isinstance(obj, cls)``. You can check if
-an object is an instance of any of a number of classes by providing a tuple instead of a single class, e.g. ``isinstance(obj, (class1, class2, ...))``,
-and can also check whether an object is one of Python's built-in types, e.g.
-``isinstance(obj, str)`` or ``isinstance(obj, (int, long, float, complex))``.
-
-Note that most programs do not use ``isinstance()`` on user-defined
-classes very often. If you are developing the classes yourself, a
-more proper object-oriented style is to define methods on the classes
-that encapsulate a particular behaviour, instead of checking the
-object's class and doing a different thing based on what class it is.
-For example, if you have a function that does something::
-
- def search (obj):
- if isinstance(obj, Mailbox):
- # ... code to search a mailbox
- elif isinstance(obj, Document):
- # ... code to search a document
- elif ...
-
-A better approach is to define a ``search()`` method on all the
-classes and just call it::
-
- class Mailbox:
- def search(self):
- # ... code to search a mailbox
-
- class Document:
- def search(self):
- # ... code to search a document
-
- obj.search()
-
-
-What is delegation?
----------------------------
-
-Delegation is an object oriented technique (also called a design
-pattern). Let's say you have an object ``x`` and want to change the
-behaviour of just one of its methods. You can create a new class that
-provides a new implementation of the method you're interested in changing
-and delegates all other methods to the corresponding method of ``x``.
-
-Python programmers can easily implement delegation. For example, the
-following class implements a class that behaves like a file but
-converts all written data to uppercase::
-
- class UpperOut:
- def __init__(self, outfile):
- self.__outfile = outfile
- def write(self, s):
- self.__outfile.write(s.upper())
- def __getattr__(self, name):
- return getattr(self.__outfile, name)
-
-Here the ``UpperOut`` class redefines the ``write()`` method to
-convert the argument string to uppercase before calling the underlying
-``self.__outfile.write()`` method. All other methods are delegated to
-the underlying ``self.__outfile`` object. The delegation is
-accomplished via the ``__getattr__`` method; consult `the language
-reference <../../doc/ref/attribute-access.html>`_ for
-more information about controlling attribute access.
-
-Note that for more general cases delegation can get trickier. When
-attributes must be set as well as retrieved, the class must define a
-``__settattr__`` method too, and it must do so carefully. The basic
-implementation of __setattr__ is roughly equivalent to the following::
-
- class X:
- ...
- def __setattr__(self, name, value):
- self.__dict__[name] = value
- ...
-
-Most __setattr__ implementations must modify
-self.__dict__ to store local state for self without
-causing an infinite recursion.
-
-How do I call a method defined in a base class from a derived class that overrides it?
-----------------------------------------------------------------------------------------------
-
-If you're using new-style classes, use the built-in ``super()`` function::
-
- class Derived(Base):
- def meth (self):
- super(Derived, self).meth()
-
-If you're using classic classes: For a class definition such as
-``class Derived(Base): ...`` you can call method ``meth()`` defined in
-``Base`` (or one of ``Base``'s base classes) as ``Base.meth(self,
-arguments...)``. Here, ``Base.meth`` is an unbound method, so you
-need to provide the ``self`` argument.
-
-How can I organize my code to make it easier to change the base class?
-------------------------------------------------------------------------------
-You could define an alias for the base class, assign the real base
-class to it before your class definition, and use the alias throughout
-your class. Then all you have to change is the value assigned to the
-alias. Incidentally, this trick is also handy if you want to decide
-dynamically (e.g. depending on availability of resources) which base
-class to use. Example::
-
- BaseAlias = <real base class>
- class Derived(BaseAlias):
- def meth(self):
- BaseAlias.meth(self)
- ...
-
-
-How do I create static class data and static class methods?
--------------------------------------------------------------------
-
-Static data (in the sense of C++ or Java) is easy; static methods
-(again in the sense of C++ or Java) are not supported directly.
-
-For static data, simply define a class attribute. To assign a new
-value to the attribute, you have to explicitly use the class name in
-the assignment::
-
- class C:
- count = 0 # number of times C.__init__ called
-
- def __init__(self):
- C.count = C.count + 1
-
- def getcount(self):
- return C.count # or return self.count
-
-``c.count`` also refers to ``C.count`` for any ``c`` such that
-``isinstance(c, C)`` holds, unless overridden by ``c`` itself or by some
-class on the base-class search path from ``c.__class__`` back to ``C``.
-
-Caution: within a method of C, an assignment like ``self.count = 42``
-creates a new and unrelated instance vrbl named "count" in ``self``'s own dict.
-Rebinding of a class-static data name must always specify the class
-whether inside a method or not::
-
- C.count = 314
-
-
-Static methods are possible when you're using new-style classes::
-
- class C:
- def static(arg1, arg2, arg3):
- # No 'self' parameter!
- ...
- static = staticmethod(static)
-
-However, a far more straightforward way to get the effect of a static
-method is via a simple module-level function::
-
- def getcount():
- return C.count
-
-If your code is structured so as to define one class (or tightly
-related class hierarchy) per module, this supplies the desired
-encapsulation.
-
-
-How can I overload constructors (or methods) in Python?
----------------------------------------------------------------
-This answer actually applies to all methods, but the question
-usually comes up first in the context of constructors.
-
-In C++ you'd write ::
-
- class C {
- C() { cout << "No arguments\n"; }
- C(int i) { cout << "Argument is " << i << "\n"; }
- }
-
-in Python you have to write a single constructor that catches all
-cases using default arguments. For example::
-
- class C:
- def __init__(self, i=None):
- if i is None:
- print "No arguments"
- else:
- print "Argument is", i
-
-This is not entirely equivalent, but close enough in practice.
-
-You could also try a variable-length argument list, e.g. ::
-
- def __init__(self, *args):
- ....
-
-The same approach works for all method definitions.
-
-
-I try to use __spam and I get an error about _SomeClassName__spam.
---------------------------------------------------------------------------
-Variables with double leading underscore are "mangled" to provide a
-simple but effective way to define class private variables. Any
-identifier of the form ``__spam`` (at least two leading
-underscores, at most one trailing underscore) is textually
-replaced with ``_classname__spam``, where ``classname`` is the
-current class name with any leading underscores stripped.
-
-This doesn't guarantee privacy: an outside user can still deliberately
-access the "_classname__spam" attribute, and private values are visible
-in the object's ``__dict__``. Many Python programmers never bother to use
-private variable names at all.
-
-
-My class defines __del__ but it is not called when I delete the object.
--------------------------------------------------------------------------------
-There are several possible reasons for this.
-
-The del statement does not necessarily call __del__ -- it simply
-decrements the object's reference count, and if this reaches zero
-__del__ is called.
-
-If your data structures contain circular links (e.g. a tree where each
-child has a parent reference and each parent has a list of children)
-the reference counts will never go back to zero. Once in a while
-Python runs an algorithm to detect such cycles, but the garbage
-collector might run some time after the last reference to your data
-structure vanishes, so your __del__ method may be called at an
-inconvenient and random time. This is inconvenient if you're trying to
-reproduce a problem. Worse, the order in which object's __del__
-methods are executed is arbitrary. You can run ``gc.collect()`` to
-force a collection, but there *are* pathological cases where objects will
-never be collected.
-
-Despite the cycle collector, it's still a good idea to define an
-explicit ``close()`` method on objects to be called whenever you're
-done with them. The ``close()`` method can then remove attributes
-that refer to subobjecs. Don't call ``__del__`` directly --
-``__del__`` should call ``close()`` and ``close()`` should make sure
-that it can be called more than once for the same object.
-
-Another way to avoid cyclical references is to use the "weakref"
-module, which allows you to point to objects without incrementing
-their reference count. Tree data structures, for instance, should use
-weak references for their parent and sibling references (if they need
-them!).
-
-If the object has ever been a local variable in a function that caught
-an expression in an except clause, chances are that a reference to the
-object still exists in that function's stack frame as contained in the
-stack trace. Normally, calling ``sys.exc_clear()`` will take care of
-this by clearing the last recorded exception.
-
-Finally, if your __del__ method raises an exception, a warning message
-is printed to sys.stderr.
-
-
-How do I get a list of all instances of a given class?
---------------------------------------------------------------
-
-Python does not keep track of all instances of a class (or of a
-built-in type). You can program the class's constructor to keep track
-of all instances by keeping a list of weak references to each
-instance.
-
-
-Modules
-=============
-How do I create a .pyc file?
--------------------------------------
-
-When a module is imported for the first time (or when the source is
-more recent than the current compiled file) a ``.pyc`` file containing
-the compiled code should be created in the same directory as the
-``.py`` file.
-
-One reason that a ``.pyc`` file may not be created is permissions
-problems with the directory. This can happen, for example, if you
-develop as one user but run as another, such as if you are testing
-with a web server. Creation of a .pyc file is automatic if you're
-importing a module and Python has the ability (permissions, free
-space, etc...) to write the compiled module back to the directory.
-
-Running Python on a top level script is not considered an import and
-no ``.pyc`` will be created. For example, if you have a top-level
-module ``abc.py`` that imports another module ``xyz.py``, when you run
-abc, ``xyz.pyc`` will be created since xyz is imported, but no
-``abc.pyc`` file will be created since ``abc.py`` isn't being
-imported.
-
-If you need to create abc.pyc -- that is, to create a .pyc file for a
-module that is not imported -- you can, using the py_compile and
-compileall modules.
-
-The ``py_compile`` module can manually compile any module. One way is
-to use the ``compile()`` function in that module interactively::
-
- >>> import py_compile
- >>> py_compile.compile('abc.py')
-
-This will write the ``.pyc`` to the same location as ``abc.py`` (or
-you can override that with the optional parameter ``cfile``).
-
-You can also automatically compile all files in a directory or
-directories using the ``compileall`` module.
-You can do it from the shell prompt by running ``compileall.py``
-and providing the path of a directory containing Python files to compile::
-
- python compileall.py .
-
-
-
-How do I find the current module name?
----------------------------------------------
-
-A module can find out its own module name by looking at the predefined
-global variable ``__name__``. If this has the value '__main__', the
-program is running as a script. Many modules that are usually used by
-importing them also provide a command-line interface or a self-test,
-and only execute this code after checking ``__name__``::
-
- def main():
- print 'Running test...'
- ...
-
- if __name__ == '__main__':
- main()
-
-
-How can I have modules that mutually import each other?
----------------------------------------------------------------
-Suppose you have the following modules:
-
-foo.py::
-
- from bar import bar_var
- foo_var=1
-
-bar.py::
-
- from foo import foo_var
- bar_var=2
-
-The problem is that the interpreter will perform the following steps:
-
-* main imports foo
-* Empty globals for foo are created
-* foo is compiled and starts executing
-* foo imports bar
-* Empty globals for bar are created
-* bar is compiled and starts executing
-* bar imports foo (which is a no-op since there already is a module named foo)
-* bar.foo_var = foo.foo_var
-
-The last step fails, because Python isn't done with interpreting ``foo``
-yet and the global symbol dictionary for ``foo`` is still empty.
-
-The same thing happens when you use ``import foo``, and then try to
-access ``foo.foo_var`` in global code.
-
-There are (at least) three possible workarounds for this problem.
-
-Guido van Rossum recommends avoiding all uses of ``from <module>
-import ...``, and placing all code inside functions. Initializations
-of global variables and class variables should use constants or
-built-in functions only. This means everything from an imported
-module is referenced as ``<module>.<name>``.
-
-Jim Roskind suggests performing steps in the following order in each
-module:
-
-* exports (globals, functions, and classes that don't need imported base classes)
-* ``import`` statements
-* active code (including globals that are initialized from imported values).
-
-van Rossum doesn't like this approach much because the imports
-appear in a strange place, but it does work.
-
-Matthias Urlichs recommends restructuring your code so that the
-recursive import is not necessary in the first place.
-
-These solutions are not mutually exclusive.
-
-
-__import__('x.y.z') returns <module 'x'>; how do I get z?
------------------------------------------------------------------------
-Try::
-
- __import__('x.y.z').y.z
-
-For more realistic situations, you may have to do something like ::
-
- m = __import__(s)
- for i in s.split(".")[1:]:
- m = getattr(m, i)
-
-
-
-When I edit an imported module and reimport it, the changes don't show up. Why does this happen?
---------------------------------------------------------------------------------------------------------------------------------------------
-
-For reasons of efficiency as well as consistency, Python only reads
-the module file on the first time a module is imported. If it didn't,
-in a program consisting of many modules where each one imports the
-same basic module, the basic module would be parsed and re-parsed many
-times. To force rereading of a changed module, do this::
-
- import modname
- reload(modname)
-
-Warning: this technique is not 100% fool-proof. In particular,
-modules containing statements like ::
-
- from modname import some_objects
-
-will continue to work with the old version of the imported objects.
-If the module contains class definitions, existing class instances
-will *not* be updated to use the new class definition. This can
-result in the following paradoxical behaviour::
-
- >>> import cls
- >>> c = cls.C() # Create an instance of C
- >>> reload(cls)
- <module 'cls' from 'cls.pyc'>
- >>> isinstance(c, cls.C) # isinstance is false?!?
- False
-
-The nature of the problem is made clear if you print out the class objects:
-
- >>> c.__class__
- <class cls.C at 0x7352a0>
- >>> cls.C
- <class cls.C at 0x4198d0>
-
diff --git a/faq/programming.html b/faq/programming.html
deleted file mode 100644
index c15502c..0000000
--- a/faq/programming.html
+++ /dev/null
@@ -1,2025 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
-<title>Programming FAQ</title>
-<meta name="date" content="2005-12-21" />
-<style type="text/css">
-
-/*
-:Author: David Goodger (goodger@python.org)
-:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
- border: 0 }
-
-table.borderless td, table.borderless th {
- /* Override padding for "table.docutils td" with "! important".
- The right padding separates the table cells. */
- padding: 0 0.5em 0 0 ! important }
-
-.first {
- /* Override more specific margin styles with "! important". */
- margin-top: 0 ! important }
-
-.last, .with-subtitle {
- margin-bottom: 0 ! important }
-
-.hidden {
- display: none }
-
-a.toc-backref {
- text-decoration: none ;
- color: black }
-
-blockquote.epigraph {
- margin: 2em 5em ; }
-
-dl.docutils dd {
- margin-bottom: 0.5em }
-
-object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
- overflow: hidden;
-}
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
- font-weight: bold }
-*/
-
-div.abstract {
- margin: 2em 5em }
-
-div.abstract p.topic-title {
- font-weight: bold ;
- text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
- margin: 2em ;
- border: medium outset ;
- padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title, .code .error {
- color: red ;
- font-weight: bold ;
- font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
- compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
- margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
- margin-top: 0.5em }
-*/
-
-div.dedication {
- margin: 2em 5em ;
- text-align: center ;
- font-style: italic }
-
-div.dedication p.topic-title {
- font-weight: bold ;
- font-style: normal }
-
-div.figure {
- margin-left: 2em ;
- margin-right: 2em }
-
-div.footer, div.header {
- clear: both;
- font-size: smaller }
-
-div.line-block {
- display: block ;
- margin-top: 1em ;
- margin-bottom: 1em }
-
-div.line-block div.line-block {
- margin-top: 0 ;
- margin-bottom: 0 ;
- margin-left: 1.5em }
-
-div.sidebar {
- margin: 0 0 0.5em 1em ;
- border: medium outset ;
- padding: 1em ;
- background-color: #ffffee ;
- width: 40% ;
- float: right ;
- clear: right }
-
-div.sidebar p.rubric {
- font-family: sans-serif ;
- font-size: medium }
-
-div.system-messages {
- margin: 5em }
-
-div.system-messages h1 {
- color: red }
-
-div.system-message {
- border: medium outset ;
- padding: 1em }
-
-div.system-message p.system-message-title {
- color: red ;
- font-weight: bold }
-
-div.topic {
- margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
- margin-top: 0.4em }
-
-h1.title {
- text-align: center }
-
-h2.subtitle {
- text-align: center }
-
-hr.docutils {
- width: 75% }
-
-img.align-left, .figure.align-left, object.align-left {
- clear: left ;
- float: left ;
- margin-right: 1em }
-
-img.align-right, .figure.align-right, object.align-right {
- clear: right ;
- float: right ;
- margin-left: 1em }
-
-img.align-center, .figure.align-center, object.align-center {
- display: block;
- margin-left: auto;
- margin-right: auto;
-}
-
-.align-left {
- text-align: left }
-
-.align-center {
- clear: both ;
- text-align: center }
-
-.align-right {
- text-align: right }
-
-/* reset inner alignment in figures */
-div.align-right {
- text-align: inherit }
-
-/* div.align-center * { */
-/* text-align: left } */
-
-ol.simple, ul.simple {
- margin-bottom: 1em }
-
-ol.arabic {
- list-style: decimal }
-
-ol.loweralpha {
- list-style: lower-alpha }
-
-ol.upperalpha {
- list-style: upper-alpha }
-
-ol.lowerroman {
- list-style: lower-roman }
-
-ol.upperroman {
- list-style: upper-roman }
-
-p.attribution {
- text-align: right ;
- margin-left: 50% }
-
-p.caption {
- font-style: italic }
-
-p.credits {
- font-style: italic ;
- font-size: smaller }
-
-p.label {
- white-space: nowrap }
-
-p.rubric {
- font-weight: bold ;
- font-size: larger ;
- color: maroon ;
- text-align: center }
-
-p.sidebar-title {
- font-family: sans-serif ;
- font-weight: bold ;
- font-size: larger }
-
-p.sidebar-subtitle {
- font-family: sans-serif ;
- font-weight: bold }
-
-p.topic-title {
- font-weight: bold }
-
-pre.address {
- margin-bottom: 0 ;
- margin-top: 0 ;
- font: inherit }
-
-pre.literal-block, pre.doctest-block, pre.math, pre.code {
- margin-left: 2em ;
- margin-right: 2em }
-
-pre.code .ln { color: grey; } /* line numbers */
-pre.code, code { background-color: #eeeeee }
-pre.code .comment, code .comment { color: #5C6576 }
-pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
-pre.code .literal.string, code .literal.string { color: #0C5404 }
-pre.code .name.builtin, code .name.builtin { color: #352B84 }
-pre.code .deleted, code .deleted { background-color: #DEB0A1}
-pre.code .inserted, code .inserted { background-color: #A3D289}
-
-span.classifier {
- font-family: sans-serif ;
- font-style: oblique }
-
-span.classifier-delimiter {
- font-family: sans-serif ;
- font-weight: bold }
-
-span.interpreted {
- font-family: sans-serif }
-
-span.option {
- white-space: nowrap }
-
-span.pre {
- white-space: pre }
-
-span.problematic {
- color: red }
-
-span.section-subtitle {
- /* font-size relative to parent (h1..h6 element) */
- font-size: 80% }
-
-table.citation {
- border-left: solid 1px gray;
- margin-left: 1px }
-
-table.docinfo {
- margin: 2em 4em }
-
-table.docutils {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
-
-table.footnote {
- border-left: solid 1px black;
- margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
- padding-left: 0.5em ;
- padding-right: 0.5em ;
- vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
- font-weight: bold ;
- text-align: left ;
- white-space: nowrap ;
- padding-left: 0 }
-
-/* "booktabs" style (no vertical lines) */
-table.docutils.booktabs {
- border: 0px;
- border-top: 2px solid;
- border-bottom: 2px solid;
- border-collapse: collapse;
-}
-table.docutils.booktabs * {
- border: 0px;
-}
-table.docutils.booktabs th {
- border-bottom: thin solid;
- text-align: left;
-}
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
- font-size: 100% }
-
-ul.auto-toc {
- list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="programming-faq">
-<h1 class="title">Programming FAQ</h1>
-<table class="docinfo" frame="void" rules="none">
-<col class="docinfo-name" />
-<col class="docinfo-content" />
-<tbody valign="top">
-<tr><th class="docinfo-name">Date:</th>
-<td>2005-12-21</td></tr>
-<tr><th class="docinfo-name">Version:</th>
-<td>8721</td></tr>
-<tr class="field"><th class="docinfo-name">Web site:</th><td class="field-body"><a class="reference external" href="http://www.python.org/">http://www.python.org/</a></td>
-</tr>
-</tbody>
-</table>
-<div class="contents topic" id="contents">
-<p class="topic-title first">Contents</p>
-<ul class="auto-toc simple">
-<li><a class="reference internal" href="#general-questions" id="id1">1 General Questions</a><ul class="auto-toc">
-<li><a class="reference internal" href="#is-there-a-source-code-level-debugger-with-breakpoints-single-stepping-etc" id="id2">1.1 Is there a source code level debugger with breakpoints, single-stepping, etc.?</a></li>
-<li><a class="reference internal" href="#is-there-a-tool-to-help-find-bugs-or-perform-static-analysis" id="id3">1.2 Is there a tool to help find bugs or perform static analysis?</a></li>
-<li><a class="reference internal" href="#how-can-i-create-a-stand-alone-binary-from-a-python-script" id="id4">1.3 How can I create a stand-alone binary from a Python script?</a></li>
-<li><a class="reference internal" href="#are-there-coding-standards-or-a-style-guide-for-python-programs" id="id5">1.4 Are there coding standards or a style guide for Python programs?</a></li>
-<li><a class="reference internal" href="#my-program-is-too-slow-how-do-i-speed-it-up" id="id6">1.5 My program is too slow. How do I speed it up?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#core-language" id="id7">2 Core Language</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-do-you-set-a-global-variable-in-a-function" id="id8">2.1 How do you set a global variable in a function?</a></li>
-<li><a class="reference internal" href="#what-are-the-rules-for-local-and-global-variables-in-python" id="id9">2.2 What are the rules for local and global variables in Python?</a></li>
-<li><a class="reference internal" href="#how-do-i-share-global-variables-across-modules" id="id10">2.3 How do I share global variables across modules?</a></li>
-<li><a class="reference internal" href="#what-are-the-best-practices-for-using-import-in-a-module" id="id11">2.4 What are the "best practices" for using import in a module?</a></li>
-<li><a class="reference internal" href="#how-can-i-pass-optional-or-keyword-parameters-from-one-function-to-another" id="id12">2.5 How can I pass optional or keyword parameters from one function to another?</a></li>
-<li><a class="reference internal" href="#how-do-i-write-a-function-with-output-parameters-call-by-reference" id="id13">2.6 How do I write a function with output parameters (call by reference)?</a></li>
-<li><a class="reference internal" href="#how-do-you-make-a-higher-order-function-in-python" id="id14">2.7 How do you make a higher order function in Python?</a></li>
-<li><a class="reference internal" href="#how-do-i-copy-an-object-in-python" id="id15">2.8 How do I copy an object in Python?</a></li>
-<li><a class="reference internal" href="#how-can-i-find-the-methods-or-attributes-of-an-object" id="id16">2.9 How can I find the methods or attributes of an object?</a></li>
-<li><a class="reference internal" href="#how-can-my-code-discover-the-name-of-an-object" id="id17">2.10 How can my code discover the name of an object?</a></li>
-<li><a class="reference internal" href="#is-there-an-equivalent-of-c-s-ternary-operator" id="id18">2.11 Is there an equivalent of C's "?:" ternary operator?</a></li>
-<li><a class="reference internal" href="#is-it-possible-to-write-obfuscated-one-liners-in-python" id="id19">2.12 Is it possible to write obfuscated one-liners in Python?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#numbers-and-strings" id="id20">3 Numbers and strings</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-do-i-specify-hexadecimal-and-octal-integers" id="id21">3.1 How do I specify hexadecimal and octal integers?</a></li>
-<li><a class="reference internal" href="#why-does-22-10-return-3" id="id22">3.2 Why does -22 / 10 return -3?</a></li>
-<li><a class="reference internal" href="#how-do-i-convert-a-string-to-a-number" id="id23">3.3 How do I convert a string to a number?</a></li>
-<li><a class="reference internal" href="#how-do-i-convert-a-number-to-a-string" id="id24">3.4 How do I convert a number to a string?</a></li>
-<li><a class="reference internal" href="#how-do-i-modify-a-string-in-place" id="id25">3.5 How do I modify a string in place?</a></li>
-<li><a class="reference internal" href="#how-do-i-use-strings-to-call-functions-methods" id="id26">3.6 How do I use strings to call functions/methods?</a></li>
-<li><a class="reference internal" href="#is-there-an-equivalent-to-perl-s-chomp-for-removing-trailing-newlines-from-strings" id="id27">3.7 Is there an equivalent to Perl's chomp() for removing trailing newlines from strings?</a></li>
-<li><a class="reference internal" href="#is-there-a-scanf-or-sscanf-equivalent" id="id28">3.8 Is there a scanf() or sscanf() equivalent?</a></li>
-<li><a class="reference internal" href="#what-does-unicodeerror-ascii-decoding-encoding-error-ordinal-not-in-range-128-mean" id="id29">3.9 What does 'UnicodeError: ASCII [decoding,encoding] error: ordinal not in range(128)' mean?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#sequences-tuples-lists" id="id30">4 Sequences (Tuples/Lists)</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-do-i-convert-between-tuples-and-lists" id="id31">4.1 How do I convert between tuples and lists?</a></li>
-<li><a class="reference internal" href="#what-s-a-negative-index" id="id32">4.2 What's a negative index?</a></li>
-<li><a class="reference internal" href="#how-do-i-iterate-over-a-sequence-in-reverse-order" id="id33">4.3 How do I iterate over a sequence in reverse order?</a></li>
-<li><a class="reference internal" href="#how-do-you-remove-duplicates-from-a-list" id="id34">4.4 How do you remove duplicates from a list?</a></li>
-<li><a class="reference internal" href="#how-do-you-make-an-array-in-python" id="id35">4.5 How do you make an array in Python?</a></li>
-<li><a class="reference internal" href="#how-do-i-create-a-multidimensional-list" id="id36">4.6 How do I create a multidimensional list?</a></li>
-<li><a class="reference internal" href="#how-do-i-apply-a-method-to-a-sequence-of-objects" id="id37">4.7 How do I apply a method to a sequence of objects?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#dictionaries" id="id38">5 Dictionaries</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-can-i-get-a-dictionary-to-display-its-keys-in-a-consistent-order" id="id39">5.1 How can I get a dictionary to display its keys in a consistent order?</a></li>
-<li><a class="reference internal" href="#i-want-to-do-a-complicated-sort-can-you-do-a-schwartzian-transform-in-python" id="id40">5.2 I want to do a complicated sort: can you do a Schwartzian Transform in Python?</a></li>
-<li><a class="reference internal" href="#how-can-i-sort-one-list-by-values-from-another-list" id="id41">5.3 How can I sort one list by values from another list?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#objects" id="id42">6 Objects</a><ul class="auto-toc">
-<li><a class="reference internal" href="#what-is-a-class" id="id43">6.1 What is a class?</a></li>
-<li><a class="reference internal" href="#what-is-a-method" id="id44">6.2 What is a method?</a></li>
-<li><a class="reference internal" href="#what-is-self" id="id45">6.3 What is self?</a></li>
-<li><a class="reference internal" href="#how-do-i-check-if-an-object-is-an-instance-of-a-given-class-or-of-a-subclass-of-it" id="id46">6.4 How do I check if an object is an instance of a given class or of a subclass of it?</a></li>
-<li><a class="reference internal" href="#what-is-delegation" id="id47">6.5 What is delegation?</a></li>
-<li><a class="reference internal" href="#how-do-i-call-a-method-defined-in-a-base-class-from-a-derived-class-that-overrides-it" id="id48">6.6 How do I call a method defined in a base class from a derived class that overrides it?</a></li>
-<li><a class="reference internal" href="#how-can-i-organize-my-code-to-make-it-easier-to-change-the-base-class" id="id49">6.7 How can I organize my code to make it easier to change the base class?</a></li>
-<li><a class="reference internal" href="#how-do-i-create-static-class-data-and-static-class-methods" id="id50">6.8 How do I create static class data and static class methods?</a></li>
-<li><a class="reference internal" href="#how-can-i-overload-constructors-or-methods-in-python" id="id51">6.9 How can I overload constructors (or methods) in Python?</a></li>
-<li><a class="reference internal" href="#i-try-to-use-spam-and-i-get-an-error-about-someclassname-spam" id="id52">6.10 I try to use __spam and I get an error about _SomeClassName__spam.</a></li>
-<li><a class="reference internal" href="#my-class-defines-del-but-it-is-not-called-when-i-delete-the-object" id="id53">6.11 My class defines __del__ but it is not called when I delete the object.</a></li>
-<li><a class="reference internal" href="#how-do-i-get-a-list-of-all-instances-of-a-given-class" id="id54">6.12 How do I get a list of all instances of a given class?</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#modules" id="id55">7 Modules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-do-i-create-a-pyc-file" id="id56">7.1 How do I create a .pyc file?</a></li>
-<li><a class="reference internal" href="#how-do-i-find-the-current-module-name" id="id57">7.2 How do I find the current module name?</a></li>
-<li><a class="reference internal" href="#how-can-i-have-modules-that-mutually-import-each-other" id="id58">7.3 How can I have modules that mutually import each other?</a></li>
-<li><a class="reference internal" href="#import-x-y-z-returns-module-x-how-do-i-get-z" id="id59">7.4 __import__('x.y.z') returns <module 'x'>; how do I get z?</a></li>
-<li><a class="reference internal" href="#when-i-edit-an-imported-module-and-reimport-it-the-changes-don-t-show-up-why-does-this-happen" id="id60">7.5 When I edit an imported module and reimport it, the changes don't show up. Why does this happen?</a></li>
-</ul>
-</li>
-</ul>
-</div>
-<div class="section" id="general-questions">
-<h1><a class="toc-backref" href="#id1">1 General Questions</a></h1>
-<div class="section" id="is-there-a-source-code-level-debugger-with-breakpoints-single-stepping-etc">
-<h2><a class="toc-backref" href="#id2">1.1 Is there a source code level debugger with breakpoints, single-stepping, etc.?</a></h2>
-<p>Yes.</p>
-<p>The pdb module is a simple but adequate console-mode debugger for
-Python. It is part of the standard Python library, and is <a class="reference external" href="http://docs.python.org/lib/module-pdb.html">documented
-in the Library Reference Manual</a>. You can
-also write your own debugger by using the code for pdb as an example.</p>
-<p>The IDLE interactive development environment, which is part of the
-standard Python distribution (normally available as Tools/scripts/idle),
-includes a graphical debugger. There is documentation for the IDLE
-debugger at <a class="reference external" href="http://www.python.org/idle/doc/idle2.html#Debugger">http://www.python.org/idle/doc/idle2.html#Debugger</a></p>
-<p>PythonWin is a Python IDE that includes a GUI debugger based on pdb.
-The Pythonwin debugger colors breakpoints and has quite a few cool
-features such as debugging non-Pythonwin programs. A reference can be
-found at <a class="reference external" href="http://www.python.org/windows/pythonwin/">http://www.python.org/windows/pythonwin/</a>. Recent versions of
-PythonWin are available as a part of the ActivePython distribution
-(see <a class="reference external" href="http://www.activestate.com/Products/ActivePython/index.html">http://www.activestate.com/Products/ActivePython/index.html</a>).</p>
-<p><a class="reference external" href="http://boa-constructor.sourceforge.net/">Boa Constructor</a> is an IDE
-and GUI builder that uses wxPython. It offers visual frame creation
-and manipulation, an object
-inspector, many views on the source like object browsers, inheritance
-hierarchies, doc string generated html documentation, an advanced
-debugger, integrated help, and Zope support.</p>
-<p><a class="reference external" href="http://www.die-offenbachs.de/detlev/eric3.html">Eric3</a> is an IDE
-built on PyQt and the Scintilla editing component.</p>
-<p>Pydb is a version of the standard Python debugger pdb, modified for
-use with DDD (Data Display Debugger), a popular graphical debugger
-front end. Pydb can be found at
-<a class="reference external" href="http://packages.debian.org/unstable/devel/pydb.html">http://packages.debian.org/unstable/devel/pydb.html</a>> and DDD can be
-found at <a class="reference external" href="http://www.gnu.org/software/ddd">http://www.gnu.org/software/ddd</a>.</p>
-<p>There are a number of commmercial Python IDEs that include graphical
-debuggers. They include:</p>
-<ul class="simple">
-<li>Wing IDE (<a class="reference external" href="http://wingide.com">http://wingide.com</a>)</li>
-<li>Komodo IDE (<a class="reference external" href="http://www.activestate.com/Products/Komodo">http://www.activestate.com/Products/Komodo</a>)</li>
-</ul>
-</div>
-<div class="section" id="is-there-a-tool-to-help-find-bugs-or-perform-static-analysis">
-<h2><a class="toc-backref" href="#id3">1.2 Is there a tool to help find bugs or perform static analysis?</a></h2>
-<p>Yes.</p>
-<p>PyChecker is a static analysis tool that finds bugs in Python source
-code and warns about code complexity and style. You can get PyChecker
-from <a class="reference external" href="http://pychecker.sf.net">http://pychecker.sf.net</a>.</p>
-<p><a class="reference external" href="http://www.logilab.org/projects/pylint">Pylint</a> is another tool
-that checks if a module satisfies a coding standard, and also makes it
-possible to write plug-ins to add a custom feature. In addition to
-the bug checking that PyChecker performs, Pylint offers some
-additional features such as checking line length, whether variable
-names are well-formed according to your coding standard, whether
-declared interfaces are fully implemented, and more.
-<a class="reference external" href="http://www.logilab.org/projects/pylint/documentation">http://www.logilab.org/projects/pylint/documentation</a> provides a full
-list of Pylint's features.</p>
-</div>
-<div class="section" id="how-can-i-create-a-stand-alone-binary-from-a-python-script">
-<h2><a class="toc-backref" href="#id4">1.3 How can I create a stand-alone binary from a Python script?</a></h2>
-<p>You don't need the ability to compile Python to C code if all you
-want is a stand-alone program that users can download and run without
-having to install the Python distribution first. There are a number
-of tools that determine the set of modules required by a program and
-bind these modules together with a Python binary to produce a single
-executable.</p>
-<p>One is to use the freeze tool, which is included in the Python
-source tree as <tt class="docutils literal">Tools/freeze</tt>. It converts Python byte
-code to C arrays; a C compiler you can embed all
-your modules into a new program, which is then linked
-with the standard Python modules.</p>
-<p>It works by scanning your source recursively for import statements (in
-both forms) and looking for the modules in the standard Python path as
-well as in the source directory (for built-in modules). It then turns
-the bytecode for modules written in Python into C code (array
-initializers that can be turned into code objects using the marshal
-module) and creates a custom-made config file that only contains those
-built-in modules which are actually used in the program. It then
-compiles the generated C code and links it with the rest of the Python
-interpreter to form a self-contained binary which acts exactly like
-your script.</p>
-<p>Obviously, freeze requires a C compiler. There are several other
-utilities which don't. The first is Gordon McMillan's installer at</p>
-<blockquote>
-<a class="reference external" href="http://www.mcmillan-inc.com/install1.html">http://www.mcmillan-inc.com/install1.html</a></blockquote>
-<p>which works on Windows, Linux and at least some forms of Unix.</p>
-<p>Another is Thomas Heller's py2exe (Windows only) at</p>
-<blockquote>
-<a class="reference external" href="http://starship.python.net/crew/theller/py2exe">http://starship.python.net/crew/theller/py2exe</a></blockquote>
-<p>A third is Christian Tismer's <a class="reference external" href="http://starship.python.net/crew/pirx">SQFREEZE</a> which appends the byte code
-to a specially-prepared Python interpreter that can find the byte
-code in the executable. It's possible that a similar approach will
-be added to Python 2.4, due out some time in 2004.</p>
-<p>Other tools include Fredrik Lundh's <a class="reference external" href="http://www.pythonware.com/products/python/squeeze">Squeeze</a> and Anthony
-Tuininga's <a class="reference external" href="http://starship.python.net/crew/atuining/cx_Freeze/index.html">cx_Freeze</a>.</p>
-</div>
-<div class="section" id="are-there-coding-standards-or-a-style-guide-for-python-programs">
-<h2><a class="toc-backref" href="#id5">1.4 Are there coding standards or a style guide for Python programs?</a></h2>
-<p>Yes. The coding style required for standard library modules
-is documented as <a class="reference external" href="../../peps/pep-0008.html">PEP 8</a>.</p>
-</div>
-<div class="section" id="my-program-is-too-slow-how-do-i-speed-it-up">
-<h2><a class="toc-backref" href="#id6">1.5 My program is too slow. How do I speed it up?</a></h2>
-<p>That's a tough one, in general. There are many tricks to speed up
-Python code; consider rewriting parts in C as a last resort.</p>
-<p>In some cases it's possible to automatically translate Python to C or
-x86 assembly language, meaning that you don't have to modify your code
-to gain increased speed.</p>
-<p><a class="reference external" href="http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/">Pyrex</a> can
-compile a slightly modified version of Python code into a C extension,
-and can be used on many different platforms.</p>
-<p><a class="reference external" href="http://psyco.sourceforge.net">Psyco</a> is a just-in-time compiler
-that translates Python code into x86 assembly language. If you can
-use it, Psyco can provide dramatic speedups for critical functions.</p>
-<p>The rest of this answer will discuss various tricks for squeezing a
-bit more speed out of Python code. <em>Never</em> apply any optimization
-tricks unless you know you need them, after profiling has indicated
-that a particular function is the heavily executed hot spot in the
-code. Optimizations almost always make the code less clear, and you
-shouldn't pay the costs of reduced clarity (increased development
-time, greater likelihood of bugs) unless the resulting performance
-benefit is worth it.</p>
-<p>There is a page on the wiki devoted to <a class="reference external" href="http://wiki.python.org/moin/PythonSpeed/PerformanceTips">performance tips</a>.</p>
-<p>Guido van Rossum has written up an anecdote related to optimization at
-<a class="reference external" href="http://www.python.org/doc/essays/list2str.html">http://www.python.org/doc/essays/list2str.html</a>.</p>
-<p>One thing to notice is that function and (especially) method calls are
-rather expensive; if you have designed a purely OO interface with lots
-of tiny functions that don't do much more than get or set an instance
-variable or call another method, you might consider using a more
-direct way such as directly accessing instance variables. Also see the
-standard module "profile" (<a class="reference external" href="http://docs.python.org/lib/module-profile.html">described in the Library Reference manual</a>) which
-makes it possible to find out where your program is spending most of
-its time (if you have some patience -- the profiling itself can slow
-your program down by an order of magnitude).</p>
-<p>Remember that many standard optimization heuristics you
-may know from other programming experience may well apply
-to Python. For example it may be faster to send output to output
-devices using larger writes rather than smaller ones in order to
-reduce the overhead of kernel system calls. Thus CGI scripts
-that write all output in "one shot" may be faster than
-those that write lots of small pieces of output.</p>
-<p>Also, be sure to use Python's core features where appropriate.
-For example, slicing allows programs to chop up
-lists and other sequence objects in a single tick of the interpreter's
-mainloop using highly optimized C implementations. Thus to
-get the same effect as:</p>
-<pre class="literal-block">
-L2 = []
-for i in range[3]:
- L2.append(L1[i])
-</pre>
-<p>it is much shorter and far faster to use</p>
-<pre class="literal-block">
-L2 = list(L1[:3]) # "list" is redundant if L1 is a list.
-</pre>
-<p>Note that the functionally-oriented builtins such as
-<tt class="docutils literal">map()</tt>, <tt class="docutils literal">zip()</tt>, and friends can be a convenient
-accelerator for loops that perform a single task. For example to pair the elements of two
-lists together:</p>
-<pre class="literal-block">
->>> zip([1,2,3], [4,5,6])
-[(1, 4), (2, 5), (3, 6)]
-</pre>
-<p>or to compute a number of sines:</p>
-<pre class="literal-block">
->>> map( math.sin, (1,2,3,4))
-[0.841470984808, 0.909297426826, 0.14112000806, -0.756802495308]
-</pre>
-<p>The operation completes very quickly in such cases.</p>
-<p>Other examples include the <tt class="docutils literal">join()</tt> and <tt class="docutils literal">split()</tt>
-methods of string objects. For example if s1..s7 are large (10K+) strings then
-<tt class="docutils literal"><span class="pre">"".join([s1,s2,s3,s4,s5,s6,s7])`</span> may be far faster than
-the more obvious ``s1+s2+s3+s4+s5+s6+s7</tt>, since the "summation"
-will compute many subexpressions, whereas <tt class="docutils literal">join()</tt> does all the
-copying in one pass. For manipulating strings, use
-the <tt class="docutils literal">replace()</tt> method on string objects. Use
-regular expressions only when you're not dealing with constant string patterns.
-Consider using the string formatting operations
-<tt class="docutils literal">string % tuple</tt> and <tt class="docutils literal">string % dictionary</tt>.</p>
-<p>Be sure to use the <tt class="docutils literal">list.sort()</tt> builtin method to do sorting, and see
-the <a class="reference external" href="http://wiki.python.org/moin/HowTo/Sorting">sorting mini-HOWTO</a> for examples of moderately advanced usage.
-<tt class="docutils literal">list.sort()</tt> beats other techniques for sorting in all but the most
-extreme circumstances.</p>
-<p>Another common trick is to "push loops into functions or methods."
-For example suppose you have a program that runs slowly and you
-use the profiler to determine that a Python function <tt class="docutils literal">ff()</tt>
-is being called lots of times. If you notice that <tt class="docutils literal">ff ()</tt>:</p>
-<pre class="literal-block">
-def ff(x):
- ...do something with x computing result...
- return result
-</pre>
-<p>tends to be called in loops like:</p>
-<pre class="literal-block">
-list = map(ff, oldlist)
-</pre>
-<p>or:</p>
-<pre class="literal-block">
-for x in sequence:
- value = ff(x)
- ...do something with value...
-</pre>
-<p>then you can often eliminate function call overhead by rewriting
-<tt class="docutils literal">ff()</tt> to:</p>
-<pre class="literal-block">
-def ffseq(seq):
- resultseq = []
- for x in seq:
- ...do something with x computing result...
- resultseq.append(result)
- return resultseq
-</pre>
-<p>and rewrite the two examples to <tt class="docutils literal">list = ffseq(oldlist)</tt> and to:</p>
-<pre class="literal-block">
-for value in ffseq(sequence):
- ...do something with value...
-</pre>
-<p>Single calls to ff(x) translate to ffseq([x])[0] with little
-penalty. Of course this technique is not always appropriate
-and there are other variants which you can figure out.</p>
-<p>You can gain some performance by explicitly storing the results of
-a function or method lookup into a local variable. A loop like:</p>
-<pre class="literal-block">
-for key in token:
- dict[key] = dict.get(key, 0) + 1
-</pre>
-<p>resolves dict.get every iteration. If the method isn't going to
-change, a slightly faster implementation is:</p>
-<pre class="literal-block">
-dict_get = dict.get # look up the method once
-for key in token:
- dict[key] = dict_get(key, 0) + 1
-</pre>
-<p>Default arguments can be used to determine values once, at
-compile time instead of at run time. This can only be done for
-functions or objects which will not be changed during program
-execution, such as replacing</p>
-<pre class="literal-block">
-def degree_sin(deg):
- return math.sin(deg * math.pi / 180.0)
-</pre>
-<p>with</p>
-<pre class="literal-block">
-def degree_sin(deg, factor = math.pi/180.0, sin = math.sin):
- return sin(deg * factor)
-</pre>
-<p>Because this trick uses default arguments for terms which should
-not be changed, it should only be used when you are not concerned
-with presenting a possibly confusing API to your users.</p>
-</div>
-</div>
-<div class="section" id="core-language">
-<h1><a class="toc-backref" href="#id7">2 Core Language</a></h1>
-<div class="section" id="how-do-you-set-a-global-variable-in-a-function">
-<h2><a class="toc-backref" href="#id8">2.1 How do you set a global variable in a function?</a></h2>
-<p>Did you do something like this?</p>
-<pre class="literal-block">
-x = 1 # make a global
-
-def f():
- print x # try to print the global
- ...
- for j in range(100):
- if q>3:
- x=4
-</pre>
-<p>Any variable assigned in a function is local to that function.
-unless it is specifically declared global. Since a value is bound
-to <tt class="docutils literal">x</tt> as the last statement of the function body, the compiler
-assumes that <tt class="docutils literal">x</tt> is local. Consequently the <tt class="docutils literal">print x</tt>
-attempts to print an uninitialized local variable and will
-trigger a <tt class="docutils literal">NameError</tt>.</p>
-<p>The solution is to insert an explicit global declaration at the start
-of the function:</p>
-<pre class="literal-block">
-def f():
- global x
- print x # try to print the global
- ...
- for j in range(100):
- if q>3:
- x=4
-</pre>
-<p>In this case, all references to <tt class="docutils literal">x</tt> are interpreted as references
-to the <tt class="docutils literal">x</tt> from the module namespace.</p>
-</div>
-<div class="section" id="what-are-the-rules-for-local-and-global-variables-in-python">
-<h2><a class="toc-backref" href="#id9">2.2 What are the rules for local and global variables in Python?</a></h2>
-<p>In Python, variables that are only referenced inside a function are
-implicitly global. If a variable is assigned a new value anywhere
-within the function's body, it's assumed to be a local. If a variable
-is ever assigned a new value inside the function, the variable is
-implicitly local, and you need to explicitly declare it as 'global'.</p>
-<p>Though a bit surprising at first, a moment's consideration explains
-this. On one hand, requiring <tt class="docutils literal">global</tt> for assigned variables provides
-a bar against unintended side-effects. On the other hand, if <tt class="docutils literal">global</tt>
-was required for all global references, you'd be using <tt class="docutils literal">global</tt> all the
-time. You'd have to declare as global every reference to a
-builtin function or to a component of an imported module. This
-clutter would defeat the usefulness of the <tt class="docutils literal">global</tt> declaration for
-identifying side-effects.</p>
-</div>
-<div class="section" id="how-do-i-share-global-variables-across-modules">
-<h2><a class="toc-backref" href="#id10">2.3 How do I share global variables across modules?</a></h2>
-<p>The canonical way to share information across modules within a single
-program is to create a special module (often called config or cfg).
-Just import the config module in all modules of your application; the
-module then becomes available as a global name. Because there is only
-one instance of each module, any changes made to the module object get
-reflected everywhere. For example:</p>
-<p>config.py:</p>
-<pre class="literal-block">
-x = 0 # Default value of the 'x' configuration setting
-</pre>
-<p>mod.py:</p>
-<pre class="literal-block">
-import config
-config.x = 1
-</pre>
-<p>main.py:</p>
-<pre class="literal-block">
-import config
-import mod
-print config.x
-</pre>
-<p>Note that using a module is also the basis for implementing the
-Singleton design pattern, for the same reason.</p>
-</div>
-<div class="section" id="what-are-the-best-practices-for-using-import-in-a-module">
-<h2><a class="toc-backref" href="#id11">2.4 What are the "best practices" for using import in a module?</a></h2>
-<p>In general, don't use <tt class="docutils literal">from modulename import *</tt>.
-Doing so clutters the importer's namespace. Some people avoid this idiom
-even with the few modules that were designed to be imported in this
-manner. Modules designed in this manner include <tt class="docutils literal">Tkinter</tt>,
-and <tt class="docutils literal">threading</tt>.</p>
-<p>Import modules at the top of a file. Doing so makes it clear what
-other modules your code requires and avoids questions of whether the
-module name is in scope. Using one import per line makes it easy to
-add and delete module imports, but using multiple imports per line
-uses less screen space.</p>
-<p>It's good practice if you import modules in the following order:</p>
-<ol class="arabic simple">
-<li>standard libary modules -- e.g. <tt class="docutils literal">sys</tt>, <tt class="docutils literal">os</tt>, <tt class="docutils literal">getopt</tt>, <tt class="docutils literal">re</tt>)</li>
-<li>third-party library modules (anything installed in Python's
-site-packages directory) -- e.g. mx.DateTime, ZODB, PIL.Image, etc.</li>
-<li>locally-developed modules</li>
-</ol>
-<p>Never use relative package imports. If you're writing code that's
-in the <tt class="docutils literal">package.sub.m1</tt> module and want to import <tt class="docutils literal">package.sub.m2</tt>,
-do not just write <tt class="docutils literal">import m2</tt>, even though it's legal.
-Write <tt class="docutils literal">from package.sub import m2</tt> instead. Relative imports can lead to a
-module being initialized twice, leading to confusing bugs.</p>
-<p>It is sometimes necessary to move imports to a function or class to
-avoid problems with circular imports. Gordon McMillan says:</p>
-<blockquote>
-Circular imports are fine where both modules use the "import <module>"
-form of import. They fail when the 2nd module wants to grab a name
-out of the first ("from module import name") and the import is at
-the top level. That's because names in the 1st are not yet available,
-because the first module is busy importing the 2nd.</blockquote>
-<p>In this case, if the second module is only used in one function, then the
-import can easily be moved into that function. By the time the import
-is called, the first module will have finished initializing, and the
-second module can do its import.</p>
-<p>It may also be necessary to move imports out of the top level of code
-if some of the modules are platform-specific. In that case, it may
-not even be possible to import all of the modules at the top of the
-file. In this case, importing the correct modules in the
-corresponding platform-specific code is a good option.</p>
-<p>Only move imports into a local scope, such as inside a function
-definition, if it's necessary to solve a problem such as avoiding a
-circular import or are trying to reduce the initialization time of a
-module. This technique is especially helpful if many of the imports
-are unnecessary depending on how the program executes. You may also
-want to move imports into a function if the modules are only ever used
-in that function. Note that loading a module the first time may be
-expensive because of the one time initialization of the module, but
-loading a module multiple times is virtually free, costing only a couple of
-dictionary lookups. Even if the module name has gone out of scope,
-the module is probably available in sys.modules.</p>
-<p>If only instances of a specific class use a module, then it is
-reasonable to import the module in the class's <tt class="docutils literal">__init__</tt> method and
-then assign the module to an instance variable so that the module is
-always available (via that instance variable) during the life of the
-object. Note that to delay an import until the class is instantiated,
-the import must be inside a method. Putting the import inside the
-class but outside of any method still causes the import to occur when
-the module is initialized.</p>
-</div>
-<div class="section" id="how-can-i-pass-optional-or-keyword-parameters-from-one-function-to-another">
-<h2><a class="toc-backref" href="#id12">2.5 How can I pass optional or keyword parameters from one function to another?</a></h2>
-<p>Collect the arguments using the <tt class="docutils literal">*</tt> and <tt class="docutils literal">**</tt> specifiers in the function's
-parameter list; this gives you the positional arguments as a tuple
-and the keyword arguments as a dictionary. You can
-then pass these arguments when calling another function by using
-<tt class="docutils literal">*</tt> and <tt class="docutils literal">**</tt>:</p>
-<pre class="literal-block">
-def f(x, *tup, **kwargs):
- ...
- kwargs['width']='14.3c'
- ...
- g(x, *tup, **kwargs)
-</pre>
-<p>In the unlikely case that you care about Python
-versions older than 2.0, use 'apply':</p>
-<pre class="literal-block">
-def f(x, *tup, **kwargs):
- ...
- kwargs['width']='14.3c'
- ...
- apply(g, (x,)+tup, kwargs)
-</pre>
-</div>
-<div class="section" id="how-do-i-write-a-function-with-output-parameters-call-by-reference">
-<h2><a class="toc-backref" href="#id13">2.6 How do I write a function with output parameters (call by reference)?</a></h2>
-<p>Remember that arguments are passed by assignment in Python. Since
-assignment just creates references to objects, there's no alias
-between an argument name in the caller and callee, and so no
-call-by-reference per se. You can achieve the desired effect in a
-number of ways.</p>
-<ol class="arabic">
-<li><p class="first">By returning a tuple of the results:</p>
-<pre class="literal-block">
-def func2(a, b):
- a = 'new-value' # a and b are local names
- b = b + 1 # assigned to new objects
- return a, b # return new values
-
-x, y = 'old-value', 99
-x, y = func2(x, y)
-print x, y # output: new-value 100
-</pre>
-<p>This is almost always the clearest solution.</p>
-</li>
-<li><p class="first">By using global variables. This isn't thread-safe, and is not
-recommended.</p>
-</li>
-<li><p class="first">By passing a mutable (changeable in-place) object:</p>
-<pre class="literal-block">
-def func1(a):
- a[0] = 'new-value' # 'a' references a mutable list
- a[1] = a[1] + 1 # changes a shared object
-
-args = ['old-value', 99]
-func1(args)
-print args[0], args[1] # output: new-value 100
-</pre>
-</li>
-<li><p class="first">By passing in a dictionary that gets mutated:</p>
-<pre class="literal-block">
-def func3(args):
- args['a'] = 'new-value' # args is a mutable dictionary
- args['b'] = args['b'] + 1 # change it in-place
-
-args = {'a':' old-value', 'b': 99}
-func3(args)
-print args['a'], args['b']
-</pre>
-</li>
-<li><p class="first">Or bundle up values in a class instance:</p>
-<pre class="literal-block">
-class callByRef:
- def __init__(self, **args):
- for (key, value) in args.items():
- setattr(self, key, value)
-
-def func4(args):
- args.a = 'new-value' # args is a mutable callByRef
- args.b = args.b + 1 # change object in-place
-
-args = callByRef(a='old-value', b=99)
-func4(args)
-print args.a, args.b
-</pre>
-<p>There's almost never a good reason to get this complicated.</p>
-</li>
-</ol>
-<p>Your best choice is to return a tuple containing the multiple results.</p>
-</div>
-<div class="section" id="how-do-you-make-a-higher-order-function-in-python">
-<h2><a class="toc-backref" href="#id14">2.7 How do you make a higher order function in Python?</a></h2>
-<p>You have two choices: you can use nested scopes
-or you can use callable objects. For example, suppose you wanted to
-define <tt class="docutils literal">linear(a,b)</tt> which returns a function <tt class="docutils literal">f(x)</tt> that computes the
-value <tt class="docutils literal">a*x+b</tt>. Using nested scopes:</p>
-<pre class="literal-block">
-def linear(a,b):
- def result(x):
- return a*x + b
- return result
-</pre>
-<p>Or using a callable object:</p>
-<pre class="literal-block">
-class linear:
- def __init__(self, a, b):
- self.a, self.b = a,b
- def __call__(self, x):
- return self.a * x + self.b
-</pre>
-<p>In both cases:</p>
-<pre class="literal-block">
-taxes = linear(0.3,2)
-</pre>
-<p>gives a callable object where taxes(10e6) == 0.3 * 10e6 + 2.</p>
-<p>The callable object approach has the disadvantage that it is a bit
-slower and results in slightly longer code. However, note that a
-collection of callables can share their signature via inheritance:</p>
-<pre class="literal-block">
-class exponential(linear):
- # __init__ inherited
- def __call__(self, x):
- return self.a * (x ** self.b)
-</pre>
-<p>Object can encapsulate state for several methods:</p>
-<pre class="literal-block">
-class counter:
- value = 0
- def set(self, x): self.value = x
- def up(self): self.value=self.value+1
- def down(self): self.value=self.value-1
-
-count = counter()
-inc, dec, reset = count.up, count.down, count.set
-</pre>
-<p>Here <tt class="docutils literal">inc()</tt>, <tt class="docutils literal">dec()</tt> and <tt class="docutils literal">reset()</tt> act like functions which share the
-same counting variable.</p>
-</div>
-<div class="section" id="how-do-i-copy-an-object-in-python">
-<h2><a class="toc-backref" href="#id15">2.8 How do I copy an object in Python?</a></h2>
-<p>In general, try copy.copy() or copy.deepcopy() for the general case. Not all
-objects can be copied, but most can.</p>
-<p>Some objects can be copied more easily.
-Dictionaries have a <tt class="docutils literal">copy()</tt> method:</p>
-<pre class="literal-block">
-newdict = olddict.copy()
-</pre>
-<p>Sequences can be copied by slicing:</p>
-<pre class="literal-block">
-new_l = l[:]
-</pre>
-</div>
-<div class="section" id="how-can-i-find-the-methods-or-attributes-of-an-object">
-<h2><a class="toc-backref" href="#id16">2.9 How can I find the methods or attributes of an object?</a></h2>
-<p>For an instance x of a user-defined class, <tt class="docutils literal">dir(x)</tt> returns an
-alphabetized list of the names containing the instance attributes and
-methods and attributes defined by its class.</p>
-</div>
-<div class="section" id="how-can-my-code-discover-the-name-of-an-object">
-<h2><a class="toc-backref" href="#id17">2.10 How can my code discover the name of an object?</a></h2>
-<p>Generally speaking, it can't, because objects don't really have
-names. Essentially, assignment always binds a name to a value; The
-same is true of <tt class="docutils literal">def</tt> and <tt class="docutils literal">class</tt> statements, but in that case the
-value is a callable. Consider the following code:</p>
-<pre class="literal-block">
-class A:
- pass
-
-B = A
-
-a = B()
-b = a
-print b
-<__main__.A instance at 016D07CC>
-print a
-<__main__.A instance at 016D07CC>
-</pre>
-<p>Arguably the class has a name: even though it is bound to two names
-and invoked through the name B the created instance is still reported
-as an instance of class A. However, it is impossible to say whether
-the instance's name is a or b, since both names are bound to the same
-value.</p>
-<p>Generally speaking it should not be necessary for your code to "know
-the names" of particular values. Unless you are deliberately writing
-introspective programs, this is usually an indication that a change of
-approach might be beneficial.</p>
-<p>In comp.lang.python, Fredrik Lundh once gave an excellent analogy in
-answer to this question:</p>
-<blockquote>
-<p>The same way as you get the name of that cat you found on your
-porch: the cat (object) itself cannot tell you its name, and it
-doesn't really care -- so the only way to find out what it's called
-is to ask all your neighbours (namespaces) if it's their cat
-(object)...</p>
-<p>....and don't be surprised if you'll find that it's known by many
-names, or no name at all!</p>
-</blockquote>
-</div>
-<div class="section" id="is-there-an-equivalent-of-c-s-ternary-operator">
-<h2><a class="toc-backref" href="#id18">2.11 Is there an equivalent of C's "?:" ternary operator?</a></h2>
-<p>No. In many cases you can mimic a?b:c with "a and b or
-c", but there's a flaw: if b is zero (or empty, or None -- anything
-that tests false) then c will be selected instead. In many cases you
-can prove by looking at the code that this can't happen (e.g. because
-b is a constant or has a type that can never be false), but in general
-this can be a problem.</p>
-<p>Tim Peters (who wishes it was Steve Majewski) suggested the following
-solution: (a and [b] or [c])[0]. Because [b] is a singleton list it
-is never false, so the wrong path is never taken; then applying [0] to
-the whole thing gets the b or c that you really wanted. Ugly, but it
-gets you there in the rare cases where it is really inconvenient to
-rewrite your code using 'if'.</p>
-<p>The best course is usually to write a simple <tt class="docutils literal"><span class="pre">if...else</span></tt> statement.
-Another solution is to implement the "?:" operator as a function:</p>
-<pre class="literal-block">
-def q(cond,on_true,on_false):
- if cond:
- if not isfunction(on_true): return on_true
- else: return apply(on_true)
- else:
- if not isfunction(on_false): return on_false
- else: return apply(on_false)
-</pre>
-<p>In most cases you'll pass b and c directly: <tt class="docutils literal">q(a,b,c)</tt>. To avoid
-evaluating b or c when they shouldn't be, encapsulate them within a
-lambda function, e.g.: <tt class="docutils literal">q(a,lambda: b, lambda: c)</tt>.</p>
-<p>It has been asked <em>why</em> Python has no if-then-else expression.
-There are several answers: many languages do
-just fine without one; it can easily lead to less readable code;
-no sufficiently "Pythonic" syntax has been discovered; a search
-of the standard library found remarkably few places where using an
-if-then-else expression would make the code more understandable.</p>
-<p>In 2002, <a class="reference external" href="../../peps/pep-0308.html">PEP 308</a> was
-written proposing several possible syntaxes and the community was
-asked to vote on the issue. The vote was inconclusive. Most people
-liked one of the syntaxes, but also hated other syntaxes; many votes
-implied that people preferred no ternary operator
-rather than having a syntax they hated.</p>
-</div>
-<div class="section" id="is-it-possible-to-write-obfuscated-one-liners-in-python">
-<h2><a class="toc-backref" href="#id19">2.12 Is it possible to write obfuscated one-liners in Python?</a></h2>
-<p>Yes. Usually this is done by nesting <cite>lambda</cite> within <cite>lambda</cite>.
-See the following three examples, due to Ulf Bartelt:</p>
-<pre class="literal-block">
-# Primes < 1000
-print filter(None,map(lambda y:y*reduce(lambda x,y:x*y!=0,
-map(lambda x,y=y:y%x,range(2,int(pow(y,0.5)+1))),1),range(2,1000)))
-
-# First 10 Fibonacci numbers
-print map(lambda x,f=lambda x,f:(x<=1) or (f(x-1,f)+f(x-2,f)): f(x,f),
-range(10))
-
-# Mandelbrot set
-print (lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+y,map(lambda y,
-Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,Sy=Sy,L=lambda yc,Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,i=IM,
-Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro,
-i=i,Sx=Sx,F=lambda xc,yc,x,y,k,f=lambda xc,yc,x,y,k,f:(k<=0)or (x*x+y*y
->=4.0) or 1+f(xc,yc,x*x-y*y+xc,2.0*x*y+yc,k-1,f):f(xc,yc,x,y,k,f):chr(
-64+F(Ru+x*(Ro-Ru)/Sx,yc,0,0,i)),range(Sx))):L(Iu+y*(Io-Iu)/Sy),range(Sy
-))))(-2.1, 0.7, -1.2, 1.2, 30, 80, 24)
-# \___ ___ \___ ___ | | |__ lines on screen
-# V V | |______ columns on screen
-# | | |__________ maximum of "iterations"
-# | |_________________ range on y axis
-# |____________________________ range on x axis
-</pre>
-<p>Don't try this at home, kids!</p>
-</div>
-</div>
-<div class="section" id="numbers-and-strings">
-<h1><a class="toc-backref" href="#id20">3 Numbers and strings</a></h1>
-<div class="section" id="how-do-i-specify-hexadecimal-and-octal-integers">
-<h2><a class="toc-backref" href="#id21">3.1 How do I specify hexadecimal and octal integers?</a></h2>
-<p>To specify an octal digit, precede the octal value with a zero. For
-example, to set the variable "a" to the octal value "10" (8 in
-decimal), type:</p>
-<pre class="literal-block">
->>> a = 010
->>> a
-8
-</pre>
-<p>Hexadecimal is just as easy. Simply precede the hexadecimal number with a
-zero, and then a lower or uppercase "x". Hexadecimal digits can be specified
-in lower or uppercase. For example, in the Python interpreter:</p>
-<pre class="literal-block">
->>> a = 0xa5
->>> a
-165
->>> b = 0XB2
->>> b
-178
-</pre>
-</div>
-<div class="section" id="why-does-22-10-return-3">
-<h2><a class="toc-backref" href="#id22">3.2 Why does -22 / 10 return -3?</a></h2>
-<p>It's primarily driven by the desire that <tt class="docutils literal">i%j</tt> have the same sign as
-<tt class="docutils literal">j</tt>. If you want that, and also want:</p>
-<pre class="literal-block">
-i == (i/j)*j + (i%j)
-</pre>
-<p>then integer division has to return the floor. C also requres that identity
-to hold, and then compilers that truncate <tt class="docutils literal">i/j</tt> need to make <tt class="docutils literal">i%j</tt> have
-the same sign as <tt class="docutils literal">i</tt>.</p>
-<p>There are few real use cases for <tt class="docutils literal">i%j</tt> when <tt class="docutils literal">j</tt> is negative. When <tt class="docutils literal">j</tt>
-is positive, there are many, and in virtually all of them it's more useful
-for <tt class="docutils literal">i%j</tt> to be <tt class="docutils literal">>= 0</tt>. If the clock says 10 now, what did it say 200
-hours ago? <tt class="docutils literal"><span class="pre">-190</span> % 12 == 2</tt> is useful; <tt class="docutils literal"><span class="pre">-190</span> % 12 == <span class="pre">-10</span></tt> is a bug
-waiting to bite.</p>
-</div>
-<div class="section" id="how-do-i-convert-a-string-to-a-number">
-<h2><a class="toc-backref" href="#id23">3.3 How do I convert a string to a number?</a></h2>
-<p>For integers, use the built-in <tt class="docutils literal">int()</tt> type constructor,
-e.g. int('144') == 144. Similarly, <tt class="docutils literal">float()</tt> converts to
-floating-point, e.g. <tt class="docutils literal"><span class="pre">float('144')</span> == 144.0</tt>.</p>
-<p>By default, these interpret the number as decimal, so that
-<tt class="docutils literal"><span class="pre">int('0144')</span> == 144</tt> and <tt class="docutils literal"><span class="pre">int('0x144')</span></tt> raises
-<tt class="docutils literal">ValueError</tt>. <tt class="docutils literal">int(string, base)</tt> takes the base to convert from
-as a second optional argument, so <tt class="docutils literal"><span class="pre">int('0x144',</span> 16) == 324</tt>. If the
-base is specified as 0, the number is interpreted using Python's
-rules: a leading '0' indicates octal, and '0x' indicates a hex number.</p>
-<p>Do not use the built-in function <tt class="docutils literal">eval()</tt> if all you need is to
-convert strings to numbers. <tt class="docutils literal">eval()</tt> will be significantly slower
-and it presents a security risk: someone could pass you a Python
-expression that might have unwanted side effects. For example,
-someone could pass <tt class="docutils literal"><span class="pre">__import__('os').system("rm</span> <span class="pre">-rf</span> $HOME")</tt> which
-would erase your home directory.</p>
-<p><tt class="docutils literal">eval()</tt> also has the effect of interpreting numbers as Python
-expressions, so that e.g. eval('09') gives a syntax error because Python
-regards numbers starting with '0' as octal (base 8).</p>
-</div>
-<div class="section" id="how-do-i-convert-a-number-to-a-string">
-<h2><a class="toc-backref" href="#id24">3.4 How do I convert a number to a string?</a></h2>
-<p>To convert, e.g., the number 144 to the string '144', use the built-in
-function <tt class="docutils literal">str()</tt>. If you want a hexadecimal or octal
-representation, use the built-in functions <tt class="docutils literal">hex()</tt> or <tt class="docutils literal">oct()</tt>.
-For fancy formatting, use <a class="reference external" href="../../doc/lib/typesseq-strings.html">the % operator</a> on strings, e.g. <tt class="docutils literal">"%04d" % 144</tt>
-yields '0144' and <tt class="docutils literal"><span class="pre">"%.3f"</span> % (1/3.0)</tt> yields '0.333'. See the library
-reference manual for details.</p>
-</div>
-<div class="section" id="how-do-i-modify-a-string-in-place">
-<h2><a class="toc-backref" href="#id25">3.5 How do I modify a string in place?</a></h2>
-<p>You can't, because strings are immutable. If you need an object with
-this ability, try converting the string to a list or use the array
-module:</p>
-<pre class="literal-block">
->>> s = "Hello, world"
->>> a = list(s)
->>> print a
-['H', 'e', 'l', 'l', 'o', ',', ' ', 'w', 'o', 'r', 'l', 'd']
->>> a[7:] = list("there!")
->>> ''.join(a)
-'Hello, there!'
-
->>> import array
->>> a = array.array('c', s)
->>> print a
-array('c', 'Hello, world')
->>> a[0] = 'y' ; print a
-array('c', 'yello world')
->>> a.tostring()
-'yello, world'
-</pre>
-</div>
-<div class="section" id="how-do-i-use-strings-to-call-functions-methods">
-<h2><a class="toc-backref" href="#id26">3.6 How do I use strings to call functions/methods?</a></h2>
-<p>There are various techniques.</p>
-<ul>
-<li><p class="first">The best is to use a dictionary that maps strings to functions. The
-primary advantage of this technique is that the strings do not need
-to match the names of the functions. This is also the primary
-technique used to emulate a case construct:</p>
-<pre class="literal-block">
-def a():
- pass
-
-def b():
- pass
-
-dispatch = {'go': a, 'stop': b} # Note lack of parens for funcs
-
-dispatch[get_input()]() # Note trailing parens to call function
-</pre>
-</li>
-<li><p class="first">Use the built-in function <tt class="docutils literal">getattr()</tt>:</p>
-<pre class="literal-block">
-import foo
-getattr(foo, 'bar')()
-</pre>
-<p>Note that getattr() works on any object, including classes, class
-instances, modules, and so on.</p>
-<p>This is used in several places in the standard library, like
-this:</p>
-<pre class="literal-block">
-class Foo:
- def do_foo(self):
- ...
-
- def do_bar(self):
- ...
-
- f = getattr(foo_instance, 'do_' + opname)
- f()
-</pre>
-</li>
-<li><p class="first">Use <tt class="docutils literal">locals()</tt> or <tt class="docutils literal">eval()</tt> to resolve the function name:</p>
-<pre class="literal-block">
-def myFunc():
- print "hello"
-
-fname = "myFunc"
-
-f = locals()[fname]
-f()
-
-f = eval(fname)
-f()
-</pre>
-<p>Note: Using <tt class="docutils literal">eval()</tt> is slow and dangerous. If you don't have absolute control
-over the contents of the string, someone could pass a string that
-resulted in an arbitrary function being executed.</p>
-</li>
-</ul>
-</div>
-<div class="section" id="is-there-an-equivalent-to-perl-s-chomp-for-removing-trailing-newlines-from-strings">
-<h2><a class="toc-backref" href="#id27">3.7 Is there an equivalent to Perl's chomp() for removing trailing newlines from strings?</a></h2>
-<p>Starting with Python 2.2, you can use <tt class="docutils literal"><span class="pre">S.rstrip("\r\n")</span></tt> to remove
-all occurances of any line terminator from the end of the string <tt class="docutils literal">S</tt>
-without removing other trailing whitespace. If the string <tt class="docutils literal">S</tt>
-represents more than one line, with several empty lines at the end,
-the line terminators for all the blank lines will be removed:</p>
-<pre class="literal-block">
->>> lines = ("line 1 \r\n"
-... "\r\n"
-... "\r\n")
->>> lines.rstrip("\n\r")
-"line 1 "
-</pre>
-<p>Since this is typically only desired when reading text one line at a
-time, using <tt class="docutils literal">S.rstrip()</tt> this way works well.</p>
-<p>For older versions of Python, There are two partial substitutes:</p>
-<ul class="simple">
-<li>If you want to remove all trailing whitespace, use the <tt class="docutils literal">rstrip()</tt>
-method of string objects. This removes all trailing whitespace, not
-just a single newline.</li>
-<li>Otherwise, if there is only one line in the string <tt class="docutils literal">S</tt>, use
-<tt class="docutils literal"><span class="pre">S.splitlines()[0]</span></tt>.</li>
-</ul>
-</div>
-<div class="section" id="is-there-a-scanf-or-sscanf-equivalent">
-<h2><a class="toc-backref" href="#id28">3.8 Is there a scanf() or sscanf() equivalent?</a></h2>
-<p>Not as such.</p>
-<p>For simple input parsing, the easiest approach is usually to split the
-line into whitespace-delimited words using the <tt class="docutils literal">split()</tt> method of
-string objects and then convert decimal strings to numeric values using
-<tt class="docutils literal">int()</tt> or <tt class="docutils literal">float()</tt>. <tt class="docutils literal">split()</tt> supports an optional "sep"
-parameter which is useful if the line uses something other than
-whitespace as a separator.</p>
-<p>For more complicated input parsing, regular expressions
-more powerful than C's <tt class="docutils literal">sscanf()</tt> and better suited for the task.</p>
-</div>
-<div class="section" id="what-does-unicodeerror-ascii-decoding-encoding-error-ordinal-not-in-range-128-mean">
-<h2><a class="toc-backref" href="#id29">3.9 What does 'UnicodeError: ASCII [decoding,encoding] error: ordinal not in range(128)' mean?</a></h2>
-<p>This error indicates that your Python installation can handle
-only 7-bit ASCII strings. There are a couple ways to fix or
-work around the problem.</p>
-<p>If your programs must handle data in arbitary character set encodings,
-the environment the application runs in will generally identify the
-encoding of the data it is handing you. You need to convert the input
-to Unicode data using that encoding. For example, a program that
-handles email or web input will typically find character set encoding
-information in Content-Type headers. This can then be used to
-properly convert input data to Unicode. Assuming the string referred
-to by <tt class="docutils literal">value</tt> is encoded as UTF-8:</p>
-<pre class="literal-block">
-value = unicode(value, "utf-8")
-</pre>
-<p>will return a Unicode object. If the data is not correctly encoded as
-UTF-8, the above call will raise a <tt class="docutils literal">UnicodeError</tt> exception.</p>
-<p>If you only want strings coverted to Unicode which have non-ASCII
-data, you can try converting them first assuming an ASCII encoding,
-and then generate Unicode objects if that fails:</p>
-<pre class="literal-block">
-try:
- x = unicode(value, "ascii")
-except UnicodeError:
- value = unicode(value, "utf-8")
-else:
- # value was valid ASCII data
- pass
-</pre>
-<p>It's possible to set a default encoding in a file called <tt class="docutils literal">sitecustomize.py</tt>
-that's part of the Python library. However, this isn't recommended because changing the Python-wide default encoding may cause third-party extension modules to fail.</p>
-<p>Note that on Windows, there is an encoding known as "mbcs", which uses
-an encoding specific to your current locale. In many cases, and
-particularly when working with COM, this may be an appropriate default
-encoding to use.</p>
-</div>
-</div>
-<div class="section" id="sequences-tuples-lists">
-<h1><a class="toc-backref" href="#id30">4 Sequences (Tuples/Lists)</a></h1>
-<div class="section" id="how-do-i-convert-between-tuples-and-lists">
-<h2><a class="toc-backref" href="#id31">4.1 How do I convert between tuples and lists?</a></h2>
-<p>The function <tt class="docutils literal">tuple(seq)</tt> converts any sequence (actually, any
-iterable) into a tuple with the same items in the same order.</p>
-<p>For example, <tt class="docutils literal"><span class="pre">tuple([1,</span> 2, 3])</tt> yields <tt class="docutils literal">(1, 2, 3)</tt> and <tt class="docutils literal"><span class="pre">tuple('abc')</span></tt>
-yields <tt class="docutils literal">('a', 'b', 'c')</tt>. If the argument is
-a tuple, it does not make a copy but returns the same object, so
-it is cheap to call <tt class="docutils literal">tuple()</tt> when you aren't sure that an object
-is already a tuple.</p>
-<p>The function <tt class="docutils literal">list(seq)</tt> converts any sequence or iterable into a list with
-the same items in the same order.
-For example, <tt class="docutils literal"><span class="pre">list((1,</span> 2, 3))</tt> yields <tt class="docutils literal">[1, 2, 3]</tt> and <tt class="docutils literal"><span class="pre">list('abc')</span></tt>
-yields <tt class="docutils literal">['a', 'b', 'c']</tt>. If the argument is a list,
-it makes a copy just like <tt class="docutils literal"><span class="pre">seq[:]</span></tt> would.</p>
-</div>
-<div class="section" id="what-s-a-negative-index">
-<h2><a class="toc-backref" href="#id32">4.2 What's a negative index?</a></h2>
-<p>Python sequences are indexed with positive numbers and
-negative numbers. For positive numbers 0 is the first index
-1 is the second index and so forth. For negative indices -1
-is the last index and -2 is the pentultimate (next to last) index
-and so forth. Think of <tt class="docutils literal"><span class="pre">seq[-n]</span></tt> as the same as <tt class="docutils literal"><span class="pre">seq[len(seq)-n]</span></tt>.</p>
-<p>Using negative indices can be very convenient. For example <tt class="docutils literal"><span class="pre">S[:-1]</span></tt>
-is all of the string except for its last character, which is useful
-for removing the trailing newline from a string.</p>
-</div>
-<div class="section" id="how-do-i-iterate-over-a-sequence-in-reverse-order">
-<h2><a class="toc-backref" href="#id33">4.3 How do I iterate over a sequence in reverse order?</a></h2>
-<p>If it is a list, the fastest solution is</p>
-<pre class="literal-block">
-list.reverse()
-try:
- for x in list:
- "do something with x"
-finally:
- list.reverse()
-</pre>
-<p>This has the disadvantage that while you are in the loop, the list
-is temporarily reversed. If you don't like this, you can make a copy.
-This appears expensive but is actually faster than other solutions:</p>
-<pre class="literal-block">
-rev = list[:]
-rev.reverse()
-for x in rev:
- <do something with x>
-</pre>
-<p>If it's not a list, a more general but slower solution is:</p>
-<pre class="literal-block">
-for i in range(len(sequence)-1, -1, -1):
- x = sequence[i]
- <do something with x>
-</pre>
-<p>A more elegant solution, is to define a class which acts as a sequence
-and yields the elements in reverse order (solution due to Steve
-Majewski):</p>
-<pre class="literal-block">
-class Rev:
- def __init__(self, seq):
- self.forw = seq
- def __len__(self):
- return len(self.forw)
- def __getitem__(self, i):
- return self.forw[-(i + 1)]
-</pre>
-<p>You can now simply write:</p>
-<pre class="literal-block">
-for x in Rev(list):
- <do something with x>
-</pre>
-<p>Unfortunately, this solution is slowest of all, due to the method
-call overhead.</p>
-<p>With Python 2.3, you can use an extended slice syntax:</p>
-<pre class="literal-block">
-for x in sequence[::-1]:
- <do something with x>
-</pre>
-</div>
-<div class="section" id="how-do-you-remove-duplicates-from-a-list">
-<h2><a class="toc-backref" href="#id34">4.4 How do you remove duplicates from a list?</a></h2>
-<p>See the Python Cookbook for a long discussion of many ways to do this:</p>
-<blockquote>
-<a class="reference external" href="http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52560">http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52560</a></blockquote>
-<p>If you don't mind reordering the list, sort it and then scan from the
-end of the list, deleting duplicates as you go:</p>
-<pre class="literal-block">
-if List:
- List.sort()
- last = List[-1]
- for i in range(len(List)-2, -1, -1):
- if last==List[i]: del List[i]
- else: last=List[i]
-</pre>
-<p>If all elements of the list may be used as
-dictionary keys (i.e. they are all hashable)
-this is often faster</p>
-<pre class="literal-block">
-d = {}
-for x in List: d[x]=x
-List = d.values()
-</pre>
-</div>
-<div class="section" id="how-do-you-make-an-array-in-python">
-<h2><a class="toc-backref" href="#id35">4.5 How do you make an array in Python?</a></h2>
-<p>Use a list:</p>
-<pre class="literal-block">
-["this", 1, "is", "an", "array"]
-</pre>
-<p>Lists are equivalent to C or Pascal arrays in their time complexity;
-the primary difference is that a Python list can contain objects of
-many different types.</p>
-<p>The <tt class="docutils literal">array</tt> module also provides methods for creating arrays of
-fixed types with compact representations, but they are slower to index
-than lists. Also note that the Numeric extensions and others define
-array-like structures with various characteristics as well.</p>
-<p>To get Lisp-style linked lists, you can emulate cons cells using tuples:</p>
-<pre class="literal-block">
-lisp_list = ("like", ("this", ("example", None) ) )
-</pre>
-<p>If mutability is desired, you could use lists instead of tuples. Here
-the analogue of lisp car is <tt class="docutils literal">lisp_list[0]</tt> and the analogue of cdr
-is <tt class="docutils literal">lisp_list[1]</tt>. Only do this if you're sure you really need to,
-because it's usually a lot slower than using Python lists.</p>
-</div>
-<div class="section" id="how-do-i-create-a-multidimensional-list">
-<h2><a class="toc-backref" href="#id36">4.6 How do I create a multidimensional list?</a></h2>
-<p>You probably tried to make a multidimensional array like this:</p>
-<pre class="literal-block">
-A = [[None] * 2] * 3
-</pre>
-<p>This looks correct if you print it:</p>
-<pre class="literal-block">
->>> A
-[[None, None], [None, None], [None, None]]
-</pre>
-<p>But when you assign a value, it shows up in multiple places:</p>
-<blockquote>
-<pre class="doctest-block">
->>> A[0][0] = 5
->>> A
-[[5, None], [5, None], [5, None]]
-</pre>
-</blockquote>
-<p>The reason is that replicating a list with <tt class="docutils literal">*</tt> doesn't create copies, it only creates references to the existing objects. The <tt class="docutils literal">*3</tt>
-creates a list containing 3 references to the same list of length
-two. Changes to one row will show in all rows, which is almost certainly
-not what you want.</p>
-<p>The suggested approach is to create a list of the desired length first
-and then fill in each element with a newly created list:</p>
-<pre class="literal-block">
-A = [None]*3
-for i in range(3):
- A[i] = [None] * 2
-</pre>
-<p>This generates a list containing 3 different lists of length two.
-You can also use a list comprehension:</p>
-<pre class="literal-block">
-w,h = 2,3
-A = [ [None]*w for i in range(h) ]
-</pre>
-<p>Or, you can use an extension that provides a matrix datatype; <a class="reference external" href="http://www.pfdubois.com/numpy/">Numeric
-Python</a> is the best known.</p>
-</div>
-<div class="section" id="how-do-i-apply-a-method-to-a-sequence-of-objects">
-<h2><a class="toc-backref" href="#id37">4.7 How do I apply a method to a sequence of objects?</a></h2>
-<p>Use a list comprehension:</p>
-<pre class="literal-block">
-result = [obj.method() for obj in List]
-</pre>
-<p>More generically, you can try the following function:</p>
-<pre class="literal-block">
-def method_map(objects, method, arguments):
- """method_map([a,b], "meth", (1,2)) gives [a.meth(1,2), b.meth(1,2)]"""
- nobjects = len(objects)
- methods = map(getattr, objects, [method]*nobjects)
- return map(apply, methods, [arguments]*nobjects)
-</pre>
-</div>
-</div>
-<div class="section" id="dictionaries">
-<h1><a class="toc-backref" href="#id38">5 Dictionaries</a></h1>
-<div class="section" id="how-can-i-get-a-dictionary-to-display-its-keys-in-a-consistent-order">
-<h2><a class="toc-backref" href="#id39">5.1 How can I get a dictionary to display its keys in a consistent order?</a></h2>
-<p>You can't. Dictionaries store their keys in an unpredictable order,
-so the display order of a dictionary's elements will be similarly
-unpredictable.</p>
-<p>This can be frustrating if you want to save a printable version to a
-file, make some changes and then compare it with some other printed
-dictionary. In this case, use the <tt class="docutils literal">pprint</tt> module to pretty-print
-the dictionary; the items will be presented in order sorted by the key.</p>
-<p>A more complicated solution is to subclass <tt class="docutils literal">UserDict.UserDict</tt>
-to create a <tt class="docutils literal">SortedDict</tt> class that prints itself in a predictable order.
-Here's one simpleminded implementation of such a class:</p>
-<pre class="literal-block">
-import UserDict, string
-
-class SortedDict(UserDict.UserDict):
- def __repr__(self):
- result = []
- append = result.append
- keys = self.data.keys()
- keys.sort()
- for k in keys:
- append("%s: %s" % (`k`, `self.data[k]`))
- return "{%s}" % string.join(result, ", ")
-
- ___str__ = __repr__
-</pre>
-<p>This will work for many common situations you might encounter, though
-it's far from a perfect solution. The largest flaw is that if some
-values in the dictionary are also dictionaries, their values won't be
-presented in any particular order.</p>
-</div>
-<div class="section" id="i-want-to-do-a-complicated-sort-can-you-do-a-schwartzian-transform-in-python">
-<h2><a class="toc-backref" href="#id40">5.2 I want to do a complicated sort: can you do a Schwartzian Transform in Python?</a></h2>
-<p>Yes, it's quite simple with list comprehensions.</p>
-<p>The technique, attributed to Randal Schwartz of the Perl community,
-sorts the elements of a list by a metric which maps each element to
-its "sort value". To sort a list of strings by their uppercase
-values:</p>
-<pre class="literal-block">
-tmp1 = [ (x.upper(), x) for x in L ] # Schwartzian transform
-tmp1.sort()
-Usorted = [ x[1] for x in tmp1 ]
-</pre>
-<p>To sort by the integer value of a subfield extending from positions 10-15
-in each string:</p>
-<pre class="literal-block">
-tmp2 = [ (int(s[10:15]), s) for s in L ] # Schwartzian transform
-tmp2.sort()
-Isorted = [ x[1] for x in tmp2 ]
-</pre>
-<p>Note that Isorted may also be computed by</p>
-<pre class="literal-block">
-def intfield(s):
- return int(s[10:15])
-
-def Icmp(s1, s2):
- return cmp(intfield(s1), intfield(s2))
-
-Isorted = L[:]
-Isorted.sort(Icmp)
-</pre>
-<p>but since this method calls <tt class="docutils literal">intfield()</tt> many times for each element
-of L, it is slower than the Schwartzian Transform.</p>
-</div>
-<div class="section" id="how-can-i-sort-one-list-by-values-from-another-list">
-<h2><a class="toc-backref" href="#id41">5.3 How can I sort one list by values from another list?</a></h2>
-<p>Merge them into a single list of tuples, sort the resulting list,
-and then pick out the element you want.</p>
-<pre class="literal-block">
->>> list1 = ["what", "I'm", "sorting", "by"]
->>> list2 = ["something", "else", "to", "sort"]
->>> pairs = zip(list1, list2)
->>> pairs
-[('what', 'something'), ("I'm", 'else'), ('sorting', 'to'), ('by', 'sort')]
->>> pairs.sort()
->>> result = [ x[1] for x in pairs ]
->>> result
-['else', 'sort', 'to', 'something']
-</pre>
-<p>An alternative for the last step is:</p>
-<pre class="literal-block">
-result = []
-for p in pairs: result.append(p[1])
-</pre>
-<p>If you find this more legible, you might prefer to use this instead of
-the final list comprehension. However, it is almost twice as slow for
-long lists. Why? First, the <tt class="docutils literal">append()</tt> operation has to reallocate
-memory, and while it uses some tricks to avoid doing that each time,
-it still has to do it occasionally, and that costs quite a bit.
-Second, the expression "result.append" requires an extra attribute
-lookup, and third, there's a speed reduction from having to make
-all those function calls.</p>
-</div>
-</div>
-<div class="section" id="objects">
-<h1><a class="toc-backref" href="#id42">6 Objects</a></h1>
-<div class="section" id="what-is-a-class">
-<h2><a class="toc-backref" href="#id43">6.1 What is a class?</a></h2>
-<p>A class is the particular object type created by executing
-a class statement. Class objects are used as templates to create
-instance objects, which embody both the data
-(attributes) and code (methods) specific to a datatype.</p>
-<p>A class can be based on one or more other classes, called its base
-class(es). It then inherits the attributes and methods of its base
-classes. This allows an object model to be successively refined by
-inheritance. You might have a generic <tt class="docutils literal">Mailbox</tt> class that provides
-basic accessor methods for a mailbox, and subclasses such as
-<tt class="docutils literal">MboxMailbox</tt>, <tt class="docutils literal">MaildirMailbox</tt>, <tt class="docutils literal">OutlookMailbox</tt> that handle
-various specific mailbox formats.</p>
-</div>
-<div class="section" id="what-is-a-method">
-<h2><a class="toc-backref" href="#id44">6.2 What is a method?</a></h2>
-<p>A method is a function on some object <tt class="docutils literal">x</tt> that you normally call as
-<tt class="docutils literal"><span class="pre">x.name(arguments...)</span></tt>. Methods are defined as functions inside the
-class definition:</p>
-<pre class="literal-block">
-class C:
- def meth (self, arg):
- return arg*2 + self.attribute
-</pre>
-</div>
-<div class="section" id="what-is-self">
-<h2><a class="toc-backref" href="#id45">6.3 What is self?</a></h2>
-<p>Self is merely a conventional name for the first argument of a method.
-A method defined as <tt class="docutils literal">meth(self, a, b, c)</tt> should be called as
-<tt class="docutils literal">x.meth(a, b, c)</tt> for some instance <tt class="docutils literal">x</tt> of the class in which the
-definition occurs; the called method will think it is called as
-<tt class="docutils literal">meth(x, a, b, c)</tt>.</p>
-<p>See also
-<a class="reference external" href="general.html#why-must-self-be-used-explicitly-in-method-definitions-and-calls">Why must 'self' be used explicitly in method definitions and calls?</a></p>
-</div>
-<div class="section" id="how-do-i-check-if-an-object-is-an-instance-of-a-given-class-or-of-a-subclass-of-it">
-<h2><a class="toc-backref" href="#id46">6.4 How do I check if an object is an instance of a given class or of a subclass of it?</a></h2>
-<p>Use the built-in function <tt class="docutils literal">isinstance(obj, cls)</tt>. You can check if
-an object is an instance of any of a number of classes by providing a tuple instead of a single class, e.g. <tt class="docutils literal">isinstance(obj, (class1, class2, <span class="pre">...))</span></tt>,
-and can also check whether an object is one of Python's built-in types, e.g.
-<tt class="docutils literal">isinstance(obj, str)</tt> or <tt class="docutils literal">isinstance(obj, (int, long, float, complex))</tt>.</p>
-<p>Note that most programs do not use <tt class="docutils literal">isinstance()</tt> on user-defined
-classes very often. If you are developing the classes yourself, a
-more proper object-oriented style is to define methods on the classes
-that encapsulate a particular behaviour, instead of checking the
-object's class and doing a different thing based on what class it is.
-For example, if you have a function that does something:</p>
-<pre class="literal-block">
-def search (obj):
- if isinstance(obj, Mailbox):
- # ... code to search a mailbox
- elif isinstance(obj, Document):
- # ... code to search a document
- elif ...
-</pre>
-<p>A better approach is to define a <tt class="docutils literal">search()</tt> method on all the
-classes and just call it:</p>
-<pre class="literal-block">
-class Mailbox:
- def search(self):
- # ... code to search a mailbox
-
-class Document:
- def search(self):
- # ... code to search a document
-
-obj.search()
-</pre>
-</div>
-<div class="section" id="what-is-delegation">
-<h2><a class="toc-backref" href="#id47">6.5 What is delegation?</a></h2>
-<p>Delegation is an object oriented technique (also called a design
-pattern). Let's say you have an object <tt class="docutils literal">x</tt> and want to change the
-behaviour of just one of its methods. You can create a new class that
-provides a new implementation of the method you're interested in changing
-and delegates all other methods to the corresponding method of <tt class="docutils literal">x</tt>.</p>
-<p>Python programmers can easily implement delegation. For example, the
-following class implements a class that behaves like a file but
-converts all written data to uppercase:</p>
-<pre class="literal-block">
-class UpperOut:
- def __init__(self, outfile):
- self.__outfile = outfile
- def write(self, s):
- self.__outfile.write(s.upper())
- def __getattr__(self, name):
- return getattr(self.__outfile, name)
-</pre>
-<p>Here the <tt class="docutils literal">UpperOut</tt> class redefines the <tt class="docutils literal">write()</tt> method to
-convert the argument string to uppercase before calling the underlying
-<tt class="docutils literal">self.__outfile.write()</tt> method. All other methods are delegated to
-the underlying <tt class="docutils literal">self.__outfile</tt> object. The delegation is
-accomplished via the <tt class="docutils literal">__getattr__</tt> method; consult <a class="reference external" href="../../doc/ref/attribute-access.html">the language
-reference</a> for
-more information about controlling attribute access.</p>
-<p>Note that for more general cases delegation can get trickier. When
-attributes must be set as well as retrieved, the class must define a
-<tt class="docutils literal">__settattr__</tt> method too, and it must do so carefully. The basic
-implementation of __setattr__ is roughly equivalent to the following:</p>
-<pre class="literal-block">
-class X:
- ...
- def __setattr__(self, name, value):
- self.__dict__[name] = value
- ...
-</pre>
-<p>Most __setattr__ implementations must modify
-self.__dict__ to store local state for self without
-causing an infinite recursion.</p>
-</div>
-<div class="section" id="how-do-i-call-a-method-defined-in-a-base-class-from-a-derived-class-that-overrides-it">
-<h2><a class="toc-backref" href="#id48">6.6 How do I call a method defined in a base class from a derived class that overrides it?</a></h2>
-<p>If you're using new-style classes, use the built-in <tt class="docutils literal">super()</tt> function:</p>
-<pre class="literal-block">
-class Derived(Base):
- def meth (self):
- super(Derived, self).meth()
-</pre>
-<p>If you're using classic classes: For a class definition such as
-<tt class="docutils literal">class Derived(Base): ...</tt> you can call method <tt class="docutils literal">meth()</tt> defined in
-<tt class="docutils literal">Base</tt> (or one of <tt class="docutils literal">Base</tt>'s base classes) as <tt class="docutils literal">Base.meth(self,
-<span class="pre">arguments...)</span></tt>. Here, <tt class="docutils literal">Base.meth</tt> is an unbound method, so you
-need to provide the <tt class="docutils literal">self</tt> argument.</p>
-</div>
-<div class="section" id="how-can-i-organize-my-code-to-make-it-easier-to-change-the-base-class">
-<h2><a class="toc-backref" href="#id49">6.7 How can I organize my code to make it easier to change the base class?</a></h2>
-<p>You could define an alias for the base class, assign the real base
-class to it before your class definition, and use the alias throughout
-your class. Then all you have to change is the value assigned to the
-alias. Incidentally, this trick is also handy if you want to decide
-dynamically (e.g. depending on availability of resources) which base
-class to use. Example:</p>
-<pre class="literal-block">
-BaseAlias = <real base class>
-class Derived(BaseAlias):
- def meth(self):
- BaseAlias.meth(self)
- ...
-</pre>
-</div>
-<div class="section" id="how-do-i-create-static-class-data-and-static-class-methods">
-<h2><a class="toc-backref" href="#id50">6.8 How do I create static class data and static class methods?</a></h2>
-<p>Static data (in the sense of C++ or Java) is easy; static methods
-(again in the sense of C++ or Java) are not supported directly.</p>
-<p>For static data, simply define a class attribute. To assign a new
-value to the attribute, you have to explicitly use the class name in
-the assignment:</p>
-<pre class="literal-block">
-class C:
- count = 0 # number of times C.__init__ called
-
- def __init__(self):
- C.count = C.count + 1
-
- def getcount(self):
- return C.count # or return self.count
-</pre>
-<p><tt class="docutils literal">c.count</tt> also refers to <tt class="docutils literal">C.count</tt> for any <tt class="docutils literal">c</tt> such that
-<tt class="docutils literal">isinstance(c, C)</tt> holds, unless overridden by <tt class="docutils literal">c</tt> itself or by some
-class on the base-class search path from <tt class="docutils literal">c.__class__</tt> back to <tt class="docutils literal">C</tt>.</p>
-<p>Caution: within a method of C, an assignment like <tt class="docutils literal">self.count = 42</tt>
-creates a new and unrelated instance vrbl named "count" in <tt class="docutils literal">self</tt>'s own dict.
-Rebinding of a class-static data name must always specify the class
-whether inside a method or not:</p>
-<pre class="literal-block">
-C.count = 314
-</pre>
-<p>Static methods are possible when you're using new-style classes:</p>
-<pre class="literal-block">
-class C:
- def static(arg1, arg2, arg3):
- # No 'self' parameter!
- ...
- static = staticmethod(static)
-</pre>
-<p>However, a far more straightforward way to get the effect of a static
-method is via a simple module-level function:</p>
-<pre class="literal-block">
-def getcount():
- return C.count
-</pre>
-<p>If your code is structured so as to define one class (or tightly
-related class hierarchy) per module, this supplies the desired
-encapsulation.</p>
-</div>
-<div class="section" id="how-can-i-overload-constructors-or-methods-in-python">
-<h2><a class="toc-backref" href="#id51">6.9 How can I overload constructors (or methods) in Python?</a></h2>
-<p>This answer actually applies to all methods, but the question
-usually comes up first in the context of constructors.</p>
-<p>In C++ you'd write</p>
-<pre class="literal-block">
-class C {
- C() { cout << "No arguments\n"; }
- C(int i) { cout << "Argument is " << i << "\n"; }
-}
-</pre>
-<p>in Python you have to write a single constructor that catches all
-cases using default arguments. For example:</p>
-<pre class="literal-block">
-class C:
- def __init__(self, i=None):
- if i is None:
- print "No arguments"
- else:
- print "Argument is", i
-</pre>
-<p>This is not entirely equivalent, but close enough in practice.</p>
-<p>You could also try a variable-length argument list, e.g.</p>
-<pre class="literal-block">
-def __init__(self, *args):
- ....
-</pre>
-<p>The same approach works for all method definitions.</p>
-</div>
-<div class="section" id="i-try-to-use-spam-and-i-get-an-error-about-someclassname-spam">
-<h2><a class="toc-backref" href="#id52">6.10 I try to use __spam and I get an error about _SomeClassName__spam.</a></h2>
-<p>Variables with double leading underscore are "mangled" to provide a
-simple but effective way to define class private variables. Any
-identifier of the form <tt class="docutils literal">__spam</tt> (at least two leading
-underscores, at most one trailing underscore) is textually
-replaced with <tt class="docutils literal">_classname__spam</tt>, where <tt class="docutils literal">classname</tt> is the
-current class name with any leading underscores stripped.</p>
-<p>This doesn't guarantee privacy: an outside user can still deliberately
-access the "_classname__spam" attribute, and private values are visible
-in the object's <tt class="docutils literal">__dict__</tt>. Many Python programmers never bother to use
-private variable names at all.</p>
-</div>
-<div class="section" id="my-class-defines-del-but-it-is-not-called-when-i-delete-the-object">
-<h2><a class="toc-backref" href="#id53">6.11 My class defines __del__ but it is not called when I delete the object.</a></h2>
-<p>There are several possible reasons for this.</p>
-<p>The del statement does not necessarily call __del__ -- it simply
-decrements the object's reference count, and if this reaches zero
-__del__ is called.</p>
-<p>If your data structures contain circular links (e.g. a tree where each
-child has a parent reference and each parent has a list of children)
-the reference counts will never go back to zero. Once in a while
-Python runs an algorithm to detect such cycles, but the garbage
-collector might run some time after the last reference to your data
-structure vanishes, so your __del__ method may be called at an
-inconvenient and random time. This is inconvenient if you're trying to
-reproduce a problem. Worse, the order in which object's __del__
-methods are executed is arbitrary. You can run <tt class="docutils literal">gc.collect()</tt> to
-force a collection, but there <em>are</em> pathological cases where objects will
-never be collected.</p>
-<p>Despite the cycle collector, it's still a good idea to define an
-explicit <tt class="docutils literal">close()</tt> method on objects to be called whenever you're
-done with them. The <tt class="docutils literal">close()</tt> method can then remove attributes
-that refer to subobjecs. Don't call <tt class="docutils literal">__del__</tt> directly --
-<tt class="docutils literal">__del__</tt> should call <tt class="docutils literal">close()</tt> and <tt class="docutils literal">close()</tt> should make sure
-that it can be called more than once for the same object.</p>
-<p>Another way to avoid cyclical references is to use the "weakref"
-module, which allows you to point to objects without incrementing
-their reference count. Tree data structures, for instance, should use
-weak references for their parent and sibling references (if they need
-them!).</p>
-<p>If the object has ever been a local variable in a function that caught
-an expression in an except clause, chances are that a reference to the
-object still exists in that function's stack frame as contained in the
-stack trace. Normally, calling <tt class="docutils literal">sys.exc_clear()</tt> will take care of
-this by clearing the last recorded exception.</p>
-<p>Finally, if your __del__ method raises an exception, a warning message
-is printed to sys.stderr.</p>
-</div>
-<div class="section" id="how-do-i-get-a-list-of-all-instances-of-a-given-class">
-<h2><a class="toc-backref" href="#id54">6.12 How do I get a list of all instances of a given class?</a></h2>
-<p>Python does not keep track of all instances of a class (or of a
-built-in type). You can program the class's constructor to keep track
-of all instances by keeping a list of weak references to each
-instance.</p>
-</div>
-</div>
-<div class="section" id="modules">
-<h1><a class="toc-backref" href="#id55">7 Modules</a></h1>
-<div class="section" id="how-do-i-create-a-pyc-file">
-<h2><a class="toc-backref" href="#id56">7.1 How do I create a .pyc file?</a></h2>
-<p>When a module is imported for the first time (or when the source is
-more recent than the current compiled file) a <tt class="docutils literal">.pyc</tt> file containing
-the compiled code should be created in the same directory as the
-<tt class="docutils literal">.py</tt> file.</p>
-<p>One reason that a <tt class="docutils literal">.pyc</tt> file may not be created is permissions
-problems with the directory. This can happen, for example, if you
-develop as one user but run as another, such as if you are testing
-with a web server. Creation of a .pyc file is automatic if you're
-importing a module and Python has the ability (permissions, free
-space, etc...) to write the compiled module back to the directory.</p>
-<p>Running Python on a top level script is not considered an import and
-no <tt class="docutils literal">.pyc</tt> will be created. For example, if you have a top-level
-module <tt class="docutils literal">abc.py</tt> that imports another module <tt class="docutils literal">xyz.py</tt>, when you run
-abc, <tt class="docutils literal">xyz.pyc</tt> will be created since xyz is imported, but no
-<tt class="docutils literal">abc.pyc</tt> file will be created since <tt class="docutils literal">abc.py</tt> isn't being
-imported.</p>
-<p>If you need to create abc.pyc -- that is, to create a .pyc file for a
-module that is not imported -- you can, using the py_compile and
-compileall modules.</p>
-<p>The <tt class="docutils literal">py_compile</tt> module can manually compile any module. One way is
-to use the <tt class="docutils literal">compile()</tt> function in that module interactively:</p>
-<pre class="literal-block">
->>> import py_compile
->>> py_compile.compile('abc.py')
-</pre>
-<p>This will write the <tt class="docutils literal">.pyc</tt> to the same location as <tt class="docutils literal">abc.py</tt> (or
-you can override that with the optional parameter <tt class="docutils literal">cfile</tt>).</p>
-<p>You can also automatically compile all files in a directory or
-directories using the <tt class="docutils literal">compileall</tt> module.
-You can do it from the shell prompt by running <tt class="docutils literal">compileall.py</tt>
-and providing the path of a directory containing Python files to compile:</p>
-<pre class="literal-block">
-python compileall.py .
-</pre>
-</div>
-<div class="section" id="how-do-i-find-the-current-module-name">
-<h2><a class="toc-backref" href="#id57">7.2 How do I find the current module name?</a></h2>
-<p>A module can find out its own module name by looking at the predefined
-global variable <tt class="docutils literal">__name__</tt>. If this has the value '__main__', the
-program is running as a script. Many modules that are usually used by
-importing them also provide a command-line interface or a self-test,
-and only execute this code after checking <tt class="docutils literal">__name__</tt>:</p>
-<pre class="literal-block">
-def main():
- print 'Running test...'
- ...
-
-if __name__ == '__main__':
- main()
-</pre>
-</div>
-<div class="section" id="how-can-i-have-modules-that-mutually-import-each-other">
-<h2><a class="toc-backref" href="#id58">7.3 How can I have modules that mutually import each other?</a></h2>
-<p>Suppose you have the following modules:</p>
-<p>foo.py:</p>
-<pre class="literal-block">
-from bar import bar_var
-foo_var=1
-</pre>
-<p>bar.py:</p>
-<pre class="literal-block">
-from foo import foo_var
-bar_var=2
-</pre>
-<p>The problem is that the interpreter will perform the following steps:</p>
-<ul class="simple">
-<li>main imports foo</li>
-<li>Empty globals for foo are created</li>
-<li>foo is compiled and starts executing</li>
-<li>foo imports bar</li>
-<li>Empty globals for bar are created</li>
-<li>bar is compiled and starts executing</li>
-<li>bar imports foo (which is a no-op since there already is a module named foo)</li>
-<li>bar.foo_var = foo.foo_var</li>
-</ul>
-<p>The last step fails, because Python isn't done with interpreting <tt class="docutils literal">foo</tt>
-yet and the global symbol dictionary for <tt class="docutils literal">foo</tt> is still empty.</p>
-<p>The same thing happens when you use <tt class="docutils literal">import foo</tt>, and then try to
-access <tt class="docutils literal">foo.foo_var</tt> in global code.</p>
-<p>There are (at least) three possible workarounds for this problem.</p>
-<p>Guido van Rossum recommends avoiding all uses of <tt class="docutils literal">from <module>
-import ...</tt>, and placing all code inside functions. Initializations
-of global variables and class variables should use constants or
-built-in functions only. This means everything from an imported
-module is referenced as <tt class="docutils literal"><span class="pre"><module>.<name></span></tt>.</p>
-<p>Jim Roskind suggests performing steps in the following order in each
-module:</p>
-<ul class="simple">
-<li>exports (globals, functions, and classes that don't need imported base classes)</li>
-<li><tt class="docutils literal">import</tt> statements</li>
-<li>active code (including globals that are initialized from imported values).</li>
-</ul>
-<p>van Rossum doesn't like this approach much because the imports
-appear in a strange place, but it does work.</p>
-<p>Matthias Urlichs recommends restructuring your code so that the
-recursive import is not necessary in the first place.</p>
-<p>These solutions are not mutually exclusive.</p>
-</div>
-<div class="section" id="import-x-y-z-returns-module-x-how-do-i-get-z">
-<h2><a class="toc-backref" href="#id59">7.4 __import__('x.y.z') returns <module 'x'>; how do I get z?</a></h2>
-<p>Try:</p>
-<pre class="literal-block">
-__import__('x.y.z').y.z
-</pre>
-<p>For more realistic situations, you may have to do something like</p>
-<pre class="literal-block">
-m = __import__(s)
-for i in s.split(".")[1:]:
- m = getattr(m, i)
-</pre>
-</div>
-<div class="section" id="when-i-edit-an-imported-module-and-reimport-it-the-changes-don-t-show-up-why-does-this-happen">
-<h2><a class="toc-backref" href="#id60">7.5 When I edit an imported module and reimport it, the changes don't show up. Why does this happen?</a></h2>
-<p>For reasons of efficiency as well as consistency, Python only reads
-the module file on the first time a module is imported. If it didn't,
-in a program consisting of many modules where each one imports the
-same basic module, the basic module would be parsed and re-parsed many
-times. To force rereading of a changed module, do this:</p>
-<pre class="literal-block">
-import modname
-reload(modname)
-</pre>
-<p>Warning: this technique is not 100% fool-proof. In particular,
-modules containing statements like</p>
-<pre class="literal-block">
-from modname import some_objects
-</pre>
-<p>will continue to work with the old version of the imported objects.
-If the module contains class definitions, existing class instances
-will <em>not</em> be updated to use the new class definition. This can
-result in the following paradoxical behaviour:</p>
-<pre class="literal-block">
->>> import cls
->>> c = cls.C() # Create an instance of C
->>> reload(cls)
-<module 'cls' from 'cls.pyc'>
->>> isinstance(c, cls.C) # isinstance is false?!?
-False
-</pre>
-<p>The nature of the problem is made clear if you print out the class objects:</p>
-<blockquote>
-<pre class="doctest-block">
->>> c.__class__
-<class cls.C at 0x7352a0>
->>> cls.C
-<class cls.C at 0x4198d0>
-</pre>
-</blockquote>
-</div>
-</div>
-</div>
-</body>
-</html>
diff --git a/faq/windows.ht b/faq/windows.ht
deleted file mode 100644
index 2620c73..0000000
--- a/faq/windows.ht
+++ /dev/null
@@ -1,592 +0,0 @@
-Title: Python Windows FAQ
-Content-type: text/x-rst
-
-====================================
-Python Windows FAQ
-====================================
-
-:Date: $Date: 2005-07-26 07:21:45 -0600 (Tue, 26 Jul 2005) $
-:Version: $Revision: 8295 $
-:Web site: http://www.python.org/
-
-.. contents::
-.. sectnum::
-
-How do I run a Python program under Windows?
-----------------------------------------------------
-
-This is not necessarily a straightforward question. If you are already
-familiar with running programs from the Windows command line then
-everything will seem obvious; otherwise, you might need a little more
-guidance. There are also differences between Windows 95, 98, NT, ME,
-2000 and XP which can add to the confusion.
-
-Unless you use some sort of integrated development environment,
-you will end up *typing* Windows commands into what is variously referred
-to as a "DOS window" or "Command prompt window". Usually you can
-create such a window from your Start menu; under Windows 2000
-the menu selection is
-"Start | Programs | Accessories | Command Prompt". You should be
-able to recognize when you have started such a window because you will
-see a Windows "command prompt", which usually looks like this::
-
- C:\>
-
-The letter may be different, and there might be other things after it,
-so you might just as easily see something like::
-
- D:\Steve\Projects\Python>
-
-depending on how your computer has been set up and what else you have
-recently done with it. Once you have started such a window, you are
-well on the way to running Python programs.
-
-You need to realize that your Python scripts have to be processed by
-another program called the Python interpreter. The
-interpreter reads your script, compiles it into bytecodes, and then executes the bytecodes to run your
-program. So, how do you arrange for the interpreter to handle your
-Python?
-
-First, you need to make sure that your command window recognises the
-word "python" as an instruction to start the interpreter. If you have
-opened a command window, you should try entering the command ``python``
-and hitting return. You should then see something like::
-
- Python 2.2 (#28, Dec 21 2001, 12:21:22) [MSC 32 bit (Intel)] on win32
- Type "help", "copyright", "credits" or "license" for more information.
- >>>
-
-You have started the interpreter in "interactive mode". That means you
-can enter Python statements or expressions interactively and have them
-executed or evaluated while you wait. This is one of Python's
-strongest features. Check it by entering a few expressions of your
-choice and seeing the results::
-
- >>> print "Hello"
- Hello
- >>> "Hello" * 3
- HelloHelloHello
-
-Many people use the interactive mode as a convenient yet highly
-programmable calculator.
-When you want to end your interactive Python session, hold the Ctrl
-key down while you enter a Z, then hit the "Enter" key to get back to
-your Windows command prompt.
-
-You may also find that you have a
-Start-menu entry such as "Start | Programs | Python 2.2 | Python
-(command line)" that results in you seeing the ``>>>`` prompt in a new
-window. If so, the window will disappear after you enter the
-Ctrl-Z character; Windows is running a single "python" command in the window,
-and closes it when you terminate the interpreter.
-
-If the ``python`` command, instead of displaying the interpreter
-prompt ``>>>``, gives you a message like::
-
- 'python' is not recognized as an internal or external command,
- operable program or batch file.
-
-or::
-
- Bad command or filename
-
-then you need to make sure that your computer knows where to find the
-Python interpreter. To do this you will have to modify a setting
-called PATH, which is a list of directories where Windows
-will look for programs. You should arrange for Python's
-installation directory to be added to the PATH of every command window
-as it starts. If you installed Python fairly recently then the command ::
-
- dir C:\py*
-
-will probably tell you where it is installed; the usual location is
-something like ``C:\Python23``. Otherwise you will be reduced to a search of your
-whole disk ... use "Tools | Find"
-or hit the "Search" button and look for "python.exe". Supposing you
-discover that Python is installed in the ``C:\Python23`` directory (the
-default at the time of writing), you should make sure that
-entering the command ::
-
- c:\Python23\python
-
-starts up the interpreter as above (and don't forget you'll need a
-"CTRL-Z" and an "Enter" to get out of it). Once you have verified the
-directory, you need to add it to the start-up routines your computer
-goes through. For older versions of Windows the easiest way to do
-this is to edit the ``C:\AUTOEXEC.BAT`` file. You would want to add a line
-like the following to ``AUTOEXEC.BAT``::
-
- PATH C:\Python23;%PATH%
-
-For Windows NT, 2000 and (I assume) XP, you will need to add a string
-such as ::
-
- ;C:\Python23
-
-to the current setting for the PATH environment variable, which you
-will find in the properties window of "My Computer" under the
-"Advanced" tab. Note that if you have sufficient privilege you might
-get a choice of installing the settings either for the Current User or
-for System. The latter is preferred if you want everybody to be able
-to run Python on the machine.
-
-If you aren't confident doing any of these manipulations yourself, ask
-for help! At this stage you may want to reboot your system
-to make absolutely sure the new setting has taken effect. You probably
-won't need to reboot for Windows NT, XP or 2000. You can also avoid it in
-earlier versions by editing the file ``C:\WINDOWS\COMMAND\CMDINIT.BAT``
-instead of ``AUTOEXEC.BAT``.
-
-You should now be able to start a new command window, enter ``python``
-at the ``C:>`` (or whatever) prompt, and see the ``>>>`` prompt that
-indicates the Python interpreter is reading interactive commands.
-
-Let's suppose you have a program called ``pytest.py`` in directory
-``C:\Steve\Projects\Python``. A session to run that program might look
-like this::
-
- C:\> cd \Steve\Projects\Python
- C:\Steve\Projects\Python> python pytest.py
-
-Because you added a file name to the command to start the interpreter,
-when it starts up it reads the Python script in the named file,
-compiles it, executes it, and terminates, so you see another ``C:\>``
-prompt. You might also have entered ::
-
- C:\> python \Steve\Projects\Python\pytest.py
-
-if you hadn't wanted to change your current directory.
-
-Under NT, 2000 and XP you may well find that the installation process
-has also arranged that the command ``pytest.py``
-(or, if the file isn't in the current directory,
-``C:\Steve\Projects\Python\pytest.py``)
-will automatically recognize the ".py" extension and run the Python
-interpreter on the named file. Using this feature is fine, but *some*
-versions of Windows have bugs which mean that this form isn't exactly
-equivalent to using the interpreter explicitly, so be careful.
-
-The important things to remember are:
-
-1. Start Python from the Start Menu, or make sure the PATH is set
- correctly so Windows can find the Python interpreter. ::
-
- python
-
- should give you a '>>>" prompt from the Python interpreter. Don't
- forget the CTRL-Z and ENTER to terminate the interpreter (and, if you
- started the window from the Start Menu, make the window disappear).
-
-2. Once this works, you run programs with commands::
-
- python {program-file}
-
-3. When you know the commands to use you can build Windows shortcuts
- to run the Python interpreter on any of your scripts, naming
- particular working directories, and adding them to your menus.
- Take a look at ::
-
- python --help
-
- if your needs are complex.
-
-4. Interactive mode (where you see the ``>>>`` prompt) is best used
- for checking that individual statements and expressions do
- what you think they will, and for developing code by experiment.
-
-
-How do I make python scripts executable?
-----------------------------------------------
-
-On Windows 2000, the standard Python installer already associates the
-.py extension with a file type (Python.File) and gives that file type
-an open command that runs the interpreter (D:\\Program
-Files\\Python\\python.exe "%1" %*). This is enough to make scripts
-executable from the command prompt as 'foo.py'. If you'd rather be
-able to execute the script by simple typing 'foo' with no extension
-you need to add .py to the PATHEXT environment variable.
-
-On Windows NT, the steps taken by the installer as described above
-allow you to run a script with 'foo.py', but a longtime bug in the NT
-command processor prevents you from redirecting the input or output of
-any script executed in this way. This is often important.
-
-The incantation for making a Python script executable under WinNT
-is to give the file an extension of .cmd and add the following as the first
-line::
-
- @setlocal enableextensions & python -x %~f0 %* & goto :EOF
-
-
-Why does Python sometimes take so long to start?
--------------------------------------------------------
-
-Usually Python starts very quickly on Windows, but occasionally there
-are bug reports that Python suddenly begins to take a long time to
-start up. This is made even more puzzling because Python will work fine
-on other Windows systems which appear to be configured identically.
-
-The problem may be caused by a misconfiguration of virus checking
-software on the problem machine. Some virus scanners have been known
-to introduce startup overhead of two orders of magnitude when the
-scanner is configured to monitor all reads from the filesystem. Try
-checking the configuration of virus scanning software on your systems
-to ensure that they are indeed configured identically. McAfee, when
-configured to scan all file system read activity, is a particular
-offender.
-
-
-Where is Freeze for Windows?
-------------------------------------
-
-"Freeze" is a program that allows you to ship a Python program
-as a single stand-alone executable file. It is *not* a compiler;
-your programs don't run any faster, but they are more easily
-distributable, at least to platforms with the same OS and CPU. Read the
-README file of the freeze program for more disclaimers.
-
-You can use freeze on Windows, but you must download the source
-tree (see http://www.python.org/download/download_source.html).
-The freeze program is in the ``Tools\freeze`` subdirectory of the source
-tree.
-
-You need the Microsoft VC++ compiler, and you probably need to build
-Python. The required project files are in the PCbuild directory.
-
-
-Is a ``*.pyd`` file the same as a DLL?
-------------------------------------------
-Yes, .pyd files are dll's, but there are a few differences. If you
-have a DLL named ``foo.pyd``, then it must have a function initfoo(). You
-can then write Python "import foo", and Python will search for foo.pyd
-(as well as foo.py, foo.pyc) and if it finds it, will attempt to call
-initfoo() to initialize it. You do not link your .exe with foo.lib,
-as that would cause Windows to require the DLL to be present.
-
-Note that the search path for foo.pyd is PYTHONPATH, not the same as
-the path that Windows uses to search for foo.dll. Also, foo.pyd need
-not be present to run your program, whereas if you linked your program
-with a dll, the dll is required. Of course, foo.pyd is required if
-you want to say "import foo". In a DLL, linkage is declared in the
-source code with __declspec(dllexport). In a .pyd, linkage is defined
-in a list of available functions.
-
-How can I embed Python into a Windows application?
-----------------------------------------------------------
-Embedding the Python interpreter in a Windows app can be summarized as
-follows:
-
-1. Do _not_ build Python into your .exe file directly. On Windows,
- Python must be a DLL to handle importing modules that are themselves
- DLL's. (This is the first key undocumented fact.) Instead, link to
- pythonNN.dll; it is typically installed in ``C:\Windows\System``.
- NN is the Python version, a number such as "23" for Python 2.3.
-
- You can link to Python statically or dynamically. Linking
- statically means linking against pythonNN.lib, while dynamically
- linking means linking against pythonNN.dll. The drawback to
- dynamic linking is that your app won't run if pythonNN.dll does not
- exist on your system.
- (General note: pythonNN.lib is the so-called "import lib" corresponding
- to python.dll. It merely defines symbols for the linker.)
-
- Linking dynamically greatly simplifies link options; everything happens
- at run time. Your code must load pythonNN.dll using the Windows
- LoadLibraryEx() routine. The code must also use access routines and
- data in pythonNN.dll (that is, Python's C API's) using pointers
- obtained by the Windows GetProcAddress() routine. Macros can make
- using these pointers transparent to any C code that calls routines in
- Python's C API.
-
- Borland note: convert pythonNN.lib to OMF format using Coff2Omf.exe
- first.
-
-2. If you use SWIG, it is easy to create a Python "extension module"
- that will make the app's data and methods available to Python. SWIG
- will handle just about all the grungy details for you. The result is C
- code that you link *into* your .exe file (!) You do _not_ have to
- create a DLL file, and this also simplifies linking.
-
-3. SWIG will create an init function (a C function) whose name depends
- on the name of the extension module. For example, if the name of the
- module is leo, the init function will be called initleo(). If you use
- SWIG shadow classes, as you should, the init function will be called
- initleoc(). This initializes a mostly hidden helper class used by the
- shadow class.
-
- The reason you can link the C code in step 2 into your .exe file is that
- calling the initialization function is equivalent to importing the
- module into Python! (This is the second key undocumented fact.)
-
-4. In short, you can use the following code to initialize the Python
- interpreter with your extension module. ::
-
- #include "python.h"
- ...
- Py_Initialize(); // Initialize Python.
- initmyAppc(); // Initialize (import) the helper class.
- PyRun_SimpleString("import myApp") ; // Import the shadow class.
-
-5. There are two problems with Python's C API which will become apparent
- if you use a compiler other than MSVC, the compiler used to build
- pythonNN.dll.
-
- Problem 1: The so-called "Very High Level" functions that take FILE *
- arguments will not work in a multi-compiler environment because each compiler's
- notion of a struct FILE will be different. From an implementation
- standpoint these are very _low_ level functions.
-
- Problem 2: SWIG generates the following code when generating wrappers to
- void functions::
-
- Py_INCREF(Py_None);
- _resultobj = Py_None;
- return _resultobj;
-
- Alas, Py_None is a macro that expands to a reference to a complex data
- structure called _Py_NoneStruct inside pythonNN.dll. Again, this code
- will fail in a mult-compiler environment. Replace such code by::
-
- return Py_BuildValue("");
-
- It may be possible to use SWIG's %typemap command to make the change
- automatically, though I have not been able to get this to work (I'm a
- complete SWIG newbie).
-
-6. Using a Python shell script to put up a Python interpreter window
- from inside your Windows app is not a good idea; the resulting window
- will be independent of your app's windowing system. Rather, you (or the
- wxPythonWindow class) should create a "native" interpreter window. It
- is easy to connect that window to the Python interpreter. You can
- redirect Python's i/o to _any_ object that supports read and write, so
- all you need is a Python object (defined in your extension module) that
- contains read() and write() methods.
-
-How do I use Python for CGI?
--------------------------------------------------------
-
-On the Microsoft IIS server or on the Win95 MS Personal Web Server you
-set up Python in the same way that you would set up any other
-scripting engine.
-
-Run regedt32 and go to::
-
- HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap
-
-and enter the following line (making any specific changes that your system may need)::
-
- .py :REG_SZ: c:\<path to python>\python.exe -u %s %s
-
-This line will allow you to call your script with a simple reference like:
-http://yourserver/scripts/yourscript.py
-provided "scripts" is an "executable" directory for your server (which
-it usually is by default).
-The "-u" flag specifies unbuffered and binary mode for stdin - needed when working with binary data.
-
-In addition, it is recommended that using
-".py" may not be a good idea for the file extensions when used in this
-context (you might want to reserve ``*.py`` for support modules and
-use ``*.cgi`` or ``*.cgp`` for "main program" scripts).
-
-In order to set up Internet Information Services 5 to use Python for CGI processing, please see the following links:
-
- http://www.e-coli.net/pyiis_server.html (for Win2k Server)
- http://www.e-coli.net/pyiis.html (for Win2k pro)
-
-Configuring Apache is much simpler.
-In the Apache configuration file ``httpd.conf``, add the following line at
-the end of the file::
-
- ScriptInterpreterSource Registry
-
-Then, give your Python CGI-scripts the extension .py and put them in the cgi-bin directory.
-
-
-How do I keep editors from inserting tabs into my Python source?
-------------------------------------------------------------------
-
-The FAQ does not recommend using tabs, and `the Python style guide <http://www.python.org/peps/pep-0008.html>`_
-recommends 4 spaces for distributed Python code; this is also the
-Emacs python-mode default.
-
-Under any editor, mixing tabs and spaces is a bad idea. MSVC is no
-different in this respect, and is easily configured to use spaces:
-Take Tools -> Options -> Tabs, and for file type "Default" set "Tab
-size" and "Indent size" to 4, and select the "Insert spaces" radio
-button.
-
-If you suspect mixed tabs and spaces are causing problems in leading
-whitespace, run Python with the -t switch or run
-``Tools/Scripts/tabnanny.py`` to check a directory tree in batch mode.
-
-
-How do I check for a keypress without blocking?
-----------------------------------------------------
-
-Use the msvcrt module. This is a standard Windows-specific extension
-module. It defines a function kbhit() which checks whether a keyboard
-hit is present, and getch() which gets one character without echoing
-it.
-
-
-How do I emulate os.kill() in Windows?
----------------------------------------------
-Use win32api::
-
- def kill(pid):
- """kill function for Win32"""
- import win32api
- handle = win32api.OpenProcess(1, 0, pid)
- return (0 != win32api.TerminateProcess(handle, 0))
-
-
-Why does os.path.isdir() fail on NT shared directories?
---------------------------------------------------------------
-The solution appears to be always append the "\\" on
-the end of shared drives. ::
-
- >>> import os
- >>> os.path.isdir( '\\\\rorschach\\public')
- 0
- >>> os.path.isdir( '\\\\rorschach\\public\\')
- 1
-
-It helps to think of share points as being like drive letters.
-Example::
-
- k: is not a directory
- k:\ is a directory
- k:\media is a directory
- k:\media\ is not a directory
-
-The same rules apply if you substitute "k:" with "\\conky\foo"::
-
- \\conky\foo is not a directory
- \\conky\foo\ is a directory
- \\conky\foo\media is a directory
- \\conky\foo\media\ is not a directory
-
-
-cgi.py (or other CGI programming) doesn't work sometimes on NT or win95!
------------------------------------------------------------------------------
-Be sure you have the latest python.exe, that you are using
-python.exe rather than a GUI version of Python and that you
-have configured the server to execute ::
-
- "...\python.exe -u ..."
-
-for the CGI execution. The -u (unbuffered) option on NT and
-Win95 prevents the interpreter from altering newlines in the
-standard input and output. Without it post/multipart requests
-will seem to have the wrong length and binary (e.g. GIF)
-responses may get garbled (resulting in broken images, PDF files,
-and other binary downloads failing).
-
-Why doesn't os.popen() work in PythonWin on NT?
--------------------------------------------------------
-
-The reason that os.popen() doesn't work from within PythonWin is due
-to a bug in Microsoft's C Runtime Library (CRT). The CRT assumes you
-have a Win32 console attached to the process.
-
-You should use the win32pipe module's popen() instead which doesn't
-depend on having an attached Win32 console.
-
-Example::
-
- import win32pipe
- f = win32pipe.popen('dir /c c:\\')
- print f.readlines()
- f.close()
-
-
-Why doesn't os.popen()/win32pipe.popen() work on Win9x?
----------------------------------------------------------------
-
-There is a bug in Win9x that prevents os.popen/win32pipe.popen* from
-working. The good news is there is a way to work around this problem.
-The Microsoft Knowledge Base article that you need to lookup is:
-Q150956. You will find links to the knowledge base at:
-http://www.microsoft.com/kb.
-
-
-PyRun_SimpleFile() crashes on Windows but not on Unix; why?
-------------------------------------------------------------
-
-This is very sensitive to the compiler vendor, version and (perhaps)
-even options. If the FILE* structure in your embedding program isn't
-the same as is assumed by the Python interpreter it won't work.
-
-The Python 1.5.* DLLs (``python15.dll``) are all compiled
-with MS VC++ 5.0 and with multithreading-DLL options (``/MD``).
-
-If you can't change compilers or flags, try using Py_RunSimpleString().
-A trick to get it to run an arbitrary file is to construct a call to
-execfile() with the name of your file as argument.
-
-Also note that you can not mix-and-match Debug and Release versions. If you
-wish to use the Debug Multithreaded DLL, then your module _must_ have an
-"_d" appended to the base name.
-
-
-Importing _tkinter fails on Windows 95/98: why?
-------------------------------------------------
-Sometimes, the import of _tkinter fails on Windows 95 or 98,
-complaining with a message like the following::
-
- ImportError: DLL load failed: One of the library files needed
- to run this application cannot be found.
-
-It could be that you haven't installed Tcl/Tk, but if you did
-install Tcl/Tk, and the Wish application works correctly,
-the problem may be that its installer didn't
-manage to edit the autoexec.bat file correctly. It tries to add a
-statement that changes the PATH environment variable to include
-the Tcl/Tk 'bin' subdirectory, but sometimes this edit doesn't
-quite work. Opening it with notepad usually reveals what the
-problem is.
-
-(One additional hint, noted by David Szafranski: you can't use
-long filenames here; e.g. use ``C:\PROGRA~1\Tcl\bin`` instead of
-``C:\Program Files\Tcl\bin``.)
-
-How do I extract the downloaded documentation on Windows?
-------------------------------------------------------------
-Sometimes, when you download the documentation package to a Windows
-machine using a web browser, the file extension of the saved file
-ends up being .EXE. This is a mistake; the extension should be .TGZ.
-
-Simply rename the downloaded file to have the .TGZ extension, and
-WinZip will be able to handle it. (If your copy of WinZip doesn't,
-get a newer one from http://www.winzip.com.)
-
-Missing cw3215mt.dll (or missing cw3215.dll)
-----------------------------------------------------
-Sometimes, when using Tkinter on Windows, you get an error that
-cw3215mt.dll or cw3215.dll is missing.
-
-Cause: you have an old Tcl/Tk DLL built with cygwin in your path
-(probably ``C:\Windows``). You must use the Tcl/Tk DLLs from the
-standard Tcl/Tk installation (Python 1.5.2 comes with one).
-
-Warning about CTL3D32 version from installer
-----------------------------------------------------
-The Python installer issues a warning like this::
-
- This version uses ``CTL3D32.DLL`` whitch is not the correct version.
- This version is used for windows NT applications only.
-
-[Tim Peters]
-This is a Microsoft DLL, and a notorious
-source of problems. The message means what it says: you have the wrong version
-of this DLL for your operating system. The Python installation did not
-cause this -- something else you installed previous to this overwrote the
-DLL that came with your OS (probably older shareware of some sort, but
-there's no way to tell now). If you search for "CTL3D32" using any search
-engine (AltaVista, for example), you'll find hundreds and hundreds of web
-pages complaining about the same problem with all sorts of installation
-programs. They'll point you to ways to get the correct version reinstalled
-on your system (since Python doesn't cause this, we can't fix it).
-
-David A Burton has written a little program to fix this. Go to
-http://www.burtonsys.com/download.html and click on "ctl3dfix.zip"
diff --git a/faq/windows.html b/faq/windows.html
deleted file mode 100644
index 58849b2..0000000
--- a/faq/windows.html
+++ /dev/null
@@ -1,912 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
-<title>Python Windows FAQ</title>
-<meta name="date" content="2005-07-26" />
-<style type="text/css">
-
-/*
-:Author: David Goodger (goodger@python.org)
-:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
- border: 0 }
-
-table.borderless td, table.borderless th {
- /* Override padding for "table.docutils td" with "! important".
- The right padding separates the table cells. */
- padding: 0 0.5em 0 0 ! important }
-
-.first {
- /* Override more specific margin styles with "! important". */
- margin-top: 0 ! important }
-
-.last, .with-subtitle {
- margin-bottom: 0 ! important }
-
-.hidden {
- display: none }
-
-a.toc-backref {
- text-decoration: none ;
- color: black }
-
-blockquote.epigraph {
- margin: 2em 5em ; }
-
-dl.docutils dd {
- margin-bottom: 0.5em }
-
-object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
- overflow: hidden;
-}
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
- font-weight: bold }
-*/
-
-div.abstract {
- margin: 2em 5em }
-
-div.abstract p.topic-title {
- font-weight: bold ;
- text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
- margin: 2em ;
- border: medium outset ;
- padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title, .code .error {
- color: red ;
- font-weight: bold ;
- font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
- compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
- margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
- margin-top: 0.5em }
-*/
-
-div.dedication {
- margin: 2em 5em ;
- text-align: center ;
- font-style: italic }
-
-div.dedication p.topic-title {
- font-weight: bold ;
- font-style: normal }
-
-div.figure {
- margin-left: 2em ;
- margin-right: 2em }
-
-div.footer, div.header {
- clear: both;
- font-size: smaller }
-
-div.line-block {
- display: block ;
- margin-top: 1em ;
- margin-bottom: 1em }
-
-div.line-block div.line-block {
- margin-top: 0 ;
- margin-bottom: 0 ;
- margin-left: 1.5em }
-
-div.sidebar {
- margin: 0 0 0.5em 1em ;
- border: medium outset ;
- padding: 1em ;
- background-color: #ffffee ;
- width: 40% ;
- float: right ;
- clear: right }
-
-div.sidebar p.rubric {
- font-family: sans-serif ;
- font-size: medium }
-
-div.system-messages {
- margin: 5em }
-
-div.system-messages h1 {
- color: red }
-
-div.system-message {
- border: medium outset ;
- padding: 1em }
-
-div.system-message p.system-message-title {
- color: red ;
- font-weight: bold }
-
-div.topic {
- margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
- margin-top: 0.4em }
-
-h1.title {
- text-align: center }
-
-h2.subtitle {
- text-align: center }
-
-hr.docutils {
- width: 75% }
-
-img.align-left, .figure.align-left, object.align-left {
- clear: left ;
- float: left ;
- margin-right: 1em }
-
-img.align-right, .figure.align-right, object.align-right {
- clear: right ;
- float: right ;
- margin-left: 1em }
-
-img.align-center, .figure.align-center, object.align-center {
- display: block;
- margin-left: auto;
- margin-right: auto;
-}
-
-.align-left {
- text-align: left }
-
-.align-center {
- clear: both ;
- text-align: center }
-
-.align-right {
- text-align: right }
-
-/* reset inner alignment in figures */
-div.align-right {
- text-align: inherit }
-
-/* div.align-center * { */
-/* text-align: left } */
-
-ol.simple, ul.simple {
- margin-bottom: 1em }
-
-ol.arabic {
- list-style: decimal }
-
-ol.loweralpha {
- list-style: lower-alpha }
-
-ol.upperalpha {
- list-style: upper-alpha }
-
-ol.lowerroman {
- list-style: lower-roman }
-
-ol.upperroman {
- list-style: upper-roman }
-
-p.attribution {
- text-align: right ;
- margin-left: 50% }
-
-p.caption {
- font-style: italic }
-
-p.credits {
- font-style: italic ;
- font-size: smaller }
-
-p.label {
- white-space: nowrap }
-
-p.rubric {
- font-weight: bold ;
- font-size: larger ;
- color: maroon ;
- text-align: center }
-
-p.sidebar-title {
- font-family: sans-serif ;
- font-weight: bold ;
- font-size: larger }
-
-p.sidebar-subtitle {
- font-family: sans-serif ;
- font-weight: bold }
-
-p.topic-title {
- font-weight: bold }
-
-pre.address {
- margin-bottom: 0 ;
- margin-top: 0 ;
- font: inherit }
-
-pre.literal-block, pre.doctest-block, pre.math, pre.code {
- margin-left: 2em ;
- margin-right: 2em }
-
-pre.code .ln { color: grey; } /* line numbers */
-pre.code, code { background-color: #eeeeee }
-pre.code .comment, code .comment { color: #5C6576 }
-pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
-pre.code .literal.string, code .literal.string { color: #0C5404 }
-pre.code .name.builtin, code .name.builtin { color: #352B84 }
-pre.code .deleted, code .deleted { background-color: #DEB0A1}
-pre.code .inserted, code .inserted { background-color: #A3D289}
-
-span.classifier {
- font-family: sans-serif ;
- font-style: oblique }
-
-span.classifier-delimiter {
- font-family: sans-serif ;
- font-weight: bold }
-
-span.interpreted {
- font-family: sans-serif }
-
-span.option {
- white-space: nowrap }
-
-span.pre {
- white-space: pre }
-
-span.problematic {
- color: red }
-
-span.section-subtitle {
- /* font-size relative to parent (h1..h6 element) */
- font-size: 80% }
-
-table.citation {
- border-left: solid 1px gray;
- margin-left: 1px }
-
-table.docinfo {
- margin: 2em 4em }
-
-table.docutils {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
-
-table.footnote {
- border-left: solid 1px black;
- margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
- padding-left: 0.5em ;
- padding-right: 0.5em ;
- vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
- font-weight: bold ;
- text-align: left ;
- white-space: nowrap ;
- padding-left: 0 }
-
-/* "booktabs" style (no vertical lines) */
-table.docutils.booktabs {
- border: 0px;
- border-top: 2px solid;
- border-bottom: 2px solid;
- border-collapse: collapse;
-}
-table.docutils.booktabs * {
- border: 0px;
-}
-table.docutils.booktabs th {
- border-bottom: thin solid;
- text-align: left;
-}
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
- font-size: 100% }
-
-ul.auto-toc {
- list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="python-windows-faq">
-<h1 class="title">Python Windows FAQ</h1>
-<table class="docinfo" frame="void" rules="none">
-<col class="docinfo-name" />
-<col class="docinfo-content" />
-<tbody valign="top">
-<tr><th class="docinfo-name">Date:</th>
-<td>2005-07-26</td></tr>
-<tr><th class="docinfo-name">Version:</th>
-<td>8295</td></tr>
-<tr class="field"><th class="docinfo-name">Web site:</th><td class="field-body"><a class="reference external" href="http://www.python.org/">http://www.python.org/</a></td>
-</tr>
-</tbody>
-</table>
-<div class="contents topic" id="contents">
-<p class="topic-title first">Contents</p>
-<ul class="auto-toc simple">
-<li><a class="reference internal" href="#how-do-i-run-a-python-program-under-windows" id="id1">1 How do I run a Python program under Windows?</a></li>
-<li><a class="reference internal" href="#how-do-i-make-python-scripts-executable" id="id2">2 How do I make python scripts executable?</a></li>
-<li><a class="reference internal" href="#why-does-python-sometimes-take-so-long-to-start" id="id3">3 Why does Python sometimes take so long to start?</a></li>
-<li><a class="reference internal" href="#where-is-freeze-for-windows" id="id4">4 Where is Freeze for Windows?</a></li>
-<li><a class="reference internal" href="#is-a-pyd-file-the-same-as-a-dll" id="id5">5 Is a <tt class="docutils literal">*.pyd</tt> file the same as a DLL?</a></li>
-<li><a class="reference internal" href="#how-can-i-embed-python-into-a-windows-application" id="id6">6 How can I embed Python into a Windows application?</a></li>
-<li><a class="reference internal" href="#how-do-i-use-python-for-cgi" id="id7">7 How do I use Python for CGI?</a></li>
-<li><a class="reference internal" href="#how-do-i-keep-editors-from-inserting-tabs-into-my-python-source" id="id8">8 How do I keep editors from inserting tabs into my Python source?</a></li>
-<li><a class="reference internal" href="#how-do-i-check-for-a-keypress-without-blocking" id="id9">9 How do I check for a keypress without blocking?</a></li>
-<li><a class="reference internal" href="#how-do-i-emulate-os-kill-in-windows" id="id10">10 How do I emulate os.kill() in Windows?</a></li>
-<li><a class="reference internal" href="#why-does-os-path-isdir-fail-on-nt-shared-directories" id="id11">11 Why does os.path.isdir() fail on NT shared directories?</a></li>
-<li><a class="reference internal" href="#cgi-py-or-other-cgi-programming-doesn-t-work-sometimes-on-nt-or-win95" id="id12">12 cgi.py (or other CGI programming) doesn't work sometimes on NT or win95!</a></li>
-<li><a class="reference internal" href="#why-doesn-t-os-popen-work-in-pythonwin-on-nt" id="id13">13 Why doesn't os.popen() work in PythonWin on NT?</a></li>
-<li><a class="reference internal" href="#why-doesn-t-os-popen-win32pipe-popen-work-on-win9x" id="id14">14 Why doesn't os.popen()/win32pipe.popen() work on Win9x?</a></li>
-<li><a class="reference internal" href="#pyrun-simplefile-crashes-on-windows-but-not-on-unix-why" id="id15">15 PyRun_SimpleFile() crashes on Windows but not on Unix; why?</a></li>
-<li><a class="reference internal" href="#importing-tkinter-fails-on-windows-95-98-why" id="id16">16 Importing _tkinter fails on Windows 95/98: why?</a></li>
-<li><a class="reference internal" href="#how-do-i-extract-the-downloaded-documentation-on-windows" id="id17">17 How do I extract the downloaded documentation on Windows?</a></li>
-<li><a class="reference internal" href="#missing-cw3215mt-dll-or-missing-cw3215-dll" id="id18">18 Missing cw3215mt.dll (or missing cw3215.dll)</a></li>
-<li><a class="reference internal" href="#warning-about-ctl3d32-version-from-installer" id="id19">19 Warning about CTL3D32 version from installer</a></li>
-</ul>
-</div>
-<div class="section" id="how-do-i-run-a-python-program-under-windows">
-<h1><a class="toc-backref" href="#id1">1 How do I run a Python program under Windows?</a></h1>
-<p>This is not necessarily a straightforward question. If you are already
-familiar with running programs from the Windows command line then
-everything will seem obvious; otherwise, you might need a little more
-guidance. There are also differences between Windows 95, 98, NT, ME,
-2000 and XP which can add to the confusion.</p>
-<p>Unless you use some sort of integrated development environment,
-you will end up <em>typing</em> Windows commands into what is variously referred
-to as a "DOS window" or "Command prompt window". Usually you can
-create such a window from your Start menu; under Windows 2000
-the menu selection is
-"Start | Programs | Accessories | Command Prompt". You should be
-able to recognize when you have started such a window because you will
-see a Windows "command prompt", which usually looks like this:</p>
-<pre class="literal-block">
-C:\>
-</pre>
-<p>The letter may be different, and there might be other things after it,
-so you might just as easily see something like:</p>
-<pre class="literal-block">
-D:\Steve\Projects\Python>
-</pre>
-<p>depending on how your computer has been set up and what else you have
-recently done with it. Once you have started such a window, you are
-well on the way to running Python programs.</p>
-<p>You need to realize that your Python scripts have to be processed by
-another program called the Python interpreter. The
-interpreter reads your script, compiles it into bytecodes, and then executes the bytecodes to run your
-program. So, how do you arrange for the interpreter to handle your
-Python?</p>
-<p>First, you need to make sure that your command window recognises the
-word "python" as an instruction to start the interpreter. If you have
-opened a command window, you should try entering the command <tt class="docutils literal">python</tt>
-and hitting return. You should then see something like:</p>
-<pre class="literal-block">
-Python 2.2 (#28, Dec 21 2001, 12:21:22) [MSC 32 bit (Intel)] on win32
-Type "help", "copyright", "credits" or "license" for more information.
->>>
-</pre>
-<p>You have started the interpreter in "interactive mode". That means you
-can enter Python statements or expressions interactively and have them
-executed or evaluated while you wait. This is one of Python's
-strongest features. Check it by entering a few expressions of your
-choice and seeing the results:</p>
-<pre class="literal-block">
->>> print "Hello"
-Hello
->>> "Hello" * 3
-HelloHelloHello
-</pre>
-<p>Many people use the interactive mode as a convenient yet highly
-programmable calculator.
-When you want to end your interactive Python session, hold the Ctrl
-key down while you enter a Z, then hit the "Enter" key to get back to
-your Windows command prompt.</p>
-<p>You may also find that you have a
-Start-menu entry such as "Start | Programs | Python 2.2 | Python
-(command line)" that results in you seeing the <tt class="docutils literal">>>></tt> prompt in a new
-window. If so, the window will disappear after you enter the
-Ctrl-Z character; Windows is running a single "python" command in the window,
-and closes it when you terminate the interpreter.</p>
-<p>If the <tt class="docutils literal">python</tt> command, instead of displaying the interpreter
-prompt <tt class="docutils literal">>>></tt>, gives you a message like:</p>
-<pre class="literal-block">
-'python' is not recognized as an internal or external command,
-operable program or batch file.
-</pre>
-<p>or:</p>
-<pre class="literal-block">
-Bad command or filename
-</pre>
-<p>then you need to make sure that your computer knows where to find the
-Python interpreter. To do this you will have to modify a setting
-called PATH, which is a list of directories where Windows
-will look for programs. You should arrange for Python's
-installation directory to be added to the PATH of every command window
-as it starts. If you installed Python fairly recently then the command</p>
-<pre class="literal-block">
-dir C:\py*
-</pre>
-<p>will probably tell you where it is installed; the usual location is
-something like <tt class="docutils literal"><span class="pre">C:\Python23</span></tt>. Otherwise you will be reduced to a search of your
-whole disk ... use "Tools | Find"
-or hit the "Search" button and look for "python.exe". Supposing you
-discover that Python is installed in the <tt class="docutils literal"><span class="pre">C:\Python23</span></tt> directory (the
-default at the time of writing), you should make sure that
-entering the command</p>
-<pre class="literal-block">
-c:\Python23\python
-</pre>
-<p>starts up the interpreter as above (and don't forget you'll need a
-"CTRL-Z" and an "Enter" to get out of it). Once you have verified the
-directory, you need to add it to the start-up routines your computer
-goes through. For older versions of Windows the easiest way to do
-this is to edit the <tt class="docutils literal"><span class="pre">C:\AUTOEXEC.BAT</span></tt> file. You would want to add a line
-like the following to <tt class="docutils literal">AUTOEXEC.BAT</tt>:</p>
-<pre class="literal-block">
-PATH C:\Python23;%PATH%
-</pre>
-<p>For Windows NT, 2000 and (I assume) XP, you will need to add a string
-such as</p>
-<pre class="literal-block">
-;C:\Python23
-</pre>
-<p>to the current setting for the PATH environment variable, which you
-will find in the properties window of "My Computer" under the
-"Advanced" tab. Note that if you have sufficient privilege you might
-get a choice of installing the settings either for the Current User or
-for System. The latter is preferred if you want everybody to be able
-to run Python on the machine.</p>
-<p>If you aren't confident doing any of these manipulations yourself, ask
-for help! At this stage you may want to reboot your system
-to make absolutely sure the new setting has taken effect. You probably
-won't need to reboot for Windows NT, XP or 2000. You can also avoid it in
-earlier versions by editing the file <tt class="docutils literal"><span class="pre">C:\WINDOWS\COMMAND\CMDINIT.BAT</span></tt>
-instead of <tt class="docutils literal">AUTOEXEC.BAT</tt>.</p>
-<p>You should now be able to start a new command window, enter <tt class="docutils literal">python</tt>
-at the <tt class="docutils literal">C:></tt> (or whatever) prompt, and see the <tt class="docutils literal">>>></tt> prompt that
-indicates the Python interpreter is reading interactive commands.</p>
-<p>Let's suppose you have a program called <tt class="docutils literal">pytest.py</tt> in directory
-<tt class="docutils literal"><span class="pre">C:\Steve\Projects\Python</span></tt>. A session to run that program might look
-like this:</p>
-<pre class="literal-block">
-C:\> cd \Steve\Projects\Python
-C:\Steve\Projects\Python> python pytest.py
-</pre>
-<p>Because you added a file name to the command to start the interpreter,
-when it starts up it reads the Python script in the named file,
-compiles it, executes it, and terminates, so you see another <tt class="docutils literal"><span class="pre">C:\></span></tt>
-prompt. You might also have entered</p>
-<pre class="literal-block">
-C:\> python \Steve\Projects\Python\pytest.py
-</pre>
-<p>if you hadn't wanted to change your current directory.</p>
-<p>Under NT, 2000 and XP you may well find that the installation process
-has also arranged that the command <tt class="docutils literal">pytest.py</tt>
-(or, if the file isn't in the current directory,
-<tt class="docutils literal"><span class="pre">C:\Steve\Projects\Python\pytest.py</span></tt>)
-will automatically recognize the ".py" extension and run the Python
-interpreter on the named file. Using this feature is fine, but <em>some</em>
-versions of Windows have bugs which mean that this form isn't exactly
-equivalent to using the interpreter explicitly, so be careful.</p>
-<p>The important things to remember are:</p>
-<ol class="arabic">
-<li><p class="first">Start Python from the Start Menu, or make sure the PATH is set
-correctly so Windows can find the Python interpreter.</p>
-<pre class="literal-block">
-python
-</pre>
-<p>should give you a '>>>" prompt from the Python interpreter. Don't
-forget the CTRL-Z and ENTER to terminate the interpreter (and, if you
-started the window from the Start Menu, make the window disappear).</p>
-</li>
-<li><p class="first">Once this works, you run programs with commands:</p>
-<pre class="literal-block">
-python {program-file}
-</pre>
-</li>
-<li><p class="first">When you know the commands to use you can build Windows shortcuts
-to run the Python interpreter on any of your scripts, naming
-particular working directories, and adding them to your menus.
-Take a look at</p>
-<pre class="literal-block">
-python --help
-</pre>
-<p>if your needs are complex.</p>
-</li>
-<li><p class="first">Interactive mode (where you see the <tt class="docutils literal">>>></tt> prompt) is best used
-for checking that individual statements and expressions do
-what you think they will, and for developing code by experiment.</p>
-</li>
-</ol>
-</div>
-<div class="section" id="how-do-i-make-python-scripts-executable">
-<h1><a class="toc-backref" href="#id2">2 How do I make python scripts executable?</a></h1>
-<p>On Windows 2000, the standard Python installer already associates the
-.py extension with a file type (Python.File) and gives that file type
-an open command that runs the interpreter (D:\Program
-Files\Python\python.exe "%1" %*). This is enough to make scripts
-executable from the command prompt as 'foo.py'. If you'd rather be
-able to execute the script by simple typing 'foo' with no extension
-you need to add .py to the PATHEXT environment variable.</p>
-<p>On Windows NT, the steps taken by the installer as described above
-allow you to run a script with 'foo.py', but a longtime bug in the NT
-command processor prevents you from redirecting the input or output of
-any script executed in this way. This is often important.</p>
-<p>The incantation for making a Python script executable under WinNT
-is to give the file an extension of .cmd and add the following as the first
-line:</p>
-<pre class="literal-block">
-@setlocal enableextensions & python -x %~f0 %* & goto :EOF
-</pre>
-</div>
-<div class="section" id="why-does-python-sometimes-take-so-long-to-start">
-<h1><a class="toc-backref" href="#id3">3 Why does Python sometimes take so long to start?</a></h1>
-<p>Usually Python starts very quickly on Windows, but occasionally there
-are bug reports that Python suddenly begins to take a long time to
-start up. This is made even more puzzling because Python will work fine
-on other Windows systems which appear to be configured identically.</p>
-<p>The problem may be caused by a misconfiguration of virus checking
-software on the problem machine. Some virus scanners have been known
-to introduce startup overhead of two orders of magnitude when the
-scanner is configured to monitor all reads from the filesystem. Try
-checking the configuration of virus scanning software on your systems
-to ensure that they are indeed configured identically. McAfee, when
-configured to scan all file system read activity, is a particular
-offender.</p>
-</div>
-<div class="section" id="where-is-freeze-for-windows">
-<h1><a class="toc-backref" href="#id4">4 Where is Freeze for Windows?</a></h1>
-<p>"Freeze" is a program that allows you to ship a Python program
-as a single stand-alone executable file. It is <em>not</em> a compiler;
-your programs don't run any faster, but they are more easily
-distributable, at least to platforms with the same OS and CPU. Read the
-README file of the freeze program for more disclaimers.</p>
-<p>You can use freeze on Windows, but you must download the source
-tree (see <a class="reference external" href="http://www.python.org/download/download_source.html">http://www.python.org/download/download_source.html</a>).
-The freeze program is in the <tt class="docutils literal">Tools\freeze</tt> subdirectory of the source
-tree.</p>
-<p>You need the Microsoft VC++ compiler, and you probably need to build
-Python. The required project files are in the PCbuild directory.</p>
-</div>
-<div class="section" id="is-a-pyd-file-the-same-as-a-dll">
-<h1><a class="toc-backref" href="#id5">5 Is a <tt class="docutils literal">*.pyd</tt> file the same as a DLL?</a></h1>
-<p>Yes, .pyd files are dll's, but there are a few differences. If you
-have a DLL named <tt class="docutils literal">foo.pyd</tt>, then it must have a function initfoo(). You
-can then write Python "import foo", and Python will search for foo.pyd
-(as well as foo.py, foo.pyc) and if it finds it, will attempt to call
-initfoo() to initialize it. You do not link your .exe with foo.lib,
-as that would cause Windows to require the DLL to be present.</p>
-<p>Note that the search path for foo.pyd is PYTHONPATH, not the same as
-the path that Windows uses to search for foo.dll. Also, foo.pyd need
-not be present to run your program, whereas if you linked your program
-with a dll, the dll is required. Of course, foo.pyd is required if
-you want to say "import foo". In a DLL, linkage is declared in the
-source code with __declspec(dllexport). In a .pyd, linkage is defined
-in a list of available functions.</p>
-</div>
-<div class="section" id="how-can-i-embed-python-into-a-windows-application">
-<h1><a class="toc-backref" href="#id6">6 How can I embed Python into a Windows application?</a></h1>
-<p>Embedding the Python interpreter in a Windows app can be summarized as
-follows:</p>
-<ol class="arabic">
-<li><p class="first">Do _not_ build Python into your .exe file directly. On Windows,
-Python must be a DLL to handle importing modules that are themselves
-DLL's. (This is the first key undocumented fact.) Instead, link to
-pythonNN.dll; it is typically installed in <tt class="docutils literal"><span class="pre">C:\Windows\System</span></tt>.
-NN is the Python version, a number such as "23" for Python 2.3.</p>
-<p>You can link to Python statically or dynamically. Linking
-statically means linking against pythonNN.lib, while dynamically
-linking means linking against pythonNN.dll. The drawback to
-dynamic linking is that your app won't run if pythonNN.dll does not
-exist on your system.
-(General note: pythonNN.lib is the so-called "import lib" corresponding
-to python.dll. It merely defines symbols for the linker.)</p>
-<p>Linking dynamically greatly simplifies link options; everything happens
-at run time. Your code must load pythonNN.dll using the Windows
-LoadLibraryEx() routine. The code must also use access routines and
-data in pythonNN.dll (that is, Python's C API's) using pointers
-obtained by the Windows GetProcAddress() routine. Macros can make
-using these pointers transparent to any C code that calls routines in
-Python's C API.</p>
-<p>Borland note: convert pythonNN.lib to OMF format using Coff2Omf.exe
-first.</p>
-</li>
-<li><p class="first">If you use SWIG, it is easy to create a Python "extension module"
-that will make the app's data and methods available to Python. SWIG
-will handle just about all the grungy details for you. The result is C
-code that you link <em>into</em> your .exe file (!) You do _not_ have to
-create a DLL file, and this also simplifies linking.</p>
-</li>
-<li><p class="first">SWIG will create an init function (a C function) whose name depends
-on the name of the extension module. For example, if the name of the
-module is leo, the init function will be called initleo(). If you use
-SWIG shadow classes, as you should, the init function will be called
-initleoc(). This initializes a mostly hidden helper class used by the
-shadow class.</p>
-<p>The reason you can link the C code in step 2 into your .exe file is that
-calling the initialization function is equivalent to importing the
-module into Python! (This is the second key undocumented fact.)</p>
-</li>
-<li><p class="first">In short, you can use the following code to initialize the Python
-interpreter with your extension module.</p>
-<pre class="literal-block">
-#include "python.h"
-...
-Py_Initialize(); // Initialize Python.
-initmyAppc(); // Initialize (import) the helper class.
-PyRun_SimpleString("import myApp") ; // Import the shadow class.
-</pre>
-</li>
-<li><p class="first">There are two problems with Python's C API which will become apparent
-if you use a compiler other than MSVC, the compiler used to build
-pythonNN.dll.</p>
-<p>Problem 1: The so-called "Very High Level" functions that take FILE *
-arguments will not work in a multi-compiler environment because each compiler's
-notion of a struct FILE will be different. From an implementation
-standpoint these are very _low_ level functions.</p>
-<p>Problem 2: SWIG generates the following code when generating wrappers to
-void functions:</p>
-<pre class="literal-block">
-Py_INCREF(Py_None);
-_resultobj = Py_None;
-return _resultobj;
-</pre>
-<p>Alas, Py_None is a macro that expands to a reference to a complex data
-structure called _Py_NoneStruct inside pythonNN.dll. Again, this code
-will fail in a mult-compiler environment. Replace such code by:</p>
-<pre class="literal-block">
-return Py_BuildValue("");
-</pre>
-<p>It may be possible to use SWIG's %typemap command to make the change
-automatically, though I have not been able to get this to work (I'm a
-complete SWIG newbie).</p>
-</li>
-<li><p class="first">Using a Python shell script to put up a Python interpreter window
-from inside your Windows app is not a good idea; the resulting window
-will be independent of your app's windowing system. Rather, you (or the
-wxPythonWindow class) should create a "native" interpreter window. It
-is easy to connect that window to the Python interpreter. You can
-redirect Python's i/o to _any_ object that supports read and write, so
-all you need is a Python object (defined in your extension module) that
-contains read() and write() methods.</p>
-</li>
-</ol>
-</div>
-<div class="section" id="how-do-i-use-python-for-cgi">
-<h1><a class="toc-backref" href="#id7">7 How do I use Python for CGI?</a></h1>
-<p>On the Microsoft IIS server or on the Win95 MS Personal Web Server you
-set up Python in the same way that you would set up any other
-scripting engine.</p>
-<p>Run regedt32 and go to:</p>
-<pre class="literal-block">
-HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap
-</pre>
-<p>and enter the following line (making any specific changes that your system may need):</p>
-<pre class="literal-block">
-.py :REG_SZ: c:\<path to python>\python.exe -u %s %s
-</pre>
-<p>This line will allow you to call your script with a simple reference like:
-<a class="reference external" href="http://yourserver/scripts/yourscript.py">http://yourserver/scripts/yourscript.py</a>
-provided "scripts" is an "executable" directory for your server (which
-it usually is by default).
-The "-u" flag specifies unbuffered and binary mode for stdin - needed when working with binary data.</p>
-<p>In addition, it is recommended that using
-".py" may not be a good idea for the file extensions when used in this
-context (you might want to reserve <tt class="docutils literal">*.py</tt> for support modules and
-use <tt class="docutils literal">*.cgi</tt> or <tt class="docutils literal">*.cgp</tt> for "main program" scripts).</p>
-<p>In order to set up Internet Information Services 5 to use Python for CGI processing, please see the following links:</p>
-<blockquote>
-<a class="reference external" href="http://www.e-coli.net/pyiis_server.html">http://www.e-coli.net/pyiis_server.html</a> (for Win2k Server)
-<a class="reference external" href="http://www.e-coli.net/pyiis.html">http://www.e-coli.net/pyiis.html</a> (for Win2k pro)</blockquote>
-<p>Configuring Apache is much simpler.
-In the Apache configuration file <tt class="docutils literal">httpd.conf</tt>, add the following line at
-the end of the file:</p>
-<pre class="literal-block">
-ScriptInterpreterSource Registry
-</pre>
-<p>Then, give your Python CGI-scripts the extension .py and put them in the cgi-bin directory.</p>
-</div>
-<div class="section" id="how-do-i-keep-editors-from-inserting-tabs-into-my-python-source">
-<h1><a class="toc-backref" href="#id8">8 How do I keep editors from inserting tabs into my Python source?</a></h1>
-<p>The FAQ does not recommend using tabs, and <a class="reference external" href="http://www.python.org/peps/pep-0008.html">the Python style guide</a>
-recommends 4 spaces for distributed Python code; this is also the
-Emacs python-mode default.</p>
-<p>Under any editor, mixing tabs and spaces is a bad idea. MSVC is no
-different in this respect, and is easily configured to use spaces:
-Take Tools -> Options -> Tabs, and for file type "Default" set "Tab
-size" and "Indent size" to 4, and select the "Insert spaces" radio
-button.</p>
-<p>If you suspect mixed tabs and spaces are causing problems in leading
-whitespace, run Python with the -t switch or run
-<tt class="docutils literal">Tools/Scripts/tabnanny.py</tt> to check a directory tree in batch mode.</p>
-</div>
-<div class="section" id="how-do-i-check-for-a-keypress-without-blocking">
-<h1><a class="toc-backref" href="#id9">9 How do I check for a keypress without blocking?</a></h1>
-<p>Use the msvcrt module. This is a standard Windows-specific extension
-module. It defines a function kbhit() which checks whether a keyboard
-hit is present, and getch() which gets one character without echoing
-it.</p>
-</div>
-<div class="section" id="how-do-i-emulate-os-kill-in-windows">
-<h1><a class="toc-backref" href="#id10">10 How do I emulate os.kill() in Windows?</a></h1>
-<p>Use win32api:</p>
-<pre class="literal-block">
-def kill(pid):
- """kill function for Win32"""
- import win32api
- handle = win32api.OpenProcess(1, 0, pid)
- return (0 != win32api.TerminateProcess(handle, 0))
-</pre>
-</div>
-<div class="section" id="why-does-os-path-isdir-fail-on-nt-shared-directories">
-<h1><a class="toc-backref" href="#id11">11 Why does os.path.isdir() fail on NT shared directories?</a></h1>
-<p>The solution appears to be always append the "\" on
-the end of shared drives.</p>
-<pre class="literal-block">
->>> import os
->>> os.path.isdir( '\\\\rorschach\\public')
-0
->>> os.path.isdir( '\\\\rorschach\\public\\')
-1
-</pre>
-<p>It helps to think of share points as being like drive letters.
-Example:</p>
-<pre class="literal-block">
-k: is not a directory
-k:\ is a directory
-k:\media is a directory
-k:\media\ is not a directory
-</pre>
-<p>The same rules apply if you substitute "k:" with "\conkyfoo":</p>
-<pre class="literal-block">
-\\conky\foo is not a directory
-\\conky\foo\ is a directory
-\\conky\foo\media is a directory
-\\conky\foo\media\ is not a directory
-</pre>
-</div>
-<div class="section" id="cgi-py-or-other-cgi-programming-doesn-t-work-sometimes-on-nt-or-win95">
-<h1><a class="toc-backref" href="#id12">12 cgi.py (or other CGI programming) doesn't work sometimes on NT or win95!</a></h1>
-<p>Be sure you have the latest python.exe, that you are using
-python.exe rather than a GUI version of Python and that you
-have configured the server to execute</p>
-<pre class="literal-block">
-"...\python.exe -u ..."
-</pre>
-<p>for the CGI execution. The -u (unbuffered) option on NT and
-Win95 prevents the interpreter from altering newlines in the
-standard input and output. Without it post/multipart requests
-will seem to have the wrong length and binary (e.g. GIF)
-responses may get garbled (resulting in broken images, PDF files,
-and other binary downloads failing).</p>
-</div>
-<div class="section" id="why-doesn-t-os-popen-work-in-pythonwin-on-nt">
-<h1><a class="toc-backref" href="#id13">13 Why doesn't os.popen() work in PythonWin on NT?</a></h1>
-<p>The reason that os.popen() doesn't work from within PythonWin is due
-to a bug in Microsoft's C Runtime Library (CRT). The CRT assumes you
-have a Win32 console attached to the process.</p>
-<p>You should use the win32pipe module's popen() instead which doesn't
-depend on having an attached Win32 console.</p>
-<p>Example:</p>
-<pre class="literal-block">
-import win32pipe
-f = win32pipe.popen('dir /c c:\\')
-print f.readlines()
-f.close()
-</pre>
-</div>
-<div class="section" id="why-doesn-t-os-popen-win32pipe-popen-work-on-win9x">
-<h1><a class="toc-backref" href="#id14">14 Why doesn't os.popen()/win32pipe.popen() work on Win9x?</a></h1>
-<p>There is a bug in Win9x that prevents os.popen/win32pipe.popen* from
-working. The good news is there is a way to work around this problem.
-The Microsoft Knowledge Base article that you need to lookup is:
-Q150956. You will find links to the knowledge base at:
-<a class="reference external" href="http://www.microsoft.com/kb">http://www.microsoft.com/kb</a>.</p>
-</div>
-<div class="section" id="pyrun-simplefile-crashes-on-windows-but-not-on-unix-why">
-<h1><a class="toc-backref" href="#id15">15 PyRun_SimpleFile() crashes on Windows but not on Unix; why?</a></h1>
-<p>This is very sensitive to the compiler vendor, version and (perhaps)
-even options. If the FILE* structure in your embedding program isn't
-the same as is assumed by the Python interpreter it won't work.</p>
-<p>The Python 1.5.* DLLs (<tt class="docutils literal">python15.dll</tt>) are all compiled
-with MS VC++ 5.0 and with multithreading-DLL options (<tt class="docutils literal">/MD</tt>).</p>
-<p>If you can't change compilers or flags, try using Py_RunSimpleString().
-A trick to get it to run an arbitrary file is to construct a call to
-execfile() with the name of your file as argument.</p>
-<p>Also note that you can not mix-and-match Debug and Release versions. If you
-wish to use the Debug Multithreaded DLL, then your module _must_ have an
-"_d" appended to the base name.</p>
-</div>
-<div class="section" id="importing-tkinter-fails-on-windows-95-98-why">
-<h1><a class="toc-backref" href="#id16">16 Importing _tkinter fails on Windows 95/98: why?</a></h1>
-<p>Sometimes, the import of _tkinter fails on Windows 95 or 98,
-complaining with a message like the following:</p>
-<pre class="literal-block">
-ImportError: DLL load failed: One of the library files needed
-to run this application cannot be found.
-</pre>
-<p>It could be that you haven't installed Tcl/Tk, but if you did
-install Tcl/Tk, and the Wish application works correctly,
-the problem may be that its installer didn't
-manage to edit the autoexec.bat file correctly. It tries to add a
-statement that changes the PATH environment variable to include
-the Tcl/Tk 'bin' subdirectory, but sometimes this edit doesn't
-quite work. Opening it with notepad usually reveals what the
-problem is.</p>
-<p>(One additional hint, noted by David Szafranski: you can't use
-long filenames here; e.g. use <tt class="docutils literal"><span class="pre">C:\PROGRA~1\Tcl\bin</span></tt> instead of
-<tt class="docutils literal"><span class="pre">C:\Program</span> Files\Tcl\bin</tt>.)</p>
-</div>
-<div class="section" id="how-do-i-extract-the-downloaded-documentation-on-windows">
-<h1><a class="toc-backref" href="#id17">17 How do I extract the downloaded documentation on Windows?</a></h1>
-<p>Sometimes, when you download the documentation package to a Windows
-machine using a web browser, the file extension of the saved file
-ends up being .EXE. This is a mistake; the extension should be .TGZ.</p>
-<p>Simply rename the downloaded file to have the .TGZ extension, and
-WinZip will be able to handle it. (If your copy of WinZip doesn't,
-get a newer one from <a class="reference external" href="http://www.winzip.com">http://www.winzip.com</a>.)</p>
-</div>
-<div class="section" id="missing-cw3215mt-dll-or-missing-cw3215-dll">
-<h1><a class="toc-backref" href="#id18">18 Missing cw3215mt.dll (or missing cw3215.dll)</a></h1>
-<p>Sometimes, when using Tkinter on Windows, you get an error that
-cw3215mt.dll or cw3215.dll is missing.</p>
-<p>Cause: you have an old Tcl/Tk DLL built with cygwin in your path
-(probably <tt class="docutils literal"><span class="pre">C:\Windows</span></tt>). You must use the Tcl/Tk DLLs from the
-standard Tcl/Tk installation (Python 1.5.2 comes with one).</p>
-</div>
-<div class="section" id="warning-about-ctl3d32-version-from-installer">
-<h1><a class="toc-backref" href="#id19">19 Warning about CTL3D32 version from installer</a></h1>
-<p>The Python installer issues a warning like this:</p>
-<pre class="literal-block">
-This version uses ``CTL3D32.DLL`` whitch is not the correct version.
-This version is used for windows NT applications only.
-</pre>
-<p>[Tim Peters]
-This is a Microsoft DLL, and a notorious
-source of problems. The message means what it says: you have the wrong version
-of this DLL for your operating system. The Python installation did not
-cause this -- something else you installed previous to this overwrote the
-DLL that came with your OS (probably older shareware of some sort, but
-there's no way to tell now). If you search for "CTL3D32" using any search
-engine (AltaVista, for example), you'll find hundreds and hundreds of web
-pages complaining about the same problem with all sorts of installation
-programs. They'll point you to ways to get the correct version reinstalled
-on your system (since Python doesn't cause this, we can't fix it).</p>
-<p>David A Burton has written a little program to fix this. Go to
-<a class="reference external" href="http://www.burtonsys.com/download.html">http://www.burtonsys.com/download.html</a> and click on "ctl3dfix.zip"</p>
-</div>
-</div>
-</body>
-</html>
--
GitLab