Guido van Rossum | 715287f | 2008-12-02 22:34:15 +0000 | [diff] [blame] | 1 | .. _whats-new-in-2.6: |
| 2 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | **************************** |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 4 | What's New in Python 2.6 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 5 | **************************** |
| 6 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 7 | .. XXX add trademark info for Apple, Microsoft, SourceForge. |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 8 | |
Benjamin Peterson | dcc1e11 | 2008-09-03 22:22:18 +0000 | [diff] [blame] | 9 | :Author: A.M. Kuchling (amk at amk.ca) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 11 | .. $Id$ |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 12 | Rules for maintenance: |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 13 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 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. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 17 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 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. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 21 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 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.) |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 27 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 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 |
| 30 | section. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 31 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 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. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 36 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 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). |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 39 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 40 | * Credit the author of a patch or bugfix. Just the name is |
| 41 | sufficient; the e-mail address isn't necessary. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 42 | |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 43 | * It's helpful to add the bug/patch number in a parenthetical comment. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 44 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 45 | XXX Describe the transmogrify() function added to the socket |
| 46 | module. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 47 | (Contributed by P.Y. Developer; :issue:`12345`.) |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 48 | |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 49 | This saves the maintainer some effort going through the SVN logs |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 50 | when researching a change. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 51 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 52 | This article explains the new features in Python 2.6, released on October 1 |
| 53 | 2008. The release schedule is described in :pep:`361`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 55 | The major theme of Python 2.6 is preparing the migration path to |
| 56 | Python 3.0, a major redesign of the language. Whenever possible, |
| 57 | Python 2.6 incorporates new features and syntax from 3.0 while |
| 58 | remaining compatible with existing code by not removing older features |
| 59 | or syntax. When it's not possible to do that, Python 2.6 tries to do |
| 60 | what it can, adding compatibility functions in a |
| 61 | :mod:`future_builtins` module and a :option:`-3` switch to warn about |
| 62 | usages that will become unsupported in 3.0. |
| 63 | |
| 64 | Some significant new packages have been added to the standard library, |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 65 | such as the :mod:`multiprocessing` and :mod:`json` modules, but |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 66 | there aren't many new features that aren't related to Python 3.0 in |
| 67 | some way. |
| 68 | |
| 69 | Python 2.6 also sees a number of improvements and bugfixes throughout |
| 70 | the source. A search through the change logs finds there were 259 |
| 71 | patches applied and 612 bugs fixed between Python 2.5 and 2.6. Both |
| 72 | figures are likely to be underestimates. |
| 73 | |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 74 | This article doesn't attempt to provide a complete specification of |
| 75 | the new features, but instead provides a convenient overview. For |
| 76 | full details, you should refer to the documentation for Python 2.6. If |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 77 | you want to understand the rationale for the design and |
| 78 | implementation, refer to the PEP for a particular new feature. |
| 79 | Whenever possible, "What's New in Python" links to the bug/patch item |
| 80 | for each change. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 81 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 82 | .. Compare with previous release in 2 - 3 sentences here. |
| 83 | add hyperlink when the documentation becomes available online. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 85 | .. ======================================================================== |
| 86 | .. Large, PEP-level features and changes should be described here. |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 87 | .. ======================================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 88 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 89 | Python 3.0 |
| 90 | ================ |
| 91 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 92 | The development cycle for Python versions 2.6 and 3.0 was |
| 93 | synchronized, with the alpha and beta releases for both versions being |
| 94 | made on the same days. The development of 3.0 has influenced many |
| 95 | features in 2.6. |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 96 | |
| 97 | Python 3.0 is a far-ranging redesign of Python that breaks |
| 98 | compatibility with the 2.x series. This means that existing Python |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 99 | code will need some conversion in order to run on |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 100 | Python 3.0. However, not all the changes in 3.0 necessarily break |
| 101 | compatibility. In cases where new features won't cause existing code |
| 102 | to break, they've been backported to 2.6 and are described in this |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 103 | document in the appropriate place. Some of the 3.0-derived features |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 104 | are: |
| 105 | |
| 106 | * A :meth:`__complex__` method for converting objects to a complex number. |
| 107 | * Alternate syntax for catching exceptions: ``except TypeError as exc``. |
| 108 | * The addition of :func:`functools.reduce` as a synonym for the built-in |
| 109 | :func:`reduce` function. |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 110 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 111 | Python 3.0 adds several new built-in functions and changes the |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 112 | semantics of some existing builtins. Functions that are new in 3.0 |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 113 | such as :func:`bin` have simply been added to Python 2.6, but existing |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 114 | builtins haven't been changed; instead, the :mod:`future_builtins` |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 115 | module has versions with the new 3.0 semantics. Code written to be |
| 116 | compatible with 3.0 can do ``from future_builtins import hex, map`` as |
| 117 | necessary. |
| 118 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 119 | A new command-line switch, :option:`-3`, enables warnings |
| 120 | about features that will be removed in Python 3.0. You can run code |
| 121 | with this switch to see how much work will be necessary to port |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 122 | code to 3.0. The value of this switch is available |
| 123 | to Python code as the boolean variable :data:`sys.py3kwarning`, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 124 | and to C extension code as :c:data:`Py_Py3kWarningFlag`. |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 125 | |
| 126 | .. seealso:: |
| 127 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 128 | The 3xxx series of PEPs, which contains proposals for Python 3.0. |
| 129 | :pep:`3000` describes the development process for Python 3.0. |
| 130 | Start with :pep:`3100` that describes the general goals for Python |
| 131 | 3.0, and then explore the higher-numbered PEPS that propose |
| 132 | specific features. |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 133 | |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 134 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 135 | Changes to the Development Process |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 136 | ================================================== |
| 137 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 138 | While 2.6 was being developed, the Python development process |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 139 | underwent two significant changes: we switched from SourceForge's |
| 140 | issue tracker to a customized Roundup installation, and the |
| 141 | documentation was converted from LaTeX to reStructuredText. |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 142 | |
| 143 | |
| 144 | New Issue Tracker: Roundup |
| 145 | -------------------------------------------------- |
| 146 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 147 | For a long time, the Python developers had been growing increasingly |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 148 | annoyed by SourceForge's bug tracker. SourceForge's hosted solution |
| 149 | doesn't permit much customization; for example, it wasn't possible to |
| 150 | customize the life cycle of issues. |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 151 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 152 | The infrastructure committee of the Python Software Foundation |
| 153 | therefore posted a call for issue trackers, asking volunteers to set |
| 154 | up different products and import some of the bugs and patches from |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 155 | SourceForge. Four different trackers were examined: `Jira |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 156 | <http://www.atlassian.com/software/jira/>`__, |
| 157 | `Launchpad <http://www.launchpad.net>`__, |
| 158 | `Roundup <http://roundup.sourceforge.net/>`__, and |
| 159 | `Trac <http://trac.edgewall.org/>`__. |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 160 | The committee eventually settled on Jira |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 161 | and Roundup as the two candidates. Jira is a commercial product that |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 162 | offers no-cost hosted instances to free-software projects; Roundup |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 163 | is an open-source project that requires volunteers |
| 164 | to administer it and a server to host it. |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 165 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 166 | After posting a call for volunteers, a new Roundup installation was |
| 167 | set up at http://bugs.python.org. One installation of Roundup can |
| 168 | host multiple trackers, and this server now also hosts issue trackers |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 169 | for Jython and for the Python web site. It will surely find |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 170 | other uses in the future. Where possible, |
| 171 | this edition of "What's New in Python" links to the bug/patch |
| 172 | item for each change. |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 173 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 174 | Hosting of the Python bug tracker is kindly provided by |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 175 | `Upfront Systems <http://www.upfrontsystems.co.za/>`__ |
Antoine Pitrou | fbd4f80 | 2012-08-11 16:51:50 +0200 | [diff] [blame] | 176 | of Stellenbosch, South Africa. Martin von Löwis put a |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 177 | lot of effort into importing existing bugs and patches from |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 178 | SourceForge; his scripts for this import operation are at |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 179 | http://svn.python.org/view/tracker/importer/ and may be useful to |
Benjamin Peterson | 206e307 | 2008-10-19 14:07:49 +0000 | [diff] [blame] | 180 | other projects wishing to move from SourceForge to Roundup. |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 181 | |
| 182 | .. seealso:: |
| 183 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 184 | http://bugs.python.org |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 185 | The Python bug tracker. |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 186 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 187 | http://bugs.jython.org: |
| 188 | The Jython bug tracker. |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 189 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 190 | http://roundup.sourceforge.net/ |
| 191 | Roundup downloads and documentation. |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 192 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 193 | http://svn.python.org/view/tracker/importer/ |
Antoine Pitrou | fbd4f80 | 2012-08-11 16:51:50 +0200 | [diff] [blame] | 194 | Martin von Löwis's conversion scripts. |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 195 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 196 | New Documentation Format: reStructuredText Using Sphinx |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 197 | ----------------------------------------------------------- |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 198 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 199 | The Python documentation was written using LaTeX since the project |
| 200 | started around 1989. In the 1980s and early 1990s, most documentation |
| 201 | was printed out for later study, not viewed online. LaTeX was widely |
| 202 | used because it provided attractive printed output while remaining |
Benjamin Peterson | dcc1e11 | 2008-09-03 22:22:18 +0000 | [diff] [blame] | 203 | straightforward to write once the basic rules of the markup were |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 204 | learned. |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 205 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 206 | Today LaTeX is still used for writing publications destined for |
| 207 | printing, but the landscape for programming tools has shifted. We no |
| 208 | longer print out reams of documentation; instead, we browse through it |
| 209 | online and HTML has become the most important format to support. |
| 210 | Unfortunately, converting LaTeX to HTML is fairly complicated and Fred |
| 211 | L. Drake Jr., the long-time Python documentation editor, spent a lot |
| 212 | of time maintaining the conversion process. Occasionally people would |
| 213 | suggest converting the documentation into SGML and later XML, but |
| 214 | performing a good conversion is a major task and no one ever committed |
| 215 | the time required to finish the job. |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 216 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 217 | During the 2.6 development cycle, Georg Brandl put a lot of effort |
| 218 | into building a new toolchain for processing the documentation. The |
| 219 | resulting package is called Sphinx, and is available from |
| 220 | http://sphinx.pocoo.org/. |
| 221 | |
| 222 | Sphinx concentrates on HTML output, producing attractively styled and |
| 223 | modern HTML; printed output is still supported through conversion to |
| 224 | LaTeX. The input format is reStructuredText, a markup syntax |
| 225 | supporting custom extensions and directives that is commonly used in |
| 226 | the Python community. |
| 227 | |
| 228 | Sphinx is a standalone package that can be used for writing, and |
| 229 | almost two dozen other projects |
| 230 | (`listed on the Sphinx web site <http://sphinx.pocoo.org/examples.html>`__) |
| 231 | have adopted Sphinx as their documentation tool. |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 232 | |
| 233 | .. seealso:: |
| 234 | |
Sandro Tosi | 515687a | 2012-01-14 22:23:27 +0100 | [diff] [blame] | 235 | `Documenting Python <http://docs.python.org/devguide/documenting.html>`__ |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 236 | Describes how to write for Python's documentation. |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 237 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 238 | `Sphinx <http://sphinx.pocoo.org/>`__ |
| 239 | Documentation and code for the Sphinx toolchain. |
| 240 | |
| 241 | `Docutils <http://docutils.sf.net>`__ |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 242 | The underlying reStructuredText parser and toolset. |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 243 | |
| 244 | |
Guido van Rossum | 715287f | 2008-12-02 22:34:15 +0000 | [diff] [blame] | 245 | .. _pep-0343: |
| 246 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 247 | PEP 343: The 'with' statement |
| 248 | ============================= |
| 249 | |
| 250 | The previous version, Python 2.5, added the ':keyword:`with`' |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 251 | statement as an optional feature, to be enabled by a ``from __future__ |
Guido van Rossum | b00324f | 2007-12-04 01:13:14 +0000 | [diff] [blame] | 252 | import with_statement`` directive. In 2.6 the statement no longer needs to |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 253 | be specially enabled; this means that :keyword:`with` is now always a |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 254 | keyword. The rest of this section is a copy of the corresponding |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 255 | section from the "What's New in Python 2.5" document; if you're |
| 256 | familiar with the ':keyword:`with`' statement |
| 257 | from Python 2.5, you can skip this section. |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 258 | |
| 259 | The ':keyword:`with`' statement clarifies code that previously would use |
| 260 | ``try...finally`` blocks to ensure that clean-up code is executed. In this |
| 261 | section, I'll discuss the statement as it will commonly be used. In the next |
| 262 | section, I'll examine the implementation details and show how to write objects |
| 263 | for use with this statement. |
| 264 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 265 | The ':keyword:`with`' statement is a control-flow structure whose basic |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 266 | structure is:: |
| 267 | |
| 268 | with expression [as variable]: |
| 269 | with-block |
| 270 | |
| 271 | The expression is evaluated, and it should result in an object that supports the |
| 272 | context management protocol (that is, has :meth:`__enter__` and :meth:`__exit__` |
Benjamin Peterson | e0124bd | 2009-03-09 21:04:33 +0000 | [diff] [blame] | 273 | methods). |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 274 | |
| 275 | The object's :meth:`__enter__` is called before *with-block* is executed and |
| 276 | therefore can run set-up code. It also may return a value that is bound to the |
| 277 | name *variable*, if given. (Note carefully that *variable* is *not* assigned |
| 278 | the result of *expression*.) |
| 279 | |
| 280 | After execution of the *with-block* is finished, the object's :meth:`__exit__` |
| 281 | method is called, even if the block raised an exception, and can therefore run |
| 282 | clean-up code. |
| 283 | |
| 284 | Some standard Python objects now support the context management protocol and can |
| 285 | be used with the ':keyword:`with`' statement. File objects are one example:: |
| 286 | |
| 287 | with open('/etc/passwd', 'r') as f: |
| 288 | for line in f: |
| 289 | print line |
| 290 | ... more processing code ... |
| 291 | |
| 292 | After this statement has executed, the file object in *f* will have been |
| 293 | automatically closed, even if the :keyword:`for` loop raised an exception part- |
| 294 | way through the block. |
| 295 | |
| 296 | .. note:: |
| 297 | |
| 298 | In this case, *f* is the same object created by :func:`open`, because |
| 299 | :meth:`file.__enter__` returns *self*. |
| 300 | |
| 301 | The :mod:`threading` module's locks and condition variables also support the |
| 302 | ':keyword:`with`' statement:: |
| 303 | |
| 304 | lock = threading.Lock() |
| 305 | with lock: |
| 306 | # Critical section of code |
| 307 | ... |
| 308 | |
| 309 | The lock is acquired before the block is executed and always released once the |
| 310 | block is complete. |
| 311 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 312 | The :func:`localcontext` function in the :mod:`decimal` module makes it easy |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 313 | to save and restore the current decimal context, which encapsulates the desired |
| 314 | precision and rounding characteristics for computations:: |
| 315 | |
| 316 | from decimal import Decimal, Context, localcontext |
| 317 | |
| 318 | # Displays with default precision of 28 digits |
| 319 | v = Decimal('578') |
| 320 | print v.sqrt() |
| 321 | |
| 322 | with localcontext(Context(prec=16)): |
| 323 | # All code in this block uses a precision of 16 digits. |
| 324 | # The original context is restored on exiting the block. |
| 325 | print v.sqrt() |
| 326 | |
| 327 | |
| 328 | .. _new-26-context-managers: |
| 329 | |
| 330 | Writing Context Managers |
| 331 | ------------------------ |
| 332 | |
| 333 | Under the hood, the ':keyword:`with`' statement is fairly complicated. Most |
| 334 | people will only use ':keyword:`with`' in company with existing objects and |
| 335 | don't need to know these details, so you can skip the rest of this section if |
| 336 | you like. Authors of new objects will need to understand the details of the |
| 337 | underlying implementation and should keep reading. |
| 338 | |
| 339 | A high-level explanation of the context management protocol is: |
| 340 | |
| 341 | * The expression is evaluated and should result in an object called a "context |
| 342 | manager". The context manager must have :meth:`__enter__` and :meth:`__exit__` |
| 343 | methods. |
| 344 | |
| 345 | * The context manager's :meth:`__enter__` method is called. The value returned |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 346 | is assigned to *VAR*. If no ``as VAR`` clause is present, the value is simply |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 347 | discarded. |
| 348 | |
| 349 | * The code in *BLOCK* is executed. |
| 350 | |
Georg Brandl | c0e22b7 | 2010-03-14 10:51:01 +0000 | [diff] [blame] | 351 | * If *BLOCK* raises an exception, the context manager's :meth:`__exit__` method |
| 352 | is called with three arguments, the exception details (``type, value, traceback``, |
| 353 | the same values returned by :func:`sys.exc_info`, which can also be ``None`` |
| 354 | if no exception occurred). The method's return value controls whether an exception |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 355 | is re-raised: any false value re-raises the exception, and ``True`` will result |
| 356 | in suppressing it. You'll only rarely want to suppress the exception, because |
| 357 | if you do the author of the code containing the ':keyword:`with`' statement will |
| 358 | never realize anything went wrong. |
| 359 | |
| 360 | * If *BLOCK* didn't raise an exception, the :meth:`__exit__` method is still |
| 361 | called, but *type*, *value*, and *traceback* are all ``None``. |
| 362 | |
| 363 | Let's think through an example. I won't present detailed code but will only |
| 364 | sketch the methods necessary for a database that supports transactions. |
| 365 | |
| 366 | (For people unfamiliar with database terminology: a set of changes to the |
| 367 | database are grouped into a transaction. Transactions can be either committed, |
| 368 | meaning that all the changes are written into the database, or rolled back, |
| 369 | meaning that the changes are all discarded and the database is unchanged. See |
| 370 | any database textbook for more information.) |
| 371 | |
| 372 | Let's assume there's an object representing a database connection. Our goal will |
| 373 | be to let the user write code like this:: |
| 374 | |
| 375 | db_connection = DatabaseConnection() |
| 376 | with db_connection as cursor: |
| 377 | cursor.execute('insert into ...') |
| 378 | cursor.execute('delete from ...') |
| 379 | # ... more operations ... |
| 380 | |
| 381 | The transaction should be committed if the code in the block runs flawlessly or |
| 382 | rolled back if there's an exception. Here's the basic interface for |
| 383 | :class:`DatabaseConnection` that I'll assume:: |
| 384 | |
| 385 | class DatabaseConnection: |
| 386 | # Database interface |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 387 | def cursor(self): |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 388 | "Returns a cursor object and starts a new transaction" |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 389 | def commit(self): |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 390 | "Commits current transaction" |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 391 | def rollback(self): |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 392 | "Rolls back current transaction" |
| 393 | |
| 394 | The :meth:`__enter__` method is pretty easy, having only to start a new |
| 395 | transaction. For this application the resulting cursor object would be a useful |
| 396 | result, so the method will return it. The user can then add ``as cursor`` to |
| 397 | their ':keyword:`with`' statement to bind the cursor to a variable name. :: |
| 398 | |
| 399 | class DatabaseConnection: |
| 400 | ... |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 401 | def __enter__(self): |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 402 | # Code to start a new transaction |
| 403 | cursor = self.cursor() |
| 404 | return cursor |
| 405 | |
| 406 | The :meth:`__exit__` method is the most complicated because it's where most of |
| 407 | the work has to be done. The method has to check if an exception occurred. If |
| 408 | there was no exception, the transaction is committed. The transaction is rolled |
| 409 | back if there was an exception. |
| 410 | |
| 411 | In the code below, execution will just fall off the end of the function, |
| 412 | returning the default value of ``None``. ``None`` is false, so the exception |
| 413 | will be re-raised automatically. If you wished, you could be more explicit and |
| 414 | add a :keyword:`return` statement at the marked location. :: |
| 415 | |
| 416 | class DatabaseConnection: |
| 417 | ... |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 418 | def __exit__(self, type, value, tb): |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 419 | if tb is None: |
| 420 | # No exception, so commit |
| 421 | self.commit() |
| 422 | else: |
| 423 | # Exception occurred, so rollback. |
| 424 | self.rollback() |
| 425 | # return False |
| 426 | |
| 427 | |
Guido van Rossum | 715287f | 2008-12-02 22:34:15 +0000 | [diff] [blame] | 428 | .. _new-module-contextlib: |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 429 | |
| 430 | The contextlib module |
| 431 | --------------------- |
| 432 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 433 | The :mod:`contextlib` module provides some functions and a decorator that |
| 434 | are useful when writing objects for use with the ':keyword:`with`' statement. |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 435 | |
| 436 | The decorator is called :func:`contextmanager`, and lets you write a single |
| 437 | generator function instead of defining a new class. The generator should yield |
| 438 | exactly one value. The code up to the :keyword:`yield` will be executed as the |
| 439 | :meth:`__enter__` method, and the value yielded will be the method's return |
| 440 | value that will get bound to the variable in the ':keyword:`with`' statement's |
| 441 | :keyword:`as` clause, if any. The code after the :keyword:`yield` will be |
| 442 | executed in the :meth:`__exit__` method. Any exception raised in the block will |
| 443 | be raised by the :keyword:`yield` statement. |
| 444 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 445 | Using this decorator, our database example from the previous section |
| 446 | could be written as:: |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 447 | |
| 448 | from contextlib import contextmanager |
| 449 | |
| 450 | @contextmanager |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 451 | def db_transaction(connection): |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 452 | cursor = connection.cursor() |
| 453 | try: |
| 454 | yield cursor |
| 455 | except: |
| 456 | connection.rollback() |
| 457 | raise |
| 458 | else: |
| 459 | connection.commit() |
| 460 | |
| 461 | db = DatabaseConnection() |
| 462 | with db_transaction(db) as cursor: |
| 463 | ... |
| 464 | |
Georg Brandl | c0e22b7 | 2010-03-14 10:51:01 +0000 | [diff] [blame] | 465 | The :mod:`contextlib` module also has a ``nested(mgr1, mgr2, ...)`` function |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 466 | that combines a number of context managers so you don't need to write nested |
| 467 | ':keyword:`with`' statements. In this example, the single ':keyword:`with`' |
| 468 | statement both starts a database transaction and acquires a thread lock:: |
| 469 | |
| 470 | lock = threading.Lock() |
| 471 | with nested (db_transaction(db), lock) as (cursor, locked): |
| 472 | ... |
| 473 | |
Georg Brandl | c0e22b7 | 2010-03-14 10:51:01 +0000 | [diff] [blame] | 474 | Finally, the :func:`closing` function returns its argument so that it can be |
| 475 | bound to a variable, and calls the argument's ``.close()`` method at the end |
| 476 | of the block. :: |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 477 | |
| 478 | import urllib, sys |
| 479 | from contextlib import closing |
| 480 | |
| 481 | with closing(urllib.urlopen('http://www.yahoo.com')) as f: |
| 482 | for line in f: |
| 483 | sys.stdout.write(line) |
| 484 | |
| 485 | |
| 486 | .. seealso:: |
| 487 | |
| 488 | :pep:`343` - The "with" statement |
| 489 | PEP written by Guido van Rossum and Nick Coghlan; implemented by Mike Bland, |
| 490 | Guido van Rossum, and Neal Norwitz. The PEP shows the code generated for a |
| 491 | ':keyword:`with`' statement, which can be helpful in learning how the statement |
| 492 | works. |
| 493 | |
| 494 | The documentation for the :mod:`contextlib` module. |
| 495 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 496 | .. ====================================================================== |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 497 | |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 498 | .. _pep-0366: |
| 499 | |
| 500 | PEP 366: Explicit Relative Imports From a Main Module |
| 501 | ============================================================ |
| 502 | |
| 503 | Python's :option:`-m` switch allows running a module as a script. |
| 504 | When you ran a module that was located inside a package, relative |
| 505 | imports didn't work correctly. |
| 506 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 507 | The fix for Python 2.6 adds a :attr:`__package__` attribute to |
| 508 | modules. When this attribute is present, relative imports will be |
| 509 | relative to the value of this attribute instead of the |
| 510 | :attr:`__name__` attribute. |
| 511 | |
| 512 | PEP 302-style importers can then set :attr:`__package__` as necessary. |
| 513 | The :mod:`runpy` module that implements the :option:`-m` switch now |
| 514 | does this, so relative imports will now work correctly in scripts |
| 515 | running from inside a package. |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 516 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 517 | .. ====================================================================== |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 518 | |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 519 | .. _pep-0370: |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 520 | |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 521 | PEP 370: Per-user ``site-packages`` Directory |
| 522 | ===================================================== |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 523 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 524 | When you run Python, the module search path ``sys.path`` usually |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 525 | includes a directory whose path ends in ``"site-packages"``. This |
| 526 | directory is intended to hold locally-installed packages available to |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 527 | all users using a machine or a particular site installation. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 528 | |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 529 | Python 2.6 introduces a convention for user-specific site directories. |
| 530 | The directory varies depending on the platform: |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 531 | |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 532 | * Unix and Mac OS X: :file:`~/.local/` |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 533 | * Windows: :file:`%APPDATA%/Python` |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 534 | |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 535 | Within this directory, there will be version-specific subdirectories, |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 536 | such as :file:`lib/python2.6/site-packages` on Unix/Mac OS and |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 537 | :file:`Python26/site-packages` on Windows. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 538 | |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 539 | If you don't like the default directory, it can be overridden by an |
| 540 | environment variable. :envvar:`PYTHONUSERBASE` sets the root |
| 541 | directory used for all Python versions supporting this feature. On |
| 542 | Windows, the directory for application-specific data can be changed by |
| 543 | setting the :envvar:`APPDATA` environment variable. You can also |
| 544 | modify the :file:`site.py` file for your Python installation. |
| 545 | |
| 546 | The feature can be disabled entirely by running Python with the |
| 547 | :option:`-s` option or setting the :envvar:`PYTHONNOUSERSITE` |
| 548 | environment variable. |
| 549 | |
| 550 | .. seealso:: |
| 551 | |
| 552 | :pep:`370` - Per-user ``site-packages`` Directory |
| 553 | PEP written and implemented by Christian Heimes. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 554 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 555 | |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 556 | .. ====================================================================== |
| 557 | |
Amaury Forgeot d'Arc | 35c8658 | 2008-06-17 21:11:29 +0000 | [diff] [blame] | 558 | .. _pep-0371: |
| 559 | |
| 560 | PEP 371: The ``multiprocessing`` Package |
| 561 | ===================================================== |
| 562 | |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 563 | The new :mod:`multiprocessing` package lets Python programs create new |
| 564 | processes that will perform a computation and return a result to the |
| 565 | parent. The parent and child processes can communicate using queues |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 566 | and pipes, synchronize their operations using locks and semaphores, |
| 567 | and can share simple arrays of data. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 568 | |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 569 | The :mod:`multiprocessing` module started out as an exact emulation of |
| 570 | the :mod:`threading` module using processes instead of threads. That |
| 571 | goal was discarded along the path to Python 2.6, but the general |
| 572 | approach of the module is still similar. The fundamental class |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 573 | is the :class:`Process`, which is passed a callable object and |
| 574 | a collection of arguments. The :meth:`start` method |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 575 | sets the callable running in a subprocess, after which you can call |
| 576 | the :meth:`is_alive` method to check whether the subprocess is still running |
| 577 | and the :meth:`join` method to wait for the process to exit. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 578 | |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 579 | Here's a simple example where the subprocess will calculate a |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 580 | factorial. The function doing the calculation is written strangely so |
| 581 | that it takes significantly longer when the input argument is a |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 582 | multiple of 4. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 583 | |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 584 | :: |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 585 | |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 586 | import time |
| 587 | from multiprocessing import Process, Queue |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 588 | |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 589 | |
| 590 | def factorial(queue, N): |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 591 | "Compute a factorial." |
| 592 | # If N is a multiple of 4, this function will take much longer. |
| 593 | if (N % 4) == 0: |
| 594 | time.sleep(.05 * N/4) |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 595 | |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 596 | # Calculate the result |
| 597 | fact = 1L |
| 598 | for i in range(1, N+1): |
| 599 | fact = fact * i |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 600 | |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 601 | # Put the result on the queue |
| 602 | queue.put(fact) |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 603 | |
| 604 | if __name__ == '__main__': |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 605 | queue = Queue() |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 606 | |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 607 | N = 5 |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 608 | |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 609 | p = Process(target=factorial, args=(queue, N)) |
| 610 | p.start() |
| 611 | p.join() |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 612 | |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 613 | result = queue.get() |
| 614 | print 'Factorial', N, '=', result |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 615 | |
Sandro Tosi | f576747 | 2012-01-05 19:48:56 +0100 | [diff] [blame] | 616 | A :class:`Queue` is used to communicate the result of the factorial. |
| 617 | The :class:`Queue` object is stored in a global variable. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 618 | The child process will use the value of the variable when the child |
| 619 | was created; because it's a :class:`Queue`, parent and child can use |
| 620 | the object to communicate. (If the parent were to change the value of |
| 621 | the global variable, the child's value would be unaffected, and vice |
| 622 | versa.) |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 623 | |
| 624 | Two other classes, :class:`Pool` and :class:`Manager`, provide |
| 625 | higher-level interfaces. :class:`Pool` will create a fixed number of |
| 626 | worker processes, and requests can then be distributed to the workers |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 627 | by calling :meth:`apply` or :meth:`apply_async` to add a single request, |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 628 | and :meth:`map` or :meth:`map_async` to add a number of |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 629 | requests. The following code uses a :class:`Pool` to spread requests |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 630 | across 5 worker processes and retrieve a list of results:: |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 631 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 632 | from multiprocessing import Pool |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 633 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 634 | def factorial(N, dictionary): |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 635 | "Compute a factorial." |
| 636 | ... |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 637 | p = Pool(5) |
| 638 | result = p.map(factorial, range(1, 1000, 10)) |
| 639 | for v in result: |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 640 | print v |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 641 | |
| 642 | This produces the following output:: |
| 643 | |
| 644 | 1 |
| 645 | 39916800 |
| 646 | 51090942171709440000 |
| 647 | 8222838654177922817725562880000000 |
| 648 | 33452526613163807108170062053440751665152000000000 |
| 649 | ... |
| 650 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 651 | The other high-level interface, the :class:`Manager` class, creates a |
| 652 | separate server process that can hold master copies of Python data |
| 653 | structures. Other processes can then access and modify these data |
| 654 | structures using proxy objects. The following example creates a |
| 655 | shared dictionary by calling the :meth:`dict` method; the worker |
| 656 | processes then insert values into the dictionary. (Locking is not |
| 657 | done for you automatically, which doesn't matter in this example. |
| 658 | :class:`Manager`'s methods also include :meth:`Lock`, :meth:`RLock`, |
| 659 | and :meth:`Semaphore` to create shared locks.) |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 660 | |
| 661 | :: |
| 662 | |
| 663 | import time |
| 664 | from multiprocessing import Pool, Manager |
| 665 | |
| 666 | def factorial(N, dictionary): |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 667 | "Compute a factorial." |
| 668 | # Calculate the result |
| 669 | fact = 1L |
| 670 | for i in range(1, N+1): |
| 671 | fact = fact * i |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 672 | |
| 673 | # Store result in dictionary |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 674 | dictionary[N] = fact |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 675 | |
| 676 | if __name__ == '__main__': |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 677 | p = Pool(5) |
| 678 | mgr = Manager() |
| 679 | d = mgr.dict() # Create shared dictionary |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 680 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 681 | # Run tasks using the pool |
| 682 | for N in range(1, 1000, 10): |
| 683 | p.apply_async(factorial, (N, d)) |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 684 | |
Georg Brandl | 3cfdd9c | 2009-06-04 10:21:10 +0000 | [diff] [blame] | 685 | # Mark pool as closed -- no more tasks can be added. |
| 686 | p.close() |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 687 | |
Georg Brandl | 3cfdd9c | 2009-06-04 10:21:10 +0000 | [diff] [blame] | 688 | # Wait for tasks to exit |
| 689 | p.join() |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 690 | |
Georg Brandl | 3cfdd9c | 2009-06-04 10:21:10 +0000 | [diff] [blame] | 691 | # Output results |
| 692 | for k, v in sorted(d.items()): |
| 693 | print k, v |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 694 | |
| 695 | This will produce the output:: |
| 696 | |
| 697 | 1 1 |
| 698 | 11 39916800 |
| 699 | 21 51090942171709440000 |
| 700 | 31 8222838654177922817725562880000000 |
| 701 | 41 33452526613163807108170062053440751665152000000000 |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 702 | 51 15511187532873822802242430164693032110632597200169861120000... |
Amaury Forgeot d'Arc | 35c8658 | 2008-06-17 21:11:29 +0000 | [diff] [blame] | 703 | |
| 704 | .. seealso:: |
| 705 | |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 706 | The documentation for the :mod:`multiprocessing` module. |
| 707 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 708 | :pep:`371` - Addition of the multiprocessing package |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 709 | PEP written by Jesse Noller and Richard Oudkerk; |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 710 | implemented by Richard Oudkerk and Jesse Noller. |
Amaury Forgeot d'Arc | 35c8658 | 2008-06-17 21:11:29 +0000 | [diff] [blame] | 711 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 712 | |
Amaury Forgeot d'Arc | 35c8658 | 2008-06-17 21:11:29 +0000 | [diff] [blame] | 713 | .. ====================================================================== |
| 714 | |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 715 | .. _pep-3101: |
| 716 | |
| 717 | PEP 3101: Advanced String Formatting |
| 718 | ===================================================== |
| 719 | |
Benjamin Peterson | 1e2f050 | 2008-05-26 12:52:02 +0000 | [diff] [blame] | 720 | In Python 3.0, the `%` operator is supplemented by a more powerful string |
| 721 | formatting method, :meth:`format`. Support for the :meth:`str.format` method |
| 722 | has been backported to Python 2.6. |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 723 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 724 | In 2.6, both 8-bit and Unicode strings have a `.format()` method that |
| 725 | treats the string as a template and takes the arguments to be formatted. |
| 726 | The formatting template uses curly brackets (`{`, `}`) as special characters:: |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 727 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 728 | >>> # Substitute positional argument 0 into the string. |
| 729 | >>> "User ID: {0}".format("root") |
| 730 | 'User ID: root' |
| 731 | >>> # Use the named keyword arguments |
| 732 | >>> "User ID: {uid} Last seen: {last_login}".format( |
| 733 | ... uid="root", |
| 734 | ... last_login = "5 Mar 2008 07:20") |
| 735 | 'User ID: root Last seen: 5 Mar 2008 07:20' |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 736 | |
| 737 | Curly brackets can be escaped by doubling them:: |
| 738 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 739 | >>> "Empty dict: {{}}".format() |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 740 | "Empty dict: {}" |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 741 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 742 | Field names can be integers indicating positional arguments, such as |
| 743 | ``{0}``, ``{1}``, etc. or names of keyword arguments. You can also |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 744 | supply compound field names that read attributes or access dictionary keys:: |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 745 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 746 | >>> import sys |
| 747 | >>> print 'Platform: {0.platform}\nPython version: {0.version}'.format(sys) |
| 748 | Platform: darwin |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 749 | Python version: 2.6a1+ (trunk:61261M, Mar 5 2008, 20:29:41) |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 750 | [GCC 4.0.1 (Apple Computer, Inc. build 5367)]' |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 751 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 752 | >>> import mimetypes |
| 753 | >>> 'Content-type: {0[.mp4]}'.format(mimetypes.types_map) |
| 754 | 'Content-type: video/mp4' |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 755 | |
| 756 | Note that when using dictionary-style notation such as ``[.mp4]``, you |
| 757 | don't need to put any quotation marks around the string; it will look |
| 758 | up the value using ``.mp4`` as the key. Strings beginning with a |
| 759 | number will be converted to an integer. You can't write more |
| 760 | complicated expressions inside a format string. |
| 761 | |
| 762 | So far we've shown how to specify which field to substitute into the |
| 763 | resulting string. The precise formatting used is also controllable by |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 764 | adding a colon followed by a format specifier. For example:: |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 765 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 766 | >>> # Field 0: left justify, pad to 15 characters |
| 767 | >>> # Field 1: right justify, pad to 6 characters |
| 768 | >>> fmt = '{0:15} ${1:>6}' |
| 769 | >>> fmt.format('Registration', 35) |
| 770 | 'Registration $ 35' |
| 771 | >>> fmt.format('Tutorial', 50) |
| 772 | 'Tutorial $ 50' |
| 773 | >>> fmt.format('Banquet', 125) |
| 774 | 'Banquet $ 125' |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 775 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 776 | Format specifiers can reference other fields through nesting:: |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 777 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 778 | >>> fmt = '{0:{1}}' |
| 779 | >>> width = 15 |
| 780 | >>> fmt.format('Invoice #1234', width) |
| 781 | 'Invoice #1234 ' |
| 782 | >>> width = 35 |
| 783 | >>> fmt.format('Invoice #1234', width) |
| 784 | 'Invoice #1234 ' |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 785 | |
| 786 | The alignment of a field within the desired width can be specified: |
| 787 | |
| 788 | ================ ============================================ |
| 789 | Character Effect |
| 790 | ================ ============================================ |
| 791 | < (default) Left-align |
| 792 | > Right-align |
| 793 | ^ Center |
| 794 | = (For numeric types only) Pad after the sign. |
| 795 | ================ ============================================ |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 796 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 797 | Format specifiers can also include a presentation type, which |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 798 | controls how the value is formatted. For example, floating-point numbers |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 799 | can be formatted as a general number or in exponential notation:: |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 800 | |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 801 | >>> '{0:g}'.format(3.75) |
| 802 | '3.75' |
| 803 | >>> '{0:e}'.format(3.75) |
| 804 | '3.750000e+00' |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 805 | |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 806 | A variety of presentation types are available. Consult the 2.6 |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 807 | documentation for a :ref:`complete list <formatstrings>`; here's a sample: |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 808 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 809 | ===== ======================================================================== |
| 810 | ``b`` Binary. Outputs the number in base 2. |
| 811 | ``c`` Character. Converts the integer to the corresponding Unicode character |
| 812 | before printing. |
| 813 | ``d`` Decimal Integer. Outputs the number in base 10. |
| 814 | ``o`` Octal format. Outputs the number in base 8. |
| 815 | ``x`` Hex format. Outputs the number in base 16, using lower-case letters for |
| 816 | the digits above 9. |
| 817 | ``e`` Exponent notation. Prints the number in scientific notation using the |
| 818 | letter 'e' to indicate the exponent. |
| 819 | ``g`` General format. This prints the number as a fixed-point number, unless |
| 820 | the number is too large, in which case it switches to 'e' exponent |
| 821 | notation. |
| 822 | ``n`` Number. This is the same as 'g' (for floats) or 'd' (for integers), |
| 823 | except that it uses the current locale setting to insert the appropriate |
| 824 | number separator characters. |
| 825 | ``%`` Percentage. Multiplies the number by 100 and displays in fixed ('f') |
| 826 | format, followed by a percent sign. |
| 827 | ===== ======================================================================== |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 828 | |
Georg Brandl | 734e268 | 2008-08-12 08:18:18 +0000 | [diff] [blame] | 829 | Classes and types can define a :meth:`__format__` method to control how they're |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 830 | formatted. It receives a single argument, the format specifier:: |
| 831 | |
| 832 | def __format__(self, format_spec): |
| 833 | if isinstance(format_spec, unicode): |
| 834 | return unicode(str(self)) |
| 835 | else: |
| 836 | return str(self) |
| 837 | |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 838 | There's also a :func:`format` builtin that will format a single |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 839 | value. It calls the type's :meth:`__format__` method with the |
| 840 | provided specifier:: |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 841 | |
| 842 | >>> format(75.6564, '.2f') |
| 843 | '75.66' |
| 844 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 845 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 846 | .. seealso:: |
| 847 | |
Benjamin Peterson | 1e2f050 | 2008-05-26 12:52:02 +0000 | [diff] [blame] | 848 | :ref:`formatstrings` |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 849 | The reference documentation for format fields. |
Benjamin Peterson | 1e2f050 | 2008-05-26 12:52:02 +0000 | [diff] [blame] | 850 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 851 | :pep:`3101` - Advanced String Formatting |
Benjamin Peterson | 1e2f050 | 2008-05-26 12:52:02 +0000 | [diff] [blame] | 852 | PEP written by Talin. Implemented by Eric Smith. |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 853 | |
| 854 | .. ====================================================================== |
| 855 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 856 | .. _pep-3105: |
| 857 | |
| 858 | PEP 3105: ``print`` As a Function |
| 859 | ===================================================== |
| 860 | |
| 861 | The ``print`` statement becomes the :func:`print` function in Python 3.0. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 862 | Making :func:`print` a function makes it possible to replace the function |
| 863 | by doing ``def print(...)`` or importing a new function from somewhere else. |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 864 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 865 | Python 2.6 has a ``__future__`` import that removes ``print`` as language |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 866 | syntax, letting you use the functional form instead. For example:: |
| 867 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 868 | >>> from __future__ import print_function |
| 869 | >>> print('# of entries', len(dictionary), file=sys.stderr) |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 870 | |
| 871 | The signature of the new function is:: |
| 872 | |
| 873 | def print(*args, sep=' ', end='\n', file=None) |
| 874 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 875 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 876 | The parameters are: |
| 877 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 878 | * *args*: positional arguments whose values will be printed out. |
| 879 | * *sep*: the separator, which will be printed between arguments. |
| 880 | * *end*: the ending text, which will be printed after all of the |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 881 | arguments have been output. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 882 | * *file*: the file object to which the output will be sent. |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 883 | |
| 884 | .. seealso:: |
| 885 | |
| 886 | :pep:`3105` - Make print a function |
| 887 | PEP written by Georg Brandl. |
| 888 | |
| 889 | .. ====================================================================== |
| 890 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 891 | .. _pep-3110: |
| 892 | |
| 893 | PEP 3110: Exception-Handling Changes |
| 894 | ===================================================== |
| 895 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 896 | One error that Python programmers occasionally make |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 897 | is writing the following code:: |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 898 | |
| 899 | try: |
| 900 | ... |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 901 | except TypeError, ValueError: # Wrong! |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 902 | ... |
| 903 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 904 | The author is probably trying to catch both :exc:`TypeError` and |
| 905 | :exc:`ValueError` exceptions, but this code actually does something |
| 906 | different: it will catch :exc:`TypeError` and bind the resulting |
| 907 | exception object to the local name ``"ValueError"``. The |
| 908 | :exc:`ValueError` exception will not be caught at all. The correct |
| 909 | code specifies a tuple of exceptions:: |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 910 | |
| 911 | try: |
| 912 | ... |
| 913 | except (TypeError, ValueError): |
| 914 | ... |
| 915 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 916 | This error happens because the use of the comma here is ambiguous: |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 917 | does it indicate two different nodes in the parse tree, or a single |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 918 | node that's a tuple? |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 919 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 920 | Python 3.0 makes this unambiguous by replacing the comma with the word |
| 921 | "as". To catch an exception and store the exception object in the |
| 922 | variable ``exc``, you must write:: |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 923 | |
| 924 | try: |
| 925 | ... |
| 926 | except TypeError as exc: |
| 927 | ... |
| 928 | |
| 929 | Python 3.0 will only support the use of "as", and therefore interprets |
| 930 | the first example as catching two different exceptions. Python 2.6 |
| 931 | supports both the comma and "as", so existing code will continue to |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 932 | work. We therefore suggest using "as" when writing new Python code |
| 933 | that will only be executed with 2.6. |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 934 | |
| 935 | .. seealso:: |
| 936 | |
| 937 | :pep:`3110` - Catching Exceptions in Python 3000 |
| 938 | PEP written and implemented by Collin Winter. |
| 939 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 940 | .. ====================================================================== |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 941 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 942 | .. _pep-3112: |
| 943 | |
| 944 | PEP 3112: Byte Literals |
| 945 | ===================================================== |
| 946 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 947 | Python 3.0 adopts Unicode as the language's fundamental string type and |
| 948 | denotes 8-bit literals differently, either as ``b'string'`` |
| 949 | or using a :class:`bytes` constructor. For future compatibility, |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 950 | Python 2.6 adds :class:`bytes` as a synonym for the :class:`str` type, |
| 951 | and it also supports the ``b''`` notation. |
| 952 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 953 | |
| 954 | The 2.6 :class:`str` differs from 3.0's :class:`bytes` type in various |
| 955 | ways; most notably, the constructor is completely different. In 3.0, |
| 956 | ``bytes([65, 66, 67])`` is 3 elements long, containing the bytes |
| 957 | representing ``ABC``; in 2.6, ``bytes([65, 66, 67])`` returns the |
| 958 | 12-byte string representing the :func:`str` of the list. |
| 959 | |
| 960 | The primary use of :class:`bytes` in 2.6 will be to write tests of |
| 961 | object type such as ``isinstance(x, bytes)``. This will help the 2to3 |
| 962 | converter, which can't tell whether 2.x code intends strings to |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 963 | contain either characters or 8-bit bytes; you can now |
| 964 | use either :class:`bytes` or :class:`str` to represent your intention |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 965 | exactly, and the resulting code will also be correct in Python 3.0. |
| 966 | |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 967 | There's also a ``__future__`` import that causes all string literals |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 968 | to become Unicode strings. This means that ``\u`` escape sequences |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 969 | can be used to include Unicode characters:: |
| 970 | |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 971 | |
Neal Norwitz | 32dde22 | 2008-04-15 06:43:13 +0000 | [diff] [blame] | 972 | from __future__ import unicode_literals |
| 973 | |
| 974 | s = ('\u751f\u3080\u304e\u3000\u751f\u3054' |
| 975 | '\u3081\u3000\u751f\u305f\u307e\u3054') |
| 976 | |
| 977 | print len(s) # 12 Unicode characters |
| 978 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 979 | At the C level, Python 3.0 will rename the existing 8-bit |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 980 | string type, called :c:type:`PyStringObject` in Python 2.x, |
| 981 | to :c:type:`PyBytesObject`. Python 2.6 uses ``#define`` |
| 982 | to support using the names :c:func:`PyBytesObject`, |
| 983 | :c:func:`PyBytes_Check`, :c:func:`PyBytes_FromStringAndSize`, |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 984 | and all the other functions and macros used with strings. |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 985 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 986 | Instances of the :class:`bytes` type are immutable just |
| 987 | as strings are. A new :class:`bytearray` type stores a mutable |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 988 | sequence of bytes:: |
| 989 | |
| 990 | >>> bytearray([65, 66, 67]) |
| 991 | bytearray(b'ABC') |
| 992 | >>> b = bytearray(u'\u21ef\u3244', 'utf-8') |
| 993 | >>> b |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 994 | bytearray(b'\xe2\x87\xaf\xe3\x89\x84') |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 995 | >>> b[0] = '\xe3' |
| 996 | >>> b |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 997 | bytearray(b'\xe3\x87\xaf\xe3\x89\x84') |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 998 | >>> unicode(str(b), 'utf-8') |
| 999 | u'\u31ef \u3244' |
| 1000 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1001 | Byte arrays support most of the methods of string types, such as |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1002 | :meth:`startswith`/:meth:`endswith`, :meth:`find`/:meth:`rfind`, |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1003 | and some of the methods of lists, such as :meth:`append`, |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1004 | :meth:`pop`, and :meth:`reverse`. |
| 1005 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1006 | :: |
| 1007 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1008 | >>> b = bytearray('ABC') |
| 1009 | >>> b.append('d') |
| 1010 | >>> b.append(ord('e')) |
| 1011 | >>> b |
| 1012 | bytearray(b'ABCde') |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 1013 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1014 | There's also a corresponding C API, with |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1015 | :c:func:`PyByteArray_FromObject`, |
| 1016 | :c:func:`PyByteArray_FromStringAndSize`, |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1017 | and various other functions. |
| 1018 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1019 | .. seealso:: |
| 1020 | |
| 1021 | :pep:`3112` - Bytes literals in Python 3000 |
| 1022 | PEP written by Jason Orendorff; backported to 2.6 by Christian Heimes. |
| 1023 | |
| 1024 | .. ====================================================================== |
| 1025 | |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 1026 | .. _pep-3116: |
| 1027 | |
| 1028 | PEP 3116: New I/O Library |
| 1029 | ===================================================== |
| 1030 | |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1031 | Python's built-in file objects support a number of methods, but |
| 1032 | file-like objects don't necessarily support all of them. Objects that |
| 1033 | imitate files usually support :meth:`read` and :meth:`write`, but they |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1034 | may not support :meth:`readline`, for example. Python 3.0 introduces |
| 1035 | a layered I/O library in the :mod:`io` module that separates buffering |
| 1036 | and text-handling features from the fundamental read and write |
| 1037 | operations. |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1038 | |
| 1039 | There are three levels of abstract base classes provided by |
| 1040 | the :mod:`io` module: |
| 1041 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1042 | * :class:`RawIOBase` defines raw I/O operations: :meth:`read`, |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1043 | :meth:`readinto`, |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1044 | :meth:`write`, :meth:`seek`, :meth:`tell`, :meth:`truncate`, |
| 1045 | and :meth:`close`. |
| 1046 | Most of the methods of this class will often map to a single system call. |
| 1047 | There are also :meth:`readable`, :meth:`writable`, and :meth:`seekable` |
| 1048 | methods for determining what operations a given object will allow. |
| 1049 | |
| 1050 | Python 3.0 has concrete implementations of this class for files and |
| 1051 | sockets, but Python 2.6 hasn't restructured its file and socket objects |
| 1052 | in this way. |
| 1053 | |
| 1054 | .. XXX should 2.6 register them in io.py? |
| 1055 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1056 | * :class:`BufferedIOBase` is an abstract base class that |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1057 | buffers data in memory to reduce the number of |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1058 | system calls used, making I/O processing more efficient. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1059 | It supports all of the methods of :class:`RawIOBase`, |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1060 | and adds a :attr:`raw` attribute holding the underlying raw object. |
| 1061 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1062 | There are five concrete classes implementing this ABC. |
| 1063 | :class:`BufferedWriter` and :class:`BufferedReader` are for objects |
| 1064 | that support write-only or read-only usage that have a :meth:`seek` |
| 1065 | method for random access. :class:`BufferedRandom` objects support |
| 1066 | read and write access upon the same underlying stream, and |
| 1067 | :class:`BufferedRWPair` is for objects such as TTYs that have both |
| 1068 | read and write operations acting upon unconnected streams of data. |
| 1069 | The :class:`BytesIO` class supports reading, writing, and seeking |
| 1070 | over an in-memory buffer. |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1071 | |
R David Murray | 1b00f25 | 2012-08-15 10:43:58 -0400 | [diff] [blame] | 1072 | .. index:: |
| 1073 | single: universal newlines; What's new |
| 1074 | |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1075 | * :class:`TextIOBase`: Provides functions for reading and writing |
| 1076 | strings (remember, strings will be Unicode in Python 3.0), |
R David Murray | 1b00f25 | 2012-08-15 10:43:58 -0400 | [diff] [blame] | 1077 | and supporting :term:`universal newlines`. :class:`TextIOBase` defines |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1078 | the :meth:`readline` method and supports iteration upon |
| 1079 | objects. |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1080 | |
| 1081 | There are two concrete implementations. :class:`TextIOWrapper` |
| 1082 | wraps a buffered I/O object, supporting all of the methods for |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1083 | text I/O and adding a :attr:`buffer` attribute for access |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1084 | to the underlying object. :class:`StringIO` simply buffers |
| 1085 | everything in memory without ever writing anything to disk. |
| 1086 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1087 | (In Python 2.6, :class:`io.StringIO` is implemented in |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1088 | pure Python, so it's pretty slow. You should therefore stick with the |
| 1089 | existing :mod:`StringIO` module or :mod:`cStringIO` for now. At some |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1090 | point Python 3.0's :mod:`io` module will be rewritten into C for speed, |
| 1091 | and perhaps the C implementation will be backported to the 2.x releases.) |
| 1092 | |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1093 | In Python 2.6, the underlying implementations haven't been |
| 1094 | restructured to build on top of the :mod:`io` module's classes. The |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1095 | module is being provided to make it easier to write code that's |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1096 | forward-compatible with 3.0, and to save developers the effort of writing |
| 1097 | their own implementations of buffering and text I/O. |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 1098 | |
| 1099 | .. seealso:: |
| 1100 | |
| 1101 | :pep:`3116` - New I/O |
| 1102 | PEP written by Daniel Stutzbach, Mike Verdone, and Guido van Rossum. |
Neal Norwitz | 32dde22 | 2008-04-15 06:43:13 +0000 | [diff] [blame] | 1103 | Code by Guido van Rossum, Georg Brandl, Walter Doerwald, |
Antoine Pitrou | fbd4f80 | 2012-08-11 16:51:50 +0200 | [diff] [blame] | 1104 | Jeremy Hylton, Martin von Löwis, Tony Lownds, and others. |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 1105 | |
| 1106 | .. ====================================================================== |
| 1107 | |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 1108 | .. _pep-3118: |
| 1109 | |
| 1110 | PEP 3118: Revised Buffer Protocol |
| 1111 | ===================================================== |
| 1112 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1113 | The buffer protocol is a C-level API that lets Python types |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1114 | exchange pointers into their internal representations. A |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1115 | memory-mapped file can be viewed as a buffer of characters, for |
| 1116 | example, and this lets another module such as :mod:`re` |
| 1117 | treat memory-mapped files as a string of characters to be searched. |
| 1118 | |
| 1119 | The primary users of the buffer protocol are numeric-processing |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1120 | packages such as NumPy, which expose the internal representation |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1121 | of arrays so that callers can write data directly into an array instead |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1122 | of going through a slower API. This PEP updates the buffer protocol in light of experience |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1123 | from NumPy development, adding a number of new features |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1124 | such as indicating the shape of an array or locking a memory region. |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1125 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1126 | The most important new C API function is |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1127 | ``PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)``, which |
| 1128 | takes an object and a set of flags, and fills in the |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1129 | ``Py_buffer`` structure with information |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1130 | about the object's memory representation. Objects |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1131 | can use this operation to lock memory in place |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1132 | while an external caller could be modifying the contents, |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1133 | so there's a corresponding ``PyBuffer_Release(Py_buffer *view)`` to |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1134 | indicate that the external caller is done. |
| 1135 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1136 | .. XXX PyObject_GetBuffer not documented in c-api |
| 1137 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1138 | The *flags* argument to :c:func:`PyObject_GetBuffer` specifies |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1139 | constraints upon the memory returned. Some examples are: |
| 1140 | |
| 1141 | * :const:`PyBUF_WRITABLE` indicates that the memory must be writable. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1142 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1143 | * :const:`PyBUF_LOCK` requests a read-only or exclusive lock on the memory. |
| 1144 | |
| 1145 | * :const:`PyBUF_C_CONTIGUOUS` and :const:`PyBUF_F_CONTIGUOUS` |
| 1146 | requests a C-contiguous (last dimension varies the fastest) or |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1147 | Fortran-contiguous (first dimension varies the fastest) array layout. |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1148 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1149 | Two new argument codes for :c:func:`PyArg_ParseTuple`, |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1150 | ``s*`` and ``z*``, return locked buffer objects for a parameter. |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 1151 | |
| 1152 | .. seealso:: |
| 1153 | |
| 1154 | :pep:`3118` - Revising the buffer protocol |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1155 | PEP written by Travis Oliphant and Carl Banks; implemented by |
| 1156 | Travis Oliphant. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1157 | |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 1158 | |
| 1159 | .. ====================================================================== |
| 1160 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 1161 | .. _pep-3119: |
| 1162 | |
| 1163 | PEP 3119: Abstract Base Classes |
| 1164 | ===================================================== |
| 1165 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1166 | Some object-oriented languages such as Java support interfaces, |
| 1167 | declaring that a class has a given set of methods or supports a given |
| 1168 | access protocol. Abstract Base Classes (or ABCs) are an equivalent |
| 1169 | feature for Python. The ABC support consists of an :mod:`abc` module |
| 1170 | containing a metaclass called :class:`ABCMeta`, special handling of |
| 1171 | this metaclass by the :func:`isinstance` and :func:`issubclass` |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1172 | builtins, and a collection of basic ABCs that the Python developers |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1173 | think will be widely useful. Future versions of Python will probably |
| 1174 | add more ABCs. |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 1175 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1176 | Let's say you have a particular class and wish to know whether it supports |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1177 | dictionary-style access. The phrase "dictionary-style" is vague, however. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1178 | It probably means that accessing items with ``obj[1]`` works. |
| 1179 | Does it imply that setting items with ``obj[2] = value`` works? |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1180 | Or that the object will have :meth:`keys`, :meth:`values`, and :meth:`items` |
| 1181 | methods? What about the iterative variants such as :meth:`iterkeys`? :meth:`copy` |
| 1182 | and :meth:`update`? Iterating over the object with :func:`iter`? |
Christian Heimes | 3f419af | 2008-01-04 03:08:33 +0000 | [diff] [blame] | 1183 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1184 | The Python 2.6 :mod:`collections` module includes a number of |
| 1185 | different ABCs that represent these distinctions. :class:`Iterable` |
| 1186 | indicates that a class defines :meth:`__iter__`, and |
| 1187 | :class:`Container` means the class defines a :meth:`__contains__` |
| 1188 | method and therefore supports ``x in y`` expressions. The basic |
| 1189 | dictionary interface of getting items, setting items, and |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1190 | :meth:`keys`, :meth:`values`, and :meth:`items`, is defined by the |
| 1191 | :class:`MutableMapping` ABC. |
Christian Heimes | 3f419af | 2008-01-04 03:08:33 +0000 | [diff] [blame] | 1192 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1193 | You can derive your own classes from a particular ABC |
| 1194 | to indicate they support that ABC's interface:: |
Christian Heimes | 3f419af | 2008-01-04 03:08:33 +0000 | [diff] [blame] | 1195 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1196 | import collections |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1197 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1198 | class Storage(collections.MutableMapping): |
| 1199 | ... |
Christian Heimes | 3f419af | 2008-01-04 03:08:33 +0000 | [diff] [blame] | 1200 | |
Christian Heimes | 3f419af | 2008-01-04 03:08:33 +0000 | [diff] [blame] | 1201 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1202 | Alternatively, you could write the class without deriving from |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1203 | the desired ABC and instead register the class by |
| 1204 | calling the ABC's :meth:`register` method:: |
Christian Heimes | 3f419af | 2008-01-04 03:08:33 +0000 | [diff] [blame] | 1205 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1206 | import collections |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1207 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1208 | class Storage: |
| 1209 | ... |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1210 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1211 | collections.MutableMapping.register(Storage) |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1212 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1213 | For classes that you write, deriving from the ABC is probably clearer. |
| 1214 | The :meth:`register` method is useful when you've written a new |
| 1215 | ABC that can describe an existing type or class, or if you want |
| 1216 | to declare that some third-party class implements an ABC. |
| 1217 | For example, if you defined a :class:`PrintableType` ABC, |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 1218 | it's legal to do:: |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 1219 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1220 | # Register Python's types |
| 1221 | PrintableType.register(int) |
| 1222 | PrintableType.register(float) |
| 1223 | PrintableType.register(str) |
| 1224 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1225 | Classes should obey the semantics specified by an ABC, but |
| 1226 | Python can't check this; it's up to the class author to |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1227 | understand the ABC's requirements and to implement the code accordingly. |
| 1228 | |
| 1229 | To check whether an object supports a particular interface, you can |
| 1230 | now write:: |
| 1231 | |
| 1232 | def func(d): |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1233 | if not isinstance(d, collections.MutableMapping): |
| 1234 | raise ValueError("Mapping object expected, not %r" % d) |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1235 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1236 | Don't feel that you must now begin writing lots of checks as in the |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1237 | above example. Python has a strong tradition of duck-typing, where |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1238 | explicit type-checking is never done and code simply calls methods on |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1239 | an object, trusting that those methods will be there and raising an |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1240 | exception if they aren't. Be judicious in checking for ABCs and only |
| 1241 | do it where it's absolutely necessary. |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1242 | |
| 1243 | You can write your own ABCs by using ``abc.ABCMeta`` as the |
| 1244 | metaclass in a class definition:: |
| 1245 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1246 | from abc import ABCMeta, abstractmethod |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1247 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1248 | class Drawable(): |
| 1249 | __metaclass__ = ABCMeta |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1250 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1251 | @abstractmethod |
| 1252 | def draw(self, x, y, scale=1.0): |
| 1253 | pass |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1254 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1255 | def draw_doubled(self, x, y): |
| 1256 | self.draw(x, y, scale=2.0) |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1257 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1258 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1259 | class Square(Drawable): |
| 1260 | def draw(self, x, y, scale): |
| 1261 | ... |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1262 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1263 | |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1264 | In the :class:`Drawable` ABC above, the :meth:`draw_doubled` method |
| 1265 | renders the object at twice its size and can be implemented in terms |
| 1266 | of other methods described in :class:`Drawable`. Classes implementing |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1267 | this ABC therefore don't need to provide their own implementation |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1268 | of :meth:`draw_doubled`, though they can do so. An implementation |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1269 | of :meth:`draw` is necessary, though; the ABC can't provide |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1270 | a useful generic implementation. |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1271 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1272 | You can apply the ``@abstractmethod`` decorator to methods such as |
| 1273 | :meth:`draw` that must be implemented; Python will then raise an |
| 1274 | exception for classes that don't define the method. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1275 | Note that the exception is only raised when you actually |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1276 | try to create an instance of a subclass lacking the method:: |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1277 | |
Benjamin Peterson | dcc1e11 | 2008-09-03 22:22:18 +0000 | [diff] [blame] | 1278 | >>> class Circle(Drawable): |
| 1279 | ... pass |
| 1280 | ... |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1281 | >>> c = Circle() |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1282 | Traceback (most recent call last): |
| 1283 | File "<stdin>", line 1, in <module> |
Benjamin Peterson | dcc1e11 | 2008-09-03 22:22:18 +0000 | [diff] [blame] | 1284 | TypeError: Can't instantiate abstract class Circle with abstract methods draw |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1285 | >>> |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1286 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1287 | Abstract data attributes can be declared using the |
| 1288 | ``@abstractproperty`` decorator:: |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1289 | |
Benjamin Peterson | dcc1e11 | 2008-09-03 22:22:18 +0000 | [diff] [blame] | 1290 | from abc import abstractproperty |
| 1291 | ... |
| 1292 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 1293 | @abstractproperty |
| 1294 | def readonly(self): |
| 1295 | return self._x |
Christian Heimes | 3f419af | 2008-01-04 03:08:33 +0000 | [diff] [blame] | 1296 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1297 | Subclasses must then define a :meth:`readonly` property. |
Christian Heimes | 3f419af | 2008-01-04 03:08:33 +0000 | [diff] [blame] | 1298 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 1299 | .. seealso:: |
| 1300 | |
| 1301 | :pep:`3119` - Introducing Abstract Base Classes |
| 1302 | PEP written by Guido van Rossum and Talin. |
Martin v. Löwis | 2a241ca | 2008-04-05 18:58:09 +0000 | [diff] [blame] | 1303 | Implemented by Guido van Rossum. |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 1304 | Backported to 2.6 by Benjamin Aranguren, with Alex Martelli. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1305 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1306 | .. ====================================================================== |
| 1307 | |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1308 | .. _pep-3127: |
| 1309 | |
| 1310 | PEP 3127: Integer Literal Support and Syntax |
| 1311 | ===================================================== |
| 1312 | |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1313 | Python 3.0 changes the syntax for octal (base-8) integer literals, |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1314 | prefixing them with "0o" or "0O" instead of a leading zero, and adds |
| 1315 | support for binary (base-2) integer literals, signalled by a "0b" or |
| 1316 | "0B" prefix. |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1317 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1318 | Python 2.6 doesn't drop support for a leading 0 signalling |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1319 | an octal number, but it does add support for "0o" and "0b":: |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1320 | |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1321 | >>> 0o21, 2*8 + 1 |
| 1322 | (17, 17) |
| 1323 | >>> 0b101111 |
| 1324 | 47 |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1325 | |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1326 | The :func:`oct` builtin still returns numbers |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1327 | prefixed with a leading zero, and a new :func:`bin` |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1328 | builtin returns the binary representation for a number:: |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1329 | |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1330 | >>> oct(42) |
| 1331 | '052' |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1332 | >>> future_builtins.oct(42) |
| 1333 | '0o52' |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1334 | >>> bin(173) |
| 1335 | '0b10101101' |
| 1336 | |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1337 | The :func:`int` and :func:`long` builtins will now accept the "0o" |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1338 | and "0b" prefixes when base-8 or base-2 are requested, or when the |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1339 | *base* argument is zero (signalling that the base used should be |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1340 | determined from the string):: |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1341 | |
| 1342 | >>> int ('0o52', 0) |
| 1343 | 42 |
| 1344 | >>> int('1101', 2) |
| 1345 | 13 |
| 1346 | >>> int('0b1101', 2) |
| 1347 | 13 |
| 1348 | >>> int('0b1101', 0) |
| 1349 | 13 |
| 1350 | |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1351 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1352 | .. seealso:: |
| 1353 | |
| 1354 | :pep:`3127` - Integer Literal Support and Syntax |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1355 | PEP written by Patrick Maupin; backported to 2.6 by |
| 1356 | Eric Smith. |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1357 | |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1358 | .. ====================================================================== |
| 1359 | |
| 1360 | .. _pep-3129: |
| 1361 | |
| 1362 | PEP 3129: Class Decorators |
| 1363 | ===================================================== |
| 1364 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 1365 | Decorators have been extended from functions to classes. It's now legal to |
| 1366 | write:: |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1367 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1368 | @foo |
| 1369 | @bar |
| 1370 | class A: |
| 1371 | pass |
| 1372 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 1373 | This is equivalent to:: |
| 1374 | |
| 1375 | class A: |
| 1376 | pass |
| 1377 | |
| 1378 | A = foo(bar(A)) |
| 1379 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1380 | .. seealso:: |
| 1381 | |
| 1382 | :pep:`3129` - Class Decorators |
| 1383 | PEP written by Collin Winter. |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1384 | |
| 1385 | .. ====================================================================== |
| 1386 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1387 | .. _pep-3141: |
| 1388 | |
| 1389 | PEP 3141: A Type Hierarchy for Numbers |
| 1390 | ===================================================== |
| 1391 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1392 | Python 3.0 adds several abstract base classes for numeric types |
| 1393 | inspired by Scheme's numeric tower. These classes were backported to |
| 1394 | 2.6 as the :mod:`numbers` module. |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1395 | |
| 1396 | The most general ABC is :class:`Number`. It defines no operations at |
| 1397 | all, and only exists to allow checking if an object is a number by |
| 1398 | doing ``isinstance(obj, Number)``. |
| 1399 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1400 | :class:`Complex` is a subclass of :class:`Number`. Complex numbers |
| 1401 | can undergo the basic operations of addition, subtraction, |
| 1402 | multiplication, division, and exponentiation, and you can retrieve the |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1403 | real and imaginary parts and obtain a number's conjugate. Python's built-in |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1404 | complex type is an implementation of :class:`Complex`. |
| 1405 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1406 | :class:`Real` further derives from :class:`Complex`, and adds |
| 1407 | operations that only work on real numbers: :func:`floor`, :func:`trunc`, |
| 1408 | rounding, taking the remainder mod N, floor division, |
| 1409 | and comparisons. |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1410 | |
| 1411 | :class:`Rational` numbers derive from :class:`Real`, have |
| 1412 | :attr:`numerator` and :attr:`denominator` properties, and can be |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 1413 | converted to floats. Python 2.6 adds a simple rational-number class, |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1414 | :class:`Fraction`, in the :mod:`fractions` module. (It's called |
| 1415 | :class:`Fraction` instead of :class:`Rational` to avoid |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1416 | a name clash with :class:`numbers.Rational`.) |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1417 | |
| 1418 | :class:`Integral` numbers derive from :class:`Rational`, and |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1419 | can be shifted left and right with ``<<`` and ``>>``, |
| 1420 | combined using bitwise operations such as ``&`` and ``|``, |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1421 | and can be used as array indexes and slice boundaries. |
| 1422 | |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1423 | In Python 3.0, the PEP slightly redefines the existing builtins |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1424 | :func:`round`, :func:`math.floor`, :func:`math.ceil`, and adds a new |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1425 | one, :func:`math.trunc`, that's been backported to Python 2.6. |
| 1426 | :func:`math.trunc` rounds toward zero, returning the closest |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1427 | :class:`Integral` that's between the function's argument and zero. |
| 1428 | |
| 1429 | .. seealso:: |
| 1430 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1431 | :pep:`3141` - A Type Hierarchy for Numbers |
| 1432 | PEP written by Jeffrey Yasskin. |
| 1433 | |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 1434 | `Scheme's numerical tower <http://www.gnu.org/software/guile/manual/html_node/Numerical-Tower.html#Numerical-Tower>`__, from the Guile manual. |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1435 | |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 1436 | `Scheme's number datatypes <http://schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_sec_6.2>`__ from the R5RS Scheme specification. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1437 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1438 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1439 | The :mod:`fractions` Module |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1440 | -------------------------------------------------- |
| 1441 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1442 | To fill out the hierarchy of numeric types, the :mod:`fractions` |
| 1443 | module provides a rational-number class. Rational numbers store their |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1444 | values as a numerator and denominator forming a fraction, and can |
| 1445 | exactly represent numbers such as ``2/3`` that floating-point numbers |
| 1446 | can only approximate. |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1447 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 1448 | The :class:`Fraction` constructor takes two :class:`Integral` values |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1449 | that will be the numerator and denominator of the resulting fraction. :: |
| 1450 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 1451 | >>> from fractions import Fraction |
| 1452 | >>> a = Fraction(2, 3) |
| 1453 | >>> b = Fraction(2, 5) |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1454 | >>> float(a), float(b) |
| 1455 | (0.66666666666666663, 0.40000000000000002) |
| 1456 | >>> a+b |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 1457 | Fraction(16, 15) |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1458 | >>> a/b |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 1459 | Fraction(5, 3) |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1460 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1461 | For converting floating-point numbers to rationals, |
| 1462 | the float type now has an :meth:`as_integer_ratio()` method that returns |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1463 | the numerator and denominator for a fraction that evaluates to the same |
| 1464 | floating-point value:: |
| 1465 | |
| 1466 | >>> (2.5) .as_integer_ratio() |
| 1467 | (5, 2) |
| 1468 | >>> (3.1415) .as_integer_ratio() |
| 1469 | (7074029114692207L, 2251799813685248L) |
| 1470 | >>> (1./3) .as_integer_ratio() |
| 1471 | (6004799503160661L, 18014398509481984L) |
| 1472 | |
| 1473 | Note that values that can only be approximated by floating-point |
| 1474 | numbers, such as 1./3, are not simplified to the number being |
| 1475 | approximated; the fraction attempts to match the floating-point value |
| 1476 | **exactly**. |
| 1477 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 1478 | The :mod:`fractions` module is based upon an implementation by Sjoerd |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1479 | Mullender that was in Python's :file:`Demo/classes/` directory for a |
| 1480 | long time. This implementation was significantly updated by Jeffrey |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1481 | Yasskin. |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1482 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 1483 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1484 | Other Language Changes |
| 1485 | ====================== |
| 1486 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1487 | Some smaller changes made to the core Python language are: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1488 | |
Andrew M. Kuchling | 9d2d327 | 2010-02-22 14:57:30 +0000 | [diff] [blame] | 1489 | * Directories and zip archives containing a :file:`__main__.py` file |
| 1490 | can now be executed directly by passing their name to the |
| 1491 | interpreter. The directory or zip archive is automatically inserted |
| 1492 | as the first entry in sys.path. (Suggestion and initial patch by |
| 1493 | Andy Chu, subsequently revised by Phillip J. Eby and Nick Coghlan; |
| 1494 | :issue:`1739468`.) |
| 1495 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1496 | * The :func:`hasattr` function was catching and ignoring all errors, |
| 1497 | under the assumption that they meant a :meth:`__getattr__` method |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1498 | was failing somehow and the return value of :func:`hasattr` would |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1499 | therefore be ``False``. This logic shouldn't be applied to |
| 1500 | :exc:`KeyboardInterrupt` and :exc:`SystemExit`, however; Python 2.6 |
| 1501 | will no longer discard such exceptions when :func:`hasattr` |
| 1502 | encounters them. (Fixed by Benjamin Peterson; :issue:`2196`.) |
| 1503 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 1504 | * When calling a function using the ``**`` syntax to provide keyword |
| 1505 | arguments, you are no longer required to use a Python dictionary; |
| 1506 | any mapping will now work:: |
| 1507 | |
| 1508 | >>> def f(**kw): |
| 1509 | ... print sorted(kw) |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1510 | ... |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 1511 | >>> ud=UserDict.UserDict() |
| 1512 | >>> ud['a'] = 1 |
| 1513 | >>> ud['b'] = 'string' |
| 1514 | >>> f(**ud) |
| 1515 | ['a', 'b'] |
| 1516 | |
Martin v. Löwis | 5680d0c | 2008-04-10 03:06:53 +0000 | [diff] [blame] | 1517 | (Contributed by Alexander Belopolsky; :issue:`1686487`.) |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 1518 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1519 | It's also become legal to provide keyword arguments after a ``*args`` argument |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1520 | to a function call. :: |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1521 | |
| 1522 | >>> def f(*args, **kw): |
| 1523 | ... print args, kw |
| 1524 | ... |
| 1525 | >>> f(1,2,3, *(4,5,6), keyword=13) |
| 1526 | (1, 2, 3, 4, 5, 6) {'keyword': 13} |
| 1527 | |
| 1528 | Previously this would have been a syntax error. |
| 1529 | (Contributed by Amaury Forgeot d'Arc; :issue:`3473`.) |
| 1530 | |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1531 | * A new builtin, ``next(iterator, [default])`` returns the next item |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 1532 | from the specified iterator. If the *default* argument is supplied, |
| 1533 | it will be returned if *iterator* has been exhausted; otherwise, |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1534 | the :exc:`StopIteration` exception will be raised. (Backported |
| 1535 | in :issue:`2719`.) |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 1536 | |
Georg Brandl | 3dbca81 | 2008-07-23 16:10:53 +0000 | [diff] [blame] | 1537 | * Tuples now have :meth:`index` and :meth:`count` methods matching the |
| 1538 | list type's :meth:`index` and :meth:`count` methods:: |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1539 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1540 | >>> t = (0,1,2,3,4,0,1,2) |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1541 | >>> t.index(3) |
| 1542 | 3 |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1543 | >>> t.count(0) |
| 1544 | 2 |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 1545 | |
Georg Brandl | 3dbca81 | 2008-07-23 16:10:53 +0000 | [diff] [blame] | 1546 | (Contributed by Raymond Hettinger) |
| 1547 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1548 | * The built-in types now have improved support for extended slicing syntax, |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1549 | accepting various combinations of ``(start, stop, step)``. |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1550 | Previously, the support was partial and certain corner cases wouldn't work. |
| 1551 | (Implemented by Thomas Wouters.) |
| 1552 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 1553 | .. Revision 57619 |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1554 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1555 | * Properties now have three attributes, :attr:`getter`, :attr:`setter` |
| 1556 | and :attr:`deleter`, that are decorators providing useful shortcuts |
| 1557 | for adding a getter, setter or deleter function to an existing |
| 1558 | property. You would use them like this:: |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 1559 | |
| 1560 | class C(object): |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1561 | @property |
| 1562 | def x(self): |
| 1563 | return self._x |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 1564 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1565 | @x.setter |
| 1566 | def x(self, value): |
| 1567 | self._x = value |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 1568 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1569 | @x.deleter |
| 1570 | def x(self): |
| 1571 | del self._x |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 1572 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 1573 | class D(C): |
| 1574 | @C.x.getter |
| 1575 | def x(self): |
| 1576 | return self._x * 2 |
| 1577 | |
| 1578 | @x.setter |
| 1579 | def x(self, value): |
| 1580 | self._x = value / 2 |
| 1581 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1582 | * Several methods of the built-in set types now accept multiple iterables: |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1583 | :meth:`intersection`, |
| 1584 | :meth:`intersection_update`, |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1585 | :meth:`union`, :meth:`update`, |
| 1586 | :meth:`difference` and :meth:`difference_update`. |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 1587 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1588 | :: |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1589 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1590 | >>> s=set('1234567890') |
| 1591 | >>> s.intersection('abc123', 'cdf246') # Intersection between all inputs |
| 1592 | set(['2']) |
| 1593 | >>> s.difference('246', '789') |
| 1594 | set(['1', '0', '3', '5']) |
| 1595 | |
| 1596 | (Contributed by Raymond Hettinger.) |
| 1597 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1598 | * Many floating-point features were added. The :func:`float` function |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1599 | will now turn the string ``nan`` into an |
| 1600 | IEEE 754 Not A Number value, and ``+inf`` and ``-inf`` into |
| 1601 | positive or negative infinity. This works on any platform with |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1602 | IEEE 754 semantics. (Contributed by Christian Heimes; :issue:`1635`.) |
Christian Heimes | a34706f | 2008-01-04 03:06:10 +0000 | [diff] [blame] | 1603 | |
Christian Heimes | 3f419af | 2008-01-04 03:08:33 +0000 | [diff] [blame] | 1604 | Other functions in the :mod:`math` module, :func:`isinf` and |
| 1605 | :func:`isnan`, return true if their floating-point argument is |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1606 | infinite or Not A Number. (:issue:`1640`) |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 1607 | |
Georg Brandl | 734e268 | 2008-08-12 08:18:18 +0000 | [diff] [blame] | 1608 | Conversion functions were added to convert floating-point numbers |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1609 | into hexadecimal strings (:issue:`3008`). These functions |
Georg Brandl | 734e268 | 2008-08-12 08:18:18 +0000 | [diff] [blame] | 1610 | convert floats to and from a string representation without |
| 1611 | introducing rounding errors from the conversion between decimal and |
| 1612 | binary. Floats have a :meth:`hex` method that returns a string |
| 1613 | representation, and the ``float.fromhex()`` method converts a string |
| 1614 | back into a number:: |
| 1615 | |
| 1616 | >>> a = 3.75 |
| 1617 | >>> a.hex() |
| 1618 | '0x1.e000000000000p+1' |
| 1619 | >>> float.fromhex('0x1.e000000000000p+1') |
| 1620 | 3.75 |
| 1621 | >>> b=1./3 |
| 1622 | >>> b.hex() |
| 1623 | '0x1.5555555555555p-2' |
Mark Dickinson | 65fe25e | 2008-07-16 11:30:51 +0000 | [diff] [blame] | 1624 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1625 | * A numerical nicety: when creating a complex number from two floats |
| 1626 | on systems that support signed zeros (-0 and +0), the |
| 1627 | :func:`complex` constructor will now preserve the sign |
| 1628 | of the zero. (Fixed by Mark T. Dickinson; :issue:`1507`.) |
Christian Heimes | 3f419af | 2008-01-04 03:08:33 +0000 | [diff] [blame] | 1629 | |
Benjamin Peterson | dcc1e11 | 2008-09-03 22:22:18 +0000 | [diff] [blame] | 1630 | * Classes that inherit a :meth:`__hash__` method from a parent class |
| 1631 | can set ``__hash__ = None`` to indicate that the class isn't |
| 1632 | hashable. This will make ``hash(obj)`` raise a :exc:`TypeError` |
| 1633 | and the class will not be indicated as implementing the |
| 1634 | :class:`Hashable` ABC. |
| 1635 | |
| 1636 | You should do this when you've defined a :meth:`__cmp__` or |
| 1637 | :meth:`__eq__` method that compares objects by their value rather |
| 1638 | than by identity. All objects have a default hash method that uses |
| 1639 | ``id(obj)`` as the hash value. There's no tidy way to remove the |
| 1640 | :meth:`__hash__` method inherited from a parent class, so |
| 1641 | assigning ``None`` was implemented as an override. At the |
| 1642 | C level, extensions can set ``tp_hash`` to |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1643 | :c:func:`PyObject_HashNotImplemented`. |
Benjamin Peterson | dcc1e11 | 2008-09-03 22:22:18 +0000 | [diff] [blame] | 1644 | (Fixed by Nick Coghlan and Amaury Forgeot d'Arc; :issue:`2235`.) |
| 1645 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1646 | * The :exc:`GeneratorExit` exception now subclasses |
| 1647 | :exc:`BaseException` instead of :exc:`Exception`. This means |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 1648 | that an exception handler that does ``except Exception:`` |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1649 | will not inadvertently catch :exc:`GeneratorExit`. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1650 | (Contributed by Chad Austin; :issue:`1537`.) |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 1651 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1652 | * Generator objects now have a :attr:`gi_code` attribute that refers to |
| 1653 | the original code object backing the generator. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1654 | (Contributed by Collin Winter; :issue:`1473257`.) |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 1655 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 1656 | * The :func:`compile` built-in function now accepts keyword arguments |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1657 | as well as positional parameters. (Contributed by Thomas Wouters; |
| 1658 | :issue:`1444529`.) |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 1659 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1660 | * The :func:`complex` constructor now accepts strings containing |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1661 | parenthesized complex numbers, meaning that ``complex(repr(cplx))`` |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 1662 | will now round-trip values. For example, ``complex('(3+4j)')`` |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1663 | now returns the value (3+4j). (:issue:`1491866`) |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 1664 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1665 | * The string :meth:`translate` method now accepts ``None`` as the |
| 1666 | translation table parameter, which is treated as the identity |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 1667 | transformation. This makes it easier to carry out operations |
Georg Brandl | 3dbca81 | 2008-07-23 16:10:53 +0000 | [diff] [blame] | 1668 | that only delete characters. (Contributed by Bengt Richter and |
| 1669 | implemented by Raymond Hettinger; :issue:`1193128`.) |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 1670 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 1671 | * The built-in :func:`dir` function now checks for a :meth:`__dir__` |
| 1672 | method on the objects it receives. This method must return a list |
| 1673 | of strings containing the names of valid attributes for the object, |
| 1674 | and lets the object control the value that :func:`dir` produces. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1675 | Objects that have :meth:`__getattr__` or :meth:`__getattribute__` |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 1676 | methods can use this to advertise pseudo-attributes they will honor. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1677 | (:issue:`1591665`) |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 1678 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 1679 | * Instance method objects have new attributes for the object and function |
| 1680 | comprising the method; the new synonym for :attr:`im_self` is |
| 1681 | :attr:`__self__`, and :attr:`im_func` is also available as :attr:`__func__`. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1682 | The old names are still supported in Python 2.6, but are gone in 3.0. |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 1683 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 1684 | * An obscure change: when you use the :func:`locals` function inside a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1685 | :keyword:`class` statement, the resulting dictionary no longer returns free |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1686 | variables. (Free variables, in this case, are variables referenced in the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1687 | :keyword:`class` statement that aren't attributes of the class.) |
| 1688 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 1689 | .. ====================================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1690 | |
| 1691 | |
| 1692 | Optimizations |
| 1693 | ------------- |
| 1694 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 1695 | * The :mod:`warnings` module has been rewritten in C. This makes |
| 1696 | it possible to invoke warnings from the parser, and may also |
| 1697 | make the interpreter's startup faster. |
| 1698 | (Contributed by Neal Norwitz and Brett Cannon; :issue:`1631171`.) |
| 1699 | |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 1700 | * Type objects now have a cache of methods that can reduce |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1701 | the work required to find the correct method implementation |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 1702 | for a particular class; once cached, the interpreter doesn't need to |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1703 | traverse base classes to figure out the right method to call. |
| 1704 | The cache is cleared if a base class or the class itself is modified, |
| 1705 | so the cache should remain correct even in the face of Python's dynamic |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 1706 | nature. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1707 | (Original optimization implemented by Armin Rigo, updated for |
| 1708 | Python 2.6 by Kevin Jacobs; :issue:`1700288`.) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 1709 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1710 | By default, this change is only applied to types that are included with |
| 1711 | the Python core. Extension modules may not necessarily be compatible with |
| 1712 | this cache, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1713 | so they must explicitly add :c:macro:`Py_TPFLAGS_HAVE_VERSION_TAG` |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1714 | to the module's ``tp_flags`` field to enable the method cache. |
| 1715 | (To be compatible with the method cache, the extension module's code |
| 1716 | must not directly access and modify the ``tp_dict`` member of |
| 1717 | any of the types it implements. Most modules don't do this, |
| 1718 | but it's impossible for the Python interpreter to determine that. |
| 1719 | See :issue:`1878` for some discussion.) |
| 1720 | |
| 1721 | * Function calls that use keyword arguments are significantly faster |
| 1722 | by doing a quick pointer comparison, usually saving the time of a |
| 1723 | full string comparison. (Contributed by Raymond Hettinger, after an |
| 1724 | initial implementation by Antoine Pitrou; :issue:`1819`.) |
Georg Brandl | 734e268 | 2008-08-12 08:18:18 +0000 | [diff] [blame] | 1725 | |
Christian Heimes | 3f419af | 2008-01-04 03:08:33 +0000 | [diff] [blame] | 1726 | * All of the functions in the :mod:`struct` module have been rewritten in |
| 1727 | C, thanks to work at the Need For Speed sprint. |
| 1728 | (Contributed by Raymond Hettinger.) |
| 1729 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1730 | * Some of the standard built-in types now set a bit in their type |
| 1731 | objects. This speeds up checking whether an object is a subclass of |
| 1732 | one of these types. (Contributed by Neal Norwitz.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1733 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 1734 | * Unicode strings now use faster code for detecting |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1735 | whitespace and line breaks; this speeds up the :meth:`split` method |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1736 | by about 25% and :meth:`splitlines` by 35%. |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 1737 | (Contributed by Antoine Pitrou.) Memory usage is reduced |
| 1738 | by using pymalloc for the Unicode string's data. |
| 1739 | |
| 1740 | * The ``with`` statement now stores the :meth:`__exit__` method on the stack, |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 1741 | producing a small speedup. (Implemented by Jeffrey Yasskin.) |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1742 | |
| 1743 | * To reduce memory usage, the garbage collector will now clear internal |
| 1744 | free lists when garbage-collecting the highest generation of objects. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1745 | This may return memory to the operating system sooner. |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 1746 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 1747 | .. ====================================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1748 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1749 | .. _new-26-interpreter: |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1750 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1751 | Interpreter Changes |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1752 | ------------------------------- |
| 1753 | |
| 1754 | Two command-line options have been reserved for use by other Python |
| 1755 | implementations. The :option:`-J` switch has been reserved for use by |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1756 | Jython for Jython-specific options, such as switches that are passed to |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1757 | the underlying JVM. :option:`-X` has been reserved for options |
| 1758 | specific to a particular implementation of Python such as CPython, |
| 1759 | Jython, or IronPython. If either option is used with Python 2.6, the |
| 1760 | interpreter will report that the option isn't currently used. |
| 1761 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1762 | Python can now be prevented from writing :file:`.pyc` or :file:`.pyo` |
| 1763 | files by supplying the :option:`-B` switch to the Python interpreter, |
| 1764 | or by setting the :envvar:`PYTHONDONTWRITEBYTECODE` environment |
| 1765 | variable before running the interpreter. This setting is available to |
| 1766 | Python programs as the ``sys.dont_write_bytecode`` variable, and |
| 1767 | Python code can change the value to modify the interpreter's |
| 1768 | behaviour. (Contributed by Neal Norwitz and Georg Brandl.) |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1769 | |
| 1770 | The encoding used for standard input, output, and standard error can |
| 1771 | be specified by setting the :envvar:`PYTHONIOENCODING` environment |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1772 | variable before running the interpreter. The value should be a string |
| 1773 | in the form ``<encoding>`` or ``<encoding>:<errorhandler>``. |
| 1774 | The *encoding* part specifies the encoding's name, e.g. ``utf-8`` or |
| 1775 | ``latin-1``; the optional *errorhandler* part specifies |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1776 | what to do with characters that can't be handled by the encoding, |
| 1777 | and should be one of "error", "ignore", or "replace". (Contributed |
Antoine Pitrou | fbd4f80 | 2012-08-11 16:51:50 +0200 | [diff] [blame] | 1778 | by Martin von Löwis.) |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1779 | |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1780 | .. ====================================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1781 | |
Georg Brandl | 8bd0546 | 2009-11-18 18:53:54 +0000 | [diff] [blame] | 1782 | New and Improved Modules |
| 1783 | ======================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1784 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1785 | As in every release, Python's standard library received a number of |
| 1786 | enhancements and bug fixes. Here's a partial list of the most notable |
| 1787 | changes, sorted alphabetically by module name. Consult the |
| 1788 | :file:`Misc/NEWS` file in the source tree for a more complete list of |
| 1789 | changes, or look through the Subversion logs for all the details. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1790 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1791 | * The :mod:`asyncore` and :mod:`asynchat` modules are |
| 1792 | being actively maintained again, and a number of patches and bugfixes |
| 1793 | were applied. (Maintained by Josiah Carlson; see :issue:`1736190` for |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1794 | one patch.) |
| 1795 | |
Antoine Pitrou | fbd4f80 | 2012-08-11 16:51:50 +0200 | [diff] [blame] | 1796 | * The :mod:`bsddb` module also has a new maintainer, Jesús Cea Avión, and the package |
Benjamin Peterson | 5478b47 | 2008-09-17 22:25:09 +0000 | [diff] [blame] | 1797 | is now available as a standalone package. The web page for the package is |
| 1798 | `www.jcea.es/programacion/pybsddb.htm |
| 1799 | <http://www.jcea.es/programacion/pybsddb.htm>`__. |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 1800 | The plan is to remove the package from the standard library |
| 1801 | in Python 3.0, because its pace of releases is much more frequent than |
| 1802 | Python's. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1803 | |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 1804 | The :mod:`bsddb.dbshelve` module now uses the highest pickling protocol |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1805 | available, instead of restricting itself to protocol 1. |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 1806 | (Contributed by W. Barnes.) |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1807 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1808 | * The :mod:`cgi` module will now read variables from the query string |
| 1809 | of an HTTP POST request. This makes it possible to use form actions |
| 1810 | with URLs that include query strings such as |
| 1811 | "/cgi-bin/add.py?category=1". (Contributed by Alexandre Fiori and |
| 1812 | Nubis; :issue:`1817`.) |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 1813 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 1814 | The :func:`parse_qs` and :func:`parse_qsl` functions have been |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 1815 | relocated from the :mod:`cgi` module to the :mod:`urlparse` module. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 1816 | The versions still available in the :mod:`cgi` module will |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 1817 | trigger :exc:`PendingDeprecationWarning` messages in 2.6 |
| 1818 | (:issue:`600362`). |
| 1819 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1820 | * The :mod:`cmath` module underwent extensive revision, |
| 1821 | contributed by Mark Dickinson and Christian Heimes. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1822 | Five new functions were added: |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 1823 | |
| 1824 | * :func:`polar` converts a complex number to polar form, returning |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1825 | the modulus and argument of the complex number. |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 1826 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1827 | * :func:`rect` does the opposite, turning a modulus, argument pair |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 1828 | back into the corresponding complex number. |
| 1829 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1830 | * :func:`phase` returns the argument (also called the angle) of a complex |
| 1831 | number. |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 1832 | |
| 1833 | * :func:`isnan` returns True if either |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1834 | the real or imaginary part of its argument is a NaN. |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 1835 | |
| 1836 | * :func:`isinf` returns True if either the real or imaginary part of |
| 1837 | its argument is infinite. |
| 1838 | |
| 1839 | The revisions also improved the numerical soundness of the |
| 1840 | :mod:`cmath` module. For all functions, the real and imaginary |
| 1841 | parts of the results are accurate to within a few units of least |
| 1842 | precision (ulps) whenever possible. See :issue:`1381` for the |
| 1843 | details. The branch cuts for :func:`asinh`, :func:`atanh`: and |
| 1844 | :func:`atan` have also been corrected. |
| 1845 | |
| 1846 | The tests for the module have been greatly expanded; nearly 2000 new |
| 1847 | test cases exercise the algebraic functions. |
| 1848 | |
| 1849 | On IEEE 754 platforms, the :mod:`cmath` module now handles IEEE 754 |
| 1850 | special values and floating-point exceptions in a manner consistent |
| 1851 | with Annex 'G' of the C99 standard. |
| 1852 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1853 | * A new data type in the :mod:`collections` module: :class:`namedtuple(typename, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1854 | fieldnames)` is a factory function that creates subclasses of the standard tuple |
| 1855 | whose fields are accessible by name as well as index. For example:: |
| 1856 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1857 | >>> var_type = collections.namedtuple('variable', |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1858 | ... 'id name type size') |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1859 | >>> # Names are separated by spaces or commas. |
| 1860 | >>> # 'id, name, type, size' would also work. |
Christian Heimes | 0449f63 | 2007-12-15 01:27:15 +0000 | [diff] [blame] | 1861 | >>> var_type._fields |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1862 | ('id', 'name', 'type', 'size') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1863 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1864 | >>> var = var_type(1, 'frequency', 'int', 4) |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 1865 | >>> print var[0], var.id # Equivalent |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1866 | 1 1 |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 1867 | >>> print var[2], var.type # Equivalent |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1868 | int int |
Christian Heimes | 0449f63 | 2007-12-15 01:27:15 +0000 | [diff] [blame] | 1869 | >>> var._asdict() |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1870 | {'size': 4, 'type': 'int', 'id': 1, 'name': 'frequency'} |
Christian Heimes | a156e09 | 2008-02-16 07:38:31 +0000 | [diff] [blame] | 1871 | >>> v2 = var._replace(name='amplitude') |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1872 | >>> v2 |
| 1873 | variable(id=1, name='amplitude', type='int', size=4) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1874 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1875 | Several places in the standard library that returned tuples have |
| 1876 | been modified to return :class:`namedtuple` instances. For example, |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1877 | the :meth:`Decimal.as_tuple` method now returns a named tuple with |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 1878 | :attr:`sign`, :attr:`digits`, and :attr:`exponent` fields. |
| 1879 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1880 | (Contributed by Raymond Hettinger.) |
| 1881 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1882 | * Another change to the :mod:`collections` module is that the |
Christian Heimes | 895627f | 2007-12-08 17:28:33 +0000 | [diff] [blame] | 1883 | :class:`deque` type now supports an optional *maxlen* parameter; |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1884 | if supplied, the deque's size will be restricted to no more |
Christian Heimes | 895627f | 2007-12-08 17:28:33 +0000 | [diff] [blame] | 1885 | than *maxlen* items. Adding more items to a full deque causes |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1886 | old items to be discarded. |
| 1887 | |
| 1888 | :: |
| 1889 | |
| 1890 | >>> from collections import deque |
| 1891 | >>> dq=deque(maxlen=3) |
| 1892 | >>> dq |
| 1893 | deque([], maxlen=3) |
| 1894 | >>> dq.append(1) ; dq.append(2) ; dq.append(3) |
| 1895 | >>> dq |
| 1896 | deque([1, 2, 3], maxlen=3) |
| 1897 | >>> dq.append(4) |
| 1898 | >>> dq |
| 1899 | deque([2, 3, 4], maxlen=3) |
| 1900 | |
| 1901 | (Contributed by Raymond Hettinger.) |
| 1902 | |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 1903 | * The :mod:`Cookie` module's :class:`Morsel` objects now support an |
| 1904 | :attr:`httponly` attribute. In some browsers. cookies with this attribute |
| 1905 | set cannot be accessed or manipulated by JavaScript code. |
| 1906 | (Contributed by Arvin Schnell; :issue:`1638033`.) |
| 1907 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1908 | * A new window method in the :mod:`curses` module, |
| 1909 | :meth:`chgat`, changes the display attributes for a certain number of |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1910 | characters on a single line. (Contributed by Fabian Kreutz.) |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 1911 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1912 | :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1913 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1914 | # Boldface text starting at y=0,x=21 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1915 | # and affecting the rest of the line. |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1916 | stdscr.chgat(0, 21, curses.A_BOLD) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1917 | |
Christian Heimes | fdab48e | 2008-01-20 09:06:41 +0000 | [diff] [blame] | 1918 | The :class:`Textbox` class in the :mod:`curses.textpad` module |
| 1919 | now supports editing in insert mode as well as overwrite mode. |
| 1920 | Insert mode is enabled by supplying a true value for the *insert_mode* |
| 1921 | parameter when creating the :class:`Textbox` instance. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1922 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 1923 | * The :mod:`datetime` module's :meth:`strftime` methods now support a |
| 1924 | ``%f`` format code that expands to the number of microseconds in the |
| 1925 | object, zero-padded on |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1926 | the left to six places. (Contributed by Skip Montanaro; :issue:`1158`.) |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 1927 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1928 | * The :mod:`decimal` module was updated to version 1.66 of |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1929 | `the General Decimal Specification <http://www2.hursley.ibm.com/decimal/decarith.html>`__. New features |
| 1930 | include some methods for some basic mathematical functions such as |
| 1931 | :meth:`exp` and :meth:`log10`:: |
| 1932 | |
| 1933 | >>> Decimal(1).exp() |
| 1934 | Decimal("2.718281828459045235360287471") |
| 1935 | >>> Decimal("2.7182818").ln() |
| 1936 | Decimal("0.9999999895305022877376682436") |
| 1937 | >>> Decimal(1000).log10() |
| 1938 | Decimal("3") |
| 1939 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1940 | The :meth:`as_tuple` method of :class:`Decimal` objects now returns a |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 1941 | named tuple with :attr:`sign`, :attr:`digits`, and :attr:`exponent` fields. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1942 | |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 1943 | (Implemented by Facundo Batista and Mark Dickinson. Named tuple |
| 1944 | support added by Raymond Hettinger.) |
| 1945 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1946 | * The :mod:`difflib` module's :class:`SequenceMatcher` class |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1947 | now returns named tuples representing matches, |
| 1948 | with :attr:`a`, :attr:`b`, and :attr:`size` attributes. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 1949 | (Contributed by Raymond Hettinger.) |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1950 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1951 | * An optional ``timeout`` parameter, specifying a timeout measured in |
| 1952 | seconds, was added to the :class:`ftplib.FTP` class constructor as |
| 1953 | well as the :meth:`connect` method. (Added by Facundo Batista.) |
| 1954 | Also, the :class:`FTP` class's :meth:`storbinary` and |
| 1955 | :meth:`storlines` now take an optional *callback* parameter that |
| 1956 | will be called with each block of data after the data has been sent. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1957 | (Contributed by Phil Schwartz; :issue:`1221598`.) |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 1958 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1959 | * The :func:`reduce` built-in function is also available in the |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1960 | :mod:`functools` module. In Python 3.0, the builtin has been |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1961 | dropped and :func:`reduce` is only available from :mod:`functools`; |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1962 | currently there are no plans to drop the builtin in the 2.x series. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1963 | (Patched by Christian Heimes; :issue:`1739906`.) |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1964 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 1965 | * When possible, the :mod:`getpass` module will now use |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1966 | :file:`/dev/tty` to print a prompt message and read the password, |
| 1967 | falling back to standard error and standard input. If the |
| 1968 | password may be echoed to the terminal, a warning is printed before |
| 1969 | the prompt is displayed. (Contributed by Gregory P. Smith.) |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 1970 | |
| 1971 | * The :func:`glob.glob` function can now return Unicode filenames if |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 1972 | a Unicode path was used and Unicode filenames are matched within the |
| 1973 | directory. (:issue:`1001604`) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1974 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1975 | * A new function in the :mod:`heapq` module, ``merge(iter1, iter2, ...)``, |
| 1976 | takes any number of iterables returning data in sorted |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 1977 | order, and returns a new generator that returns the contents of all |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 1978 | the iterators, also in sorted order. For example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1979 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1980 | >>> list(heapq.merge([1, 3, 5, 9], [2, 8, 16])) |
| 1981 | [1, 2, 3, 5, 8, 9, 16] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1982 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 1983 | Another new function, ``heappushpop(heap, item)``, |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1984 | pushes *item* onto *heap*, then pops off and returns the smallest item. |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 1985 | This is more efficient than making a call to :func:`heappush` and then |
| 1986 | :func:`heappop`. |
| 1987 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 1988 | :mod:`heapq` is now implemented to only use less-than comparison, |
| 1989 | instead of the less-than-or-equal comparison it previously used. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1990 | This makes :mod:`heapq`'s usage of a type match the |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 1991 | :meth:`list.sort` method. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1992 | (Contributed by Raymond Hettinger.) |
| 1993 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 1994 | * An optional ``timeout`` parameter, specifying a timeout measured in |
| 1995 | seconds, was added to the :class:`httplib.HTTPConnection` and |
| 1996 | :class:`HTTPSConnection` class constructors. (Added by Facundo |
| 1997 | Batista.) |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 1998 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 1999 | * Most of the :mod:`inspect` module's functions, such as |
| 2000 | :func:`getmoduleinfo` and :func:`getargs`, now return named tuples. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 2001 | In addition to behaving like tuples, the elements of the return value |
| 2002 | can also be accessed as attributes. |
| 2003 | (Contributed by Raymond Hettinger.) |
| 2004 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2005 | Some new functions in the module include |
| 2006 | :func:`isgenerator`, :func:`isgeneratorfunction`, |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2007 | and :func:`isabstract`. |
| 2008 | |
| 2009 | * The :mod:`itertools` module gained several new functions. |
| 2010 | |
| 2011 | ``izip_longest(iter1, iter2, ...[, fillvalue])`` makes tuples from |
| 2012 | each of the elements; if some of the iterables are shorter than |
| 2013 | others, the missing values are set to *fillvalue*. For example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 2014 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2015 | >>> tuple(itertools.izip_longest([1,2,3], [1,2,3,4,5])) |
| 2016 | ((1, 1), (2, 2), (3, 3), (None, 4), (None, 5)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 2017 | |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2018 | ``product(iter1, iter2, ..., [repeat=N])`` returns the Cartesian product |
| 2019 | of the supplied iterables, a set of tuples containing |
| 2020 | every possible combination of the elements returned from each iterable. :: |
| 2021 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2022 | >>> list(itertools.product([1,2,3], [4,5,6])) |
| 2023 | [(1, 4), (1, 5), (1, 6), |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 2024 | (2, 4), (2, 5), (2, 6), |
| 2025 | (3, 4), (3, 5), (3, 6)] |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2026 | |
| 2027 | The optional *repeat* keyword argument is used for taking the |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2028 | product of an iterable or a set of iterables with themselves, |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2029 | repeated *N* times. With a single iterable argument, *N*-tuples |
| 2030 | are returned:: |
| 2031 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2032 | >>> list(itertools.product([1,2], repeat=3)) |
| 2033 | [(1, 1, 1), (1, 1, 2), (1, 2, 1), (1, 2, 2), |
| 2034 | (2, 1, 1), (2, 1, 2), (2, 2, 1), (2, 2, 2)] |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2035 | |
| 2036 | With two iterables, *2N*-tuples are returned. :: |
| 2037 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2038 | >>> list(itertools.product([1,2], [3,4], repeat=2)) |
| 2039 | [(1, 3, 1, 3), (1, 3, 1, 4), (1, 3, 2, 3), (1, 3, 2, 4), |
| 2040 | (1, 4, 1, 3), (1, 4, 1, 4), (1, 4, 2, 3), (1, 4, 2, 4), |
| 2041 | (2, 3, 1, 3), (2, 3, 1, 4), (2, 3, 2, 3), (2, 3, 2, 4), |
| 2042 | (2, 4, 1, 3), (2, 4, 1, 4), (2, 4, 2, 3), (2, 4, 2, 4)] |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2043 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 2044 | ``combinations(iterable, r)`` returns sub-sequences of length *r* from |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2045 | the elements of *iterable*. :: |
| 2046 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2047 | >>> list(itertools.combinations('123', 2)) |
| 2048 | [('1', '2'), ('1', '3'), ('2', '3')] |
| 2049 | >>> list(itertools.combinations('123', 3)) |
| 2050 | [('1', '2', '3')] |
| 2051 | >>> list(itertools.combinations('1234', 3)) |
| 2052 | [('1', '2', '3'), ('1', '2', '4'), |
| 2053 | ('1', '3', '4'), ('2', '3', '4')] |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2054 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2055 | ``permutations(iter[, r])`` returns all the permutations of length *r* of |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2056 | the iterable's elements. If *r* is not specified, it will default to the |
Christian Heimes | 5d8da20 | 2008-05-06 13:58:24 +0000 | [diff] [blame] | 2057 | number of elements produced by the iterable. :: |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2058 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2059 | >>> list(itertools.permutations([1,2,3,4], 2)) |
| 2060 | [(1, 2), (1, 3), (1, 4), |
| 2061 | (2, 1), (2, 3), (2, 4), |
| 2062 | (3, 1), (3, 2), (3, 4), |
| 2063 | (4, 1), (4, 2), (4, 3)] |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2064 | |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 2065 | ``itertools.chain(*iterables)`` is an existing function in |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2066 | :mod:`itertools` that gained a new constructor in Python 2.6. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2067 | ``itertools.chain.from_iterable(iterable)`` takes a single |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2068 | iterable that should return other iterables. :func:`chain` will |
| 2069 | then return all the elements of the first iterable, then |
| 2070 | all the elements of the second, and so on. :: |
| 2071 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2072 | >>> list(itertools.chain.from_iterable([[1,2,3], [4,5,6]])) |
| 2073 | [1, 2, 3, 4, 5, 6] |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2074 | |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2075 | (All contributed by Raymond Hettinger.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 2076 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2077 | * The :mod:`logging` module's :class:`FileHandler` class |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2078 | and its subclasses :class:`WatchedFileHandler`, :class:`RotatingFileHandler`, |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2079 | and :class:`TimedRotatingFileHandler` now |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2080 | have an optional *delay* parameter to their constructors. If *delay* |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2081 | is true, opening of the log file is deferred until the first |
| 2082 | :meth:`emit` call is made. (Contributed by Vinay Sajip.) |
| 2083 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2084 | :class:`TimedRotatingFileHandler` also has a *utc* constructor |
| 2085 | parameter. If the argument is true, UTC time will be used |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2086 | in determining when midnight occurs and in generating filenames; |
| 2087 | otherwise local time will be used. |
| 2088 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2089 | * Several new functions were added to the :mod:`math` module: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 2090 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2091 | * :func:`~math.isinf` and :func:`~math.isnan` determine whether a given float |
| 2092 | is a (positive or negative) infinity or a NaN (Not a Number), respectively. |
| 2093 | |
| 2094 | * :func:`~math.copysign` copies the sign bit of an IEEE 754 number, |
| 2095 | returning the absolute value of *x* combined with the sign bit of |
| 2096 | *y*. For example, ``math.copysign(1, -0.0)`` returns -1.0. |
| 2097 | (Contributed by Christian Heimes.) |
| 2098 | |
| 2099 | * :func:`~math.factorial` computes the factorial of a number. |
| 2100 | (Contributed by Raymond Hettinger; :issue:`2138`.) |
| 2101 | |
| 2102 | * :func:`~math.fsum` adds up the stream of numbers from an iterable, |
| 2103 | and is careful to avoid loss of precision through using partial sums. |
| 2104 | (Contributed by Jean Brouwers, Raymond Hettinger, and Mark Dickinson; |
| 2105 | :issue:`2819`.) |
| 2106 | |
| 2107 | * :func:`~math.acosh`, :func:`~math.asinh` |
| 2108 | and :func:`~math.atanh` compute the inverse hyperbolic functions. |
| 2109 | |
| 2110 | * :func:`~math.log1p` returns the natural logarithm of *1+x* |
| 2111 | (base *e*). |
| 2112 | |
| 2113 | * :func:`trunc` rounds a number toward zero, returning the closest |
| 2114 | :class:`Integral` that's between the function's argument and zero. |
| 2115 | Added as part of the backport of |
| 2116 | `PEP 3141's type hierarchy for numbers <#pep-3141>`__. |
| 2117 | |
| 2118 | * The :mod:`math` module has been improved to give more consistent |
| 2119 | behaviour across platforms, especially with respect to handling of |
| 2120 | floating-point exceptions and IEEE 754 special values. |
| 2121 | |
| 2122 | Whenever possible, the module follows the recommendations of the C99 |
| 2123 | standard about 754's special values. For example, ``sqrt(-1.)`` |
| 2124 | should now give a :exc:`ValueError` across almost all platforms, |
| 2125 | while ``sqrt(float('NaN'))`` should return a NaN on all IEEE 754 |
| 2126 | platforms. Where Annex 'F' of the C99 standard recommends signaling |
| 2127 | 'divide-by-zero' or 'invalid', Python will raise :exc:`ValueError`. |
| 2128 | Where Annex 'F' of the C99 standard recommends signaling 'overflow', |
| 2129 | Python will raise :exc:`OverflowError`. (See :issue:`711019` and |
| 2130 | :issue:`1640`.) |
| 2131 | |
| 2132 | (Contributed by Christian Heimes and Mark Dickinson.) |
| 2133 | |
| 2134 | * :class:`mmap` objects now have a :meth:`rfind` method that searches for a |
| 2135 | substring beginning at the end of the string and searching |
| 2136 | backwards. The :meth:`find` method also gained an *end* parameter |
| 2137 | giving an index at which to stop searching. |
Georg Brandl | fceab5a | 2008-01-19 20:08:23 +0000 | [diff] [blame] | 2138 | (Contributed by John Lenton.) |
| 2139 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2140 | * The :mod:`operator` module gained a |
| 2141 | :func:`methodcaller` function that takes a name and an optional |
| 2142 | set of arguments, returning a callable that will call |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2143 | the named function on any arguments passed to it. For example:: |
| 2144 | |
| 2145 | >>> # Equivalent to lambda s: s.replace('old', 'new') |
| 2146 | >>> replacer = operator.methodcaller('replace', 'old', 'new') |
| 2147 | >>> replacer('old wine in old bottles') |
| 2148 | 'new wine in new bottles' |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2149 | |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2150 | (Contributed by Georg Brandl, after a suggestion by Gregory Petrosyan.) |
| 2151 | |
| 2152 | The :func:`attrgetter` function now accepts dotted names and performs |
| 2153 | the corresponding attribute lookups:: |
| 2154 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2155 | >>> inst_name = operator.attrgetter( |
| 2156 | ... '__class__.__name__') |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2157 | >>> inst_name('') |
| 2158 | 'str' |
| 2159 | >>> inst_name(help) |
| 2160 | '_Helper' |
| 2161 | |
| 2162 | (Contributed by Georg Brandl, after a suggestion by Barry Warsaw.) |
| 2163 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2164 | * The :mod:`os` module now wraps several new system calls. |
| 2165 | ``fchmod(fd, mode)`` and ``fchown(fd, uid, gid)`` change the mode |
| 2166 | and ownership of an opened file, and ``lchmod(path, mode)`` changes |
| 2167 | the mode of a symlink. (Contributed by Georg Brandl and Christian |
| 2168 | Heimes.) |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 2169 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2170 | :func:`chflags` and :func:`lchflags` are wrappers for the |
| 2171 | corresponding system calls (where they're available), changing the |
| 2172 | flags set on a file. Constants for the flag values are defined in |
| 2173 | the :mod:`stat` module; some possible values include |
| 2174 | :const:`UF_IMMUTABLE` to signal the file may not be changed and |
| 2175 | :const:`UF_APPEND` to indicate that data can only be appended to the |
| 2176 | file. (Contributed by M. Levinson.) |
| 2177 | |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 2178 | ``os.closerange(low, high)`` efficiently closes all file descriptors |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2179 | from *low* to *high*, ignoring any errors and not including *high* itself. |
| 2180 | This function is now used by the :mod:`subprocess` module to make starting |
| 2181 | processes faster. (Contributed by Georg Brandl; :issue:`1663329`.) |
| 2182 | |
| 2183 | * The ``os.environ`` object's :meth:`clear` method will now unset the |
| 2184 | environment variables using :func:`os.unsetenv` in addition to clearing |
| 2185 | the object's keys. (Contributed by Martin Horcicka; :issue:`1181`.) |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 2186 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 2187 | * The :func:`os.walk` function now has a ``followlinks`` parameter. If |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2188 | set to True, it will follow symlinks pointing to directories and |
| 2189 | visit the directory's contents. For backward compatibility, the |
| 2190 | parameter's default value is false. Note that the function can fall |
| 2191 | into an infinite recursion if there's a symlink that points to a |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2192 | parent directory. (:issue:`1273829`) |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2193 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 2194 | * In the :mod:`os.path` module, the :func:`splitext` function |
| 2195 | has been changed to not split on leading period characters. |
| 2196 | This produces better results when operating on Unix's dot-files. |
| 2197 | For example, ``os.path.splitext('.ipython')`` |
| 2198 | now returns ``('.ipython', '')`` instead of ``('', '.ipython')``. |
Ezio Melotti | 19192dd | 2010-04-05 13:25:51 +0000 | [diff] [blame] | 2199 | (:issue:`1115886`) |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 2200 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2201 | A new function, ``os.path.relpath(path, start='.')``, returns a relative path |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 2202 | from the ``start`` path, if it's supplied, or from the current |
| 2203 | working directory to the destination ``path``. (Contributed by |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2204 | Richard Barran; :issue:`1339796`.) |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 2205 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2206 | On Windows, :func:`os.path.expandvars` will now expand environment variables |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2207 | given in the form "%var%", and "~user" will be expanded into the |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2208 | user's home directory path. (Contributed by Josiah Carlson; |
| 2209 | :issue:`957650`.) |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2210 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2211 | * The Python debugger provided by the :mod:`pdb` module |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2212 | gained a new command: "run" restarts the Python program being debugged |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 2213 | and can optionally take new command-line arguments for the program. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2214 | (Contributed by Rocky Bernstein; :issue:`1393667`.) |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 2215 | |
Georg Brandl | 8bd0546 | 2009-11-18 18:53:54 +0000 | [diff] [blame] | 2216 | * The :func:`pdb.post_mortem` function, used to begin debugging a |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 2217 | traceback, will now use the traceback returned by :func:`sys.exc_info` |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2218 | if no traceback is supplied. (Contributed by Facundo Batista; |
| 2219 | :issue:`1106316`.) |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 2220 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2221 | * The :mod:`pickletools` module now has an :func:`optimize` function |
| 2222 | that takes a string containing a pickle and removes some unused |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2223 | opcodes, returning a shorter pickle that contains the same data structure. |
| 2224 | (Contributed by Raymond Hettinger.) |
| 2225 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 2226 | * A :func:`get_data` function was added to the :mod:`pkgutil` |
| 2227 | module that returns the contents of resource files included |
| 2228 | with an installed Python package. For example:: |
| 2229 | |
| 2230 | >>> import pkgutil |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2231 | >>> print pkgutil.get_data('test', 'exception_hierarchy.txt') |
| 2232 | BaseException |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 2233 | +-- SystemExit |
| 2234 | +-- KeyboardInterrupt |
| 2235 | +-- GeneratorExit |
| 2236 | +-- Exception |
| 2237 | +-- StopIteration |
| 2238 | +-- StandardError |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2239 | ... |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 2240 | |
| 2241 | (Contributed by Paul Moore; :issue:`2439`.) |
| 2242 | |
Christian Heimes | 2380ac7 | 2008-01-09 00:17:24 +0000 | [diff] [blame] | 2243 | * The :mod:`pyexpat` module's :class:`Parser` objects now allow setting |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2244 | their :attr:`buffer_size` attribute to change the size of the buffer |
Christian Heimes | 2380ac7 | 2008-01-09 00:17:24 +0000 | [diff] [blame] | 2245 | used to hold character data. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2246 | (Contributed by Achim Gaedke; :issue:`1137`.) |
Christian Heimes | 2380ac7 | 2008-01-09 00:17:24 +0000 | [diff] [blame] | 2247 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2248 | * The :mod:`Queue` module now provides queue variants that retrieve entries |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2249 | in different orders. The :class:`PriorityQueue` class stores |
| 2250 | queued items in a heap and retrieves them in priority order, |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 2251 | and :class:`LifoQueue` retrieves the most recently added entries first, |
| 2252 | meaning that it behaves like a stack. |
| 2253 | (Contributed by Raymond Hettinger.) |
| 2254 | |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 2255 | * The :mod:`random` module's :class:`Random` objects can |
| 2256 | now be pickled on a 32-bit system and unpickled on a 64-bit |
| 2257 | system, and vice versa. Unfortunately, this change also means |
| 2258 | that Python 2.6's :class:`Random` objects can't be unpickled correctly |
| 2259 | on earlier versions of Python. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2260 | (Contributed by Shawn Ligocki; :issue:`1727780`.) |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 2261 | |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 2262 | The new ``triangular(low, high, mode)`` function returns random |
| 2263 | numbers following a triangular distribution. The returned values |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2264 | are between *low* and *high*, not including *high* itself, and |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2265 | with *mode* as the most frequently occurring value |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 2266 | in the distribution. (Contributed by Wladmir van der Laan and |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2267 | Raymond Hettinger; :issue:`1681432`.) |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 2268 | |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 2269 | * Long regular expression searches carried out by the :mod:`re` |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2270 | module will check for signals being delivered, so |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2271 | time-consuming searches can now be interrupted. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2272 | (Contributed by Josh Hoyt and Ralf Schmitt; :issue:`846388`.) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 2273 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2274 | The regular expression module is implemented by compiling bytecodes |
| 2275 | for a tiny regex-specific virtual machine. Untrusted code |
| 2276 | could create malicious strings of bytecode directly and cause crashes, |
| 2277 | so Python 2.6 includes a verifier for the regex bytecode. |
| 2278 | (Contributed by Guido van Rossum from work for Google App Engine; |
| 2279 | :issue:`3487`.) |
| 2280 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2281 | * The :mod:`rlcompleter` module's :meth:`Completer.complete()` method |
| 2282 | will now ignore exceptions triggered while evaluating a name. |
| 2283 | (Fixed by Lorenz Quack; :issue:`2250`.) |
| 2284 | |
| 2285 | * The :mod:`sched` module's :class:`scheduler` instances now |
| 2286 | have a read-only :attr:`queue` attribute that returns the |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2287 | contents of the scheduler's queue, represented as a list of |
| 2288 | named tuples with the fields ``(time, priority, action, argument)``. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2289 | (Contributed by Raymond Hettinger; :issue:`1861`.) |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2290 | |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 2291 | * The :mod:`select` module now has wrapper functions |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2292 | for the Linux :c:func:`epoll` and BSD :c:func:`kqueue` system calls. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2293 | :meth:`modify` method was added to the existing :class:`poll` |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 2294 | objects; ``pollobj.modify(fd, eventmask)`` takes a file descriptor |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2295 | or file object and an event mask, modifying the recorded event mask |
| 2296 | for that file. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2297 | (Contributed by Christian Heimes; :issue:`1657`.) |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 2298 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2299 | * The :func:`shutil.copytree` function now has an optional *ignore* argument |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 2300 | that takes a callable object. This callable will receive each directory path |
| 2301 | and a list of the directory's contents, and returns a list of names that |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2302 | will be ignored, not copied. |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 2303 | |
| 2304 | The :mod:`shutil` module also provides an :func:`ignore_patterns` |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 2305 | function for use with this new parameter. :func:`ignore_patterns` |
| 2306 | takes an arbitrary number of glob-style patterns and returns a |
| 2307 | callable that will ignore any files and directories that match any |
| 2308 | of these patterns. The following example copies a directory tree, |
| 2309 | but skips both :file:`.svn` directories and Emacs backup files, |
| 2310 | which have names ending with '~':: |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 2311 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2312 | shutil.copytree('Doc/library', '/tmp/library', |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 2313 | ignore=shutil.ignore_patterns('*~', '.svn')) |
| 2314 | |
| 2315 | (Contributed by Tarek Ziadé; :issue:`2663`.) |
| 2316 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2317 | * Integrating signal handling with GUI handling event loops |
Christian Heimes | 5fb7c2a | 2007-12-24 08:52:31 +0000 | [diff] [blame] | 2318 | like those used by Tkinter or GTk+ has long been a problem; most |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2319 | software ends up polling, waking up every fraction of a second to check |
| 2320 | if any GUI events have occurred. |
Christian Heimes | 5fb7c2a | 2007-12-24 08:52:31 +0000 | [diff] [blame] | 2321 | The :mod:`signal` module can now make this more efficient. |
| 2322 | Calling ``signal.set_wakeup_fd(fd)`` sets a file descriptor |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2323 | to be used; when a signal is received, a byte is written to that |
Christian Heimes | 5fb7c2a | 2007-12-24 08:52:31 +0000 | [diff] [blame] | 2324 | file descriptor. There's also a C-level function, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2325 | :c:func:`PySignal_SetWakeupFd`, for setting the descriptor. |
Christian Heimes | 5fb7c2a | 2007-12-24 08:52:31 +0000 | [diff] [blame] | 2326 | |
| 2327 | Event loops will use this by opening a pipe to create two descriptors, |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 2328 | one for reading and one for writing. The writable descriptor |
Christian Heimes | 5fb7c2a | 2007-12-24 08:52:31 +0000 | [diff] [blame] | 2329 | will be passed to :func:`set_wakeup_fd`, and the readable descriptor |
| 2330 | will be added to the list of descriptors monitored by the event loop via |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2331 | :c:func:`select` or :c:func:`poll`. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2332 | On receiving a signal, a byte will be written and the main event loop |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2333 | will be woken up, avoiding the need to poll. |
Christian Heimes | 5fb7c2a | 2007-12-24 08:52:31 +0000 | [diff] [blame] | 2334 | |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2335 | (Contributed by Adam Olsen; :issue:`1583`.) |
Christian Heimes | 5fb7c2a | 2007-12-24 08:52:31 +0000 | [diff] [blame] | 2336 | |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2337 | The :func:`siginterrupt` function is now available from Python code, |
| 2338 | and allows changing whether signals can interrupt system calls or not. |
| 2339 | (Contributed by Ralf Schmitt.) |
| 2340 | |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 2341 | The :func:`setitimer` and :func:`getitimer` functions have also been |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2342 | added (where they're available). :func:`setitimer` |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 2343 | allows setting interval timers that will cause a signal to be |
| 2344 | delivered to the process after a specified time, measured in |
| 2345 | wall-clock time, consumed process time, or combined process+system |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2346 | time. (Contributed by Guilherme Polo; :issue:`2240`.) |
Neal Norwitz | f5c7c2e | 2008-04-05 04:47:45 +0000 | [diff] [blame] | 2347 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 2348 | * The :mod:`smtplib` module now supports SMTP over SSL thanks to the |
| 2349 | addition of the :class:`SMTP_SSL` class. This class supports an |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2350 | interface identical to the existing :class:`SMTP` class. |
| 2351 | (Contributed by Monty Taylor.) Both class constructors also have an |
| 2352 | optional ``timeout`` parameter that specifies a timeout for the |
| 2353 | initial connection attempt, measured in seconds. (Contributed by |
| 2354 | Facundo Batista.) |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 2355 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2356 | An implementation of the LMTP protocol (:rfc:`2033`) was also added |
| 2357 | to the module. LMTP is used in place of SMTP when transferring |
| 2358 | e-mail between agents that don't manage a mail queue. (LMTP |
| 2359 | implemented by Leif Hedstrom; :issue:`957003`.) |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 2360 | |
Georg Brandl | 8bd0546 | 2009-11-18 18:53:54 +0000 | [diff] [blame] | 2361 | :meth:`SMTP.starttls` now complies with :rfc:`3207` and forgets any |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2362 | knowledge obtained from the server not obtained from the TLS |
| 2363 | negotiation itself. (Patch contributed by Bill Fenner; |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2364 | :issue:`829951`.) |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 2365 | |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 2366 | * The :mod:`socket` module now supports TIPC (http://tipc.sf.net), |
| 2367 | a high-performance non-IP-based protocol designed for use in clustered |
| 2368 | environments. TIPC addresses are 4- or 5-tuples. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2369 | (Contributed by Alberto Bertogli; :issue:`1646`.) |
Georg Brandl | fceab5a | 2008-01-19 20:08:23 +0000 | [diff] [blame] | 2370 | |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 2371 | A new function, :func:`create_connection`, takes an address and |
| 2372 | connects to it using an optional timeout value, returning the |
| 2373 | connected socket object. This function also looks up the address's |
| 2374 | type and connects to it using IPv4 or IPv6 as appropriate. Changing |
| 2375 | your code to use :func:`create_connection` instead of |
| 2376 | ``socket(socket.AF_INET, ...)`` may be all that's required to make |
| 2377 | your code work with IPv6. |
Neal Norwitz | 32dde22 | 2008-04-15 06:43:13 +0000 | [diff] [blame] | 2378 | |
Georg Brandl | fceab5a | 2008-01-19 20:08:23 +0000 | [diff] [blame] | 2379 | * The base classes in the :mod:`SocketServer` module now support |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2380 | calling a :meth:`handle_timeout` method after a span of inactivity |
| 2381 | specified by the server's :attr:`timeout` attribute. (Contributed |
| 2382 | by Michael Pomraning.) The :meth:`serve_forever` method |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 2383 | now takes an optional poll interval measured in seconds, |
| 2384 | controlling how often the server will check for a shutdown request. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2385 | (Contributed by Pedro Werneck and Jeffrey Yasskin; |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2386 | :issue:`742598`, :issue:`1193577`.) |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2387 | |
Antoine Pitrou | fbd4f80 | 2012-08-11 16:51:50 +0200 | [diff] [blame] | 2388 | * The :mod:`sqlite3` module, maintained by Gerhard Häring, |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 2389 | has been updated from version 2.3.2 in Python 2.5 to |
Benjamin Peterson | 5478b47 | 2008-09-17 22:25:09 +0000 | [diff] [blame] | 2390 | version 2.4.1. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 2391 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2392 | * The :mod:`struct` module now supports the C99 :c:type:`_Bool` type, |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2393 | using the format character ``'?'``. |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2394 | (Contributed by David Remahl.) |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 2395 | |
| 2396 | * The :class:`Popen` objects provided by the :mod:`subprocess` module |
| 2397 | now have :meth:`terminate`, :meth:`kill`, and :meth:`send_signal` methods. |
| 2398 | On Windows, :meth:`send_signal` only supports the :const:`SIGTERM` |
| 2399 | signal, and all these methods are aliases for the Win32 API function |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2400 | :c:func:`TerminateProcess`. |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 2401 | (Contributed by Christian Heimes.) |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2402 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2403 | * A new variable in the :mod:`sys` module, :attr:`float_info`, is an |
| 2404 | object containing information derived from the :file:`float.h` file |
| 2405 | about the platform's floating-point support. Attributes of this |
| 2406 | object include :attr:`mant_dig` (number of digits in the mantissa), |
| 2407 | :attr:`epsilon` (smallest difference between 1.0 and the next |
| 2408 | largest value representable), and several others. (Contributed by |
| 2409 | Christian Heimes; :issue:`1534`.) |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 2410 | |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 2411 | Another new variable, :attr:`dont_write_bytecode`, controls whether Python |
| 2412 | writes any :file:`.pyc` or :file:`.pyo` files on importing a module. |
| 2413 | If this variable is true, the compiled files are not written. The |
| 2414 | variable is initially set on start-up by supplying the :option:`-B` |
| 2415 | switch to the Python interpreter, or by setting the |
| 2416 | :envvar:`PYTHONDONTWRITEBYTECODE` environment variable before |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2417 | running the interpreter. Python code can subsequently |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 2418 | change the value of this variable to control whether bytecode files |
| 2419 | are written or not. |
| 2420 | (Contributed by Neal Norwitz and Georg Brandl.) |
| 2421 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2422 | Information about the command-line arguments supplied to the Python |
| 2423 | interpreter is available by reading attributes of a named |
| 2424 | tuple available as ``sys.flags``. For example, the :attr:`verbose` |
| 2425 | attribute is true if Python |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 2426 | was executed in verbose mode, :attr:`debug` is true in debugging mode, etc. |
| 2427 | These attributes are all read-only. |
| 2428 | (Contributed by Christian Heimes.) |
| 2429 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2430 | A new function, :func:`getsizeof`, takes a Python object and returns |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2431 | the amount of memory used by the object, measured in bytes. Built-in |
| 2432 | objects return correct results; third-party extensions may not, |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2433 | but can define a :meth:`__sizeof__` method to return the |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2434 | object's size. |
| 2435 | (Contributed by Robert Schuppenies; :issue:`2898`.) |
| 2436 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2437 | It's now possible to determine the current profiler and tracer functions |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2438 | by calling :func:`sys.getprofile` and :func:`sys.gettrace`. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2439 | (Contributed by Georg Brandl; :issue:`1648`.) |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 2440 | |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 2441 | * The :mod:`tarfile` module now supports POSIX.1-2001 (pax) tarfiles in |
| 2442 | addition to the POSIX.1-1988 (ustar) and GNU tar formats that were |
| 2443 | already supported. The default format is GNU tar; specify the |
| 2444 | ``format`` parameter to open a file using a different format:: |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2445 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2446 | tar = tarfile.open("output.tar", "w", |
| 2447 | format=tarfile.PAX_FORMAT) |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2448 | |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 2449 | The new ``encoding`` and ``errors`` parameters specify an encoding and |
| 2450 | an error handling scheme for character conversions. ``'strict'``, |
| 2451 | ``'ignore'``, and ``'replace'`` are the three standard ways Python can |
| 2452 | handle errors,; |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2453 | ``'utf-8'`` is a special value that replaces bad characters with |
| 2454 | their UTF-8 representation. (Character conversions occur because the |
| 2455 | PAX format supports Unicode filenames, defaulting to UTF-8 encoding.) |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2456 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2457 | The :meth:`TarFile.add` method now accepts an ``exclude`` argument that's |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2458 | a function that can be used to exclude certain filenames from |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2459 | an archive. |
| 2460 | The function must take a filename and return true if the file |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2461 | should be excluded or false if it should be archived. |
| 2462 | The function is applied to both the name initially passed to :meth:`add` |
| 2463 | and to the names of files in recursively-added directories. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2464 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2465 | (All changes contributed by Lars Gustäbel). |
| 2466 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 2467 | * An optional ``timeout`` parameter was added to the |
| 2468 | :class:`telnetlib.Telnet` class constructor, specifying a timeout |
| 2469 | measured in seconds. (Added by Facundo Batista.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 2470 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2471 | * The :class:`tempfile.NamedTemporaryFile` class usually deletes |
| 2472 | the temporary file it created when the file is closed. This |
| 2473 | behaviour can now be changed by passing ``delete=False`` to the |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2474 | constructor. (Contributed by Damien Miller; :issue:`1537850`.) |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2475 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2476 | A new class, :class:`SpooledTemporaryFile`, behaves like |
| 2477 | a temporary file but stores its data in memory until a maximum size is |
| 2478 | exceeded. On reaching that limit, the contents will be written to |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2479 | an on-disk temporary file. (Contributed by Dustin J. Mitchell.) |
| 2480 | |
| 2481 | The :class:`NamedTemporaryFile` and :class:`SpooledTemporaryFile` classes |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2482 | both work as context managers, so you can write |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2483 | ``with tempfile.NamedTemporaryFile() as tmp: ...``. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2484 | (Contributed by Alexander Belopolsky; :issue:`2021`.) |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 2485 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 2486 | * The :mod:`test.test_support` module gained a number |
| 2487 | of context managers useful for writing tests. |
| 2488 | :func:`EnvironmentVarGuard` is a |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2489 | context manager that temporarily changes environment variables and |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2490 | automatically restores them to their old values. |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2491 | |
| 2492 | Another context manager, :class:`TransientResource`, can surround calls |
| 2493 | to resources that may or may not be available; it will catch and |
| 2494 | ignore a specified list of exceptions. For example, |
| 2495 | a network test may ignore certain failures when connecting to an |
| 2496 | external web site:: |
| 2497 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2498 | with test_support.TransientResource(IOError, |
| 2499 | errno=errno.ETIMEDOUT): |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2500 | f = urllib.urlopen('https://sf.net') |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2501 | ... |
| 2502 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 2503 | Finally, :func:`check_warnings` resets the :mod:`warning` module's |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 2504 | warning filters and returns an object that will record all warning |
| 2505 | messages triggered (:issue:`3781`):: |
| 2506 | |
| 2507 | with test_support.check_warnings() as wrec: |
| 2508 | warnings.simplefilter("always") |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2509 | # ... code that triggers a warning ... |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 2510 | assert str(wrec.message) == "function is outdated" |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2511 | assert len(wrec.warnings) == 1, "Multiple warnings raised" |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 2512 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2513 | (Contributed by Brett Cannon.) |
| 2514 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2515 | * The :mod:`textwrap` module can now preserve existing whitespace |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2516 | at the beginnings and ends of the newly-created lines |
| 2517 | by specifying ``drop_whitespace=False`` |
| 2518 | as an argument:: |
| 2519 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2520 | >>> S = """This sentence has a bunch of |
| 2521 | ... extra whitespace.""" |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2522 | >>> print textwrap.fill(S, width=15) |
| 2523 | This sentence |
| 2524 | has a bunch |
| 2525 | of extra |
| 2526 | whitespace. |
| 2527 | >>> print textwrap.fill(S, drop_whitespace=False, width=15) |
| 2528 | This sentence |
| 2529 | has a bunch |
| 2530 | of extra |
| 2531 | whitespace. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2532 | >>> |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2533 | |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2534 | (Contributed by Dwayne Bailey; :issue:`1581073`.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 2535 | |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 2536 | * The :mod:`threading` module API is being changed to use properties |
| 2537 | such as :attr:`daemon` instead of :meth:`setDaemon` and |
| 2538 | :meth:`isDaemon` methods, and some methods have been renamed to use |
| 2539 | underscores instead of camel-case; for example, the |
| 2540 | :meth:`activeCount` method is renamed to :meth:`active_count`. Both |
| 2541 | the 2.6 and 3.0 versions of the module support the same properties |
| 2542 | and renamed methods, but don't remove the old methods. No date has been set |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 2543 | for the deprecation of the old APIs in Python 3.x; the old APIs won't |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 2544 | be removed in any 2.x version. |
Benjamin Peterson | dcc1e11 | 2008-09-03 22:22:18 +0000 | [diff] [blame] | 2545 | (Carried out by several people, most notably Benjamin Peterson.) |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2546 | |
| 2547 | The :mod:`threading` module's :class:`Thread` objects |
| 2548 | gained an :attr:`ident` property that returns the thread's |
| 2549 | identifier, a nonzero integer. (Contributed by Gregory P. Smith; |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2550 | :issue:`2871`.) |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2551 | |
| 2552 | * The :mod:`timeit` module now accepts callables as well as strings |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 2553 | for the statement being timed and for the setup code. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2554 | Two convenience functions were added for creating |
| 2555 | :class:`Timer` instances: |
| 2556 | ``repeat(stmt, setup, time, repeat, number)`` and |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 2557 | ``timeit(stmt, setup, time, number)`` create an instance and call |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2558 | the corresponding method. (Contributed by Erik Demaine; |
| 2559 | :issue:`1533909`.) |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 2560 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2561 | * The :mod:`Tkinter` module now accepts lists and tuples for options, |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2562 | separating the elements by spaces before passing the resulting value to |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2563 | Tcl/Tk. |
| 2564 | (Contributed by Guilherme Polo; :issue:`2906`.) |
| 2565 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2566 | * The :mod:`turtle` module for turtle graphics was greatly enhanced by |
| 2567 | Gregor Lingl. New features in the module include: |
| 2568 | |
| 2569 | * Better animation of turtle movement and rotation. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2570 | * Control over turtle movement using the new :meth:`delay`, |
| 2571 | :meth:`tracer`, and :meth:`speed` methods. |
| 2572 | * The ability to set new shapes for the turtle, and to |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2573 | define a new coordinate system. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2574 | * Turtles now have an :meth:`undo()` method that can roll back actions. |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2575 | * Simple support for reacting to input events such as mouse and keyboard |
| 2576 | activity, making it possible to write simple games. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2577 | * A :file:`turtle.cfg` file can be used to customize the starting appearance |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2578 | of the turtle's screen. |
| 2579 | * The module's docstrings can be replaced by new docstrings that have been |
| 2580 | translated into another language. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2581 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2582 | (:issue:`1513695`) |
| 2583 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2584 | * An optional ``timeout`` parameter was added to the |
| 2585 | :func:`urllib.urlopen` function and the |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2586 | :class:`urllib.ftpwrapper` class constructor, as well as the |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2587 | :func:`urllib2.urlopen` function. The parameter specifies a timeout |
| 2588 | measured in seconds. For example:: |
| 2589 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2590 | >>> u = urllib2.urlopen("http://slow.example.com", |
| 2591 | timeout=3) |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2592 | Traceback (most recent call last): |
| 2593 | ... |
| 2594 | urllib2.URLError: <urlopen error timed out> |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2595 | >>> |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2596 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2597 | (Added by Facundo Batista.) |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 2598 | |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 2599 | * The Unicode database provided by the :mod:`unicodedata` module |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 2600 | has been updated to version 5.1.0. (Updated by |
Antoine Pitrou | fbd4f80 | 2012-08-11 16:51:50 +0200 | [diff] [blame] | 2601 | Martin von Löwis; :issue:`3811`.) |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 2602 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2603 | * The :mod:`warnings` module's :func:`formatwarning` and :func:`showwarning` |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 2604 | gained an optional *line* argument that can be used to supply the |
| 2605 | line of source code. (Added as part of :issue:`1631171`, which re-implemented |
| 2606 | part of the :mod:`warnings` module in C code.) |
| 2607 | |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 2608 | A new function, :func:`catch_warnings`, is a context manager |
| 2609 | intended for testing purposes that lets you temporarily modify the |
| 2610 | warning filters and then restore their original values (:issue:`3781`). |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 2611 | |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 2612 | * The XML-RPC :class:`SimpleXMLRPCServer` and :class:`DocXMLRPCServer` |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 2613 | classes can now be prevented from immediately opening and binding to |
| 2614 | their socket by passing True as the ``bind_and_activate`` |
| 2615 | constructor parameter. This can be used to modify the instance's |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2616 | :attr:`allow_reuse_address` attribute before calling the |
| 2617 | :meth:`server_bind` and :meth:`server_activate` methods to |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 2618 | open the socket and begin listening for connections. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2619 | (Contributed by Peter Parente; :issue:`1599845`.) |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 2620 | |
| 2621 | :class:`SimpleXMLRPCServer` also has a :attr:`_send_traceback_header` |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2622 | attribute; if true, the exception and formatted traceback are returned |
| 2623 | as HTTP headers "X-Exception" and "X-Traceback". This feature is |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 2624 | for debugging purposes only and should not be used on production servers |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2625 | because the tracebacks might reveal passwords or other sensitive |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2626 | information. (Contributed by Alan McIntyre as part of his |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 2627 | project for Google's Summer of Code 2007.) |
| 2628 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 2629 | * The :mod:`xmlrpclib` module no longer automatically converts |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2630 | :class:`datetime.date` and :class:`datetime.time` to the |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 2631 | :class:`xmlrpclib.DateTime` type; the conversion semantics were |
| 2632 | not necessarily correct for all applications. Code using |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2633 | :mod:`xmlrpclib` should convert :class:`date` and :class:`time` |
| 2634 | instances. (:issue:`1330538`) The code can also handle |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2635 | dates before 1900 (contributed by Ralf Schmitt; :issue:`2014`) |
| 2636 | and 64-bit integers represented by using ``<i8>`` in XML-RPC responses |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2637 | (contributed by Riku Lindblad; :issue:`2985`). |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2638 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2639 | * The :mod:`zipfile` module's :class:`ZipFile` class now has |
| 2640 | :meth:`extract` and :meth:`extractall` methods that will unpack |
| 2641 | a single file or all the files in the archive to the current directory, or |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 2642 | to a specified directory:: |
| 2643 | |
| 2644 | z = zipfile.ZipFile('python-251.zip') |
| 2645 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2646 | # Unpack a single file, writing it relative |
| 2647 | # to the /tmp directory. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 2648 | z.extract('Python/sysmodule.c', '/tmp') |
| 2649 | |
| 2650 | # Unpack all the files in the archive. |
| 2651 | z.extractall() |
| 2652 | |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 2653 | (Contributed by Alan McIntyre; :issue:`467924`.) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 2654 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2655 | The :meth:`open`, :meth:`read` and :meth:`extract` methods can now |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2656 | take either a filename or a :class:`ZipInfo` object. This is useful when an |
| 2657 | archive accidentally contains a duplicated filename. |
| 2658 | (Contributed by Graham Horler; :issue:`1775025`.) |
Alexandre Vassalotti | 6461e10 | 2008-05-15 22:09:29 +0000 | [diff] [blame] | 2659 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2660 | Finally, :mod:`zipfile` now supports using Unicode filenames |
| 2661 | for archived files. (Contributed by Alexey Borzenkov; :issue:`1734346`.) |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2662 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 2663 | .. ====================================================================== |
| 2664 | .. whole new modules get described in subsections here |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 2665 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2666 | The :mod:`ast` module |
| 2667 | ---------------------- |
| 2668 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2669 | The :mod:`ast` module provides an Abstract Syntax Tree |
| 2670 | representation of Python code, and Armin Ronacher |
| 2671 | contributed a set of helper functions that perform a variety of |
| 2672 | common tasks. These will be useful for HTML templating |
| 2673 | packages, code analyzers, and similar tools that process |
| 2674 | Python code. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2675 | |
| 2676 | The :func:`parse` function takes an expression and returns an AST. |
| 2677 | The :func:`dump` function outputs a representation of a tree, suitable |
| 2678 | for debugging:: |
| 2679 | |
| 2680 | import ast |
| 2681 | |
| 2682 | t = ast.parse(""" |
| 2683 | d = {} |
| 2684 | for i in 'abcdefghijklm': |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2685 | d[i + i] = ord(i) - ord('a') + 1 |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2686 | print d |
| 2687 | """) |
| 2688 | print ast.dump(t) |
| 2689 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2690 | This outputs a deeply nested tree:: |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2691 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2692 | Module(body=[ |
| 2693 | Assign(targets=[ |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2694 | Name(id='d', ctx=Store()) |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2695 | ], value=Dict(keys=[], values=[])) |
| 2696 | For(target=Name(id='i', ctx=Store()), |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2697 | iter=Str(s='abcdefghijklm'), body=[ |
| 2698 | Assign(targets=[ |
| 2699 | Subscript(value= |
| 2700 | Name(id='d', ctx=Load()), |
| 2701 | slice= |
| 2702 | Index(value= |
| 2703 | BinOp(left=Name(id='i', ctx=Load()), op=Add(), |
| 2704 | right=Name(id='i', ctx=Load()))), ctx=Store()) |
| 2705 | ], value= |
| 2706 | BinOp(left= |
| 2707 | BinOp(left= |
| 2708 | Call(func= |
| 2709 | Name(id='ord', ctx=Load()), args=[ |
| 2710 | Name(id='i', ctx=Load()) |
| 2711 | ], keywords=[], starargs=None, kwargs=None), |
| 2712 | op=Sub(), right=Call(func= |
| 2713 | Name(id='ord', ctx=Load()), args=[ |
| 2714 | Str(s='a') |
| 2715 | ], keywords=[], starargs=None, kwargs=None)), |
| 2716 | op=Add(), right=Num(n=1))) |
| 2717 | ], orelse=[]) |
| 2718 | Print(dest=None, values=[ |
| 2719 | Name(id='d', ctx=Load()) |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2720 | ], nl=True) |
| 2721 | ]) |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2722 | |
| 2723 | The :func:`literal_eval` method takes a string or an AST |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2724 | representing a literal expression, parses and evaluates it, and |
| 2725 | returns the resulting value. A literal expression is a Python |
| 2726 | expression containing only strings, numbers, dictionaries, |
| 2727 | etc. but no statements or function calls. If you need to |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2728 | evaluate an expression but cannot accept the security risk of using an |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2729 | :func:`eval` call, :func:`literal_eval` will handle it safely:: |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2730 | |
| 2731 | >>> literal = '("a", "b", {2:4, 3:8, 1:2})' |
| 2732 | >>> print ast.literal_eval(literal) |
| 2733 | ('a', 'b', {1: 2, 2: 4, 3: 8}) |
| 2734 | >>> print ast.literal_eval('"a" + "b"') |
| 2735 | Traceback (most recent call last): |
| 2736 | ... |
| 2737 | ValueError: malformed string |
| 2738 | |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 2739 | The module also includes :class:`NodeVisitor` and |
| 2740 | :class:`NodeTransformer` classes for traversing and modifying an AST, |
| 2741 | and functions for common transformations such as changing line |
| 2742 | numbers. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2743 | |
| 2744 | .. ====================================================================== |
| 2745 | |
| 2746 | The :mod:`future_builtins` module |
| 2747 | -------------------------------------- |
| 2748 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2749 | Python 3.0 makes many changes to the repertoire of built-in |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2750 | functions, and most of the changes can't be introduced in the Python |
| 2751 | 2.x series because they would break compatibility. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2752 | The :mod:`future_builtins` module provides versions |
| 2753 | of these built-in functions that can be imported when writing |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2754 | 3.0-compatible code. |
| 2755 | |
| 2756 | The functions in this module currently include: |
| 2757 | |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 2758 | * ``ascii(obj)``: equivalent to :func:`repr`. In Python 3.0, |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2759 | :func:`repr` will return a Unicode string, while :func:`ascii` will |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2760 | return a pure ASCII bytestring. |
| 2761 | |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 2762 | * ``filter(predicate, iterable)``, |
| 2763 | ``map(func, iterable1, ...)``: the 3.0 versions |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 2764 | return iterators, unlike the 2.x builtins which return lists. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2765 | |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 2766 | * ``hex(value)``, ``oct(value)``: instead of calling the |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2767 | :meth:`__hex__` or :meth:`__oct__` methods, these versions will |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2768 | call the :meth:`__index__` method and convert the result to hexadecimal |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2769 | or octal. :func:`oct` will use the new ``0o`` notation for its |
| 2770 | result. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2771 | |
| 2772 | .. ====================================================================== |
| 2773 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2774 | The :mod:`json` module: JavaScript Object Notation |
| 2775 | -------------------------------------------------------------------- |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 2776 | |
| 2777 | The new :mod:`json` module supports the encoding and decoding of Python types in |
| 2778 | JSON (Javascript Object Notation). JSON is a lightweight interchange format |
| 2779 | often used in web applications. For more information about JSON, see |
| 2780 | http://www.json.org. |
| 2781 | |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 2782 | :mod:`json` comes with support for decoding and encoding most built-in Python |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 2783 | types. The following example encodes and decodes a dictionary:: |
| 2784 | |
| 2785 | >>> import json |
| 2786 | >>> data = {"spam" : "foo", "parrot" : 42} |
| 2787 | >>> in_json = json.dumps(data) # Encode the data |
| 2788 | >>> in_json |
| 2789 | '{"parrot": 42, "spam": "foo"}' |
| 2790 | >>> json.loads(in_json) # Decode into a Python object |
| 2791 | {"spam" : "foo", "parrot" : 42} |
| 2792 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2793 | It's also possible to write your own decoders and encoders to support |
| 2794 | more types. Pretty-printing of the JSON strings is also supported. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 2795 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2796 | :mod:`json` (originally called simplejson) was written by Bob |
| 2797 | Ippolito. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 2798 | |
| 2799 | |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 2800 | .. ====================================================================== |
| 2801 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2802 | The :mod:`plistlib` module: A Property-List Parser |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 2803 | -------------------------------------------------- |
| 2804 | |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 2805 | The ``.plist`` format is commonly used on Mac OS X to |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2806 | store basic data types (numbers, strings, lists, |
| 2807 | and dictionaries) by serializing them into an XML-based format. |
| 2808 | It resembles the XML-RPC serialization of data types. |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 2809 | |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 2810 | Despite being primarily used on Mac OS X, the format |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 2811 | has nothing Mac-specific about it and the Python implementation works |
| 2812 | on any platform that Python supports, so the :mod:`plistlib` module |
| 2813 | has been promoted to the standard library. |
| 2814 | |
| 2815 | Using the module is simple:: |
| 2816 | |
| 2817 | import sys |
| 2818 | import plistlib |
| 2819 | import datetime |
| 2820 | |
| 2821 | # Create data structure |
| 2822 | data_struct = dict(lastAccessed=datetime.datetime.now(), |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 2823 | version=1, |
| 2824 | categories=('Personal','Shared','Private')) |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 2825 | |
| 2826 | # Create string containing XML. |
| 2827 | plist_str = plistlib.writePlistToString(data_struct) |
| 2828 | new_struct = plistlib.readPlistFromString(plist_str) |
| 2829 | print data_struct |
| 2830 | print new_struct |
| 2831 | |
| 2832 | # Write data structure to a file and read it back. |
| 2833 | plistlib.writePlist(data_struct, '/tmp/customizations.plist') |
| 2834 | new_struct = plistlib.readPlist('/tmp/customizations.plist') |
| 2835 | |
| 2836 | # read/writePlist accepts file-like objects as well as paths. |
| 2837 | plistlib.writePlist(data_struct, sys.stdout) |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2838 | |
| 2839 | .. ====================================================================== |
| 2840 | |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 2841 | ctypes Enhancements |
| 2842 | -------------------------------------------------- |
| 2843 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2844 | Thomas Heller continued to maintain and enhance the |
| 2845 | :mod:`ctypes` module. |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 2846 | |
| 2847 | :mod:`ctypes` now supports a :class:`c_bool` datatype |
| 2848 | that represents the C99 ``bool`` type. (Contributed by David Remahl; |
| 2849 | :issue:`1649190`.) |
| 2850 | |
| 2851 | The :mod:`ctypes` string, buffer and array types have improved |
| 2852 | support for extended slicing syntax, |
| 2853 | where various combinations of ``(start, stop, step)`` are supplied. |
| 2854 | (Implemented by Thomas Wouters.) |
| 2855 | |
| 2856 | .. Revision 57769 |
| 2857 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2858 | All :mod:`ctypes` data types now support |
| 2859 | :meth:`from_buffer` and :meth:`from_buffer_copy` |
| 2860 | methods that create a ctypes instance based on a |
| 2861 | provided buffer object. :meth:`from_buffer_copy` copies |
| 2862 | the contents of the object, |
| 2863 | while :meth:`from_buffer` will share the same memory area. |
| 2864 | |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 2865 | A new calling convention tells :mod:`ctypes` to clear the ``errno`` or |
| 2866 | Win32 LastError variables at the outset of each wrapped call. |
| 2867 | (Implemented by Thomas Heller; :issue:`1798`.) |
| 2868 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2869 | You can now retrieve the Unix ``errno`` variable after a function |
| 2870 | call. When creating a wrapped function, you can supply |
| 2871 | ``use_errno=True`` as a keyword parameter to the :func:`DLL` function |
| 2872 | and then call the module-level methods :meth:`set_errno` and |
| 2873 | :meth:`get_errno` to set and retrieve the error value. |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 2874 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2875 | The Win32 LastError variable is similarly supported by |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 2876 | the :func:`DLL`, :func:`OleDLL`, and :func:`WinDLL` functions. |
| 2877 | You supply ``use_last_error=True`` as a keyword parameter |
| 2878 | and then call the module-level methods :meth:`set_last_error` |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2879 | and :meth:`get_last_error`. |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 2880 | |
| 2881 | The :func:`byref` function, used to retrieve a pointer to a ctypes |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2882 | instance, now has an optional *offset* parameter that is a byte |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 2883 | count that will be added to the returned pointer. |
| 2884 | |
| 2885 | .. ====================================================================== |
| 2886 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2887 | Improved SSL Support |
| 2888 | -------------------------------------------------- |
| 2889 | |
| 2890 | Bill Janssen made extensive improvements to Python 2.6's support for |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2891 | the Secure Sockets Layer by adding a new module, :mod:`ssl`, that's |
| 2892 | built atop the `OpenSSL <http://www.openssl.org/>`__ library. |
| 2893 | This new module provides more control over the protocol negotiated, |
| 2894 | the X.509 certificates used, and has better support for writing SSL |
| 2895 | servers (as opposed to clients) in Python. The existing SSL support |
| 2896 | in the :mod:`socket` module hasn't been removed and continues to work, |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2897 | though it will be removed in Python 3.0. |
| 2898 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2899 | To use the new module, you must first create a TCP connection in the |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2900 | usual way and then pass it to the :func:`ssl.wrap_socket` function. |
| 2901 | It's possible to specify whether a certificate is required, and to |
| 2902 | obtain certificate info by calling the :meth:`getpeercert` method. |
| 2903 | |
| 2904 | .. seealso:: |
| 2905 | |
| 2906 | The documentation for the :mod:`ssl` module. |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 2907 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 2908 | .. ====================================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 2909 | |
Georg Brandl | 8bd0546 | 2009-11-18 18:53:54 +0000 | [diff] [blame] | 2910 | Deprecations and Removals |
| 2911 | ========================= |
| 2912 | |
| 2913 | * String exceptions have been removed. Attempting to use them raises a |
| 2914 | :exc:`TypeError`. |
| 2915 | |
| 2916 | * Changes to the :class:`Exception` interface |
| 2917 | as dictated by :pep:`352` continue to be made. For 2.6, |
| 2918 | the :attr:`message` attribute is being deprecated in favor of the |
| 2919 | :attr:`args` attribute. |
| 2920 | |
| 2921 | * (3.0-warning mode) Python 3.0 will feature a reorganized standard |
| 2922 | library that will drop many outdated modules and rename others. |
| 2923 | Python 2.6 running in 3.0-warning mode will warn about these modules |
| 2924 | when they are imported. |
| 2925 | |
| 2926 | The list of deprecated modules is: |
| 2927 | :mod:`audiodev`, |
| 2928 | :mod:`bgenlocations`, |
| 2929 | :mod:`buildtools`, |
| 2930 | :mod:`bundlebuilder`, |
| 2931 | :mod:`Canvas`, |
| 2932 | :mod:`compiler`, |
| 2933 | :mod:`dircache`, |
| 2934 | :mod:`dl`, |
| 2935 | :mod:`fpformat`, |
| 2936 | :mod:`gensuitemodule`, |
| 2937 | :mod:`ihooks`, |
| 2938 | :mod:`imageop`, |
| 2939 | :mod:`imgfile`, |
| 2940 | :mod:`linuxaudiodev`, |
| 2941 | :mod:`mhlib`, |
| 2942 | :mod:`mimetools`, |
| 2943 | :mod:`multifile`, |
| 2944 | :mod:`new`, |
| 2945 | :mod:`pure`, |
| 2946 | :mod:`statvfs`, |
| 2947 | :mod:`sunaudiodev`, |
| 2948 | :mod:`test.testall`, and |
| 2949 | :mod:`toaiff`. |
| 2950 | |
| 2951 | * The :mod:`gopherlib` module has been removed. |
| 2952 | |
| 2953 | * The :mod:`MimeWriter` module and :mod:`mimify` module |
| 2954 | have been deprecated; use the :mod:`email` |
| 2955 | package instead. |
| 2956 | |
| 2957 | * The :mod:`md5` module has been deprecated; use the :mod:`hashlib` module |
| 2958 | instead. |
| 2959 | |
| 2960 | * The :mod:`posixfile` module has been deprecated; :func:`fcntl.lockf` |
| 2961 | provides better locking. |
| 2962 | |
| 2963 | * The :mod:`popen2` module has been deprecated; use the :mod:`subprocess` |
| 2964 | module. |
| 2965 | |
| 2966 | * The :mod:`rgbimg` module has been removed. |
| 2967 | |
| 2968 | * The :mod:`sets` module has been deprecated; it's better to |
| 2969 | use the built-in :class:`set` and :class:`frozenset` types. |
| 2970 | |
| 2971 | * The :mod:`sha` module has been deprecated; use the :mod:`hashlib` module |
| 2972 | instead. |
| 2973 | |
| 2974 | |
| 2975 | .. ====================================================================== |
| 2976 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 2977 | |
| 2978 | Build and C API Changes |
| 2979 | ======================= |
| 2980 | |
| 2981 | Changes to Python's build process and to the C API include: |
| 2982 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2983 | * Python now must be compiled with C89 compilers (after 19 |
| 2984 | years!). This means that the Python source tree has dropped its |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2985 | own implementations of :c:func:`memmove` and :c:func:`strerror`, which |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2986 | are in the C89 standard library. |
| 2987 | |
| 2988 | * Python 2.6 can be built with Microsoft Visual Studio 2008 (version |
| 2989 | 9.0), and this is the new default compiler. See the |
| 2990 | :file:`PCbuild` directory for the build files. (Implemented by |
| 2991 | Christian Heimes.) |
Guido van Rossum | 0d3fb8a | 2007-11-26 23:23:18 +0000 | [diff] [blame] | 2992 | |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 2993 | * On Mac OS X, Python 2.6 can be compiled as a 4-way universal build. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 2994 | The :program:`configure` script |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 2995 | can take a :option:`--with-universal-archs=[32-bit|64-bit|all]` |
| 2996 | switch, controlling whether the binaries are built for 32-bit |
| 2997 | architectures (x86, PowerPC), 64-bit (x86-64 and PPC-64), or both. |
| 2998 | (Contributed by Ronald Oussoren.) |
| 2999 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3000 | * The BerkeleyDB module now has a C API object, available as |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 3001 | ``bsddb.db.api``. This object can be used by other C extensions |
| 3002 | that wish to use the :mod:`bsddb` module for their own purposes. |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 3003 | (Contributed by Duncan Grisby.) |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 3004 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3005 | * The new buffer interface, previously described in |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3006 | `the PEP 3118 section <#pep-3118-revised-buffer-protocol>`__, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3007 | adds :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release`, |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3008 | as well as a few other functions. |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 3009 | |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 3010 | * Python's use of the C stdio library is now thread-safe, or at least |
| 3011 | as thread-safe as the underlying library is. A long-standing potential |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3012 | bug occurred if one thread closed a file object while another thread |
| 3013 | was reading from or writing to the object. In 2.6 file objects |
| 3014 | have a reference count, manipulated by the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3015 | :c:func:`PyFile_IncUseCount` and :c:func:`PyFile_DecUseCount` |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3016 | functions. File objects can't be closed unless the reference count |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3017 | is zero. :c:func:`PyFile_IncUseCount` should be called while the GIL |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3018 | is still held, before carrying out an I/O operation using the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3019 | ``FILE *`` pointer, and :c:func:`PyFile_DecUseCount` should be called |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 3020 | immediately after the GIL is re-acquired. |
| 3021 | (Contributed by Antoine Pitrou and Gregory P. Smith.) |
| 3022 | |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3023 | * Importing modules simultaneously in two different threads no longer |
| 3024 | deadlocks; it will now raise an :exc:`ImportError`. A new API |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3025 | function, :c:func:`PyImport_ImportModuleNoBlock`, will look for a |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3026 | module in ``sys.modules`` first, then try to import it after |
| 3027 | acquiring an import lock. If the import lock is held by another |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3028 | thread, an :exc:`ImportError` is raised. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3029 | (Contributed by Christian Heimes.) |
| 3030 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3031 | * Several functions return information about the platform's |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3032 | floating-point support. :c:func:`PyFloat_GetMax` returns |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 3033 | the maximum representable floating point value, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3034 | and :c:func:`PyFloat_GetMin` returns the minimum |
| 3035 | positive value. :c:func:`PyFloat_GetInfo` returns an object |
Christian Heimes | 90aa764 | 2007-12-19 02:45:37 +0000 | [diff] [blame] | 3036 | containing more information from the :file:`float.h` file, such as |
| 3037 | ``"mant_dig"`` (number of digits in the mantissa), ``"epsilon"`` |
| 3038 | (smallest difference between 1.0 and the next largest value |
| 3039 | representable), and several others. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3040 | (Contributed by Christian Heimes; :issue:`1534`.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3041 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3042 | * C functions and methods that use |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3043 | :c:func:`PyComplex_AsCComplex` will now accept arguments that |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3044 | have a :meth:`__complex__` method. In particular, the functions in the |
| 3045 | :mod:`cmath` module will now accept objects with this method. |
| 3046 | This is a backport of a Python 3.0 change. |
| 3047 | (Contributed by Mark Dickinson; :issue:`1675423`.) |
| 3048 | |
Christian Heimes | a34706f | 2008-01-04 03:06:10 +0000 | [diff] [blame] | 3049 | * Python's C API now includes two functions for case-insensitive string |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 3050 | comparisons, ``PyOS_stricmp(char*, char*)`` |
Christian Heimes | a34706f | 2008-01-04 03:06:10 +0000 | [diff] [blame] | 3051 | and ``PyOS_strnicmp(char*, char*, Py_ssize_t)``. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3052 | (Contributed by Christian Heimes; :issue:`1635`.) |
Christian Heimes | a34706f | 2008-01-04 03:06:10 +0000 | [diff] [blame] | 3053 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3054 | * Many C extensions define their own little macro for adding |
| 3055 | integers and strings to the module's dictionary in the |
| 3056 | ``init*`` function. Python 2.6 finally defines standard macros |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3057 | for adding values to a module, :c:macro:`PyModule_AddStringMacro` |
| 3058 | and :c:macro:`PyModule_AddIntMacro()`. (Contributed by |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 3059 | Christian Heimes.) |
| 3060 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 3061 | * Some macros were renamed in both 3.0 and 2.6 to make it clearer that |
| 3062 | they are macros, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3063 | not functions. :c:macro:`Py_Size()` became :c:macro:`Py_SIZE()`, |
| 3064 | :c:macro:`Py_Type()` became :c:macro:`Py_TYPE()`, and |
| 3065 | :c:macro:`Py_Refcnt()` became :c:macro:`Py_REFCNT()`. |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 3066 | The mixed-case macros are still available |
| 3067 | in Python 2.6 for backward compatibility. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3068 | (:issue:`1629`) |
Christian Heimes | a34706f | 2008-01-04 03:06:10 +0000 | [diff] [blame] | 3069 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3070 | * Distutils now places C extensions it builds in a |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 3071 | different directory when running on a debug version of Python. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3072 | (Contributed by Collin Winter; :issue:`1530959`.) |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 3073 | |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 3074 | * Several basic data types, such as integers and strings, maintain |
| 3075 | internal free lists of objects that can be re-used. The data |
| 3076 | structures for these free lists now follow a naming convention: the |
| 3077 | variable is always named ``free_list``, the counter is always named |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3078 | ``numfree``, and a macro ``Py<typename>_MAXFREELIST`` is |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 3079 | always defined. |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 3080 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 3081 | * A new Makefile target, "make patchcheck", prepares the Python source tree |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3082 | for making a patch: it fixes trailing whitespace in all modified |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 3083 | ``.py`` files, checks whether the documentation has been changed, |
| 3084 | and reports whether the :file:`Misc/ACKS` and :file:`Misc/NEWS` files |
| 3085 | have been updated. |
| 3086 | (Contributed by Brett Cannon.) |
| 3087 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 3088 | Another new target, "make profile-opt", compiles a Python binary |
| 3089 | using GCC's profile-guided optimization. It compiles Python with |
| 3090 | profiling enabled, runs the test suite to obtain a set of profiling |
| 3091 | results, and then compiles using these results for optimization. |
| 3092 | (Contributed by Gregory P. Smith.) |
| 3093 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 3094 | .. ====================================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3095 | |
Christian Heimes | a34706f | 2008-01-04 03:06:10 +0000 | [diff] [blame] | 3096 | Port-Specific Changes: Windows |
| 3097 | ----------------------------------- |
| 3098 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 3099 | * The support for Windows 95, 98, ME and NT4 has been dropped. |
| 3100 | Python 2.6 requires at least Windows 2000 SP4. |
| 3101 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3102 | * The new default compiler on Windows is Visual Studio 2008 (version |
| 3103 | 9.0). The build directories for Visual Studio 2003 (version 7.1) and |
| 3104 | 2005 (version 8.0) were moved into the PC/ directory. The new |
| 3105 | :file:`PCbuild` directory supports cross compilation for X64, debug |
| 3106 | builds and Profile Guided Optimization (PGO). PGO builds are roughly |
| 3107 | 10% faster than normal builds. (Contributed by Christian Heimes |
Antoine Pitrou | fbd4f80 | 2012-08-11 16:51:50 +0200 | [diff] [blame] | 3108 | with help from Amaury Forgeot d'Arc and Martin von Löwis.) |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3109 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3110 | * The :mod:`msvcrt` module now supports |
Christian Heimes | a34706f | 2008-01-04 03:06:10 +0000 | [diff] [blame] | 3111 | both the normal and wide char variants of the console I/O |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3112 | API. The :func:`getwch` function reads a keypress and returns a Unicode |
Christian Heimes | a34706f | 2008-01-04 03:06:10 +0000 | [diff] [blame] | 3113 | value, as does the :func:`getwche` function. The :func:`putwch` function |
| 3114 | takes a Unicode character and writes it to the console. |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 3115 | (Contributed by Christian Heimes.) |
| 3116 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3117 | * :func:`os.path.expandvars` will now expand environment variables in |
| 3118 | the form "%var%", and "~user" will be expanded into the user's home |
| 3119 | directory path. (Contributed by Josiah Carlson; :issue:`957650`.) |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 3120 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3121 | * The :mod:`socket` module's socket objects now have an |
| 3122 | :meth:`ioctl` method that provides a limited interface to the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3123 | :c:func:`WSAIoctl` system interface. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3124 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3125 | * The :mod:`_winreg` module now has a function, |
| 3126 | :func:`ExpandEnvironmentStrings`, |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 3127 | that expands environment variable references such as ``%NAME%`` |
| 3128 | in an input string. The handle objects provided by this |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3129 | module now support the context protocol, so they can be used |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 3130 | in :keyword:`with` statements. (Contributed by Christian Heimes.) |
| 3131 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3132 | :mod:`_winreg` also has better support for x64 systems, |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 3133 | exposing the :func:`DisableReflectionKey`, :func:`EnableReflectionKey`, |
| 3134 | and :func:`QueryReflectionKey` functions, which enable and disable |
| 3135 | registry reflection for 32-bit processes running on 64-bit systems. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3136 | (:issue:`1753245`) |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 3137 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3138 | * The :mod:`msilib` module's :class:`Record` object |
| 3139 | gained :meth:`GetInteger` and :meth:`GetString` methods that |
| 3140 | return field values as an integer or a string. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3141 | (Contributed by Floris Bruynooghe; :issue:`2125`.) |
| 3142 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 3143 | .. ====================================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3144 | |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 3145 | Port-Specific Changes: Mac OS X |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 3146 | ----------------------------------- |
| 3147 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3148 | * When compiling a framework build of Python, you can now specify the |
| 3149 | framework name to be used by providing the |
| 3150 | :option:`--with-framework-name=` option to the |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 3151 | :program:`configure` script. |
| 3152 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3153 | * The :mod:`macfs` module has been removed. This in turn required the |
| 3154 | :func:`macostools.touched` function to be removed because it depended on the |
| 3155 | :mod:`macfs` module. (:issue:`1490190`) |
| 3156 | |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 3157 | * Many other Mac OS modules have been deprecated and will removed in |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3158 | Python 3.0: |
| 3159 | :mod:`_builtinSuites`, |
| 3160 | :mod:`aepack`, |
| 3161 | :mod:`aetools`, |
| 3162 | :mod:`aetypes`, |
| 3163 | :mod:`applesingle`, |
| 3164 | :mod:`appletrawmain`, |
| 3165 | :mod:`appletrunner`, |
| 3166 | :mod:`argvemulator`, |
| 3167 | :mod:`Audio_mac`, |
| 3168 | :mod:`autoGIL`, |
| 3169 | :mod:`Carbon`, |
| 3170 | :mod:`cfmfile`, |
| 3171 | :mod:`CodeWarrior`, |
| 3172 | :mod:`ColorPicker`, |
| 3173 | :mod:`EasyDialogs`, |
| 3174 | :mod:`Explorer`, |
| 3175 | :mod:`Finder`, |
| 3176 | :mod:`FrameWork`, |
| 3177 | :mod:`findertools`, |
| 3178 | :mod:`ic`, |
| 3179 | :mod:`icglue`, |
| 3180 | :mod:`icopen`, |
| 3181 | :mod:`macerrors`, |
| 3182 | :mod:`MacOS`, |
| 3183 | :mod:`macfs`, |
| 3184 | :mod:`macostools`, |
| 3185 | :mod:`macresource`, |
| 3186 | :mod:`MiniAEFrame`, |
| 3187 | :mod:`Nav`, |
| 3188 | :mod:`Netscape`, |
| 3189 | :mod:`OSATerminology`, |
| 3190 | :mod:`pimp`, |
| 3191 | :mod:`PixMapWrapper`, |
| 3192 | :mod:`StdSuites`, |
| 3193 | :mod:`SystemEvents`, |
| 3194 | :mod:`Terminal`, and |
| 3195 | :mod:`terminalcommand`. |
| 3196 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 3197 | .. ====================================================================== |
| 3198 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3199 | Port-Specific Changes: IRIX |
| 3200 | ----------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3201 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3202 | A number of old IRIX-specific modules were deprecated and will |
| 3203 | be removed in Python 3.0: |
| 3204 | :mod:`al` and :mod:`AL`, |
| 3205 | :mod:`cd`, |
| 3206 | :mod:`cddb`, |
| 3207 | :mod:`cdplayer`, |
| 3208 | :mod:`CL` and :mod:`cl`, |
| 3209 | :mod:`DEVICE`, |
| 3210 | :mod:`ERRNO`, |
| 3211 | :mod:`FILE`, |
| 3212 | :mod:`FL` and :mod:`fl`, |
| 3213 | :mod:`flp`, |
| 3214 | :mod:`fm`, |
| 3215 | :mod:`GET`, |
| 3216 | :mod:`GLWS`, |
| 3217 | :mod:`GL` and :mod:`gl`, |
| 3218 | :mod:`IN`, |
| 3219 | :mod:`IOCTL`, |
| 3220 | :mod:`jpeg`, |
| 3221 | :mod:`panelparser`, |
| 3222 | :mod:`readcd`, |
| 3223 | :mod:`SV` and :mod:`sv`, |
| 3224 | :mod:`torgb`, |
| 3225 | :mod:`videoreader`, and |
| 3226 | :mod:`WAIT`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3227 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 3228 | .. ====================================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3229 | |
| 3230 | |
| 3231 | Porting to Python 2.6 |
| 3232 | ===================== |
| 3233 | |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 3234 | This section lists previously described changes and other bugfixes |
| 3235 | that may require changes to your code: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3236 | |
Benjamin Peterson | dcc1e11 | 2008-09-03 22:22:18 +0000 | [diff] [blame] | 3237 | * Classes that aren't supposed to be hashable should |
| 3238 | set ``__hash__ = None`` in their definitions to indicate |
| 3239 | the fact. |
| 3240 | |
Benjamin Peterson | 28d88b4 | 2009-01-09 03:03:23 +0000 | [diff] [blame] | 3241 | * String exceptions have been removed. Attempting to use them raises a |
| 3242 | :exc:`TypeError`. |
| 3243 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 3244 | * The :meth:`__init__` method of :class:`collections.deque` |
Christian Heimes | a34706f | 2008-01-04 03:06:10 +0000 | [diff] [blame] | 3245 | now clears any existing contents of the deque |
| 3246 | before adding elements from the iterable. This change makes the |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 3247 | behavior match ``list.__init__()``. |
Christian Heimes | a34706f | 2008-01-04 03:06:10 +0000 | [diff] [blame] | 3248 | |
Benjamin Peterson | 5478b47 | 2008-09-17 22:25:09 +0000 | [diff] [blame] | 3249 | * :meth:`object.__init__` previously accepted arbitrary arguments and |
| 3250 | keyword arguments, ignoring them. In Python 2.6, this is no longer |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 3251 | allowed and will result in a :exc:`TypeError`. This will affect |
| 3252 | :meth:`__init__` methods that end up calling the corresponding |
Benjamin Peterson | 5478b47 | 2008-09-17 22:25:09 +0000 | [diff] [blame] | 3253 | method on :class:`object` (perhaps through using :func:`super`). |
| 3254 | See :issue:`1683368` for discussion. |
| 3255 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3256 | * The :class:`Decimal` constructor now accepts leading and trailing |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 3257 | whitespace when passed a string. Previously it would raise an |
| 3258 | :exc:`InvalidOperation` exception. On the other hand, the |
| 3259 | :meth:`create_decimal` method of :class:`Context` objects now |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3260 | explicitly disallows extra whitespace, raising a |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 3261 | :exc:`ConversionSyntax` exception. |
| 3262 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3263 | * Due to an implementation accident, if you passed a file path to |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 3264 | the built-in :func:`__import__` function, it would actually import |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3265 | the specified file. This was never intended to work, however, and |
| 3266 | the implementation now explicitly checks for this case and raises |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 3267 | an :exc:`ImportError`. |
| 3268 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3269 | * C API: the :c:func:`PyImport_Import` and :c:func:`PyImport_ImportModule` |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3270 | functions now default to absolute imports, not relative imports. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3271 | This will affect C extensions that import other modules. |
| 3272 | |
Benjamin Peterson | dcc1e11 | 2008-09-03 22:22:18 +0000 | [diff] [blame] | 3273 | * C API: extension data types that shouldn't be hashable |
| 3274 | should define their ``tp_hash`` slot to |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 3275 | :c:func:`PyObject_HashNotImplemented`. |
Benjamin Peterson | dcc1e11 | 2008-09-03 22:22:18 +0000 | [diff] [blame] | 3276 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 3277 | * The :mod:`socket` module exception :exc:`socket.error` now inherits |
| 3278 | from :exc:`IOError`. Previously it wasn't a subclass of |
| 3279 | :exc:`StandardError` but now it is, through :exc:`IOError`. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3280 | (Implemented by Gregory P. Smith; :issue:`1706815`.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3281 | |
Christian Heimes | 05e8be1 | 2008-02-23 18:30:17 +0000 | [diff] [blame] | 3282 | * The :mod:`xmlrpclib` module no longer automatically converts |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3283 | :class:`datetime.date` and :class:`datetime.time` to the |
Christian Heimes | 05e8be1 | 2008-02-23 18:30:17 +0000 | [diff] [blame] | 3284 | :class:`xmlrpclib.DateTime` type; the conversion semantics were |
| 3285 | not necessarily correct for all applications. Code using |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3286 | :mod:`xmlrpclib` should convert :class:`date` and :class:`time` |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 3287 | instances. (:issue:`1330538`) |
Christian Heimes | 05e8be1 | 2008-02-23 18:30:17 +0000 | [diff] [blame] | 3288 | |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3289 | * (3.0-warning mode) The :class:`Exception` class now warns |
| 3290 | when accessed using slicing or index access; having |
Christian Heimes | f6cd967 | 2008-03-26 13:45:42 +0000 | [diff] [blame] | 3291 | :class:`Exception` behave like a tuple is being phased out. |
| 3292 | |
| 3293 | * (3.0-warning mode) inequality comparisons between two dictionaries |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 3294 | or two objects that don't implement comparison methods are reported |
| 3295 | as warnings. ``dict1 == dict2`` still works, but ``dict1 < dict2`` |
| 3296 | is being phased out. |
Benjamin Peterson | f9c98b4 | 2008-07-02 16:19:28 +0000 | [diff] [blame] | 3297 | |
Christian Heimes | 02781dc | 2008-03-21 01:11:52 +0000 | [diff] [blame] | 3298 | Comparisons between cells, which are an implementation detail of Python's |
| 3299 | scoping rules, also cause warnings because such comparisons are forbidden |
| 3300 | entirely in 3.0. |
| 3301 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 3302 | .. ====================================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3303 | |
| 3304 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 3305 | .. _26acks: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3306 | |
| 3307 | Acknowledgements |
| 3308 | ================ |
| 3309 | |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 3310 | The author would like to thank the following people for offering |
| 3311 | suggestions, corrections and assistance with various drafts of this |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 3312 | article: Georg Brandl, Steve Brown, Nick Coghlan, Ralph Corderoy, |
| 3313 | Jim Jewett, Kent Johnson, Chris Lambacher, Martin Michlmayr, |
Benjamin Peterson | 206e307 | 2008-10-19 14:07:49 +0000 | [diff] [blame] | 3314 | Antoine Pitrou, Brian Warner. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3315 | |