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