Initial revision
diff --git a/Misc/FAQ b/Misc/FAQ
new file mode 100644
index 0000000..49b1607
--- /dev/null
+++ b/Misc/FAQ
@@ -0,0 +1,643 @@
+Subject: FAQ: Python -- an object-oriented language
+Newsgroups: comp.lang.misc,comp.answers,news.answers
+Followup-to: comp.lang.misc
+From: guido@cwi.nl (Guido van Rossum)
+Reply-to: guido@cwi.nl (Guido van Rossum)
+Approved: news-answers-request@MIT.Edu
+
+Archive-name: python-faq/part1
+Version: 1.2
+Last-modified: 24 Jan 1994
+
+This article contains answers to Frequently Asked Questions about
+Python (an object-oriented interpreted programming language -- see
+the answer to question 1.1 for a short overview).
+
+Copyright 1993, 1994 Guido van Rossum. Unchanged electronic
+redistribution of this FAQ is allowed. Printed redistribution only
+with permission of the author. No warranties.
+
+Author's address:
+ Guido van Rossum
+ CWI, dept. CST
+ Kruislaan 413
+ P.O. Box 94079
+ 1090 GB Amsterdam
+ The Netherlands
+Email: guido@cwi.nl
+
+The latest version of this FAQ is available by anonymous ftp from
+ftp.cwi.nl [192.16.184.180] in the directory /pub/python, with
+filename python-FAQ. It will also be posted regularly to the
+newsgroups comp.answers and comp.lang.misc.
+
+Many FAQs, including this one, are available by anonymous ftp from
+rtfm.mit.edu [18.70.0.209] in the directory pub/usenet/news.answers.
+The name under which a FAQ is archived appears in the Archive-name line
+at the top of the article. This FAQ is archived as python-faq/part1.
+
+There's a mail server on that machine which will send you files from
+the archive by e-mail if you have no ftp access. You send a e-mail
+message to mail-server@rtfm.mit.edu containing the single word help in
+the message body to receive instructions.
+
+This FAQ is divided in the following chapters:
+
+ 1. General information and availability
+ 2. Python in the real world
+ 3. Building Python
+ 4. Programming in Python
+ 5. Extending Python
+ 6. Python's design
+ 7. Using Python on non-UNIX platforms
+
+To find the start of a particular chapter, search for the chapter number
+followed by a dot and a space at the beginning of a line (e.g. to
+find chapter 4 in vi, type /^4\. /).
+
+Here's an overview of the questions per chapter:
+
+ 1. General information and availability
+ 1.1. Q. What is Python?
+ 1.2. Q. Why is it called Python?
+ 1.3. Q. How do I obtain a copy of the Python source?
+ 1.4. Q. How do I get documentation on Python?
+ 1.5. Q. Is there a newsgroup or mailing list devoted to Python?
+ 1.6. Q. Is there a book on Python, or will there be one out soon?
+ 1.7. Q. Are there any published articles about Python that I can quote?
+
+ 2. Python in the real world
+ 2.1. Q. How many people are using Python?
+ 2.2. Q. Have any significant projects been done in Python?
+ 2.3. Q. Are there any commercial projects going on using Python?
+ 2.4. Q. What new developments are expected for Python in the future?
+ 2.5. Q. How stable is Python?
+ 2.6. Q. Any more future plans?
+
+ 3. Building Python
+ 3.1. Q. I have trouble building the md5 module and/or finding the file
+ md5.c.
+ 3.2. Q. Is there a test set?
+ 3.3. Q. When running the test set, I get complaints about floating point
+ operations, but when playing with floating point operations I cannot
+ find anything wrong with them.
+ 3.4. Q. I get an OverflowError on evaluating 2*2. What is going on?
+ 3.5. Q. Trouble building Python 0.9.9 on platform X.
+
+ 4. Programming in Python
+ 4.1. Q. Can I create an object class with some methods implemented in
+ C and others in Python (e.g. through inheritance)? (Also phrased as:
+ Can I use a built-in type as base class?)
+ 4.2. Q. I assign to a variable in a call to exec() but when I try to
+ use it on the next line I get an error. What is going on?
+ 4.3. Q. Why does that work?
+ 4.4. Q. Is there a curses/termcap package for Python?
+ 4.5. Q. Is there an equivalent to C's onexit() in Python?
+ 4.6. Q. When I define a function nested inside another function, the
+ nested function seemingly can't access the local variables of the
+ outer function. What is going on? How do I pass local data to a
+ nested function?
+ 4.7. Q. How do I iterate over a sequence in reverse order?
+ 4.8. Q. My program is too slow. How do I speed it up?
+ 4.9. Q. When I have imported a module, then edit it, and import it
+ again (into the same Python process), the changes don't seem to take
+ place. What is going on?
+
+ 5. Extending Python
+ 5.1. Q. Can I create my own functions in C?
+ 5.2. Q. Can I create my own functions in C++?
+
+ 6. Python's design
+ 6.1. Q. Why isn't there a generic copying operation for objects in
+ Python?
+ 6.2. Q. Why isn't there a generic way to implement persistent objects
+ in Python? (Persistent == automatically saved to and restored from
+ disk.)
+ 6.3. Q. Why isn't there a switch or case statement in Python?
+
+ 7. Using Python on non-UNIX platforms
+ 7.1. Q. Where's the DOS version of 0.9.9?
+ 7.2. Q. Is there a Windows version of Python?
+ 7.3. Q. I have the Mac or DOS version but it appears to be only a binary.
+ Where's the library?
+ 7.4. Q. Where's the documentation for the Mac or DOS version?
+ 7.5. Q. The Mac version doesn't seem to have any facilities for creating or
+ editing programs apart from entering it interactively, and there seems
+ to be no way to save code that was entered interactively. How do I
+ create a Python program on the Mac?
+
+To find a particular question, search for the question number followed
+by a dot, a space, and a Q at the beginning of a line (e.g. to find
+question 4.2 in vi, type /^4\.2\. Q/).
+
+
+1. General information and availability
+=======================================
+
+1.1. Q. What is Python?
+
+A. 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 brands of UNIX, on the Mac, and on
+MS-DOS.
+
+To find out more, the best thing to do is to start reading the
+tutorial from the documentation set (see a few questions further
+down).
+
+1.2. Q. Why is it called Python?
+
+A. Apart from being a computer wizard, I'm also a fan of "Monty
+Python's Flying Circus" (a BBC comedy series from the seventies, in
+case you didn't know). It occurred to me one day that I needed a name
+that was short, unique, and slightly mysterious. And I happened to be
+reading some scripts from the series at the time... So then I decided
+to call my language Python. But Python is not a joke. And don't you
+associate it with dangerous reptiles either!
+
+1.3. Q. How do I obtain a copy of the Python source?
+
+A. The latest Python source distribution is always available by
+anonymous ftp from ftp.cwi.nl [192.16.184.180] in the directory
+/pub/python, with filename python<version>.tar.Z. It is a compressed
+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. Currently <version> is 0.9.9. (See section 7
+for non-UNIX information.)
+
+1.4. Q. How do I get documentation on Python?
+
+A. The latest Python documentation set is always available by
+anonymous ftp from ftp.cwi.nl [192.16.184.180] in the directory
+/pub/python, with filename pythondoc-ps<version>.tar.Z. It is a
+compressed tar file containing PostScript files of the reference
+manual, the library manual, and the tutorial. Currently <version> is
+0.9.9. (Note that the library manual is the most important one of the
+set, as much of Python's power stems from the standard or built-in
+types, functions and modules, all of which are described here.)
+PostScript for a high-level description of Python is in the file
+nluug-paper.ps.
+
+The following sites keep mirrors of the Python distribution:
+
+Site IP address Directory
+
+gatekeeper.dec.com 16.1.0.2 /pub/plan/python/cwi
+ftp.uu.net 192.48.96.9 /languages/python
+ftp.wustl.edu 128.252.135.4 /graphics/graphics/sgi-stuff/python
+ftp.funet.fi 128.214.6.100 /pub/languages/python (old?)
+ftp.fu-berlin.de 130.133.4.50 /pub/unix/languages/python (python* only)
+
+Or try archie on e.g. python0.9.9.tar.Z to locate the nearest copy of
+that version...
+
+1.5. Q. Is there a newsgroup or mailing list devoted to Python?
+
+A. There is no Python newsgroup yet; if you want to post to the net
+about Python, use comp.lang.misc. There is a mailing list devoted to
+Python; send e-mail to python-list-request@cwi.nl to (un)subscribe.
+There are plans to start the discussion about creation of
+comp.lang.python as soon as version 1.0.0 has been released.
+
+1.6. Q. Is there a book on Python, or will there be one out soon?
+
+A. Unfortunately, not yet. I would like to write one but my
+obligations at CWI include too much other work to make much progress
+on it. Several parties have expressed interest in sponsoring or
+helping the production of a book or reference manual, but so far there
+are no firm plans. If you volunteer help, by all means drop me a
+note!
+
+1.7. Q. Are there any published articles about Python that I can quote?
+
+A. So far the only refereed and published article that describes
+Python in some detail is:
+
+ 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.
+
+LaTeX source for this paper is available as part of the Python source
+distribution.
+
+A more recent high-level description of Python is:
+
+ Guido van Rossum, "An Introduction to Python for UNIX/C
+ Programmers", in the proceedings of the NLUUG najaarsconferentie
+ 1993 (dutch UNIX users group meeting november 1993).
+
+PostScript for this paper and for the slides used for the accompanying
+presentation can be found in the ftp directory mentioned a few
+questions earlier, with filenames nluug-paper.ps and nluug-slides.ps,
+respectively.
+
+
+2. Python in the real world
+===========================
+
+2.1. Q. How many people are using Python?
+
+A. I don't know, but at the last count there were at least 130
+addresses on the Python mailing list (several of which are local
+redistribution lists). I suspect that many users don't bother
+to subscribe to the list.
+
+2.2. Q. Have any significant projects been done in Python?
+
+A. Here at CWI (the home of Python), we have written a 20,000 line
+authoring environment for transportable hypermedia presentations, a
+multimedia teleconferencing tool, as well as many smaller programs.
+
+The University of Virginia uses Python to control a virtual reality
+engine. Contact: Matt Conway <conway@virginia.edu>.
+
+See also the next question.
+
+2.3. Q. Are there any commercial projects going on using Python?
+
+A. Several companies have revealed to me that they are planning or
+considering to use Python in a future product. The furthest is
+Sunrise Software, who already have a product out using Python -- they
+use Python for a GUI management application and an SNMP network
+manangement application. Contact: <info@sunrise.com>.
+
+Individuals at many other companies are using Python for
+internal development (witness their contributions to the Python
+mailing list).
+
+Python has also been elected as an extension language by MADE, a
+consortium supported by the European Committee's ESPRIT program and
+consisting of Bull, CWI and some other European companies. Contact:
+Ivan Herman <ivan@cwi.nl>.
+
+2.4. Q. What new developments are expected for Python in the future?
+
+A. I am almost ready to release version 1.0.0 -- it should be out by
+the end of January 1994. It will have some new functionality and
+bugfixes and be portable to more platforms. The directory tree
+structure and build procedure will be radically different -- almost
+all configuration is now done automatically, using GNU autoconf.
+User-visible changes include: double-quoted strings, functional
+programming operations (lambda, map, filter, reduce -- all evaluated
+eagerly), exec becomes a statement, str() is customizable through
+__str__ (used by print). The originally planned grand renaming scheme
+will not be implemented because of lack of time. A beta version can
+be ftp'ed from the usual sites, file python1.0.0beta.tar.Z.
+
+2.5. Q. How stable is Python?
+
+A. Very stable. While the current version number (0.9.9) would
+suggest it is in the early stages of development, in fact new, stable
+releases have been coming out every 3-6 months for the past three years.
+
+2.6. Q. Any more future plans?
+
+A. Without warranty that any of this will actually be realized: I am
+currently thinking about mechanisms for built-in on-line help and a
+switch/case statement. There are also some people (independently)
+working on a windowing interface based on STDWIN but with the power
+and ease of use of the average modern widget set. I still hope to get
+some help in producing a Windows version. It would be nice if there
+were a window-based class browser (Someone at CWI has contributed one
+using Motif but it needs some work).
+
+
+3. Building Python
+==================
+
+3.1. Q. I have trouble building the md5 module and/or finding the file
+md5.c.
+
+A. Apparently the md5 module was based on an older version of RSA's
+md5 implementation. The ftp site rsa.com mentioned in the Makefile
+where this version was found is no longer accessible, and the version
+from RFC 1321 (md5c.c) is slightly different. This will be fixed in
+the 1.0 release; write me if you need the fixes now.
+
+3.2. Q. Is there a test set?
+
+A. Yes, simply do "import testall" (or "import autotest" if you aren't
+interested in the output). The standard modules whose name begins
+with "test" together comprise the test. The test set doesn't test
+*all* features of Python but it goes a long way to confirm that a new
+port is actually working. The Makefile contains an entry "make test"
+which runs the autotest module.
+
+3.3. Q. When running the test set, I get complaints about floating point
+operations, but when playing with floating point operations I cannot
+find anything wrong with them.
+
+A. The test set makes occasional unwarranted assumptions about the
+semantics of C floating point operations. Until someone donates a
+better floating point test set, you will have to comment out the
+offending floating point tests and execute similar tests manually.
+
+3.4. Q. I get an OverflowError on evaluating 2*2. What is going on?
+
+A. Your machine probably has 64 bit long integers (e.g. DEC alpha or
+HP snake architectures). There are some dependencies on word length
+in file intobject.c. This will be corrected in the 1.0 release; until
+then, on a 64 bit machine, just comment out the check for overflow
+from int_mul:
+
+ #if 0
+ if (x > 0x7fffffff || x < (double) (long) 0x80000000)
+ return err_ovf("integer multiplication");
+ #endif
+
+You should also include <limits.h> and replace the constant 32 by
+LONG_BIT in int_[lr]shift.
+
+3.5. Q. Trouble building Python 0.9.9 on platform X.
+
+A. In the bootstrap phase (before you have built the first running
+interpreter), make sure the -D settings in the Makefile are correct
+for your system. In particular you may have to add or delete -DSYSV.
+It may also be necessary to change the flags used to compile
+posixmodule.c and timemodule.c; e.g. on AIX the following are
+necessary:
+ posixmodule.c: -DHAVE_STDLIB -DNOALTTZ -DOLDTZ -Dunix -DSYSV -DDO_TIMES
+ timemodule.c: -DHAVE_STDLIB -DNOALTTZ -DOLDTZ -Uunix -DSYSV -DBSD_TIME
+(Note the -Uunix for timemodule!)
+Those switches for timemodule also require that the
+ #ifdef unix
+ #ifdef BSD_TIME
+just above:
+ static long
+ millitimer()
+( and below the "#endif /* macintosh */" version of millitimer
+be changed to:
+ #if defined(unix) | defined(BSD_TIME)
+ #ifdef BSD_TIME
+
+
+4. Programming in Python
+========================
+
+4.1. Q. Can I create an object class with some methods implemented in
+C and others in Python (e.g. through inheritance)? (Also phrased as:
+Can I use a built-in type as base class?)
+
+A. No, but you can easily create a Python class which serves as a
+wrapper around a built-in object, e.g. (for dictionaries):
+
+ # A user-defined class behaving almost identical
+ # to a built-in dictionary.
+ class UserDict:
+ def __init__(self): self.data = {}
+ def __repr__(self): return repr(self.data)
+ def __cmp__(self, dict):
+ if type(dict) == type(self.data):
+ return cmp(self.data, dict)
+ else:
+ return cmp(self.data, dict.data)
+ def __len__(self): return len(self.data)
+ def __getitem__(self, key): return self.data[key]
+ def __setitem__(self, key, item): self.data[key] = item
+ def __delitem__(self, key): del self.data[key]
+ def keys(self): return self.data.keys()
+ def items(self): return self.data.items()
+ def values(self): return self.data.values()
+ def has_key(self, key): return self.data.has_key(key)
+
+4.2. Q. I assign to a variable in a call to exec() but when I try to
+use it on the next line I get an error. What is going on?
+
+A. The reason why this occurs is too complicated to explain (but see
+the next question). To fix it is easy, however: simply assign None to
+the variable *before* calling exec(). This will be fixed in the 1.0
+release.
+
+4.3. Q. Why does that work?
+
+A. When parsing your program and converting it into internal pseudo
+code, the interpreter does some optimizations to speed up function
+execution: it figures out the names of all the local variables and
+treats them specially. Because your assignment is done by exec(), it
+is not seen initially by the parser and the variable is not recognized
+as a local variable. The default treatment is as a global variable,
+but the exec() statement places it in the local scope, where it is not
+found. This will be fixed in release 1.0 by making exec into a
+statement; the parser will then be able to switch off the
+optimizations for local variables if it encounters an exec statement
+(recognizing calls to built-in functions is not possible for the
+parser, hence the syntax change to a statement).
+
+4.4. Q. Is there a curses/termcap package for Python?
+
+A. No, but you can use the "alfa" (== character cell) version of
+STDWIN. (STDWIN == Standard Windows, a portable windowing system
+interface by the same author, URL ftp://ftp.cwi.nl/pub/stdwin.)
+This will also prepare your program for porting to windowing
+environments such as X11 or the Macintosh.
+
+4.5. Q. Is there an equivalent to C's onexit() in Python?
+
+A. Yes, if you import sys and assign a function to sys.exitfunc, it
+will be called when your program exits, is killed by an unhandled
+exception, or (on UNIX) receives a SIGHUP or SIGTERM signal.
+
+4.6. Q. When I define a function nested inside another function, the
+nested function seemingly can't access the local variables of the
+outer function. What is going on? How do I pass local data to a
+nested function?
+
+A. Python does not have arbitrarily nested scopes. When you need to
+create a function that needs to access some data which you have
+available locally, create a new class to hold the data and return a
+method of an instance of that class, e.g.:
+
+ class MultiplierClass:
+ def __init__(self, factor):
+ self.factor = factor
+ def multiplier(self, argument):
+ return argument * self.factor
+
+ def generate_multiplier(factor):
+ return MultiplierClass(factor).multiplier
+
+ twice = generate_multiplier(2)
+ print twice(10)
+ # Output: 20
+
+4.7. Q. How do I iterate over a sequence in reverse order?
+
+A. If it is a list, the fastest solution is
+
+ list.reverse()
+ try:
+ for x in list:
+ "do something with x"
+ finally:
+ list.reverse()
+
+This has the disadvantage that while you are in the loop, the list
+is temporarily reversed. If you don't like this, you can make a copy.
+This appears expensive but is actually faster than other solutions:
+
+ rev = list[:]
+ rev.reverse()
+ for x in rev:
+ <do something with x>
+
+If it isn't a list, a more general but slower solution is:
+
+ i = len(list)
+ while i > 0:
+ i = i-1
+ x = list[i]
+ <do something with x>
+
+A more elegant solution, is to define a class which acts as a sequence
+and yields the elements in reverse order (solution due to Steve
+Majewski):
+
+ class Rev:
+ def __init__(self, seq):
+ self.forw = seq
+ def __len__(self):
+ return len(self.forw)
+ def __getitem__(self, i):
+ return self.forw[-(i + 1)]
+
+You can now simply write:
+
+ for x in Rev(list):
+ <do something with x>
+
+Unfortunately, this solution is slowest of all, due the the method
+call overhead...
+
+4.8. Q. My program is too slow. How do I speed it up?
+
+A. That's a tough one, in general. There are many tricks to speed up
+Python code; I would consider rewriting parts in C only as a last
+resort. 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 may consider using a
+more direct way, e.g. directly accessing instance variables. Also see
+the standard module "profile" (described in the file
+"python/lib/profile.doc") 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).
+
+4.9. Q. When I have imported a module, then edit it, and import it
+again (into the same Python process), the changes don't seem to take
+place. What is going on?
+
+A. For efficiency reasons, Python only reads the module file on the
+first time a module is imported (otherwise a program consisting of
+many modules, each of which imports the same basic module, would read
+the basic module over and over again). To force a changed module
+being read again, 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 objects imported
+thus.
+
+
+5. Extending Python
+===================
+
+5.1. Q. Can I create my own functions in C?
+
+A. Yes, you can create built-in modules containing functions,
+variables, exceptions and even new types in C. This is all explained
+in the file "python/misc/EXTENDING". Also read the file "DYNLOAD"
+there for hints on how to load such extension modules
+
+5.2. Q. Can I create my own functions in C++?
+
+A. Yes, using the C-compatibility features found in C++. Basically
+you 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.
+
+
+6. Python's design
+==================
+
+6.1. Q. Why isn't there a generic copying operation for objects in
+Python?
+
+A. Hmm. Maybe there should be one, but it's difficult to assign a
+useful meaning to copying of open files, sockets and windows, or
+recursive data structures. As long as you design all your classes
+yourself you are of course free to define a standard base class that
+defines an overridable copying operation for all the objects you care
+about. (One practical point: it would have to be a built-in function,
+not a standard method name, since not all built-in object types have
+methods; e.g. strings, integers and tuples don't.)
+
+6.2. Q. Why isn't there a generic way to implement persistent objects
+in Python? (Persistent == automatically saved to and restored from
+disk.)
+
+A. Hmm, hmm. Basically for the same reasons as why there is no
+generic copying operation.
+
+6.3. Q. Why isn't there a switch or case statement in Python?
+
+A. 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 concensus (yet) on whether and how
+to do range tests.
+
+
+7. Using Python on non-UNIX platforms
+=====================================
+
+7.1. Q. Where's the DOS version of 0.9.9?
+
+A. I hope it will be coming soon. A friend with a DOS machine and a
+compiler has volunteered to build it but he's very busy. Until then,
+you will have to make do with the 0.9.8 version (which isn't so bad,
+actually).
+
+7.2. Q. Is there a Windows version of Python?
+
+A. Not yet. Several Windows hackers with C compilers are working on a
+port though, so maybe we'll have one soon.
+
+7.3. Q. I have the Mac or DOS version but it appears to be only a binary.
+Where's the library?
+
+A. You still need to copy the files from the distribution directory
+"python/lib" to your system. If you don't have the full distribution,
+you can ftp the file pythonlib0.9.9.tar.Z from site ftp.cwi.nl,
+directory /pub/python; this is a subset of the distribution containing
+just those file.
+
+7.4. Q. Where's the documentation for the Mac or DOS version?
+
+A. There isn't any. The documentation for the Unix version also
+applies to the Mac and DOS versions. Where applicable, differences
+are indicated in the text.
+
+7.5. Q. The Mac version doesn't seem to have any facilities for creating or
+editing programs apart from entering it interactively, and there seems
+to be no way to save code that was entered interactively. How do I
+create a Python program on the Mac?
+
+A. Use an external editor. I am quite happy with the Desk Accessory
+called Sigma Edit; this doesn't require Multifinder or System 7. I
+work like this: start the interpreter; edit a module file using Sigma
+Edit; import and test it in the interpreter; edit again in Sigma Edit;
+then use the built-in function reload() to re-read the imported
+module; etc.