Python Developer’s Guide¶
This guide is a comprehensive resource for contributing to Python – for both new and experienced contributors. It is maintained by the same community that maintains Python. We welcome your contributions to Python!
Here are the basic steps needed to get set up and contribute a patch:
Set up and install dependencies.
Install Mercurial and other dependencies.
The dependencies needed will depend on the platform you’re on. Go to Get Setup page for detailed information.
hg clone https://hg.python.org/cpython
The command to compile on UNIX and Mac OS is:
./configure --with-pydebug make -j
PCbuild\build.bat -e -d
If the build outputs warnings or errors, Build dependencies provides detail on standard library extensions that depend on installing third-party libraries for some operating systems.
./python -m test -j3
Make the patch.
Submit it to the issue tracker.
Status of Python branches¶
|default||TBD||features||TBD||TBD||The default branch is currently the future version Python 3.7.|
|3.6||PEP 494||bugfix||2016-12-16||2021-12-16||For the beta and rc phases of the future 3.6.0, then maintenance for 3.6.x|
|2.7||PEP 373||bugfix||2010-07-03||2020-01-01||The support has been extended to 2020.|
|3.4||PEP 429||security||2014-03-16||2019-03-16||Last binary release: Python 3.4.4|
|3.3||PEP 398||security||2012-09-29||2017-09-29||Last binary release: Python 3.3.5|
|3.2||PEP 392||end-of-life||2011-02-20||2016-02-20||Last binary release: Python 3.2.5|
|3.1||PEP 375||end-of-life||2009-06-27||2012-04-11||Last release: Python 3.1.5|
|3.0||PEP 361||end-of-life||2008-12-03||2009-01-13||Last release: Python 3.0.1|
|2.6||PEP 361||end-of-life||2008-10-01||2013-10-29||Last release: Python 2.6.9|
|features:||new features are only added to the default branch, this branch accepts any kind of change.|
|bugfix:||bugfixes and security fixes are accepted, new binaries are still released.|
|security:||only security fixes are accepted and no more binaries are released, but new source-only versions can be released|
|end-of-life:||branch no longer maintained; no more changes can be pushed to this branch.|
Dates in italic are scheduled and can be adjusted.
By default, the end-of-life is scheduled 5 years after the first release. It can be adjusted by the release manager of each branch. Versions older than 2.7 have reached end-of-life.
See also Security branches.
We encourage everyone to contribute to Python and that’s why we have put up this developer’s guide. If you still have questions after reviewing the material in this guide, then the Python Mentors group is available to help guide new contributors through the process. The Developer FAQ is another useful source of information.
Guide for contributing to Python:
It is recommended that the above documents be read in the order listed. You can stop where you feel comfortable and begin contributing immediately without reading and understanding these documents all at once. If you do choose to skip around within the documentation, be aware that it is written assuming preceding documentation has been read so you may find it necessary to backtrack to fill in missing concepts and terminology.
Proposing changes to Python itself¶
Improving Python’s code, documentation and tests are ongoing tasks that are never going to be “finished”, as Python operates as part of an ever-evolving system of technology. An even more challenging ongoing task than these necessary maintenance activities is finding ways to make Python, in the form of the standard library and the language definition, an even better tool in a developer’s toolkit.
While these kinds of change are much rarer than those described above, they do happen and that process is also described as part of this guide:
Also refer to Where should I suggest new features and language changes? in the FAQ.
Other Interpreter Implementations¶
This guide is specifically for contributing to the Python reference interpreter, also known as CPython (while most of the standard library is written in Python, the interpreter core is written in C and integrates most easily with the C and C++ ecosystems).
There are other Python implementations, each with a different focus. Like CPython, they always have more things they would like to do than they have developers to work on them. Some major example that may be of interest are:
- PyPy: A Python interpreter focused on high speed (JIT-compiled) operation on major platforms
- Jython: A Python interpreter focused on good integration with the Java Virtual Machine (JVM) environment
- IronPython: A Python interpreter focused on good integration with the Common Language Runtime (CLR) provided by .NET and Mono
- Stackless: A Python interpreter focused on providing lightweight microthreads while remaining largely compatible with CPython specific extension modules
PEPs (Python Enhancement Proposals)
Anyone can clone the sources for this guide. See Helping with the Developer’s Guide.
Full Table of Contents¶
- 1. Getting Started
- 1.1. Getting Set Up
- 1.2. Editors and Tools
- 1.3. Directory Structure
- 2. Where to Get Help
- 3. Lifecycle of a Patch
- 4. Running & Writing Tests
- 5. Increase Test Coverage
- 6. Helping with Documentation
- 7. Documenting Python
- 7.1. Introduction
- 7.2. Style guide
- 7.3. reStructuredText Primer
- 7.4. Additional Markup Constructs
- 7.4.1. Meta-information markup
- 7.4.2. Module-specific markup
- 7.4.3. Information units
- 7.4.4. Showing code examples
- 7.4.5. Inline markup
- 7.4.6. Cross-linking markup
- 7.4.7. Paragraph-level markup
- 7.4.8. Table-of-contents markup
- 7.4.9. Index-generating markup
- 7.4.10. Grammar production displays
- 7.4.11. Substitutions
- 7.5. Building the documentation
- 8. Silence Warnings From the Test Suite
- 9. Fixing “easy” Issues (and Beyond)
- 10. Issue Tracking
- 10.1. Using the Issue Tracker
- 10.2. Helping Triage Issues
- 10.3. Gaining the “Developer” Role on the Issue Tracker
- 10.4. The Meta Tracker
- 11. Triaging an Issue
- 11.1. Fields
- 11.2. Generating Special Links in a Comment
- 12. Following Python’s Development
- 13. How to Become a Core Developer
- 14. Developer Log
- 15. Committing and Pushing Changes
- 16. Working with Mercurial
- 16.1. Minimal Configuration
- 16.2. Clones Setup
- 16.3. Active branches
- 16.4. Merging order
- 16.5. Merging between different branches (within the same major version)
- 16.6. Porting changesets between the two major Python versions (2.x and 3.x)
- 16.7. Long-term development of features
- 17. Development Cycle
- 18. Continuous Integration
- 19. Adding to the Stdlib
- 20. Changing the Python Language
- 21. Experts Index
- 22. gdb Support
- 23. Changing CPython’s Grammar
- 24. Design of CPython’s Compiler
- 24.1. Abstract
- 24.2. Parse Trees
- 24.3. Abstract Syntax Trees (AST)
- 24.4. Memory Management
- 24.5. Parse Tree to AST
- 24.6. Control Flow Graphs
- 24.7. AST to CFG to Bytecode
- 24.8. Introducing New Bytecode
- 24.9. Code Objects
- 24.10. Important Files
- 24.11. Known Compiler-related Experiments
- 24.12. References
- 25. Coverity Scan
- 26. Dynamic Analysis with Clang
- 27. Running a buildslave
- 28. Mercurial for git developers
- 28.1. Overview
- 28.2. Git workflow
- 28.3. Main differences between git and hg
- 28.4. Mercurial workflow
- 28.5. Rebasing your work
- 28.6. Workflow comparison
- 29. Python Developer FAQ
- 30. Core Developer Motivations and Affiliations