blob: 61281042e3bde6e17e21a8399bdedc423263a61e [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
Steve Dower680d26e2018-09-24 08:04:33 -040012.. image:: https://dev.azure.com/python/cpython/_apis/build/status/Azure%20Pipelines%20CI?branchName=master
13 :alt: CPython build status on Azure DevOps
Steve Dowerb7d613f2018-09-11 10:47:46 -070014 :target: https://dev.azure.com/python/cpython/_build/latest?definitionId=4&branchName=master
Steve Dower757b73c2018-08-31 08:11:35 -070015
Victor Stinnerc9b62b42017-02-13 16:57:30 +010016.. image:: https://codecov.io/gh/python/cpython/branch/master/graph/badge.svg
17 :alt: CPython code coverage on Codecov
18 :target: https://codecov.io/gh/python/cpython
19
Mariattab57eea12018-06-29 13:43:45 -070020.. image:: https://img.shields.io/badge/zulip-join_chat-brightgreen.svg
21 :alt: Python Zulip chat
22 :target: https://python.zulipchat.com
Steve Dower757b73c2018-08-31 08:11:35 -070023
Mariattab57eea12018-06-29 13:43:45 -070024
David Kleuker9d43fa12018-11-10 04:45:40 +010025Copyright (c) 2001-2018 Python Software Foundation. All rights reserved.
Guido van Rossum4405cf32007-08-30 17:16:55 +000026
Zachary Wared50f1882017-02-13 22:01:03 -060027See the end of this file for further copyright and license information.
28
INADA Naoki7c8b3fa2017-02-28 16:26:58 +090029.. contents::
30
Mariattae32ec932017-02-25 08:59:26 -080031General Information
32-------------------
33
34- Website: https://www.python.org
35- Source code: https://github.com/python/cpython
36- Issue tracker: https://bugs.python.org
37- Documentation: https://docs.python.org
Lisa Hewus Fresh384899d2017-08-30 09:37:43 -070038- Developer's Guide: https://devguide.python.org/
Mariattae32ec932017-02-25 08:59:26 -080039
Nick Coghlan1b3d88e2017-02-18 12:01:47 +053040Contributing to CPython
41-----------------------
42
43For more complete instructions on contributing to CPython development,
44see the `Developer Guide`_.
45
Lisa Hewus Fresh384899d2017-08-30 09:37:43 -070046.. _Developer Guide: https://devguide.python.org/
Guido van Rossum1c896e32007-08-29 23:03:30 +000047
Ned Batchelder3cdbd682017-02-13 12:05:47 -050048Using Python
49------------
50
51Installable Python kits, and information about using Python, are available at
52`python.org`_.
53
54.. _python.org: https://www.python.org/
55
Benjamin Peterson1da43e52009-06-26 13:21:52 +000056Build Instructions
57------------------
Guido van Rossum3ff96dd1996-07-30 18:05:04 +000058
Paul Schreiberc0866852017-02-20 08:08:59 -050059On Unix, Linux, BSD, macOS, and Cygwin::
Benjamin Peterson1da43e52009-06-26 13:21:52 +000060
61 ./configure
62 make
63 make test
64 sudo make install
65
66This will install Python as python3.
67
Zachary Wared50f1882017-02-13 22:01:03 -060068You can pass many options to the configure script; run ``./configure --help``
Paul Schreiberc0866852017-02-20 08:08:59 -050069to find out more. On macOS and Cygwin, the executable is called ``python.exe``;
Victor Stinnerd783b012017-02-11 02:21:38 +010070elsewhere it's just ``python``.
Benjamin Peterson1da43e52009-06-26 13:21:52 +000071
atg7000ee994d72018-06-07 19:33:20 -070072If you are running on macOS with the latest updates installed, make sure to install
73openSSL or some other SSL software along with Homebrew or another package manager.
74If issues persist, see https://devguide.python.org/setup/#macos-and-os-x for more
75information.
76
Paul Schreiberc0866852017-02-20 08:08:59 -050077On macOS, if you have configured Python with ``--enable-framework``, you
Zachary Wared50f1882017-02-13 22:01:03 -060078should use ``make frameworkinstall`` to do the installation. Note that this
79installs the Python executable in a place that is not normally on your PATH,
80you may want to set up a symlink in ``/usr/local/bin``.
Benjamin Peterson1da43e52009-06-26 13:21:52 +000081
Zachary Wared50f1882017-02-13 22:01:03 -060082On Windows, see `PCbuild/readme.txt
83<https://github.com/python/cpython/blob/master/PCbuild/readme.txt>`_.
Benjamin Peterson1da43e52009-06-26 13:21:52 +000084
Larry Hastingsf92f6c82015-09-12 17:28:39 +010085If you wish, you can create a subdirectory and invoke configure from there.
Victor Stinnerd783b012017-02-11 02:21:38 +010086For example::
Benjamin Peterson1da43e52009-06-26 13:21:52 +000087
88 mkdir debug
89 cd debug
90 ../configure --with-pydebug
91 make
92 make test
93
Zachary Wared50f1882017-02-13 22:01:03 -060094(This will fail if you *also* built at the top-level directory. You should do
95a ``make clean`` at the toplevel first.)
Benjamin Peterson1da43e52009-06-26 13:21:52 +000096
Zachary Wared50f1882017-02-13 22:01:03 -060097To get an optimized build of Python, ``configure --enable-optimizations``
98before you run ``make``. This sets the default make targets up to enable
99Profile Guided Optimization (PGO) and may be used to auto-enable Link Time
100Optimization (LTO) on some platforms. For more details, see the sections
101below.
Brett Cannon7188a3e2015-09-18 15:13:44 -0700102
103
104Profile Guided Optimization
Evan Klitzke6db764a2017-02-27 22:32:07 -0800105^^^^^^^^^^^^^^^^^^^^^^^^^^^
Brett Cannon7188a3e2015-09-18 15:13:44 -0700106
Gregory P. Smithb87c1c92018-04-19 08:58:17 -0700107PGO takes advantage of recent versions of the GCC or Clang compilers. If used,
Gregory P. Smith93f9a8a2018-05-16 10:34:47 -0500108either via ``configure --enable-optimizations`` or by manually running
109``make profile-opt`` regardless of configure flags, the optimized build
110process will perform the following steps:
Brett Cannon7188a3e2015-09-18 15:13:44 -0700111
Gregory P. Smith93f9a8a2018-05-16 10:34:47 -0500112The entire Python directory is cleaned of temporary files that may have
113resulted from a previous compilation.
Brett Cannon7188a3e2015-09-18 15:13:44 -0700114
Gregory P. Smith93f9a8a2018-05-16 10:34:47 -0500115An instrumented version of the interpreter is built, using suitable compiler
116flags for each flavour. Note that this is just an intermediary step. The
117binary resulting from this step is not good for real life workloads as it has
118profiling instructions embedded inside.
Brett Cannon7188a3e2015-09-18 15:13:44 -0700119
Gregory P. Smith93f9a8a2018-05-16 10:34:47 -0500120After the instrumented interpreter is built, the Makefile will run a training
121workload. This is necessary in order to profile the interpreter execution.
122Note also that any output, both stdout and stderr, that may appear at this step
123is suppressed.
Brett Cannon7188a3e2015-09-18 15:13:44 -0700124
Gregory P. Smith93f9a8a2018-05-16 10:34:47 -0500125The final step is to build the actual interpreter, using the information
126collected from the instrumented one. The end result will be a Python binary
127that is optimized; suitable for distribution or production installation.
Brett Cannon7188a3e2015-09-18 15:13:44 -0700128
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000129
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)014d52f2016-09-08 18:33:00 +0000130Link Time Optimization
Evan Klitzke6db764a2017-02-27 22:32:07 -0800131^^^^^^^^^^^^^^^^^^^^^^
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)014d52f2016-09-08 18:33:00 +0000132
Zachary Wared50f1882017-02-13 22:01:03 -0600133Enabled via configure's ``--with-lto`` flag. LTO takes advantage of the
134ability of recent compiler toolchains to optimize across the otherwise
135arbitrary ``.o`` file boundary when building final executables or shared
136libraries for additional performance gains.
Gregory P. Smith ext:(%20%5BGoogle%20Inc.%5D)014d52f2016-09-08 18:33:00 +0000137
138
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000139What's New
140----------
141
Zachary Wared50f1882017-02-13 22:01:03 -0600142We have a comprehensive overview of the changes in the `What's New in Python
Ned Deily5489bda2018-01-31 17:44:09 -05001433.8 <https://docs.python.org/3.8/whatsnew/3.8.html>`_ document. For a more
Zachary Wared50f1882017-02-13 22:01:03 -0600144detailed change log, read `Misc/NEWS
Mariatta1b8f6122017-09-13 16:47:33 -0700145<https://github.com/python/cpython/blob/master/Misc/NEWS.d>`_, but a full
Zachary Wared50f1882017-02-13 22:01:03 -0600146accounting of changes can only be gleaned from the `commit history
147<https://github.com/python/cpython/commits/master>`_.
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000148
149If you want to install multiple versions of Python see the section below
150entitled "Installing multiple versions".
Guido van Rossum8d90f9d1997-05-22 20:13:25 +0000151
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000152
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000153Documentation
154-------------
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000155
Ned Deily5489bda2018-01-31 17:44:09 -0500156`Documentation for Python 3.8 <https://docs.python.org/3.8/>`_ is online,
Victor Stinnerd783b012017-02-11 02:21:38 +0100157updated daily.
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000158
Georg Brandl62069d32010-07-31 08:56:11 +0000159It can also be downloaded in many formats for faster access. The documentation
160is downloadable in HTML, PDF, and reStructuredText formats; the latter version
161is primarily for documentation authors, translators, and people with special
162formatting requirements.
Benjamin Peterson2a691a82008-03-31 01:51:45 +0000163
Rogerb3f1f592017-02-15 17:54:05 -0500164For information about building Python's documentation, refer to `Doc/README.rst
165<https://github.com/python/cpython/blob/master/Doc/README.rst>`_.
Ezio Melotti802bf8a2013-08-16 21:32:25 +0300166
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000167
Barry Warsaw97f005d2008-12-03 16:46:14 +0000168Converting From Python 2.x to 3.x
Guido van Rossum1c896e32007-08-29 23:03:30 +0000169---------------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000170
Zachary Wared50f1882017-02-13 22:01:03 -0600171Significant backward incompatible changes were made for the release of Python
1723.0, which may cause programs written for Python 2 to fail when run with Python
1733. For more information about porting your code from Python 2 to Python 3, see
174the `Porting HOWTO <https://docs.python.org/3/howto/pyporting.html>`_.
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000175
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000176
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000177Testing
178-------
179
Zachary Wared50f1882017-02-13 22:01:03 -0600180To test the interpreter, type ``make test`` in the top-level directory. The
181test set produces some output. You can generally ignore the messages about
182skipped tests due to optional features which can't be imported. If a message
183is printed about a failed test or a traceback or core dump is produced,
184something is wrong.
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000185
186By default, tests are prevented from overusing resources like disk space and
Victor Stinnerd783b012017-02-11 02:21:38 +0100187memory. To enable these tests, run ``make testall``.
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000188
Aaron Ang0f914b52018-04-09 14:09:31 -0700189If any tests fail, you can re-run the failing test(s) in verbose mode. For
190example, if ``test_os`` and ``test_gdb`` failed, you can run::
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000191
Aaron Ang0f914b52018-04-09 14:09:31 -0700192 make test TESTOPTS="-v test_os test_gdb"
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000193
Zachary Wared50f1882017-02-13 22:01:03 -0600194If the failure persists and appears to be a problem with Python rather than
195your environment, you can `file a bug report <https://bugs.python.org>`_ and
196include relevant output from that command to show the issue.
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000197
Michael Osipovcae8ff92018-08-17 23:43:34 +0200198See `Running & Writing Tests <https://devguide.python.org/runtests/>`_
199for more on running tests.
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000200
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000201Installing multiple versions
202----------------------------
203
204On Unix and Mac systems if you intend to install multiple versions of Python
Zachary Wared50f1882017-02-13 22:01:03 -0600205using the same installation prefix (``--prefix`` argument to the configure
206script) you must take care that your primary python executable is not
207overwritten by the installation of a different version. All files and
208directories installed using ``make altinstall`` contain the major and minor
209version and can thus live side-by-side. ``make install`` also creates
210``${prefix}/bin/python3`` which refers to ``${prefix}/bin/pythonX.Y``. If you
211intend to install multiple versions using the same prefix you must decide which
212version (if any) is your "primary" version. Install that version using ``make
213install``. Install all other versions using ``make altinstall``.
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000214
Ned Deily5489bda2018-01-31 17:44:09 -0500215For example, if you want to install Python 2.7, 3.6, and 3.8 with 3.8 being the
216primary version, you would execute ``make install`` in your 3.8 build directory
Victor Stinnerd783b012017-02-11 02:21:38 +0100217and ``make altinstall`` in the others.
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000218
219
Guido van Rossum1c896e32007-08-29 23:03:30 +0000220Issue Tracker and Mailing List
221------------------------------
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000222
Zachary Wared50f1882017-02-13 22:01:03 -0600223Bug reports are welcome! You can use the `issue tracker
224<https://bugs.python.org>`_ to report bugs, and/or submit pull requests `on
225GitHub <https://github.com/python/cpython>`_.
Guido van Rossum76be6ed1995-01-02 18:33:54 +0000226
Zachary Wared50f1882017-02-13 22:01:03 -0600227You can also follow development discussion on the `python-dev mailing list
228<https://mail.python.org/mailman/listinfo/python-dev/>`_.
Georg Brandl81299ad2006-02-20 10:24:06 +0000229
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000230
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000231Proposals for enhancement
232-------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000233
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000234If you have a proposal to change Python, you may want to send an email to the
Zachary Wared50f1882017-02-13 22:01:03 -0600235comp.lang.python or `python-ideas`_ mailing lists for initial feedback. A
236Python Enhancement Proposal (PEP) may be submitted if your idea gains ground.
237All current PEPs, as well as guidelines for submitting a new PEP, are listed at
Victor Stinnerd783b012017-02-11 02:21:38 +0100238`python.org/dev/peps/ <https://www.python.org/dev/peps/>`_.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000239
Ned Batchelder3cdbd682017-02-13 12:05:47 -0500240.. _python-ideas: https://mail.python.org/mailman/listinfo/python-ideas/
Guido van Rossum1c896e32007-08-29 23:03:30 +0000241
Zachary Wared50f1882017-02-13 22:01:03 -0600242
Benjamin Peterson1da43e52009-06-26 13:21:52 +0000243Release Schedule
244----------------
Guido van Rossum1c896e32007-08-29 23:03:30 +0000245
Ned Deily5489bda2018-01-31 17:44:09 -0500246See :pep:`569` for Python 3.8 release details.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000247
248
249Copyright and License Information
250---------------------------------
251
David Kleuker9d43fa12018-11-10 04:45:40 +0100252Copyright (c) 2001-2018 Python Software Foundation. All rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000253
Georg Brandl260a7882011-02-20 10:29:04 +0000254Copyright (c) 2000 BeOpen.com. All rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000255
Georg Brandl260a7882011-02-20 10:29:04 +0000256Copyright (c) 1995-2001 Corporation for National Research Initiatives. All
257rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000258
Georg Brandl260a7882011-02-20 10:29:04 +0000259Copyright (c) 1991-1995 Stichting Mathematisch Centrum. All rights reserved.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000260
Zachary Wared50f1882017-02-13 22:01:03 -0600261See the file "LICENSE" for information on the history of this software, terms &
262conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000263
Larry Hastingsf92f6c82015-09-12 17:28:39 +0100264This Python distribution contains *no* GNU General Public License (GPL) code,
265so it may be used in proprietary projects. There are interfaces to some GNU
266code but these are entirely optional.
Guido van Rossumef0f1292007-08-30 14:51:05 +0000267
Georg Brandl260a7882011-02-20 10:29:04 +0000268All trademarks referenced herein are property of their respective holders.