1 ****************************
2 What's New in Python 2.6
3 ****************************
5 .. XXX add trademark info for Apple, Microsoft, SourceForge.
11 .. $Id: whatsnew26.tex 55746 2007-06-02 18:33:53Z neal.norwitz $
12 Rules for maintenance:
14 * Anyone can add text to this document. Do not spend very much time
15 on the wording of your changes, because your text will probably
16 get rewritten to some degree.
18 * The maintainer will go through Misc/NEWS periodically and add
19 changes; it's therefore more important to add your changes to
20 Misc/NEWS than to this file.
22 * This is not a complete list of every single change; completeness
23 is the purpose of Misc/NEWS. Some changes I consider too small
24 or esoteric to include. If such a change is added to the text,
25 I'll just remove it. (This is another reason you shouldn't spend
26 too much time on writing your addition.)
28 * If you want to draw your new text to the attention of the
29 maintainer, add 'XXX' to the beginning of the paragraph or
32 * It's OK to just add a fragmentary note about a change. For
33 example: "XXX Describe the transmogrify() function added to the
34 socket module." The maintainer will research the change and
35 write the necessary text.
37 * You can comment out your additions if you like, but it's not
38 necessary (especially when a final release is some months away).
40 * Credit the author of a patch or bugfix. Just the name is
41 sufficient; the e-mail address isn't necessary.
43 * It's helpful to add the bug/patch number in a parenthetical comment.
45 XXX Describe the transmogrify() function added to the socket
47 (Contributed by P.Y. Developer; :issue:`12345`.)
49 This saves the maintainer some effort going through the SVN logs
50 when researching a change.
52 This article explains the new features in Python 2.6. The release
53 schedule is described in :pep:`361`; currently the final release is
54 scheduled for October 1 2008.
56 This article doesn't attempt to provide a complete specification of
57 the new features, but instead provides a convenient overview. For
58 full details, you should refer to the documentation for Python 2.6. If
59 you want to understand the rationale for the design and
60 implementation, refer to the PEP for a particular new feature.
61 Whenever possible, "What's New in Python" links to the bug/patch item
64 .. Compare with previous release in 2 - 3 sentences here.
65 add hyperlink when the documentation becomes available online.
67 .. ========================================================================
68 .. Large, PEP-level features and changes should be described here.
69 .. Should there be a new section here for 3k migration?
70 .. Or perhaps a more general section describing module changes/deprecation?
71 .. ========================================================================
76 The development cycle for Python 2.6 also saw the release of the first
77 alphas of Python 3.0, and the development of 3.0 has influenced
78 a number of features in 2.6.
80 Python 3.0 is a far-ranging redesign of Python that breaks
81 compatibility with the 2.x series. This means that existing Python
82 code will need a certain amount of conversion in order to run on
83 Python 3.0. However, not all the changes in 3.0 necessarily break
84 compatibility. In cases where new features won't cause existing code
85 to break, they've been backported to 2.6 and are described in this
86 document in the appropriate place. Some of the 3.0-derived features
89 * A :meth:`__complex__` method for converting objects to a complex number.
90 * Alternate syntax for catching exceptions: ``except TypeError as exc``.
91 * The addition of :func:`functools.reduce` as a synonym for the built-in
92 :func:`reduce` function.
94 A new command-line switch, :option:`-3`, enables warnings
95 about features that will be removed in Python 3.0. You can run code
96 with this switch to see how much work will be necessary to port
97 code to 3.0. The value of this switch is available
98 to Python code as the boolean variable :data:`sys.py3kwarning`,
99 and to C extension code as :cdata:`Py_Py3kWarningFlag`.
101 Python 3.0 adds several new built-in functions and change the
102 semantics of some existing built-ins. Entirely new functions such as
103 :func:`bin` have simply been added to Python 2.6, but existing
104 built-ins haven't been changed; instead, the :mod:`future_builtins`
105 module has versions with the new 3.0 semantics. Code written to be
106 compatible with 3.0 can do ``from future_builtins import hex, map``
111 The 3xxx series of PEPs, which describes the development process for
112 Python 3.0 and various features that have been accepted, rejected,
113 or are still under consideration.
117 ==================================================
119 While 2.6 was being developed, the Python development process
120 underwent two significant changes: the developer group
121 switched from SourceForge's issue tracker to a customized
122 Roundup installation, and the documentation was converted from
123 LaTeX to reStructuredText.
126 New Issue Tracker: Roundup
127 --------------------------------------------------
129 For a long time, the Python developers have been growing increasingly
130 annoyed by SourceForge's bug tracker. SourceForge's hosted solution
131 doesn't permit much customization; for example, it wasn't possible to
132 customize the life cycle of issues.
134 The infrastructure committee of the Python Software Foundation
135 therefore posted a call for issue trackers, asking volunteers to set
136 up different products and import some of the bugs and patches from
137 SourceForge. Four different trackers were examined: Atlassian's `Jira
138 <http://www.atlassian.com/software/jira/>`__,
139 `Launchpad <http://www.launchpad.net>`__,
140 `Roundup <http://roundup.sourceforge.net/>`__, and
141 `Trac <http://trac.edgewall.org/>`__.
142 The committee eventually settled on Jira
143 and Roundup as the two candidates. Jira is a commercial product that
144 offers a no-cost hosted instance to free-software projects; Roundup
145 is an open-source project that requires volunteers
146 to administer it and a server to host it.
148 After posting a call for volunteers, a new Roundup installation was
149 set up at http://bugs.python.org. One installation of Roundup can
150 host multiple trackers, and this server now also hosts issue trackers
151 for Jython and for the Python web site. It will surely find
152 other uses in the future. Where possible,
153 this edition of "What's New in Python" links to the bug/patch
154 item for each change.
156 Hosting is kindly provided by
157 `Upfront Systems <http://www.upfrontsystems.co.za/>`__
158 of Stellenbosch, South Africa. Martin von Loewis put a
159 lot of effort into importing existing bugs and patches from
160 SourceForge; his scripts for this import operation are at
161 http://svn.python.org/view/tracker/importer/.
165 http://bugs.python.org
166 The Python bug tracker.
168 http://bugs.jython.org:
169 The Jython bug tracker.
171 http://roundup.sourceforge.net/
172 Roundup downloads and documentation.
175 New Documentation Format: reStructuredText Using Sphinx
176 -----------------------------------------------------------
178 Since the Python project's inception around 1989, the documentation
179 had been written using LaTeX. At that time, most documentation was
180 printed out for later study, not viewed online. LaTeX was widely used
181 because it provided attractive printed output while remaining
182 straightforward to write, once the basic rules of the markup have been
185 LaTeX is still used today for writing technical publications destined
186 for printing, but the landscape for programming tools has shifted. We
187 no longer print out reams of documentation; instead, we browse through
188 it online and HTML has become the most important format to support.
189 Unfortunately, converting LaTeX to HTML is fairly complicated, and
190 Fred L. Drake Jr., the Python documentation editor for many years,
191 spent a lot of time wrestling the conversion process into shape.
192 Occasionally people would suggest converting the documentation into
193 SGML or, later, XML, but performing a good conversion is a major task
194 and no one pursued the task to completion.
196 During the 2.6 development cycle, Georg Brandl put a substantial
197 effort into building a new toolchain for processing the documentation.
198 The resulting package is called Sphinx, and is available from
199 http://sphinx.pocoo.org/. The input format is reStructuredText, a
200 markup commonly used in the Python community that supports custom
201 extensions and directives. Sphinx concentrates on HTML output,
202 producing attractively styled and modern HTML, though printed output
203 is still supported through conversion to LaTeX. Sphinx is a
204 standalone package that can be used in documenting other projects.
208 :ref:`documenting-index`
209 Describes how to write for Python's documentation.
211 `Sphinx <http://sphinx.pocoo.org/>`__
212 Documentation and code for the Sphinx toolchain.
214 `Docutils <http://docutils.sf.net>`__
215 The underlying reStructuredText parser and toolset.
218 PEP 343: The 'with' statement
219 =============================
221 The previous version, Python 2.5, added the ':keyword:`with`'
222 statement an optional feature, to be enabled by a ``from __future__
223 import with_statement`` directive. In 2.6 the statement no longer needs to
224 be specially enabled; this means that :keyword:`with` is now always a
225 keyword. The rest of this section is a copy of the corresponding
226 section from "What's New in Python 2.5" document; if you read
227 it back when Python 2.5 came out, you can skip the rest of this
230 The ':keyword:`with`' statement clarifies code that previously would use
231 ``try...finally`` blocks to ensure that clean-up code is executed. In this
232 section, I'll discuss the statement as it will commonly be used. In the next
233 section, I'll examine the implementation details and show how to write objects
234 for use with this statement.
236 The ':keyword:`with`' statement is a new control-flow structure whose basic
239 with expression [as variable]:
242 The expression is evaluated, and it should result in an object that supports the
243 context management protocol (that is, has :meth:`__enter__` and :meth:`__exit__`
246 The object's :meth:`__enter__` is called before *with-block* is executed and
247 therefore can run set-up code. It also may return a value that is bound to the
248 name *variable*, if given. (Note carefully that *variable* is *not* assigned
249 the result of *expression*.)
251 After execution of the *with-block* is finished, the object's :meth:`__exit__`
252 method is called, even if the block raised an exception, and can therefore run
255 Some standard Python objects now support the context management protocol and can
256 be used with the ':keyword:`with`' statement. File objects are one example::
258 with open('/etc/passwd', 'r') as f:
261 ... more processing code ...
263 After this statement has executed, the file object in *f* will have been
264 automatically closed, even if the :keyword:`for` loop raised an exception part-
265 way through the block.
269 In this case, *f* is the same object created by :func:`open`, because
270 :meth:`file.__enter__` returns *self*.
272 The :mod:`threading` module's locks and condition variables also support the
273 ':keyword:`with`' statement::
275 lock = threading.Lock()
277 # Critical section of code
280 The lock is acquired before the block is executed and always released once the
283 The new :func:`localcontext` function in the :mod:`decimal` module makes it easy
284 to save and restore the current decimal context, which encapsulates the desired
285 precision and rounding characteristics for computations::
287 from decimal import Decimal, Context, localcontext
289 # Displays with default precision of 28 digits
293 with localcontext(Context(prec=16)):
294 # All code in this block uses a precision of 16 digits.
295 # The original context is restored on exiting the block.
299 .. _new-26-context-managers:
301 Writing Context Managers
302 ------------------------
304 Under the hood, the ':keyword:`with`' statement is fairly complicated. Most
305 people will only use ':keyword:`with`' in company with existing objects and
306 don't need to know these details, so you can skip the rest of this section if
307 you like. Authors of new objects will need to understand the details of the
308 underlying implementation and should keep reading.
310 A high-level explanation of the context management protocol is:
312 * The expression is evaluated and should result in an object called a "context
313 manager". The context manager must have :meth:`__enter__` and :meth:`__exit__`
316 * The context manager's :meth:`__enter__` method is called. The value returned
317 is assigned to *VAR*. If no ``as VAR`` clause is present, the value is simply
320 * The code in *BLOCK* is executed.
322 * If *BLOCK* raises an exception, the :meth:`__exit__(type, value, traceback)`
323 is called with the exception details, the same values returned by
324 :func:`sys.exc_info`. The method's return value controls whether the exception
325 is re-raised: any false value re-raises the exception, and ``True`` will result
326 in suppressing it. You'll only rarely want to suppress the exception, because
327 if you do the author of the code containing the ':keyword:`with`' statement will
328 never realize anything went wrong.
330 * If *BLOCK* didn't raise an exception, the :meth:`__exit__` method is still
331 called, but *type*, *value*, and *traceback* are all ``None``.
333 Let's think through an example. I won't present detailed code but will only
334 sketch the methods necessary for a database that supports transactions.
336 (For people unfamiliar with database terminology: a set of changes to the
337 database are grouped into a transaction. Transactions can be either committed,
338 meaning that all the changes are written into the database, or rolled back,
339 meaning that the changes are all discarded and the database is unchanged. See
340 any database textbook for more information.)
342 Let's assume there's an object representing a database connection. Our goal will
343 be to let the user write code like this::
345 db_connection = DatabaseConnection()
346 with db_connection as cursor:
347 cursor.execute('insert into ...')
348 cursor.execute('delete from ...')
349 # ... more operations ...
351 The transaction should be committed if the code in the block runs flawlessly or
352 rolled back if there's an exception. Here's the basic interface for
353 :class:`DatabaseConnection` that I'll assume::
355 class DatabaseConnection:
358 "Returns a cursor object and starts a new transaction"
360 "Commits current transaction"
362 "Rolls back current transaction"
364 The :meth:`__enter__` method is pretty easy, having only to start a new
365 transaction. For this application the resulting cursor object would be a useful
366 result, so the method will return it. The user can then add ``as cursor`` to
367 their ':keyword:`with`' statement to bind the cursor to a variable name. ::
369 class DatabaseConnection:
372 # Code to start a new transaction
373 cursor = self.cursor()
376 The :meth:`__exit__` method is the most complicated because it's where most of
377 the work has to be done. The method has to check if an exception occurred. If
378 there was no exception, the transaction is committed. The transaction is rolled
379 back if there was an exception.
381 In the code below, execution will just fall off the end of the function,
382 returning the default value of ``None``. ``None`` is false, so the exception
383 will be re-raised automatically. If you wished, you could be more explicit and
384 add a :keyword:`return` statement at the marked location. ::
386 class DatabaseConnection:
388 def __exit__(self, type, value, tb):
390 # No exception, so commit
393 # Exception occurred, so rollback.
398 .. _module-contextlib:
400 The contextlib module
401 ---------------------
403 The new :mod:`contextlib` module provides some functions and a decorator that
404 are useful for writing objects for use with the ':keyword:`with`' statement.
406 The decorator is called :func:`contextmanager`, and lets you write a single
407 generator function instead of defining a new class. The generator should yield
408 exactly one value. The code up to the :keyword:`yield` will be executed as the
409 :meth:`__enter__` method, and the value yielded will be the method's return
410 value that will get bound to the variable in the ':keyword:`with`' statement's
411 :keyword:`as` clause, if any. The code after the :keyword:`yield` will be
412 executed in the :meth:`__exit__` method. Any exception raised in the block will
413 be raised by the :keyword:`yield` statement.
415 Our database example from the previous section could be written using this
418 from contextlib import contextmanager
421 def db_transaction(connection):
422 cursor = connection.cursor()
426 connection.rollback()
431 db = DatabaseConnection()
432 with db_transaction(db) as cursor:
435 The :mod:`contextlib` module also has a :func:`nested(mgr1, mgr2, ...)` function
436 that combines a number of context managers so you don't need to write nested
437 ':keyword:`with`' statements. In this example, the single ':keyword:`with`'
438 statement both starts a database transaction and acquires a thread lock::
440 lock = threading.Lock()
441 with nested (db_transaction(db), lock) as (cursor, locked):
444 Finally, the :func:`closing(object)` function returns *object* so that it can be
445 bound to a variable, and calls ``object.close`` at the end of the block. ::
448 from contextlib import closing
450 with closing(urllib.urlopen('http://www.yahoo.com')) as f:
452 sys.stdout.write(line)
457 :pep:`343` - The "with" statement
458 PEP written by Guido van Rossum and Nick Coghlan; implemented by Mike Bland,
459 Guido van Rossum, and Neal Norwitz. The PEP shows the code generated for a
460 ':keyword:`with`' statement, which can be helpful in learning how the statement
463 The documentation for the :mod:`contextlib` module.
465 .. ======================================================================
469 PEP 366: Explicit Relative Imports From a Main Module
470 ============================================================
472 Python's :option:`-m` switch allows running a module as a script.
473 When you ran a module that was located inside a package, relative
474 imports didn't work correctly.
476 The fix in Python 2.6 adds a :attr:`__package__` attribute to modules.
477 When present, relative imports will be relative to the value of this
478 attribute instead of the :attr:`__name__` attribute. PEP 302-style
479 importers can then set :attr:`__package__`. The :mod:`runpy` module
480 that implements the :option:`-m` switch now does this, so relative imports
481 can now be used in scripts running from inside a package.
483 .. ======================================================================
487 PEP 370: Per-user ``site-packages`` Directory
488 =====================================================
490 When you run Python, the module search path ``sys.modules`` usually
491 includes a directory whose path ends in ``"site-packages"``. This
492 directory is intended to hold locally-installed packages available to
493 all users on a machine or using a particular site installation.
495 Python 2.6 introduces a convention for user-specific site directories.
496 The directory varies depending on the platform:
498 * Unix and MacOS: :file:`~/.local/`
499 * Windows: :file:`%APPDATA%/Python`
501 Within this directory, there will be version-specific subdirectories,
502 such as :file:`lib/python2.6/site-packages` on Unix/MacOS and
503 :file:`Python26/site-packages` on Windows.
505 If you don't like the default directory, it can be overridden by an
506 environment variable. :envvar:`PYTHONUSERBASE` sets the root
507 directory used for all Python versions supporting this feature. On
508 Windows, the directory for application-specific data can be changed by
509 setting the :envvar:`APPDATA` environment variable. You can also
510 modify the :file:`site.py` file for your Python installation.
512 The feature can be disabled entirely by running Python with the
513 :option:`-s` option or setting the :envvar:`PYTHONNOUSERSITE`
514 environment variable.
518 :pep:`370` - Per-user ``site-packages`` Directory
519 PEP written and implemented by Christian Heimes.
522 .. ======================================================================
526 PEP 371: The ``multiprocessing`` Package
527 =====================================================
529 The new :mod:`multiprocessing` package lets Python programs create new
530 processes that will perform a computation and return a result to the
531 parent. The parent and child processes can communicate using queues
532 and pipes, synchronize their operations using locks and semaphores,
533 and can share simple arrays of data.
535 The :mod:`multiprocessing` module started out as an exact emulation of
536 the :mod:`threading` module using processes instead of threads. That
537 goal was discarded along the path to Python 2.6, but the general
538 approach of the module is still similar. The fundamental class
539 is the :class:`Process`, which is passed a callable object and
540 a collection of arguments. The :meth:`start` method
541 sets the callable running in a subprocess, after which you can call
542 the :meth:`is_alive` method to check whether the subprocess is still running
543 and the :meth:`join` method to wait for the process to exit.
545 Here's a simple example where the subprocess will calculate a
546 factorial. The function doing the calculation is a bit strange; it's
547 written to take significantly longer when the input argument is a
553 from multiprocessing import Process, Queue
556 def factorial(queue, N):
557 "Compute a factorial."
558 # If N is a multiple of 4, this function will take much longer.
560 time.sleep(.05 * N/4)
562 # Calculate the result
564 for i in range(1, N+1):
567 # Put the result on the queue
570 if __name__ == '__main__':
575 p = Process(target=factorial, args=(queue, N))
580 print 'Factorial', N, '=', result
582 A :class:`Queue` object is created and stored as a global. The child
583 process will use the value of the variable when the child was created;
584 because it's a :class:`Queue`, parent and child can use the object to
585 communicate. (If the parent were to change the value of the global
586 variable, the child's value would be unaffected, and vice versa.)
588 Two other classes, :class:`Pool` and :class:`Manager`, provide
589 higher-level interfaces. :class:`Pool` will create a fixed number of
590 worker processes, and requests can then be distributed to the workers
591 by calling :meth:`apply` or `apply_async`, adding a single request,
592 and :meth:`map` or :meth:`map_async` to distribute a number of
593 requests. The following code uses a :class:`Pool` to spread requests
594 across 5 worker processes, receiving a list of results back.
598 from multiprocessing import Pool
601 result = p.map(factorial, range(1, 1000, 10))
605 This produces the following output::
610 8222838654177922817725562880000000
611 33452526613163807108170062053440751665152000000000
614 The :class:`Manager` class creates a separate server process that can
615 hold master copies of Python data structures. Other processes can
616 then access and modify these data structures by using proxy objects.
617 The following example creates a shared dictionary by calling the
618 :meth:`dict` method; the worker processes then insert values into the
619 dictionary. (No locking is done automatically, which doesn't matter
620 in this example. :class:`Manager`'s methods also include
621 :meth:`Lock`, :meth:`RLock`, and :meth:`Semaphore` to create shared locks.
626 from multiprocessing import Pool, Manager
628 def factorial(N, dictionary):
629 "Compute a factorial."
630 # Calculate the result
632 for i in range(1, N+1):
635 # Store result in dictionary
638 if __name__ == '__main__':
641 d = mgr.dict() # Create shared dictionary
643 # Run tasks using the pool
644 for N in range(1, 1000, 10):
645 p.apply_async(factorial, (N, d))
647 # Mark pool as closed -- no more tasks can be added.
650 # Wait for tasks to exit
654 for k, v in sorted(d.items()):
657 This will produce the output::
661 21 51090942171709440000
662 31 8222838654177922817725562880000000
663 41 33452526613163807108170062053440751665152000000000
664 51 1551118753287382280224243016469303211063259720016986112000000000000
668 The documentation for the :mod:`multiprocessing` module.
670 :pep:`371` - Addition of the multiprocessing package
671 PEP written by Jesse Noller and Richard Oudkerk;
672 implemented by Richard Oudkerk and Jesse Noller.
675 .. ======================================================================
679 PEP 3101: Advanced String Formatting
680 =====================================================
682 In Python 3.0, the `%` operator is supplemented by a more powerful string
683 formatting method, :meth:`format`. Support for the :meth:`str.format` method
684 has been backported to Python 2.6.
686 In 2.6, both 8-bit and Unicode strings have a `.format()` method that
687 treats the string as a template and takes the arguments to be formatted.
688 The formatting template uses curly brackets (`{`, `}`) as special characters::
690 # Substitute positional argument 0 into the string.
691 "User ID: {0}".format("root") -> "User ID: root"
693 # Use the named keyword arguments
696 'User ID: {uid} Last seen: {last_login}'.format(uid='root',
697 last_login = '5 Mar 2008 07:20') ->
698 'User ID: root Last seen: 5 Mar 2008 07:20'
700 Curly brackets can be escaped by doubling them::
702 format("Empty dict: {{}}") -> "Empty dict: {}"
704 Field names can be integers indicating positional arguments, such as
705 ``{0}``, ``{1}``, etc. or names of keyword arguments. You can also
706 supply compound field names that read attributes or access dictionary keys::
709 'Platform: {0.platform}\nPython version: {0.version}'.format(sys) ->
711 Python version: 2.6a1+ (trunk:61261M, Mar 5 2008, 20:29:41) \n
712 [GCC 4.0.1 (Apple Computer, Inc. build 5367)]'
715 'Content-type: {0[.mp4]}'.format(mimetypes.types_map) ->
716 'Content-type: video/mp4'
718 Note that when using dictionary-style notation such as ``[.mp4]``, you
719 don't need to put any quotation marks around the string; it will look
720 up the value using ``.mp4`` as the key. Strings beginning with a
721 number will be converted to an integer. You can't write more
722 complicated expressions inside a format string.
724 So far we've shown how to specify which field to substitute into the
725 resulting string. The precise formatting used is also controllable by
726 adding a colon followed by a format specifier. For example::
728 # Field 0: left justify, pad to 15 characters
729 # Field 1: right justify, pad to 6 characters
730 fmt = '{0:15} ${1:>6}'
731 fmt.format('Registration', 35) ->
733 fmt.format('Tutorial', 50) ->
735 fmt.format('Banquet', 125) ->
738 Format specifiers can reference other fields through nesting::
741 fmt.format('Invoice #1234', 15) ->
744 fmt.format('Invoice #1234', width) ->
747 The alignment of a field within the desired width can be specified:
749 ================ ============================================
751 ================ ============================================
752 < (default) Left-align
755 = (For numeric types only) Pad after the sign.
756 ================ ============================================
758 Format specifiers can also include a presentation type, which
759 controls how the value is formatted. For example, floating-point numbers
760 can be formatted as a general number or in exponential notation:
762 >>> '{0:g}'.format(3.75)
764 >>> '{0:e}'.format(3.75)
767 A variety of presentation types are available. Consult the 2.6
768 documentation for a :ref:`complete list <formatstrings>`; here's a sample::
770 'b' - Binary. Outputs the number in base 2.
771 'c' - Character. Converts the integer to the corresponding
772 Unicode character before printing.
773 'd' - Decimal Integer. Outputs the number in base 10.
774 'o' - Octal format. Outputs the number in base 8.
775 'x' - Hex format. Outputs the number in base 16, using lower-
776 case letters for the digits above 9.
777 'e' - Exponent notation. Prints the number in scientific
778 notation using the letter 'e' to indicate the exponent.
779 'g' - General format. This prints the number as a fixed-point
780 number, unless the number is too large, in which case
781 it switches to 'e' exponent notation.
782 'n' - Number. This is the same as 'g' (for floats) or 'd' (for
783 integers), except that it uses the current locale setting to
784 insert the appropriate number separator characters.
785 '%' - Percentage. Multiplies the number by 100 and displays
786 in fixed ('f') format, followed by a percent sign.
788 Classes and types can define a __format__ method to control how they're
789 formatted. It receives a single argument, the format specifier::
791 def __format__(self, format_spec):
792 if isinstance(format_spec, unicode):
793 return unicode(str(self))
797 There's also a format() built-in that will format a single value. It calls
798 the type's :meth:`__format__` method with the provided specifier::
800 >>> format(75.6564, '.2f')
807 The reference format fields.
809 :pep:`3101` - Advanced String Formatting
810 PEP written by Talin. Implemented by Eric Smith.
812 .. ======================================================================
816 PEP 3105: ``print`` As a Function
817 =====================================================
819 The ``print`` statement becomes the :func:`print` function in Python 3.0.
820 Making :func:`print` a function makes it easier to change
821 by doing 'def print(...)' or importing a new function from somewhere else.
823 Python 2.6 has a ``__future__`` import that removes ``print`` as language
824 syntax, letting you use the functional form instead. For example::
826 from __future__ import print_function
827 print('# of entries', len(dictionary), file=sys.stderr)
829 The signature of the new function is::
831 def print(*args, sep=' ', end='\n', file=None)
835 * **args**: positional arguments whose values will be printed out.
836 * **sep**: the separator, which will be printed between arguments.
837 * **end**: the ending text, which will be printed after all of the
838 arguments have been output.
839 * **file**: the file object to which the output will be sent.
843 :pep:`3105` - Make print a function
844 PEP written by Georg Brandl.
846 .. ======================================================================
850 PEP 3110: Exception-Handling Changes
851 =====================================================
853 One error that Python programmers occasionally make
858 except TypeError, ValueError:
861 The author is probably trying to catch both
862 :exc:`TypeError` and :exc:`ValueError` exceptions, but this code
863 actually does something different: it will catch
864 :exc:`TypeError` and bind the resulting exception object
865 to the local name ``"ValueError"``. The correct code
866 would have specified a tuple::
870 except (TypeError, ValueError):
873 This error is possible because the use of the comma here is ambiguous:
874 does it indicate two different nodes in the parse tree, or a single
877 Python 3.0 changes the syntax to make this unambiguous by replacing
878 the comma with the word "as". To catch an exception and store the
879 exception object in the variable ``exc``, you must write::
883 except TypeError as exc:
886 Python 3.0 will only support the use of "as", and therefore interprets
887 the first example as catching two different exceptions. Python 2.6
888 supports both the comma and "as", so existing code will continue to
893 :pep:`3110` - Catching Exceptions in Python 3000
894 PEP written and implemented by Collin Winter.
896 .. ======================================================================
900 PEP 3112: Byte Literals
901 =====================================================
903 Python 3.0 adopts Unicode as the language's fundamental string type and
904 denotes 8-bit literals differently, either as ``b'string'``
905 or using a :class:`bytes` constructor. For future compatibility,
906 Python 2.6 adds :class:`bytes` as a synonym for the :class:`str` type,
907 and it also supports the ``b''`` notation.
909 There's also a ``__future__`` import that causes all string literals
910 to become Unicode strings. This means that ``\u`` escape sequences
911 can be used to include Unicode characters::
914 from __future__ import unicode_literals
916 s = ('\u751f\u3080\u304e\u3000\u751f\u3054'
917 '\u3081\u3000\u751f\u305f\u307e\u3054')
919 print len(s) # 12 Unicode characters
921 At the C level, Python 3.0 will rename the existing 8-bit
922 string type, called :ctype:`PyStringObject` in Python 2.x,
923 to :ctype:`PyBytesObject`. Python 2.6 uses ``#define``
924 to support using the names :cfunc:`PyBytesObject`,
925 :cfunc:`PyBytes_Check`, :cfunc:`PyBytes_FromStringAndSize`,
926 and all the other functions and macros used with strings.
928 Instances of the :class:`bytes` type are immutable just
929 as strings are. A new :class:`bytearray` type stores a mutable
932 >>> bytearray([65, 66, 67])
934 >>> b = bytearray(u'\u21ef\u3244', 'utf-8')
936 bytearray(b'\xe2\x87\xaf \xe3\x89\x84')
939 bytearray(b'\xe3\x87\xaf \xe3\x89\x84')
940 >>> unicode(str(b), 'utf-8')
943 Byte arrays support most of the methods of string types, such as
944 :meth:`startswith`/:meth:`endswith`, :meth:`find`/:meth:`rfind`,
945 and some of the methods of lists, such as :meth:`append`,
946 :meth:`pop`, and :meth:`reverse`.
948 >>> b = bytearray('ABC')
950 >>> b.append(ord('e'))
956 :pep:`3112` - Bytes literals in Python 3000
957 PEP written by Jason Orendorff; backported to 2.6 by Christian Heimes.
959 .. ======================================================================
963 PEP 3116: New I/O Library
964 =====================================================
966 Python's built-in file objects support a number of methods, but
967 file-like objects don't necessarily support all of them. Objects that
968 imitate files usually support :meth:`read` and :meth:`write`, but they
969 may not support :meth:`readline`. Python 3.0 introduces a layered I/O
970 library in the :mod:`io` module that separates buffering and
971 text-handling features from the fundamental read and write operations.
973 There are three levels of abstract base classes provided by
974 the :mod:`io` module:
976 * :class:`RawIOBase`: defines raw I/O operations: :meth:`read`,
978 :meth:`write`, :meth:`seek`, :meth:`tell`, :meth:`truncate`,
980 Most of the methods of this class will often map to a single system call.
981 There are also :meth:`readable`, :meth:`writable`, and :meth:`seekable`
982 methods for determining what operations a given object will allow.
984 Python 3.0 has concrete implementations of this class for files and
985 sockets, but Python 2.6 hasn't restructured its file and socket objects
988 .. XXX should 2.6 register them in io.py?
990 * :class:`BufferedIOBase`: is an abstract base class that
991 buffers data in memory to reduce the number of
992 system calls used, making I/O processing more efficient.
993 It supports all of the methods of :class:`RawIOBase`,
994 and adds a :attr:`raw` attribute holding the underlying raw object.
996 There are four concrete classes implementing this ABC:
997 :class:`BufferedWriter` and
998 :class:`BufferedReader` for objects that only support
999 writing or reading and don't support random access,
1000 :class:`BufferedRandom` for objects that support the :meth:`seek` method
1002 and :class:`BufferedRWPair` for objects such as TTYs that have
1003 both read and write operations that act upon unconnected streams of data.
1005 * :class:`TextIOBase`: Provides functions for reading and writing
1006 strings (remember, strings will be Unicode in Python 3.0),
1007 and supporting universal newlines. :class:`TextIOBase` defines
1008 the :meth:`readline` method and supports iteration upon
1011 There are two concrete implementations. :class:`TextIOWrapper`
1012 wraps a buffered I/O object, supporting all of the methods for
1013 text I/O and adding a :attr:`buffer` attribute for access
1014 to the underlying object. :class:`StringIO` simply buffers
1015 everything in memory without ever writing anything to disk.
1017 (In current 2.6 alpha releases, :class:`io.StringIO` is implemented in
1018 pure Python, so it's pretty slow. You should therefore stick with the
1019 existing :mod:`StringIO` module or :mod:`cStringIO` for now. At some
1020 point Python 3.0's :mod:`io` module will be rewritten into C for speed,
1021 and perhaps the C implementation will be backported to the 2.x releases.)
1023 .. XXX check before final release: is io.py still written in Python?
1025 In Python 2.6, the underlying implementations haven't been
1026 restructured to build on top of the :mod:`io` module's classes. The
1027 module is being provided to make it easier to write code that's
1028 forward-compatible with 3.0, and to save developers the effort of writing
1029 their own implementations of buffering and text I/O.
1033 :pep:`3116` - New I/O
1034 PEP written by Daniel Stutzbach, Mike Verdone, and Guido van Rossum.
1035 Code by Guido van Rossum, Georg Brandl, Walter Doerwald,
1036 Jeremy Hylton, Martin von Loewis, Tony Lownds, and others.
1038 .. ======================================================================
1042 PEP 3118: Revised Buffer Protocol
1043 =====================================================
1045 The buffer protocol is a C-level API that lets Python types
1046 exchange pointers into their internal representations. A
1047 memory-mapped file can be viewed as a buffer of characters, for
1048 example, and this lets another module such as :mod:`re`
1049 treat memory-mapped files as a string of characters to be searched.
1051 The primary users of the buffer protocol are numeric-processing
1052 packages such as NumPy, which can expose the internal representation
1053 of arrays so that callers can write data directly into an array instead
1054 of going through a slower API. This PEP updates the buffer protocol in light of experience
1055 from NumPy development, adding a number of new features
1056 such as indicating the shape of an array,
1059 The most important new C API function is
1060 ``PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)``, which
1061 takes an object and a set of flags, and fills in the
1062 ``Py_buffer`` structure with information
1063 about the object's memory representation. Objects
1064 can use this operation to lock memory in place
1065 while an external caller could be modifying the contents,
1066 so there's a corresponding
1067 ``PyObject_ReleaseBuffer(PyObject *obj, Py_buffer *view)`` to
1068 indicate that the external caller is done.
1070 The **flags** argument to :cfunc:`PyObject_GetBuffer` specifies
1071 constraints upon the memory returned. Some examples are:
1073 * :const:`PyBUF_WRITABLE` indicates that the memory must be writable.
1075 * :const:`PyBUF_LOCK` requests a read-only or exclusive lock on the memory.
1077 * :const:`PyBUF_C_CONTIGUOUS` and :const:`PyBUF_F_CONTIGUOUS`
1078 requests a C-contiguous (last dimension varies the fastest) or
1079 Fortran-contiguous (first dimension varies the fastest) layout.
1081 .. XXX this feature is not in 2.6 docs yet
1085 :pep:`3118` - Revising the buffer protocol
1086 PEP written by Travis Oliphant and Carl Banks; implemented by
1090 .. ======================================================================
1094 PEP 3119: Abstract Base Classes
1095 =====================================================
1097 Some object-oriented languages such as Java support interfaces: declarations
1098 that a class has a given set of methods or supports a given access protocol.
1099 Abstract Base Classes (or ABCs) are an equivalent feature for Python. The ABC
1100 support consists of an :mod:`abc` module containing a metaclass called
1101 :class:`ABCMeta`, special handling
1102 of this metaclass by the :func:`isinstance` and :func:`issubclass` built-ins,
1103 and a collection of basic ABCs that the Python developers think will be widely
1106 Let's say you have a particular class and wish to know whether it supports
1107 dictionary-style access. The phrase "dictionary-style" is vague, however.
1108 It probably means that accessing items with ``obj[1]`` works.
1109 Does it imply that setting items with ``obj[2] = value`` works?
1110 Or that the object will have :meth:`keys`, :meth:`values`, and :meth:`items`
1111 methods? What about the iterative variants such as :meth:`iterkeys`? :meth:`copy`
1112 and :meth:`update`? Iterating over the object with :func:`iter`?
1114 Python 2.6 includes a number of different ABCs in the :mod:`collections`
1115 module. :class:`Iterable` indicates that a class defines :meth:`__iter__`,
1116 and :class:`Container` means the class supports ``x in y`` expressions
1117 by defining a :meth:`__contains__` method. The basic dictionary interface of
1118 getting items, setting items, and
1119 :meth:`keys`, :meth:`values`, and :meth:`items`, is defined by the
1120 :class:`MutableMapping` ABC.
1122 You can derive your own classes from a particular ABC
1123 to indicate they support that ABC's interface::
1127 class Storage(collections.MutableMapping):
1131 Alternatively, you could write the class without deriving from
1132 the desired ABC and instead register the class by
1133 calling the ABC's :meth:`register` method::
1140 collections.MutableMapping.register(Storage)
1142 For classes that you write, deriving from the ABC is probably clearer.
1143 The :meth:`register` method is useful when you've written a new
1144 ABC that can describe an existing type or class, or if you want
1145 to declare that some third-party class implements an ABC.
1146 For example, if you defined a :class:`PrintableType` ABC,
1149 # Register Python's types
1150 PrintableType.register(int)
1151 PrintableType.register(float)
1152 PrintableType.register(str)
1154 Classes should obey the semantics specified by an ABC, but
1155 Python can't check this; it's up to the class author to
1156 understand the ABC's requirements and to implement the code accordingly.
1158 To check whether an object supports a particular interface, you can
1162 if not isinstance(d, collections.MutableMapping):
1163 raise ValueError("Mapping object expected, not %r" % d)
1165 (Don't feel that you must now begin writing lots of checks as in the
1166 above example. Python has a strong tradition of duck-typing, where
1167 explicit type-checking isn't done and code simply calls methods on
1168 an object, trusting that those methods will be there and raising an
1169 exception if they aren't. Be judicious in checking for ABCs
1170 and only do it where it helps.)
1172 You can write your own ABCs by using ``abc.ABCMeta`` as the
1173 metaclass in a class definition::
1175 from abc import ABCMeta
1178 __metaclass__ = ABCMeta
1180 def draw(self, x, y, scale=1.0):
1183 def draw_doubled(self, x, y):
1184 self.draw(x, y, scale=2.0)
1187 class Square(Drawable):
1188 def draw(self, x, y, scale):
1192 In the :class:`Drawable` ABC above, the :meth:`draw_doubled` method
1193 renders the object at twice its size and can be implemented in terms
1194 of other methods described in :class:`Drawable`. Classes implementing
1195 this ABC therefore don't need to provide their own implementation
1196 of :meth:`draw_doubled`, though they can do so. An implementation
1197 of :meth:`draw` is necessary, though; the ABC can't provide
1198 a useful generic implementation. You
1199 can apply the ``@abstractmethod`` decorator to methods such as
1200 :meth:`draw` that must be implemented; Python will
1201 then raise an exception for classes that
1202 don't define the method::
1205 __metaclass__ = ABCMeta
1208 def draw(self, x, y, scale):
1211 Note that the exception is only raised when you actually
1212 try to create an instance of a subclass without the method::
1215 Traceback (most recent call last):
1216 File "<stdin>", line 1, in <module>
1217 TypeError: Can't instantiate abstract class Square with abstract methods draw
1220 Abstract data attributes can be declared using the ``@abstractproperty`` decorator::
1226 Subclasses must then define a :meth:`readonly` property
1230 :pep:`3119` - Introducing Abstract Base Classes
1231 PEP written by Guido van Rossum and Talin.
1232 Implemented by Guido van Rossum.
1233 Backported to 2.6 by Benjamin Aranguren, with Alex Martelli.
1235 .. ======================================================================
1239 PEP 3127: Integer Literal Support and Syntax
1240 =====================================================
1242 Python 3.0 changes the syntax for octal (base-8) integer literals,
1243 which are now prefixed by "0o" or "0O" instead of a leading zero, and
1244 adds support for binary (base-2) integer literals, signalled by a "0b"
1247 Python 2.6 doesn't drop support for a leading 0 signalling
1248 an octal number, but it does add support for "0o" and "0b"::
1255 The :func:`oct` built-in still returns numbers
1256 prefixed with a leading zero, and a new :func:`bin`
1257 built-in returns the binary representation for a number::
1264 The :func:`int` and :func:`long` built-ins will now accept the "0o"
1265 and "0b" prefixes when base-8 or base-2 are requested, or when the
1266 **base** argument is zero (meaning the base used is determined from
1273 >>> int('0b1101', 2)
1275 >>> int('0b1101', 0)
1281 :pep:`3127` - Integer Literal Support and Syntax
1282 PEP written by Patrick Maupin; backported to 2.6 by
1285 .. ======================================================================
1289 PEP 3129: Class Decorators
1290 =====================================================
1292 Decorators have been extended from functions to classes. It's now legal to
1300 This is equivalent to::
1309 :pep:`3129` - Class Decorators
1310 PEP written by Collin Winter.
1312 .. ======================================================================
1316 PEP 3141: A Type Hierarchy for Numbers
1317 =====================================================
1319 In Python 3.0, several abstract base classes for numeric types,
1320 inspired by Scheme's numeric tower, are being added.
1321 This change was backported to 2.6 as the :mod:`numbers` module.
1323 The most general ABC is :class:`Number`. It defines no operations at
1324 all, and only exists to allow checking if an object is a number by
1325 doing ``isinstance(obj, Number)``.
1327 :class:`Complex` is a subclass of :class:`Number`. Complex numbers
1328 can undergo the basic operations of addition, subtraction,
1329 multiplication, division, and exponentiation, and you can retrieve the
1330 real and imaginary parts and obtain a number's conjugate. Python's built-in
1331 complex type is an implementation of :class:`Complex`.
1333 :class:`Real` further derives from :class:`Complex`, and adds
1334 operations that only work on real numbers: :func:`floor`, :func:`trunc`,
1335 rounding, taking the remainder mod N, floor division,
1338 :class:`Rational` numbers derive from :class:`Real`, have
1339 :attr:`numerator` and :attr:`denominator` properties, and can be
1340 converted to floats. Python 2.6 adds a simple rational-number class,
1341 :class:`Fraction`, in the :mod:`fractions` module. (It's called
1342 :class:`Fraction` instead of :class:`Rational` to avoid
1343 a name clash with :class:`numbers.Rational`.)
1345 :class:`Integral` numbers derive from :class:`Rational`, and
1346 can be shifted left and right with ``<<`` and ``>>``,
1347 combined using bitwise operations such as ``&`` and ``|``,
1348 and can be used as array indexes and slice boundaries.
1350 In Python 3.0, the PEP slightly redefines the existing built-ins
1351 :func:`round`, :func:`math.floor`, :func:`math.ceil`, and adds a new
1352 one, :func:`math.trunc`, that's been backported to Python 2.6.
1353 :func:`math.trunc` rounds toward zero, returning the closest
1354 :class:`Integral` that's between the function's argument and zero.
1358 :pep:`3141` - A Type Hierarchy for Numbers
1359 PEP written by Jeffrey Yasskin.
1361 `Scheme's numerical tower <http://www.gnu.org/software/guile/manual/html_node/Numerical-Tower.html#Numerical-Tower>`__, from the Guile manual.
1363 `Scheme's number datatypes <http://schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_sec_6.2>`__ from the R5RS Scheme specification.
1366 The :mod:`fractions` Module
1367 --------------------------------------------------
1369 To fill out the hierarchy of numeric types, a rational-number class is
1370 provided by the :mod:`fractions` module. Rational numbers store their
1371 values as a numerator and denominator forming a fraction, and can
1372 exactly represent numbers such as ``2/3`` that floating-point numbers
1373 can only approximate.
1375 The :class:`Fraction` constructor takes two :class:`Integral` values
1376 that will be the numerator and denominator of the resulting fraction. ::
1378 >>> from fractions import Fraction
1379 >>> a = Fraction(2, 3)
1380 >>> b = Fraction(2, 5)
1381 >>> float(a), float(b)
1382 (0.66666666666666663, 0.40000000000000002)
1388 To help in converting floating-point numbers to rationals,
1389 the float type now has a :meth:`as_integer_ratio()` method that returns
1390 the numerator and denominator for a fraction that evaluates to the same
1391 floating-point value::
1393 >>> (2.5) .as_integer_ratio()
1395 >>> (3.1415) .as_integer_ratio()
1396 (7074029114692207L, 2251799813685248L)
1397 >>> (1./3) .as_integer_ratio()
1398 (6004799503160661L, 18014398509481984L)
1400 Note that values that can only be approximated by floating-point
1401 numbers, such as 1./3, are not simplified to the number being
1402 approximated; the fraction attempts to match the floating-point value
1405 The :mod:`fractions` module is based upon an implementation by Sjoerd
1406 Mullender that was in Python's :file:`Demo/classes/` directory for a
1407 long time. This implementation was significantly updated by Jeffrey
1411 Other Language Changes
1412 ======================
1414 Here are all of the changes that Python 2.6 makes to the core Python language.
1416 * The :func:`hasattr` function was catching and ignoring all errors,
1417 under the assumption that they meant a :meth:`__getattr__` method
1418 was failing somewhere and the return value of :func:`hasattr` would
1419 therefore be ``False``. This logic shouldn't be applied to
1420 :exc:`KeyboardInterrupt` and :exc:`SystemExit`, however; Python 2.6
1421 will no longer discard such exceptions when :func:`hasattr`
1422 encounters them. (Fixed by Benjamin Peterson; :issue:`2196`.)
1424 * When calling a function using the ``**`` syntax to provide keyword
1425 arguments, you are no longer required to use a Python dictionary;
1426 any mapping will now work::
1429 ... print sorted(kw)
1431 >>> ud=UserDict.UserDict()
1433 >>> ud['b'] = 'string'
1437 (Contributed by Alexander Belopolsky; :issue:`1686487`.)
1439 * A new built-in, ``next(*iterator*, [*default*])`` returns the next item
1440 from the specified iterator. If the *default* argument is supplied,
1441 it will be returned if *iterator* has been exhausted; otherwise,
1442 the :exc:`StopIteration` exception will be raised. (:issue:`2719`)
1444 * Tuples now have :meth:`index` and :meth:`count` methods matching the
1445 list type's :meth:`index` and :meth:`count` methods::
1451 (Contributed by Raymond Hettinger)
1453 * The built-in types now have improved support for extended slicing syntax,
1454 where various combinations of ``(start, stop, step)`` are supplied.
1455 Previously, the support was partial and certain corner cases wouldn't work.
1456 (Implemented by Thomas Wouters.)
1460 * Properties now have three attributes, :attr:`getter`,
1461 :attr:`setter` and :attr:`deleter`, that are useful shortcuts for
1462 adding or modifying a getter, setter or deleter function to an
1463 existing property. You would use them like this::
1487 * Several methods of the built-in set types now accept multiple iterables:
1488 :meth:`intersection`,
1489 :meth:`intersection_update`,
1490 :meth:`union`, :meth:`update`,
1491 :meth:`difference` and :meth:`difference_update`.
1495 >>> s=set('1234567890')
1496 >>> s.intersection('abc123', 'cdf246') # Intersection between all inputs
1498 >>> s.difference('246', '789')
1499 set(['1', '0', '3', '5'])
1501 (Contributed by Raymond Hettinger.)
1503 * A numerical nicety: when creating a complex number from two floats
1504 on systems that support signed zeros (-0 and +0), the
1505 :func:`complex` constructor will now preserve the sign
1506 of the zero. (Fixed by Mark T. Dickinson; :issue:`1507`)
1508 * More floating-point features were also added. The :func:`float` function
1509 will now turn the string ``nan`` into an
1510 IEEE 754 Not A Number value, and ``+inf`` and ``-inf`` into
1511 positive or negative infinity. This works on any platform with
1512 IEEE 754 semantics. (Contributed by Christian Heimes; :issue:`1635`.)
1514 Other functions in the :mod:`math` module, :func:`isinf` and
1515 :func:`isnan`, return true if their floating-point argument is
1516 infinite or Not A Number. (:issue:`1640`)
1518 The float type has a new instance method :meth:`float.hex` and a
1519 corresponding new class method :meth:`float.fromhex` to convert
1520 floating-point numbers to and from hexadecimal strings,
1521 respectively. (:issue:`3008`)
1523 * The :mod:`math` module has a number of new functions, and the existing
1524 functions have been improved to give more consistent behaviour
1525 across platforms, especially with respect to handling of
1526 floating-point exceptions and IEEE 754 special values.
1527 The new functions are:
1529 * :func:`~math.isinf` and :func:`~math.isnan` determine whether a given float
1530 is a (positive or negative) infinity or a NaN (Not a Number), respectively.
1532 * :func:`~math.copysign` copies the sign bit of an IEEE 754 number,
1533 returning the absolute value of *x* combined with the sign bit of
1534 *y*. For example, ``math.copysign(1, -0.0)`` returns -1.0.
1535 (Contributed by Christian Heimes.)
1537 * :func:`~math.factorial` computes the factorial of a number.
1538 (Contributed by Raymond Hettinger; :issue:`2138`.)
1540 * :func:`~math.fsum` adds up the stream of numbers from an iterable,
1541 and is careful to avoid loss of precision by calculating partial sums.
1542 (Contributed by Jean Brouwers, Raymond Hettinger, and Mark Dickinson;
1545 * The inverse hyperbolic functions :func:`~math.acosh`, :func:`~math.asinh`
1546 and :func:`~math.atanh`.
1548 * The function :func:`~math.log1p`, returning the natural logarithm of *1+x*
1551 There's also a new :func:`trunc` built-in function as a result of the
1552 backport of `PEP 3141's type hierarchy for numbers <#pep-3141>`__.
1554 The existing math functions have been modified to follow the
1555 recommendations of the C99 standard with respect to special values
1556 whenever possible. For example, ``sqrt(-1.)`` should now give a
1557 :exc:`ValueError` across (nearly) all platforms, while
1558 ``sqrt(float('NaN'))`` should return a NaN on all IEEE 754
1559 platforms. Where Annex 'F' of the C99 standard recommends signaling
1560 'divide-by-zero' or 'invalid', Python will raise :exc:`ValueError`.
1561 Where Annex 'F' of the C99 standard recommends signaling 'overflow',
1562 Python will raise :exc:`OverflowError`. (See :issue:`711019`,
1565 (Contributed by Christian Heimes and Mark Dickinson.)
1567 * Changes to the :class:`Exception` interface
1568 as dictated by :pep:`352` continue to be made. For 2.6,
1569 the :attr:`message` attribute is being deprecated in favor of the
1570 :attr:`args` attribute.
1572 * The :exc:`GeneratorExit` exception now subclasses
1573 :exc:`BaseException` instead of :exc:`Exception`. This means
1574 that an exception handler that does ``except Exception:``
1575 will not inadvertently catch :exc:`GeneratorExit`.
1576 (Contributed by Chad Austin; :issue:`1537`.)
1578 * Generator objects now have a :attr:`gi_code` attribute that refers to
1579 the original code object backing the generator.
1580 (Contributed by Collin Winter; :issue:`1473257`.)
1582 * The :func:`compile` built-in function now accepts keyword arguments
1583 as well as positional parameters. (Contributed by Thomas Wouters;
1586 * The :func:`complex` constructor now accepts strings containing
1587 parenthesized complex numbers, letting ``complex(repr(cmplx))``
1588 will now round-trip values. For example, ``complex('(3+4j)')``
1589 now returns the value (3+4j). (:issue:`1491866`)
1591 * The string :meth:`translate` method now accepts ``None`` as the
1592 translation table parameter, which is treated as the identity
1593 transformation. This makes it easier to carry out operations
1594 that only delete characters. (Contributed by Bengt Richter and
1595 implemented by Raymond Hettinger; :issue:`1193128`.)
1597 * The built-in :func:`dir` function now checks for a :meth:`__dir__`
1598 method on the objects it receives. This method must return a list
1599 of strings containing the names of valid attributes for the object,
1600 and lets the object control the value that :func:`dir` produces.
1601 Objects that have :meth:`__getattr__` or :meth:`__getattribute__`
1602 methods can use this to advertise pseudo-attributes they will honor.
1605 * Instance method objects have new attributes for the object and function
1606 comprising the method; the new synonym for :attr:`im_self` is
1607 :attr:`__self__`, and :attr:`im_func` is also available as :attr:`__func__`.
1608 The old names are still supported in Python 2.6; they're gone in 3.0.
1610 * An obscure change: when you use the the :func:`locals` function inside a
1611 :keyword:`class` statement, the resulting dictionary no longer returns free
1612 variables. (Free variables, in this case, are variables referred to in the
1613 :keyword:`class` statement that aren't attributes of the class.)
1615 .. ======================================================================
1621 * The :mod:`warnings` module has been rewritten in C. This makes
1622 it possible to invoke warnings from the parser, and may also
1623 make the interpreter's startup faster.
1624 (Contributed by Neal Norwitz and Brett Cannon; :issue:`1631171`.)
1626 * Type objects now have a cache of methods that can reduce
1627 the amount of work required to find the correct method implementation
1628 for a particular class; once cached, the interpreter doesn't need to
1629 traverse base classes to figure out the right method to call.
1630 The cache is cleared if a base class or the class itself is modified,
1631 so the cache should remain correct even in the face of Python's dynamic
1633 (Original optimization implemented by Armin Rigo, updated for
1634 Python 2.6 by Kevin Jacobs; :issue:`1700288`.)
1636 * All of the functions in the :mod:`struct` module have been rewritten in
1637 C, thanks to work at the Need For Speed sprint.
1638 (Contributed by Raymond Hettinger.)
1640 * Internally, a bit is now set in type objects to indicate some of the standard
1641 built-in types. This speeds up checking if an object is a subclass of one of
1642 these types. (Contributed by Neal Norwitz.)
1644 * Unicode strings now use faster code for detecting
1645 whitespace and line breaks; this speeds up the :meth:`split` method
1646 by about 25% and :meth:`splitlines` by 35%.
1647 (Contributed by Antoine Pitrou.) Memory usage is reduced
1648 by using pymalloc for the Unicode string's data.
1650 * The ``with`` statement now stores the :meth:`__exit__` method on the stack,
1651 producing a small speedup. (Implemented by Jeffrey Yasskin.)
1653 * To reduce memory usage, the garbage collector will now clear internal
1654 free lists when garbage-collecting the highest generation of objects.
1655 This may return memory to the OS sooner.
1657 The net result of the 2.6 optimizations is that Python 2.6 runs the pystone
1658 benchmark around XX% faster than Python 2.5.
1660 .. ======================================================================
1662 .. _new-26-interpreter:
1665 -------------------------------
1667 Two command-line options have been reserved for use by other Python
1668 implementations. The :option:`-J` switch has been reserved for use by
1669 Jython for Jython-specific options, such as ones that are passed to
1670 the underlying JVM. :option:`-X` has been reserved for options
1671 specific to a particular implementation of Python such as CPython,
1672 Jython, or IronPython. If either option is used with Python 2.6, the
1673 interpreter will report that the option isn't currently used.
1675 It's now possible to prevent Python from writing :file:`.pyc` or
1676 :file:`.pyo` files on importing a module by supplying the :option:`-B`
1677 switch to the Python interpreter, or by setting the
1678 :envvar:`PYTHONDONTWRITEBYTECODE` environment variable before running
1679 the interpreter. This setting is available to Python programs as the
1680 ``sys.dont_write_bytecode`` variable, and can be changed by Python
1681 code to modify the interpreter's behaviour. (Contributed by Neal
1682 Norwitz and Georg Brandl.)
1684 The encoding used for standard input, output, and standard error can
1685 be specified by setting the :envvar:`PYTHONIOENCODING` environment
1686 variable before running the interpreter. The value should be a string
1687 in the form ``**encoding**`` or ``**encoding**:**errorhandler**``.
1688 The **encoding** part specifies the encoding's name, e.g. ``utf-8`` or
1689 ``latin-1``; the optional **errorhandler** part specifies
1690 what to do with characters that can't be handled by the encoding,
1691 and should be one of "error", "ignore", or "replace". (Contributed
1692 by Martin von Loewis.)
1694 .. ======================================================================
1696 New, Improved, and Deprecated Modules
1697 =====================================
1699 As usual, Python's standard library received a number of enhancements and bug
1700 fixes. Here's a partial list of the most notable changes, sorted alphabetically
1701 by module name. Consult the :file:`Misc/NEWS` file in the source tree for a more
1702 complete list of changes, or look through the Subversion logs for all the
1705 * (3.0-warning mode) Python 3.0 will feature a reorganized standard
1706 library; many outdated modules are being dropped.
1707 Python 2.6 running in 3.0-warning mode will warn about these modules
1708 when they are imported.
1710 The list of deprecated modules is:
1712 :mod:`bgenlocations`,
1714 :mod:`bundlebuilder`,
1720 :mod:`gensuitemodule`,
1724 :mod:`linuxaudiodev`,
1733 :mod:`test.testall`,
1736 Various MacOS modules have been removed:
1737 :mod:`_builtinSuites`,
1742 :mod:`appletrawmain`,
1743 :mod:`appletrunner`,
1744 :mod:`argvemulator`,
1766 :mod:`OSATerminology`,
1768 :mod:`PixMapWrapper`,
1770 :mod:`SystemEvents`,
1772 :mod:`terminalcommand`.
1774 A number of old IRIX-specific modules were deprecated:
1775 :mod:`al` and :mod:`AL`,
1779 :mod:`CL` and :mod:`cl`,
1783 :mod:`FL` and :mod:`fl`,
1788 :mod:`GL` and :mod:`gl`,
1794 :mod:`SV` and :mod:`sv`,
1799 * The :mod:`asyncore` and :mod:`asynchat` modules are
1800 being actively maintained again, and a number of patches and bugfixes
1801 were applied. (Maintained by Josiah Carlson; see :issue:`1736190` for
1804 * The :mod:`bsddb.dbshelve` module now uses the highest pickling protocol
1805 available, instead of restricting itself to protocol 1.
1806 (Contributed by W. Barnes; :issue:`1551443`.)
1808 * The :mod:`cgi` module will now read variables from the query string of an
1809 HTTP POST request. This makes it possible to use form actions with
1810 URLs such as "/cgi-bin/add.py?category=1". (Contributed by
1811 Alexandre Fiori and Nubis; :issue:`1817`.)
1813 * The :mod:`cmath` module underwent an extensive set of revisions,
1814 thanks to Mark Dickinson and Christian Heimes, that added some new
1815 features and greatly improved the accuracy of the computations.
1817 Five new functions were added:
1819 * :func:`polar` converts a complex number to polar form, returning
1820 the modulus and argument of that complex number.
1822 * :func:`rect` does the opposite, turning a (modulus, argument) pair
1823 back into the corresponding complex number.
1825 * :func:`phase` returns the phase or argument of a complex number.
1827 * :func:`isnan` returns True if either
1828 the real or imaginary part of its argument is a NaN.
1830 * :func:`isinf` returns True if either the real or imaginary part of
1831 its argument is infinite.
1833 The revisions also improved the numerical soundness of the
1834 :mod:`cmath` module. For all functions, the real and imaginary
1835 parts of the results are accurate to within a few units of least
1836 precision (ulps) whenever possible. See :issue:`1381` for the
1837 details. The branch cuts for :func:`asinh`, :func:`atanh`: and
1838 :func:`atan` have also been corrected.
1840 The tests for the module have been greatly expanded; nearly 2000 new
1841 test cases exercise the algebraic functions.
1843 On IEEE 754 platforms, the :mod:`cmath` module now handles IEEE 754
1844 special values and floating-point exceptions in a manner consistent
1845 with Annex 'G' of the C99 standard.
1847 * A new data type in the :mod:`collections` module: :class:`namedtuple(typename,
1848 fieldnames)` is a factory function that creates subclasses of the standard tuple
1849 whose fields are accessible by name as well as index. For example::
1851 >>> var_type = collections.namedtuple('variable',
1852 ... 'id name type size')
1853 # Names are separated by spaces or commas.
1854 # 'id, name, type, size' would also work.
1855 >>> var_type._fields
1856 ('id', 'name', 'type', 'size')
1858 >>> var = var_type(1, 'frequency', 'int', 4)
1859 >>> print var[0], var.id # Equivalent
1861 >>> print var[2], var.type # Equivalent
1864 {'size': 4, 'type': 'int', 'id': 1, 'name': 'frequency'}
1865 >>> v2 = var._replace(name='amplitude')
1867 variable(id=1, name='amplitude', type='int', size=4)
1869 Where the new :class:`namedtuple` type proved suitable, the standard
1870 library has been modified to return them. For example,
1871 the :meth:`Decimal.as_tuple` method now returns a named tuple with
1872 :attr:`sign`, :attr:`digits`, and :attr:`exponent` fields.
1874 (Contributed by Raymond Hettinger.)
1876 * Another change to the :mod:`collections` module is that the
1877 :class:`deque` type now supports an optional *maxlen* parameter;
1878 if supplied, the deque's size will be restricted to no more
1879 than *maxlen* items. Adding more items to a full deque causes
1880 old items to be discarded.
1884 >>> from collections import deque
1885 >>> dq=deque(maxlen=3)
1888 >>> dq.append(1) ; dq.append(2) ; dq.append(3)
1890 deque([1, 2, 3], maxlen=3)
1893 deque([2, 3, 4], maxlen=3)
1895 (Contributed by Raymond Hettinger.)
1897 * A new method in the :mod:`curses` module: for a window, :meth:`chgat` changes
1898 the display characters for a certain number of characters on a single line.
1899 (Contributed by Fabian Kreutz.)
1902 # Boldface text starting at y=0,x=21
1903 # and affecting the rest of the line.
1904 stdscr.chgat(0,21, curses.A_BOLD)
1906 The :class:`Textbox` class in the :mod:`curses.textpad` module
1907 now supports editing in insert mode as well as overwrite mode.
1908 Insert mode is enabled by supplying a true value for the *insert_mode*
1909 parameter when creating the :class:`Textbox` instance.
1911 * The :mod:`datetime` module's :meth:`strftime` methods now support a
1912 ``%f`` format code that expands to the number of microseconds in the
1913 object, zero-padded on
1914 the left to six places. (Contributed by Skip Montanaro; :issue:`1158`.)
1916 * The :mod:`decimal` module was updated to version 1.66 of
1917 `the General Decimal Specification <http://www2.hursley.ibm.com/decimal/decarith.html>`__. New features
1918 include some methods for some basic mathematical functions such as
1919 :meth:`exp` and :meth:`log10`::
1921 >>> Decimal(1).exp()
1922 Decimal("2.718281828459045235360287471")
1923 >>> Decimal("2.7182818").ln()
1924 Decimal("0.9999999895305022877376682436")
1925 >>> Decimal(1000).log10()
1928 The :meth:`as_tuple` method of :class:`Decimal` objects now returns a
1929 named tuple with :attr:`sign`, :attr:`digits`, and :attr:`exponent` fields.
1931 (Implemented by Facundo Batista and Mark Dickinson. Named tuple
1932 support added by Raymond Hettinger.)
1934 * The :mod:`difflib` module's :class:`SequenceMatcher` class
1935 now returns named tuples representing matches.
1936 In addition to behaving like tuples, the returned values
1937 also have :attr:`a`, :attr:`b`, and :attr:`size` attributes.
1938 (Contributed by Raymond Hettinger.)
1940 * An optional ``timeout`` parameter was added to the
1941 :class:`ftplib.FTP` class constructor as well as the :meth:`connect`
1942 method, specifying a timeout measured in seconds. (Added by Facundo
1943 Batista.) Also, the :class:`FTP` class's
1944 :meth:`storbinary` and :meth:`storlines`
1945 now take an optional *callback* parameter that will be called with
1946 each block of data after the data has been sent.
1947 (Contributed by Phil Schwartz; :issue:`1221598`.)
1949 * The :func:`reduce` built-in function is also available in the
1950 :mod:`functools` module. In Python 3.0, the built-in is dropped and it's
1951 only available from :mod:`functools`; currently there are no plans
1952 to drop the built-in in the 2.x series. (Patched by
1953 Christian Heimes; :issue:`1739906`.)
1955 * When possible, the :mod:`getpass` module will now use
1956 :file:`/dev/tty` (when available) to print
1957 a prompting message and read the password, falling back to using
1958 standard error and standard input. If the password may be echoed to
1959 the terminal, a warning is printed before the prompt is displayed.
1960 (Contributed by Gregory P. Smith.)
1962 * The :func:`glob.glob` function can now return Unicode filenames if
1963 a Unicode path was used and Unicode filenames are matched within the
1964 directory. (:issue:`1001604`)
1966 * The :mod:`gopherlib` module has been removed.
1968 * A new function in the :mod:`heapq` module: ``merge(iter1, iter2, ...)``
1969 takes any number of iterables that return data *in sorted
1970 order*, and returns a new iterator that returns the contents of all
1971 the iterators, also in sorted order. For example::
1973 heapq.merge([1, 3, 5, 9], [2, 8, 16]) ->
1974 [1, 2, 3, 5, 8, 9, 16]
1976 Another new function, ``heappushpop(heap, item)``,
1977 pushes *item* onto *heap*, then pops off and returns the smallest item.
1978 This is more efficient than making a call to :func:`heappush` and then
1981 :mod:`heapq` is now implemented to only use less-than comparison,
1982 instead of the less-than-or-equal comparison it previously used.
1983 This makes :mod:`heapq`'s usage of a type match that of the
1984 :meth:`list.sort` method.
1985 (Contributed by Raymond Hettinger.)
1987 * An optional ``timeout`` parameter was added to the
1988 :class:`httplib.HTTPConnection` and :class:`HTTPSConnection`
1989 class constructors, specifying a timeout measured in seconds.
1990 (Added by Facundo Batista.)
1992 * Most of the :mod:`inspect` module's functions, such as
1993 :func:`getmoduleinfo` and :func:`getargs`, now return named tuples.
1994 In addition to behaving like tuples, the elements of the return value
1995 can also be accessed as attributes.
1996 (Contributed by Raymond Hettinger.)
1998 Some new functions in the module include
1999 :func:`isgenerator`, :func:`isgeneratorfunction`,
2000 and :func:`isabstract`.
2002 * The :mod:`itertools` module gained several new functions.
2004 ``izip_longest(iter1, iter2, ...[, fillvalue])`` makes tuples from
2005 each of the elements; if some of the iterables are shorter than
2006 others, the missing values are set to *fillvalue*. For example::
2008 itertools.izip_longest([1,2,3], [1,2,3,4,5]) ->
2009 [(1, 1), (2, 2), (3, 3), (None, 4), (None, 5)]
2011 ``product(iter1, iter2, ..., [repeat=N])`` returns the Cartesian product
2012 of the supplied iterables, a set of tuples containing
2013 every possible combination of the elements returned from each iterable. ::
2015 itertools.product([1,2,3], [4,5,6]) ->
2016 [(1, 4), (1, 5), (1, 6),
2017 (2, 4), (2, 5), (2, 6),
2018 (3, 4), (3, 5), (3, 6)]
2020 The optional *repeat* keyword argument is used for taking the
2021 product of an iterable or a set of iterables with themselves,
2022 repeated *N* times. With a single iterable argument, *N*-tuples
2025 itertools.product([1,2], repeat=3)) ->
2026 [(1, 1, 1), (1, 1, 2), (1, 2, 1), (1, 2, 2),
2027 (2, 1, 1), (2, 1, 2), (2, 2, 1), (2, 2, 2)]
2029 With two iterables, *2N*-tuples are returned. ::
2031 itertools(product([1,2], [3,4], repeat=2) ->
2032 [(1, 3, 1, 3), (1, 3, 1, 4), (1, 3, 2, 3), (1, 3, 2, 4),
2033 (1, 4, 1, 3), (1, 4, 1, 4), (1, 4, 2, 3), (1, 4, 2, 4),
2034 (2, 3, 1, 3), (2, 3, 1, 4), (2, 3, 2, 3), (2, 3, 2, 4),
2035 (2, 4, 1, 3), (2, 4, 1, 4), (2, 4, 2, 3), (2, 4, 2, 4)]
2037 ``combinations(iterable, r)`` returns sub-sequences of length *r* from
2038 the elements of *iterable*. ::
2040 itertools.combinations('123', 2) ->
2041 [('1', '2'), ('1', '3'), ('2', '3')]
2043 itertools.combinations('123', 3) ->
2046 itertools.combinations('1234', 3) ->
2047 [('1', '2', '3'), ('1', '2', '4'), ('1', '3', '4'),
2050 ``permutations(iter[, r])`` returns all the permutations of length *r* of
2051 the iterable's elements. If *r* is not specified, it will default to the
2052 number of elements produced by the iterable. ::
2054 itertools.permutations([1,2,3,4], 2) ->
2055 [(1, 2), (1, 3), (1, 4),
2056 (2, 1), (2, 3), (2, 4),
2057 (3, 1), (3, 2), (3, 4),
2058 (4, 1), (4, 2), (4, 3)]
2060 ``itertools.chain(*iterables)`` is an existing function in
2061 :mod:`itertools` that gained a new constructor in Python 2.6.
2062 ``itertools.chain.from_iterable(iterable)`` takes a single
2063 iterable that should return other iterables. :func:`chain` will
2064 then return all the elements of the first iterable, then
2065 all the elements of the second, and so on. ::
2067 chain.from_iterable([[1,2,3], [4,5,6]]) ->
2070 (All contributed by Raymond Hettinger.)
2072 * The :mod:`logging` module's :class:`FileHandler` class
2073 and its subclasses :class:`WatchedFileHandler`, :class:`RotatingFileHandler`,
2074 and :class:`TimedRotatingFileHandler` now
2075 have an optional *delay* parameter to its constructor. If *delay*
2076 is true, opening of the log file is deferred until the first
2077 :meth:`emit` call is made. (Contributed by Vinay Sajip.)
2079 :class:`TimedRotatingFileHandler` also has a *utc* constructor
2080 parameter. If the argument is true, UTC time will be used
2081 in determining when midnight occurs and in generating filenames;
2082 otherwise local time will be used.
2084 * The :mod:`macfs` module has been removed. This in turn required the
2085 :func:`macostools.touched` function to be removed because it depended on the
2086 :mod:`macfs` module. (:issue:`1490190`)
2088 * :class:`mmap` objects now have a :meth:`rfind` method that finds
2089 a substring, beginning at the end of the string and searching
2090 backwards. The :meth:`find` method
2091 also gained an *end* parameter containing the index at which to stop
2093 (Contributed by John Lenton.)
2095 * The :mod:`operator` module gained a
2096 :func:`methodcaller` function that takes a name and an optional
2097 set of arguments, returning a callable that will call
2098 the named function on any arguments passed to it. For example::
2100 >>> # Equivalent to lambda s: s.replace('old', 'new')
2101 >>> replacer = operator.methodcaller('replace', 'old', 'new')
2102 >>> replacer('old wine in old bottles')
2103 'new wine in new bottles'
2105 (Contributed by Georg Brandl, after a suggestion by Gregory Petrosyan.)
2107 The :func:`attrgetter` function now accepts dotted names and performs
2108 the corresponding attribute lookups::
2110 >>> inst_name = operator.attrgetter('__class__.__name__')
2116 (Contributed by Georg Brandl, after a suggestion by Barry Warsaw.)
2118 * New functions in the :mod:`os` module include
2119 ``fchmod(fd, mode)``, ``fchown(fd, uid, gid)``,
2120 and ``lchmod(path, mode)``, on operating systems that support these
2121 functions. :func:`fchmod` and :func:`fchown` let you change the mode
2122 and ownership of an opened file, and :func:`lchmod` changes the mode
2125 (Contributed by Georg Brandl and Christian Heimes.)
2127 * The :func:`os.walk` function now has a ``followlinks`` parameter. If
2128 set to True, it will follow symlinks pointing to directories and
2129 visit the directory's contents. For backward compatibility, the
2130 parameter's default value is false. Note that the function can fall
2131 into an infinite recursion if there's a symlink that points to a
2132 parent directory. (:issue:`1273829`)
2134 * The ``os.environ`` object's :meth:`clear` method will now unset the
2135 environment variables using :func:`os.unsetenv` in addition to clearing
2136 the object's keys. (Contributed by Martin Horcicka; :issue:`1181`.)
2138 * In the :mod:`os.path` module, the :func:`splitext` function
2139 has been changed to not split on leading period characters.
2140 This produces better results when operating on Unix's dot-files.
2141 For example, ``os.path.splitext('.ipython')``
2142 now returns ``('.ipython', '')`` instead of ``('', '.ipython')``.
2145 A new function, :func:`relpath(path, start)` returns a relative path
2146 from the ``start`` path, if it's supplied, or from the current
2147 working directory to the destination ``path``. (Contributed by
2148 Richard Barran; :issue:`1339796`.)
2150 On Windows, :func:`os.path.expandvars` will now expand environment variables
2151 in the form "%var%", and "~user" will be expanded into the
2152 user's home directory path. (Contributed by Josiah Carlson;
2155 * The Python debugger provided by the :mod:`pdb` module
2156 gained a new command: "run" restarts the Python program being debugged,
2157 and can optionally take new command-line arguments for the program.
2158 (Contributed by Rocky Bernstein; :issue:`1393667`.)
2160 The :func:`post_mortem` function, used to enter debugging of a
2161 traceback, will now use the traceback returned by :func:`sys.exc_info`
2162 if no traceback is supplied. (Contributed by Facundo Batista;
2165 * The :mod:`pickletools` module now has an :func:`optimize` function
2166 that takes a string containing a pickle and removes some unused
2167 opcodes, returning a shorter pickle that contains the same data structure.
2168 (Contributed by Raymond Hettinger.)
2170 * A :func:`get_data` function was added to the :mod:`pkgutil`
2171 module that returns the contents of resource files included
2172 with an installed Python package. For example::
2175 >>> pkgutil.get_data('test', 'exception_hierarchy.txt')
2178 +-- KeyboardInterrupt
2186 (Contributed by Paul Moore; :issue:`2439`.)
2188 * New functions in the :mod:`posix` module: :func:`chflags` and :func:`lchflags`
2189 are wrappers for the corresponding system calls (where they're available).
2190 Constants for the flag values are defined in the :mod:`stat` module; some
2191 possible values include :const:`UF_IMMUTABLE` to signal the file may not be
2192 changed and :const:`UF_APPEND` to indicate that data can only be appended to the
2193 file. (Contributed by M. Levinson.)
2195 ``os.closerange(*low*, *high*)`` efficiently closes all file descriptors
2196 from *low* to *high*, ignoring any errors and not including *high* itself.
2197 This function is now used by the :mod:`subprocess` module to make starting
2198 processes faster. (Contributed by Georg Brandl; :issue:`1663329`.)
2200 * The :mod:`pyexpat` module's :class:`Parser` objects now allow setting
2201 their :attr:`buffer_size` attribute to change the size of the buffer
2202 used to hold character data.
2203 (Contributed by Achim Gaedke; :issue:`1137`.)
2205 * The :mod:`Queue` module now provides queue classes that retrieve entries
2206 in different orders. The :class:`PriorityQueue` class stores
2207 queued items in a heap and retrieves them in priority order,
2208 and :class:`LifoQueue` retrieves the most recently added entries first,
2209 meaning that it behaves like a stack.
2210 (Contributed by Raymond Hettinger.)
2212 * The :mod:`random` module's :class:`Random` objects can
2213 now be pickled on a 32-bit system and unpickled on a 64-bit
2214 system, and vice versa. Unfortunately, this change also means
2215 that Python 2.6's :class:`Random` objects can't be unpickled correctly
2216 on earlier versions of Python.
2217 (Contributed by Shawn Ligocki; :issue:`1727780`.)
2219 The new ``triangular(low, high, mode)`` function returns random
2220 numbers following a triangular distribution. The returned values
2221 are between *low* and *high*, not including *high* itself, and
2222 with *mode* as the mode, the most frequently occurring value
2223 in the distribution. (Contributed by Wladmir van der Laan and
2224 Raymond Hettinger; :issue:`1681432`.)
2226 * Long regular expression searches carried out by the :mod:`re`
2227 module will now check for signals being delivered, so especially
2228 time-consuming searches can now be interrupted.
2229 (Contributed by Josh Hoyt and Ralf Schmitt; :issue:`846388`.)
2231 * The :mod:`rgbimg` module has been removed.
2233 * The :mod:`rlcompleter` module's :meth:`Completer.complete()` method
2234 will now ignore exceptions triggered while evaluating a name.
2235 (Fixed by Lorenz Quack; :issue:`2250`.)
2237 * The :mod:`sched` module's :class:`scheduler` instances now
2238 have a read-only :attr:`queue` attribute that returns the
2239 contents of the scheduler's queue, represented as a list of
2240 named tuples with the fields ``(time, priority, action, argument)``.
2241 (Contributed by Raymond Hettinger; :issue:`1861`.)
2243 * The :mod:`select` module now has wrapper functions
2244 for the Linux :cfunc:`epoll` and BSD :cfunc:`kqueue` system calls.
2245 Also, a :meth:`modify` method was added to the existing :class:`poll`
2246 objects; ``pollobj.modify(fd, eventmask)`` takes a file descriptor
2247 or file object and an event mask,
2249 (Contributed by Christian Heimes; :issue:`1657`.)
2251 * The :mod:`sets` module has been deprecated; it's better to
2252 use the built-in :class:`set` and :class:`frozenset` types.
2254 * The :func:`shutil.copytree` function now has an optional **ignore** argument
2255 that takes a callable object. This callable will receive each directory path
2256 and a list of the directory's contents, and returns a list of names that
2257 will be ignored, not copied.
2259 The :mod:`shutil` module also provides an :func:`ignore_patterns`
2260 function for use with this new parameter.
2261 :func:`ignore_patterns` takes an arbitrary number of glob-style patterns
2262 and will ignore any files and directories that match this pattern.
2263 The following example copies a directory tree, but skip both SVN's internal
2264 :file:`.svn` directories and Emacs backup
2265 files, which have names ending with '~'::
2267 shutil.copytree('Doc/library', '/tmp/library',
2268 ignore=shutil.ignore_patterns('*~', '.svn'))
2270 (Contributed by Tarek Ziadé; :issue:`2663`.)
2272 * Integrating signal handling with GUI handling event loops
2273 like those used by Tkinter or GTk+ has long been a problem; most
2274 software ends up polling, waking up every fraction of a second.
2275 The :mod:`signal` module can now make this more efficient.
2276 Calling ``signal.set_wakeup_fd(fd)`` sets a file descriptor
2277 to be used; when a signal is received, a byte is written to that
2278 file descriptor. There's also a C-level function,
2279 :cfunc:`PySignal_SetWakeupFd`, for setting the descriptor.
2281 Event loops will use this by opening a pipe to create two descriptors,
2282 one for reading and one for writing. The writable descriptor
2283 will be passed to :func:`set_wakeup_fd`, and the readable descriptor
2284 will be added to the list of descriptors monitored by the event loop via
2285 :cfunc:`select` or :cfunc:`poll`.
2286 On receiving a signal, a byte will be written and the main event loop
2287 will be woken up, without the need to poll.
2289 (Contributed by Adam Olsen; :issue:`1583`.)
2291 The :func:`siginterrupt` function is now available from Python code,
2292 and allows changing whether signals can interrupt system calls or not.
2293 (Contributed by Ralf Schmitt.)
2295 The :func:`setitimer` and :func:`getitimer` functions have also been
2296 added on systems that support these system calls. :func:`setitimer`
2297 allows setting interval timers that will cause a signal to be
2298 delivered to the process after a specified time, measured in
2299 wall-clock time, consumed process time, or combined process+system
2300 time. (Contributed by Guilherme Polo; :issue:`2240`.)
2302 * The :mod:`smtplib` module now supports SMTP over SSL thanks to the
2303 addition of the :class:`SMTP_SSL` class. This class supports an
2304 interface identical to the existing :class:`SMTP` class. Both
2305 class constructors also have an optional ``timeout`` parameter
2306 that specifies a timeout for the initial connection attempt, measured in
2309 An implementation of the LMTP protocol (:rfc:`2033`) was also added to
2310 the module. LMTP is used in place of SMTP when transferring e-mail
2311 between agents that don't manage a mail queue.
2313 (SMTP over SSL contributed by Monty Taylor; timeout parameter
2314 added by Facundo Batista; LMTP implemented by Leif
2315 Hedstrom; :issue:`957003`.)
2317 * In the :mod:`smtplib` module, SMTP.starttls() now complies with :rfc:`3207`
2318 and forgets any knowledge obtained from the server not obtained from
2319 the TLS negotiation itself. (Patch contributed by Bill Fenner;
2322 * The :mod:`socket` module now supports TIPC (http://tipc.sf.net),
2323 a high-performance non-IP-based protocol designed for use in clustered
2324 environments. TIPC addresses are 4- or 5-tuples.
2325 (Contributed by Alberto Bertogli; :issue:`1646`.)
2327 A new function, :func:`create_connection`, takes an address
2328 and connects to it using an optional timeout value, returning
2329 the connected socket object.
2331 * The base classes in the :mod:`SocketServer` module now support
2332 calling a :meth:`handle_timeout` method after a span of inactivity
2333 specified by the server's :attr:`timeout` attribute. (Contributed
2334 by Michael Pomraning.) The :meth:`serve_forever` method
2335 now takes an optional poll interval measured in seconds,
2336 controlling how often the server will check for a shutdown request.
2337 (Contributed by Pedro Werneck and Jeffrey Yasskin;
2338 :issue:`742598`, :issue:`1193577`.)
2340 * The :mod:`struct` module now supports the C99 :ctype:`_Bool` type,
2341 using the format character ``'?'``.
2342 (Contributed by David Remahl.)
2344 * The :class:`Popen` objects provided by the :mod:`subprocess` module
2345 now have :meth:`terminate`, :meth:`kill`, and :meth:`send_signal` methods.
2346 On Windows, :meth:`send_signal` only supports the :const:`SIGTERM`
2347 signal, and all these methods are aliases for the Win32 API function
2348 :cfunc:`TerminateProcess`.
2349 (Contributed by Christian Heimes.)
2351 * A new variable in the :mod:`sys` module,
2352 :attr:`float_info`, is an object
2353 containing information about the platform's floating-point support
2354 derived from the :file:`float.h` file. Attributes of this object
2356 :attr:`mant_dig` (number of digits in the mantissa), :attr:`epsilon`
2357 (smallest difference between 1.0 and the next largest value
2358 representable), and several others. (Contributed by Christian Heimes;
2361 Another new variable, :attr:`dont_write_bytecode`, controls whether Python
2362 writes any :file:`.pyc` or :file:`.pyo` files on importing a module.
2363 If this variable is true, the compiled files are not written. The
2364 variable is initially set on start-up by supplying the :option:`-B`
2365 switch to the Python interpreter, or by setting the
2366 :envvar:`PYTHONDONTWRITEBYTECODE` environment variable before
2367 running the interpreter. Python code can subsequently
2368 change the value of this variable to control whether bytecode files
2370 (Contributed by Neal Norwitz and Georg Brandl.)
2372 Information about the command-line arguments supplied to the Python
2373 interpreter is available by reading attributes of a named
2374 tuple available as ``sys.flags``. For example, the :attr:`verbose`
2375 attribute is true if Python
2376 was executed in verbose mode, :attr:`debug` is true in debugging mode, etc.
2377 These attributes are all read-only.
2378 (Contributed by Christian Heimes.)
2380 A new function, :func:`getsizeof`, takes a Python object and returns
2381 the amount of memory used by the object, measured in bytes. Built-in
2382 objects return correct results; third-party extensions may not,
2383 but can define a :meth:`__sizeof__` method to return the
2385 (Contributed by Robert Schuppenies; :issue:`2898`.)
2387 It's now possible to determine the current profiler and tracer functions
2388 by calling :func:`sys.getprofile` and :func:`sys.gettrace`.
2389 (Contributed by Georg Brandl; :issue:`1648`.)
2391 * The :mod:`tarfile` module now supports POSIX.1-2001 (pax) and
2392 POSIX.1-1988 (ustar) format tarfiles, in addition to the GNU tar
2393 format that was already supported. The default format
2394 is GNU tar; specify the ``format`` parameter to open a file
2395 using a different format::
2397 tar = tarfile.open("output.tar", "w", format=tarfile.PAX_FORMAT)
2399 The new ``errors`` parameter lets you specify an error handling
2400 scheme for character conversions: the three standard ways Python can
2401 handle errors ``'strict'``, ``'ignore'``, ``'replace'`` , or the
2402 special value ``'utf-8'``, which replaces bad characters with their
2403 UTF-8 representation. Character conversions occur because the PAX
2404 format supports Unicode filenames, defaulting to UTF-8 encoding.
2406 The :meth:`TarFile.add` method now accepts a ``exclude`` argument that's
2407 a function that can be used to exclude certain filenames from
2409 The function must take a filename and return true if the file
2410 should be excluded or false if it should be archived.
2411 The function is applied to both the name initially passed to :meth:`add`
2412 and to the names of files in recursively-added directories.
2414 (All changes contributed by Lars Gustäbel).
2416 * An optional ``timeout`` parameter was added to the
2417 :class:`telnetlib.Telnet` class constructor, specifying a timeout
2418 measured in seconds. (Added by Facundo Batista.)
2420 * The :class:`tempfile.NamedTemporaryFile` class usually deletes
2421 the temporary file it created when the file is closed. This
2422 behaviour can now be changed by passing ``delete=False`` to the
2423 constructor. (Contributed by Damien Miller; :issue:`1537850`.)
2425 A new class, :class:`SpooledTemporaryFile`, behaves like
2426 a temporary file but stores its data in memory until a maximum size is
2427 exceeded. On reaching that limit, the contents will be written to
2428 an on-disk temporary file. (Contributed by Dustin J. Mitchell.)
2430 The :class:`NamedTemporaryFile` and :class:`SpooledTemporaryFile` classes
2431 both work as context managers, so you can write
2432 ``with tempfile.NamedTemporaryFile() as tmp: ...``.
2433 (Contributed by Alexander Belopolsky; :issue:`2021`.)
2435 * The :mod:`test.test_support` module now contains a
2436 :func:`EnvironmentVarGuard`
2437 context manager that supports temporarily changing environment variables and
2438 automatically restores them to their old values.
2440 Another context manager, :class:`TransientResource`, can surround calls
2441 to resources that may or may not be available; it will catch and
2442 ignore a specified list of exceptions. For example,
2443 a network test may ignore certain failures when connecting to an
2446 with test_support.TransientResource(IOError, errno=errno.ETIMEDOUT):
2447 f = urllib.urlopen('https://sf.net')
2450 (Contributed by Brett Cannon.)
2452 * The :mod:`textwrap` module can now preserve existing whitespace
2453 at the beginnings and ends of the newly-created lines
2454 by specifying ``drop_whitespace=False``
2457 >>> S = """This sentence has a bunch of extra whitespace."""
2458 >>> print textwrap.fill(S, width=15)
2463 >>> print textwrap.fill(S, drop_whitespace=False, width=15)
2470 (Contributed by Dwayne Bailey; :issue:`1581073`.)
2472 * The :mod:`threading` module's :class:`Thread` objects
2473 gained a :meth:`getIdent` method that returns the thread's
2474 identifier, a nonzero integer. (Contributed by Gregory P. Smith;
2477 * The :mod:`timeit` module now accepts callables as well as strings
2478 for the statement being timed and for the setup code.
2479 Two convenience functions were added for creating
2480 :class:`Timer` instances:
2481 ``repeat(stmt, setup, time, repeat, number)`` and
2482 ``timeit(stmt, setup, time, number)`` create an instance and call
2483 the corresponding method. (Contributed by Erik Demaine;
2486 * The :mod:`Tkinter` module now accepts lists and tuples for options,
2487 separating the elements by spaces before passing the resulting value to
2489 (Contributed by Guilherme Polo; :issue:`2906`.)
2491 * The :mod:`turtle` module for turtle graphics was greatly enhanced by
2492 Gregor Lingl. New features in the module include:
2494 * Better animation of turtle movement and rotation.
2495 * Control over turtle movement using the new delay(),
2496 tracer(), and speed() methods.
2497 * The ability to set new shapes for the turtle, and to
2498 define a new coordinate system.
2499 * Turtles now have an undo() method that can roll back actions.
2500 * Simple support for reacting to input events such as mouse and keyboard
2501 activity, making it possible to write simple games.
2502 * A :file:`turtle.cfg` file can be used to customize the starting appearance
2503 of the turtle's screen.
2504 * The module's docstrings can be replaced by new docstrings that have been
2505 translated into another language.
2509 * An optional ``timeout`` parameter was added to the
2510 :func:`urllib.urlopen` function and the
2511 :class:`urllib.ftpwrapper` class constructor, as well as the
2512 :func:`urllib2.urlopen` function. The parameter specifies a timeout
2513 measured in seconds. For example::
2515 >>> u = urllib2.urlopen("http://slow.example.com", timeout=3)
2516 Traceback (most recent call last):
2518 urllib2.URLError: <urlopen error timed out>
2521 (Added by Facundo Batista.)
2523 * The :mod:`warnings` module's :func:`formatwarning` and :func:`showwarning`
2524 gained an optional *line* argument that can be used to supply the
2525 line of source code. (Added as part of :issue:`1631171`, which re-implemented
2526 part of the :mod:`warnings` module in C code.)
2528 * The XML-RPC :class:`SimpleXMLRPCServer` and :class:`DocXMLRPCServer`
2529 classes can now be prevented from immediately opening and binding to
2530 their socket by passing True as the ``bind_and_activate``
2531 constructor parameter. This can be used to modify the instance's
2532 :attr:`allow_reuse_address` attribute before calling the
2533 :meth:`server_bind` and :meth:`server_activate` methods to
2534 open the socket and begin listening for connections.
2535 (Contributed by Peter Parente; :issue:`1599845`.)
2537 :class:`SimpleXMLRPCServer` also has a :attr:`_send_traceback_header`
2538 attribute; if true, the exception and formatted traceback are returned
2539 as HTTP headers "X-Exception" and "X-Traceback". This feature is
2540 for debugging purposes only and should not be used on production servers
2541 because the tracebacks could possibly reveal passwords or other sensitive
2542 information. (Contributed by Alan McIntyre as part of his
2543 project for Google's Summer of Code 2007.)
2545 * The :mod:`xmlrpclib` module no longer automatically converts
2546 :class:`datetime.date` and :class:`datetime.time` to the
2547 :class:`xmlrpclib.DateTime` type; the conversion semantics were
2548 not necessarily correct for all applications. Code using
2549 :mod:`xmlrpclib` should convert :class:`date` and :class:`time`
2550 instances. (:issue:`1330538`) The code can also handle
2551 dates before 1900 (contributed by Ralf Schmitt; :issue:`2014`)
2552 and 64-bit integers represented by using ``<i8>`` in XML-RPC responses
2553 (contributed by Riku Lindblad; :issue:`2985`).
2555 * The :mod:`zipfile` module's :class:`ZipFile` class now has
2556 :meth:`extract` and :meth:`extractall` methods that will unpack
2557 a single file or all the files in the archive to the current directory, or
2558 to a specified directory::
2560 z = zipfile.ZipFile('python-251.zip')
2562 # Unpack a single file, writing it relative to the /tmp directory.
2563 z.extract('Python/sysmodule.c', '/tmp')
2565 # Unpack all the files in the archive.
2568 (Contributed by Alan McIntyre; :issue:`467924`.)
2570 The :meth:`open`, :meth:`read` and :meth:`extract` methods can now
2571 take either a filename or a :class:`ZipInfo` object. This is useful when an
2572 archive accidentally contains a duplicated filename.
2573 (Contributed by Graham Horler; :issue:`1775025`.)
2575 Finally, :mod:`zipfile` now supports using Unicode filenames
2576 for archived files. (Contributed by Alexey Borzenkov; :issue:`1734346`.)
2578 .. ======================================================================
2579 .. whole new modules get described in subsections here
2581 The :mod:`ast` module
2582 ----------------------
2584 The :mod:`ast` module provides an Abstract Syntax Tree representation
2585 of Python code. For Python 2.6, Armin Ronacher contributed a set of
2586 helper functions that perform various common tasks. These will be useful
2587 for HTML templating packages, code analyzers, and similar tools that
2588 process Python code.
2590 The :func:`parse` function takes an expression and returns an AST.
2591 The :func:`dump` function outputs a representation of a tree, suitable
2598 for i in 'abcdefghijklm':
2599 d[i + i] = ord(i) - ord('a') + 1
2606 Module(body=[Assign(targets=[Name(id='d', ctx=Store())],
2607 value=Dict(keys=[], values=[])), For(target=Name(id='i',
2608 ctx=Store()), iter=Str(s='abcdefghijklm'),
2609 body=[Assign(targets=[Subscript(value=Name(id='d', ctx=Load()),
2610 slice=Index(value=BinOp(left=Name(id='i', ctx=Load()), op=Add(),
2611 right=Name(id='i', ctx=Load()))), ctx=Store())],
2612 value=BinOp(left=BinOp(left=Call(func=Name(id='ord', ctx=Load()),
2613 args=[Name(id='i', ctx=Load())], keywords=[], starargs=None,
2614 kwargs=None), op=Sub(), right=Call(func=Name(id='ord',
2615 ctx=Load()), args=[Str(s='a')], keywords=[], starargs=None,
2616 kwargs=None)), op=Add(), right=Num(n=1)))], orelse=[]),
2617 Print(dest=None, values=[Name(id='d', ctx=Load())], nl=True)])
2619 The :func:`literal_eval` method takes a string or an AST
2620 representing a literal expression, one that contains a Python
2621 expression containing only strings, numbers, dictionaries, etc. but no
2622 statements or function calls, and returns the resulting value. If you
2623 need to unserialize an expression but need to worry about security
2624 and can't risk using an :func:`eval` call, :func:`literal_eval` will
2627 >>> literal = '("a", "b", {2:4, 3:8, 1:2})'
2628 >>> print ast.literal_eval(literal)
2629 ('a', 'b', {1: 2, 2: 4, 3: 8})
2630 >>> print ast.literal_eval('"a" + "b"')
2631 Traceback (most recent call last):
2633 ValueError: malformed string
2635 The module also includes :class:`NodeVisitor` and
2636 :class:`NodeTransformer` classes for traversing and modifying an AST,
2637 and functions for common transformations such as changing line
2640 .. ======================================================================
2642 The :mod:`future_builtins` module
2643 --------------------------------------
2645 Python 3.0 makes various changes to the repertoire of built-in
2646 functions, and most of the changes can't be introduced in the Python
2647 2.x series because they would break compatibility.
2648 The :mod:`future_builtins` module provides versions
2649 of these built-in functions that can be imported when writing
2650 3.0-compatible code.
2652 The functions in this module currently include:
2654 * ``ascii(**obj**)``: equivalent to :func:`repr`. In Python 3.0,
2655 :func:`repr` will return a Unicode string, while :func:`ascii` will
2656 return a pure ASCII bytestring.
2658 * ``filter(**predicate**, **iterable**)``,
2659 ``map(**func**, **iterable1**, ...)``: the 3.0 versions
2660 return iterators, differing from the 2.x built-ins that return lists.
2662 * ``hex(**value**)``, ``oct(**value**)``: instead of calling the
2663 :meth:`__hex__` or :meth:`__oct__` methods, these versions will
2664 call the :meth:`__index__` method and convert the result to hexadecimal
2667 .. ======================================================================
2669 The :mod:`json` module
2670 ----------------------
2672 The new :mod:`json` module supports the encoding and decoding of Python types in
2673 JSON (Javascript Object Notation). JSON is a lightweight interchange format
2674 often used in web applications. For more information about JSON, see
2675 http://www.json.org.
2677 :mod:`json` comes with support for decoding and encoding most builtin Python
2678 types. The following example encodes and decodes a dictionary::
2681 >>> data = {"spam" : "foo", "parrot" : 42}
2682 >>> in_json = json.dumps(data) # Encode the data
2684 '{"parrot": 42, "spam": "foo"}'
2685 >>> json.loads(in_json) # Decode into a Python object
2686 {"spam" : "foo", "parrot" : 42}
2688 It is also possible to write your own decoders and encoders to support more
2689 types. Pretty-printing of the JSON strings is also supported.
2691 :mod:`json` (originally called simplejson) was written by Bob Ippolito.
2694 .. ======================================================================
2696 plistlib: A Property-List Parser
2697 --------------------------------------------------
2699 A commonly-used format on MacOS X is the ``.plist`` format,
2700 which stores basic data types (numbers, strings, lists,
2701 and dictionaries) and serializes them into an XML-based format.
2702 (It's a lot like the XML-RPC serialization of data types.)
2704 Despite being primarily used on MacOS X, the format
2705 has nothing Mac-specific about it and the Python implementation works
2706 on any platform that Python supports, so the :mod:`plistlib` module
2707 has been promoted to the standard library.
2709 Using the module is simple::
2715 # Create data structure
2716 data_struct = dict(lastAccessed=datetime.datetime.now(),
2718 categories=('Personal', 'Shared', 'Private'))
2720 # Create string containing XML.
2721 plist_str = plistlib.writePlistToString(data_struct)
2722 new_struct = plistlib.readPlistFromString(plist_str)
2726 # Write data structure to a file and read it back.
2727 plistlib.writePlist(data_struct, '/tmp/customizations.plist')
2728 new_struct = plistlib.readPlist('/tmp/customizations.plist')
2730 # read/writePlist accepts file-like objects as well as paths.
2731 plistlib.writePlist(data_struct, sys.stdout)
2733 .. ======================================================================
2736 --------------------------------------------------
2738 Thomas Heller continued to maintain and enhance the
2739 :mod:`ctypes` module.
2741 :mod:`ctypes` now supports a :class:`c_bool` datatype
2742 that represents the C99 ``bool`` type. (Contributed by David Remahl;
2745 The :mod:`ctypes` string, buffer and array types have improved
2746 support for extended slicing syntax,
2747 where various combinations of ``(start, stop, step)`` are supplied.
2748 (Implemented by Thomas Wouters.)
2752 A new calling convention tells :mod:`ctypes` to clear the ``errno`` or
2753 Win32 LastError variables at the outset of each wrapped call.
2754 (Implemented by Thomas Heller; :issue:`1798`.)
2756 For the Unix ``errno`` variable: when creating a wrapped function,
2757 you can supply ``use_errno=True`` as a keyword parameter
2758 to the :func:`DLL` function
2759 and then call the module-level methods :meth:`set_errno`
2760 and :meth:`get_errno` to set and retrieve the error value.
2762 The Win32 LastError variable is supported similarly by
2763 the :func:`DLL`, :func:`OleDLL`, and :func:`WinDLL` functions.
2764 You supply ``use_last_error=True`` as a keyword parameter
2765 and then call the module-level methods :meth:`set_last_error`
2766 and :meth:`get_last_error`.
2768 The :func:`byref` function, used to retrieve a pointer to a ctypes
2769 instance, now has an optional **offset** parameter that is a byte
2770 count that will be added to the returned pointer.
2772 .. ======================================================================
2774 Improved SSL Support
2775 --------------------------------------------------
2777 Bill Janssen made extensive improvements to Python 2.6's support for
2778 the Secure Sockets Layer by adding a new module, :mod:`ssl`, on top of
2779 the `OpenSSL <http://www.openssl.org/>`__ library. This new module
2780 provides more control over the protocol negotiated, the X.509
2781 certificates used, and has better support for writing SSL servers (as
2782 opposed to clients) in Python. The existing SSL support in the
2783 :mod:`socket` module hasn't been removed and continues to work,
2784 though it will be removed in Python 3.0.
2786 To use the new module, first you must create a TCP connection in the
2787 usual way and then pass it to the :func:`ssl.wrap_socket` function.
2788 It's possible to specify whether a certificate is required, and to
2789 obtain certificate info by calling the :meth:`getpeercert` method.
2793 The documentation for the :mod:`ssl` module.
2795 .. ======================================================================
2798 Build and C API Changes
2799 =======================
2801 Changes to Python's build process and to the C API include:
2803 * Python 2.6 can be built with Microsoft Visual Studio 2008.
2804 See the :file:`PCbuild9` directory for the build files.
2805 (Implemented by Christian Heimes.)
2807 * On MacOS X, Python 2.6 can be compiled as a 4-way universal build.
2808 The :program:`configure` script
2809 can take a :option:`--with-universal-archs=[32-bit|64-bit|all]`
2810 switch, controlling whether the binaries are built for 32-bit
2811 architectures (x86, PowerPC), 64-bit (x86-64 and PPC-64), or both.
2812 (Contributed by Ronald Oussoren.)
2814 * Python now can only be compiled with C89 compilers (after 19
2815 years!). This means that the Python source tree can now drop its
2816 own implementations of :cfunc:`memmove` and :cfunc:`strerror`, which
2817 are in the C89 standard library.
2819 * The BerkeleyDB module now has a C API object, available as
2820 ``bsddb.db.api``. This object can be used by other C extensions
2821 that wish to use the :mod:`bsddb` module for their own purposes.
2822 (Contributed by Duncan Grisby; :issue:`1551895`.)
2824 * The new buffer interface, previously described in
2825 `the PEP 3118 section <#pep-3118-revised-buffer-protocol>`__,
2826 adds :cfunc:`PyObject_GetBuffer` and :cfunc:`PyObject_ReleaseBuffer`,
2827 as well as a few other functions.
2829 * Python's use of the C stdio library is now thread-safe, or at least
2830 as thread-safe as the underlying library is. A long-standing potential
2831 bug occurred if one thread closed a file object while another thread
2832 was reading from or writing to the object. In 2.6 file objects
2833 have a reference count, manipulated by the
2834 :cfunc:`PyFile_IncUseCount` and :cfunc:`PyFile_DecUseCount`
2835 functions. File objects can't be closed unless the reference count
2836 is zero. :cfunc:`PyFile_IncUseCount` should be called while the GIL
2837 is still held, before carrying out an I/O operation using the
2838 ``FILE *`` pointer, and :cfunc:`PyFile_DecUseCount` should be called
2839 immediately after the GIL is re-acquired.
2840 (Contributed by Antoine Pitrou and Gregory P. Smith.)
2842 * Importing modules simultaneously in two different threads no longer
2843 deadlocks; it will now raise an :exc:`ImportError`. A new API
2844 function, :cfunc:`PyImport_ImportModuleNoBlock`, will look for a
2845 module in ``sys.modules`` first, then try to import it after
2846 acquiring an import lock. If the import lock is held by another
2847 thread, the :exc:`ImportError` is raised.
2848 (Contributed by Christian Heimes.)
2850 * Several functions return information about the platform's
2851 floating-point support. :cfunc:`PyFloat_GetMax` returns
2852 the maximum representable floating point value,
2853 and :cfunc:`PyFloat_GetMin` returns the minimum
2854 positive value. :cfunc:`PyFloat_GetInfo` returns a dictionary
2855 containing more information from the :file:`float.h` file, such as
2856 ``"mant_dig"`` (number of digits in the mantissa), ``"epsilon"``
2857 (smallest difference between 1.0 and the next largest value
2858 representable), and several others.
2859 (Contributed by Christian Heimes; :issue:`1534`.)
2861 * C functions and methods that use
2862 :cfunc:`PyComplex_AsCComplex` will now accept arguments that
2863 have a :meth:`__complex__` method. In particular, the functions in the
2864 :mod:`cmath` module will now accept objects with this method.
2865 This is a backport of a Python 3.0 change.
2866 (Contributed by Mark Dickinson; :issue:`1675423`.)
2868 * Python's C API now includes two functions for case-insensitive string
2869 comparisons, ``PyOS_stricmp(char*, char*)``
2870 and ``PyOS_strnicmp(char*, char*, Py_ssize_t)``.
2871 (Contributed by Christian Heimes; :issue:`1635`.)
2873 * Many C extensions define their own little macro for adding
2874 integers and strings to the module's dictionary in the
2875 ``init*`` function. Python 2.6 finally defines standard macros
2876 for adding values to a module, :cmacro:`PyModule_AddStringMacro`
2877 and :cmacro:`PyModule_AddIntMacro()`. (Contributed by
2880 * Some macros were renamed in both 3.0 and 2.6 to make it clearer that
2882 not functions. :cmacro:`Py_Size()` became :cmacro:`Py_SIZE()`,
2883 :cmacro:`Py_Type()` became :cmacro:`Py_TYPE()`, and
2884 :cmacro:`Py_Refcnt()` became :cmacro:`Py_REFCNT()`.
2885 The mixed-case macros are still available
2886 in Python 2.6 for backward compatibility.
2889 * Distutils now places C extensions it builds in a
2890 different directory when running on a debug version of Python.
2891 (Contributed by Collin Winter; :issue:`1530959`.)
2893 * Several basic data types, such as integers and strings, maintain
2894 internal free lists of objects that can be re-used. The data
2895 structures for these free lists now follow a naming convention: the
2896 variable is always named ``free_list``, the counter is always named
2897 ``numfree``, and a macro :cmacro:`Py<typename>_MAXFREELIST` is
2900 * A new Makefile target, "make check", prepares the Python source tree
2901 for making a patch: it fixes trailing whitespace in all modified
2902 ``.py`` files, checks whether the documentation has been changed,
2903 and reports whether the :file:`Misc/ACKS` and :file:`Misc/NEWS` files
2905 (Contributed by Brett Cannon.)
2907 Another new target, "make profile-opt", compiles a Python binary
2908 using GCC's profile-guided optimization. It compiles Python with
2909 profiling enabled, runs the test suite to obtain a set of profiling
2910 results, and then compiles using these results for optimization.
2911 (Contributed by Gregory P. Smith.)
2913 .. ======================================================================
2915 Port-Specific Changes: Windows
2916 -----------------------------------
2918 * The support for Windows 95, 98, ME and NT4 has been dropped.
2919 Python 2.6 requires at least Windows 2000 SP4.
2921 * The :mod:`msvcrt` module now supports
2922 both the normal and wide char variants of the console I/O
2923 API. The :func:`getwch` function reads a keypress and returns a Unicode
2924 value, as does the :func:`getwche` function. The :func:`putwch` function
2925 takes a Unicode character and writes it to the console.
2926 (Contributed by Christian Heimes.)
2928 * :func:`os.path.expandvars` will now expand environment variables
2929 in the form "%var%", and "~user" will be expanded into the
2930 user's home directory path. (Contributed by Josiah Carlson.)
2932 * The :mod:`socket` module's socket objects now have an
2933 :meth:`ioctl` method that provides a limited interface to the
2934 :cfunc:`WSAIoctl` system interface.
2936 * The :mod:`_winreg` module now has a function,
2937 :func:`ExpandEnvironmentStrings`,
2938 that expands environment variable references such as ``%NAME%``
2939 in an input string. The handle objects provided by this
2940 module now support the context protocol, so they can be used
2941 in :keyword:`with` statements. (Contributed by Christian Heimes.)
2943 :mod:`_winreg` also has better support for x64 systems,
2944 exposing the :func:`DisableReflectionKey`, :func:`EnableReflectionKey`,
2945 and :func:`QueryReflectionKey` functions, which enable and disable
2946 registry reflection for 32-bit processes running on 64-bit systems.
2949 * The :mod:`msilib` module's :class:`Record` object
2950 gained :meth:`GetInteger` and :meth:`GetString` methods that
2951 return field values as an integer or a string.
2952 (Contributed by Floris Bruynooghe; :issue:`2125`.)
2954 * The new default compiler on Windows is Visual Studio 2008 (VS 9.0). The
2955 build directories for Visual Studio 2003 (VS7.1) and 2005 (VS8.0)
2956 were moved into the PC/ directory. The new PCbuild directory supports
2957 cross compilation for X64, debug builds and Profile Guided Optimization
2958 (PGO). PGO builds are roughly 10% faster than normal builds.
2959 (Contributed by Christian Heimes with help from Amaury Forgeot d'Arc and
2962 .. ======================================================================
2964 Port-Specific Changes: MacOS X
2965 -----------------------------------
2967 * When compiling a framework build of Python, you can now specify the
2968 framework name to be used by providing the
2969 :option:`--with-framework-name=` option to the
2970 :program:`configure` script.
2972 .. ======================================================================
2977 Other Changes and Fixes
2978 =======================
2980 As usual, there were a bunch of other improvements and bugfixes
2981 scattered throughout the source tree. A search through the change
2982 logs finds there were XXX patches applied and YYY bugs fixed between
2983 Python 2.5 and 2.6. Both figures are likely to be underestimates.
2985 Some of the more notable changes are:
2987 * It's now possible to prevent Python from writing any :file:`.pyc`
2988 or :file:`.pyo` files by either supplying the :option:`-B` switch
2989 or setting the :envvar:`PYTHONDONTWRITEBYTECODE` environment variable
2990 to any non-empty string when running the Python interpreter. These
2991 are also used to set the :data:`sys.dont_write_bytecode` attribute;
2992 Python code can change this variable to control whether bytecode
2993 files are subsequently written.
2994 (Contributed by Neal Norwitz and Georg Brandl.)
2996 .. ======================================================================
2999 Porting to Python 2.6
3000 =====================
3002 This section lists previously described changes and other bugfixes
3003 that may require changes to your code:
3005 * The :meth:`__init__` method of :class:`collections.deque`
3006 now clears any existing contents of the deque
3007 before adding elements from the iterable. This change makes the
3008 behavior match that of ``list.__init__()``.
3010 * The :class:`Decimal` constructor now accepts leading and trailing
3011 whitespace when passed a string. Previously it would raise an
3012 :exc:`InvalidOperation` exception. On the other hand, the
3013 :meth:`create_decimal` method of :class:`Context` objects now
3014 explicitly disallows extra whitespace, raising a
3015 :exc:`ConversionSyntax` exception.
3017 * Due to an implementation accident, if you passed a file path to
3018 the built-in :func:`__import__` function, it would actually import
3019 the specified file. This was never intended to work, however, and
3020 the implementation now explicitly checks for this case and raises
3021 an :exc:`ImportError`.
3023 * C API: the :cfunc:`PyImport_Import` and :cfunc:`PyImport_ImportModule`
3024 functions now default to absolute imports, not relative imports.
3025 This will affect C extensions that import other modules.
3027 * The :mod:`socket` module exception :exc:`socket.error` now inherits
3028 from :exc:`IOError`. Previously it wasn't a subclass of
3029 :exc:`StandardError` but now it is, through :exc:`IOError`.
3030 (Implemented by Gregory P. Smith; :issue:`1706815`.)
3032 * The :mod:`xmlrpclib` module no longer automatically converts
3033 :class:`datetime.date` and :class:`datetime.time` to the
3034 :class:`xmlrpclib.DateTime` type; the conversion semantics were
3035 not necessarily correct for all applications. Code using
3036 :mod:`xmlrpclib` should convert :class:`date` and :class:`time`
3037 instances. (:issue:`1330538`)
3039 * (3.0-warning mode) The :class:`Exception` class now warns
3040 when accessed using slicing or index access; having
3041 :class:`Exception` behave like a tuple is being phased out.
3043 * (3.0-warning mode) inequality comparisons between two dictionaries
3044 or two objects that don't implement comparison methods are reported
3045 as warnings. ``dict1 == dict2`` still works, but ``dict1 < dict2``
3046 is being phased out.
3048 Comparisons between cells, which are an implementation detail of Python's
3049 scoping rules, also cause warnings because such comparisons are forbidden
3052 .. ======================================================================
3060 The author would like to thank the following people for offering suggestions,
3061 corrections and assistance with various drafts of this article:
3062 Georg Brandl, Jim Jewett.