--- rest25/whatsnew/2.2.rst	2008-12-19 16:58:06.000000000 +0900
+++ rest262/whatsnew/2.2.rst	2009-04-05 05:01:47.000000000 +0900
@@ -1,21 +1,21 @@
 ****************************
-  What's New in Python 2.2  
+  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 $
+.. $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
@@ -27,46 +27,45 @@
 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.
+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
@@ -287,25 +286,25 @@
 
 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()
+           # 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
 ----------------
 
@@ -387,45 +386,44 @@
 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.
+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):
@@ -466,25 +464,25 @@
    >>> 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
@@ -528,25 +526,25 @@
 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
@@ -625,29 +623,29 @@
            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::
+(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
@@ -655,25 +653,25 @@
 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
@@ -695,37 +693,37 @@
 
 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
+division 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
@@ -763,25 +761,25 @@
   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.)
 
@@ -825,25 +823,25 @@
 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.
 
@@ -902,74 +900,73 @@
 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'  
+       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.', 
+     # [{'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.
+  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
@@ -1036,25 +1033,25 @@
   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
@@ -1116,25 +1113,25 @@
 
 * 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:
@@ -1149,41 +1146,41 @@
   :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.
+  .. 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
@@ -1247,25 +1244,25 @@
 
 * 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.
