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