blob: 0e452833f15f1cb0dea729edce41e789bdad8ef0 [file] [log] [blame]
Ned Deilyffb40e52015-05-27 22:00:46 -07001This is Python version 3.6.0 alpha 1
2====================================
Guido van Rossum91447632000-04-11 17:11:09 +00003
Benjamin Petersonf606e682011-12-31 22:42:26 -06004Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
Benjamin Peterson75e36302016-01-01 10:23:45 -060052012, 2013, 2014, 2015, 2016 Python Software Foundation. All rights reserved.
Guido van Rossum4405cf32007-08-30 17:16:55 +00006
Larry Hastingsf92f6c82015-09-12 17:28:39 +01007Python 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 +000012
Guido van Rossum50e9fb92006-08-17 05:42:55 +000013
Benjamin Peterson1da43e52009-06-26 13:21:52 +000014Build Instructions
15------------------
Guido van Rossum3ff96dd1996-07-30 18:05:04 +000016
Benjamin Peterson1da43e52009-06-26 13:21:52 +000017On Unix, Linux, BSD, OSX, and Cygwin:
18
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 +000026You 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 +000029
Georg Brandla02607e2010-07-31 11:00:47 +000030On 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 +000034
35On Windows, see PCbuild/readme.txt.
36
Larry Hastingsf92f6c82015-09-12 17:28:39 +010037If you wish, you can create a subdirectory and invoke configure from there.
38For example:
Benjamin Peterson1da43e52009-06-26 13:21:52 +000039
40 mkdir debug
41 cd debug
42 ../configure --with-pydebug
43 make
44 make test
45
Larry Hastingsf92f6c82015-09-12 17:28:39 +010046(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 +000048
Brett Cannon7188a3e2015-09-18 15:13:44 -070049If you need an optimized version of Python, you type "make profile-opt" in the
50top level directory. This will rebuild the interpreter executable using Profile
51Guided Optimization (PGO). For more details, see the section bellow.
52
53
54Profile Guided Optimization
55---------------------------
56
57PGO takes advantage of recent versions of the GCC or Clang compilers.
58If ran, the "profile-opt" rule will do several steps.
59
60First, the entire Python directory is cleaned of temporary files that
61may resulted in a previous compilation.
62
63Then, an instrumented version of the interpreter is built, using suitable
64compiler flags for each flavour. Note that this is just an intermediary
65step and the binary resulted after this step is not good for real life
66workloads, as it has profiling instructions embedded inside.
67
68After this instrumented version of the interpreter is built, the Makefile
69will automatically run a training workload. This is necessary in order to
70profile the interpreter execution. Note also that any output, both stdout
71and stderr, that may appear at this step is supressed.
72
73Finally, the last step is to rebuild the interpreter, using the information
74collected in the previous one. The end result will be a the Python binary
75that is optimized and suitable for distribution or production installation.
76
Benjamin Peterson1da43e52009-06-26 13:21:52 +000077
78What's New
79----------
80
Larry Hastingsf92f6c82015-09-12 17:28:39 +010081We have a comprehensive overview of the changes in the "What's New in
Ned Deilyffb40e52015-05-27 22:00:46 -070082Python 3.6" document, found at
Benjamin Peterson1da43e52009-06-26 13:21:52 +000083
Ned Deilyffb40e52015-05-27 22:00:46 -070084 http://docs.python.org/3.6/whatsnew/3.6.html
Benjamin Peterson1da43e52009-06-26 13:21:52 +000085
Larry Hastingsf92f6c82015-09-12 17:28:39 +010086For a more detailed change log, read Misc/NEWS (though this file, too,
87is incomplete, and also doesn't list anything merged in from the 2.7
88release under development).
Benjamin Peterson1da43e52009-06-26 13:21:52 +000089
90If you want to install multiple versions of Python see the section below
91entitled "Installing multiple versions".
Guido van Rossum8d90f9d1997-05-22 20:13:25 +000092
Guido van Rossumf501b4e1996-10-25 14:32:48 +000093
Guido van Rossumc07d5fa2000-09-01 22:50:02 +000094Documentation
95-------------
Guido van Rossum91cb9d21995-04-10 11:47:38 +000096
Ned Deilyffb40e52015-05-27 22:00:46 -070097Documentation for Python 3.6 is online, updated daily:
Guido van Rossum91cb9d21995-04-10 11:47:38 +000098
Ned Deilyffb40e52015-05-27 22:00:46 -070099 http://docs.python.org/3.6/
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000100
Georg Brandl62069d32010-07-31 08:56:11 +0000101It can also be downloaded in many formats for faster access. The documentation
102is downloadable in HTML, PDF, and reStructuredText formats; the latter version
103is primarily for documentation authors, translators, and people with special
104formatting requirements.
Benjamin Peterson2a691a82008-03-31 01:51:45 +0000105
Ezio Melotti802bf8a2013-08-16 21:32:25 +0300106If you would like to contribute to the development of Python, relevant
107documentation is available at:
108
109 http://docs.python.org/devguide/
110
111For information about building Python's documentation, refer to Doc/README.txt.
112
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000113
Barry Warsaw97f005d2008-12-03 16:46:14 +0000114Converting From Python 2.x to 3.x
Guido van Rossum1c896e32007-08-29 23:03:30 +0000115---------------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000116
Georg Brandla02607e2010-07-31 11:00:47 +0000117Python starting with 2.6 contains features to help locating code that needs to
118be changed, such as optional warnings when deprecated features are used, and
119backported versions of certain key Python 3.x features.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000120
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000121A source-to-source translation tool, "2to3", can take care of the mundane task
122of converting large amounts of source code. It is not a complete solution but
123is complemented by the deprecation warnings in 2.6. See
Ned Deilyffb40e52015-05-27 22:00:46 -0700124http://docs.python.org/3.6/library/2to3.html for more information.
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000125
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000126
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000127Testing
128-------
129
Larry Hastingsf92f6c82015-09-12 17:28:39 +0100130To test the interpreter, type "make test" in the top-level directory.
131The test set produces some output. You can generally ignore the messages
132about skipped tests due to optional features which can't be imported.
133If a message is printed about a failed test or a traceback or core dump
134is produced, something is wrong.
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000135
136By default, tests are prevented from overusing resources like disk space and
137memory. To enable these tests, run "make testall".
138
Georg Brandla02607e2010-07-31 11:00:47 +0000139IMPORTANT: If the tests fail and you decide to mail a bug report, *don't*
140include the output of "make test". It is useless. Run the failing test
141manually, as follows:
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000142
Antoine Pitroue7fed672010-12-14 22:06:10 +0000143 ./python -m test -v test_whatever
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000144
Georg Brandla02607e2010-07-31 11:00:47 +0000145(substituting the top of the source tree for '.' if you built in a different
146directory). This runs the test in verbose mode.
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000147
148
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000149Installing multiple versions
150----------------------------
151
152On Unix and Mac systems if you intend to install multiple versions of Python
Georg Brandla02607e2010-07-31 11:00:47 +0000153using the same installation prefix (--prefix argument to the configure script)
154you must take care that your primary python executable is not overwritten by the
155installation of a different version. All files and directories installed using
156"make altinstall" contain the major and minor version and can thus live
157side-by-side. "make install" also creates ${prefix}/bin/python3 which refers to
158${prefix}/bin/pythonX.Y. If you intend to install multiple versions using the
159same prefix you must decide which version (if any) is your "primary" version.
160Install that version using "make install". Install all other versions using
161"make altinstall".
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000162
Ned Deilyffb40e52015-05-27 22:00:46 -0700163For example, if you want to install Python 2.6, 2.7 and 3.6 with 2.7 being the
Georg Brandlfa2c61a2011-02-20 10:41:31 +0000164primary version, you would execute "make install" in your 2.7 build directory
Georg Brandla02607e2010-07-31 11:00:47 +0000165and "make altinstall" in the others.
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000166
167
Guido van Rossum1c896e32007-08-29 23:03:30 +0000168Issue Tracker and Mailing List
169------------------------------
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000170
Georg Brandla02607e2010-07-31 11:00:47 +0000171We're soliciting bug reports about all aspects of the language. Fixes are also
Larry Hastingsf92f6c82015-09-12 17:28:39 +0100172welcome, preferably in unified diff format. Please use the issue tracker:
Fred Drake6caae142000-10-25 17:51:02 +0000173
Guido van Rossum1c896e32007-08-29 23:03:30 +0000174 http://bugs.python.org/
Guido van Rossum76be6ed1995-01-02 18:33:54 +0000175
Georg Brandla02607e2010-07-31 11:00:47 +0000176If you're not sure whether you're dealing with a bug or a feature, use the
177mailing list:
Guido van Rossum1c896e32007-08-29 23:03:30 +0000178
Mark Dickinsonb9ebd042009-02-06 16:39:11 +0000179 python-dev@python.org
Guido van Rossum1c896e32007-08-29 23:03:30 +0000180
181To subscribe to the list, use the mailman form:
182
Mark Dickinsonb9ebd042009-02-06 16:39:11 +0000183 http://mail.python.org/mailman/listinfo/python-dev/
Georg Brandl81299ad2006-02-20 10:24:06 +0000184
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000185
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000186Proposals for enhancement
187-------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000188
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000189If you have a proposal to change Python, you may want to send an email to the
Georg Brandl260a7882011-02-20 10:29:04 +0000190comp.lang.python or python-ideas mailing lists for inital feedback. A Python
191Enhancement Proposal (PEP) may be submitted if your idea gains ground. All
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000192current PEPs, as well as guidelines for submitting a new PEP, are listed at
193http://www.python.org/dev/peps/.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000194
Guido van Rossum1c896e32007-08-29 23:03:30 +0000195
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000196Release Schedule
197----------------
Guido van Rossum1c896e32007-08-29 23:03:30 +0000198
Larry Hastings45d1c002015-08-25 14:21:59 -0700199See PEP 494 for release details: http://www.python.org/dev/peps/pep-0494/
Guido van Rossumef0f1292007-08-30 14:51:05 +0000200
201
202Copyright and License Information
203---------------------------------
204
Georg Brandla7d2f002013-03-23 16:06:13 +0100205Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
Benjamin Petersonf1dcdd92016-01-01 11:53:14 -06002062012, 2013, 2014, 2015, 2016 Python Software Foundation. All rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000207
Georg Brandl260a7882011-02-20 10:29:04 +0000208Copyright (c) 2000 BeOpen.com. All rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000209
Georg Brandl260a7882011-02-20 10:29:04 +0000210Copyright (c) 1995-2001 Corporation for National Research Initiatives. All
211rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000212
Georg Brandl260a7882011-02-20 10:29:04 +0000213Copyright (c) 1991-1995 Stichting Mathematisch Centrum. All rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000214
Larry Hastingsf92f6c82015-09-12 17:28:39 +0100215See the file "LICENSE" for information on the history of this software,
216terms & conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000217
Larry Hastingsf92f6c82015-09-12 17:28:39 +0100218This Python distribution contains *no* GNU General Public License (GPL) code,
219so it may be used in proprietary projects. There are interfaces to some GNU
220code but these are entirely optional.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000221
Georg Brandl260a7882011-02-20 10:29:04 +0000222All trademarks referenced herein are property of their respective holders.