diff options
Diffstat (limited to 'Doc/whatsnew/3.2.rst')
| -rw-r--r-- | Doc/whatsnew/3.2.rst | 350 |
1 files changed, 175 insertions, 175 deletions
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst index 21b2b75..a9d054b 100644 --- a/Doc/whatsnew/3.2.rst +++ b/Doc/whatsnew/3.2.rst @@ -36,14 +36,12 @@ 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. + sufficient; the e-mail address isn't necessary. It's helpful to + add the issue number: - * 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.) + (Contributed by P.Y. Developer; :issue:`12345`.) This saves the maintainer the effort of going through the SVN log when researching a change. @@ -54,46 +52,46 @@ This article explains the new features in Python 3.2, compared to 3.1. PEP 391: Dictionary Based Configuration for Logging =================================================== -The :mod:`logging` module had two ways of configuring the module, either -calling functions for each option or by reading an external file saved -in a ConfigParser format. Those options did not provide the flexibility -to create configurations from JSON or YAML files and they did not support -incremental configuration which is needed for specifying logger options -from a command line. +The :mod:`logging` module had two ways of configuring the module, either calling +functions for each option or by reading an external file saved in a ConfigParser +format. Those options did not provide the flexibility to create configurations +from JSON or YAML files and they did not support incremental configuration which +is needed for specifying logger options from a command line. To support a more flexible style, the module now offers :func:`logging.config.dictConfig` to use dictionaries to specify logger -configurations (including formatters, handlers, filters, and loggers). -For example:: +configurations (including formatters, handlers, filters, and loggers). For +example: - >>> import logging.config - >>> logging.config.dictConfig(json.load(open('log.cfg', 'rb'))) +>>> import logging.config +>>> logging.config.dictConfig(json.load(open('log.cfg', 'rb'))) The above fragment configures logging from a JSON encoded dictionary stored in file called "log.cfg". Here's a working example of a configuration dictionary:: - {"version": 1, - "formatters": {"brief": {"format": "%(levelname)-8s: %(name)-15s: %(message)s"}, - "full": {"format": "%(asctime)s %(name)-15s %(levelname)-8s %(message)s"}, - }, - "handlers": {"console": { - "class": "logging.StreamHandler", - "formatter": "brief", - "level": "INFO", - "stream": "ext://sys.stdout"}, - "console_priority": { - "class": "logging.StreamHandler", - "formatter": "full", - "level": "ERROR", - "stream": "ext://sys.stderr"}, - }, - "root": {"level": "DEBUG", "handlers": ["console", "console_priority"]}} + {"version": 1, + "formatters": {"brief": {"format": "%(levelname)-8s: %(name)-15s: %(message)s"}, + "full": {"format": "%(asctime)s %(name)-15s %(levelname)-8s %(message)s"}, + }, + "handlers": {"console": { + "class": "logging.StreamHandler", + "formatter": "brief", + "level": "INFO", + "stream": "ext://sys.stdout"}, + "console_priority": { + "class": "logging.StreamHandler", + "formatter": "full", + "level": "ERROR", + "stream": "ext://sys.stderr"}, + }, + "root": {"level": "DEBUG", "handlers": ["console", "console_priority"]}} .. seealso:: :pep:`391` - Dictionary Based Configuration for Logging PEP written by Vinay Sajip. + PEP 3147: PYC Repository Directories ===================================== @@ -117,28 +115,28 @@ cluttering source directories, the *pyc* files are now collected in a Aside from the filenames and target directories, the new scheme has a few aspects that are visible to the programmer: -* Imported modules now have a :attr:`__cached__` attribute which stores the - name of the actual file that was imported:: +* Imported modules now have a :attr:`__cached__` attribute which stores the name + of the actual file that was imported: - >>> import collections - >>> collections.__cached__ - 'c:/py32/lib/__pycache__/collections.cpython-32.pyc' + >>> import collections + >>> collections.__cached__ + 'c:/py32/lib/__pycache__/collections.cpython-32.pyc' * The tag that is unique to each interpreter is accessible from the :mod:`imp` - module:: + module: - >>> import imp - >>> imp.get_tag() - 'cpython-32' + >>> import imp + >>> imp.get_tag() + 'cpython-32' * Scripts that try to deduce source filename from the imported file now need to be smarter. It is no longer sufficient to simply strip the "c" from a ".pyc" filename. Instead, use the new functions in the :mod:`imp` module: - >>> imp.source_from_cache('c:/py32/lib/__pycache__/collections.cpython-32.pyc') - 'c:/py32/lib/collections.py' - >>> imp.cache_from_source('c:/py32/lib/collections.py') - 'c:/py32/lib/__pycache__/collections.cpython-32.pyc' + >>> imp.source_from_cache('c:/py32/lib/__pycache__/collections.cpython-32.pyc') + 'c:/py32/lib/collections.py' + >>> imp.cache_from_source('c:/py32/lib/collections.py') + 'c:/py32/lib/__pycache__/collections.cpython-32.pyc' * The :mod:`py_compile` and :mod:`compileall` modules have been updated to reflect the new naming convention and target directory. @@ -148,6 +146,7 @@ aspects that are visible to the programmer: :pep:`3147` - PYC Repository Directories PEP written by Barry Warsaw. + PEP 3149 ABI Version Tagged .so Files ===================================== @@ -184,27 +183,27 @@ Other Language Changes Some smaller changes made to the core Python language are: -* The :func:`hasattr` function used to catch and suppress any Exception. - Now, it only catches :exc:`AttributeError`. Under the hood, :func:`hasattr` - works by calling :func:`getattr` and throwing away the results. This is - necessary because dynamic attribute creation is possible using - :meth:`__getattribute__` or :meth:`__getattr`. If :func:`hasattr` were to - just scan instance and class dictionaries it would miss the dynmaic methods - and make it difficult to implement proxy objects. +* The :func:`hasattr` function used to catch and suppress any Exception. Now, + it only catches :exc:`AttributeError`. Under the hood, :func:`hasattr` works + by calling :func:`getattr` and throwing away the results. This is necessary + because dynamic attribute creation is possible using :meth:`__getattribute__` + or :meth:`__getattr`. If :func:`hasattr` were to just scan instance and class + dictionaries it would miss the dynmaic methods and make it difficult to + implement proxy objects. (Discovered by Yury Selivanov and fixed by Benjamin Peterson; :issue:`9666`.) * The :func:`str` of a float or complex number is now the same as it :func:`repr`. Previously, the :func:`str` form was shorter but that just caused confusion and is no longer needed now that we the shortest possible - :func:`repr` is displayed by default:: + :func:`repr` is displayed by default: - >>> repr(math.pi) - '3.141592653589793' - >>> str(math.pi) - '3.141592653589793' + >>> repr(math.pi) + '3.141592653589793' + >>> str(math.pi) + '3.141592653589793' - (Proposed and implemented by Mark Dickinson; :issue:`9337`). + (Proposed and implemented by Mark Dickinson; :issue:`9337`.) * The :func:`functools.wraps` decorator now adds a :attr:`__wrapped__` attribute pointing to the original callable function. This allows wrapped functions to @@ -218,68 +217,70 @@ Some smaller changes made to the core Python language are: * The :mod:`abc` module now supports :func:`abstractclassmethod` and :func:`abstractstaticmethod`. - (:issue:`5867`) + (:issue:`5867`.) + New, Improved, and Deprecated Modules ===================================== -* The :mod:`functools` module now includes a new decorator for caching - function calls. :func:`functools.lru_cache` can save repeated queries to an - external resource whenever the results are expected to be the same. +* The :mod:`functools` module now includes a new decorator for caching function + calls. :func:`functools.lru_cache` can save repeated queries to an external + resource whenever the results are expected to be the same. For example, adding a caching decorator to a database query function can save database accesses for popular searches:: - @functools.lru_cache(maxsize=300) - def get_phone_number(name): - c = conn.cursor() - c.execute('SELECT phonenumber FROM phonelist WHERE name=?', (name,)) - return c.fetchone()[0] + @functools.lru_cache(maxsize=300) + def get_phone_number(name): + c = conn.cursor() + c.execute('SELECT phonenumber FROM phonelist WHERE name=?', (name,)) + return c.fetchone()[0] To help with choosing an effective cache size, the wrapped function is - instrumented with two attributes *cache_hits* and *cache_misses*:: + instrumented with two attributes *cache_hits* and *cache_misses*: - >>> for name in user_requests: - ... get_phone_number(name) - >>> print(get_phone_number.cache_hits, get_phone_number.cache_misses) - 4805 980 + >>> for name in user_requests: + ... get_phone_number(name) + >>> print(get_phone_number.cache_hits, get_phone_number.cache_misses) + 4805 980 If the phonelist table gets updated, the outdated contents of the cache can be - cleared with:: + cleared with: - >>> get_phone_number.cache_clear() + >>> get_phone_number.cache_clear() - (Contributed by Raymond Hettinger) + (Contributed by Raymond Hettinger.) -* The previously deprecated :func:`contextlib.nested` function has been - removed in favor of a plain :keyword:`with` statement which can - accept multiple context managers. The latter technique is faster - (because it is built-in), and it does a better job finalizing multiple - context managers when one of them raises an exception. +* The previously deprecated :func:`contextlib.nested` function has been removed + in favor of a plain :keyword:`with` statement which can accept multiple + context managers. The latter technique is faster (because it is built-in), + and it does a better job finalizing multiple context managers when one of them + raises an exception. (Contributed by Georg Brandl and Mattias Brändström; `appspot issue 53094 <http://codereview.appspot.com/53094>`_.) -* The :class:`ftplib.FTP` class now supports the context manager protocol - to unconditionally consume :exc:`socket.error` exceptions and to close - the ftp connection when done:: - - >>> from ftplib import FTP - >>> with FTP("ftp1.at.proftpd.org") as ftp: - ... ftp.login() - ... ftp.dir() - ... - '230 Anonymous login ok, restrictions apply.' - dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 . - dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 .. - dr-xr-xr-x 5 ftp ftp 4096 May 6 10:43 CentOS - dr-xr-xr-x 3 ftp ftp 18 Jul 10 2008 Fedora +* The :class:`ftplib.FTP` class now supports the context manager protocol to + unconditionally consume :exc:`socket.error` exceptions and to close the ftp + connection when done: + + >>> from ftplib import FTP + >>> with FTP("ftp1.at.proftpd.org") as ftp: + ... ftp.login() + ... ftp.dir() + ... + '230 Anonymous login ok, restrictions apply.' + dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 . + dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 .. + dr-xr-xr-x 5 ftp ftp 4096 May 6 10:43 CentOS + dr-xr-xr-x 3 ftp ftp 18 Jul 10 2008 Fedora (Contributed by Tarek Ziadé and Giampaolo Rodolà; :issue:`4972`.) -* A warning message will now get printed at interpreter shutdown if - the :data:`gc.garbage` list isn't empty. This is meant to make the - programmer aware that his code contains object finalization issues. +* A warning message will now get printed at interpreter shutdown if the + :data:`gc.garbage` list isn't empty. This is meant to make the programmer + aware that his code contains object finalization issues. + (Added by Antoine Pitrou; :issue:`477863`.) * The :mod:`os` module now has the :const:`ST_RDONLY` and :const:`ST_NOSUID` @@ -289,72 +290,66 @@ New, Improved, and Deprecated Modules * The :func:`shutil.copytree` function has two new options: - * *ignore_dangling_symlinks*: when ``symlinks=False`` dp that the - function copies the file pointed to by the symlink, not the symlink - itself. This option will silence the error raised if the file doesn't - exist. + * *ignore_dangling_symlinks*: when ``symlinks=False`` dp that the function + copies the file pointed to by the symlink, not the symlink itself. This + option will silence the error raised if the file doesn't exist. * *copy_function*: is a callable that will be used to copy files. :func:`shutil.copy2` is used by default. (Contributed by Tarek Ziadé.) -* Socket objects now have a :meth:`~socket.socket.detach()` method which - puts the socket into closed state without actually closing the underlying - file descriptor. The latter can then be reused for other purposes. +* Socket objects now have a :meth:`~socket.socket.detach()` method which puts + the socket into closed state without actually closing the underlying file + descriptor. The latter can then be reused for other purposes. (Added by Antoine Pitrou; :issue:`8524`.) * The :mod:`sqlite3` module has two new capabilities. - The :attr:`Connection.in_transit` attribute is true if there is an - active transaction for uncommitted changes. + The :attr:`Connection.in_transit` attribute is true if there is an active + transaction for uncommitted changes. The :meth:`Connection.enable_load_extension` and :meth:`Connection.load_extension` methods allows you to load SQLite extensions from ".so" files. One well-known extension is the fulltext-search extension distributed with SQLite. - (Contributed by R. David Murray and Shashwat Anand, :issue:`8845`.) + (Contributed by R. David Murray and Shashwat Anand; :issue:`8845`.) -* The :mod:`ssl` module has a new class, :class:`~ssl.SSLContext` which - serves as a container for various persistent SSL data, such as protocol - settings, certificates, private keys, and various other options. - The :meth:`~ssl.SSLContext.wrap_socket` method allows to create an - SSL socket from such an SSL context. - (Added by Antoine Pitrou; :issue:`8550`.) +* The :mod:`ssl` module has a new class, :class:`~ssl.SSLContext` which serves + as a container for various persistent SSL data, such as protocol settings, + certificates, private keys, and various other options. The + :meth:`~ssl.SSLContext.wrap_socket` method allows to create an SSL socket from + such an SSL context. (Added by Antoine Pitrou; :issue:`8550`.) - The :func:`ssl.wrap_socket` constructor function now takes a - *ciphers* argument that's a string listing the encryption algorithms - to be allowed; the format of the string is described - `in the OpenSSL documentation - <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>`__. - (Added by Antoine Pitrou; :issue:`8322`.) + The :func:`ssl.wrap_socket` constructor function now takes a *ciphers* + argument that's a string listing the encryption algorithms to be allowed; the + format of the string is described `in the OpenSSL documentation + <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>`__. (Added + by Antoine Pitrou; :issue:`8322`.) Various options have been added to the :mod:`ssl` module, such as - :data:`~ssl.OP_NO_SSLv2` which allows to force disabling of the insecure - and obsolete SSLv2 protocol. - (Added by Antoine Pitrou; :issue:`4870`.) - - Another change makes the extension load all of OpenSSL's ciphers and - digest algorithms so that they're all available. Some SSL - certificates couldn't be verified, reporting an "unknown algorithm" - error. (Reported by Beda Kosata, and fixed by Antoine Pitrou; - :issue:`8484`.) - - The version of OpenSSL being used is now available as the module - attributes :data:`ssl.OPENSSL_VERSION` (a string), - :data:`ssl.OPENSSL_VERSION_INFO` (a 5-tuple), and - :data:`ssl.OPENSSL_VERSION_NUMBER` (an integer). (Added by Antoine - Pitrou; :issue:`8321`.) - -* The previously deprecated :func:`string.maketrans` function has been - removed in favor of the static methods, :meth:`bytes.maketrans` and + :data:`~ssl.OP_NO_SSLv2` which allows to force disabling of the insecure and + obsolete SSLv2 protocol. (Added by Antoine Pitrou; :issue:`4870`.) + + Another change makes the extension load all of OpenSSL's ciphers and digest + algorithms so that they're all available. Some SSL certificates couldn't be + verified, reporting an "unknown algorithm" error. (Reported by Beda Kosata, + and fixed by Antoine Pitrou; :issue:`8484`.) + + The version of OpenSSL being used is now available as the module attributes + :data:`ssl.OPENSSL_VERSION` (a string), :data:`ssl.OPENSSL_VERSION_INFO` (a + 5-tuple), and :data:`ssl.OPENSSL_VERSION_NUMBER` (an integer). (Added by + Antoine Pitrou; :issue:`8321`.) + +* The previously deprecated :func:`string.maketrans` function has been removed + in favor of the 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`, + 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. + **translate** methods with intermediate translation tables of the appropriate + type. (Contributed by Georg Brandl; :issue:`5675`.) @@ -365,44 +360,46 @@ New, Improved, and Deprecated Modules (Contributed by Giampaolo Rodolà; :issue:`8807`.) + Multi-threading =============== -* The mechanism for serializing execution of concurrently running Python - threads (generally known as the GIL or Global Interpreter Lock) has been - rewritten. Among the objectives were more predictable switching intervals - and reduced overhead due to lock contention and the number of ensuing - system calls. The notion of a "check interval" to allow thread switches - has been abandoned and replaced by an absolute duration expressed in - seconds. This parameter is tunable through :func:`sys.setswitchinterval()`. - It currently defaults to 5 milliseconds. +* The mechanism for serializing execution of concurrently running Python threads + (generally known as the GIL or Global Interpreter Lock) has been rewritten. + Among the objectives were more predictable switching intervals and reduced + overhead due to lock contention and the number of ensuing system calls. The + notion of a "check interval" to allow thread switches has been abandoned and + replaced by an absolute duration expressed in seconds. This parameter is + tunable through :func:`sys.setswitchinterval()`. It currently defaults to 5 + milliseconds. Additional details about the implementation can be read from a `python-dev mailing-list message <http://mail.python.org/pipermail/python-dev/2009-October/093321.html>`_ - (however, "priority requests" as exposed in this message have not been - kept for inclusion). + (however, "priority requests" as exposed in this message have not been kept + for inclusion). (Contributed by Antoine Pitrou.) * Recursive locks (created with the :func:`threading.RLock` API) now benefit - from a C implementation which makes them as fast as regular locks, and - between 10x and 15x faster than their previous pure Python implementation. + from a C implementation which makes them as fast as regular locks, and between + 10x and 15x faster than their previous pure Python implementation. (Contributed by Antoine Pitrou; :issue:`3001`.) -* Regular and recursive locks now accept an optional *timeout* argument - to their ``acquire`` method. (Contributed by Antoine Pitrou; :issue:`7316`) +* Regular and recursive locks now accept an optional *timeout* argument to their + ``acquire`` method. (Contributed by Antoine Pitrou; :issue:`7316`.) + Similarly, :meth:`threading.Semaphore.acquire` also gains a *timeout* - argument. (Contributed by Torsten Landschoff; :issue:`850728`.) + argument. (Contributed by Torsten Landschoff; :issue:`850728`.) -Optimizations -============= +.. Optimizations + ============= -Major performance enhancements have been added: + Major performance enhancements have been added: -* Stub + * Stub Filenames and unicode @@ -418,10 +415,10 @@ The :mod:`os` module has two new functions: :func:`os.fsencode` and :func:`os.fsdecode`. -IDLE -==== +.. IDLE + ==== -* Stub + * Stub Build and C API Changes @@ -429,27 +426,30 @@ Build and C API Changes Changes to Python's build process and to the C API include: -* The C functions that access the Unicode Database now accept and - return characters from the full Unicode range, even on narrow unicode builds +* The C functions that access the Unicode Database now accept and return + characters from the full Unicode range, even on narrow unicode builds (Py_UNICODE_TOLOWER, Py_UNICODE_ISDECIMAL, and others). A visible difference - in Python is that :cfunc:`unicodedata.numeric` now returns the correct value for - large code points, and :func:`repr` may consider more characters as printable. + in Python is that :func:`unicodedata.numeric` now returns the correct value + for large code points, and :func:`repr` may consider more characters as + printable. (Reported by Bupjoe Lee and fixed by Amaury Forgeot D'Arc; :issue:`5127`.) -* Computed gotos are now enabled by default on supported - compilers (which are detected by the configure script). They can still - be disable selectively by specifying ``--without-computed-gotos``. +* Computed gotos are now enabled by default on supported compilers (which are + detected by the configure script). They can still be disable selectively by + specifying ``--without-computed-gotos``. + + (Contributed by Antoine Pitrou; :issue:`9203`.) - (:issue:`9203`) Porting to Python 3.2 ===================== -This section lists previously described changes and other bugfixes -that may require changes to your code: +This section lists previously described changes and other bugfixes that may +require changes to your code: -* bytearray objects cannot be used anymore as filenames: convert them to bytes +* :class:`bytearray` objects cannot be used anymore as filenames: convert them + to :class:`bytes`. * PyArg_Parse*() functions: @@ -457,6 +457,6 @@ that may require changes to your code: * "w" and "w#" formats has been removed: use "w*" instead * The :ctype:`PyCObject` type, deprecated in 3.1, has been removed. To wrap - opaque C pointers in Python objects, the :ctype:`PyCapsule` API should be - used instead; the new type has a well defined interface for passing typing - safety information and a less complicated signature for calling a destructor. + opaque C pointers in Python objects, the :ctype:`PyCapsule` API should be used + instead; the new type has a well defined interface for passing typing safety + information and a less complicated signature for calling a destructor. |