mirrors/cosmopolitan
1
0
Fork 0
mirror of https://github.com/jart/cosmopolitan.git synced 2025-06-03 03:02:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

python-3.6.zip added from Github

Browse source 
README.cosmo contains the necessary links.
This commit is contained in:
ahgamut 2021-08-08 09:38:33 +05:30 • committed by Justine Tunney
parent 75fc601ff5
commit 0c4c56ff39
4219 changed files with 1968626 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1205
third_party/python/Doc/whatsnew/2.0.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

794
third_party/python/Doc/whatsnew/2.1.rst vendored Normal file
View file

@ -0,0 +1,794 @@
****************************
What's New in Python 2.1
****************************
:Author: A.M. Kuchling
.. |release| replace:: 1.01
.. $Id: whatsnew21.tex 50964 2006-07-30 03:03:43Z fred.drake $
Introduction
============
This article explains the new features in Python 2.1. While there aren't as
many changes in 2.1 as there were in Python 2.0, there are still some pleasant
surprises in store. 2.1 is the first release to be steered through the use of
Python Enhancement Proposals, or PEPs, so most of the sizable changes have
accompanying PEPs that provide more complete documentation and a design
rationale for the change. This article doesn't attempt to document the new
features completely, but simply provides an overview of the new features for
Python programmers. Refer to the Python 2.1 documentation, or to the specific
PEP, for more details about any new feature that particularly interests you.
One recent goal of the Python development team has been to accelerate the pace
of new releases, with a new release coming every 6 to 9 months. 2.1 is the first
release to come out at this faster pace, with the first alpha appearing in
January, 3 months after the final version of 2.0 was released.
The final release of Python 2.1 was made on April 17, 2001.
.. ======================================================================
PEP 227: Nested Scopes
======================
The largest change in Python 2.1 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.1 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
``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 ``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 ``exec`` statement is a syntax error, since
``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 ``exec`` is rarely used in
most Python code (and when it is used, it's often a sign of a poor design
anyway).
Compatibility concerns have led to nested scopes being introduced gradually; in
Python 2.1, they aren't enabled by default, but can be turned on within a module
by using a future statement as described in PEP 236. (See the following section
for further discussion of PEP 236.) In Python 2.2, nested scopes will become
the default and there will be no way to turn them off, but users will have had
all of 2.1's lifetime to fix any breakage resulting from their introduction.
.. seealso::
:pep:`227` - Statically Nested Scopes
Written and implemented by Jeremy Hylton.
.. ======================================================================
PEP 236: __future__ Directives
==============================
The reaction to nested scopes was widespread concern about the dangers of
breaking code with the 2.1 release, and it was strong enough to make the
Pythoneers take a more conservative approach. This approach consists of
introducing a convention for enabling optional functionality in release N that
will become compulsory in release N+1.
The syntax uses a ``from...import`` statement using the reserved module name
:mod:`__future__`. Nested scopes can be enabled by the following statement::
from __future__ import nested_scopes
While it looks like a normal :keyword:`import` statement, it's not; there are
strict rules on where such a future statement can be put. They can only be at
the top of a module, and must precede any Python code or regular
:keyword:`import` statements. This is because such statements can affect how
the Python bytecode compiler parses code and generates bytecode, so they must
precede any statement that will result in bytecodes being produced.
.. seealso::
:pep:`236` - Back to the :mod:`__future__`
Written by Tim Peters, and primarily implemented by Jeremy Hylton.
.. ======================================================================
PEP 207: Rich Comparisons
=========================
In earlier versions, Python's support for implementing comparisons on user-defined
classes and extension types was quite simple. Classes could implement a
:meth:`__cmp__` method that was given two instances of a class, and could only
return 0 if they were equal or +1 or -1 if they weren't; the method couldn't
raise an exception or return anything other than a Boolean value. Users of
Numeric Python often found this model too weak and restrictive, because in the
number-crunching programs that numeric Python is used for, it would be more
useful to be able to perform elementwise comparisons of two matrices, returning
a matrix containing the results of a given comparison for each element. If the
two matrices are of different sizes, then the compare has to be able to raise an
exception to signal the error.
In Python 2.1, rich comparisons were added in order to support this need.
Python classes can now individually overload each of the ``<``, ``<=``, ``>``,
``>=``, ``==``, and ``!=`` operations. The new magic method names are:
+-----------+----------------+
| Operation | Method name |
+===========+================+
| ``<`` | :meth:`__lt__` |
+-----------+----------------+
| ``<=`` | :meth:`__le__` |
+-----------+----------------+
| ``>`` | :meth:`__gt__` |
+-----------+----------------+
| ``>=`` | :meth:`__ge__` |
+-----------+----------------+
| ``==`` | :meth:`__eq__` |
+-----------+----------------+
| ``!=`` | :meth:`__ne__` |
+-----------+----------------+
(The magic methods are named after the corresponding Fortran operators ``.LT.``.
``.LE.``, &c. Numeric programmers are almost certainly quite familiar with
these names and will find them easy to remember.)
Each of these magic methods is of the form ``method(self, other)``, where
``self`` will be the object on the left-hand side of the operator, while
``other`` will be the object on the right-hand side. For example, the
expression ``A < B`` will cause ``A.__lt__(B)`` to be called.
Each of these magic methods can return anything at all: a Boolean, a matrix, a
list, or any other Python object. Alternatively they can raise an exception if
the comparison is impossible, inconsistent, or otherwise meaningless.
The built-in ``cmp(A,B)`` function can use the rich comparison machinery,
and now accepts an optional argument specifying which comparison operation to
use; this is given as one of the strings ``"<"``, ``"<="``, ``">"``, ``">="``,
``"=="``, or ``"!="``. If called without the optional third argument,
:func:`cmp` will only return -1, 0, or +1 as in previous versions of Python;
otherwise it will call the appropriate method and can return any Python object.
There are also corresponding changes of interest to C programmers; there's a new
slot ``tp_richcmp`` in type objects and an API for performing a given rich
comparison. I won't cover the C API here, but will refer you to PEP 207, or to
2.1's C API documentation, for the full list of related functions.
.. seealso::
:pep:`207` - Rich Comparisons
Written by Guido van Rossum, heavily based on earlier work by David Ascher, and
implemented by Guido van Rossum.
.. ======================================================================
PEP 230: Warning Framework
==========================
Over its 10 years of existence, Python has accumulated a certain number of
obsolete modules and features along the way. It's difficult to know when a
feature is safe to remove, since there's no way of knowing how much code uses it
--- perhaps no programs depend on the feature, or perhaps many do. To enable
removing old features in a more structured way, a warning framework was added.
When the Python developers want to get rid of a feature, it will first trigger a
warning in the next version of Python. The following Python version can then
drop the feature, and users will have had a full release cycle to remove uses of
the old feature.
Python 2.1 adds the warning framework to be used in this scheme. It adds a
:mod:`warnings` module that provide functions to issue warnings, and to filter
out warnings that you don't want to be displayed. Third-party modules can also
use this framework to deprecate old features that they no longer wish to
support.
For example, in Python 2.1 the :mod:`regex` module is deprecated, so importing
it causes a warning to be printed::
>>> import regex
__main__:1: DeprecationWarning: the regex module
is deprecated; please use the re module
>>>
Warnings can be issued by calling the :func:`warnings.warn` function::
warnings.warn("feature X no longer supported")
The first parameter is the warning message; an additional optional parameters
can be used to specify a particular warning category.
Filters can be added to disable certain warnings; a regular expression pattern
can be applied to the message or to the module name in order to suppress a
warning. For example, you may have a program that uses the :mod:`regex` module
and not want to spare the time to convert it to use the :mod:`re` module right
now. The warning can be suppressed by calling ::
import warnings
warnings.filterwarnings(action = 'ignore',
message='.*regex module is deprecated',
category=DeprecationWarning,
module = '__main__')
This adds a filter that will apply only to warnings of the class
:class:`DeprecationWarning` triggered in the :mod:`__main__` module, and applies
a regular expression to only match the message about the :mod:`regex` module
being deprecated, and will cause such warnings to be ignored. Warnings can also
be printed only once, printed every time the offending code is executed, or
turned into exceptions that will cause the program to stop (unless the
exceptions are caught in the usual way, of course).
Functions were also added to Python's C API for issuing warnings; refer to PEP
230 or to Python's API documentation for the details.
.. seealso::
:pep:`5` - Guidelines for Language Evolution
Written by Paul Prescod, to specify procedures to be followed when removing old
features from Python. The policy described in this PEP hasn't been officially
adopted, but the eventual policy probably won't be too different from Prescod's
proposal.
:pep:`230` - Warning Framework
Written and implemented by Guido van Rossum.
.. ======================================================================
PEP 229: New Build System
=========================
When compiling Python, the user had to go in and edit the :file:`Modules/Setup`
file in order to enable various additional modules; the default set is
relatively small and limited to modules that compile on most Unix platforms.
This means that on Unix platforms with many more features, most notably Linux,
Python installations often don't contain all useful modules they could.
Python 2.0 added the Distutils, a set of modules for distributing and installing
extensions. In Python 2.1, the Distutils are used to compile much of the
standard library of extension modules, autodetecting which ones are supported on
the current machine. It's hoped that this will make Python installations easier
and more featureful.
Instead of having to edit the :file:`Modules/Setup` file in order to enable
modules, a :file:`setup.py` script in the top directory of the Python source
distribution is run at build time, and attempts to discover which modules can be
enabled by examining the modules and header files on the system. If a module is
configured in :file:`Modules/Setup`, the :file:`setup.py` script won't attempt
to compile that module and will defer to the :file:`Modules/Setup` file's
contents. This provides a way to specific any strange command-line flags or
libraries that are required for a specific platform.
In another far-reaching change to the build mechanism, Neil Schemenauer
restructured things so Python now uses a single makefile that isn't recursive,
instead of makefiles in the top directory and in each of the :file:`Python/`,
:file:`Parser/`, :file:`Objects/`, and :file:`Modules/` subdirectories. This
makes building Python faster and also makes hacking the Makefiles clearer and
simpler.
.. seealso::
:pep:`229` - Using Distutils to Build Python
Written and implemented by A.M. Kuchling.
.. ======================================================================
PEP 205: Weak References
========================
Weak references, available through the :mod:`weakref` module, are a minor but
useful new data type in the Python programmer's toolbox.
Storing a reference to an object (say, in a dictionary or a list) has the side
effect of keeping that object alive forever. There are a few specific cases
where this behaviour is undesirable, object caches being the most common one,
and another being circular references in data structures such as trees.
For example, consider a memoizing function that caches the results of another
function ``f(x)`` by storing the function's argument and its result in a
dictionary::
_cache = {}
def memoize(x):
if _cache.has_key(x):
return _cache[x]
retval = f(x)
# Cache the returned object
_cache[x] = retval
return retval
This version works for simple things such as integers, but it has a side effect;
the ``_cache`` dictionary holds a reference to the return values, so they'll
never be deallocated until the Python process exits and cleans up. This isn't
very noticeable for integers, but if :func:`f` returns an object, or a data
structure that takes up a lot of memory, this can be a problem.
Weak references provide a way to implement a cache that won't keep objects alive
beyond their time. If an object is only accessible through weak references, the
object will be deallocated and the weak references will now indicate that the
object it referred to no longer exists. A weak reference to an object *obj* is
created by calling ``wr = weakref.ref(obj)``. The object being referred to is
returned by calling the weak reference as if it were a function: ``wr()``. It
will return the referenced object, or ``None`` if the object no longer exists.
This makes it possible to write a :func:`memoize` function whose cache doesn't
keep objects alive, by storing weak references in the cache. ::
_cache = {}
def memoize(x):
if _cache.has_key(x):
obj = _cache[x]()
# If weak reference object still exists,
# return it
if obj is not None: return obj
retval = f(x)
# Cache a weak reference
_cache[x] = weakref.ref(retval)
return retval
The :mod:`weakref` module also allows creating proxy objects which behave like
weak references --- an object referenced only by proxy objects is deallocated --
but instead of requiring an explicit call to retrieve the object, the proxy
transparently forwards all operations to the object as long as the object still
exists. If the object is deallocated, attempting to use a proxy will cause a
:exc:`weakref.ReferenceError` exception to be raised. ::
proxy = weakref.proxy(obj)
proxy.attr # Equivalent to obj.attr
proxy.meth() # Equivalent to obj.meth()
del obj
proxy.attr # raises weakref.ReferenceError
.. seealso::
:pep:`205` - Weak References
Written and implemented by Fred L. Drake, Jr.
.. ======================================================================
PEP 232: Function Attributes
============================
In Python 2.1, functions can now have arbitrary information attached to them.
People were often using docstrings to hold information about functions and
methods, because the ``__doc__`` attribute was the only way of attaching any
information to a function. For example, in the Zope Web application server,
functions are marked as safe for public access by having a docstring, and in
John Aycock's SPARK parsing framework, docstrings hold parts of the BNF grammar
to be parsed. This overloading is unfortunate, since docstrings are really
intended to hold a function's documentation; for example, it means you can't
properly document functions intended for private use in Zope.
Arbitrary attributes can now be set and retrieved on functions using the regular
Python syntax::
def f(): pass
f.publish = 1
f.secure = 1
f.grammar = "A ::= B (C D)*"
The dictionary containing attributes can be accessed as the function's
:attr:`~object.__dict__`. Unlike the :attr:`~object.__dict__` attribute of class instances, in
functions you can actually assign a new dictionary to :attr:`~object.__dict__`, though
the new value is restricted to a regular Python dictionary; you *can't* be
tricky and set it to a :class:`UserDict` instance, or any other random object
that behaves like a mapping.
.. seealso::
:pep:`232` - Function Attributes
Written and implemented by Barry Warsaw.
.. ======================================================================
PEP 235: Importing Modules on Case-Insensitive Platforms
========================================================
Some operating systems have filesystems that are case-insensitive, MacOS and
Windows being the primary examples; on these systems, it's impossible to
distinguish the filenames ``FILE.PY`` and ``file.py``, even though they do store
the file's name in its original case (they're case-preserving, too).
In Python 2.1, the :keyword:`import` statement will work to simulate case-sensitivity
on case-insensitive platforms. Python will now search for the first
case-sensitive match by default, raising an :exc:`ImportError` if no such file
is found, so ``import file`` will not import a module named ``FILE.PY``.
Case-insensitive matching can be requested by setting the :envvar:`PYTHONCASEOK`
environment variable before starting the Python interpreter.
.. ======================================================================
PEP 217: Interactive Display Hook
=================================
When using the Python interpreter interactively, the output of commands is
displayed using the built-in :func:`repr` function. In Python 2.1, the variable
:func:`sys.displayhook` can be set to a callable object which will be called
instead of :func:`repr`. For example, you can set it to a special
pretty-printing function::
>>> # Create a recursive data structure
... L = [1,2,3]
>>> L.append(L)
>>> L # Show Python's default output
[1, 2, 3, [...]]
>>> # Use pprint.pprint() as the display function
... import sys, pprint
>>> sys.displayhook = pprint.pprint
>>> L
[1, 2, 3, <Recursion on list with id=135143996>]
>>>
.. seealso::
:pep:`217` - Display Hook for Interactive Use
Written and implemented by Moshe Zadka.
.. ======================================================================
PEP 208: New Coercion Model
===========================
How numeric coercion is done at the C level was significantly modified. This
will only affect the authors of C extensions to Python, allowing them more
flexibility in writing extension types that support numeric operations.
Extension types can now set the type flag ``Py_TPFLAGS_CHECKTYPES`` in their
``PyTypeObject`` structure to indicate that they support the new coercion model.
In such extension types, the numeric slot functions can no longer assume that
they'll be passed two arguments of the same type; instead they may be passed two
arguments of differing types, and can then perform their own internal coercion.
If the slot function is passed a type it can't handle, it can indicate the
failure by returning a reference to the ``Py_NotImplemented`` singleton value.
The numeric functions of the other type will then be tried, and perhaps they can
handle the operation; if the other type also returns ``Py_NotImplemented``, then
a :exc:`TypeError` will be raised. Numeric methods written in Python can also
return ``Py_NotImplemented``, causing the interpreter to act as if the method
did not exist (perhaps raising a :exc:`TypeError`, perhaps trying another
object's numeric methods).
.. seealso::
:pep:`208` - Reworking the Coercion Model
Written and implemented by Neil Schemenauer, heavily based upon earlier work by
Marc-André Lemburg. Read this to understand the fine points of how numeric
operations will now be processed at the C level.
.. ======================================================================
PEP 241: Metadata in Python Packages
====================================
A common complaint from Python users is that there's no single catalog of all
the Python modules in existence. T. Middleton's Vaults of Parnassus at
http://www.vex.net/parnassus/ are the largest catalog of Python modules, but
registering software at the Vaults is optional, and many people don't bother.
As a first small step toward fixing the problem, Python software packaged using
the Distutils :command:`sdist` command will include a file named
:file:`PKG-INFO` containing information about the package such as its name,
version, and author (metadata, in cataloguing terminology). PEP 241 contains
the full list of fields that can be present in the :file:`PKG-INFO` file. As
people began to package their software using Python 2.1, more and more packages
will include metadata, making it possible to build automated cataloguing systems
and experiment with them. With the result experience, perhaps it'll be possible
to design a really good catalog and then build support for it into Python 2.2.
For example, the Distutils :command:`sdist` and :command:`bdist_\*` commands
could support an ``upload`` option that would automatically upload your
package to a catalog server.
You can start creating packages containing :file:`PKG-INFO` even if you're not
using Python 2.1, since a new release of the Distutils will be made for users of
earlier Python versions. Version 1.0.2 of the Distutils includes the changes
described in PEP 241, as well as various bugfixes and enhancements. It will be
available from the Distutils SIG at https://www.python.org/community/sigs/current/distutils-sig/.
.. seealso::
:pep:`241` - Metadata for Python Software Packages
Written and implemented by A.M. Kuchling.
:pep:`243` - Module Repository Upload Mechanism
Written by Sean Reifschneider, this draft PEP describes a proposed mechanism for
uploading Python packages to a central server.
.. ======================================================================
New and Improved Modules
========================
* Ka-Ping Yee contributed two new modules: :mod:`inspect.py`, a module for
getting information about live Python code, and :mod:`pydoc.py`, a module for
interactively converting docstrings to HTML or text. As a bonus,
:file:`Tools/scripts/pydoc`, which is now automatically installed, uses
:mod:`pydoc.py` to display documentation given a Python module, package, or
class name. For example, ``pydoc xml.dom`` displays the following::
Python Library Documentation: package xml.dom in xml
NAME
xml.dom - W3C Document Object Model implementation for Python.
FILE
/usr/local/lib/python2.1/xml/dom/__init__.pyc
DESCRIPTION
The Python mapping of the Document Object Model is documented in the
Python Library Reference in the section on the xml.dom package.
This package contains the following modules:
...
:file:`pydoc` also includes a Tk-based interactive help browser. :file:`pydoc`
quickly becomes addictive; try it out!
* Two different modules for unit testing were added to the standard library.
The :mod:`doctest` module, contributed by Tim Peters, provides a testing
framework based on running embedded examples in docstrings and comparing the
results against the expected output. PyUnit, contributed by Steve Purcell, is a
unit testing framework inspired by JUnit, which was in turn an adaptation of
Kent Beck's Smalltalk testing framework. See http://pyunit.sourceforge.net/ for
more information about PyUnit.
* The :mod:`difflib` module contains a class, :class:`SequenceMatcher`, which
compares two sequences and computes the changes required to transform one
sequence into the other. For example, this module can be used to write a tool
similar to the Unix :program:`diff` program, and in fact the sample program
:file:`Tools/scripts/ndiff.py` demonstrates how to write such a script.
* :mod:`curses.panel`, a wrapper for the panel library, part of ncurses and of
SYSV curses, was contributed by Thomas Gellekum. The panel library provides
windows with the additional feature of depth. Windows can be moved higher or
lower in the depth ordering, and the panel library figures out where panels
overlap and which sections are visible.
* The PyXML package has gone through a few releases since Python 2.0, and Python
2.1 includes an updated version of the :mod:`xml` package. Some of the
noteworthy changes include support for Expat 1.2 and later versions, the ability
for Expat parsers to handle files in any encoding supported by Python, and
various bugfixes for SAX, DOM, and the :mod:`minidom` module.
* Ping also contributed another hook for handling uncaught exceptions.
:func:`sys.excepthook` can be set to a callable object. When an exception isn't
caught by any :keyword:`try`...\ :keyword:`except` blocks, the exception will be
passed to :func:`sys.excepthook`, which can then do whatever it likes. At the
Ninth Python Conference, Ping demonstrated an application for this hook:
printing an extended traceback that not only lists the stack frames, but also
lists the function arguments and the local variables for each frame.
* Various functions in the :mod:`time` module, such as :func:`asctime` and
:func:`localtime`, require a floating point argument containing the time in
seconds since the epoch. The most common use of these functions is to work with
the current time, so the floating point argument has been made optional; when a
value isn't provided, the current time will be used. For example, log file
entries usually need a string containing the current time; in Python 2.1,
``time.asctime()`` can be used, instead of the lengthier
``time.asctime(time.localtime(time.time()))`` that was previously required.
This change was proposed and implemented by Thomas Wouters.
* The :mod:`ftplib` module now defaults to retrieving files in passive mode,
because passive mode is more likely to work from behind a firewall. This
request came from the Debian bug tracking system, since other Debian packages
use :mod:`ftplib` to retrieve files and then don't work from behind a firewall.
It's deemed unlikely that this will cause problems for anyone, because Netscape
defaults to passive mode and few people complain, but if passive mode is
unsuitable for your application or network setup, call ``set_pasv(0)`` on
FTP objects to disable passive mode.
* Support for raw socket access has been added to the :mod:`socket` module,
contributed by Grant Edwards.
* The :mod:`pstats` module now contains a simple interactive statistics browser
for displaying timing profiles for Python programs, invoked when the module is
run as a script. Contributed by Eric S. Raymond.
* A new implementation-dependent function, ``sys._getframe([depth])``, has
been added to return a given frame object from the current call stack.
:func:`sys._getframe` returns the frame at the top of the call stack; if the
optional integer argument *depth* is supplied, the function returns the frame
that is *depth* calls below the top of the stack. For example,
``sys._getframe(1)`` returns the caller's frame object.
This function is only present in CPython, not in Jython or the .NET
implementation. Use it for debugging, and resist the temptation to put it into
production code.
.. ======================================================================
Other Changes and Fixes
=======================
There were relatively few smaller changes made in Python 2.1 due to the shorter
release cycle. A search through the CVS change logs turns up 117 patches
applied, and 136 bugs fixed; both figures are likely to be underestimates. Some
of the more notable changes are:
* A specialized object allocator is now optionally available, that should be
faster than the system :func:`malloc` and have less memory overhead. The
allocator uses C's :func:`malloc` function to get large pools of memory, and
then fulfills smaller memory requests from these pools. It can be enabled by
providing the :option:`!--with-pymalloc` option to the :program:`configure`
script; see :file:`Objects/obmalloc.c` for the implementation details.
Authors of C extension modules should test their code with the object allocator
enabled, because some incorrect code may break, causing core dumps at runtime.
There are a bunch of memory allocation functions in Python's C API that have
previously been just aliases for the C library's :func:`malloc` and
:func:`free`, meaning that if you accidentally called mismatched functions, the
error wouldn't be noticeable. When the object allocator is enabled, these
functions aren't aliases of :func:`malloc` and :func:`free` any more, and
calling the wrong function to free memory will get you a core dump. For
example, if memory was allocated using :func:`PyMem_New`, it has to be freed
using :func:`PyMem_Del`, not :func:`free`. A few modules included with Python
fell afoul of this and had to be fixed; doubtless there are more third-party
modules that will have the same problem.
The object allocator was contributed by Vladimir Marangozov.
* The speed of line-oriented file I/O has been improved because people often
complain about its lack of speed, and because it's often been used as a naïve
benchmark. The :meth:`readline` method of file objects has therefore been
rewritten to be much faster. The exact amount of the speedup will vary from
platform to platform depending on how slow the C library's :func:`getc` was, but
is around 66%, and potentially much faster on some particular operating systems.
Tim Peters did much of the benchmarking and coding for this change, motivated by
a discussion in comp.lang.python.
A new module and method for file objects was also added, contributed by Jeff
Epler. The new method, :meth:`xreadlines`, is similar to the existing
:func:`xrange` built-in. :func:`xreadlines` returns an opaque sequence object
that only supports being iterated over, reading a line on every iteration but
not reading the entire file into memory as the existing :meth:`readlines` method
does. You'd use it like this::
for line in sys.stdin.xreadlines():
# ... do something for each line ...
...
For a fuller discussion of the line I/O changes, see the python-dev summary for
January 1--15, 2001 at https://mail.python.org/pipermail/python-dev/2001-January/.
* A new method, :meth:`popitem`, was added to dictionaries to enable
destructively iterating through the contents of a dictionary; this can be faster
for large dictionaries because there's no need to construct a list containing
all the keys or values. ``D.popitem()`` removes a random ``(key, value)`` pair
from the dictionary ``D`` and returns it as a 2-tuple. This was implemented
mostly by Tim Peters and Guido van Rossum, after a suggestion and preliminary
patch by Moshe Zadka.
* Modules can now control which names are imported when ``from module import *``
is used, by defining an ``__all__`` attribute containing a list of names that
will be imported. One common complaint is that if the module imports other
modules such as :mod:`sys` or :mod:`string`, ``from module import *`` will add
them to the importing module's namespace. To fix this, simply list the public
names in ``__all__``::
# List public names
__all__ = ['Database', 'open']
A stricter version of this patch was first suggested and implemented by Ben
Wolfson, but after some python-dev discussion, a weaker final version was
checked in.
* Applying :func:`repr` to strings previously used octal escapes for
non-printable characters; for example, a newline was ``'\012'``. This was a
vestigial trace of Python's C ancestry, but today octal is of very little
practical use. Ka-Ping Yee suggested using hex escapes instead of octal ones,
and using the ``\n``, ``\t``, ``\r`` escapes for the appropriate characters,
and implemented this new formatting.
* Syntax errors detected at compile-time can now raise exceptions containing the
filename and line number of the error, a pleasant side effect of the compiler
reorganization done by Jeremy Hylton.
* C extensions which import other modules have been changed to use
:func:`PyImport_ImportModule`, which means that they will use any import hooks
that have been installed. This is also encouraged for third-party extensions
that need to import some other module from C code.
* The size of the Unicode character database was shrunk by another 340K thanks
to Fredrik Lundh.
* Some new ports were contributed: MacOS X (by Steven Majewski), Cygwin (by
Jason Tishler); RISCOS (by Dietmar Schwertberger); Unixware 7 (by Billy G.
Allie).
And there's the usual list of minor bugfixes, minor memory leaks, docstring
edits, and other tweaks, too lengthy to be worth itemizing; see the CVS logs for
the full details if you want them.
.. ======================================================================
Acknowledgements
================
The author would like to thank the following people for offering suggestions on
various drafts of this article: Graeme Cross, David Goodger, Jay Graves, Michael
Hudson, Marc-André Lemburg, Fredrik Lundh, Neil Schemenauer, Thomas Wouters.

1269
third_party/python/Doc/whatsnew/2.2.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

2086
third_party/python/Doc/whatsnew/2.3.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

1565
third_party/python/Doc/whatsnew/2.4.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

2289
third_party/python/Doc/whatsnew/2.5.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

3315
third_party/python/Doc/whatsnew/2.6.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

2799
third_party/python/Doc/whatsnew/2.7.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

929
third_party/python/Doc/whatsnew/3.0.rst vendored Normal file
View file

@ -0,0 +1,929 @@
****************************
What's New In Python 3.0
****************************
.. XXX Add trademark info for Apple, Microsoft.
:Author: Guido van Rossum
.. $Id$
Rules for maintenance:
* Anyone can add text to this document. Do not spend very much time
on the wording of your changes, because your text will probably
get rewritten to some degree.
* The maintainer will go through Misc/NEWS periodically and add
changes; it's therefore more important to add your changes to
Misc/NEWS than to this file. (Note: I didn't get to this for 3.0.
GvR.)
* This is not a complete list of every single change; completeness
is the purpose of Misc/NEWS. Some changes I consider too small
or esoteric to include. If such a change is added to the text,
I'll just remove it. (This is another reason you shouldn't spend
too much time on writing your addition.)
* If you want to draw your new text to the attention of the
maintainer, add 'XXX' to the beginning of the paragraph or
section.
* It's OK to just add a fragmentary note about a change. For
example: "XXX Describe the transmogrify() function added to the
socket module." The maintainer will research the change and
write the necessary text.
* You can comment out your additions if you like, but it's not
necessary (especially when a final release is some months away).
* Credit the author of a patch or bugfix. Just the name is
sufficient; the e-mail address isn't necessary. (Due to time
constraints I haven't managed to do this for 3.0. GvR.)
* It's helpful to add the bug/patch number as a comment:
% Patch 12345
XXX Describe the transmogrify() function added to the socket
module.
(Contributed by P.Y. Developer.)
This saves the maintainer the effort of going through the SVN log
when researching a change. (Again, I didn't get to this for 3.0.
GvR.)
This article explains the new features in Python 3.0, compared to 2.6.
Python 3.0, also known as "Python 3000" or "Py3K", is the first ever
*intentionally backwards incompatible* Python release. There are more
changes than in a typical release, and more that are important for all
Python users. Nevertheless, after digesting the changes, you'll find
that Python really hasn't changed all that much -- by and large, we're
mostly fixing well-known annoyances and warts, and removing a lot of
old cruft.
This article doesn't attempt to provide a complete specification of
all new features, but instead tries to give a convenient overview.
For full details, you should refer to the documentation for Python
3.0, and/or the many PEPs referenced in the text. If you want to
understand the complete implementation and design rationale for a
particular feature, PEPs usually have more details than the regular
documentation; but note that PEPs usually are not kept up-to-date once
a feature has been fully implemented.
Due to time constraints this document is not as complete as it should
have been. As always for a new release, the ``Misc/NEWS`` file in the
source distribution contains a wealth of detailed information about
every small thing that was changed.
.. Compare with previous release in 2 - 3 sentences here.
.. add hyperlink when the documentation becomes available online.
.. ======================================================================
.. Large, PEP-level features and changes should be described here.
.. Should there be a new section here for 3k migration?
.. Or perhaps a more general section describing module changes/deprecation?
.. sets module deprecated
.. ======================================================================
Common Stumbling Blocks
=======================
This section lists those few changes that are most likely to trip you
up if you're used to Python 2.5.
Print Is A Function
-------------------
The ``print`` statement has been replaced with a :func:`print`
function, with keyword arguments to replace most of the special syntax
of the old ``print`` statement (:pep:`3105`). Examples::
Old: print "The answer is", 2*2
New: print("The answer is", 2*2)
Old: print x, # Trailing comma suppresses newline
New: print(x, end=" ") # Appends a space instead of a newline
Old: print # Prints a newline
New: print() # You must call the function!
Old: print >>sys.stderr, "fatal error"
New: print("fatal error", file=sys.stderr)
Old: print (x, y) # prints repr((x, y))
New: print((x, y)) # Not the same as print(x, y)!
You can also customize the separator between items, e.g.::
print("There are <", 2**32, "> possibilities!", sep="")
which produces:
.. code-block:: none
There are <4294967296> possibilities!
Note:
* The :func:`print` function doesn't support the "softspace" feature of
the old ``print`` statement. For example, in Python 2.x,
``print "A\n", "B"`` would write ``"A\nB\n"``; but in Python 3.0,
``print("A\n", "B")`` writes ``"A\n B\n"``.
* Initially, you'll be finding yourself typing the old ``print x``
a lot in interactive mode. Time to retrain your fingers to type
``print(x)`` instead!
* When using the ``2to3`` source-to-source conversion tool, all
``print`` statements are automatically converted to
:func:`print` function calls, so this is mostly a non-issue for
larger projects.
Views And Iterators Instead Of Lists
-------------------------------------
Some well-known APIs no longer return lists:
* :class:`dict` methods :meth:`dict.keys`, :meth:`dict.items` and
:meth:`dict.values` return "views" instead of lists. For example,
this no longer works: ``k = d.keys(); k.sort()``. Use ``k =
sorted(d)`` instead (this works in Python 2.5 too and is just
as efficient).
* Also, the :meth:`dict.iterkeys`, :meth:`dict.iteritems` and
:meth:`dict.itervalues` methods are no longer supported.
* :func:`map` and :func:`filter` return iterators. If you really need
a list and the input sequences are all of equal length, a quick
fix is to wrap :func:`map` in :func:`list`, e.g. ``list(map(...))``,
but a better fix is
often to use a list comprehension (especially when the original code
uses :keyword:`lambda`), or rewriting the code so it doesn't need a
list at all. Particularly tricky is :func:`map` invoked for the
side effects of the function; the correct transformation is to use a
regular :keyword:`for` loop (since creating a list would just be
wasteful).
If the input sequences are not of equal length, :func:`map` will
stop at the termination of the shortest of the sequences. For full
compatibility with :func:`map` from Python 2.x, also wrap the sequences in
:func:`itertools.zip_longest`, e.g. ``map(func, *sequences)`` becomes
``list(map(func, itertools.zip_longest(*sequences)))``.
* :func:`range` now behaves like :func:`xrange` used to behave, except
it works with values of arbitrary size. The latter no longer
exists.
* :func:`zip` now returns an iterator.
Ordering Comparisons
--------------------
Python 3.0 has simplified the rules for ordering comparisons:
* The ordering comparison operators (``<``, ``<=``, ``>=``, ``>``)
raise a TypeError exception when the operands don't have a
meaningful natural ordering. Thus, expressions like ``1 < ''``, ``0
> None`` or ``len <= len`` are no longer valid, and e.g. ``None <
None`` raises :exc:`TypeError` instead of returning
``False``. A corollary is that sorting a heterogeneous list
no longer makes sense -- all the elements must be comparable to each
other. Note that this does not apply to the ``==`` and ``!=``
operators: objects of different incomparable types always compare
unequal to each other.
* :meth:`builtin.sorted` and :meth:`list.sort` no longer accept the
*cmp* argument providing a comparison function. Use the *key*
argument instead. N.B. the *key* and *reverse* arguments are now
"keyword-only".
* The :func:`cmp` function should be treated as gone, and the :meth:`__cmp__`
special method is no longer supported. Use :meth:`__lt__` for sorting,
:meth:`__eq__` with :meth:`__hash__`, and other rich comparisons as needed.
(If you really need the :func:`cmp` functionality, you could use the
expression ``(a > b) - (a < b)`` as the equivalent for ``cmp(a, b)``.)
Integers
--------
* :pep:`237`: Essentially, :class:`long` renamed to :class:`int`.
That is, there is only one built-in integral type, named
:class:`int`; but it behaves mostly like the old :class:`long` type.
* :pep:`238`: An expression like ``1/2`` returns a float. Use
``1//2`` to get the truncating behavior. (The latter syntax has
existed for years, at least since Python 2.2.)
* The :data:`sys.maxint` constant was removed, since there is no
longer a limit to the value of integers. However, :data:`sys.maxsize`
can be used as an integer larger than any practical list or string
index. It conforms to the implementation's "natural" integer size
and is typically the same as :data:`sys.maxint` in previous releases
on the same platform (assuming the same build options).
* The :func:`repr` of a long integer doesn't include the trailing ``L``
anymore, so code that unconditionally strips that character will
chop off the last digit instead. (Use :func:`str` instead.)
* Octal literals are no longer of the form ``0720``; use ``0o720``
instead.
Text Vs. Data Instead Of Unicode Vs. 8-bit
------------------------------------------
Everything you thought you knew about binary data and Unicode has
changed.
* Python 3.0 uses the concepts of *text* and (binary) *data* instead
of Unicode strings and 8-bit strings. All text is Unicode; however
*encoded* Unicode is represented as binary data. The type used to
hold text is :class:`str`, the type used to hold data is
:class:`bytes`. The biggest difference with the 2.x situation is
that any attempt to mix text and data in Python 3.0 raises
:exc:`TypeError`, whereas if you were to mix Unicode and 8-bit
strings in Python 2.x, it would work if the 8-bit string happened to
contain only 7-bit (ASCII) bytes, but you would get
:exc:`UnicodeDecodeError` if it contained non-ASCII values. This
value-specific behavior has caused numerous sad faces over the
years.
* As a consequence of this change in philosophy, pretty much all code
that uses Unicode, encodings or binary data most likely has to
change. The change is for the better, as in the 2.x world there
were numerous bugs having to do with mixing encoded and unencoded
text. To be prepared in Python 2.x, start using :class:`unicode`
for all unencoded text, and :class:`str` for binary or encoded data
only. Then the ``2to3`` tool will do most of the work for you.
* You can no longer use ``u"..."`` literals for Unicode text.
However, you must use ``b"..."`` literals for binary data.
* As the :class:`str` and :class:`bytes` types cannot be mixed, you
must always explicitly convert between them. Use :meth:`str.encode`
to go from :class:`str` to :class:`bytes`, and :meth:`bytes.decode`
to go from :class:`bytes` to :class:`str`. You can also use
``bytes(s, encoding=...)`` and ``str(b, encoding=...)``,
respectively.
* Like :class:`str`, the :class:`bytes` type is immutable. There is a
separate *mutable* type to hold buffered binary data,
:class:`bytearray`. Nearly all APIs that accept :class:`bytes` also
accept :class:`bytearray`. The mutable API is based on
:class:`collections.MutableSequence`.
* All backslashes in raw string literals are interpreted literally.
This means that ``'\U'`` and ``'\u'`` escapes in raw strings are not
treated specially. For example, ``r'\u20ac'`` is a string of 6
characters in Python 3.0, whereas in 2.6, ``ur'\u20ac'`` was the
single "euro" character. (Of course, this change only affects raw
string literals; the euro character is ``'\u20ac'`` in Python 3.0.)
* The built-in :class:`basestring` abstract type was removed. Use
:class:`str` instead. The :class:`str` and :class:`bytes` types
don't have functionality enough in common to warrant a shared base
class. The ``2to3`` tool (see below) replaces every occurrence of
:class:`basestring` with :class:`str`.
* Files opened as text files (still the default mode for :func:`open`)
always use an encoding to map between strings (in memory) and bytes
(on disk). Binary files (opened with a ``b`` in the mode argument)
always use bytes in memory. This means that if a file is opened
using an incorrect mode or encoding, I/O will likely fail loudly,
instead of silently producing incorrect data. It also means that
even Unix users will have to specify the correct mode (text or
binary) when opening a file. There is a platform-dependent default
encoding, which on Unixy platforms can be set with the ``LANG``
environment variable (and sometimes also with some other
platform-specific locale-related environment variables). In many
cases, but not all, the system default is UTF-8; you should never
count on this default. Any application reading or writing more than
pure ASCII text should probably have a way to override the encoding.
There is no longer any need for using the encoding-aware streams
in the :mod:`codecs` module.
* The initial values of :data:`sys.stdin`, :data:`sys.stdout` and
:data:`sys.stderr` are now unicode-only text files (i.e., they are
instances of :class:`io.TextIOBase`). To read and write bytes data
with these streams, you need to use their :data:`io.TextIOBase.buffer`
attribute.
* Filenames are passed to and returned from APIs as (Unicode) strings.
This can present platform-specific problems because on some
platforms filenames are arbitrary byte strings. (On the other hand,
on Windows filenames are natively stored as Unicode.) As a
work-around, most APIs (e.g. :func:`open` and many functions in the
:mod:`os` module) that take filenames accept :class:`bytes` objects
as well as strings, and a few APIs have a way to ask for a
:class:`bytes` return value. Thus, :func:`os.listdir` returns a
list of :class:`bytes` instances if the argument is a :class:`bytes`
instance, and :func:`os.getcwdb` returns the current working
directory as a :class:`bytes` instance. Note that when
:func:`os.listdir` returns a list of strings, filenames that
cannot be decoded properly are omitted rather than raising
:exc:`UnicodeError`.
* Some system APIs like :data:`os.environ` and :data:`sys.argv` can
also present problems when the bytes made available by the system is
not interpretable using the default encoding. Setting the ``LANG``
variable and rerunning the program is probably the best approach.
* :pep:`3138`: The :func:`repr` of a string no longer escapes
non-ASCII characters. It still escapes control characters and code
points with non-printable status in the Unicode standard, however.
* :pep:`3120`: The default source encoding is now UTF-8.
* :pep:`3131`: Non-ASCII letters are now allowed in identifiers.
(However, the standard library remains ASCII-only with the exception
of contributor names in comments.)
* The :mod:`StringIO` and :mod:`cStringIO` modules are gone. Instead,
import the :mod:`io` module and use :class:`io.StringIO` or
:class:`io.BytesIO` for text and data respectively.
* See also the :ref:`unicode-howto`, which was updated for Python 3.0.
Overview Of Syntax Changes
==========================
This section gives a brief overview of every *syntactic* change in
Python 3.0.
New Syntax
----------
* :pep:`3107`: Function argument and return value annotations. This
provides a standardized way of annotating a function's parameters
and return value. There are no semantics attached to such
annotations except that they can be introspected at runtime using
the :attr:`__annotations__` attribute. The intent is to encourage
experimentation through metaclasses, decorators or frameworks.
* :pep:`3102`: Keyword-only arguments. Named parameters occurring
after ``*args`` in the parameter list *must* be specified using
keyword syntax in the call. You can also use a bare ``*`` in the
parameter list to indicate that you don't accept a variable-length
argument list, but you do have keyword-only arguments.
* Keyword arguments are allowed after the list of base classes in a
class definition. This is used by the new convention for specifying
a metaclass (see next section), but can be used for other purposes
as well, as long as the metaclass supports it.
* :pep:`3104`: :keyword:`nonlocal` statement. Using ``nonlocal x``
you can now assign directly to a variable in an outer (but
non-global) scope. :keyword:`nonlocal` is a new reserved word.
* :pep:`3132`: Extended Iterable Unpacking. You can now write things
like ``a, b, *rest = some_sequence``. And even ``*rest, a =
stuff``. The ``rest`` object is always a (possibly empty) list; the
right-hand side may be any iterable. Example::
(a, *rest, b) = range(5)
This sets *a* to ``0``, *b* to ``4``, and *rest* to ``[1, 2, 3]``.
* Dictionary comprehensions: ``{k: v for k, v in stuff}`` means the
same thing as ``dict(stuff)`` but is more flexible. (This is
:pep:`274` vindicated. :-)
* Set literals, e.g. ``{1, 2}``. Note that ``{}`` is an empty
dictionary; use ``set()`` for an empty set. Set comprehensions are
also supported; e.g., ``{x for x in stuff}`` means the same thing as
``set(stuff)`` but is more flexible.
* New octal literals, e.g. ``0o720`` (already in 2.6). The old octal
literals (``0720``) are gone.
* New binary literals, e.g. ``0b1010`` (already in 2.6), and
there is a new corresponding built-in function, :func:`bin`.
* Bytes literals are introduced with a leading ``b`` or ``B``, and
there is a new corresponding built-in function, :func:`bytes`.
Changed Syntax
--------------
* :pep:`3109` and :pep:`3134`: new :keyword:`raise` statement syntax:
:samp:`raise [{expr} [from {expr}]]`. See below.
* :keyword:`as` and :keyword:`with` are now reserved words. (Since
2.6, actually.)
* ``True``, ``False``, and ``None`` are reserved words. (2.6 partially enforced
the restrictions on ``None`` already.)
* Change from :keyword:`except` *exc*, *var* to
:keyword:`except` *exc* :keyword:`as` *var*. See :pep:`3110`.
* :pep:`3115`: New Metaclass Syntax. Instead of::
class C:
__metaclass__ = M
...
you must now use::
class C(metaclass=M):
...
The module-global :data:`__metaclass__` variable is no longer
supported. (It was a crutch to make it easier to default to
new-style classes without deriving every class from
:class:`object`.)
* List comprehensions no longer support the syntactic form
:samp:`[... for {var} in {item1}, {item2}, ...]`. Use
:samp:`[... for {var} in ({item1}, {item2}, ...)]` instead.
Also note that list comprehensions have different semantics: they
are closer to syntactic sugar for a generator expression inside a
:func:`list` constructor, and in particular the loop control
variables are no longer leaked into the surrounding scope.
* The *ellipsis* (``...``) can be used as an atomic expression
anywhere. (Previously it was only allowed in slices.) Also, it
*must* now be spelled as ``...``. (Previously it could also be
spelled as ``. . .``, by a mere accident of the grammar.)
Removed Syntax
--------------
* :pep:`3113`: Tuple parameter unpacking removed. You can no longer
write ``def foo(a, (b, c)): ...``.
Use ``def foo(a, b_c): b, c = b_c`` instead.
* Removed backticks (use :func:`repr` instead).
* Removed ``<>`` (use ``!=`` instead).
* Removed keyword: :func:`exec` is no longer a keyword; it remains as
a function. (Fortunately the function syntax was also accepted in
2.x.) Also note that :func:`exec` no longer takes a stream argument;
instead of ``exec(f)`` you can use ``exec(f.read())``.
* Integer literals no longer support a trailing ``l`` or ``L``.
* String literals no longer support a leading ``u`` or ``U``.
* The :keyword:`from` *module* :keyword:`import` ``*`` syntax is only
allowed at the module level, no longer inside functions.
* The only acceptable syntax for relative imports is :samp:`from .[{module}]
import {name}`. All :keyword:`import` forms not starting with ``.`` are
interpreted as absolute imports. (:pep:`328`)
* Classic classes are gone.
Changes Already Present In Python 2.6
=====================================
Since many users presumably make the jump straight from Python 2.5 to
Python 3.0, this section reminds the reader of new features that were
originally designed for Python 3.0 but that were back-ported to Python
2.6. The corresponding sections in :ref:`whats-new-in-2.6` should be
consulted for longer descriptions.
* :ref:`pep-0343`. The :keyword:`with` statement is now a standard
feature and no longer needs to be imported from the :mod:`__future__`.
Also check out :ref:`new-26-context-managers` and
:ref:`new-module-contextlib`.
* :ref:`pep-0366`. This enhances the usefulness of the :option:`-m`
option when the referenced module lives in a package.
* :ref:`pep-0370`.
* :ref:`pep-0371`.
* :ref:`pep-3101`. Note: the 2.6 description mentions the
:meth:`format` method for both 8-bit and Unicode strings. In 3.0,
only the :class:`str` type (text strings with Unicode support)
supports this method; the :class:`bytes` type does not. The plan is
to eventually make this the only API for string formatting, and to
start deprecating the ``%`` operator in Python 3.1.
* :ref:`pep-3105`. This is now a standard feature and no longer needs
to be imported from :mod:`__future__`. More details were given above.
* :ref:`pep-3110`. The :keyword:`except` *exc* :keyword:`as` *var*
syntax is now standard and :keyword:`except` *exc*, *var* is no
longer supported. (Of course, the :keyword:`as` *var* part is still
optional.)
* :ref:`pep-3112`. The ``b"..."`` string literal notation (and its
variants like ``b'...'``, ``b"""..."""``, and ``br"..."``) now
produces a literal of type :class:`bytes`.
* :ref:`pep-3116`. The :mod:`io` module is now the standard way of
doing file I/O. The built-in :func:`open` function is now an
alias for :func:`io.open` and has additional keyword arguments
*encoding*, *errors*, *newline* and *closefd*. Also note that an
invalid *mode* argument now raises :exc:`ValueError`, not
:exc:`IOError`. The binary file object underlying a text file
object can be accessed as :attr:`f.buffer` (but beware that the
text object maintains a buffer of itself in order to speed up
the encoding and decoding operations).
* :ref:`pep-3118`. The old builtin :func:`buffer` is now really gone;
the new builtin :func:`memoryview` provides (mostly) similar
functionality.
* :ref:`pep-3119`. The :mod:`abc` module and the ABCs defined in the
:mod:`collections` module plays a somewhat more prominent role in
the language now, and built-in collection types like :class:`dict`
and :class:`list` conform to the :class:`collections.MutableMapping`
and :class:`collections.MutableSequence` ABCs, respectively.
* :ref:`pep-3127`. As mentioned above, the new octal literal
notation is the only one supported, and binary literals have been
added.
* :ref:`pep-3129`.
* :ref:`pep-3141`. The :mod:`numbers` module is another new use of
ABCs, defining Python's "numeric tower". Also note the new
:mod:`fractions` module which implements :class:`numbers.Rational`.
Library Changes
===============
Due to time constraints, this document does not exhaustively cover the
very extensive changes to the standard library. :pep:`3108` is the
reference for the major changes to the library. Here's a capsule
review:
* Many old modules were removed. Some, like :mod:`gopherlib` (no
longer used) and :mod:`md5` (replaced by :mod:`hashlib`), were
already deprecated by :pep:`4`. Others were removed as a result
of the removal of support for various platforms such as Irix, BeOS
and Mac OS 9 (see :pep:`11`). Some modules were also selected for
removal in Python 3.0 due to lack of use or because a better
replacement exists. See :pep:`3108` for an exhaustive list.
* The :mod:`bsddb3` package was removed because its presence in the
core standard library has proved over time to be a particular burden
for the core developers due to testing instability and Berkeley DB's
release schedule. However, the package is alive and well,
externally maintained at https://www.jcea.es/programacion/pybsddb.htm.
* Some modules were renamed because their old name disobeyed
:pep:`8`, or for various other reasons. Here's the list:
======================= =======================
Old Name New Name
======================= =======================
_winreg winreg
ConfigParser configparser
copy_reg copyreg
Queue queue
SocketServer socketserver
markupbase _markupbase
repr reprlib
test.test_support test.support
======================= =======================
* A common pattern in Python 2.x is to have one version of a module
implemented in pure Python, with an optional accelerated version
implemented as a C extension; for example, :mod:`pickle` and
:mod:`cPickle`. This places the burden of importing the accelerated
version and falling back on the pure Python version on each user of
these modules. In Python 3.0, the accelerated versions are
considered implementation details of the pure Python versions.
Users should always import the standard version, which attempts to
import the accelerated version and falls back to the pure Python
version. The :mod:`pickle` / :mod:`cPickle` pair received this
treatment. The :mod:`profile` module is on the list for 3.1. The
:mod:`StringIO` module has been turned into a class in the :mod:`io`
module.
* Some related modules have been grouped into packages, and usually
the submodule names have been simplified. The resulting new
packages are:
* :mod:`dbm` (:mod:`anydbm`, :mod:`dbhash`, :mod:`dbm`,
:mod:`dumbdbm`, :mod:`gdbm`, :mod:`whichdb`).
* :mod:`html` (:mod:`HTMLParser`, :mod:`htmlentitydefs`).
* :mod:`http` (:mod:`httplib`, :mod:`BaseHTTPServer`,
:mod:`CGIHTTPServer`, :mod:`SimpleHTTPServer`, :mod:`Cookie`,
:mod:`cookielib`).
* :mod:`tkinter` (all :mod:`Tkinter`-related modules except
:mod:`turtle`). The target audience of :mod:`turtle` doesn't
really care about :mod:`tkinter`. Also note that as of Python
2.6, the functionality of :mod:`turtle` has been greatly enhanced.
* :mod:`urllib` (:mod:`urllib`, :mod:`urllib2`, :mod:`urlparse`,
:mod:`robotparse`).
* :mod:`xmlrpc` (:mod:`xmlrpclib`, :mod:`DocXMLRPCServer`,
:mod:`SimpleXMLRPCServer`).
Some other changes to standard library modules, not covered by
:pep:`3108`:
* Killed :mod:`sets`. Use the built-in :func:`set` class.
* Cleanup of the :mod:`sys` module: removed :func:`sys.exitfunc`,
:func:`sys.exc_clear`, :data:`sys.exc_type`, :data:`sys.exc_value`,
:data:`sys.exc_traceback`. (Note that :data:`sys.last_type`
etc. remain.)
* Cleanup of the :class:`array.array` type: the :meth:`read` and
:meth:`write` methods are gone; use :meth:`fromfile` and
:meth:`tofile` instead. Also, the ``'c'`` typecode for array is
gone -- use either ``'b'`` for bytes or ``'u'`` for Unicode
characters.
* Cleanup of the :mod:`operator` module: removed
:func:`sequenceIncludes` and :func:`isCallable`.
* Cleanup of the :mod:`thread` module: :func:`acquire_lock` and
:func:`release_lock` are gone; use :func:`acquire` and
:func:`release` instead.
* Cleanup of the :mod:`random` module: removed the :func:`jumpahead` API.
* The :mod:`new` module is gone.
* The functions :func:`os.tmpnam`, :func:`os.tempnam` and
:func:`os.tmpfile` have been removed in favor of the :mod:`tempfile`
module.
* The :mod:`tokenize` module has been changed to work with bytes. The
main entry point is now :func:`tokenize.tokenize`, instead of
generate_tokens.
* :data:`string.letters` and its friends (:data:`string.lowercase` and
:data:`string.uppercase`) are gone. Use
:data:`string.ascii_letters` etc. instead. (The reason for the
removal is that :data:`string.letters` and friends had
locale-specific behavior, which is a bad idea for such
attractively-named global "constants".)
* Renamed module :mod:`__builtin__` to :mod:`builtins` (removing the
underscores, adding an 's'). The :data:`__builtins__` variable
found in most global namespaces is unchanged. To modify a builtin,
you should use :mod:`builtins`, not :data:`__builtins__`!
:pep:`3101`: A New Approach To String Formatting
================================================
* A new system for built-in string formatting operations replaces the
``%`` string formatting operator. (However, the ``%`` operator is
still supported; it will be deprecated in Python 3.1 and removed
from the language at some later time.) Read :pep:`3101` for the full
scoop.
Changes To Exceptions
=====================
The APIs for raising and catching exception have been cleaned up and
new powerful features added:
* :pep:`352`: All exceptions must be derived (directly or indirectly)
from :exc:`BaseException`. This is the root of the exception
hierarchy. This is not new as a recommendation, but the
*requirement* to inherit from :exc:`BaseException` is new. (Python
2.6 still allowed classic classes to be raised, and placed no
restriction on what you can catch.) As a consequence, string
exceptions are finally truly and utterly dead.
* Almost all exceptions should actually derive from :exc:`Exception`;
:exc:`BaseException` should only be used as a base class for
exceptions that should only be handled at the top level, such as
:exc:`SystemExit` or :exc:`KeyboardInterrupt`. The recommended
idiom for handling all exceptions except for this latter category is
to use :keyword:`except` :exc:`Exception`.
* :exc:`StandardError` was removed.
* Exceptions no longer behave as sequences. Use the :attr:`args`
attribute instead.
* :pep:`3109`: Raising exceptions. You must now use :samp:`raise
{Exception}({args})` instead of :samp:`raise {Exception}, {args}`.
Additionally, you can no longer explicitly specify a traceback;
instead, if you *have* to do this, you can assign directly to the
:attr:`__traceback__` attribute (see below).
* :pep:`3110`: Catching exceptions. You must now use
:samp:`except {SomeException} as {variable}` instead
of :samp:`except {SomeException}, {variable}`. Moreover, the
*variable* is explicitly deleted when the :keyword:`except` block
is left.
* :pep:`3134`: Exception chaining. There are two cases: implicit
chaining and explicit chaining. Implicit chaining happens when an
exception is raised in an :keyword:`except` or :keyword:`finally`
handler block. This usually happens due to a bug in the handler
block; we call this a *secondary* exception. In this case, the
original exception (that was being handled) is saved as the
:attr:`__context__` attribute of the secondary exception.
Explicit chaining is invoked with this syntax::
raise SecondaryException() from primary_exception
(where *primary_exception* is any expression that produces an
exception object, probably an exception that was previously caught).
In this case, the primary exception is stored on the
:attr:`__cause__` attribute of the secondary exception. The
traceback printed when an unhandled exception occurs walks the chain
of :attr:`__cause__` and :attr:`__context__` attributes and prints a
separate traceback for each component of the chain, with the primary
exception at the top. (Java users may recognize this behavior.)
* :pep:`3134`: Exception objects now store their traceback as the
:attr:`__traceback__` attribute. This means that an exception
object now contains all the information pertaining to an exception,
and there are fewer reasons to use :func:`sys.exc_info` (though the
latter is not removed).
* A few exception messages are improved when Windows fails to load an
extension module. For example, ``error code 193`` is now ``%1 is
not a valid Win32 application``. Strings now deal with non-English
locales.
Miscellaneous Other Changes
===========================
Operators And Special Methods
-----------------------------
* ``!=`` now returns the opposite of ``==``, unless ``==`` returns
:data:`NotImplemented`.
* The concept of "unbound methods" has been removed from the language.
When referencing a method as a class attribute, you now get a plain
function object.
* :meth:`__getslice__`, :meth:`__setslice__` and :meth:`__delslice__`
were killed. The syntax ``a[i:j]`` now translates to
``a.__getitem__(slice(i, j))`` (or :meth:`__setitem__` or
:meth:`__delitem__`, when used as an assignment or deletion target,
respectively).
* :pep:`3114`: the standard :meth:`next` method has been renamed to
:meth:`~iterator.__next__`.
* The :meth:`__oct__` and :meth:`__hex__` special methods are removed
-- :func:`oct` and :func:`hex` use :meth:`__index__` now to convert
the argument to an integer.
* Removed support for :attr:`__members__` and :attr:`__methods__`.
* The function attributes named :attr:`func_X` have been renamed to
use the :data:`__X__` form, freeing up these names in the function
attribute namespace for user-defined attributes. To wit,
:attr:`func_closure`, :attr:`func_code`, :attr:`func_defaults`,
:attr:`func_dict`, :attr:`func_doc`, :attr:`func_globals`,
:attr:`func_name` were renamed to :attr:`__closure__`,
:attr:`__code__`, :attr:`__defaults__`, :attr:`~object.__dict__`,
:attr:`__doc__`, :attr:`__globals__`, :attr:`~definition.__name__`,
respectively.
* :meth:`__nonzero__` is now :meth:`__bool__`.
Builtins
--------
* :pep:`3135`: New :func:`super`. You can now invoke :func:`super`
without arguments and (assuming this is in a regular instance method
defined inside a :keyword:`class` statement) the right class and
instance will automatically be chosen. With arguments, the behavior
of :func:`super` is unchanged.
* :pep:`3111`: :func:`raw_input` was renamed to :func:`input`. That
is, the new :func:`input` function reads a line from
:data:`sys.stdin` and returns it with the trailing newline stripped.
It raises :exc:`EOFError` if the input is terminated prematurely.
To get the old behavior of :func:`input`, use ``eval(input())``.
* A new built-in function :func:`next` was added to call the
:meth:`~iterator.__next__` method on an object.
* The :func:`round` function rounding strategy and return type have
changed. Exact halfway cases are now rounded to the nearest even
result instead of away from zero. (For example, ``round(2.5)`` now
returns ``2`` rather than ``3``.) ``round(x[, n])`` now
delegates to ``x.__round__([n])`` instead of always returning a
float. It generally returns an integer when called with a single
argument and a value of the same type as ``x`` when called with two
arguments.
* Moved :func:`intern` to :func:`sys.intern`.
* Removed: :func:`apply`. Instead of ``apply(f, args)`` use
``f(*args)``.
* Removed :func:`callable`. Instead of ``callable(f)`` you can use
``isinstance(f, collections.Callable)``. The :func:`operator.isCallable`
function is also gone.
* Removed :func:`coerce`. This function no longer serves a purpose
now that classic classes are gone.
* Removed :func:`execfile`. Instead of ``execfile(fn)`` use
``exec(open(fn).read())``.
* Removed the :class:`file` type. Use :func:`open`. There are now several
different kinds of streams that open can return in the :mod:`io` module.
* Removed :func:`reduce`. Use :func:`functools.reduce` if you really
need it; however, 99 percent of the time an explicit :keyword:`for`
loop is more readable.
* Removed :func:`reload`. Use :func:`imp.reload`.
* Removed. :meth:`dict.has_key` -- use the :keyword:`in` operator
instead.
.. ======================================================================
Build and C API Changes
=======================
Due to time constraints, here is a *very* incomplete list of changes
to the C API.
* Support for several platforms was dropped, including but not limited
to Mac OS 9, BeOS, RISCOS, Irix, and Tru64.
* :pep:`3118`: New Buffer API.
* :pep:`3121`: Extension Module Initialization & Finalization.
* :pep:`3123`: Making :c:macro:`PyObject_HEAD` conform to standard C.
* No more C API support for restricted execution.
* :c:func:`PyNumber_Coerce`, :c:func:`PyNumber_CoerceEx`,
:c:func:`PyMember_Get`, and :c:func:`PyMember_Set` C APIs are removed.
* New C API :c:func:`PyImport_ImportModuleNoBlock`, works like
:c:func:`PyImport_ImportModule` but won't block on the import lock
(returning an error instead).
* Renamed the boolean conversion C-level slot and method:
``nb_nonzero`` is now ``nb_bool``.
* Removed :c:macro:`METH_OLDARGS` and :c:macro:`WITH_CYCLE_GC` from the C API.
.. ======================================================================
Performance
===========
The net result of the 3.0 generalizations is that Python 3.0 runs the
pystone benchmark around 10% slower than Python 2.5. Most likely the
biggest cause is the removal of special-casing for small integers.
There's room for improvement, but it will happen after 3.0 is
released!
.. ======================================================================
Porting To Python 3.0
=====================
For porting existing Python 2.5 or 2.6 source code to Python 3.0, the
best strategy is the following:
0. (Prerequisite:) Start with excellent test coverage.
1. Port to Python 2.6. This should be no more work than the average
port from Python 2.x to Python 2.(x+1). Make sure all your tests
pass.
2. (Still using 2.6:) Turn on the :option:`!-3` command line switch.
This enables warnings about features that will be removed (or
change) in 3.0. Run your test suite again, and fix code that you
get warnings about until there are no warnings left, and all your
tests still pass.
3. Run the ``2to3`` source-to-source translator over your source code
tree. (See :ref:`2to3-reference` for more on this tool.) Run the
result of the translation under Python 3.0. Manually fix up any
remaining issues, fixing problems until all tests pass again.
It is not recommended to try to write source code that runs unchanged
under both Python 2.6 and 3.0; you'd have to use a very contorted
coding style, e.g. avoiding ``print`` statements, metaclasses,
and much more. If you are maintaining a library that needs to support
both Python 2.6 and Python 3.0, the best approach is to modify step 3
above by editing the 2.6 version of the source code and running the
``2to3`` translator again, rather than editing the 3.0 version of the
source code.
For porting C extensions to Python 3.0, please see :ref:`cporting-howto`.
.. ======================================================================

