Move the 3k reST doc tree in place.
diff --git a/Doc/whatsnew/2.2.rst b/Doc/whatsnew/2.2.rst
new file mode 100644
index 0000000..6a7e0e8
--- /dev/null
+++ b/Doc/whatsnew/2.2.rst
@@ -0,0 +1,1269 @@
+****************************
+ What's New in Python 2.2
+****************************
+
+:Author: A.M. Kuchling
+
+.. |release| replace:: 1.02
+
+.. % $Id: whatsnew22.tex 37315 2004-09-10 19:33:00Z akuchling $
+
+
+Introduction
+============
+
+This article explains the new features in Python 2.2.2, released on October 14,
+2002. Python 2.2.2 is a bugfix release of Python 2.2, originally released on
+December 21, 2001.
+
+Python 2.2 can be thought of as the "cleanup release". There are some features
+such as generators and iterators that are completely new, but most of the
+changes, significant and far-reaching though they may be, are aimed at cleaning
+up irregularities and dark corners of the language design.
+
+This article doesn't attempt to provide a complete specification of the new
+features, but instead provides a convenient overview. For full details, you
+should refer to the documentation for Python 2.2, such as the `Python Library
+Reference <http://www.python.org/doc/2.2/lib/lib.html>`_ and the `Python
+Reference Manual <http://www.python.org/doc/2.2/ref/ref.html>`_. If you want to
+understand the complete implementation and design rationale for a change, refer
+to the PEP for a particular new feature.
+
+
+.. seealso::
+
+ http://www.unixreview.com/documents/s=1356/urm0109h/0109h.htm
+ "What's So Special About Python 2.2?" is also about the new 2.2 features, and
+ was written by Cameron Laird and Kathryn Soraiz.
+
+.. % ======================================================================
+
+
+PEPs 252 and 253: Type and Class Changes
+========================================
+
+The largest and most far-reaching changes in Python 2.2 are to Python's model of
+objects and classes. The changes should be backward compatible, so it's likely
+that your code will continue to run unchanged, but the changes provide some
+amazing new capabilities. Before beginning this, the longest and most
+complicated section of this article, I'll provide an overview of the changes and
+offer some comments.
+
+A long time ago I wrote a Web page (http://www.amk.ca/python/writing/warts.html)
+listing flaws in Python's design. One of the most significant flaws was that
+it's impossible to subclass Python types implemented in C. In particular, it's
+not possible to subclass built-in types, so you can't just subclass, say, lists
+in order to add a single useful method to them. The :mod:`UserList` module
+provides a class that supports all of the methods of lists and that can be
+subclassed further, but there's lots of C code that expects a regular Python
+list and won't accept a :class:`UserList` instance.
+
+Python 2.2 fixes this, and in the process adds some exciting new capabilities.
+A brief summary:
+
+* You can subclass built-in types such as lists and even integers, and your
+ subclasses should work in every place that requires the original type.
+
+* It's now possible to define static and class methods, in addition to the
+ instance methods available in previous versions of Python.
+
+* It's also possible to automatically call methods on accessing or setting an
+ instance attribute by using a new mechanism called :dfn:`properties`. Many uses
+ of :meth:`__getattr__` can be rewritten to use properties instead, making the
+ resulting code simpler and faster. As a small side benefit, attributes can now
+ have docstrings, too.
+
+* The list of legal attributes for an instance can be limited to a particular
+ set using :dfn:`slots`, making it possible to safeguard against typos and
+ perhaps make more optimizations possible in future versions of Python.
+
+Some users have voiced concern about all these changes. Sure, they say, the new
+features are neat and lend themselves to all sorts of tricks that weren't
+possible in previous versions of Python, but they also make the language more
+complicated. Some people have said that they've always recommended Python for
+its simplicity, and feel that its simplicity is being lost.
+
+Personally, I think there's no need to worry. Many of the new features are
+quite esoteric, and you can write a lot of Python code without ever needed to be
+aware of them. Writing a simple class is no more difficult than it ever was, so
+you don't need to bother learning or teaching them unless they're actually
+needed. Some very complicated tasks that were previously only possible from C
+will now be possible in pure Python, and to my mind that's all for the better.
+
+I'm not going to attempt to cover every single corner case and small change that
+were required to make the new features work. Instead this section will paint
+only the broad strokes. See section :ref:`sect-rellinks`, "Related Links", for
+further sources of information about Python 2.2's new object model.
+
+
+Old and New Classes
+-------------------
+
+First, you should know that Python 2.2 really has two kinds of classes: classic
+or old-style classes, and new-style classes. The old-style class model is
+exactly the same as the class model in earlier versions of Python. All the new
+features described in this section apply only to new-style classes. This
+divergence isn't intended to last forever; eventually old-style classes will be
+dropped, possibly in Python 3.0.
+
+So how do you define a new-style class? You do it by subclassing an existing
+new-style class. Most of Python's built-in types, such as integers, lists,
+dictionaries, and even files, are new-style classes now. A new-style class
+named :class:`object`, the base class for all built-in types, has also been
+added so if no built-in type is suitable, you can just subclass
+:class:`object`::
+
+ class C(object):
+ def __init__ (self):
+ ...
+ ...
+
+This means that :keyword:`class` statements that don't have any base classes are
+always classic classes in Python 2.2. (Actually you can also change this by
+setting a module-level variable named :attr:`__metaclass__` --- see :pep:`253`
+for the details --- but it's easier to just subclass :keyword:`object`.)
+
+The type objects for the built-in types are available as built-ins, named using
+a clever trick. Python has always had built-in functions named :func:`int`,
+:func:`float`, and :func:`str`. In 2.2, they aren't functions any more, but
+type objects that behave as factories when called. ::
+
+ >>> int
+ <type 'int'>
+ >>> int('123')
+ 123
+
+To make the set of types complete, new type objects such as :func:`dict` and
+:func:`file` have been added. Here's a more interesting example, adding a
+:meth:`lock` method to file objects::
+
+ class LockableFile(file):
+ def lock (self, operation, length=0, start=0, whence=0):
+ import fcntl
+ return fcntl.lockf(self.fileno(), operation,
+ length, start, whence)
+
+The now-obsolete :mod:`posixfile` module contained a class that emulated all of
+a file object's methods and also added a :meth:`lock` method, but this class
+couldn't be passed to internal functions that expected a built-in file,
+something which is possible with our new :class:`LockableFile`.
+
+
+Descriptors
+-----------
+
+In previous versions of Python, there was no consistent way to discover what
+attributes and methods were supported by an object. There were some informal
+conventions, such as defining :attr:`__members__` and :attr:`__methods__`
+attributes that were lists of names, but often the author of an extension type
+or a class wouldn't bother to define them. You could fall back on inspecting
+the :attr:`__dict__` of an object, but when class inheritance or an arbitrary
+:meth:`__getattr__` hook were in use this could still be inaccurate.
+
+The one big idea underlying the new class model is that an API for describing
+the attributes of an object using :dfn:`descriptors` has been formalized.
+Descriptors specify the value of an attribute, stating whether it's a method or
+a field. With the descriptor API, static methods and class methods become
+possible, as well as more exotic constructs.
+
+Attribute descriptors are objects that live inside class objects, and have a few
+attributes of their own:
+
+* :attr:`__name__` is the attribute's name.
+
+* :attr:`__doc__` is the attribute's docstring.
+
+* :meth:`__get__(object)` is a method that retrieves the attribute value from
+ *object*.
+
+* :meth:`__set__(object, value)` sets the attribute on *object* to *value*.
+
+* :meth:`__delete__(object, value)` deletes the *value* attribute of *object*.
+
+For example, when you write ``obj.x``, the steps that Python actually performs
+are::
+
+ descriptor = obj.__class__.x
+ descriptor.__get__(obj)
+
+For methods, :meth:`descriptor.__get__` returns a temporary object that's
+callable, and wraps up the instance and the method to be called on it. This is
+also why static methods and class methods are now possible; they have
+descriptors that wrap up just the method, or the method and the class. As a
+brief explanation of these new kinds of methods, static methods aren't passed
+the instance, and therefore resemble regular functions. Class methods are
+passed the class of the object, but not the object itself. Static and class
+methods are defined like this::
+
+ class C(object):
+ def f(arg1, arg2):
+ ...
+ f = staticmethod(f)
+
+ def g(cls, arg1, arg2):
+ ...
+ g = classmethod(g)
+
+The :func:`staticmethod` function takes the function :func:`f`, and returns it
+wrapped up in a descriptor so it can be stored in the class object. You might
+expect there to be special syntax for creating such methods (``def static f``,
+``defstatic f()``, or something like that) but no such syntax has been defined
+yet; that's been left for future versions of Python.
+
+More new features, such as slots and properties, are also implemented as new
+kinds of descriptors, and it's not difficult to write a descriptor class that
+does something novel. For example, it would be possible to write a descriptor
+class that made it possible to write Eiffel-style preconditions and
+postconditions for a method. A class that used this feature might be defined
+like this::
+
+ from eiffel import eiffelmethod
+
+ class C(object):
+ def f(self, arg1, arg2):
+ # The actual function
+ ...
+ def pre_f(self):
+ # Check preconditions
+ ...
+ def post_f(self):
+ # Check postconditions
+ ...
+
+ f = eiffelmethod(f, pre_f, post_f)
+
+Note that a person using the new :func:`eiffelmethod` doesn't have to understand
+anything about descriptors. This is why I think the new features don't increase
+the basic complexity of the language. There will be a few wizards who need to
+know about it in order to write :func:`eiffelmethod` or the ZODB or whatever,
+but most users will just write code on top of the resulting libraries and ignore
+the implementation details.
+
+
+Multiple Inheritance: The Diamond Rule
+--------------------------------------
+
+Multiple inheritance has also been made more useful through changing the rules
+under which names are resolved. Consider this set of classes (diagram taken
+from :pep:`253` by Guido van Rossum)::
+
+ class A:
+ ^ ^ def save(self): ...
+ / \
+ / \
+ / \
+ / \
+ class B class C:
+ ^ ^ def save(self): ...
+ \ /
+ \ /
+ \ /
+ \ /
+ class D
+
+The lookup rule for classic classes is simple but not very smart; the base
+classes are searched depth-first, going from left to right. A reference to
+:meth:`D.save` will search the classes :class:`D`, :class:`B`, and then
+:class:`A`, where :meth:`save` would be found and returned. :meth:`C.save`
+would never be found at all. This is bad, because if :class:`C`'s :meth:`save`
+method is saving some internal state specific to :class:`C`, not calling it will
+result in that state never getting saved.
+
+New-style classes follow a different algorithm that's a bit more complicated to
+explain, but does the right thing in this situation. (Note that Python 2.3
+changes this algorithm to one that produces the same results in most cases, but
+produces more useful results for really complicated inheritance graphs.)
+
+#. List all the base classes, following the classic lookup rule and include a
+ class multiple times if it's visited repeatedly. In the above example, the list
+ of visited classes is [:class:`D`, :class:`B`, :class:`A`, :class:`C`,
+ :class:`A`].
+
+#. Scan the list for duplicated classes. If any are found, remove all but one
+ occurrence, leaving the *last* one in the list. In the above example, the list
+ becomes [:class:`D`, :class:`B`, :class:`C`, :class:`A`] after dropping
+ duplicates.
+
+Following this rule, referring to :meth:`D.save` will return :meth:`C.save`,
+which is the behaviour we're after. This lookup rule is the same as the one
+followed by Common Lisp. A new built-in function, :func:`super`, provides a way
+to get at a class's superclasses without having to reimplement Python's
+algorithm. The most commonly used form will be :func:`super(class, obj)`, which
+returns a bound superclass object (not the actual class object). This form
+will be used in methods to call a method in the superclass; for example,
+:class:`D`'s :meth:`save` method would look like this::
+
+ class D (B,C):
+ def save (self):
+ # Call superclass .save()
+ super(D, self).save()
+ # Save D's private information here
+ ...
+
+:func:`super` can also return unbound superclass objects when called as
+:func:`super(class)` or :func:`super(class1, class2)`, but this probably won't
+often be useful.
+
+
+Attribute Access
+----------------
+
+A fair number of sophisticated Python classes define hooks for attribute access
+using :meth:`__getattr__`; most commonly this is done for convenience, to make
+code more readable by automatically mapping an attribute access such as
+``obj.parent`` into a method call such as ``obj.get_parent``. Python 2.2 adds
+some new ways of controlling attribute access.
+
+First, :meth:`__getattr__(attr_name)` is still supported by new-style classes,
+and nothing about it has changed. As before, it will be called when an attempt
+is made to access ``obj.foo`` and no attribute named ``foo`` is found in the
+instance's dictionary.
+
+New-style classes also support a new method,
+:meth:`__getattribute__(attr_name)`. The difference between the two methods is
+that :meth:`__getattribute__` is *always* called whenever any attribute is
+accessed, while the old :meth:`__getattr__` is only called if ``foo`` isn't
+found in the instance's dictionary.
+
+However, Python 2.2's support for :dfn:`properties` will often be a simpler way
+to trap attribute references. Writing a :meth:`__getattr__` method is
+complicated because to avoid recursion you can't use regular attribute accesses
+inside them, and instead have to mess around with the contents of
+:attr:`__dict__`. :meth:`__getattr__` methods also end up being called by Python
+when it checks for other methods such as :meth:`__repr__` or :meth:`__coerce__`,
+and so have to be written with this in mind. Finally, calling a function on
+every attribute access results in a sizable performance loss.
+
+:class:`property` is a new built-in type that packages up three functions that
+get, set, or delete an attribute, and a docstring. For example, if you want to
+define a :attr:`size` attribute that's computed, but also settable, you could
+write::
+
+ class C(object):
+ def get_size (self):
+ result = ... computation ...
+ return result
+ def set_size (self, size):
+ ... compute something based on the size
+ and set internal state appropriately ...
+
+ # Define a property. The 'delete this attribute'
+ # method is defined as None, so the attribute
+ # can't be deleted.
+ size = property(get_size, set_size,
+ None,
+ "Storage size of this instance")
+
+That is certainly clearer and easier to write than a pair of
+:meth:`__getattr__`/:meth:`__setattr__` methods that check for the :attr:`size`
+attribute and handle it specially while retrieving all other attributes from the
+instance's :attr:`__dict__`. Accesses to :attr:`size` are also the only ones
+which have to perform the work of calling a function, so references to other
+attributes run at their usual speed.
+
+Finally, it's possible to constrain the list of attributes that can be
+referenced on an object using the new :attr:`__slots__` class attribute. Python
+objects are usually very dynamic; at any time it's possible to define a new
+attribute on an instance by just doing ``obj.new_attr=1``. A new-style class
+can define a class attribute named :attr:`__slots__` to limit the legal
+attributes to a particular set of names. An example will make this clear::
+
+ >>> class C(object):
+ ... __slots__ = ('template', 'name')
+ ...
+ >>> obj = C()
+ >>> print obj.template
+ None
+ >>> obj.template = 'Test'
+ >>> print obj.template
+ Test
+ >>> obj.newattr = None
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ AttributeError: 'C' object has no attribute 'newattr'
+
+Note how you get an :exc:`AttributeError` on the attempt to assign to an
+attribute not listed in :attr:`__slots__`.
+
+
+.. _sect-rellinks:
+
+Related Links
+-------------
+
+This section has just been a quick overview of the new features, giving enough
+of an explanation to start you programming, but many details have been
+simplified or ignored. Where should you go to get a more complete picture?
+
+http://www.python.org/2.2/descrintro.html is a lengthy tutorial introduction to
+the descriptor features, written by Guido van Rossum. If my description has
+whetted your appetite, go read this tutorial next, because it goes into much
+more detail about the new features while still remaining quite easy to read.
+
+Next, there are two relevant PEPs, :pep:`252` and :pep:`253`. :pep:`252` is
+titled "Making Types Look More Like Classes", and covers the descriptor API.
+:pep:`253` is titled "Subtyping Built-in Types", and describes the changes to
+type objects that make it possible to subtype built-in objects. :pep:`253` is
+the more complicated PEP of the two, and at a few points the necessary
+explanations of types and meta-types may cause your head to explode. Both PEPs
+were written and implemented by Guido van Rossum, with substantial assistance
+from the rest of the Zope Corp. team.
+
+Finally, there's the ultimate authority: the source code. Most of the machinery
+for the type handling is in :file:`Objects/typeobject.c`, but you should only
+resort to it after all other avenues have been exhausted, including posting a
+question to python-list or python-dev.
+
+.. % ======================================================================
+
+
+PEP 234: Iterators
+==================
+
+Another significant addition to 2.2 is an iteration interface at both the C and
+Python levels. Objects can define how they can be looped over by callers.
+
+In Python versions up to 2.1, the usual way to make ``for item in obj`` work is
+to define a :meth:`__getitem__` method that looks something like this::
+
+ def __getitem__(self, index):
+ return <next item>
+
+:meth:`__getitem__` is more properly used to define an indexing operation on an
+object so that you can write ``obj[5]`` to retrieve the sixth element. It's a
+bit misleading when you're using this only to support :keyword:`for` loops.
+Consider some file-like object that wants to be looped over; the *index*
+parameter is essentially meaningless, as the class probably assumes that a
+series of :meth:`__getitem__` calls will be made with *index* incrementing by
+one each time. In other words, the presence of the :meth:`__getitem__` method
+doesn't mean that using ``file[5]`` to randomly access the sixth element will
+work, though it really should.
+
+In Python 2.2, iteration can be implemented separately, and :meth:`__getitem__`
+methods can be limited to classes that really do support random access. The
+basic idea of iterators is simple. A new built-in function, :func:`iter(obj)`
+or ``iter(C, sentinel)``, is used to get an iterator. :func:`iter(obj)` returns
+an iterator for the object *obj*, while ``iter(C, sentinel)`` returns an
+iterator that will invoke the callable object *C* until it returns *sentinel* to
+signal that the iterator is done.
+
+Python classes can define an :meth:`__iter__` method, which should create and
+return a new iterator for the object; if the object is its own iterator, this
+method can just return ``self``. In particular, iterators will usually be their
+own iterators. Extension types implemented in C can implement a :attr:`tp_iter`
+function in order to return an iterator, and extension types that want to behave
+as iterators can define a :attr:`tp_iternext` function.
+
+So, after all this, what do iterators actually do? They have one required
+method, :meth:`next`, which takes no arguments and returns the next value. When
+there are no more values to be returned, calling :meth:`next` should raise the
+:exc:`StopIteration` exception. ::
+
+ >>> L = [1,2,3]
+ >>> i = iter(L)
+ >>> print i
+ <iterator object at 0x8116870>
+ >>> i.next()
+ 1
+ >>> i.next()
+ 2
+ >>> i.next()
+ 3
+ >>> i.next()
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ StopIteration
+ >>>
+
+In 2.2, Python's :keyword:`for` statement no longer expects a sequence; it
+expects something for which :func:`iter` will return an iterator. For backward
+compatibility and convenience, an iterator is automatically constructed for
+sequences that don't implement :meth:`__iter__` or a :attr:`tp_iter` slot, so
+``for i in [1,2,3]`` will still work. Wherever the Python interpreter loops
+over a sequence, it's been changed to use the iterator protocol. This means you
+can do things like this::
+
+ >>> L = [1,2,3]
+ >>> i = iter(L)
+ >>> a,b,c = i
+ >>> a,b,c
+ (1, 2, 3)
+
+Iterator support has been added to some of Python's basic types. Calling
+:func:`iter` on a dictionary will return an iterator which loops over its keys::
+
+ >>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,
+ ... 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12}
+ >>> for key in m: print key, m[key]
+ ...
+ Mar 3
+ Feb 2
+ Aug 8
+ Sep 9
+ May 5
+ Jun 6
+ Jul 7
+ Jan 1
+ Apr 4
+ Nov 11
+ Dec 12
+ Oct 10
+
+That's just the default behaviour. If you want to iterate over keys, values, or
+key/value pairs, you can explicitly call the :meth:`iterkeys`,
+:meth:`itervalues`, or :meth:`iteritems` methods to get an appropriate iterator.
+In a minor related change, the :keyword:`in` operator now works on dictionaries,
+so ``key in dict`` is now equivalent to ``dict.has_key(key)``.
+
+Files also provide an iterator, which calls the :meth:`readline` method until
+there are no more lines in the file. This means you can now read each line of a
+file using code like this::
+
+ for line in file:
+ # do something for each line
+ ...
+
+Note that you can only go forward in an iterator; there's no way to get the
+previous element, reset the iterator, or make a copy of it. An iterator object
+could provide such additional capabilities, but the iterator protocol only
+requires a :meth:`next` method.
+
+
+.. seealso::
+
+ :pep:`234` - Iterators
+ Written by Ka-Ping Yee and GvR; implemented by the Python Labs crew, mostly by
+ GvR and Tim Peters.
+
+.. % ======================================================================
+
+
+PEP 255: Simple Generators
+==========================
+
+Generators are another new feature, one that interacts with the introduction of
+iterators.
+
+You're doubtless familiar with how function calls work in Python or C. When you
+call a function, it gets a private namespace where its local variables are
+created. When the function reaches a :keyword:`return` statement, the local
+variables are destroyed and the resulting value is returned to the caller. A
+later call to the same function will get a fresh new set of local variables.
+But, what if the local variables weren't thrown away on exiting a function?
+What if you could later resume the function where it left off? This is what
+generators provide; they can be thought of as resumable functions.
+
+Here's the simplest example of a generator function::
+
+ def generate_ints(N):
+ for i in range(N):
+ yield i
+
+A new keyword, :keyword:`yield`, was introduced for generators. Any function
+containing a :keyword:`yield` statement is a generator function; this is
+detected by Python's bytecode compiler which compiles the function specially as
+a result. Because a new keyword was introduced, generators must be explicitly
+enabled in a module by including a ``from __future__ import generators``
+statement near the top of the module's source code. In Python 2.3 this
+statement will become unnecessary.
+
+When you call a generator function, it doesn't return a single value; instead it
+returns a generator object that supports the iterator protocol. On executing
+the :keyword:`yield` statement, the generator outputs the value of ``i``,
+similar to a :keyword:`return` statement. The big difference between
+:keyword:`yield` and a :keyword:`return` statement is that on reaching a
+:keyword:`yield` the generator's state of execution is suspended and local
+variables are preserved. On the next call to the generator's ``next()`` method,
+the function will resume executing immediately after the :keyword:`yield`
+statement. (For complicated reasons, the :keyword:`yield` statement isn't
+allowed inside the :keyword:`try` block of a :keyword:`try`...\
+:keyword:`finally` statement; read :pep:`255` for a full explanation of the
+interaction between :keyword:`yield` and exceptions.)
+
+Here's a sample usage of the :func:`generate_ints` generator::
+
+ >>> gen = generate_ints(3)
+ >>> gen
+ <generator object at 0x8117f90>
+ >>> gen.next()
+ 0
+ >>> gen.next()
+ 1
+ >>> gen.next()
+ 2
+ >>> gen.next()
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ File "<stdin>", line 2, in generate_ints
+ StopIteration
+
+You could equally write ``for i in generate_ints(5)``, or ``a,b,c =
+generate_ints(3)``.
+
+Inside a generator function, the :keyword:`return` statement can only be used
+without a value, and signals the end of the procession of values; afterwards the
+generator cannot return any further values. :keyword:`return` with a value, such
+as ``return 5``, is a syntax error inside a generator function. The end of the
+generator's results can also be indicated by raising :exc:`StopIteration`
+manually, or by just letting the flow of execution fall off the bottom of the
+function.
+
+You could achieve the effect of generators manually by writing your own class
+and storing all the local variables of the generator as instance variables. For
+example, returning a list of integers could be done by setting ``self.count`` to
+0, and having the :meth:`next` method increment ``self.count`` and return it.
+However, for a moderately complicated generator, writing a corresponding class
+would be much messier. :file:`Lib/test/test_generators.py` contains a number of
+more interesting examples. The simplest one implements an in-order traversal of
+a tree using generators recursively. ::
+
+ # A recursive generator that generates Tree leaves in in-order.
+ def inorder(t):
+ if t:
+ for x in inorder(t.left):
+ yield x
+ yield t.label
+ for x in inorder(t.right):
+ yield x
+
+Two other examples in :file:`Lib/test/test_generators.py` produce solutions for
+the N-Queens problem (placing $N$ queens on an $NxN$ chess board so that no
+queen threatens another) and the Knight's Tour (a route that takes a knight to
+every square of an $NxN$ chessboard without visiting any square twice).
+
+The idea of generators comes from other programming languages, especially Icon
+(http://www.cs.arizona.edu/icon/), where the idea of generators is central. In
+Icon, every expression and function call behaves like a generator. One example
+from "An Overview of the Icon Programming Language" at
+http://www.cs.arizona.edu/icon/docs/ipd266.htm gives an idea of what this looks
+like::
+
+ sentence := "Store it in the neighboring harbor"
+ if (i := find("or", sentence)) > 5 then write(i)
+
+In Icon the :func:`find` function returns the indexes at which the substring
+"or" is found: 3, 23, 33. In the :keyword:`if` statement, ``i`` is first
+assigned a value of 3, but 3 is less than 5, so the comparison fails, and Icon
+retries it with the second value of 23. 23 is greater than 5, so the comparison
+now succeeds, and the code prints the value 23 to the screen.
+
+Python doesn't go nearly as far as Icon in adopting generators as a central
+concept. Generators are considered a new part of the core Python language, but
+learning or using them isn't compulsory; if they don't solve any problems that
+you have, feel free to ignore them. One novel feature of Python's interface as
+compared to Icon's is that a generator's state is represented as a concrete
+object (the iterator) that can be passed around to other functions or stored in
+a data structure.
+
+
+.. seealso::
+
+ :pep:`255` - Simple Generators
+ Written by Neil Schemenauer, Tim Peters, Magnus Lie Hetland. Implemented mostly
+ by Neil Schemenauer and Tim Peters, with other fixes from the Python Labs crew.
+
+.. % ======================================================================
+
+
+PEP 237: Unifying Long Integers and Integers
+============================================
+
+In recent versions, the distinction between regular integers, which are 32-bit
+values on most machines, and long integers, which can be of arbitrary size, was
+becoming an annoyance. For example, on platforms that support files larger than
+``2**32`` bytes, the :meth:`tell` method of file objects has to return a long
+integer. However, there were various bits of Python that expected plain integers
+and would raise an error if a long integer was provided instead. For example,
+in Python 1.5, only regular integers could be used as a slice index, and
+``'abc'[1L:]`` would raise a :exc:`TypeError` exception with the message 'slice
+index must be int'.
+
+Python 2.2 will shift values from short to long integers as required. The 'L'
+suffix is no longer needed to indicate a long integer literal, as now the
+compiler will choose the appropriate type. (Using the 'L' suffix will be
+discouraged in future 2.x versions of Python, triggering a warning in Python
+2.4, and probably dropped in Python 3.0.) Many operations that used to raise an
+:exc:`OverflowError` will now return a long integer as their result. For
+example::
+
+ >>> 1234567890123
+ 1234567890123L
+ >>> 2 ** 64
+ 18446744073709551616L
+
+In most cases, integers and long integers will now be treated identically. You
+can still distinguish them with the :func:`type` built-in function, but that's
+rarely needed.
+
+
+.. seealso::
+
+ :pep:`237` - Unifying Long Integers and Integers
+ Written by Moshe Zadka and Guido van Rossum. Implemented mostly by Guido van
+ Rossum.
+
+.. % ======================================================================
+
+
+PEP 238: Changing the Division Operator
+=======================================
+
+The most controversial change in Python 2.2 heralds the start of an effort to
+fix an old design flaw that's been in Python from the beginning. Currently
+Python's division operator, ``/``, behaves like C's division operator when
+presented with two integer arguments: it returns an integer result that's
+truncated down when there would be a fractional part. For example, ``3/2`` is
+1, not 1.5, and ``(-1)/2`` is -1, not -0.5. This means that the results of
+divison can vary unexpectedly depending on the type of the two operands and
+because Python is dynamically typed, it can be difficult to determine the
+possible types of the operands.
+
+(The controversy is over whether this is *really* a design flaw, and whether
+it's worth breaking existing code to fix this. It's caused endless discussions
+on python-dev, and in July 2001 erupted into an storm of acidly sarcastic
+postings on :newsgroup:`comp.lang.python`. I won't argue for either side here
+and will stick to describing what's implemented in 2.2. Read :pep:`238` for a
+summary of arguments and counter-arguments.)
+
+Because this change might break code, it's being introduced very gradually.
+Python 2.2 begins the transition, but the switch won't be complete until Python
+3.0.
+
+First, I'll borrow some terminology from :pep:`238`. "True division" is the
+division that most non-programmers are familiar with: 3/2 is 1.5, 1/4 is 0.25,
+and so forth. "Floor division" is what Python's ``/`` operator currently does
+when given integer operands; the result is the floor of the value returned by
+true division. "Classic division" is the current mixed behaviour of ``/``; it
+returns the result of floor division when the operands are integers, and returns
+the result of true division when one of the operands is a floating-point number.
+
+Here are the changes 2.2 introduces:
+
+* A new operator, ``//``, is the floor division operator. (Yes, we know it looks
+ like C++'s comment symbol.) ``//`` *always* performs floor division no matter
+ what the types of its operands are, so ``1 // 2`` is 0 and ``1.0 // 2.0`` is
+ also 0.0.
+
+ ``//`` is always available in Python 2.2; you don't need to enable it using a
+ ``__future__`` statement.
+
+* By including a ``from __future__ import division`` in a module, the ``/``
+ operator will be changed to return the result of true division, so ``1/2`` is
+ 0.5. Without the ``__future__`` statement, ``/`` still means classic division.
+ The default meaning of ``/`` will not change until Python 3.0.
+
+* Classes can define methods called :meth:`__truediv__` and :meth:`__floordiv__`
+ to overload the two division operators. At the C level, there are also slots in
+ the :ctype:`PyNumberMethods` structure so extension types can define the two
+ operators.
+
+* Python 2.2 supports some command-line arguments for testing whether code will
+ works with the changed division semantics. Running python with :option:`-Q
+ warn` will cause a warning to be issued whenever division is applied to two
+ integers. You can use this to find code that's affected by the change and fix
+ it. By default, Python 2.2 will simply perform classic division without a
+ warning; the warning will be turned on by default in Python 2.3.
+
+
+.. seealso::
+
+ :pep:`238` - Changing the Division Operator
+ Written by Moshe Zadka and Guido van Rossum. Implemented by Guido van Rossum..
+
+.. % ======================================================================
+
+
+Unicode Changes
+===============
+
+Python's Unicode support has been enhanced a bit in 2.2. Unicode strings are
+usually stored as UCS-2, as 16-bit unsigned integers. Python 2.2 can also be
+compiled to use UCS-4, 32-bit unsigned integers, as its internal encoding by
+supplying :option:`--enable-unicode=ucs4` to the configure script. (It's also
+possible to specify :option:`--disable-unicode` to completely disable Unicode
+support.)
+
+When built to use UCS-4 (a "wide Python"), the interpreter can natively handle
+Unicode characters from U+000000 to U+110000, so the range of legal values for
+the :func:`unichr` function is expanded accordingly. Using an interpreter
+compiled to use UCS-2 (a "narrow Python"), values greater than 65535 will still
+cause :func:`unichr` to raise a :exc:`ValueError` exception. This is all
+described in :pep:`261`, "Support for 'wide' Unicode characters"; consult it for
+further details.
+
+Another change is simpler to explain. Since their introduction, Unicode strings
+have supported an :meth:`encode` method to convert the string to a selected
+encoding such as UTF-8 or Latin-1. A symmetric :meth:`decode([*encoding*])`
+method has been added to 8-bit strings (though not to Unicode strings) in 2.2.
+:meth:`decode` assumes that the string is in the specified encoding and decodes
+it, returning whatever is returned by the codec.
+
+Using this new feature, codecs have been added for tasks not directly related to
+Unicode. For example, codecs have been added for uu-encoding, MIME's base64
+encoding, and compression with the :mod:`zlib` module::
+
+ >>> s = """Here is a lengthy piece of redundant, overly verbose,
+ ... and repetitive text.
+ ... """
+ >>> data = s.encode('zlib')
+ >>> data
+ 'x\x9c\r\xc9\xc1\r\x80 \x10\x04\xc0?Ul...'
+ >>> data.decode('zlib')
+ 'Here is a lengthy piece of redundant, overly verbose,\nand repetitive text.\n'
+ >>> print s.encode('uu')
+ begin 666 <data>
+ M2&5R92!I<R!A(&QE;F=T:'D@<&EE8V4@;V8@<F5D=6YD86YT+"!O=F5R;'D@
+ >=F5R8F]S92P*86YD(')E<&5T:71I=F4@=&5X="X*
+
+ end
+ >>> "sheesh".encode('rot-13')
+ 'furrfu'
+
+To convert a class instance to Unicode, a :meth:`__unicode__` method can be
+defined by a class, analogous to :meth:`__str__`.
+
+:meth:`encode`, :meth:`decode`, and :meth:`__unicode__` were implemented by
+Marc-André Lemburg. The changes to support using UCS-4 internally were
+implemented by Fredrik Lundh and Martin von Löwis.
+
+
+.. seealso::
+
+ :pep:`261` - Support for 'wide' Unicode characters
+ Written by Paul Prescod.
+
+.. % ======================================================================
+
+
+PEP 227: Nested Scopes
+======================
+
+In Python 2.1, statically nested scopes were added as an optional feature, to be
+enabled by a ``from __future__ import nested_scopes`` directive. In 2.2 nested
+scopes no longer need to be specially enabled, and are now always present. The
+rest of this section is a copy of the description of nested scopes from my
+"What's New in Python 2.1" document; if you read it when 2.1 came out, you can
+skip the rest of this section.
+
+The largest change introduced in Python 2.1, and made complete in 2.2, is to
+Python's scoping rules. In Python 2.0, at any given time there are at most
+three namespaces used to look up variable names: local, module-level, and the
+built-in namespace. This often surprised people because it didn't match their
+intuitive expectations. For example, a nested recursive function definition
+doesn't work::
+
+ def f():
+ ...
+ def g(value):
+ ...
+ return g(value-1) + 1
+ ...
+
+The function :func:`g` will always raise a :exc:`NameError` exception, because
+the binding of the name ``g`` isn't in either its local namespace or in the
+module-level namespace. This isn't much of a problem in practice (how often do
+you recursively define interior functions like this?), but this also made using
+the :keyword:`lambda` statement clumsier, and this was a problem in practice.
+In code which uses :keyword:`lambda` you can often find local variables being
+copied by passing them as the default values of arguments. ::
+
+ def find(self, name):
+ "Return list of any entries equal to 'name'"
+ L = filter(lambda x, name=name: x == name,
+ self.list_attribute)
+ return L
+
+The readability of Python code written in a strongly functional style suffers
+greatly as a result.
+
+The most significant change to Python 2.2 is that static scoping has been added
+to the language to fix this problem. As a first effect, the ``name=name``
+default argument is now unnecessary in the above example. Put simply, when a
+given variable name is not assigned a value within a function (by an assignment,
+or the :keyword:`def`, :keyword:`class`, or :keyword:`import` statements),
+references to the variable will be looked up in the local namespace of the
+enclosing scope. A more detailed explanation of the rules, and a dissection of
+the implementation, can be found in the PEP.
+
+This change may cause some compatibility problems for code where the same
+variable name is used both at the module level and as a local variable within a
+function that contains further function definitions. This seems rather unlikely
+though, since such code would have been pretty confusing to read in the first
+place.
+
+One side effect of the change is that the ``from module import *`` and
+:keyword:`exec` statements have been made illegal inside a function scope under
+certain conditions. The Python reference manual has said all along that ``from
+module import *`` is only legal at the top level of a module, but the CPython
+interpreter has never enforced this before. As part of the implementation of
+nested scopes, the compiler which turns Python source into bytecodes has to
+generate different code to access variables in a containing scope. ``from
+module import *`` and :keyword:`exec` make it impossible for the compiler to
+figure this out, because they add names to the local namespace that are
+unknowable at compile time. Therefore, if a function contains function
+definitions or :keyword:`lambda` expressions with free variables, the compiler
+will flag this by raising a :exc:`SyntaxError` exception.
+
+To make the preceding explanation a bit clearer, here's an example::
+
+ x = 1
+ def f():
+ # The next line is a syntax error
+ exec 'x=2'
+ def g():
+ return x
+
+Line 4 containing the :keyword:`exec` statement is a syntax error, since
+:keyword:`exec` would define a new local variable named ``x`` whose value should
+be accessed by :func:`g`.
+
+This shouldn't be much of a limitation, since :keyword:`exec` is rarely used in
+most Python code (and when it is used, it's often a sign of a poor design
+anyway).
+
+
+.. seealso::
+
+ :pep:`227` - Statically Nested Scopes
+ Written and implemented by Jeremy Hylton.
+
+.. % ======================================================================
+
+
+New and Improved Modules
+========================
+
+* The :mod:`xmlrpclib` module was contributed to the standard library by Fredrik
+ Lundh, providing support for writing XML-RPC clients. XML-RPC is a simple
+ remote procedure call protocol built on top of HTTP and XML. For example, the
+ following snippet retrieves a list of RSS channels from the O'Reilly Network,
+ and then lists the recent headlines for one channel::
+
+ import xmlrpclib
+ s = xmlrpclib.Server(
+ 'http://www.oreillynet.com/meerkat/xml-rpc/server.php')
+ channels = s.meerkat.getChannels()
+ # channels is a list of dictionaries, like this:
+ # [{'id': 4, 'title': 'Freshmeat Daily News'}
+ # {'id': 190, 'title': '32Bits Online'},
+ # {'id': 4549, 'title': '3DGamers'}, ... ]
+
+ # Get the items for one channel
+ items = s.meerkat.getItems( {'channel': 4} )
+
+ # 'items' is another list of dictionaries, like this:
+ # [{'link': 'http://freshmeat.net/releases/52719/',
+ # 'description': 'A utility which converts HTML to XSL FO.',
+ # 'title': 'html2fo 0.3 (Default)'}, ... ]
+
+ The :mod:`SimpleXMLRPCServer` module makes it easy to create straightforward
+ XML-RPC servers. See http://www.xmlrpc.com/ for more information about XML-RPC.
+
+* The new :mod:`hmac` module implements the HMAC algorithm described by
+ :rfc:`2104`. (Contributed by Gerhard Häring.)
+
+* Several functions that originally returned lengthy tuples now return pseudo-
+ sequences that still behave like tuples but also have mnemonic attributes such
+ as memberst_mtime or :attr:`tm_year`. The enhanced functions include
+ :func:`stat`, :func:`fstat`, :func:`statvfs`, and :func:`fstatvfs` in the
+ :mod:`os` module, and :func:`localtime`, :func:`gmtime`, and :func:`strptime` in
+ the :mod:`time` module.
+
+ For example, to obtain a file's size using the old tuples, you'd end up writing
+ something like ``file_size = os.stat(filename)[stat.ST_SIZE]``, but now this can
+ be written more clearly as ``file_size = os.stat(filename).st_size``.
+
+ The original patch for this feature was contributed by Nick Mathewson.
+
+* The Python profiler has been extensively reworked and various errors in its
+ output have been corrected. (Contributed by Fred L. Drake, Jr. and Tim Peters.)
+
+* The :mod:`socket` module can be compiled to support IPv6; specify the
+ :option:`--enable-ipv6` option to Python's configure script. (Contributed by
+ Jun-ichiro "itojun" Hagino.)
+
+* Two new format characters were added to the :mod:`struct` module for 64-bit
+ integers on platforms that support the C :ctype:`long long` type. ``q`` is for
+ a signed 64-bit integer, and ``Q`` is for an unsigned one. The value is
+ returned in Python's long integer type. (Contributed by Tim Peters.)
+
+* In the interpreter's interactive mode, there's a new built-in function
+ :func:`help` that uses the :mod:`pydoc` module introduced in Python 2.1 to
+ provide interactive help. ``help(object)`` displays any available help text
+ about *object*. :func:`help` with no argument puts you in an online help
+ utility, where you can enter the names of functions, classes, or modules to read
+ their help text. (Contributed by Guido van Rossum, using Ka-Ping Yee's
+ :mod:`pydoc` module.)
+
+* Various bugfixes and performance improvements have been made to the SRE engine
+ underlying the :mod:`re` module. For example, the :func:`re.sub` and
+ :func:`re.split` functions have been rewritten in C. Another contributed patch
+ speeds up certain Unicode character ranges by a factor of two, and a new
+ :meth:`finditer` method that returns an iterator over all the non-overlapping
+ matches in a given string. (SRE is maintained by Fredrik Lundh. The
+ BIGCHARSET patch was contributed by Martin von Löwis.)
+
+* The :mod:`smtplib` module now supports :rfc:`2487`, "Secure SMTP over TLS", so
+ it's now possible to encrypt the SMTP traffic between a Python program and the
+ mail transport agent being handed a message. :mod:`smtplib` also supports SMTP
+ authentication. (Contributed by Gerhard Häring.)
+
+* The :mod:`imaplib` module, maintained by Piers Lauder, has support for several
+ new extensions: the NAMESPACE extension defined in :rfc:`2342`, SORT, GETACL and
+ SETACL. (Contributed by Anthony Baxter and Michel Pelletier.)
+
+* The :mod:`rfc822` module's parsing of email addresses is now compliant with
+ :rfc:`2822`, an update to :rfc:`822`. (The module's name is *not* going to be
+ changed to ``rfc2822``.) A new package, :mod:`email`, has also been added for
+ parsing and generating e-mail messages. (Contributed by Barry Warsaw, and
+ arising out of his work on Mailman.)
+
+* The :mod:`difflib` module now contains a new :class:`Differ` class for
+ producing human-readable lists of changes (a "delta") between two sequences of
+ lines of text. There are also two generator functions, :func:`ndiff` and
+ :func:`restore`, which respectively return a delta from two sequences, or one of
+ the original sequences from a delta. (Grunt work contributed by David Goodger,
+ from ndiff.py code by Tim Peters who then did the generatorization.)
+
+* New constants :const:`ascii_letters`, :const:`ascii_lowercase`, and
+ :const:`ascii_uppercase` were added to the :mod:`string` module. There were
+ several modules in the standard library that used :const:`string.letters` to
+ mean the ranges A-Za-z, but that assumption is incorrect when locales are in
+ use, because :const:`string.letters` varies depending on the set of legal
+ characters defined by the current locale. The buggy modules have all been fixed
+ to use :const:`ascii_letters` instead. (Reported by an unknown person; fixed by
+ Fred L. Drake, Jr.)
+
+* The :mod:`mimetypes` module now makes it easier to use alternative MIME-type
+ databases by the addition of a :class:`MimeTypes` class, which takes a list of
+ filenames to be parsed. (Contributed by Fred L. Drake, Jr.)
+
+* A :class:`Timer` class was added to the :mod:`threading` module that allows
+ scheduling an activity to happen at some future time. (Contributed by Itamar
+ Shtull-Trauring.)
+
+.. % ======================================================================
+
+
+Interpreter Changes and Fixes
+=============================
+
+Some of the changes only affect people who deal with the Python interpreter at
+the C level because they're writing Python extension modules, embedding the
+interpreter, or just hacking on the interpreter itself. If you only write Python
+code, none of the changes described here will affect you very much.
+
+* Profiling and tracing functions can now be implemented in C, which can operate
+ at much higher speeds than Python-based functions and should reduce the overhead
+ of profiling and tracing. This will be of interest to authors of development
+ environments for Python. Two new C functions were added to Python's API,
+ :cfunc:`PyEval_SetProfile` and :cfunc:`PyEval_SetTrace`. The existing
+ :func:`sys.setprofile` and :func:`sys.settrace` functions still exist, and have
+ simply been changed to use the new C-level interface. (Contributed by Fred L.
+ Drake, Jr.)
+
+* Another low-level API, primarily of interest to implementors of Python
+ debuggers and development tools, was added. :cfunc:`PyInterpreterState_Head` and
+ :cfunc:`PyInterpreterState_Next` let a caller walk through all the existing
+ interpreter objects; :cfunc:`PyInterpreterState_ThreadHead` and
+ :cfunc:`PyThreadState_Next` allow looping over all the thread states for a given
+ interpreter. (Contributed by David Beazley.)
+
+* The C-level interface to the garbage collector has been changed to make it
+ easier to write extension types that support garbage collection and to debug
+ misuses of the functions. Various functions have slightly different semantics,
+ so a bunch of functions had to be renamed. Extensions that use the old API will
+ still compile but will *not* participate in garbage collection, so updating them
+ for 2.2 should be considered fairly high priority.
+
+ To upgrade an extension module to the new API, perform the following steps:
+
+* Rename :cfunc:`Py_TPFLAGS_GC` to :cfunc:`PyTPFLAGS_HAVE_GC`.
+
+* Use :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_NewVar` to allocate
+ objects, and :cfunc:`PyObject_GC_Del` to deallocate them.
+
+* Rename :cfunc:`PyObject_GC_Init` to :cfunc:`PyObject_GC_Track` and
+ :cfunc:`PyObject_GC_Fini` to :cfunc:`PyObject_GC_UnTrack`.
+
+* Remove :cfunc:`PyGC_HEAD_SIZE` from object size calculations.
+
+* Remove calls to :cfunc:`PyObject_AS_GC` and :cfunc:`PyObject_FROM_GC`.
+
+* A new ``et`` format sequence was added to :cfunc:`PyArg_ParseTuple`; ``et``
+ takes both a parameter and an encoding name, and converts the parameter to the
+ given encoding if the parameter turns out to be a Unicode string, or leaves it
+ alone if it's an 8-bit string, assuming it to already be in the desired
+ encoding. This differs from the ``es`` format character, which assumes that
+ 8-bit strings are in Python's default ASCII encoding and converts them to the
+ specified new encoding. (Contributed by M.-A. Lemburg, and used for the MBCS
+ support on Windows described in the following section.)
+
+* A different argument parsing function, :cfunc:`PyArg_UnpackTuple`, has been
+ added that's simpler and presumably faster. Instead of specifying a format
+ string, the caller simply gives the minimum and maximum number of arguments
+ expected, and a set of pointers to :ctype:`PyObject\*` variables that will be
+ filled in with argument values.
+
+* Two new flags :const:`METH_NOARGS` and :const:`METH_O` are available in method
+ definition tables to simplify implementation of methods with no arguments or a
+ single untyped argument. Calling such methods is more efficient than calling a
+ corresponding method that uses :const:`METH_VARARGS`. Also, the old
+ :const:`METH_OLDARGS` style of writing C methods is now officially deprecated.
+
+* Two new wrapper functions, :cfunc:`PyOS_snprintf` and :cfunc:`PyOS_vsnprintf`
+ were added to provide cross-platform implementations for the relatively new
+ :cfunc:`snprintf` and :cfunc:`vsnprintf` C lib APIs. In contrast to the standard
+ :cfunc:`sprintf` and :cfunc:`vsprintf` functions, the Python versions check the
+ bounds of the buffer used to protect against buffer overruns. (Contributed by
+ M.-A. Lemburg.)
+
+* The :cfunc:`_PyTuple_Resize` function has lost an unused parameter, so now it
+ takes 2 parameters instead of 3. The third argument was never used, and can
+ simply be discarded when porting code from earlier versions to Python 2.2.
+
+.. % ======================================================================
+
+
+Other Changes and Fixes
+=======================
+
+As usual there were a bunch of other improvements and bugfixes scattered
+throughout the source tree. A search through the CVS change logs finds there
+were 527 patches applied and 683 bugs fixed between Python 2.1 and 2.2; 2.2.1
+applied 139 patches and fixed 143 bugs; 2.2.2 applied 106 patches and fixed 82
+bugs. These figures are likely to be underestimates.
+
+Some of the more notable changes are:
+
+* The code for the MacOS port for Python, maintained by Jack Jansen, is now kept
+ in the main Python CVS tree, and many changes have been made to support MacOS X.
+
+ The most significant change is the ability to build Python as a framework,
+ enabled by supplying the :option:`--enable-framework` option to the configure
+ script when compiling Python. According to Jack Jansen, "This installs a self-
+ contained Python installation plus the OS X framework "glue" into
+ :file:`/Library/Frameworks/Python.framework` (or another location of choice).
+ For now there is little immediate added benefit to this (actually, there is the
+ disadvantage that you have to change your PATH to be able to find Python), but
+ it is the basis for creating a full-blown Python application, porting the
+ MacPython IDE, possibly using Python as a standard OSA scripting language and
+ much more."
+
+ Most of the MacPython toolbox modules, which interface to MacOS APIs such as
+ windowing, QuickTime, scripting, etc. have been ported to OS X, but they've been
+ left commented out in :file:`setup.py`. People who want to experiment with
+ these modules can uncomment them manually.
+
+ .. % Jack's original comments:
+ .. % The main change is the possibility to build Python as a
+ .. % framework. This installs a self-contained Python installation plus the
+ .. % OSX framework "glue" into /Library/Frameworks/Python.framework (or
+ .. % another location of choice). For now there is little immedeate added
+ .. % benefit to this (actually, there is the disadvantage that you have to
+ .. % change your PATH to be able to find Python), but it is the basis for
+ .. % creating a fullblown Python application, porting the MacPython IDE,
+ .. % possibly using Python as a standard OSA scripting language and much
+ .. % more. You enable this with "configure --enable-framework".
+ .. % The other change is that most MacPython toolbox modules, which
+ .. % interface to all the MacOS APIs such as windowing, quicktime,
+ .. % scripting, etc. have been ported. Again, most of these are not of
+ .. % immedeate use, as they need a full application to be really useful, so
+ .. % they have been commented out in setup.py. People wanting to experiment
+ .. % can uncomment them. Gestalt and Internet Config modules are enabled by
+ .. % default.
+
+* Keyword arguments passed to builtin functions that don't take them now cause a
+ :exc:`TypeError` exception to be raised, with the message "*function* takes no
+ keyword arguments".
+
+* Weak references, added in Python 2.1 as an extension module, are now part of
+ the core because they're used in the implementation of new-style classes. The
+ :exc:`ReferenceError` exception has therefore moved from the :mod:`weakref`
+ module to become a built-in exception.
+
+* A new script, :file:`Tools/scripts/cleanfuture.py` by Tim Peters,
+ automatically removes obsolete ``__future__`` statements from Python source
+ code.
+
+* An additional *flags* argument has been added to the built-in function
+ :func:`compile`, so the behaviour of ``__future__`` statements can now be
+ correctly observed in simulated shells, such as those presented by IDLE and
+ other development environments. This is described in :pep:`264`. (Contributed
+ by Michael Hudson.)
+
+* The new license introduced with Python 1.6 wasn't GPL-compatible. This is
+ fixed by some minor textual changes to the 2.2 license, so it's now legal to
+ embed Python inside a GPLed program again. Note that Python itself is not
+ GPLed, but instead is under a license that's essentially equivalent to the BSD
+ license, same as it always was. The license changes were also applied to the
+ Python 2.0.1 and 2.1.1 releases.
+
+* When presented with a Unicode filename on Windows, Python will now convert it
+ to an MBCS encoded string, as used by the Microsoft file APIs. As MBCS is
+ explicitly used by the file APIs, Python's choice of ASCII as the default
+ encoding turns out to be an annoyance. On Unix, the locale's character set is
+ used if :func:`locale.nl_langinfo(CODESET)` is available. (Windows support was
+ contributed by Mark Hammond with assistance from Marc-André Lemburg. Unix
+ support was added by Martin von Löwis.)
+
+* Large file support is now enabled on Windows. (Contributed by Tim Peters.)
+
+* The :file:`Tools/scripts/ftpmirror.py` script now parses a :file:`.netrc`
+ file, if you have one. (Contributed by Mike Romberg.)
+
+* Some features of the object returned by the :func:`xrange` function are now
+ deprecated, and trigger warnings when they're accessed; they'll disappear in
+ Python 2.3. :class:`xrange` objects tried to pretend they were full sequence
+ types by supporting slicing, sequence multiplication, and the :keyword:`in`
+ operator, but these features were rarely used and therefore buggy. The
+ :meth:`tolist` method and the :attr:`start`, :attr:`stop`, and :attr:`step`
+ attributes are also being deprecated. At the C level, the fourth argument to
+ the :cfunc:`PyRange_New` function, ``repeat``, has also been deprecated.
+
+* There were a bunch of patches to the dictionary implementation, mostly to fix
+ potential core dumps if a dictionary contains objects that sneakily changed
+ their hash value, or mutated the dictionary they were contained in. For a while
+ python-dev fell into a gentle rhythm of Michael Hudson finding a case that
+ dumped core, Tim Peters fixing the bug, Michael finding another case, and round
+ and round it went.
+
+* On Windows, Python can now be compiled with Borland C thanks to a number of
+ patches contributed by Stephen Hansen, though the result isn't fully functional
+ yet. (But this *is* progress...)
+
+* Another Windows enhancement: Wise Solutions generously offered PythonLabs use
+ of their InstallerMaster 8.1 system. Earlier PythonLabs Windows installers used
+ Wise 5.0a, which was beginning to show its age. (Packaged up by Tim Peters.)
+
+* Files ending in ``.pyw`` can now be imported on Windows. ``.pyw`` is a
+ Windows-only thing, used to indicate that a script needs to be run using
+ PYTHONW.EXE instead of PYTHON.EXE in order to prevent a DOS console from popping
+ up to display the output. This patch makes it possible to import such scripts,
+ in case they're also usable as modules. (Implemented by David Bolen.)
+
+* On platforms where Python uses the C :cfunc:`dlopen` function to load
+ extension modules, it's now possible to set the flags used by :cfunc:`dlopen`
+ using the :func:`sys.getdlopenflags` and :func:`sys.setdlopenflags` functions.
+ (Contributed by Bram Stolk.)
+
+* The :func:`pow` built-in function no longer supports 3 arguments when
+ floating-point numbers are supplied. ``pow(x, y, z)`` returns ``(x**y) % z``,
+ but this is never useful for floating point numbers, and the final result varies
+ unpredictably depending on the platform. A call such as ``pow(2.0, 8.0, 7.0)``
+ will now raise a :exc:`TypeError` exception.
+
+.. % ======================================================================
+
+
+Acknowledgements
+================
+
+The author would like to thank the following people for offering suggestions,
+corrections and assistance with various drafts of this article: Fred Bremmer,
+Keith Briggs, Andrew Dalke, Fred L. Drake, Jr., Carel Fellinger, David Goodger,
+Mark Hammond, Stephen Hansen, Michael Hudson, Jack Jansen, Marc-André Lemburg,
+Martin von Löwis, Fredrik Lundh, Michael McLay, Nick Mathewson, Paul Moore,
+Gustavo Niemeyer, Don O'Donnell, Joonas Paalasma, Tim Peters, Jens Quade, Tom
+Reinhardt, Neil Schemenauer, Guido van Rossum, Greg Ward, Edward Welbourne.
+