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