blob: 7ab7d019b2c8b48db3dbab66c457508da6961150 [file] [log] [blame]
Ned Deily5489bda2018-01-31 17:44:09 -05001This is Python version 3.8.0 alpha 0
2====================================
Guido van Rossum91447632000-04-11 17:11:09 +00003
Victor Stinnerc9b62b42017-02-13 16:57:30 +01004.. image:: https://travis-ci.org/python/cpython.svg?branch=master
5 :alt: CPython build status on Travis CI
6 :target: https://travis-ci.org/python/cpython
7
Zachary Wared31b28e2017-03-05 15:45:53 -06008.. image:: https://ci.appveyor.com/api/projects/status/4mew1a93xdkbf5ua/branch/master?svg=true
9 :alt: CPython build status on Appveyor
10 :target: https://ci.appveyor.com/project/python/cpython/branch/master
11
Victor Stinnerc9b62b42017-02-13 16:57:30 +010012.. image:: https://codecov.io/gh/python/cpython/branch/master/graph/badge.svg
13 :alt: CPython code coverage on Codecov
14 :target: https://codecov.io/gh/python/cpython
15
Benjamin Petersonf606e682011-12-31 22:42:26 -060016Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
Benjamin Peterson65f2a6d2018-01-04 22:34:19 -0800172012, 2013, 2014, 2015, 2016, 2017, 2018 Python Software Foundation. All rights
Benjamin Petersone527dd32017-01-01 22:04:13 -060018reserved.
Guido van Rossum4405cf32007-08-30 17:16:55 +000019
Zachary Wared50f1882017-02-13 22:01:03 -060020See the end of this file for further copyright and license information.
21
INADA Naoki7c8b3fa2017-02-28 16:26:58 +090022.. contents::
23
Mariattae32ec932017-02-25 08:59:26 -080024General Information
25-------------------
26
27- Website: https://www.python.org
28- Source code: https://github.com/python/cpython
29- Issue tracker: https://bugs.python.org
30- Documentation: https://docs.python.org
Lisa Hewus Fresh384899d2017-08-30 09:37:43 -070031- Developer's Guide: https://devguide.python.org/
Mariattae32ec932017-02-25 08:59:26 -080032
Nick Coghlan1b3d88e2017-02-18 12:01:47 +053033Contributing to CPython
34-----------------------
35
36For more complete instructions on contributing to CPython development,
37see the `Developer Guide`_.
38
Lisa Hewus Fresh384899d2017-08-30 09:37:43 -070039.. _Developer Guide: https://devguide.python.org/
Guido van Rossum1c896e32007-08-29 23:03:30 +000040
Ned Batchelder3cdbd682017-02-13 12:05:47 -050041Using Python
42------------
43
44Installable Python kits, and information about using Python, are available at
45`python.org`_.
46
47.. _python.org: https://www.python.org/
48
Benjamin Peterson1da43e52009-06-26 13:21:52 +000049Build Instructions
50------------------
Guido van Rossum3ff96dd1996-07-30 18:05:04 +000051
Paul Schreiberc0866852017-02-20 08:08:59 -050052On Unix, Linux, BSD, macOS, and Cygwin::
Benjamin Peterson1da43e52009-06-26 13:21:52 +000053
54 ./configure
55 make
56 make test
57 sudo make install
58
59This will install Python as python3.
60
Zachary Wared50f1882017-02-13 22:01:03 -060061You can pass many options to the configure script; run ``./configure --help``
Paul Schreiberc0866852017-02-20 08:08:59 -050062to find out more. On macOS and Cygwin, the executable is called ``python.exe``;
Victor Stinnerd783b012017-02-11 02:21:38 +010063elsewhere it's just ``python``.
Benjamin Peterson1da43e52009-06-26 13:21:52 +000064
Paul Schreiberc0866852017-02-20 08:08:59 -050065On macOS, if you have configured Python with ``--enable-framework``, you
Zachary Wared50f1882017-02-13 22:01:03 -060066should use ``make frameworkinstall`` to do the installation. Note that this
67installs the Python executable in a place that is not normally on your PATH,
68you may want to set up a symlink in ``/usr/local/bin``.
Benjamin Peterson1da43e52009-06-26 13:21:52 +000069
Zachary Wared50f1882017-02-13 22:01:03 -060070On Windows, see `PCbuild/readme.txt
71<https://github.com/python/cpython/blob/master/PCbuild/readme.txt>`_.
Benjamin Peterson1da43e52009-06-26 13:21:52 +000072
Larry Hastingsf92f6c82015-09-12 17:28:39 +010073If you wish, you can create a subdirectory and invoke configure from there.
Victor Stinnerd783b012017-02-11 02:21:38 +010074For example::
Benjamin Peterson1da43e52009-06-26 13:21:52 +000075
76 mkdir debug
77 cd debug
78 ../configure --with-pydebug
79 make
80 make test
81
Zachary Wared50f1882017-02-13 22:01:03 -060082(This will fail if you *also* built at the top-level directory. You should do
83a ``make clean`` at the toplevel first.)
Benjamin Peterson1da43e52009-06-26 13:21:52 +000084
Zachary Wared50f1882017-02-13 22:01:03 -060085To get an optimized build of Python, ``configure --enable-optimizations``
86before you run ``make``. This sets the default make targets up to enable
87Profile Guided Optimization (PGO) and may be used to auto-enable Link Time
88Optimization (LTO) on some platforms. For more details, see the sections
89below.
Brett Cannon7188a3e2015-09-18 15:13:44 -070090
91
92Profile Guided Optimization
Evan Klitzke6db764a2017-02-27 22:32:07 -080093^^^^^^^^^^^^^^^^^^^^^^^^^^^
Brett Cannon7188a3e2015-09-18 15:13:44 -070094
Zachary Wared50f1882017-02-13 22:01:03 -060095PGO takes advantage of recent versions of the GCC or Clang compilers. If ran,
96``make profile-opt`` will do several steps.
Brett Cannon7188a3e2015-09-18 15:13:44 -070097
Zachary Wared50f1882017-02-13 22:01:03 -060098First, the entire Python directory is cleaned of temporary files that may have
99resulted in a previous compilation.
Brett Cannon7188a3e2015-09-18 15:13:44 -0700100
101Then, an instrumented version of the interpreter is built, using suitable
Zachary Wared50f1882017-02-13 22:01:03 -0600102compiler flags for each flavour. Note that this is just an intermediary step
103and the binary resulted after this step is not good for real life workloads, as
104it has profiling instructions embedded inside.
Brett Cannon7188a3e2015-09-18 15:13:44 -0700105
Zachary Wared50f1882017-02-13 22:01:03 -0600106After this instrumented version of the interpreter is built, the Makefile will
107automatically run a training workload. This is necessary in order to profile
108the interpreter execution. Note also that any output, both stdout and stderr,
109that may appear at this step is suppressed.
Brett Cannon7188a3e2015-09-18 15:13:44 -0700110
111Finally, the last step is to rebuild the interpreter, using the information
Zachary Wared50f1882017-02-13 22:01:03 -0600112collected in the previous one. The end result will be a Python binary that is
113optimized and suitable for distribution or production installation.
Brett Cannon7188a3e2015-09-18 15:13:44 -0700114
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000115
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)014d52f2016-09-08 18:33:00 +0000116Link Time Optimization
Evan Klitzke6db764a2017-02-27 22:32:07 -0800117^^^^^^^^^^^^^^^^^^^^^^
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)014d52f2016-09-08 18:33:00 +0000118
Zachary Wared50f1882017-02-13 22:01:03 -0600119Enabled via configure's ``--with-lto`` flag. LTO takes advantage of the
120ability of recent compiler toolchains to optimize across the otherwise
121arbitrary ``.o`` file boundary when building final executables or shared
122libraries for additional performance gains.
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)014d52f2016-09-08 18:33:00 +0000123
124
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000125What's New
126----------
127
Zachary Wared50f1882017-02-13 22:01:03 -0600128We have a comprehensive overview of the changes in the `What's New in Python
Ned Deily5489bda2018-01-31 17:44:09 -05001293.8 <https://docs.python.org/3.8/whatsnew/3.8.html>`_ document. For a more
Zachary Wared50f1882017-02-13 22:01:03 -0600130detailed change log, read `Misc/NEWS
Mariatta1b8f6122017-09-13 16:47:33 -0700131<https://github.com/python/cpython/blob/master/Misc/NEWS.d>`_, but a full
Zachary Wared50f1882017-02-13 22:01:03 -0600132accounting of changes can only be gleaned from the `commit history
133<https://github.com/python/cpython/commits/master>`_.
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000134
135If you want to install multiple versions of Python see the section below
136entitled "Installing multiple versions".
Guido van Rossum8d90f9d1997-05-22 20:13:25 +0000137
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000138
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000139Documentation
140-------------
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000141
Ned Deily5489bda2018-01-31 17:44:09 -0500142`Documentation for Python 3.8 <https://docs.python.org/3.8/>`_ is online,
Victor Stinnerd783b012017-02-11 02:21:38 +0100143updated daily.
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000144
Georg Brandl62069d32010-07-31 08:56:11 +0000145It can also be downloaded in many formats for faster access. The documentation
146is downloadable in HTML, PDF, and reStructuredText formats; the latter version
147is primarily for documentation authors, translators, and people with special
148formatting requirements.
Benjamin Peterson2a691a82008-03-31 01:51:45 +0000149
Rogerb3f1f592017-02-15 17:54:05 -0500150For information about building Python's documentation, refer to `Doc/README.rst
151<https://github.com/python/cpython/blob/master/Doc/README.rst>`_.
Ezio Melotti802bf8a2013-08-16 21:32:25 +0300152
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000153
Barry Warsaw97f005d2008-12-03 16:46:14 +0000154Converting From Python 2.x to 3.x
Guido van Rossum1c896e32007-08-29 23:03:30 +0000155---------------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000156
Zachary Wared50f1882017-02-13 22:01:03 -0600157Significant backward incompatible changes were made for the release of Python
1583.0, which may cause programs written for Python 2 to fail when run with Python
1593. For more information about porting your code from Python 2 to Python 3, see
160the `Porting HOWTO <https://docs.python.org/3/howto/pyporting.html>`_.
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000161
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000162
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000163Testing
164-------
165
Zachary Wared50f1882017-02-13 22:01:03 -0600166To test the interpreter, type ``make test`` in the top-level directory. The
167test set produces some output. You can generally ignore the messages about
168skipped tests due to optional features which can't be imported. If a message
169is printed about a failed test or a traceback or core dump is produced,
170something is wrong.
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000171
172By default, tests are prevented from overusing resources like disk space and
Victor Stinnerd783b012017-02-11 02:21:38 +0100173memory. To enable these tests, run ``make testall``.
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000174
Zachary Wared50f1882017-02-13 22:01:03 -0600175If any tests fail, you can re-run the failing test(s) in verbose mode::
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000176
Zachary Wared50f1882017-02-13 22:01:03 -0600177 make test TESTOPTS="-v test_that_failed"
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000178
Zachary Wared50f1882017-02-13 22:01:03 -0600179If the failure persists and appears to be a problem with Python rather than
180your environment, you can `file a bug report <https://bugs.python.org>`_ and
181include relevant output from that command to show the issue.
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000182
183
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000184Installing multiple versions
185----------------------------
186
187On Unix and Mac systems if you intend to install multiple versions of Python
Zachary Wared50f1882017-02-13 22:01:03 -0600188using the same installation prefix (``--prefix`` argument to the configure
189script) you must take care that your primary python executable is not
190overwritten by the installation of a different version. All files and
191directories installed using ``make altinstall`` contain the major and minor
192version and can thus live side-by-side. ``make install`` also creates
193``${prefix}/bin/python3`` which refers to ``${prefix}/bin/pythonX.Y``. If you
194intend to install multiple versions using the same prefix you must decide which
195version (if any) is your "primary" version. Install that version using ``make
196install``. Install all other versions using ``make altinstall``.
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000197
Ned Deily5489bda2018-01-31 17:44:09 -0500198For example, if you want to install Python 2.7, 3.6, and 3.8 with 3.8 being the
199primary version, you would execute ``make install`` in your 3.8 build directory
Victor Stinnerd783b012017-02-11 02:21:38 +0100200and ``make altinstall`` in the others.
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000201
202
Guido van Rossum1c896e32007-08-29 23:03:30 +0000203Issue Tracker and Mailing List
204------------------------------
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000205
Zachary Wared50f1882017-02-13 22:01:03 -0600206Bug reports are welcome! You can use the `issue tracker
207<https://bugs.python.org>`_ to report bugs, and/or submit pull requests `on
208GitHub <https://github.com/python/cpython>`_.
Guido van Rossum76be6ed1995-01-02 18:33:54 +0000209
Zachary Wared50f1882017-02-13 22:01:03 -0600210You can also follow development discussion on the `python-dev mailing list
211<https://mail.python.org/mailman/listinfo/python-dev/>`_.
Georg Brandl81299ad2006-02-20 10:24:06 +0000212
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000213
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000214Proposals for enhancement
215-------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000216
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000217If you have a proposal to change Python, you may want to send an email to the
Zachary Wared50f1882017-02-13 22:01:03 -0600218comp.lang.python or `python-ideas`_ mailing lists for initial feedback. A
219Python Enhancement Proposal (PEP) may be submitted if your idea gains ground.
220All current PEPs, as well as guidelines for submitting a new PEP, are listed at
Victor Stinnerd783b012017-02-11 02:21:38 +0100221`python.org/dev/peps/ <https://www.python.org/dev/peps/>`_.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000222
Ned Batchelder3cdbd682017-02-13 12:05:47 -0500223.. _python-ideas: https://mail.python.org/mailman/listinfo/python-ideas/
Guido van Rossum1c896e32007-08-29 23:03:30 +0000224
Zachary Wared50f1882017-02-13 22:01:03 -0600225
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000226Release Schedule
227----------------
Guido van Rossum1c896e32007-08-29 23:03:30 +0000228
Ned Deily5489bda2018-01-31 17:44:09 -0500229See :pep:`569` for Python 3.8 release details.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000230
231
232Copyright and License Information
233---------------------------------
234
Georg Brandla7d2f002013-03-23 16:06:13 +0100235Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
Benjamin Peterson65f2a6d2018-01-04 22:34:19 -08002362012, 2013, 2014, 2015, 2016, 2017, 2018 Python Software Foundation. All rights
Christian Heimes0c72a0c2017-09-07 13:59:13 -0700237reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000238
Georg Brandl260a7882011-02-20 10:29:04 +0000239Copyright (c) 2000 BeOpen.com. All rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000240
Georg Brandl260a7882011-02-20 10:29:04 +0000241Copyright (c) 1995-2001 Corporation for National Research Initiatives. All
242rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000243
Georg Brandl260a7882011-02-20 10:29:04 +0000244Copyright (c) 1991-1995 Stichting Mathematisch Centrum. All rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000245
Zachary Wared50f1882017-02-13 22:01:03 -0600246See the file "LICENSE" for information on the history of this software, terms &
247conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000248
Larry Hastingsf92f6c82015-09-12 17:28:39 +0100249This Python distribution contains *no* GNU General Public License (GPL) code,
250so it may be used in proprietary projects. There are interfaces to some GNU
251code but these are entirely optional.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000252
Georg Brandl260a7882011-02-20 10:29:04 +0000253All trademarks referenced herein are property of their respective holders.