1 This is Python version 3.7.3
2 ============================
3
4 .. 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
8 .. 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
12 .. image:: https://dev.azure.com/python/cpython/_apis/build/status/Azure%20Pipelines%20CI?branchName=3.7
13 :alt: CPython build status on Azure Pipelines
14 :target: https://dev.azure.com/python/cpython/_build/latest?definitionId=4&branchName=3.7
15
16 .. 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
20 Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
21 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Python Software Foundation. All
22 rights reserved.
23
24 See the end of this file for further copyright and license information.
25
26 .. contents::
27
28 General Information
29 -------------------
30
31 - Website: https://www.python.org
32 - Source code: https://github.com/python/cpython
33 - Issue tracker: https://bugs.python.org
34 - Documentation: https://docs.python.org
35 - Developer's Guide: https://devguide.python.org/
36
37 Contributing to CPython
38 -----------------------
39
40 For more complete instructions on contributing to CPython development,
41 see the `Developer Guide`_.
42
43 .. _Developer Guide: https://devguide.python.org/
44
45 Using Python
46 ------------
47
48 Installable Python kits, and information about using Python, are available at
49 `python.org`_.
50
51 .. _python.org: https://www.python.org/
52
53 Build Instructions
54 ------------------
55
56 On Unix, Linux, BSD, macOS, and Cygwin::
57
58 ./configure
59 make
60 make test
61 sudo make install
62
63 This will install Python as ``python3``.
64
65 You can pass many options to the configure script; run ``./configure --help``
66 to find out more. On macOS and Cygwin, the executable is called ``python.exe``;
67 elsewhere it's just ``python``.
68
69 If you are running on macOS with the latest updates installed, make sure to install
70 openSSL or some other SSL software along with Homebrew or another package manager.
71 If issues persist, see https://devguide.python.org/setup/#macos-and-os-x for more
72 information.
73
74 On macOS, if you have configured Python with ``--enable-framework``, you
75 should use ``make frameworkinstall`` to do the installation. Note that this
76 installs the Python executable in a place that is not normally on your PATH,
77 you may want to set up a symlink in ``/usr/local/bin``.
78
79 On Windows, see `PCbuild/readme.txt
80 <https://github.com/python/cpython/blob/master/PCbuild/readme.txt>`_.
81
82 If you wish, you can create a subdirectory and invoke configure from there.
83 For example::
84
85 mkdir debug
86 cd debug
87 ../configure --with-pydebug
88 make
89 make test
90
91 (This will fail if you *also* built at the top-level directory. You should do
92 a ``make clean`` at the toplevel first.)
93
94 To get an optimized build of Python, ``configure --enable-optimizations``
95 before you run ``make``. This sets the default make targets up to enable
96 Profile Guided Optimization (PGO) and may be used to auto-enable Link Time
97 Optimization (LTO) on some platforms. For more details, see the sections
98 below.
99
100
101 Profile Guided Optimization
102 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
103
104 PGO takes advantage of recent versions of the GCC or Clang compilers. If used,
105 either via ``configure --enable-optimizations`` or by manually running
106 ``make profile-opt`` regardless of configure flags, the optimized build
107 process will perform the following steps:
108
109 The entire Python directory is cleaned of temporary files that may have
110 resulted from a previous compilation.
111
112 An instrumented version of the interpreter is built, using suitable compiler
113 flags for each flavour. Note that this is just an intermediary step. The
114 binary resulting from this step is not good for real life workloads as it has
115 profiling instructions embedded inside.
116
117 After the instrumented interpreter is built, the Makefile will run a training
118 workload. This is necessary in order to profile the interpreter execution.
119 Note also that any output, both stdout and stderr, that may appear at this step
120 is suppressed.
121
122 The final step is to build the actual interpreter, using the information
123 collected from the instrumented one. The end result will be a Python binary
124 that is optimized; suitable for distribution or production installation.
125
126
127 Link Time Optimization
128 ^^^^^^^^^^^^^^^^^^^^^^
129
130 Enabled via configure's ``--with-lto`` flag. LTO takes advantage of the
131 ability of recent compiler toolchains to optimize across the otherwise
132 arbitrary ``.o`` file boundary when building final executables or shared
133 libraries for additional performance gains.
134
135
136 What's New
137 ----------
138
139 We have a comprehensive overview of the changes in the `What's New in Python
140 3.7 <https://docs.python.org/3.7/whatsnew/3.7.html>`_ document. For a more
141 detailed change log, read `Misc/NEWS
142 <https://github.com/python/cpython/blob/master/Misc/NEWS.d>`_, but a full
143 accounting of changes can only be gleaned from the `commit history
144 <https://github.com/python/cpython/commits/master>`_.
145
146 If you want to install multiple versions of Python see the section below
147 entitled "Installing multiple versions".
148
149
150 Documentation
151 -------------
152
153 `Documentation for Python 3.7 <https://docs.python.org/3.7/>`_ is online,
154 updated daily.
155
156 It can also be downloaded in many formats for faster access. The documentation
157 is downloadable in HTML, PDF, and reStructuredText formats; the latter version
158 is primarily for documentation authors, translators, and people with special
159 formatting requirements.
160
161 For information about building Python's documentation, refer to `Doc/README.rst
162 <https://github.com/python/cpython/blob/master/Doc/README.rst>`_.
163
164
165 Converting From Python 2.x to 3.x
166 ---------------------------------
167
168 Significant backward incompatible changes were made for the release of Python
169 3.0, which may cause programs written for Python 2 to fail when run with Python
170 3. For more information about porting your code from Python 2 to Python 3, see
171 the `Porting HOWTO <https://docs.python.org/3/howto/pyporting.html>`_.
172
173
174 Testing
175 -------
176
177 To test the interpreter, type ``make test`` in the top-level directory. The
178 test set produces some output. You can generally ignore the messages about
179 skipped tests due to optional features which can't be imported. If a message
180 is printed about a failed test or a traceback or core dump is produced,
181 something is wrong.
182
183 By default, tests are prevented from overusing resources like disk space and
184 memory. To enable these tests, run ``make testall``.
185
186 If any tests fail, you can re-run the failing test(s) in verbose mode. For
187 example, if ``test_os`` and ``test_gdb`` failed, you can run::
188
189 make test TESTOPTS="-v test_os test_gdb"
190
191 If the failure persists and appears to be a problem with Python rather than
192 your environment, you can `file a bug report <https://bugs.python.org>`_ and
193 include relevant output from that command to show the issue.
194
195 See `Running & Writing Tests <https://devguide.python.org/runtests/>`_
196 for more on running tests.
197
198 Installing multiple versions
199 ----------------------------
200
201 On Unix and Mac systems if you intend to install multiple versions of Python
202 using the same installation prefix (``--prefix`` argument to the configure
203 script) you must take care that your primary python executable is not
204 overwritten by the installation of a different version. All files and
205 directories installed using ``make altinstall`` contain the major and minor
206 version and can thus live side-by-side. ``make install`` also creates
207 ``${prefix}/bin/python3`` which refers to ``${prefix}/bin/pythonX.Y``. If you
208 intend to install multiple versions using the same prefix you must decide which
209 version (if any) is your "primary" version. Install that version using ``make
210 install``. Install all other versions using ``make altinstall``.
211
212 For example, if you want to install Python 2.7, 3.6, and 3.7 with 3.7 being the
213 primary version, you would execute ``make install`` in your 3.7 build directory
214 and ``make altinstall`` in the others.
215
216
217 Issue Tracker and Mailing List
218 ------------------------------
219
220 Bug reports are welcome! You can use the `issue tracker
221 <https://bugs.python.org>`_ to report bugs, and/or submit pull requests `on
222 GitHub <https://github.com/python/cpython>`_.
223
224 You can also follow development discussion on the `python-dev mailing list
225 <https://mail.python.org/mailman/listinfo/python-dev/>`_.
226
227
228 Proposals for enhancement
229 -------------------------
230
231 If you have a proposal to change Python, you may want to send an email to the
232 comp.lang.python or `python-ideas`_ mailing lists for initial feedback. A
233 Python Enhancement Proposal (PEP) may be submitted if your idea gains ground.
234 All current PEPs, as well as guidelines for submitting a new PEP, are listed at
235 `python.org/dev/peps/ <https://www.python.org/dev/peps/>`_.
236
237 .. _python-ideas: https://mail.python.org/mailman/listinfo/python-ideas/
238
239
240 Release Schedule
241 ----------------
242
243 See :pep:`537` for Python 3.7 release details.
244
245
246 Copyright and License Information
247 ---------------------------------
248
249 Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
250 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Python Software Foundation. All
251 rights reserved.
252
253 Copyright (c) 2000 BeOpen.com. All rights reserved.
254
255 Copyright (c) 1995-2001 Corporation for National Research Initiatives. All
256 rights reserved.
257
258 Copyright (c) 1991-1995 Stichting Mathematisch Centrum. All rights reserved.
259
260 See the file "LICENSE" for information on the history of this software, terms &
261 conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.
262
263 This Python distribution contains *no* GNU General Public License (GPL) code,
264 so it may be used in proprietary projects. There are interfaces to some GNU
265 code but these are entirely optional.
266
267 All trademarks referenced herein are property of their respective holders.
268