Google Git
Sign in
chromium / external / github.com / python / cpython / refs/tags/v3.5.3 / . / README
blob: de3a091e07a598d102c063a168371d907662f5c9 [file] [log] [blame]
Larry Hastings51ba5b72017-01-16 08:19:36[diff] [blame]1This is Python version 3.5.3
2============================
Guido van Rossum91447632000-04-11 17:11:09[diff] [blame]3
Benjamin Petersonf606e682012-01-01 04:42:26[diff] [blame]4Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
Benjamin Petersone527dd32017-01-02 04:04:13[diff] [blame]52012, 2013, 2014, 2015, 2016, 2017 Python Software Foundation. All rights
6reserved.
Guido van Rossum4405cf32007-08-30 17:16:55[diff] [blame]7
Larry Hastingsf92f6c82015-09-12 16:28:39[diff] [blame]8Python 3.x is a new version of the language, which is incompatible with the
92.x line of releases. The language is mostly the same, but many details,
10especially how built-in objects like dictionaries and strings work,
11have changed considerably, and a lot of deprecated features have finally
12been removed.
Guido van Rossum1c896e32007-08-29 23:03:30[diff] [blame]13
Guido van Rossum50e9fb92006-08-17 05:42:55[diff] [blame]14
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]15Build Instructions
16------------------
Guido van Rossum3ff96dd1996-07-30 18:05:04[diff] [blame]17
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]18On Unix, Linux, BSD, OSX, and Cygwin:
19
20 ./configure
21 make
22 make test
23 sudo make install
24
25This will install Python as python3.
26
Georg Brandla02607e2010-07-31 11:00:47[diff] [blame]27You can pass many options to the configure script; run "./configure --help" to
28find out more. On OSX and Cygwin, the executable is called python.exe;
29elsewhere it's just python.
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]30
Georg Brandla02607e2010-07-31 11:00:47[diff] [blame]31On Mac OS X, if you have configured Python with --enable-framework, you should
Larry Hastingsf92f6c82015-09-12 16:28:39[diff] [blame]32use "make frameworkinstall" to do the installation. Note that this installs
33the Python executable in a place that is not normally on your PATH, you may
34want to set up a symlink in /usr/local/bin.
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]35
36On Windows, see PCbuild/readme.txt.
37
Larry Hastingsf92f6c82015-09-12 16:28:39[diff] [blame]38If you wish, you can create a subdirectory and invoke configure from there.
39For example:
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]40
41 mkdir debug
42 cd debug
43 ../configure --with-pydebug
44 make
45 make test
46
Larry Hastingsf92f6c82015-09-12 16:28:39[diff] [blame]47(This will fail if you *also* built at the top-level directory.
48You should do a "make clean" at the toplevel first.)
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]49
Gregory P. Smithaa5a13f2016-11-21 08:11:47[diff] [blame]50To get an optimized build of Python, "configure --enable-optimizations" before
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)014d52f2016-09-08 18:33:00[diff] [blame]51you run make. This sets the default make targets up to enable Profile Guided
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)14c7f712016-09-08 22:38:46[diff] [blame]52Optimization (PGO) and may be used to auto-enable Link Time Optimization (LTO)
53on some platforms. For more details, see the sections bellow.
Brett Cannon7188a3e2015-09-18 22:13:44[diff] [blame]54
55
56Profile Guided Optimization
57---------------------------
58
59PGO takes advantage of recent versions of the GCC or Clang compilers.
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)014d52f2016-09-08 18:33:00[diff] [blame]60If ran, "make profile-opt" will do several steps.
Brett Cannon7188a3e2015-09-18 22:13:44[diff] [blame]61
62First, the entire Python directory is cleaned of temporary files that
Martin Panter8d56c022016-05-29 04:13:35[diff] [blame]63may have resulted in a previous compilation.
Brett Cannon7188a3e2015-09-18 22:13:44[diff] [blame]64
65Then, an instrumented version of the interpreter is built, using suitable
66compiler flags for each flavour. Note that this is just an intermediary
67step and the binary resulted after this step is not good for real life
68workloads, as it has profiling instructions embedded inside.
69
70After this instrumented version of the interpreter is built, the Makefile
71will automatically run a training workload. This is necessary in order to
72profile the interpreter execution. Note also that any output, both stdout
Martin Panter0be894b2016-09-07 12:03:06[diff] [blame]73and stderr, that may appear at this step is suppressed.
Brett Cannon7188a3e2015-09-18 22:13:44[diff] [blame]74
75Finally, the last step is to rebuild the interpreter, using the information
Martin Pantercc71a792016-04-05 06:19:42[diff] [blame]76collected in the previous one. The end result will be a Python binary
Brett Cannon7188a3e2015-09-18 22:13:44[diff] [blame]77that is optimized and suitable for distribution or production installation.
78
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]79
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)014d52f2016-09-08 18:33:00[diff] [blame]80Link Time Optimization
81----------------------
82
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)14c7f712016-09-08 22:38:46[diff] [blame]83Enabled via configure's --with-lto flag. LTO takes advantages of recent
84compiler toolchains ability to optimize across the otherwise arbitrary .o file
85boundary when building final executables or shared libraries for additional
86performance gains.
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)014d52f2016-09-08 18:33:00[diff] [blame]87
88
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]89What's New
90----------
91
Larry Hastingsf92f6c82015-09-12 16:28:39[diff] [blame]92We have a comprehensive overview of the changes in the "What's New in
Yury Selivanov7aa53412015-05-30 14:57:56[diff] [blame]93Python 3.5" document, found at
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]94
Yury Selivanov7aa53412015-05-30 14:57:56[diff] [blame]95 http://docs.python.org/3.5/whatsnew/3.5.html
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]96
Larry Hastingsf92f6c82015-09-12 16:28:39[diff] [blame]97For a more detailed change log, read Misc/NEWS (though this file, too,
98is incomplete, and also doesn't list anything merged in from the 2.7
99release under development).
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]100
101If you want to install multiple versions of Python see the section below
102entitled "Installing multiple versions".
Guido van Rossum8d90f9d1997-05-22 20:13:25[diff] [blame]103
Guido van Rossumf501b4e1996-10-25 14:32:48[diff] [blame]104
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]105Documentation
106-------------
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]107
Yury Selivanov7aa53412015-05-30 14:57:56[diff] [blame]108Documentation for Python 3.5 is online, updated daily:
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]109
Yury Selivanov7aa53412015-05-30 14:57:56[diff] [blame]110 http://docs.python.org/3.5/
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]111
Georg Brandl62069d32010-07-31 08:56:11[diff] [blame]112It can also be downloaded in many formats for faster access. The documentation
113is downloadable in HTML, PDF, and reStructuredText formats; the latter version
114is primarily for documentation authors, translators, and people with special
115formatting requirements.
Benjamin Peterson2a691a82008-03-31 01:51:45[diff] [blame]116
Ezio Melotti802bf8ae2013-08-16 18:32:25[diff] [blame]117If you would like to contribute to the development of Python, relevant
118documentation is available at:
119
120 http://docs.python.org/devguide/
121
122For information about building Python's documentation, refer to Doc/README.txt.
123
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]124
Barry Warsaw97f005d2008-12-03 16:46:14[diff] [blame]125Converting From Python 2.x to 3.x
Guido van Rossum1c896e32007-08-29 23:03:30[diff] [blame]126---------------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]127
Georg Brandla02607e2010-07-31 11:00:47[diff] [blame]128Python starting with 2.6 contains features to help locating code that needs to
129be changed, such as optional warnings when deprecated features are used, and
130backported versions of certain key Python 3.x features.
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]131
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]132A source-to-source translation tool, "2to3", can take care of the mundane task
133of converting large amounts of source code. It is not a complete solution but
134is complemented by the deprecation warnings in 2.6. See
Yury Selivanov7aa53412015-05-30 14:57:56[diff] [blame]135http://docs.python.org/3.5/library/2to3.html for more information.
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]136
Christian Heimesdd15f6c2008-03-16 00:07:10[diff] [blame]137
Benjamin Petersonad3d5c22009-02-26 03:38:59[diff] [blame]138Testing
139-------
140
Larry Hastingsf92f6c82015-09-12 16:28:39[diff] [blame]141To test the interpreter, type "make test" in the top-level directory.
142The test set produces some output. You can generally ignore the messages
143about skipped tests due to optional features which can't be imported.
144If a message is printed about a failed test or a traceback or core dump
145is produced, something is wrong.
Benjamin Petersonad3d5c22009-02-26 03:38:59[diff] [blame]146
147By default, tests are prevented from overusing resources like disk space and
148memory. To enable these tests, run "make testall".
149
Georg Brandla02607e2010-07-31 11:00:47[diff] [blame]150IMPORTANT: If the tests fail and you decide to mail a bug report, *don't*
151include the output of "make test". It is useless. Run the failing test
152manually, as follows:
Benjamin Petersonad3d5c22009-02-26 03:38:59[diff] [blame]153
Antoine Pitroue7fed672010-12-14 22:06:10[diff] [blame]154 ./python -m test -v test_whatever
Benjamin Petersonad3d5c22009-02-26 03:38:59[diff] [blame]155
Georg Brandla02607e2010-07-31 11:00:47[diff] [blame]156(substituting the top of the source tree for '.' if you built in a different
157directory). This runs the test in verbose mode.
Benjamin Petersonad3d5c22009-02-26 03:38:59[diff] [blame]158
159
Christian Heimesdd15f6c2008-03-16 00:07:10[diff] [blame]160Installing multiple versions
161----------------------------
162
163On Unix and Mac systems if you intend to install multiple versions of Python
Georg Brandla02607e2010-07-31 11:00:47[diff] [blame]164using the same installation prefix (--prefix argument to the configure script)
Larry Hastingsf92f6c82015-09-12 16:28:39[diff] [blame]165you must take care that your primary python executable is not overwritten by
166the installation of a different version. All files and directories installed
167using "make altinstall" contain the major and minor version and can thus live
168side-by-side. "make install" also creates ${prefix}/bin/python3 which refers
169to ${prefix}/bin/pythonX.Y. If you intend to install multiple versions using
170the same prefix you must decide which version (if any) is your "primary"
171version. Install that version using "make install". Install all other
172versions using "make altinstall".
Christian Heimesdd15f6c2008-03-16 00:07:10[diff] [blame]173
Yury Selivanov7aa53412015-05-30 14:57:56[diff] [blame]174For example, if you want to install Python 2.6, 2.7 and 3.5 with 2.7 being the
Georg Brandlfa2c61a2011-02-20 10:41:31[diff] [blame]175primary version, you would execute "make install" in your 2.7 build directory
Georg Brandla02607e2010-07-31 11:00:47[diff] [blame]176and "make altinstall" in the others.
Christian Heimesdd15f6c2008-03-16 00:07:10[diff] [blame]177
178
Guido van Rossum1c896e32007-08-29 23:03:30[diff] [blame]179Issue Tracker and Mailing List
180------------------------------
Michael W. Hudson71dcc3e2005-02-22 15:33:26[diff] [blame]181
Georg Brandla02607e2010-07-31 11:00:47[diff] [blame]182We're soliciting bug reports about all aspects of the language. Fixes are also
Larry Hastingsf92f6c82015-09-12 16:28:39[diff] [blame]183welcome, preferably in unified diff format. Please use the issue tracker:
Fred Drake6caae142000-10-25 17:51:02[diff] [blame]184
Guido van Rossum1c896e32007-08-29 23:03:30[diff] [blame]185 http://bugs.python.org/
Guido van Rossum76be6ed1995-01-02 18:33:54[diff] [blame]186
Georg Brandla02607e2010-07-31 11:00:47[diff] [blame]187If you're not sure whether you're dealing with a bug or a feature, use the
188mailing list:
Guido van Rossum1c896e32007-08-29 23:03:30[diff] [blame]189
Mark Dickinsonb9ebd042009-02-06 16:39:11[diff] [blame]190 python-dev@python.org
Guido van Rossum1c896e32007-08-29 23:03:30[diff] [blame]191
192To subscribe to the list, use the mailman form:
193
Mark Dickinsonb9ebd042009-02-06 16:39:11[diff] [blame]194 http://mail.python.org/mailman/listinfo/python-dev/
Georg Brandl81299ad2006-02-20 10:24:06[diff] [blame]195
Michael W. Hudson71dcc3e2005-02-22 15:33:26[diff] [blame]196
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]197Proposals for enhancement
198-------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]199
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]200If you have a proposal to change Python, you may want to send an email to the
Georg Brandl260a7882011-02-20 10:29:04[diff] [blame]201comp.lang.python or python-ideas mailing lists for inital feedback. A Python
202Enhancement Proposal (PEP) may be submitted if your idea gains ground. All
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]203current PEPs, as well as guidelines for submitting a new PEP, are listed at
204http://www.python.org/dev/peps/.
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]205
Guido van Rossum1c896e32007-08-29 23:03:30[diff] [blame]206
Benjamin Peterson1da43e52009-06-26 13:21:52[diff] [blame]207Release Schedule
208----------------
Guido van Rossum1c896e32007-08-29 23:03:30[diff] [blame]209
Berker Peksag51a4a2b2014-10-12 03:59:14[diff] [blame]210See PEP 478 for release details: http://www.python.org/dev/peps/pep-0478/
Guido van Rossumef0f1292007-08-30 14:51:05[diff] [blame]211
212
213Copyright and License Information
214---------------------------------
215
Georg Brandla7d2f002013-03-23 15:06:13[diff] [blame]216Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
Benjamin Petersonf1dcdd92016-01-01 17:53:14[diff] [blame]2172012, 2013, 2014, 2015, 2016 Python Software Foundation. All rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05[diff] [blame]218
Georg Brandl260a7882011-02-20 10:29:04[diff] [blame]219Copyright (c) 2000 BeOpen.com. All rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05[diff] [blame]220
Georg Brandl260a7882011-02-20 10:29:04[diff] [blame]221Copyright (c) 1995-2001 Corporation for National Research Initiatives. All
222rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05[diff] [blame]223
Georg Brandl260a7882011-02-20 10:29:04[diff] [blame]224Copyright (c) 1991-1995 Stichting Mathematisch Centrum. All rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05[diff] [blame]225
Larry Hastingsf92f6c82015-09-12 16:28:39[diff] [blame]226See the file "LICENSE" for information on the history of this software,
227terms & conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.
Guido van Rossumef0f1292007-08-30 14:51:05[diff] [blame]228
Larry Hastingsf92f6c82015-09-12 16:28:39[diff] [blame]229This Python distribution contains *no* GNU General Public License (GPL) code,
230so it may be used in proprietary projects. There are interfaces to some GNU
231code but these are entirely optional.
Guido van Rossumef0f1292007-08-30 14:51:05[diff] [blame]232
Georg Brandl260a7882011-02-20 10:29:04[diff] [blame]233All trademarks referenced herein are property of their respective holders.