[Python-checkins] r75034 - in sandbox/trunk/faq: README extending.rst general.rst gui.rst index.rst installed.rst library.rst programming.rst windows.rst
andrew.kuchling
python-checkins at python.org
Wed Sep 23 02:56:34 CEST 2009
Author: andrew.kuchling
Date: Wed Sep 23 02:56:33 2009
New Revision: 75034
Log:
Initial commit of FAQ manual
Added:
sandbox/trunk/faq/
sandbox/trunk/faq/README
sandbox/trunk/faq/extending.rst
sandbox/trunk/faq/general.rst
sandbox/trunk/faq/gui.rst
sandbox/trunk/faq/index.rst
sandbox/trunk/faq/installed.rst
sandbox/trunk/faq/library.rst
sandbox/trunk/faq/programming.rst
sandbox/trunk/faq/windows.rst
Added: sandbox/trunk/faq/README
==============================================================================
--- (empty file)
+++ sandbox/trunk/faq/README Wed Sep 23 02:56:33 2009
@@ -0,0 +1,36 @@
+
+To add the FAQ to the Python documentation set:
+
+1) Create a symlink from Doc/faq to this directory.
+
+2) Make the following change to contents.rst:
+
+Index: contents.rst
+===================================================================
+--- contents.rst (revision 75033)
++++ contents.rst (working copy)
+@@ -15,6 +15,7 @@
+ install/index.rst
+ documenting/index.rst
+ howto/index.rst
++ faq/index.rst
+ glossary.rst
+
+ about.rst
+
+3) (optional) To add the FAQs to the top-level table of contents,
+ apply the following patch.
+
+Index: tools/sphinxext/indexcontent.html
+===================================================================
+--- tools/sphinxext/indexcontent.html (revision 75033)
++++ tools/sphinxext/indexcontent.html (working copy)
+@@ -26,6 +26,8 @@
+ <span class="linkdescr">sharing modules with others</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("documenting/index") }}">Documenting Python</a><br/>
+ <span class="linkdescr">guide for documentation authors</span></p>
++ <p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">FAQs</a><br/>
++ <span class="linkdescr">frequently asked questions</span></p>
+ </td></tr>
+ </table>
+
Added: sandbox/trunk/faq/extending.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/faq/extending.rst Wed Sep 23 02:56:33 2009
@@ -0,0 +1,462 @@
+====================================
+Extending/Embedding FAQ
+====================================
+
+.. contents::
+
+
+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 or 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>`_. `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>`_ are also alternatives for
+wrapping C++ libraries.
+
+
+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>`_, `Weave <http://www.scipy.org/site_content/weave>`_ or
+`SWIG <http://www.swig.org>`_
+
+
+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
+extension 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.
+
+
+
Added: sandbox/trunk/faq/general.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/faq/general.rst Wed Sep 23 02:56:33 2009
@@ -0,0 +1,1490 @@
+
+====================================
+General Python FAQ
+====================================
+
+.. contents::
+
+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://wiki.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/library/>`_ to get an idea of what's available.
+A wide variety of third-party extensions are also available.
+Consult `the Python Package Index <http://pypi.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 </dev/peps/pep-0006/>`_
+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/>`_
+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
+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.
+
+Consult the `Developer FAQ <http://www.python.org/dev/devfaq.html#subversion-svn>`__
+for more information on getting the source code and compiling it.
+
+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/. PDF and downloadable HTML
+versions are also available.
+
+The documentation is written using
+`the Sphinx documentation tool <http://sphinx.pocoo.org/>`__.
+The Sphinx source for the documentation is part of the Python source
+distribution.
+
+
+I've never programmed before. Is there a Python tutorial?
+-----------------------------------------------------------------
+
+There are numerous tutorials and books available. Consult `the
+Beginner's Guide <http://wiki.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?
+---------------------------------------------------------------------
+
+Mirroring has been discontinued as of March 15, 2007. Please
+`download here <http://www.python.org/download/>`_.
+
+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/.
+
+How do I get a beta test version of Python?
+---------------------------------------------------
+
+Alpha and beta releases are available from
+http://www.python.org/download/. All releases are announced on the
+comp.lang.python and comp.lang.python.announce newsgroups and 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 Roundup
+installation at http://bugs.python.org/.
+
+You must have a Roundup account to report bugs; this makes it
+possible for us to contact you if we have follow-up questions. It
+will also enable Roundup to send you updates as we act on your
+bug. If you had previously used SourceForge to report bugs to
+Python, you can obtain your Roundup password through Roundup's
+`password reset procedure <http://bugs.python.org/user?@template=forgotten>`_.
+
+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 cite 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://wiki.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 time when 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.6.2 release </download/>`_ is recommended production-ready version at
+this point in time. Python 3.1 is also considered production-ready, but may be
+less useful, since currently there is more third party software available for
+Python 2 than for Python 3. Python 2 code will generally not run unchanged in
+Python 3.
+
+
+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://python.org/about/success for a list of projects that
+use Python. Consulting the proceedings for `past Python conferences
+</community/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/dev/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 </dev/peps/pep-0001/>`_
+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's still
+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 </dev/peps/pep-0005/>`_
+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/>`_.
+
+
+
+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* unforeseen 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.
+
+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 lets students 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 probably even 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.
+
+If you want to discuss Python's use in education, then you may
+be interested in joining `the edu-sig mailing list </community/sigs/current/edu-sig>`_.
+
+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 at it a long time 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 one screen (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. This has nothing to do
+with Python, but with how the underlying C platform handles floating
+point numbers, and ultimately with the inaccuracies introduced when
+writing down numbers as a string of a fixed number of digits.
+
+The internal representation of floating point numbers 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 number'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
+
+One of the consequences of this is that it is error-prone 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/tutorial/floatingpoint>`_
+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 means we can
+allocate space for it at creation time, and the storage requirements
+are fixed and unchanging. This is also one of the reasons for the
+distinction between tuples and lists.
+
+Another advantage 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 common 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 a sequence of strings and insert
+itself between adjacent elements. This method can be used with any
+argument which obeys the rules for sequence objects, including 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
+</dev/peps/pep-0275/>`_ 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 </community/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
+</community/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 provided
+iterable, sorts it and returns it.
+For example, here's how to iterate over the keys of a
+dictionary in sorted order::
+
+ for key in sorted(dict.iterkeys()):
+ ...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 helps in the construction of large programs.
+
+Python 2.6 adds an ``abc`` module that lets you define Abstract Base
+Classes (ABCs). You can then use ``isinstance()``
+and ``issubclass`` to check whether an instance or a class
+implements a particular ABC. The ``collections`` modules defines a set
+of useful ABCs such as ``Iterable``, ``Container``,
+and ``MutableMapping``.
+
+For Python, many of the advantages of interface specifications can be
+obtained by an appropriate test discipline for components. There is
+also a tool, PyChecker, which can be used to find problems due to
+subclassing.
+
+A good test suite for a module can both provide a regression test
+and serve as 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 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 for attribute assignments?
+---------------------------------------------------------------------------------------
+
+Python has a 'with' statement that wraps the execution of a block,
+calling code on the entrance and exit from the block.
+Some language have a construct that looks like this::
+
+ with obj:
+ a = 1 # equivalent to obj.a = 1
+ total = total + 1 # obj.total = obj.total + 1
+
+In Python, such a construct would be ambiguous.
+
+Other languages, such as Object Pascal, Delphi, and C++, use static
+types, so it's possible to know, in an unambiguous way, what member is
+being assigned to. This is the main point of static typing -- 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 makes 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 tells the interpreter
+this. What should happen if "a" is, let us say, an integer? If there is
+a global variable named "x", will it be 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.
+
+
+Why does Python allow commas at the end of lists and tuples?
+------------------------------------------------------------------------------
+
+Python lets you add a trailing comma at the end of lists, tuples, and
+dictionaries::
+
+ [1, 2, 3,]
+ ('a', 'b', 'c',)
+ d = {
+ "A": [1, 5],
+ "B": [6, 7], # last trailing comma is optional but good style
+ }
+
+
+There are several reasons to allow this.
+
+When you have a literal value for a list, tuple, or dictionary spread
+across multiple lines, it's easier to add more elements because you
+don't have to remember to add a comma to the previous line. The lines
+can also be sorted in your editor without creating a syntax error.
+
+Accidentally omitting the comma can lead to errors that are hard to
+diagnose. For example::
+
+ x = [
+ "fee",
+ "fie"
+ "foo",
+ "fum"
+ ]
+
+This list looks like it has four elements, but it actually contains
+three: "fee", "fiefoo" and "fum". Always adding the comma avoids this
+source of error.
+
+Allowing the trailing comma may also make programmatic code generation
+easier.
Added: sandbox/trunk/faq/gui.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/faq/gui.rst Wed Sep 23 02:56:33 2009
@@ -0,0 +1,166 @@
+
+====================================
+Graphic User Interface FAQ
+====================================
+
+.. contents::
+
+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; wxWidgets 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.
+
+`wxWidgets <http://wxwidgets.org>`_ is an extension module that
+wraps many of the wxWindows C++ classes, and is quickly gaining
+popularity amongst Python developers. You can get wxWidgets 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 </download/mac>`_ 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 <../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).
+
+
+
Added: sandbox/trunk/faq/index.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/faq/index.rst Wed Sep 23 02:56:33 2009
@@ -0,0 +1,18 @@
+
+###################################
+ Python Frequently Asked Questions
+###################################
+
+:Release: |version|
+:Date: |today|
+
+.. toctree::
+ :maxdepth: 1
+
+ general.rst
+ programming.rst
+ library.rst
+ extending.rst
+ windows.rst
+ gui.rst
+ installed.rst
Added: sandbox/trunk/faq/installed.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/faq/installed.rst Wed Sep 23 02:56:33 2009
@@ -0,0 +1,59 @@
+
+=====================================================
+"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://wiki.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.
+
Added: sandbox/trunk/faq/library.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/faq/library.rst Wed Sep 23 02:56:33 2009
@@ -0,0 +1,901 @@
+
+====================================
+Python Library and Extension FAQ
+====================================
+
+.. contents::
+
+General Library Questions
+===============================
+
+How do I find a module or application to perform task X?
+-------------------------------------------------------------
+
+Check `the Library Reference <http://docs.python.org/library/>`_ 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://pypi.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://docs.python.org/library/atexit>`_ 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://docs.python.org/library/doctest>`_ 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://docs.python.org/library/unittest>`_ 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://docs.python.org/library/pydoc>`_
+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://docs.python.org/library/threading>`_ 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://docs.python.org/library/queue>`_ 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://docs.python.org/library/queue>`_ 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://docs.python.org/library/posix>`_. 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://docs.python.org/library/struct>`_. 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://docs.python.org/library/array>`_.
+
+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://docs.python.org/library/popen2>`_. 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://docs.python.org/library/tempfile>`_
+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://docs.python.org/lib/internet>`_ and `"Internet Data
+Handling" <http://docs.python.org/lib/netdata>`_ 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://wiki.python.org/moin/WebProgramming .
+
+Cameron Laird maintains a useful set of pages about Python web technologies at
+http://phaseit.net/claird/comp.lang.python/web_python.
+
+
+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 wiki pages <http://wiki.python.org/moin/WebProgramming>`_ for more links.
+
+
+How do I send mail from a Python script?
+------------------------------------------------
+
+Use `the standard library module smtplib
+<http://docs.python.org/library/smtplib>`_.
+
+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 at 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 writable.
+
+
+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://docs.python.org/library/bsddb>`_ library.
+Interfaces to disk-based hashes such as `DBM
+<http://docs.python.org/library/dbm>`_ and `GDBM
+<http://docs.python.org/library/gdbm>`_ are also included
+with standard Python.
+
+Support for most relational databases is available. See the `DatabaseProgramming wiki page <http://wiki.python.org/moin/DatabaseProgramming>`_ for details.
+
+
+How do you implement persistent objects in Python?
+------------------------------------------------------------
+
+The `pickle library module
+<http://docs.python.org/library/pickle>`_ 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://docs.python.org/library/shelve>`_ uses pickle and
+(g)dbm to create persistent mappings containing arbitrary Python
+objects. For better performance, you can use
+`the cPickle module <http://docs.python.org/library/pickle#module-cPickle>`_.
+
+A more awkward way of doing things is to use pickle's little sister,
+marshal. `The marshal module
+<http://docs.python.org/library/marshal>`_ 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://docs.python.org/library/random>`_ 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.
+
Added: sandbox/trunk/faq/programming.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/faq/programming.rst Wed Sep 23 02:56:33 2009
@@ -0,0 +1,1782 @@
+====================================
+Programming FAQ
+====================================
+
+.. contents::
+
+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/library/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. Pythonwin
+is available as part of the `Python for Windows Extensions
+<http://sourceforge.net/projects/pywin32/>`__
+project and 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 wxWidgets. 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/eric/index.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://bashdb.sourceforge.net/pydb/
+and DDD can be found at http://www.gnu.org/software/ddd.
+
+There are a number of commercial Python IDEs that include graphical
+debuggers. They include:
+
+* Wing IDE (http://wingware.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. One is Thomas Heller's py2exe (Windows only) at
+
+ http://www.py2exe.org/
+
+Another 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.
+
+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 </dev/peps/pep-0008>`_.
+
+
+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/library/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 library 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!
+
+
+What's up with the comma operator's precedence?
+----------------------------------------------------------------------
+
+Comma is not an operator in Python. Consider this session::
+
+ >>> "a" in "b", "a"
+ (False, '1')
+
+Since the comma is not an operator, but a separator between expressions the
+above is evaluated as if you had entered::
+
+ >>> ("a" in "b"), "a"
+
+not::
+
+ >>> "a" in ("5", "a")
+
+The same is true of the various assignment operators (``=``, ``+=`` etc).
+They are not truly operators but syntactic delimiters in assignment
+statements.
+
+
+Is there an equivalent of C's "?:" ternary operator?
+----------------------------------------------------------------------
+Yes, this feature was added in python 2.5. The syntax would be as follows::
+
+ [on_true] if [expression] else [on_false]
+
+ x, y = 50,25
+
+ small = x if x < y else y
+
+For versions previous to 2.5 the answer would be '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 </dev/peps/pep-0308>`_ 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 requires 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
+<http://docs.python.org/library/stdtypes#string-formatting-operations>`_ 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 occurences 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 arbitrary 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 converted 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 penultimate (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?
+---------------------------------------------------------
+
+Use the ``reversed`` builtin function, which is new in Python 2.4::
+
+ for x in reversed(sequence):
+ ...do something with x...
+
+This won't touch your original sequence, but build a new copy with
+reversed order to iterate over.
+
+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()
+
+In Python 2.5 and later, the following is possible instead::
+
+ List = list(set(List))
+
+This converts the list into a set, thereby removing duplicates, and
+then back into a list.
+
+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?
+--------------------------------------------------------------------------------------
+
+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". In Python, just use the ``key`` argument for the
+``sort()`` method::
+
+ Isorted = L[:]
+ Isorted.sort(key=lambda s: int(s[10:15]))
+
+The ``key`` argument is new in Python 2.4, for older versions this
+kind of sorting is quite simple to do with list comprehensions.
+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?
+</doc/faq/general#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
+<http://docs.python.org/reference/datamodel.html#customizing-attribute-access>`_
+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 since Python 2.2::
+
+ class C:
+ def static(arg1, arg2, arg3):
+ # No 'self' parameter!
+ ...
+ static = staticmethod(static)
+
+With Python 2.4's decorators, this can also be written as ::
+
+ class C:
+ @staticmethod
+ def static(arg1, arg2, arg3):
+ # No 'self' parameter!
+ ...
+
+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>
+
Added: sandbox/trunk/faq/windows.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/faq/windows.rst Wed Sep 23 02:56:33 2009
@@ -0,0 +1,594 @@
+
+====================================
+Python Windows FAQ
+====================================
+
+.. contents::
+
+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.
+
+
+.. sidebar:: |Python Development on XP|_
+ :subtitle: `Python Development on XP`_
+
+ This series of screencasts aims to get you up and running with Python on
+ Windows XP. The knowledge is distilled into 1.5 hours and will get you up
+ and running with the right Python distribution, coding in your choice of
+ IDE, and debugging and writing solid code with unit-tests.
+
+.. |Python Development on XP| image:: /images/python-video-icon.png
+.. _`Python Development on XP`: http://www.showmedo.com/videos/series?name=pythonOzsvaldPyNewbieSeries
+
+
+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.
+
+
+.. sidebar:: |Adding Python to DOS Path|_
+ :subtitle: `Adding Python to DOS Path`_
+
+ Python is not added to the DOS path by default. This screencast will walk
+ you through the steps to add the correct entry to the `System Path`,
+ allowing Python to be executed from the command-line by all users.
+
+.. |Adding Python to DOS Path| image:: /images/python-video-icon.png
+.. _`Adding Python to DOS Path`: http://showmedo.com/videos/video?name=960000&fromSeriesID=96
+
+
+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/source). 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/dev/peps/pep-0008>`_ 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`` which 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"
More information about the Python-checkins
mailing list