Move the 3k reST doc tree in place.
diff --git a/Doc/whatsnew/2.4.rst b/Doc/whatsnew/2.4.rst
new file mode 100644
index 0000000..d782f5d
--- /dev/null
+++ b/Doc/whatsnew/2.4.rst
@@ -0,0 +1,1571 @@
+****************************
+ What's New in Python 2.4
+****************************
+
+:Author: A.M. Kuchling
+
+.. |release| replace:: 1.02
+
+.. % $Id: whatsnew24.tex 55005 2007-04-27 19:54:29Z guido.van.rossum $
+.. % Don't write extensive text for new sections; I'll do that.
+.. % Feel free to add commented-out reminders of things that need
+.. % to be covered. --amk
+
+This article explains the new features in Python 2.4.1, released on March 30,
+2005.
+
+Python 2.4 is a medium-sized release. It doesn't introduce as many changes as
+the radical Python 2.2, but introduces more features than the conservative 2.3
+release. The most significant new language features are function decorators and
+generator expressions; most other changes are to the standard library.
+
+According to the CVS change logs, there were 481 patches applied and 502 bugs
+fixed between Python 2.3 and 2.4. Both figures are likely to be underestimates.
+
+This article doesn't attempt to provide a complete specification of every single
+new feature, but instead provides a brief introduction to each feature. For
+full details, you should refer to the documentation for Python 2.4, such as the
+Python Library Reference and the Python Reference Manual. Often you will be
+referred to the PEP for a particular new feature for explanations of the
+implementation and design rationale.
+
+.. % ======================================================================
+
+
+PEP 218: Built-In Set Objects
+=============================
+
+Python 2.3 introduced the :mod:`sets` module. C implementations of set data
+types have now been added to the Python core as two new built-in types,
+:func:`set(iterable)` and :func:`frozenset(iterable)`. They provide high speed
+operations for membership testing, for eliminating duplicates from sequences,
+and for mathematical operations like unions, intersections, differences, and
+symmetric differences. ::
+
+ >>> a = set('abracadabra') # form a set from a string
+ >>> 'z' in a # fast membership testing
+ False
+ >>> a # unique letters in a
+ set(['a', 'r', 'b', 'c', 'd'])
+ >>> ''.join(a) # convert back into a string
+ 'arbcd'
+
+ >>> b = set('alacazam') # form a second set
+ >>> a - b # letters in a but not in b
+ set(['r', 'd', 'b'])
+ >>> a | b # letters in either a or b
+ set(['a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'])
+ >>> a & b # letters in both a and b
+ set(['a', 'c'])
+ >>> a ^ b # letters in a or b but not both
+ set(['r', 'd', 'b', 'm', 'z', 'l'])
+
+ >>> a.add('z') # add a new element
+ >>> a.update('wxy') # add multiple new elements
+ >>> a
+ set(['a', 'c', 'b', 'd', 'r', 'w', 'y', 'x', 'z'])
+ >>> a.remove('x') # take one element out
+ >>> a
+ set(['a', 'c', 'b', 'd', 'r', 'w', 'y', 'z'])
+
+The :func:`frozenset` type is an immutable version of :func:`set`. Since it is
+immutable and hashable, it may be used as a dictionary key or as a member of
+another set.
+
+The :mod:`sets` module remains in the standard library, and may be useful if you
+wish to subclass the :class:`Set` or :class:`ImmutableSet` classes. There are
+currently no plans to deprecate the module.
+
+
+.. seealso::
+
+ :pep:`218` - Adding a Built-In Set Object Type
+ Originally proposed by Greg Wilson and ultimately implemented by Raymond
+ Hettinger.
+
+.. % ======================================================================
+
+
+PEP 237: Unifying Long Integers and Integers
+============================================
+
+The lengthy transition process for this PEP, begun in Python 2.2, takes another
+step forward in Python 2.4. In 2.3, certain integer operations that would
+behave differently after int/long unification triggered :exc:`FutureWarning`
+warnings and returned values limited to 32 or 64 bits (depending on your
+platform). In 2.4, these expressions no longer produce a warning and instead
+produce a different result that's usually a long integer.
+
+The problematic expressions are primarily left shifts and lengthy hexadecimal
+and octal constants. For example, ``2 << 32`` results in a warning in 2.3,
+evaluating to 0 on 32-bit platforms. In Python 2.4, this expression now returns
+the correct answer, 8589934592.
+
+
+.. seealso::
+
+ :pep:`237` - Unifying Long Integers and Integers
+ Original PEP written by Moshe Zadka and GvR. The changes for 2.4 were
+ implemented by Kalle Svensson.
+
+.. % ======================================================================
+
+
+PEP 289: Generator Expressions
+==============================
+
+The iterator feature introduced in Python 2.2 and the :mod:`itertools` module
+make it easier to write programs that loop through large data sets without
+having the entire data set in memory at one time. List comprehensions don't fit
+into this picture very well because they produce a Python list object containing
+all of the items. This unavoidably pulls all of the objects into memory, which
+can be a problem if your data set is very large. When trying to write a
+functionally-styled program, it would be natural to write something like::
+
+ links = [link for link in get_all_links() if not link.followed]
+ for link in links:
+ ...
+
+instead of ::
+
+ for link in get_all_links():
+ if link.followed:
+ continue
+ ...
+
+The first form is more concise and perhaps more readable, but if you're dealing
+with a large number of link objects you'd have to write the second form to avoid
+having all link objects in memory at the same time.
+
+Generator expressions work similarly to list comprehensions but don't
+materialize the entire list; instead they create a generator that will return
+elements one by one. The above example could be written as::
+
+ links = (link for link in get_all_links() if not link.followed)
+ for link in links:
+ ...
+
+Generator expressions always have to be written inside parentheses, as in the
+above example. The parentheses signalling a function call also count, so if you
+want to create an iterator that will be immediately passed to a function you
+could write::
+
+ print sum(obj.count for obj in list_all_objects())
+
+Generator expressions differ from list comprehensions in various small ways.
+Most notably, the loop variable (*obj* in the above example) is not accessible
+outside of the generator expression. List comprehensions leave the variable
+assigned to its last value; future versions of Python will change this, making
+list comprehensions match generator expressions in this respect.
+
+
+.. seealso::
+
+ :pep:`289` - Generator Expressions
+ Proposed by Raymond Hettinger and implemented by Jiwon Seo with early efforts
+ steered by Hye-Shik Chang.
+
+.. % ======================================================================
+
+
+PEP 292: Simpler String Substitutions
+=====================================
+
+Some new classes in the standard library provide an alternative mechanism for
+substituting variables into strings; this style of substitution may be better
+for applications where untrained users need to edit templates.
+
+The usual way of substituting variables by name is the ``%`` operator::
+
+ >>> '%(page)i: %(title)s' % {'page':2, 'title': 'The Best of Times'}
+ '2: The Best of Times'
+
+When writing the template string, it can be easy to forget the ``i`` or ``s``
+after the closing parenthesis. This isn't a big problem if the template is in a
+Python module, because you run the code, get an "Unsupported format character"
+:exc:`ValueError`, and fix the problem. However, consider an application such
+as Mailman where template strings or translations are being edited by users who
+aren't aware of the Python language. The format string's syntax is complicated
+to explain to such users, and if they make a mistake, it's difficult to provide
+helpful feedback to them.
+
+PEP 292 adds a :class:`Template` class to the :mod:`string` module that uses
+``$`` to indicate a substitution::
+
+ >>> import string
+ >>> t = string.Template('$page: $title')
+ >>> t.substitute({'page':2, 'title': 'The Best of Times'})
+ '2: The Best of Times'
+
+If a key is missing from the dictionary, the :meth:`substitute` method will
+raise a :exc:`KeyError`. There's also a :meth:`safe_substitute` method that
+ignores missing keys:
+
+.. % $ Terminate $-mode for Emacs
+
+::
+
+ >>> t = string.Template('$page: $title')
+ >>> t.safe_substitute({'page':3})
+ '3: $title'
+
+.. % $ Terminate math-mode for Emacs
+
+
+.. seealso::
+
+ :pep:`292` - Simpler String Substitutions
+ Written and implemented by Barry Warsaw.
+
+.. % ======================================================================
+
+
+PEP 318: Decorators for Functions and Methods
+=============================================
+
+Python 2.2 extended Python's object model by adding static methods and class
+methods, but it didn't extend Python's syntax to provide any new way of defining
+static or class methods. Instead, you had to write a :keyword:`def` statement
+in the usual way, and pass the resulting method to a :func:`staticmethod` or
+:func:`classmethod` function that would wrap up the function as a method of the
+new type. Your code would look like this::
+
+ class C:
+ def meth (cls):
+ ...
+
+ meth = classmethod(meth) # Rebind name to wrapped-up class method
+
+If the method was very long, it would be easy to miss or forget the
+:func:`classmethod` invocation after the function body.
+
+The intention was always to add some syntax to make such definitions more
+readable, but at the time of 2.2's release a good syntax was not obvious. Today
+a good syntax *still* isn't obvious but users are asking for easier access to
+the feature; a new syntactic feature has been added to meet this need.
+
+The new feature is called "function decorators". The name comes from the idea
+that :func:`classmethod`, :func:`staticmethod`, and friends are storing
+additional information on a function object; they're *decorating* functions with
+more details.
+
+The notation borrows from Java and uses the ``'@'`` character as an indicator.
+Using the new syntax, the example above would be written::
+
+ class C:
+
+ @classmethod
+ def meth (cls):
+ ...
+
+
+The ``@classmethod`` is shorthand for the ``meth=classmethod(meth)`` assignment.
+More generally, if you have the following::
+
+ @A
+ @B
+ @C
+ def f ():
+ ...
+
+It's equivalent to the following pre-decorator code::
+
+ def f(): ...
+ f = A(B(C(f)))
+
+Decorators must come on the line before a function definition, one decorator per
+line, and can't be on the same line as the def statement, meaning that ``@A def
+f(): ...`` is illegal. You can only decorate function definitions, either at
+the module level or inside a class; you can't decorate class definitions.
+
+A decorator is just a function that takes the function to be decorated as an
+argument and returns either the same function or some new object. The return
+value of the decorator need not be callable (though it typically is), unless
+further decorators will be applied to the result. It's easy to write your own
+decorators. The following simple example just sets an attribute on the function
+object::
+
+ >>> def deco(func):
+ ... func.attr = 'decorated'
+ ... return func
+ ...
+ >>> @deco
+ ... def f(): pass
+ ...
+ >>> f
+ <function f at 0x402ef0d4>
+ >>> f.attr
+ 'decorated'
+ >>>
+
+As a slightly more realistic example, the following decorator checks that the
+supplied argument is an integer::
+
+ def require_int (func):
+ def wrapper (arg):
+ assert isinstance(arg, int)
+ return func(arg)
+
+ return wrapper
+
+ @require_int
+ def p1 (arg):
+ print arg
+
+ @require_int
+ def p2(arg):
+ print arg*2
+
+An example in :pep:`318` contains a fancier version of this idea that lets you
+both specify the required type and check the returned type.
+
+Decorator functions can take arguments. If arguments are supplied, your
+decorator function is called with only those arguments and must return a new
+decorator function; this function must take a single function and return a
+function, as previously described. In other words, ``@A @B @C(args)`` becomes::
+
+ def f(): ...
+ _deco = C(args)
+ f = A(B(_deco(f)))
+
+Getting this right can be slightly brain-bending, but it's not too difficult.
+
+A small related change makes the :attr:`func_name` attribute of functions
+writable. This attribute is used to display function names in tracebacks, so
+decorators should change the name of any new function that's constructed and
+returned.
+
+
+.. seealso::
+
+ :pep:`318` - Decorators for Functions, Methods and Classes
+ Written by Kevin D. Smith, Jim Jewett, and Skip Montanaro. Several people
+ wrote patches implementing function decorators, but the one that was actually
+ checked in was patch #979728, written by Mark Russell.
+
+ http://www.python.org/moin/PythonDecoratorLibrary
+ This Wiki page contains several examples of decorators.
+
+.. % ======================================================================
+
+
+PEP 322: Reverse Iteration
+==========================
+
+A new built-in function, :func:`reversed(seq)`, takes a sequence and returns an
+iterator that loops over the elements of the sequence in reverse order. ::
+
+ >>> for i in reversed(xrange(1,4)):
+ ... print i
+ ...
+ 3
+ 2
+ 1
+
+Compared to extended slicing, such as ``range(1,4)[::-1]``, :func:`reversed` is
+easier to read, runs faster, and uses substantially less memory.
+
+Note that :func:`reversed` only accepts sequences, not arbitrary iterators. If
+you want to reverse an iterator, first convert it to a list with :func:`list`.
+::
+
+ >>> input = open('/etc/passwd', 'r')
+ >>> for line in reversed(list(input)):
+ ... print line
+ ...
+ root:*:0:0:System Administrator:/var/root:/bin/tcsh
+ ...
+
+
+.. seealso::
+
+ :pep:`322` - Reverse Iteration
+ Written and implemented by Raymond Hettinger.
+
+.. % ======================================================================
+
+
+PEP 324: New subprocess Module
+==============================
+
+The standard library provides a number of ways to execute a subprocess, offering
+different features and different levels of complexity.
+:func:`os.system(command)` is easy to use, but slow (it runs a shell process
+which executes the command) and dangerous (you have to be careful about escaping
+the shell's metacharacters). The :mod:`popen2` module offers classes that can
+capture standard output and standard error from the subprocess, but the naming
+is confusing. The :mod:`subprocess` module cleans this up, providing a unified
+interface that offers all the features you might need.
+
+Instead of :mod:`popen2`'s collection of classes, :mod:`subprocess` contains a
+single class called :class:`Popen` whose constructor supports a number of
+different keyword arguments. ::
+
+ class Popen(args, bufsize=0, executable=None,
+ stdin=None, stdout=None, stderr=None,
+ preexec_fn=None, close_fds=False, shell=False,
+ cwd=None, env=None, universal_newlines=False,
+ startupinfo=None, creationflags=0):
+
+*args* is commonly a sequence of strings that will be the arguments to the
+program executed as the subprocess. (If the *shell* argument is true, *args*
+can be a string which will then be passed on to the shell for interpretation,
+just as :func:`os.system` does.)
+
+*stdin*, *stdout*, and *stderr* specify what the subprocess's input, output, and
+error streams will be. You can provide a file object or a file descriptor, or
+you can use the constant ``subprocess.PIPE`` to create a pipe between the
+subprocess and the parent.
+
+The constructor has a number of handy options:
+
+* *close_fds* requests that all file descriptors be closed before running the
+ subprocess.
+
+* *cwd* specifies the working directory in which the subprocess will be executed
+ (defaulting to whatever the parent's working directory is).
+
+* *env* is a dictionary specifying environment variables.
+
+* *preexec_fn* is a function that gets called before the child is started.
+
+* *universal_newlines* opens the child's input and output using Python's
+ universal newline feature.
+
+Once you've created the :class:`Popen` instance, you can call its :meth:`wait`
+method to pause until the subprocess has exited, :meth:`poll` to check if it's
+exited without pausing, or :meth:`communicate(data)` to send the string *data*
+to the subprocess's standard input. :meth:`communicate(data)` then reads any
+data that the subprocess has sent to its standard output or standard error,
+returning a tuple ``(stdout_data, stderr_data)``.
+
+:func:`call` is a shortcut that passes its arguments along to the :class:`Popen`
+constructor, waits for the command to complete, and returns the status code of
+the subprocess. It can serve as a safer analog to :func:`os.system`::
+
+ sts = subprocess.call(['dpkg', '-i', '/tmp/new-package.deb'])
+ if sts == 0:
+ # Success
+ ...
+ else:
+ # dpkg returned an error
+ ...
+
+The command is invoked without use of the shell. If you really do want to use
+the shell, you can add ``shell=True`` as a keyword argument and provide a string
+instead of a sequence::
+
+ sts = subprocess.call('dpkg -i /tmp/new-package.deb', shell=True)
+
+The PEP takes various examples of shell and Python code and shows how they'd be
+translated into Python code that uses :mod:`subprocess`. Reading this section
+of the PEP is highly recommended.
+
+
+.. seealso::
+
+ :pep:`324` - subprocess - New process module
+ Written and implemented by Peter Åstrand, with assistance from Fredrik Lundh and
+ others.
+
+.. % ======================================================================
+
+
+PEP 327: Decimal Data Type
+==========================
+
+Python has always supported floating-point (FP) numbers, based on the underlying
+C :ctype:`double` type, as a data type. However, while most programming
+languages provide a floating-point type, many people (even programmers) are
+unaware that floating-point numbers don't represent certain decimal fractions
+accurately. The new :class:`Decimal` type can represent these fractions
+accurately, up to a user-specified precision limit.
+
+
+Why is Decimal needed?
+----------------------
+
+The limitations arise from the representation used for floating-point numbers.
+FP numbers are made up of three components:
+
+* The sign, which is positive or negative.
+
+* The mantissa, which is a single-digit binary number followed by a fractional
+ part. For example, ``1.01`` in base-2 notation is ``1 + 0/2 + 1/4``, or 1.25 in
+ decimal notation.
+
+* The exponent, which tells where the decimal point is located in the number
+ represented.
+
+For example, the number 1.25 has positive sign, a mantissa value of 1.01 (in
+binary), and an exponent of 0 (the decimal point doesn't need to be shifted).
+The number 5 has the same sign and mantissa, but the exponent is 2 because the
+mantissa is multiplied by 4 (2 to the power of the exponent 2); 1.25 \* 4 equals
+5.
+
+Modern systems usually provide floating-point support that conforms to a
+standard called IEEE 754. C's :ctype:`double` type is usually implemented as a
+64-bit IEEE 754 number, which uses 52 bits of space for the mantissa. This
+means that numbers can only be specified to 52 bits of precision. If you're
+trying to represent numbers whose expansion repeats endlessly, the expansion is
+cut off after 52 bits. Unfortunately, most software needs to produce output in
+base 10, and common fractions in base 10 are often repeating decimals in binary.
+For example, 1.1 decimal is binary ``1.0001100110011 ...``; .1 = 1/16 + 1/32 +
+1/256 plus an infinite number of additional terms. IEEE 754 has to chop off
+that infinitely repeated decimal after 52 digits, so the representation is
+slightly inaccurate.
+
+Sometimes you can see this inaccuracy when the number is printed::
+
+ >>> 1.1
+ 1.1000000000000001
+
+The inaccuracy isn't always visible when you print the number because the FP-to-
+decimal-string conversion is provided by the C library, and most C libraries try
+to produce sensible output. Even if it's not displayed, however, the inaccuracy
+is still there and subsequent operations can magnify the error.
+
+For many applications this doesn't matter. If I'm plotting points and
+displaying them on my monitor, the difference between 1.1 and 1.1000000000000001
+is too small to be visible. Reports often limit output to a certain number of
+decimal places, and if you round the number to two or three or even eight
+decimal places, the error is never apparent. However, for applications where it
+does matter, it's a lot of work to implement your own custom arithmetic
+routines.
+
+Hence, the :class:`Decimal` type was created.
+
+
+The :class:`Decimal` type
+-------------------------
+
+A new module, :mod:`decimal`, was added to Python's standard library. It
+contains two classes, :class:`Decimal` and :class:`Context`. :class:`Decimal`
+instances represent numbers, and :class:`Context` instances are used to wrap up
+various settings such as the precision and default rounding mode.
+
+:class:`Decimal` instances are immutable, like regular Python integers and FP
+numbers; once it's been created, you can't change the value an instance
+represents. :class:`Decimal` instances can be created from integers or
+strings::
+
+ >>> import decimal
+ >>> decimal.Decimal(1972)
+ Decimal("1972")
+ >>> decimal.Decimal("1.1")
+ Decimal("1.1")
+
+You can also provide tuples containing the sign, the mantissa represented as a
+tuple of decimal digits, and the exponent::
+
+ >>> decimal.Decimal((1, (1, 4, 7, 5), -2))
+ Decimal("-14.75")
+
+Cautionary note: the sign bit is a Boolean value, so 0 is positive and 1 is
+negative.
+
+Converting from floating-point numbers poses a bit of a problem: should the FP
+number representing 1.1 turn into the decimal number for exactly 1.1, or for 1.1
+plus whatever inaccuracies are introduced? The decision was to dodge the issue
+and leave such a conversion out of the API. Instead, you should convert the
+floating-point number into a string using the desired precision and pass the
+string to the :class:`Decimal` constructor::
+
+ >>> f = 1.1
+ >>> decimal.Decimal(str(f))
+ Decimal("1.1")
+ >>> decimal.Decimal('%.12f' % f)
+ Decimal("1.100000000000")
+
+Once you have :class:`Decimal` instances, you can perform the usual mathematical
+operations on them. One limitation: exponentiation requires an integer
+exponent::
+
+ >>> a = decimal.Decimal('35.72')
+ >>> b = decimal.Decimal('1.73')
+ >>> a+b
+ Decimal("37.45")
+ >>> a-b
+ Decimal("33.99")
+ >>> a*b
+ Decimal("61.7956")
+ >>> a/b
+ Decimal("20.64739884393063583815028902")
+ >>> a ** 2
+ Decimal("1275.9184")
+ >>> a**b
+ Traceback (most recent call last):
+ ...
+ decimal.InvalidOperation: x ** (non-integer)
+
+You can combine :class:`Decimal` instances with integers, but not with floating-
+point numbers::
+
+ >>> a + 4
+ Decimal("39.72")
+ >>> a + 4.5
+ Traceback (most recent call last):
+ ...
+ TypeError: You can interact Decimal only with int, long or Decimal data types.
+ >>>
+
+:class:`Decimal` numbers can be used with the :mod:`math` and :mod:`cmath`
+modules, but note that they'll be immediately converted to floating-point
+numbers before the operation is performed, resulting in a possible loss of
+precision and accuracy. You'll also get back a regular floating-point number
+and not a :class:`Decimal`. ::
+
+ >>> import math, cmath
+ >>> d = decimal.Decimal('123456789012.345')
+ >>> math.sqrt(d)
+ 351364.18288201344
+ >>> cmath.sqrt(-d)
+ 351364.18288201344j
+
+:class:`Decimal` instances have a :meth:`sqrt` method that returns a
+:class:`Decimal`, but if you need other things such as trigonometric functions
+you'll have to implement them. ::
+
+ >>> d.sqrt()
+ Decimal("351364.1828820134592177245001")
+
+
+The :class:`Context` type
+-------------------------
+
+Instances of the :class:`Context` class encapsulate several settings for
+decimal operations:
+
+* :attr:`prec` is the precision, the number of decimal places.
+
+* :attr:`rounding` specifies the rounding mode. The :mod:`decimal` module has
+ constants for the various possibilities: :const:`ROUND_DOWN`,
+ :const:`ROUND_CEILING`, :const:`ROUND_HALF_EVEN`, and various others.
+
+* :attr:`traps` is a dictionary specifying what happens on encountering certain
+ error conditions: either an exception is raised or a value is returned. Some
+ examples of error conditions are division by zero, loss of precision, and
+ overflow.
+
+There's a thread-local default context available by calling :func:`getcontext`;
+you can change the properties of this context to alter the default precision,
+rounding, or trap handling. The following example shows the effect of changing
+the precision of the default context::
+
+ >>> decimal.getcontext().prec
+ 28
+ >>> decimal.Decimal(1) / decimal.Decimal(7)
+ Decimal("0.1428571428571428571428571429")
+ >>> decimal.getcontext().prec = 9
+ >>> decimal.Decimal(1) / decimal.Decimal(7)
+ Decimal("0.142857143")
+
+The default action for error conditions is selectable; the module can either
+return a special value such as infinity or not-a-number, or exceptions can be
+raised::
+
+ >>> decimal.Decimal(1) / decimal.Decimal(0)
+ Traceback (most recent call last):
+ ...
+ decimal.DivisionByZero: x / 0
+ >>> decimal.getcontext().traps[decimal.DivisionByZero] = False
+ >>> decimal.Decimal(1) / decimal.Decimal(0)
+ Decimal("Infinity")
+ >>>
+
+The :class:`Context` instance also has various methods for formatting numbers
+such as :meth:`to_eng_string` and :meth:`to_sci_string`.
+
+For more information, see the documentation for the :mod:`decimal` module, which
+includes a quick-start tutorial and a reference.
+
+
+.. seealso::
+
+ :pep:`327` - Decimal Data Type
+ Written by Facundo Batista and implemented by Facundo Batista, Eric Price,
+ Raymond Hettinger, Aahz, and Tim Peters.
+
+ http://research.microsoft.com/~hollasch/cgindex/coding/ieeefloat.html
+ A more detailed overview of the IEEE-754 representation.
+
+ http://www.lahey.com/float.htm
+ The article uses Fortran code to illustrate many of the problems that floating-
+ point inaccuracy can cause.
+
+ http://www2.hursley.ibm.com/decimal/
+ A description of a decimal-based representation. This representation is being
+ proposed as a standard, and underlies the new Python decimal type. Much of this
+ material was written by Mike Cowlishaw, designer of the Rexx language.
+
+.. % ======================================================================
+
+
+PEP 328: Multi-line Imports
+===========================
+
+One language change is a small syntactic tweak aimed at making it easier to
+import many names from a module. In a ``from module import names`` statement,
+*names* is a sequence of names separated by commas. If the sequence is very
+long, you can either write multiple imports from the same module, or you can use
+backslashes to escape the line endings like this::
+
+ from SimpleXMLRPCServer import SimpleXMLRPCServer,\
+ SimpleXMLRPCRequestHandler,\
+ CGIXMLRPCRequestHandler,\
+ resolve_dotted_attribute
+
+The syntactic change in Python 2.4 simply allows putting the names within
+parentheses. Python ignores newlines within a parenthesized expression, so the
+backslashes are no longer needed::
+
+ from SimpleXMLRPCServer import (SimpleXMLRPCServer,
+ SimpleXMLRPCRequestHandler,
+ CGIXMLRPCRequestHandler,
+ resolve_dotted_attribute)
+
+The PEP also proposes that all :keyword:`import` statements be absolute imports,
+with a leading ``.`` character to indicate a relative import. This part of the
+PEP was not implemented for Python 2.4, but was completed for Python 2.5.
+
+
+.. seealso::
+
+ :pep:`328` - Imports: Multi-Line and Absolute/Relative
+ Written by Aahz. Multi-line imports were implemented by Dima Dorfman.
+
+.. % ======================================================================
+
+
+PEP 331: Locale-Independent Float/String Conversions
+====================================================
+
+The :mod:`locale` modules lets Python software select various conversions and
+display conventions that are localized to a particular country or language.
+However, the module was careful to not change the numeric locale because various
+functions in Python's implementation required that the numeric locale remain set
+to the ``'C'`` locale. Often this was because the code was using the C
+library's :cfunc:`atof` function.
+
+Not setting the numeric locale caused trouble for extensions that used third-
+party C libraries, however, because they wouldn't have the correct locale set.
+The motivating example was GTK+, whose user interface widgets weren't displaying
+numbers in the current locale.
+
+The solution described in the PEP is to add three new functions to the Python
+API that perform ASCII-only conversions, ignoring the locale setting:
+
+* :cfunc:`PyOS_ascii_strtod(str, ptr)` and :cfunc:`PyOS_ascii_atof(str, ptr)`
+ both convert a string to a C :ctype:`double`.
+
+* :cfunc:`PyOS_ascii_formatd(buffer, buf_len, format, d)` converts a
+ :ctype:`double` to an ASCII string.
+
+The code for these functions came from the GLib library
+(http://developer.gnome.org/arch/gtk/glib.html), whose developers kindly
+relicensed the relevant functions and donated them to the Python Software
+Foundation. The :mod:`locale` module can now change the numeric locale,
+letting extensions such as GTK+ produce the correct results.
+
+
+.. seealso::
+
+ :pep:`331` - Locale-Independent Float/String Conversions
+ Written by Christian R. Reis, and implemented by Gustavo Carneiro.
+
+.. % ======================================================================
+
+
+Other Language Changes
+======================
+
+Here are all of the changes that Python 2.4 makes to the core Python language.
+
+* Decorators for functions and methods were added (:pep:`318`).
+
+* Built-in :func:`set` and :func:`frozenset` types were added (:pep:`218`).
+ Other new built-ins include the :func:`reversed(seq)` function (:pep:`322`).
+
+* Generator expressions were added (:pep:`289`).
+
+* Certain numeric expressions no longer return values restricted to 32 or 64
+ bits (:pep:`237`).
+
+* You can now put parentheses around the list of names in a ``from module import
+ names`` statement (:pep:`328`).
+
+* The :meth:`dict.update` method now accepts the same argument forms as the
+ :class:`dict` constructor. This includes any mapping, any iterable of key/value
+ pairs, and keyword arguments. (Contributed by Raymond Hettinger.)
+
+* The string methods :meth:`ljust`, :meth:`rjust`, and :meth:`center` now take
+ an optional argument for specifying a fill character other than a space.
+ (Contributed by Raymond Hettinger.)
+
+* Strings also gained an :meth:`rsplit` method that works like the :meth:`split`
+ method but splits from the end of the string. (Contributed by Sean
+ Reifschneider.) ::
+
+ >>> 'www.python.org'.split('.', 1)
+ ['www', 'python.org']
+ 'www.python.org'.rsplit('.', 1)
+ ['www.python', 'org']
+
+* Three keyword parameters, *cmp*, *key*, and *reverse*, were added to the
+ :meth:`sort` method of lists. These parameters make some common usages of
+ :meth:`sort` simpler. All of these parameters are optional.
+
+ For the *cmp* parameter, the value should be a comparison function that takes
+ two parameters and returns -1, 0, or +1 depending on how the parameters compare.
+ This function will then be used to sort the list. Previously this was the only
+ parameter that could be provided to :meth:`sort`.
+
+ *key* should be a single-parameter function that takes a list element and
+ returns a comparison key for the element. The list is then sorted using the
+ comparison keys. The following example sorts a list case-insensitively::
+
+ >>> L = ['A', 'b', 'c', 'D']
+ >>> L.sort() # Case-sensitive sort
+ >>> L
+ ['A', 'D', 'b', 'c']
+ >>> # Using 'key' parameter to sort list
+ >>> L.sort(key=lambda x: x.lower())
+ >>> L
+ ['A', 'b', 'c', 'D']
+ >>> # Old-fashioned way
+ >>> L.sort(cmp=lambda x,y: cmp(x.lower(), y.lower()))
+ >>> L
+ ['A', 'b', 'c', 'D']
+
+ The last example, which uses the *cmp* parameter, is the old way to perform a
+ case-insensitive sort. It works but is slower than using a *key* parameter.
+ Using *key* calls :meth:`lower` method once for each element in the list while
+ using *cmp* will call it twice for each comparison, so using *key* saves on
+ invocations of the :meth:`lower` method.
+
+ For simple key functions and comparison functions, it is often possible to avoid
+ a :keyword:`lambda` expression by using an unbound method instead. For example,
+ the above case-insensitive sort is best written as::
+
+ >>> L.sort(key=str.lower)
+ >>> L
+ ['A', 'b', 'c', 'D']
+
+ Finally, the *reverse* parameter takes a Boolean value. If the value is true,
+ the list will be sorted into reverse order. Instead of ``L.sort() ;
+ L.reverse()``, you can now write ``L.sort(reverse=True)``.
+
+ The results of sorting are now guaranteed to be stable. This means that two
+ entries with equal keys will be returned in the same order as they were input.
+ For example, you can sort a list of people by name, and then sort the list by
+ age, resulting in a list sorted by age where people with the same age are in
+ name-sorted order.
+
+ (All changes to :meth:`sort` contributed by Raymond Hettinger.)
+
+* There is a new built-in function :func:`sorted(iterable)` that works like the
+ in-place :meth:`list.sort` method but can be used in expressions. The
+ differences are:
+
+* the input may be any iterable;
+
+* a newly formed copy is sorted, leaving the original intact; and
+
+* the expression returns the new sorted copy
+
+ ::
+
+ >>> L = [9,7,8,3,2,4,1,6,5]
+ >>> [10+i for i in sorted(L)] # usable in a list comprehension
+ [11, 12, 13, 14, 15, 16, 17, 18, 19]
+ >>> L # original is left unchanged
+ [9,7,8,3,2,4,1,6,5]
+ >>> sorted('Monty Python') # any iterable may be an input
+ [' ', 'M', 'P', 'h', 'n', 'n', 'o', 'o', 't', 't', 'y', 'y']
+
+ >>> # List the contents of a dict sorted by key values
+ >>> colormap = dict(red=1, blue=2, green=3, black=4, yellow=5)
+ >>> for k, v in sorted(colormap.iteritems()):
+ ... print k, v
+ ...
+ black 4
+ blue 2
+ green 3
+ red 1
+ yellow 5
+
+ (Contributed by Raymond Hettinger.)
+
+* Integer operations will no longer trigger an :exc:`OverflowWarning`. The
+ :exc:`OverflowWarning` warning will disappear in Python 2.5.
+
+* The interpreter gained a new switch, :option:`-m`, that takes a name, searches
+ for the corresponding module on ``sys.path``, and runs the module as a script.
+ For example, you can now run the Python profiler with ``python -m profile``.
+ (Contributed by Nick Coghlan.)
+
+* The :func:`eval(expr, globals, locals)` and :func:`execfile(filename, globals,
+ locals)` functions and the :keyword:`exec` statement now accept any mapping type
+ for the *locals* parameter. Previously this had to be a regular Python
+ dictionary. (Contributed by Raymond Hettinger.)
+
+* The :func:`zip` built-in function and :func:`itertools.izip` now return an
+ empty list if called with no arguments. Previously they raised a
+ :exc:`TypeError` exception. This makes them more suitable for use with variable
+ length argument lists::
+
+ >>> def transpose(array):
+ ... return zip(*array)
+ ...
+ >>> transpose([(1,2,3), (4,5,6)])
+ [(1, 4), (2, 5), (3, 6)]
+ >>> transpose([])
+ []
+
+ (Contributed by Raymond Hettinger.)
+
+* Encountering a failure while importing a module no longer leaves a partially-
+ initialized module object in ``sys.modules``. The incomplete module object left
+ behind would fool further imports of the same module into succeeding, leading to
+ confusing errors. (Fixed by Tim Peters.)
+
+* :const:`None` is now a constant; code that binds a new value to the name
+ ``None`` is now a syntax error. (Contributed by Raymond Hettinger.)
+
+.. % ======================================================================
+
+
+Optimizations
+-------------
+
+* The inner loops for list and tuple slicing were optimized and now run about
+ one-third faster. The inner loops for dictionaries were also optimized,
+ resulting in performance boosts for :meth:`keys`, :meth:`values`, :meth:`items`,
+ :meth:`iterkeys`, :meth:`itervalues`, and :meth:`iteritems`. (Contributed by
+ Raymond Hettinger.)
+
+* The machinery for growing and shrinking lists was optimized for speed and for
+ space efficiency. Appending and popping from lists now runs faster due to more
+ efficient code paths and less frequent use of the underlying system
+ :cfunc:`realloc`. List comprehensions also benefit. :meth:`list.extend` was
+ also optimized and no longer converts its argument into a temporary list before
+ extending the base list. (Contributed by Raymond Hettinger.)
+
+* :func:`list`, :func:`tuple`, :func:`map`, :func:`filter`, and :func:`zip` now
+ run several times faster with non-sequence arguments that supply a
+ :meth:`__len__` method. (Contributed by Raymond Hettinger.)
+
+* The methods :meth:`list.__getitem__`, :meth:`dict.__getitem__`, and
+ :meth:`dict.__contains__` are are now implemented as :class:`method_descriptor`
+ objects rather than :class:`wrapper_descriptor` objects. This form of access
+ doubles their performance and makes them more suitable for use as arguments to
+ functionals: ``map(mydict.__getitem__, keylist)``. (Contributed by Raymond
+ Hettinger.)
+
+* Added a new opcode, ``LIST_APPEND``, that simplifies the generated bytecode
+ for list comprehensions and speeds them up by about a third. (Contributed by
+ Raymond Hettinger.)
+
+* The peephole bytecode optimizer has been improved to produce shorter, faster
+ bytecode; remarkably, the resulting bytecode is more readable. (Enhanced by
+ Raymond Hettinger.)
+
+* String concatenations in statements of the form ``s = s + "abc"`` and ``s +=
+ "abc"`` are now performed more efficiently in certain circumstances. This
+ optimization won't be present in other Python implementations such as Jython, so
+ you shouldn't rely on it; using the :meth:`join` method of strings is still
+ recommended when you want to efficiently glue a large number of strings
+ together. (Contributed by Armin Rigo.)
+
+The net result of the 2.4 optimizations is that Python 2.4 runs the pystone
+benchmark around 5% faster than Python 2.3 and 35% faster than Python 2.2.
+(pystone is not a particularly good benchmark, but it's the most commonly used
+measurement of Python's performance. Your own applications may show greater or
+smaller benefits from Python 2.4.)
+
+.. % pystone is almost useless for comparing different versions of Python;
+.. % instead, it excels at predicting relative Python performance on
+.. % different machines.
+.. % So, this section would be more informative if it used other tools
+.. % such as pybench and parrotbench. For a more application oriented
+.. % benchmark, try comparing the timings of test_decimal.py under 2.3
+.. % and 2.4.
+
+.. % ======================================================================
+
+
+New, Improved, and Deprecated Modules
+=====================================
+
+As usual, Python's standard library received a number of enhancements and bug
+fixes. Here's a partial list of the most notable changes, sorted alphabetically
+by module name. Consult the :file:`Misc/NEWS` file in the source tree for a more
+complete list of changes, or look through the CVS logs for all the details.
+
+* The :mod:`asyncore` module's :func:`loop` function now has a *count* parameter
+ that lets you perform a limited number of passes through the polling loop. The
+ default is still to loop forever.
+
+* The :mod:`base64` module now has more complete RFC 3548 support for Base64,
+ Base32, and Base16 encoding and decoding, including optional case folding and
+ optional alternative alphabets. (Contributed by Barry Warsaw.)
+
+* The :mod:`bisect` module now has an underlying C implementation for improved
+ performance. (Contributed by Dmitry Vasiliev.)
+
+* The CJKCodecs collections of East Asian codecs, maintained by Hye-Shik Chang,
+ was integrated into 2.4. The new encodings are:
+
+* Chinese (PRC): gb2312, gbk, gb18030, big5hkscs, hz
+
+* Chinese (ROC): big5, cp950
+
+* Japanese: cp932, euc-jis-2004, euc-jp, euc-jisx0213, iso-2022-jp,
+ iso-2022-jp-1, iso-2022-jp-2, iso-2022-jp-3, iso-2022-jp-ext, iso-2022-jp-2004,
+ shift-jis, shift-jisx0213, shift-jis-2004
+
+* Korean: cp949, euc-kr, johab, iso-2022-kr
+
+* Some other new encodings were added: HP Roman8, ISO_8859-11, ISO_8859-16,
+ PCTP-154, and TIS-620.
+
+* The UTF-8 and UTF-16 codecs now cope better with receiving partial input.
+ Previously the :class:`StreamReader` class would try to read more data, making
+ it impossible to resume decoding from the stream. The :meth:`read` method will
+ now return as much data as it can and future calls will resume decoding where
+ previous ones left off. (Implemented by Walter Dörwald.)
+
+* There is a new :mod:`collections` module for various specialized collection
+ datatypes. Currently it contains just one type, :class:`deque`, a double-
+ ended queue that supports efficiently adding and removing elements from either
+ end::
+
+ >>> from collections import deque
+ >>> d = deque('ghi') # make a new deque with three items
+ >>> d.append('j') # add a new entry to the right side
+ >>> d.appendleft('f') # add a new entry to the left side
+ >>> d # show the representation of the deque
+ deque(['f', 'g', 'h', 'i', 'j'])
+ >>> d.pop() # return and remove the rightmost item
+ 'j'
+ >>> d.popleft() # return and remove the leftmost item
+ 'f'
+ >>> list(d) # list the contents of the deque
+ ['g', 'h', 'i']
+ >>> 'h' in d # search the deque
+ True
+
+ Several modules, such as the :mod:`Queue` and :mod:`threading` modules, now take
+ advantage of :class:`collections.deque` for improved performance. (Contributed
+ by Raymond Hettinger.)
+
+* The :mod:`ConfigParser` classes have been enhanced slightly. The :meth:`read`
+ method now returns a list of the files that were successfully parsed, and the
+ :meth:`set` method raises :exc:`TypeError` if passed a *value* argument that
+ isn't a string. (Contributed by John Belmonte and David Goodger.)
+
+* The :mod:`curses` module now supports the ncurses extension
+ :func:`use_default_colors`. On platforms where the terminal supports
+ transparency, this makes it possible to use a transparent background.
+ (Contributed by Jörg Lehmann.)
+
+* The :mod:`difflib` module now includes an :class:`HtmlDiff` class that creates
+ an HTML table showing a side by side comparison of two versions of a text.
+ (Contributed by Dan Gass.)
+
+* The :mod:`email` package was updated to version 3.0, which dropped various
+ deprecated APIs and removes support for Python versions earlier than 2.3. The
+ 3.0 version of the package uses a new incremental parser for MIME messages,
+ available in the :mod:`email.FeedParser` module. The new parser doesn't require
+ reading the entire message into memory, and doesn't throw exceptions if a
+ message is malformed; instead it records any problems in the :attr:`defect`
+ attribute of the message. (Developed by Anthony Baxter, Barry Warsaw, Thomas
+ Wouters, and others.)
+
+* The :mod:`heapq` module has been converted to C. The resulting tenfold
+ improvement in speed makes the module suitable for handling high volumes of
+ data. In addition, the module has two new functions :func:`nlargest` and
+ :func:`nsmallest` that use heaps to find the N largest or smallest values in a
+ dataset without the expense of a full sort. (Contributed by Raymond Hettinger.)
+
+* The :mod:`httplib` module now contains constants for HTTP status codes defined
+ in various HTTP-related RFC documents. Constants have names such as
+ :const:`OK`, :const:`CREATED`, :const:`CONTINUE`, and
+ :const:`MOVED_PERMANENTLY`; use pydoc to get a full list. (Contributed by
+ Andrew Eland.)
+
+* The :mod:`imaplib` module now supports IMAP's THREAD command (contributed by
+ Yves Dionne) and new :meth:`deleteacl` and :meth:`myrights` methods (contributed
+ by Arnaud Mazin).
+
+* The :mod:`itertools` module gained a :func:`groupby(iterable[, *func*])`
+ function. *iterable* is something that can be iterated over to return a stream
+ of elements, and the optional *func* parameter is a function that takes an
+ element and returns a key value; if omitted, the key is simply the element
+ itself. :func:`groupby` then groups the elements into subsequences which have
+ matching values of the key, and returns a series of 2-tuples containing the key
+ value and an iterator over the subsequence.
+
+ Here's an example to make this clearer. The *key* function simply returns
+ whether a number is even or odd, so the result of :func:`groupby` is to return
+ consecutive runs of odd or even numbers. ::
+
+ >>> import itertools
+ >>> L = [2, 4, 6, 7, 8, 9, 11, 12, 14]
+ >>> for key_val, it in itertools.groupby(L, lambda x: x % 2):
+ ... print key_val, list(it)
+ ...
+ 0 [2, 4, 6]
+ 1 [7]
+ 0 [8]
+ 1 [9, 11]
+ 0 [12, 14]
+ >>>
+
+ :func:`groupby` is typically used with sorted input. The logic for
+ :func:`groupby` is similar to the Unix ``uniq`` filter which makes it handy for
+ eliminating, counting, or identifying duplicate elements::
+
+ >>> word = 'abracadabra'
+ >>> letters = sorted(word) # Turn string into a sorted list of letters
+ >>> letters
+ ['a', 'a', 'a', 'a', 'a', 'b', 'b', 'c', 'd', 'r', 'r']
+ >>> for k, g in itertools.groupby(letters):
+ ... print k, list(g)
+ ...
+ a ['a', 'a', 'a', 'a', 'a']
+ b ['b', 'b']
+ c ['c']
+ d ['d']
+ r ['r', 'r']
+ >>> # List unique letters
+ >>> [k for k, g in groupby(letters)]
+ ['a', 'b', 'c', 'd', 'r']
+ >>> # Count letter occurrences
+ >>> [(k, len(list(g))) for k, g in groupby(letters)]
+ [('a', 5), ('b', 2), ('c', 1), ('d', 1), ('r', 2)]
+
+ (Contributed by Hye-Shik Chang.)
+
+* :mod:`itertools` also gained a function named :func:`tee(iterator, N)` that
+ returns *N* independent iterators that replicate *iterator*. If *N* is omitted,
+ the default is 2. ::
+
+ >>> L = [1,2,3]
+ >>> i1, i2 = itertools.tee(L)
+ >>> i1,i2
+ (<itertools.tee object at 0x402c2080>, <itertools.tee object at 0x402c2090>)
+ >>> list(i1) # Run the first iterator to exhaustion
+ [1, 2, 3]
+ >>> list(i2) # Run the second iterator to exhaustion
+ [1, 2, 3]
+
+ Note that :func:`tee` has to keep copies of the values returned by the
+ iterator; in the worst case, it may need to keep all of them. This should
+ therefore be used carefully if the leading iterator can run far ahead of the
+ trailing iterator in a long stream of inputs. If the separation is large, then
+ you might as well use :func:`list` instead. When the iterators track closely
+ with one another, :func:`tee` is ideal. Possible applications include
+ bookmarking, windowing, or lookahead iterators. (Contributed by Raymond
+ Hettinger.)
+
+* A number of functions were added to the :mod:`locale` module, such as
+ :func:`bind_textdomain_codeset` to specify a particular encoding and a family of
+ :func:`l\*gettext` functions that return messages in the chosen encoding.
+ (Contributed by Gustavo Niemeyer.)
+
+* Some keyword arguments were added to the :mod:`logging` package's
+ :func:`basicConfig` function to simplify log configuration. The default
+ behavior is to log messages to standard error, but various keyword arguments can
+ be specified to log to a particular file, change the logging format, or set the
+ logging level. For example::
+
+ import logging
+ logging.basicConfig(filename='/var/log/application.log',
+ level=0, # Log all messages
+ format='%(levelname):%(process):%(thread):%(message)')
+
+ Other additions to the :mod:`logging` package include a :meth:`log(level, msg)`
+ convenience method, as well as a :class:`TimedRotatingFileHandler` class that
+ rotates its log files at a timed interval. The module already had
+ :class:`RotatingFileHandler`, which rotated logs once the file exceeded a
+ certain size. Both classes derive from a new :class:`BaseRotatingHandler` class
+ that can be used to implement other rotating handlers.
+
+ (Changes implemented by Vinay Sajip.)
+
+* The :mod:`marshal` module now shares interned strings on unpacking a data
+ structure. This may shrink the size of certain pickle strings, but the primary
+ effect is to make :file:`.pyc` files significantly smaller. (Contributed by
+ Martin von Löwis.)
+
+* The :mod:`nntplib` module's :class:`NNTP` class gained :meth:`description` and
+ :meth:`descriptions` methods to retrieve newsgroup descriptions for a single
+ group or for a range of groups. (Contributed by Jürgen A. Erhard.)
+
+* Two new functions were added to the :mod:`operator` module,
+ :func:`attrgetter(attr)` and :func:`itemgetter(index)`. Both functions return
+ callables that take a single argument and return the corresponding attribute or
+ item; these callables make excellent data extractors when used with :func:`map`
+ or :func:`sorted`. For example::
+
+ >>> L = [('c', 2), ('d', 1), ('a', 4), ('b', 3)]
+ >>> map(operator.itemgetter(0), L)
+ ['c', 'd', 'a', 'b']
+ >>> map(operator.itemgetter(1), L)
+ [2, 1, 4, 3]
+ >>> sorted(L, key=operator.itemgetter(1)) # Sort list by second tuple item
+ [('d', 1), ('c', 2), ('b', 3), ('a', 4)]
+
+ (Contributed by Raymond Hettinger.)
+
+* The :mod:`optparse` module was updated in various ways. The module now passes
+ its messages through :func:`gettext.gettext`, making it possible to
+ internationalize Optik's help and error messages. Help messages for options can
+ now include the string ``'%default'``, which will be replaced by the option's
+ default value. (Contributed by Greg Ward.)
+
+* The long-term plan is to deprecate the :mod:`rfc822` module in some future
+ Python release in favor of the :mod:`email` package. To this end, the
+ :func:`email.Utils.formatdate` function has been changed to make it usable as a
+ replacement for :func:`rfc822.formatdate`. You may want to write new e-mail
+ processing code with this in mind. (Change implemented by Anthony Baxter.)
+
+* A new :func:`urandom(n)` function was added to the :mod:`os` module, returning
+ a string containing *n* bytes of random data. This function provides access to
+ platform-specific sources of randomness such as :file:`/dev/urandom` on Linux or
+ the Windows CryptoAPI. (Contributed by Trevor Perrin.)
+
+* Another new function: :func:`os.path.lexists(path)` returns true if the file
+ specified by *path* exists, whether or not it's a symbolic link. This differs
+ from the existing :func:`os.path.exists(path)` function, which returns false if
+ *path* is a symlink that points to a destination that doesn't exist.
+ (Contributed by Beni Cherniavsky.)
+
+* A new :func:`getsid` function was added to the :mod:`posix` module that
+ underlies the :mod:`os` module. (Contributed by J. Raynor.)
+
+* The :mod:`poplib` module now supports POP over SSL. (Contributed by Hector
+ Urtubia.)
+
+* The :mod:`profile` module can now profile C extension functions. (Contributed
+ by Nick Bastin.)
+
+* The :mod:`random` module has a new method called :meth:`getrandbits(N)` that
+ returns a long integer *N* bits in length. The existing :meth:`randrange`
+ method now uses :meth:`getrandbits` where appropriate, making generation of
+ arbitrarily large random numbers more efficient. (Contributed by Raymond
+ Hettinger.)
+
+* The regular expression language accepted by the :mod:`re` module was extended
+ with simple conditional expressions, written as ``(?(group)A|B)``. *group* is
+ either a numeric group ID or a group name defined with ``(?P<group>...)``
+ earlier in the expression. If the specified group matched, the regular
+ expression pattern *A* will be tested against the string; if the group didn't
+ match, the pattern *B* will be used instead. (Contributed by Gustavo Niemeyer.)
+
+* The :mod:`re` module is also no longer recursive, thanks to a massive amount
+ of work by Gustavo Niemeyer. In a recursive regular expression engine, certain
+ patterns result in a large amount of C stack space being consumed, and it was
+ possible to overflow the stack. For example, if you matched a 30000-byte string
+ of ``a`` characters against the expression ``(a|b)+``, one stack frame was
+ consumed per character. Python 2.3 tried to check for stack overflow and raise
+ a :exc:`RuntimeError` exception, but certain patterns could sidestep the
+ checking and if you were unlucky Python could segfault. Python 2.4's regular
+ expression engine can match this pattern without problems.
+
+* The :mod:`signal` module now performs tighter error-checking on the parameters
+ to the :func:`signal.signal` function. For example, you can't set a handler on
+ the :const:`SIGKILL` signal; previous versions of Python would quietly accept
+ this, but 2.4 will raise a :exc:`RuntimeError` exception.
+
+* Two new functions were added to the :mod:`socket` module. :func:`socketpair`
+ returns a pair of connected sockets and :func:`getservbyport(port)` looks up the
+ service name for a given port number. (Contributed by Dave Cole and Barry
+ Warsaw.)
+
+* The :func:`sys.exitfunc` function has been deprecated. Code should be using
+ the existing :mod:`atexit` module, which correctly handles calling multiple exit
+ functions. Eventually :func:`sys.exitfunc` will become a purely internal
+ interface, accessed only by :mod:`atexit`.
+
+* The :mod:`tarfile` module now generates GNU-format tar files by default.
+ (Contributed by Lars Gustaebel.)
+
+* The :mod:`threading` module now has an elegantly simple way to support
+ thread-local data. The module contains a :class:`local` class whose attribute
+ values are local to different threads. ::
+
+ import threading
+
+ data = threading.local()
+ data.number = 42
+ data.url = ('www.python.org', 80)
+
+ Other threads can assign and retrieve their own values for the :attr:`number`
+ and :attr:`url` attributes. You can subclass :class:`local` to initialize
+ attributes or to add methods. (Contributed by Jim Fulton.)
+
+* The :mod:`timeit` module now automatically disables periodic garbage
+ collection during the timing loop. This change makes consecutive timings more
+ comparable. (Contributed by Raymond Hettinger.)
+
+* The :mod:`weakref` module now supports a wider variety of objects including
+ Python functions, class instances, sets, frozensets, deques, arrays, files,
+ sockets, and regular expression pattern objects. (Contributed by Raymond
+ Hettinger.)
+
+* The :mod:`xmlrpclib` module now supports a multi-call extension for
+ transmitting multiple XML-RPC calls in a single HTTP operation. (Contributed by
+ Brian Quinlan.)
+
+* The :mod:`mpz`, :mod:`rotor`, and :mod:`xreadlines` modules have been
+ removed.
+
+.. % ======================================================================
+.. % whole new modules get described in subsections here
+.. % =====================
+
+
+cookielib
+---------
+
+The :mod:`cookielib` library supports client-side handling for HTTP cookies,
+mirroring the :mod:`Cookie` module's server-side cookie support. Cookies are
+stored in cookie jars; the library transparently stores cookies offered by the
+web server in the cookie jar, and fetches the cookie from the jar when
+connecting to the server. As in web browsers, policy objects control whether
+cookies are accepted or not.
+
+In order to store cookies across sessions, two implementations of cookie jars
+are provided: one that stores cookies in the Netscape format so applications can
+use the Mozilla or Lynx cookie files, and one that stores cookies in the same
+format as the Perl libwww library.
+
+:mod:`urllib2` has been changed to interact with :mod:`cookielib`:
+:class:`HTTPCookieProcessor` manages a cookie jar that is used when accessing
+URLs.
+
+This module was contributed by John J. Lee.
+
+.. % ==================
+
+
+doctest
+-------
+
+The :mod:`doctest` module underwent considerable refactoring thanks to Edward
+Loper and Tim Peters. Testing can still be as simple as running
+:func:`doctest.testmod`, but the refactorings allow customizing the module's
+operation in various ways
+
+The new :class:`DocTestFinder` class extracts the tests from a given object's
+docstrings::
+
+ def f (x, y):
+ """>>> f(2,2)
+ 4
+ >>> f(3,2)
+ 6
+ """
+ return x*y
+
+ finder = doctest.DocTestFinder()
+
+ # Get list of DocTest instances
+ tests = finder.find(f)
+
+The new :class:`DocTestRunner` class then runs individual tests and can produce
+a summary of the results::
+
+ runner = doctest.DocTestRunner()
+ for t in tests:
+ tried, failed = runner.run(t)
+
+ runner.summarize(verbose=1)
+
+The above example produces the following output::
+
+ 1 items passed all tests:
+ 2 tests in f
+ 2 tests in 1 items.
+ 2 passed and 0 failed.
+ Test passed.
+
+:class:`DocTestRunner` uses an instance of the :class:`OutputChecker` class to
+compare the expected output with the actual output. This class takes a number
+of different flags that customize its behaviour; ambitious users can also write
+a completely new subclass of :class:`OutputChecker`.
+
+The default output checker provides a number of handy features. For example,
+with the :const:`doctest.ELLIPSIS` option flag, an ellipsis (``...``) in the
+expected output matches any substring, making it easier to accommodate outputs
+that vary in minor ways::
+
+ def o (n):
+ """>>> o(1)
+ <__main__.C instance at 0x...>
+ >>>
+ """
+
+Another special string, ``<BLANKLINE>``, matches a blank line::
+
+ def p (n):
+ """>>> p(1)
+ <BLANKLINE>
+ >>>
+ """
+
+Another new capability is producing a diff-style display of the output by
+specifying the :const:`doctest.REPORT_UDIFF` (unified diffs),
+:const:`doctest.REPORT_CDIFF` (context diffs), or :const:`doctest.REPORT_NDIFF`
+(delta-style) option flags. For example::
+
+ def g (n):
+ """>>> g(4)
+ here
+ is
+ a
+ lengthy
+ >>>"""
+ L = 'here is a rather lengthy list of words'.split()
+ for word in L[:n]:
+ print word
+
+Running the above function's tests with :const:`doctest.REPORT_UDIFF` specified,
+you get the following output::
+
+ **********************************************************************
+ File ``t.py'', line 15, in g
+ Failed example:
+ g(4)
+ Differences (unified diff with -expected +actual):
+ @@ -2,3 +2,3 @@
+ is
+ a
+ -lengthy
+ +rather
+ **********************************************************************
+
+.. % ======================================================================
+
+
+Build and C API Changes
+=======================
+
+Some of the changes to Python's build process and to the C API are:
+
+* Three new convenience macros were added for common return values from
+ extension functions: :cmacro:`Py_RETURN_NONE`, :cmacro:`Py_RETURN_TRUE`, and
+ :cmacro:`Py_RETURN_FALSE`. (Contributed by Brett Cannon.)
+
+* Another new macro, :cmacro:`Py_CLEAR(obj)`, decreases the reference count of
+ *obj* and sets *obj* to the null pointer. (Contributed by Jim Fulton.)
+
+* A new function, :cfunc:`PyTuple_Pack(N, obj1, obj2, ..., objN)`, constructs
+ tuples from a variable length argument list of Python objects. (Contributed by
+ Raymond Hettinger.)
+
+* A new function, :cfunc:`PyDict_Contains(d, k)`, implements fast dictionary
+ lookups without masking exceptions raised during the look-up process.
+ (Contributed by Raymond Hettinger.)
+
+* The :cmacro:`Py_IS_NAN(X)` macro returns 1 if its float or double argument
+ *X* is a NaN. (Contributed by Tim Peters.)
+
+* C code can avoid unnecessary locking by using the new
+ :cfunc:`PyEval_ThreadsInitialized` function to tell if any thread operations
+ have been performed. If this function returns false, no lock operations are
+ needed. (Contributed by Nick Coghlan.)
+
+* A new function, :cfunc:`PyArg_VaParseTupleAndKeywords`, is the same as
+ :cfunc:`PyArg_ParseTupleAndKeywords` but takes a :ctype:`va_list` instead of a
+ number of arguments. (Contributed by Greg Chapman.)
+
+* A new method flag, :const:`METH_COEXISTS`, allows a function defined in slots
+ to co-exist with a :ctype:`PyCFunction` having the same name. This can halve
+ the access time for a method such as :meth:`set.__contains__`. (Contributed by
+ Raymond Hettinger.)
+
+* Python can now be built with additional profiling for the interpreter itself,
+ intended as an aid to people developing the Python core. Providing
+ :option:`----enable-profiling` to the :program:`configure` script will let you
+ profile the interpreter with :program:`gprof`, and providing the
+ :option:`----with-tsc` switch enables profiling using the Pentium's Time-Stamp-
+ Counter register. Note that the :option:`----with-tsc` switch is slightly
+ misnamed, because the profiling feature also works on the PowerPC platform,
+ though that processor architecture doesn't call that register "the TSC
+ register". (Contributed by Jeremy Hylton.)
+
+* The :ctype:`tracebackobject` type has been renamed to
+ :ctype:`PyTracebackObject`.
+
+.. % ======================================================================
+
+
+Port-Specific Changes
+---------------------
+
+* The Windows port now builds under MSVC++ 7.1 as well as version 6.
+ (Contributed by Martin von Löwis.)
+
+.. % ======================================================================
+
+
+Porting to Python 2.4
+=====================
+
+This section lists previously described changes that may require changes to your
+code:
+
+* Left shifts and hexadecimal/octal constants that are too large no longer
+ trigger a :exc:`FutureWarning` and return a value limited to 32 or 64 bits;
+ instead they return a long integer.
+
+* Integer operations will no longer trigger an :exc:`OverflowWarning`. The
+ :exc:`OverflowWarning` warning will disappear in Python 2.5.
+
+* The :func:`zip` built-in function and :func:`itertools.izip` now return an
+ empty list instead of raising a :exc:`TypeError` exception if called with no
+ arguments.
+
+* You can no longer compare the :class:`date` and :class:`datetime` instances
+ provided by the :mod:`datetime` module. Two instances of different classes
+ will now always be unequal, and relative comparisons (``<``, ``>``) will raise
+ a :exc:`TypeError`.
+
+* :func:`dircache.listdir` now passes exceptions to the caller instead of
+ returning empty lists.
+
+* :func:`LexicalHandler.startDTD` used to receive the public and system IDs in
+ the wrong order. This has been corrected; applications relying on the wrong
+ order need to be fixed.
+
+* :func:`fcntl.ioctl` now warns if the *mutate* argument is omitted and
+ relevant.
+
+* The :mod:`tarfile` module now generates GNU-format tar files by default.
+
+* Encountering a failure while importing a module no longer leaves a partially-
+ initialized module object in ``sys.modules``.
+
+* :const:`None` is now a constant; code that binds a new value to the name
+ ``None`` is now a syntax error.
+
+* The :func:`signals.signal` function now raises a :exc:`RuntimeError` exception
+ for certain illegal values; previously these errors would pass silently. For
+ example, you can no longer set a handler on the :const:`SIGKILL` signal.
+
+.. % ======================================================================
+
+
+.. _acks:
+
+Acknowledgements
+================
+
+The author would like to thank the following people for offering suggestions,
+corrections and assistance with various drafts of this article: Koray Can, Hye-
+Shik Chang, Michael Dyck, Raymond Hettinger, Brian Hurt, Hamish Lawson, Fredrik
+Lundh, Sean Reifschneider, Sadruddin Rejeb.
+