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!
Quick Reference
Here are the basic steps needed to get set up and contribute a patch. This is meant as a checklist, once you know the basics. For complete instructions please see the setup guide.
-
Install and set up Git and other dependencies (see the Get Setup page for detailed information).
-
Fork the CPython repository to your GitHub account and get the source code using:
git clone https://github.com/<your_username>/cpython
-
Build Python, on UNIX and Mac OS use:
./configure --with-pydebug && make -j
and on Windows use:
PCbuild\build.bat -e -d
See also more detailed instructions, how to build dependencies, and the plaform-specific pages for UNIX, Mac OS, and Windows.
-
./python -m test -j3
On most Mac OS X systems, replace
./python
with./python.exe
. On Windows, usepython.bat
. With Python 2.7, replacetest
withtest.regrtest
. -
Create a new branch where your work for the issue will go, e.g.:
git checkout -b fix-issue-12345 master
If an issue does not already exist, please create it. Trivial issues (e.g. typo fixes) do not require any issue to be created.
-
Once you fixed the issue, run the tests, run
make patchcheck
, and if everything is ok, commit. -
Push the branch on your fork on GitHub and create a pull request. Include the issue number using
bpo-NNNN
in the pull request description. For example:bpo-12345: Fix some bug in spam module
Note
First time contributors will need to sign the Contributor Licensing Agreement (CLA) as described in the Licensing section of this guide.
Quick Links
Here are some links that you probably will reference frequently while contributing to Python:
- Issue tracker
- Buildbot status
- Where to Get Help
- PEPs (Python Enhancement Proposals)
- Mercurial for git developers
- Git Bootcamp and Cheat Sheet
Status of Python branches
Branch | Schedule | Status | First release | End-of-life | Comment |
---|---|---|---|---|---|
master | PEP 537 | features | 2018-06-15 | 2023-06-15 | The default branch is currently the future version Python 3.7. |
3.6 | PEP 494 | bugfix | 2016-12-23 | 2021-12-23 | Most recent binary release: Python 3.6.2 |
2.7 | PEP 373 | bugfix | 2010-07-03 | 2020-01-01 | The support has been extended to 2020 (1). Most recent binary release: Python 2.7.13 |
3.5 | PEP 478 | security | 2015-09-13 | 2020-09-13 | Most recent binary release: Python 3.5.4 |
3.4 | PEP 429 | security | 2014-03-16 | 2019-03-16 | Most recent security release: Python 3.4.7 |
3.3 | PEP 398 | security | 2012-09-29 | 2017-09-29 | Most recent security release: Python 3.3.6 |
3.2 | PEP 392 | end-of-life | 2011-02-20 | 2016-02-20 | Final release: Python 3.2.6 |
3.1 | PEP 375 | end-of-life | 2009-06-27 | 2012-04-11 | Final release: Python 3.1.5 |
3.0 | PEP 361 | end-of-life | 2008-12-03 | 2009-01-13 | Final release: Python 3.0.1 |
2.6 | PEP 361 | end-of-life | 2008-10-01 | 2013-10-29 | Final release: Python 2.6.9 |
(1) The exact date of Python 2.7 end-of-life has not been decided yet. It will be decided by Python 2.7 release manager, Benjamin Peterson, who will update the PEP 373. Read also the [Python-Dev] Exact date of Python 2 EOL? thread on python-dev (March 2017).
Status:
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.
Contributing
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.
A number of individuals from the Python community have contributed to a series of excellent guides at Open Source Guides.
Core developers and contributors alike will find the following guides useful:
Guide for contributing to Python:
- Getting Started
- Where to Get Help
- Lifecycle of a Pull Request
- Running & Writing Tests
-
- Beginner tasks to become familiar with the development process
-
- Advanced tasks for once you are comfortable
-
- Silence Warnings From the Test Suite
- Fixing issues found by the buildbots
- Fixing “easy” Issues (and Beyond)
- Following Python’s Development
- Mercurial for git developers
- Git Bootcamp and Cheat Sheet
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:
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
Key Resources
-
- Issue tracker
-
- Meta tracker (issue tracker for the issue tracker)
- Experts Index
- Firefox search engine plug-in
- Buildbot status
- PEPs (Python Enhancement Proposals)
- Where to Get Help
- Developer Log
Additional Resources
- Anyone can clone the sources for this guide. See Helping with the Developer’s Guide.
-
- Tool support
-
- gdb Support
- Dynamic Analysis with Clang
- Various tools with configuration files as found in the Misc directory
- Information about editors and their configurations can be found in the wiki
- python.org maintenance
- Search this guide
Code of Conduct
Please note that all interactions on Python Software Foundation-supported infrastructure is covered by the PSF Code of Conduct, which includes all infrastructure used in the development of Python itself (e.g. mailing lists, issue trackers, GitHub, etc.). In general this means everyone is expected to be open, considerate, and respectful of others no matter what their position is within the project.
Full Table of Contents
- 1. Getting Started
- 2. Where to Get Help
- 3. Lifecycle of a Pull Request
- 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
- 11. Triaging an Issue
- 12. Following Python’s Development
- 13. Porting Python to a new platform
- 14. How to Become a Core Developer
- 15. Developer Log
- 16. Committing and Pushing Changes
- 17. Working with Git
- 18. Development Cycle
- 19. Continuous Integration
- 20. Adding to the Stdlib
- 21. Changing the Python Language
- 22. Experts Index
- 23. gdb Support
- 24. Exploring CPython’s Internals
- 25. Changing CPython’s Grammar
- 26. Design of CPython’s Compiler
- 26.1. Abstract
- 26.2. Parse Trees
- 26.3. Abstract Syntax Trees (AST)
- 26.4. Memory Management
- 26.5. Parse Tree to AST
- 26.6. Control Flow Graphs
- 26.7. AST to CFG to Bytecode
- 26.8. Introducing New Bytecode
- 26.9. Code Objects
- 26.10. Important Files
- 26.11. Known Compiler-related Experiments
- 26.12. References
- 27. Coverity Scan
- 28. Dynamic Analysis with Clang
- 29. Running a buildslave
- 30. Mercurial for git developers
- 31. Core Developer Motivations and Affiliations
- 32. Git Bootcamp and Cheat Sheet
- 32.1. Forking CPython GitHub Repository
- 32.2. Cloning The Forked CPython Repository
- 32.3. Listing the Remote Repositories
- 32.4. Creating and Switching Branches
- 32.5. Deleting Local Branches
- 32.6. Staging and Committing Files
- 32.7. Reverting Changes
- 32.8. Stashing Changes
- 32.9. Pushing Changes
- 32.10. Creating a Pull Request
- 32.11. Syncing With Upstream
- 32.12. Backporting Merged Changes
- 32.13. Applying a Patch from Mercurial to Git
- 32.14. Downloading Other’s Patches
- 32.15. Accepting and Merging A Pull Request
- 32.16. Editing a Pull Request Prior to Merging