552
third_party/python/Doc/whatsnew/3.1.rst vendored Normal file
View file

@ -0,0 +1,552 @@
****************************
What's New In Python 3.1
****************************
:Author: Raymond Hettinger
.. $Id$
Rules for maintenance:
* Anyone can add text to this document. Do not spend very much time
on the wording of your changes, because your text will probably
get rewritten to some degree.
* The maintainer will go through Misc/NEWS periodically and add
changes; it's therefore more important to add your changes to
Misc/NEWS than to this file.
* This is not a complete list of every single change; completeness
is the purpose of Misc/NEWS. Some changes I consider too small
or esoteric to include. If such a change is added to the text,
I'll just remove it. (This is another reason you shouldn't spend
too much time on writing your addition.)
* If you want to draw your new text to the attention of the
maintainer, add 'XXX' to the beginning of the paragraph or
section.
* It's OK to just add a fragmentary note about a change. For
example: "XXX Describe the transmogrify() function added to the
socket module." The maintainer will research the change and
write the necessary text.
* You can comment out your additions if you like, but it's not
necessary (especially when a final release is some months away).
* Credit the author of a patch or bugfix. Just the name is
sufficient; the e-mail address isn't necessary.
* It's helpful to add the bug/patch number as a comment:
% Patch 12345
XXX Describe the transmogrify() function added to the socket
module.
(Contributed by P.Y. Developer.)
This saves the maintainer the effort of going through the SVN log
when researching a change.
This article explains the new features in Python 3.1, compared to 3.0.
PEP 372: Ordered Dictionaries
=============================
Regular Python dictionaries iterate over key/value pairs in arbitrary order.
Over the years, a number of authors have written alternative implementations
that remember the order that the keys were originally inserted. Based on
the experiences from those implementations, a new
:class:`collections.OrderedDict` class has been introduced.
The OrderedDict API is substantially the same as regular dictionaries
but will iterate over keys and values in a guaranteed order depending on
when a key was first inserted. If a new entry overwrites an existing entry,
the original insertion position is left unchanged. Deleting an entry and
reinserting it will move it to the end.
The standard library now supports use of ordered dictionaries in several
modules. The :mod:`configparser` module uses them by default. This lets
configuration files be read, modified, and then written back in their original
order. The *_asdict()* method for :func:`collections.namedtuple` now
returns an ordered dictionary with the values appearing in the same order as
the underlying tuple indicies. The :mod:`json` module is being built-out with
an *object_pairs_hook* to allow OrderedDicts to be built by the decoder.
Support was also added for third-party tools like `PyYAML <http://pyyaml.org/>`_.
.. seealso::
:pep:`372` - Ordered Dictionaries
PEP written by Armin Ronacher and Raymond Hettinger. Implementation
written by Raymond Hettinger.
PEP 378: Format Specifier for Thousands Separator
=================================================
The built-in :func:`format` function and the :meth:`str.format` method use
a mini-language that now includes a simple, non-locale aware way to format
a number with a thousands separator. That provides a way to humanize a
program's output, improving its professional appearance and readability::
>>> format(1234567, ',d')
'1,234,567'
>>> format(1234567.89, ',.2f')
'1,234,567.89'
>>> format(12345.6 + 8901234.12j, ',f')
'12,345.600000+8,901,234.120000j'
>>> format(Decimal('1234567.89'), ',f')
'1,234,567.89'
The supported types are :class:`int`, :class:`float`, :class:`complex`
and :class:`decimal.Decimal`.
Discussions are underway about how to specify alternative separators
like dots, spaces, apostrophes, or underscores. Locale-aware applications
should use the existing *n* format specifier which already has some support
for thousands separators.
.. seealso::
:pep:`378` - Format Specifier for Thousands Separator
PEP written by Raymond Hettinger and implemented by Eric Smith and
Mark Dickinson.
Other Language Changes
======================
Some smaller changes made to the core Python language are:
* Directories and zip archives containing a :file:`__main__.py`
file can now be executed directly by passing their name to the
interpreter. The directory/zipfile is automatically inserted as the
first entry in sys.path. (Suggestion and initial patch by Andy Chu;
revised patch by Phillip J. Eby and Nick Coghlan; :issue:`1739468`.)
* The :func:`int` type gained a ``bit_length`` method that returns the
number of bits necessary to represent its argument in binary::
>>> n = 37
>>> bin(37)
'0b100101'
>>> n.bit_length()
6
>>> n = 2**123-1
>>> n.bit_length()
123
>>> (n+1).bit_length()
124
(Contributed by Fredrik Johansson, Victor Stinner, Raymond Hettinger,
and Mark Dickinson; :issue:`3439`.)
* The fields in :func:`format` strings can now be automatically
numbered::
>>> 'Sir {} of {}'.format('Gallahad', 'Camelot')
'Sir Gallahad of Camelot'
Formerly, the string would have required numbered fields such as:
``'Sir {0} of {1}'``.
(Contributed by Eric Smith; :issue:`5237`.)
* The :func:`string.maketrans` function is deprecated and is replaced by new
static methods, :meth:`bytes.maketrans` and :meth:`bytearray.maketrans`.
This change solves the confusion around which types were supported by the
:mod:`string` module. Now, :class:`str`, :class:`bytes`, and
:class:`bytearray` each have their own **maketrans** and **translate**
methods with intermediate translation tables of the appropriate type.
(Contributed by Georg Brandl; :issue:`5675`.)
* The syntax of the :keyword:`with` statement now allows multiple context
managers in a single statement::
>>> with open('mylog.txt') as infile, open('a.out', 'w') as outfile:
... for line in infile:
... if '<critical>' in line:
... outfile.write(line)
With the new syntax, the :func:`contextlib.nested` function is no longer
needed and is now deprecated.
(Contributed by Georg Brandl and Mattias Brändström;
`appspot issue 53094 <https://codereview.appspot.com/53094>`_.)
* ``round(x, n)`` now returns an integer if *x* is an integer.
Previously it returned a float::
>>> round(1123, -2)
1100
(Contributed by Mark Dickinson; :issue:`4707`.)
* Python now uses David Gay's algorithm for finding the shortest floating
point representation that doesn't change its value. This should help
mitigate some of the confusion surrounding binary floating point
numbers.
The significance is easily seen with a number like ``1.1`` which does not
have an exact equivalent in binary floating point. Since there is no exact
equivalent, an expression like ``float('1.1')`` evaluates to the nearest
representable value which is ``0x1.199999999999ap+0`` in hex or
``1.100000000000000088817841970012523233890533447265625`` in decimal. That
nearest value was and still is used in subsequent floating point
calculations.
What is new is how the number gets displayed. Formerly, Python used a
simple approach. The value of ``repr(1.1)`` was computed as ``format(1.1,
'.17g')`` which evaluated to ``'1.1000000000000001'``. The advantage of
using 17 digits was that it relied on IEEE-754 guarantees to assure that
``eval(repr(1.1))`` would round-trip exactly to its original value. The
disadvantage is that many people found the output to be confusing (mistaking
intrinsic limitations of binary floating point representation as being a
problem with Python itself).
The new algorithm for ``repr(1.1)`` is smarter and returns ``'1.1'``.
Effectively, it searches all equivalent string representations (ones that
get stored with the same underlying float value) and returns the shortest
representation.
The new algorithm tends to emit cleaner representations when possible, but
it does not change the underlying values. So, it is still the case that
``1.1 + 2.2 != 3.3`` even though the representations may suggest otherwise.
The new algorithm depends on certain features in the underlying floating
point implementation. If the required features are not found, the old
algorithm will continue to be used. Also, the text pickle protocols
assure cross-platform portability by using the old algorithm.
(Contributed by Eric Smith and Mark Dickinson; :issue:`1580`)
New, Improved, and Deprecated Modules
=====================================
* Added a :class:`collections.Counter` class to support convenient
counting of unique items in a sequence or iterable::
>>> Counter(['red', 'blue', 'red', 'green', 'blue', 'blue'])
Counter({'blue': 3, 'red': 2, 'green': 1})
(Contributed by Raymond Hettinger; :issue:`1696199`.)
* Added a new module, :mod:`tkinter.ttk` for access to the Tk themed widget set.
The basic idea of ttk is to separate, to the extent possible, the code
implementing a widget's behavior from the code implementing its appearance.
(Contributed by Guilherme Polo; :issue:`2983`.)
* The :class:`gzip.GzipFile` and :class:`bz2.BZ2File` classes now support
the context management protocol::
>>> # Automatically close file after writing
>>> with gzip.GzipFile(filename, "wb") as f:
... f.write(b"xxx")
(Contributed by Antoine Pitrou.)
* The :mod:`decimal` module now supports methods for creating a
decimal object from a binary :class:`float`. The conversion is
exact but can sometimes be surprising::
>>> Decimal.from_float(1.1)
Decimal('1.100000000000000088817841970012523233890533447265625')
The long decimal result shows the actual binary fraction being
stored for *1.1*. The fraction has many digits because *1.1* cannot
be exactly represented in binary.
(Contributed by Raymond Hettinger and Mark Dickinson.)
* The :mod:`itertools` module grew two new functions. The
:func:`itertools.combinations_with_replacement` function is one of
four for generating combinatorics including permutations and Cartesian
products. The :func:`itertools.compress` function mimics its namesake
from APL. Also, the existing :func:`itertools.count` function now has
an optional *step* argument and can accept any type of counting
sequence including :class:`fractions.Fraction` and
:class:`decimal.Decimal`::
>>> [p+q for p,q in combinations_with_replacement('LOVE', 2)]
['LL', 'LO', 'LV', 'LE', 'OO', 'OV', 'OE', 'VV', 'VE', 'EE']
>>> list(compress(data=range(10), selectors=[0,0,1,1,0,1,0,1,0,0]))
[2, 3, 5, 7]
>>> c = count(start=Fraction(1,2), step=Fraction(1,6))
>>> [next(c), next(c), next(c), next(c)]
[Fraction(1, 2), Fraction(2, 3), Fraction(5, 6), Fraction(1, 1)]
(Contributed by Raymond Hettinger.)
* :func:`collections.namedtuple` now supports a keyword argument
*rename* which lets invalid fieldnames be automatically converted to
positional names in the form _0, _1, etc. This is useful when
the field names are being created by an external source such as a
CSV header, SQL field list, or user input::
>>> query = input()
SELECT region, dept, count(*) FROM main GROUPBY region, dept
>>> cursor.execute(query)
>>> query_fields = [desc[0] for desc in cursor.description]
>>> UserQuery = namedtuple('UserQuery', query_fields, rename=True)
>>> pprint.pprint([UserQuery(*row) for row in cursor])
[UserQuery(region='South', dept='Shipping', _2=185),
UserQuery(region='North', dept='Accounting', _2=37),
UserQuery(region='West', dept='Sales', _2=419)]
(Contributed by Raymond Hettinger; :issue:`1818`.)
* The :func:`re.sub`, :func:`re.subn` and :func:`re.split` functions now
accept a flags parameter.
(Contributed by Gregory Smith.)
* The :mod:`logging` module now implements a simple :class:`logging.NullHandler`
class for applications that are not using logging but are calling
library code that does. Setting-up a null handler will suppress
spurious warnings such as "No handlers could be found for logger foo"::
>>> h = logging.NullHandler()
>>> logging.getLogger("foo").addHandler(h)
(Contributed by Vinay Sajip; :issue:`4384`).
* The :mod:`runpy` module which supports the ``-m`` command line switch
now supports the execution of packages by looking for and executing
a ``__main__`` submodule when a package name is supplied.
(Contributed by Andi Vajda; :issue:`4195`.)
* The :mod:`pdb` module can now access and display source code loaded via
:mod:`zipimport` (or any other conformant :pep:`302` loader).
(Contributed by Alexander Belopolsky; :issue:`4201`.)
* :class:`functools.partial` objects can now be pickled.
(Suggested by Antoine Pitrou and Jesse Noller. Implemented by
Jack Diederich; :issue:`5228`.)
* Add :mod:`pydoc` help topics for symbols so that ``help('@')``
works as expected in the interactive environment.
(Contributed by David Laban; :issue:`4739`.)
* The :mod:`unittest` module now supports skipping individual tests or classes
of tests. And it supports marking a test as an expected failure, a test that
is known to be broken, but shouldn't be counted as a failure on a
TestResult::
class TestGizmo(unittest.TestCase):
@unittest.skipUnless(sys.platform.startswith("win"), "requires Windows")
def test_gizmo_on_windows(self):
...
@unittest.expectedFailure
def test_gimzo_without_required_library(self):
...
Also, tests for exceptions have been builtout to work with context managers
using the :keyword:`with` statement::
def test_division_by_zero(self):
with self.assertRaises(ZeroDivisionError):
x / 0
In addition, several new assertion methods were added including
:func:`assertSetEqual`, :func:`assertDictEqual`,
:func:`assertDictContainsSubset`, :func:`assertListEqual`,
:func:`assertTupleEqual`, :func:`assertSequenceEqual`,
:func:`assertRaisesRegexp`, :func:`assertIsNone`,
and :func:`assertIsNotNone`.
(Contributed by Benjamin Peterson and Antoine Pitrou.)
* The :mod:`io` module has three new constants for the :meth:`seek`
method :data:`SEEK_SET`, :data:`SEEK_CUR`, and :data:`SEEK_END`.
* The :attr:`sys.version_info` tuple is now a named tuple::
>>> sys.version_info
sys.version_info(major=3, minor=1, micro=0, releaselevel='alpha', serial=2)
(Contributed by Ross Light; :issue:`4285`.)
* The :mod:`nntplib` and :mod:`imaplib` modules now support IPv6.
(Contributed by Derek Morr; :issue:`1655` and :issue:`1664`.)
* The :mod:`pickle` module has been adapted for better interoperability with
Python 2.x when used with protocol 2 or lower. The reorganization of the
standard library changed the formal reference for many objects. For
example, ``__builtin__.set`` in Python 2 is called ``builtins.set`` in Python
3. This change confounded efforts to share data between different versions of
Python. But now when protocol 2 or lower is selected, the pickler will
automatically use the old Python 2 names for both loading and dumping. This
remapping is turned-on by default but can be disabled with the *fix_imports*
option::
>>> s = {1, 2, 3}
>>> pickle.dumps(s, protocol=0)
b'c__builtin__\nset\np0\n((lp1\nL1L\naL2L\naL3L\natp2\nRp3\n.'
>>> pickle.dumps(s, protocol=0, fix_imports=False)
b'cbuiltins\nset\np0\n((lp1\nL1L\naL2L\naL3L\natp2\nRp3\n.'
An unfortunate but unavoidable side-effect of this change is that protocol 2
pickles produced by Python 3.1 won't be readable with Python 3.0. The latest
pickle protocol, protocol 3, should be used when migrating data between
Python 3.x implementations, as it doesn't attempt to remain compatible with
Python 2.x.
(Contributed by Alexandre Vassalotti and Antoine Pitrou, :issue:`6137`.)
* A new module, :mod:`importlib` was added. It provides a complete, portable,
pure Python reference implementation of the :keyword:`import` statement and its
counterpart, the :func:`__import__` function. It represents a substantial
step forward in documenting and defining the actions that take place during
imports.
(Contributed by Brett Cannon.)
Optimizations
=============
Major performance enhancements have been added:
* The new I/O library (as defined in :pep:`3116`) was mostly written in
Python and quickly proved to be a problematic bottleneck in Python 3.0.
In Python 3.1, the I/O library has been entirely rewritten in C and is
2 to 20 times faster depending on the task at hand. The pure Python
version is still available for experimentation purposes through
the ``_pyio`` module.
(Contributed by Amaury Forgeot d'Arc and Antoine Pitrou.)
* Added a heuristic so that tuples and dicts containing only untrackable objects
are not tracked by the garbage collector. This can reduce the size of
collections and therefore the garbage collection overhead on long-running
programs, depending on their particular use of datatypes.
(Contributed by Antoine Pitrou, :issue:`4688`.)
* Enabling a configure option named ``--with-computed-gotos``
on compilers that support it (notably: gcc, SunPro, icc), the bytecode
evaluation loop is compiled with a new dispatch mechanism which gives
speedups of up to 20%, depending on the system, the compiler, and
the benchmark.
(Contributed by Antoine Pitrou along with a number of other participants,
:issue:`4753`).
* The decoding of UTF-8, UTF-16 and LATIN-1 is now two to four times
faster.
(Contributed by Antoine Pitrou and Amaury Forgeot d'Arc, :issue:`4868`.)
* The :mod:`json` module now has a C extension to substantially improve
its performance. In addition, the API was modified so that json works
only with :class:`str`, not with :class:`bytes`. That change makes the
module closely match the `JSON specification <http://json.org/>`_
which is defined in terms of Unicode.
(Contributed by Bob Ippolito and converted to Py3.1 by Antoine Pitrou
and Benjamin Peterson; :issue:`4136`.)
* Unpickling now interns the attribute names of pickled objects. This saves
memory and allows pickles to be smaller.
(Contributed by Jake McGuire and Antoine Pitrou; :issue:`5084`.)
IDLE
====
* IDLE's format menu now provides an option to strip trailing whitespace
from a source file.
(Contributed by Roger D. Serwy; :issue:`5150`.)
Build and C API Changes
=======================
Changes to Python's build process and to the C API include:
* Integers are now stored internally either in base 2**15 or in base
2**30, the base being determined at build time. Previously, they
were always stored in base 2**15. Using base 2**30 gives
significant performance improvements on 64-bit machines, but
benchmark results on 32-bit machines have been mixed. Therefore,
the default is to use base 2**30 on 64-bit machines and base 2**15
on 32-bit machines; on Unix, there's a new configure option
``--enable-big-digits`` that can be used to override this default.
Apart from the performance improvements this change should be invisible to
end users, with one exception: for testing and debugging purposes there's a
new :attr:`sys.int_info` that provides information about the
internal format, giving the number of bits per digit and the size in bytes
of the C type used to store each digit::
>>> import sys
>>> sys.int_info
sys.int_info(bits_per_digit=30, sizeof_digit=4)
(Contributed by Mark Dickinson; :issue:`4258`.)
* The :c:func:`PyLong_AsUnsignedLongLong()` function now handles a negative
*pylong* by raising :exc:`OverflowError` instead of :exc:`TypeError`.
(Contributed by Mark Dickinson and Lisandro Dalcrin; :issue:`5175`.)
* Deprecated :c:func:`PyNumber_Int`. Use :c:func:`PyNumber_Long` instead.
(Contributed by Mark Dickinson; :issue:`4910`.)
* Added a new :c:func:`PyOS_string_to_double` function to replace the
deprecated functions :c:func:`PyOS_ascii_strtod` and :c:func:`PyOS_ascii_atof`.
(Contributed by Mark Dickinson; :issue:`5914`.)
* Added :c:type:`PyCapsule` as a replacement for the :c:type:`PyCObject` API.
The principal difference is that the new type has a well defined interface
for passing typing safety information and a less complicated signature
for calling a destructor. The old type had a problematic API and is now
deprecated.
(Contributed by Larry Hastings; :issue:`5630`.)
Porting to Python 3.1
=====================
This section lists previously described changes and other bugfixes
that may require changes to your code:
* The new floating point string representations can break existing doctests.
For example::
def e():
'''Compute the base of natural logarithms.
>>> e()
2.7182818284590451
'''
return sum(1/math.factorial(x) for x in reversed(range(30)))
doctest.testmod()
**********************************************************************
Failed example:
e()
Expected:
2.7182818284590451
Got:
2.718281828459045
**********************************************************************
* The automatic name remapping in the pickle module for protocol 2 or lower can
make Python 3.1 pickles unreadable in Python 3.0. One solution is to use
protocol 3. Another solution is to set the *fix_imports* option to ``False``.
See the discussion above for more details.

2734
third_party/python/Doc/whatsnew/3.2.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

2517
third_party/python/Doc/whatsnew/3.3.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

2545
third_party/python/Doc/whatsnew/3.4.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

2574
third_party/python/Doc/whatsnew/3.5.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

2490
third_party/python/Doc/whatsnew/3.6.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

7
third_party/python/Doc/whatsnew/changelog.rst vendored Normal file
View file

@ -0,0 +1,7 @@
.. _changelog:
+++++++++
Changelog
+++++++++
.. miscnews:: ../build/NEWS

38
third_party/python/Doc/whatsnew/index.rst vendored Normal file
View file

@ -0,0 +1,38 @@
.. _whatsnew-index:
######################
What's New in Python
######################
The "What's New in Python" series of essays takes tours through the most
important changes between major Python versions. They are a "must read" for
anyone wishing to stay up-to-date after a new release.
.. toctree::
:maxdepth: 2
3.6.rst
3.5.rst
3.4.rst
3.3.rst
3.2.rst
3.1.rst
3.0.rst
2.7.rst
2.6.rst
2.5.rst
2.4.rst
2.3.rst
2.2.rst
2.1.rst
2.0.rst
The "Changelog" is an HTML version of the `file built
<https://pypi.org/project/blurb>`_ from the contents of the
:source:`Misc/NEWS.d` directory tree, which contains *all* nontrivial changes
to Python for the current version.
.. toctree::
:maxdepth: 2
changelog.rst