├── .editorconfig ├── .github ├── CODEOWNERS ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── ISSUE_TEMPLATE │ ├── bug_report.yml │ ├── config.yml │ └── feature_request.yml ├── PULL_REQUEST_TEMPLATE.md ├── dependabot.yml └── workflows │ ├── ci.yml │ ├── documentation-links.yml │ └── lint.yml ├── .gitignore ├── .pre-commit-config.yaml ├── .readthedocs.yml ├── .ruff.toml ├── LICENSE ├── Makefile ├── README.rst ├── _static ├── activate_tab.js ├── devguide_overrides.css ├── favicon.png ├── og-image-200x200.png ├── python-cyclic-gc-1-new-page.png ├── python-cyclic-gc-2-new-page.png ├── python-cyclic-gc-3-new-page.png ├── python-cyclic-gc-4-new-page.png ├── python-cyclic-gc-5-new-page.png └── python-logo.svg ├── _tools ├── generate_release_cycle.py └── release_cycle_template.svg.jinja ├── conf.py ├── contrib ├── code │ ├── developer-workflow.rst │ ├── development-tools.rst │ ├── git.rst │ ├── index.rst │ ├── pull-request-lifecycle.rst │ ├── setup.rst │ └── testing.rst ├── contrib-plan.rst ├── core-team │ ├── committing.rst │ ├── developer-log.rst │ ├── experts.rst │ ├── index.rst │ ├── join-team.rst │ ├── motivations.rst │ └── responsibilities.rst ├── doc │ ├── devguide.rst │ ├── help-documenting.rst │ ├── index.rst │ ├── markup.rst │ ├── pull-request-lifecycle.rst │ ├── start-documenting.rst │ ├── style-guide.rst │ └── translating.rst ├── index.rst ├── intro │ └── index.rst ├── project │ ├── channels.rst │ ├── conduct.rst │ ├── directory-structure.rst │ ├── generative-ai.rst │ ├── github.rst │ ├── governance.rst │ ├── index.rst │ ├── outreach.rst │ └── roles.rst ├── security.rst ├── triage │ ├── index.rst │ ├── issue-tracker.rst │ ├── labels.rst │ ├── reviewing.rst │ ├── triage-team.rst │ └── triaging.rst ├── user-success.rst └── workflows │ ├── codespaces.rst │ ├── compile.rst │ ├── get-source.rst │ ├── index.rst │ ├── install-dependencies.rst │ ├── install-git.rst │ ├── regenerate.rst │ └── troubleshooting.rst ├── core-developers ├── become-core-developer.rst ├── committing.rst ├── developer-log.rst ├── developers.csv ├── experts.rst ├── index.rst ├── memorialization.rst ├── motivations.rst └── responsibilities.rst ├── developer-workflow ├── c-api.rst ├── communication-channels.rst ├── development-cycle.rst ├── extension-modules.rst ├── grammar.rst ├── index.rst ├── lang-changes.rst ├── porting.rst ├── psrt.rst ├── sbom.rst └── stdlib.rst ├── development-tools ├── clang.rst ├── clinic.rst ├── gdb.rst ├── index.rst └── warnings.rst ├── documentation ├── devguide.rst ├── help-documenting.rst ├── index.rst ├── markup.rst ├── start-documenting.rst ├── style-guide.rst └── translating.rst ├── getting-started ├── fixing-issues.rst ├── generative-ai.rst ├── getting-help.rst ├── git-boot-camp.rst ├── index.rst ├── pull-request-lifecycle.rst └── setup-building.rst ├── include └── release-cycle.json ├── index.rst ├── internals ├── compiler.rst ├── exploring.rst ├── garbage-collector.rst ├── index.rst ├── interpreter.rst └── parser.rst ├── links.rst ├── make.bat ├── make.ps1 ├── requirements.txt ├── testing ├── buildbots.rst ├── coverage.rst ├── index.rst ├── new-buildbot-worker.rst ├── run-write-tests.rst └── silence-warnings.rst ├── triage ├── github-bpo-faq.rst ├── index.rst ├── issue-tracker.rst ├── labels.rst ├── triage-team.rst └── triaging.rst └── versions.rst /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*.{py,c,cpp,h,rst,md,yml}] 4 | trim_trailing_whitespace = true 5 | insert_final_newline = true 6 | indent_style = space 7 | 8 | [*.{py,c,cpp,h}] 9 | indent_size = 4 10 | 11 | [*.rst] 12 | indent_size = 3 13 | 14 | [*.{css,yml}] 15 | indent_size = 2 16 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # See https://help.github.com/articles/about-codeowners/ 2 | # for more info about CODEOWNERS file 3 | 4 | # It uses the same pattern rule for gitignore file 5 | # https://git-scm.com/docs/gitignore#_pattern_format 6 | 7 | 8 | garbage_collector.rst @pablogsal 9 | -------------------------------------------------------------------------------- /.github/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | Code of Conduct 2 | =============== 3 | 4 | Please note that all interactions on 5 | [Python Software Foundation](https://www.python.org/psf-landing/)-supported 6 | infrastructure is [covered](https://www.python.org/psf/records/board/minutes/2014-01-06/#management-of-the-psfs-web-properties) 7 | by the [PSF Code of Conduct](https://policies.python.org/python.org/code-of-conduct/), 8 | which includes all infrastructure used in the development of Python itself 9 | (for example, mailing lists, issue trackers, GitHub, etc.). 10 | 11 | In general this means everyone is expected to be open, considerate, and 12 | respectful of others no matter what their position is within the project. 13 | -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to the Devguide 2 | 3 | ## Thank You 4 | 5 | First off, thanks for contributing to the devguide of the Python programming 6 | language! Even if your contribution is not ultimately accepted, the fact you 7 | put time and effort into helping out is greatly appreciated. 8 | 9 | 10 | ## Contribution Guidelines 11 | 12 | Please read this [devguide](https://devguide.python.org/) for 13 | guidance on how to contribute to this project. The documentation covers 14 | everything from how to build the code to submitting a pull request. There are 15 | also suggestions on how you can most effectively help the project. 16 | 17 | Please be aware that our workflow does deviate slightly from the typical GitHub 18 | project. Details on how to properly submit a pull request are covered in 19 | [Lifecycle of a Pull Request](https://devguide.python.org/pullrequest/). 20 | We utilize various bots and status checks to help with this, so do follow the 21 | comments they leave and their "Details" links, respectively. The key points of 22 | our workflow that are not covered by a bot or status check are: 23 | 24 | - All discussions that are not directly related to the code in the pull request 25 | should happen on the [issue tracker](https://devguide.python.org/tracker/) 26 | - Upon your first non-trivial pull request (which includes documentation changes), 27 | feel free to add yourself to [`Misc/ACKS`](https://github.com/python/cpython/blob/main/Misc/ACKS) 28 | 29 | 30 | ## Setting Expectations 31 | 32 | Due to the fact that this project is entirely volunteer-run (that is, no one is paid 33 | to work on Python full-time), we unfortunately can make no guarantees as to if 34 | or when a core developer will get around to reviewing your pull request. 35 | If no core developer has done a review or responded to changes made because of a 36 | "changes requested" review, please consider seeking assistance through the 37 | [Core Development Discourse category](https://discuss.python.org/c/core-dev/23). 38 | 39 | 40 | ## Code of Conduct 41 | 42 | All interactions for this project are covered by the 43 | [PSF Code of Conduct](https://policies.python.org/python.org/code-of-conduct/). Everyone is 44 | expected to be open, considerate, and respectful of others no matter their 45 | position within the project. 46 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.yml: -------------------------------------------------------------------------------- 1 | name: "Bug report" 2 | description: Create a report to help us improve the Python devguide 3 | title: "Bug: " 4 | labels: ["bug"] 5 | assignees: [] 6 | 7 | body: 8 | - type: markdown 9 | attributes: 10 | value: | 11 | > [!NOTE] 12 | > This repo is for the [Python developer's guide](https://devguide.python.org/). 13 | > If you are reporting a bug for the Python language or 14 | > CPython interpreter, then use the 15 | > [CPython issue tracker](https://github.com/python/cpython/issues) instead. 16 | 17 | - type: textarea 18 | id: bug_description 19 | attributes: 20 | label: "Describe the bug" 21 | description: A clear and concise description of what the bug is and, optionally, what you expected to happen. 22 | validations: 23 | required: true 24 | 25 | - type: textarea 26 | id: screenshots 27 | attributes: 28 | label: "Screenshots" 29 | description: If applicable, add screenshots to help explain your problem. 30 | validations: 31 | required: false 32 | 33 | - type: textarea 34 | id: additional_context 35 | attributes: 36 | label: "Additional context" 37 | description: Add any other context about the problem here. 38 | validations: 39 | required: false 40 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | contact_links: 3 | - name: CPython Documentation 4 | url: https://docs.python.org/ 5 | about: Official CPython documentation - please check here before opening an issue. 6 | - name: Python Website 7 | url: https://python.org/ 8 | about: For all things Python 9 | - name: PyPI Issues / Support 10 | url: https://github.com/pypi/support 11 | about: For issues with PyPI itself, PyPI accounts, or with packages hosted on PyPI. 12 | - name: CPython Issues 13 | url: https://github.com/python/cpython/issues 14 | about: For issues with the CPython interpreter itself. 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.yml: -------------------------------------------------------------------------------- 1 | name: "Feature request" 2 | description: Suggest an idea for the Python devguide 3 | title: "Feature: <title>" 4 | labels: ["enhancement"] 5 | assignees: [] 6 | 7 | body: 8 | - type: markdown 9 | attributes: 10 | value: | 11 | > [!NOTE] 12 | > This repo is for the [Python developer's guide](https://devguide.python.org/). 13 | > If you are requesting an enhancement for the Python language or 14 | > CPython interpreter, then use the 15 | > [CPython issue tracker](https://github.com/python/cpython/issues) instead. 16 | 17 | - type: textarea 18 | id: feature_description 19 | attributes: 20 | label: "Describe the enhancement or feature you would like" 21 | description: A clear and concise description of what you want to happen. 22 | validations: 23 | required: true 24 | 25 | - type: textarea 26 | id: alternatives 27 | attributes: 28 | label: "Describe alternatives you have considered" 29 | description: A clear and concise description of any alternative solutions or features you have considered. 30 | validations: 31 | required: false 32 | 33 | - type: textarea 34 | id: additional_context 35 | attributes: 36 | label: "Additional context" 37 | description: Add any other context or screenshots about the feature request here. 38 | validations: 39 | required: false 40 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | <!-- 2 | Thanks for your contribution! 3 | Please read this comment in its entirety. It's quite important. 4 | 5 | # Pull Request title 6 | 7 | It should describe the change to be made. 8 | 9 | Most PRs will require an issue number. Trivial changes, like fixing a typo, 10 | do not need an issue. 11 | --> 12 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: pip 4 | directory: "/" 5 | schedule: 6 | interval: monthly 7 | open-pull-requests-limit: 10 8 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: Tests 2 | 3 | on: [pull_request, push, workflow_dispatch] 4 | 5 | env: 6 | FORCE_COLOR: 1 7 | 8 | jobs: 9 | test: 10 | name: Check build, markup, and links 11 | runs-on: ubuntu-latest 12 | timeout-minutes: 10 13 | 14 | steps: 15 | - uses: actions/checkout@v4 16 | - uses: actions/setup-python@v5 17 | with: 18 | python-version: "3" 19 | - name: Install uv 20 | uses: hynek/setup-cached-uv@v2 21 | - name: Build docs 22 | run: make html 23 | - name: Link check 24 | run: make linkcheck 25 | continue-on-error: true 26 | -------------------------------------------------------------------------------- /.github/workflows/documentation-links.yml: -------------------------------------------------------------------------------- 1 | name: Read the Docs PR preview 2 | on: 3 | pull_request_target: 4 | types: 5 | - opened 6 | 7 | permissions: 8 | pull-requests: write 9 | 10 | jobs: 11 | documentation-links: 12 | runs-on: ubuntu-latest 13 | timeout-minutes: 10 14 | steps: 15 | - uses: readthedocs/actions/preview@v1 16 | with: 17 | project-slug: "cpython-devguide" 18 | single-version: "true" 19 | -------------------------------------------------------------------------------- /.github/workflows/lint.yml: -------------------------------------------------------------------------------- 1 | name: Lint 2 | 3 | on: [push, pull_request, workflow_dispatch] 4 | 5 | jobs: 6 | lint: 7 | runs-on: ubuntu-latest 8 | timeout-minutes: 10 9 | 10 | steps: 11 | - uses: actions/checkout@v4 12 | - uses: actions/setup-python@v4 13 | with: 14 | python-version: "3.x" 15 | - uses: pre-commit/action@v3.0.0 16 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | 9 | # Distribution / packaging 10 | .Python 11 | env/ 12 | ENV/ 13 | venv/ 14 | build/ 15 | develop-eggs/ 16 | dist/ 17 | downloads/ 18 | eggs/ 19 | .eggs/ 20 | lib/ 21 | lib64/ 22 | parts/ 23 | sdist/ 24 | var/ 25 | *.egg-info/ 26 | .installed.cfg 27 | *.egg 28 | 29 | # PyInstaller 30 | # Usually these files are written by a python script from a template 31 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 32 | *.manifest 33 | *.spec 34 | 35 | # Installer logs 36 | pip-log.txt 37 | pip-delete-this-directory.txt 38 | 39 | # Unit test / coverage reports 40 | htmlcov/ 41 | .tox/ 42 | .coverage 43 | .coverage.* 44 | .cache 45 | nosetests.xml 46 | coverage.xml 47 | *,cover 48 | .hypothesis/ 49 | 50 | # Translations 51 | *.mo 52 | *.pot 53 | 54 | # Django stuff: 55 | *.log 56 | local_settings.py 57 | 58 | # Flask stuff: 59 | instance/ 60 | .webassets-cache 61 | 62 | # Scrapy stuff: 63 | .scrapy 64 | 65 | # Sphinx documentation 66 | docs/_build/ 67 | _build/ 68 | 69 | # PyBuilder 70 | target/ 71 | 72 | # IPython Notebook 73 | .ipynb_checkpoints 74 | 75 | # pyenv 76 | .python-version 77 | 78 | # celery beat schedule file 79 | celerybeat-schedule 80 | 81 | # dotenv 82 | .env 83 | 84 | # Spyder project settings 85 | .spyderproject 86 | 87 | # Rope project settings 88 | .ropeproject 89 | 90 | # Generated CSV and SVG files 91 | include/branches.csv 92 | include/end-of-life.csv 93 | include/release-cycle.svg 94 | include/release-cycle-all.svg 95 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | repos: 2 | - repo: https://github.com/astral-sh/ruff-pre-commit 3 | rev: v0.5.7 4 | hooks: 5 | - id: ruff 6 | name: Run Ruff (lint) 7 | args: [--exit-non-zero-on-fix] 8 | - id: ruff-format 9 | name: Run Ruff (format) 10 | args: [--check] 11 | 12 | - repo: https://github.com/pre-commit/pre-commit-hooks 13 | rev: v4.5.0 14 | hooks: 15 | - id: check-case-conflict 16 | - id: check-merge-conflict 17 | - id: check-json 18 | - id: check-yaml 19 | - id: debug-statements 20 | - id: end-of-file-fixer 21 | - id: trailing-whitespace 22 | 23 | - repo: https://github.com/sphinx-contrib/sphinx-lint 24 | rev: v0.9.1 25 | hooks: 26 | - id: sphinx-lint 27 | args: [--enable=default-role] 28 | 29 | - repo: meta 30 | hooks: 31 | - id: check-hooks-apply 32 | - id: check-useless-excludes 33 | 34 | ci: 35 | autoupdate_schedule: quarterly 36 | -------------------------------------------------------------------------------- /.readthedocs.yml: -------------------------------------------------------------------------------- 1 | # Read the Docs configuration file 2 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 3 | # Project page: https://readthedocs.org/projects/cpython-devguide/ 4 | 5 | version: 2 6 | 7 | sphinx: 8 | builder: dirhtml 9 | configuration: conf.py 10 | 11 | build: 12 | os: ubuntu-22.04 13 | tools: 14 | python: "3" 15 | 16 | commands: 17 | - asdf plugin add uv 18 | - asdf install uv latest 19 | - asdf global uv latest 20 | - make dirhtml BUILDDIR=_readthedocs 21 | - mv _readthedocs/dirhtml _readthedocs/html 22 | -------------------------------------------------------------------------------- /.ruff.toml: -------------------------------------------------------------------------------- 1 | target-version = "py310" 2 | fix = true 3 | output-format = "full" 4 | line-length = 88 5 | 6 | [lint] 7 | preview = true 8 | select = [ 9 | "C4", # flake8-comprehensions 10 | "B", # flake8-bugbear 11 | "E", # pycodestyle 12 | "F", # pyflakes 13 | "FA", # flake8-future-annotations 14 | "FLY", # flynt 15 | "FURB", # refurb 16 | "G", # flake8-logging-format 17 | "I", # isort 18 | "ISC", # flake8-implicit-str-concat 19 | "LOG", # flake8-logging 20 | "PERF", # perflint 21 | "PGH", # pygrep-hooks 22 | "PT", # flake8-pytest-style 23 | "TCH", # flake8-type-checking 24 | "UP", # pyupgrade 25 | "W", # pycodestyle 26 | "YTT", # flake8-2020 27 | ] 28 | ignore = [ 29 | "E501", # Ignore line length errors (we use auto-formatting) 30 | ] 31 | 32 | [format] 33 | preview = true 34 | quote-style = "preserve" 35 | docstring-code-format = true 36 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | CC0 1.0 Universal 2 | 3 | Statement of Purpose 4 | 5 | The laws of most jurisdictions throughout the world automatically confer 6 | exclusive Copyright and Related Rights (defined below) upon the creator and 7 | subsequent owner(s) (each and all, an "owner") of an original work of 8 | authorship and/or a database (each, a "Work"). 9 | 10 | Certain owners wish to permanently relinquish those rights to a Work for the 11 | purpose of contributing to a commons of creative, cultural and scientific 12 | works ("Commons") that the public can reliably and without fear of later 13 | claims of infringement build upon, modify, incorporate in other works, reuse 14 | and redistribute as freely as possible in any form whatsoever and for any 15 | purposes, including without limitation commercial purposes. These owners may 16 | contribute to the Commons to promote the ideal of a free culture and the 17 | further production of creative, cultural and scientific works, or to gain 18 | reputation or greater distribution for their Work in part through the use and 19 | efforts of others. 20 | 21 | For these and/or other purposes and motivations, and without any expectation 22 | of additional consideration or compensation, the person associating CC0 with a 23 | Work (the "Affirmer"), to the extent that he or she is an owner of Copyright 24 | and Related Rights in the Work, voluntarily elects to apply CC0 to the Work 25 | and publicly distribute the Work under its terms, with knowledge of his or her 26 | Copyright and Related Rights in the Work and the meaning and intended legal 27 | effect of CC0 on those rights. 28 | 29 | 1. Copyright and Related Rights. A Work made available under CC0 may be 30 | protected by copyright and related or neighboring rights ("Copyright and 31 | Related Rights"). Copyright and Related Rights include, but are not limited 32 | to, the following: 33 | 34 | i. the right to reproduce, adapt, distribute, perform, display, communicate, 35 | and translate a Work; 36 | 37 | ii. moral rights retained by the original author(s) and/or performer(s); 38 | 39 | iii. publicity and privacy rights pertaining to a person's image or likeness 40 | depicted in a Work; 41 | 42 | iv. rights protecting against unfair competition in regards to a Work, 43 | subject to the limitations in paragraph 4(a), below; 44 | 45 | v. rights protecting the extraction, dissemination, use and reuse of data in 46 | a Work; 47 | 48 | vi. database rights (such as those arising under Directive 96/9/EC of the 49 | European Parliament and of the Council of 11 March 1996 on the legal 50 | protection of databases, and under any national implementation thereof, 51 | including any amended or successor version of such directive); and 52 | 53 | vii. other similar, equivalent or corresponding rights throughout the world 54 | based on applicable law or treaty, and any national implementations thereof. 55 | 56 | 2. Waiver. To the greatest extent permitted by, but not in contravention of, 57 | applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and 58 | unconditionally waives, abandons, and surrenders all of Affirmer's Copyright 59 | and Related Rights and associated claims and causes of action, whether now 60 | known or unknown (including existing as well as future claims and causes of 61 | action), in the Work (i) in all territories worldwide, (ii) for the maximum 62 | duration provided by applicable law or treaty (including future time 63 | extensions), (iii) in any current or future medium and for any number of 64 | copies, and (iv) for any purpose whatsoever, including without limitation 65 | commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes 66 | the Waiver for the benefit of each member of the public at large and to the 67 | detriment of Affirmer's heirs and successors, fully intending that such Waiver 68 | shall not be subject to revocation, rescission, cancellation, termination, or 69 | any other legal or equitable action to disrupt the quiet enjoyment of the Work 70 | by the public as contemplated by Affirmer's express Statement of Purpose. 71 | 72 | 3. Public License Fallback. Should any part of the Waiver for any reason be 73 | judged legally invalid or ineffective under applicable law, then the Waiver 74 | shall be preserved to the maximum extent permitted taking into account 75 | Affirmer's express Statement of Purpose. In addition, to the extent the Waiver 76 | is so judged Affirmer hereby grants to each affected person a royalty-free, 77 | non transferable, non sublicensable, non exclusive, irrevocable and 78 | unconditional license to exercise Affirmer's Copyright and Related Rights in 79 | the Work (i) in all territories worldwide, (ii) for the maximum duration 80 | provided by applicable law or treaty (including future time extensions), (iii) 81 | in any current or future medium and for any number of copies, and (iv) for any 82 | purpose whatsoever, including without limitation commercial, advertising or 83 | promotional purposes (the "License"). The License shall be deemed effective as 84 | of the date CC0 was applied by Affirmer to the Work. Should any part of the 85 | License for any reason be judged legally invalid or ineffective under 86 | applicable law, such partial invalidity or ineffectiveness shall not 87 | invalidate the remainder of the License, and in such case Affirmer hereby 88 | affirms that he or she will not (i) exercise any of his or her remaining 89 | Copyright and Related Rights in the Work or (ii) assert any associated claims 90 | and causes of action with respect to the Work, in either case contrary to 91 | Affirmer's express Statement of Purpose. 92 | 93 | 4. Limitations and Disclaimers. 94 | 95 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 96 | surrendered, licensed or otherwise affected by this document. 97 | 98 | b. Affirmer offers the Work as-is and makes no representations or warranties 99 | of any kind concerning the Work, express, implied, statutory or otherwise, 100 | including without limitation warranties of title, merchantability, fitness 101 | for a particular purpose, non infringement, or the absence of latent or 102 | other defects, accuracy, or the present or absence of errors, whether or not 103 | discoverable, all to the greatest extent permissible under applicable law. 104 | 105 | c. Affirmer disclaims responsibility for clearing rights of other persons 106 | that may apply to the Work or any use thereof, including without limitation 107 | any person's Copyright and Related Rights in the Work. Further, Affirmer 108 | disclaims responsibility for obtaining any necessary consents, permissions 109 | or other rights required for any use of the Work. 110 | 111 | d. Affirmer understands and acknowledges that Creative Commons is not a 112 | party to this document and has no duty or obligation with respect to this 113 | CC0 or use of the Work. 114 | 115 | For more information, please see 116 | <https://creativecommons.org/publicdomain/zero/1.0/> 117 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | PYTHON = python3 6 | VENVDIR = ./venv 7 | UV = uv 8 | SPHINXBUILD = $(VENVDIR)/bin/sphinx-build 9 | # Temporary: while we are using ..include:: to show the reorganization, 10 | # there are duplicate labels. These cause warnings, which prevent the 11 | # build from finishing. Turn off --fail-on-warning so we can see the 12 | # finished results. 13 | #SPHINXOPTS = --fail-on-warning 14 | SPHINXOPTS = 15 | BUILDDIR = _build 16 | BUILDER = html 17 | JOBS = auto 18 | SPHINXLINT = $(VENVDIR)/bin/sphinx-lint 19 | REQUIREMENTS = requirements.txt 20 | 21 | # Internal variables. 22 | _ALL_SPHINX_OPTS = --jobs $(JOBS) $(SPHINXOPTS) 23 | _RELEASE_CYCLE = include/branches.csv \ 24 | include/end-of-life.csv \ 25 | include/release-cycle-all.svg \ 26 | include/release-cycle.svg 27 | 28 | .PHONY: help 29 | help: 30 | @echo "Please use \`make <target>' where <target> is one of" 31 | @echo " venv to create a venv with necessary tools" 32 | @echo " html to make standalone HTML files" 33 | @echo " linkcheck to check all external links for integrity" 34 | @echo " htmlview to open the index page built by the html target in your browser" 35 | @echo " htmllive to rebuild and reload HTML files in your browser" 36 | @echo " clean to remove the venv and build files" 37 | @echo " check to run a check for frequent markup errors" 38 | @echo " lint to lint all the files" 39 | 40 | .PHONY: clean 41 | clean: clean-venv 42 | -rm -rf $(BUILDDIR)/* 43 | -rm -rf $(_RELEASE_CYCLE) 44 | 45 | .PHONY: clean-venv 46 | clean-venv: 47 | rm -rf $(VENVDIR) 48 | 49 | .PHONY: venv 50 | venv: 51 | @if [ -d $(VENVDIR) ] ; then \ 52 | echo "venv already exists."; \ 53 | echo "To recreate it, remove it first with \`make clean-venv'."; \ 54 | else \ 55 | $(MAKE) ensure-venv; \ 56 | fi 57 | 58 | .PHONY: ensure-venv 59 | ensure-venv: 60 | @if [ ! -d $(VENVDIR) ] ; then \ 61 | echo "Creating venv in $(VENVDIR)"; \ 62 | if $(UV) --version >/dev/null 2>&1; then \ 63 | $(UV) venv --python=$(PYTHON) $(VENVDIR); \ 64 | VIRTUAL_ENV=$(VENVDIR) $(UV) pip install -r $(REQUIREMENTS); \ 65 | else \ 66 | $(PYTHON) -m venv $(VENVDIR); \ 67 | $(VENVDIR)/bin/python3 -m pip install --upgrade pip; \ 68 | $(VENVDIR)/bin/python3 -m pip install -r $(REQUIREMENTS); \ 69 | fi; \ 70 | echo "The venv has been created in the $(VENVDIR) directory"; \ 71 | fi 72 | 73 | .PHONY: htmlview 74 | htmlview: html 75 | $(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('_build/html/index.html'))" 76 | 77 | .PHONY: htmllive 78 | htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild 79 | # Arbitrarily selected ephemeral port between 49152–65535 80 | # to avoid conflicts with other processes: 81 | htmllive: SPHINXOPTS = --open-browser --delay 0 --port 55301 82 | htmllive: html 83 | 84 | .PHONY: check 85 | check: ensure-venv 86 | # Ignore the tools and venv dirs and check that the default role is not used. 87 | $(SPHINXLINT) -i tools -i $(VENVDIR) --enable default-role 88 | 89 | .PHONY: _ensure-package 90 | _ensure-package: venv 91 | if $(UV) --version >/dev/null 2>&1; then \ 92 | VIRTUAL_ENV=$(VENVDIR) $(UV) pip install $(PACKAGE); \ 93 | else \ 94 | $(VENVDIR)/bin/python3 -m pip install $(PACKAGE); \ 95 | fi 96 | 97 | .PHONY: _ensure-pre-commit 98 | _ensure-pre-commit: 99 | make _ensure-package PACKAGE=pre-commit 100 | 101 | .PHONY: lint 102 | lint: _ensure-pre-commit 103 | $(VENVDIR)/bin/python3 -m pre_commit run --all-files 104 | 105 | # Defined so that "include/release-cycle.json" 106 | # doesn't fall through to the catch-all target. 107 | include/release-cycle.json: 108 | @exit 109 | 110 | $(_RELEASE_CYCLE): include/release-cycle.json 111 | $(VENVDIR)/bin/python3 _tools/generate_release_cycle.py 112 | @echo Release cycle data generated. 113 | 114 | # Catch-all target: route all unknown targets to Sphinx using the new 115 | # "make mode" option. 116 | .PHONY: Makefile 117 | %: Makefile ensure-venv $(_RELEASE_CYCLE) 118 | $(SPHINXBUILD) -M $@ "." "$(BUILDDIR)" $(_ALL_SPHINX_OPTS) 119 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | The CPython Developer's Guide 2 | ============================= 3 | 4 | |ReadTheDocs| |Discourse| |Codestyle| 5 | 6 | .. |ReadTheDocs| image:: https://readthedocs.org/projects/cpython-devguide/badge/ 7 | :target: https://devguide.python.org 8 | :alt: Documentation Status 9 | 10 | .. |Discourse| image:: https://img.shields.io/badge/discourse-join_chat-brightgreen.svg 11 | :alt: Python Discourse chat 12 | :target: https://discuss.python.org/ 13 | 14 | .. |Codestyle| image:: https://img.shields.io/badge/code%20style-black-000000.svg 15 | :target: https://github.com/psf/black 16 | :alt: Code style is black 17 | 18 | 19 | This guide covers how to contribute to CPython. It is known by the 20 | nickname of "the devguide" by the Python core developers. 21 | 22 | The official home of this guide is https://devguide.python.org. 23 | 24 | Render HTML 25 | ----------- 26 | 27 | To render the devguide to HTML under ``_build/html``, run:: 28 | 29 | make html 30 | 31 | To render the devguide to HTML, and open the result in a browser, run:: 32 | 33 | make htmlview 34 | 35 | To maintain a live view of edits as they are saved, run:: 36 | 37 | make htmllive 38 | -------------------------------------------------------------------------------- /_static/activate_tab.js: -------------------------------------------------------------------------------- 1 | // Based on https://stackoverflow.com/a/38241481/724176 2 | function getOS() { 3 | const userAgent = window.navigator.userAgent, 4 | platform = 5 | window.navigator?.userAgentData?.platform || window.navigator.platform, 6 | macosPlatforms = ["macOS", "Macintosh", "MacIntel", "MacPPC", "Mac68K"], 7 | windowsPlatforms = ["Win32", "Win64", "Windows", "WinCE"], 8 | iosPlatforms = ["iPhone", "iPad", "iPod"]; 9 | 10 | if (macosPlatforms.includes(platform)) { 11 | return "macOS"; 12 | } else if (iosPlatforms.includes(platform)) { 13 | return "iOS"; 14 | } else if (windowsPlatforms.includes(platform)) { 15 | return "Windows"; 16 | } else if (/Android/.test(userAgent)) { 17 | return "Android"; 18 | } else if (/Linux/.test(platform)) { 19 | return "Unix"; 20 | } 21 | 22 | return "unknown"; 23 | } 24 | 25 | function activateTab(tabName) { 26 | // Find all label elements containing the specified tab name 27 | const labels = document.querySelectorAll(".tab-label"); 28 | 29 | labels.forEach((label) => { 30 | if (label.textContent.includes(tabName)) { 31 | // Find the associated input element using the 'for' attribute 32 | const tabInputId = label.getAttribute("for"); 33 | const tabInput = document.getElementById(tabInputId); 34 | 35 | // Check if the input element exists before attempting to set the "checked" attribute 36 | if (tabInput) { 37 | // Activate the tab by setting its "checked" attribute to true 38 | tabInput.checked = true; 39 | } 40 | } 41 | }); 42 | } 43 | -------------------------------------------------------------------------------- /_static/devguide_overrides.css: -------------------------------------------------------------------------------- 1 | /* Style overrides for the devguide */ 2 | 3 | /* Make the site logo smaller */ 4 | .sidebar-logo { 5 | width: 111px; 6 | height: 110px; 7 | } 8 | 9 | /* Release cycle chart */ 10 | 11 | .release-cycle-chart { 12 | width: 100%; 13 | } 14 | 15 | .release-cycle-chart .release-cycle-year-line { 16 | stroke: var(--color-foreground-primary); 17 | stroke-width: 0.8px; 18 | opacity: 75%; 19 | } 20 | 21 | .release-cycle-chart .release-cycle-year-text { 22 | fill: var(--color-foreground-primary); 23 | } 24 | 25 | .release-cycle-chart .release-cycle-today-line { 26 | stroke: var(--color-brand-primary); 27 | stroke-width: 1.6px; 28 | } 29 | 30 | .release-cycle-chart .release-cycle-row-shade { 31 | fill: var(--color-background-item); 32 | opacity: 50%; 33 | } 34 | 35 | .release-cycle-chart .release-cycle-version-label { 36 | fill: var(--color-foreground-primary); 37 | } 38 | 39 | .release-cycle-chart .release-cycle-blob { 40 | stroke-width: 1.6px; 41 | /* default colours, overridden below for individual statuses */ 42 | fill: var(--color-background-primary); 43 | stroke: var(--color-foreground-primary); 44 | } 45 | 46 | .release-cycle-chart .release-cycle-blob-label { 47 | /* white looks good on both light & dark */ 48 | fill: white; 49 | } 50 | 51 | .release-cycle-chart .release-cycle-blob-label.release-cycle-status-security, 52 | .release-cycle-chart .release-cycle-blob-label.release-cycle-status-bugfix { 53 | /* but use black to improve contrast for lighter backgrounds */ 54 | fill: black; 55 | } 56 | 57 | .release-cycle-chart .release-cycle-blob-label.release-cycle-status-end-of-life, 58 | .release-cycle-chart .release-cycle-blob-label.release-cycle-status-prerelease, 59 | .release-cycle-chart .release-cycle-blob-label.release-cycle-status-feature { 60 | /* and FG when it's not in a blob */ 61 | fill: var(--color-foreground-primary); 62 | } 63 | 64 | .release-cycle-chart .release-cycle-status-end-of-life { 65 | --status-bg-color: #DD2200; 66 | --status-border-color: #FF8888; 67 | } 68 | 69 | .release-cycle-chart .release-cycle-status-security { 70 | --status-bg-color: #FFDD44; 71 | --status-border-color: #FF8800; 72 | } 73 | 74 | .release-cycle-chart .release-cycle-status-bugfix { 75 | --status-bg-color: #00DD22; 76 | --status-border-color: #008844; 77 | } 78 | 79 | .release-cycle-chart .release-cycle-status-prerelease { 80 | --status-bg-color: teal; 81 | --status-border-color: darkgreen; 82 | } 83 | 84 | .release-cycle-chart .release-cycle-status-feature { 85 | --status-bg-color: #2222EE; 86 | --status-border-color: #008888; 87 | } 88 | 89 | .release-cycle-chart .release-cycle-blob { 90 | fill: var(--status-bg-color); 91 | stroke: transparent; 92 | } 93 | 94 | .release-cycle-chart .release-cycle-blob-full { 95 | fill: var(--status-bg-color); 96 | stroke: var(--status-border-color); 97 | } 98 | 99 | .release-cycle-chart .release-cycle-border { 100 | fill: transparent; 101 | stroke: var(--status-border-color); 102 | stroke-width: 1.6px; 103 | } 104 | 105 | .good pre { 106 | border-left: 3px solid rgba(74, 182, 93, 1); 107 | } 108 | .bad pre { 109 | border-left: 3px solid rgb(244, 76, 78); 110 | } 111 | 112 | .extlink-cpy-file, 113 | .extlink-gh-label { 114 | border: 1px solid var(--color-background-border); 115 | border-radius: .2em; 116 | font-family: var(--font-stack--monospace); 117 | font-size: var(--font-size--small--2); 118 | padding: .1em .2em; 119 | } 120 | 121 | /* Table cells should always top-align */ 122 | 123 | table.docutils td { 124 | vertical-align: top; 125 | } 126 | -------------------------------------------------------------------------------- /_static/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/python/devguide/24fa99f9894910fb935030e0986b5f39211a176c/_static/favicon.png -------------------------------------------------------------------------------- /_static/og-image-200x200.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/python/devguide/24fa99f9894910fb935030e0986b5f39211a176c/_static/og-image-200x200.png -------------------------------------------------------------------------------- /_static/python-cyclic-gc-1-new-page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/python/devguide/24fa99f9894910fb935030e0986b5f39211a176c/_static/python-cyclic-gc-1-new-page.png -------------------------------------------------------------------------------- /_static/python-cyclic-gc-2-new-page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/python/devguide/24fa99f9894910fb935030e0986b5f39211a176c/_static/python-cyclic-gc-2-new-page.png -------------------------------------------------------------------------------- /_static/python-cyclic-gc-3-new-page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/python/devguide/24fa99f9894910fb935030e0986b5f39211a176c/_static/python-cyclic-gc-3-new-page.png -------------------------------------------------------------------------------- /_static/python-cyclic-gc-4-new-page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/python/devguide/24fa99f9894910fb935030e0986b5f39211a176c/_static/python-cyclic-gc-4-new-page.png -------------------------------------------------------------------------------- /_static/python-cyclic-gc-5-new-page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/python/devguide/24fa99f9894910fb935030e0986b5f39211a176c/_static/python-cyclic-gc-5-new-page.png -------------------------------------------------------------------------------- /_static/python-logo.svg: -------------------------------------------------------------------------------- 1 | <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 110.4 109.8"> 2 | <defs> 3 | <linearGradient id="Y" x1="89.1" x2="147.8" y1="111.9" y2="168.1" gradientUnits="userSpaceOnUse"> 4 | <stop offset="0" stop-color="#ffe052"/> 5 | <stop offset="1" stop-color="#ffc331"/> 6 | </linearGradient> 7 | <linearGradient id="B" x1="55.5" x2="110.1" y1="77.1" y2="131.9" gradientUnits="userSpaceOnUse"> 8 | <stop offset="0" stop-color="#387eb8"/> 9 | <stop offset="1" stop-color="#366994"/> 10 | </linearGradient> 11 | </defs> 12 | <path fill="url(#B)" 13 | d="M99.8 67.5c-28 0-26.3 12.1-26.3 12.1v12.6h26.8V96H62.9s-18-2-18 26.3 15.7 27.2 15.7 27.2h9.3v-13s-.5-15.7 15.4-15.7H112s14.9.2 14.9-14.5V82.1s2.2-14.6-27-14.6zM85 75.9a4.8 4.8 0 1 1 0 9.7 4.8 4.8 0 1 1 0-9.7z" 14 | transform="translate(-45 -67.5)"/> 15 | <path fill="url(#Y)" 16 | d="M100.5 177.3c28 0 26.3-12.1 26.3-12.1v-12.6H100v-3.8h37.4s18 2 18-26.3-15.7-27.2-15.7-27.2h-9.3v13s.5 15.7-15.4 15.7H88.4s-14.9-.2-14.9 14.4v24.3s-2.2 14.6 27 14.6zm14.8-8.5a4.8 4.8 0 1 1 0-9.6 4.8 4.8 0 1 1 0 9.6z" 17 | transform="translate(-45 -67.5)"/> 18 | </svg> 19 | -------------------------------------------------------------------------------- /_tools/generate_release_cycle.py: -------------------------------------------------------------------------------- 1 | """Read in a JSON and generate two CSVs and an SVG file.""" 2 | 3 | from __future__ import annotations 4 | 5 | import argparse 6 | import csv 7 | import datetime as dt 8 | import json 9 | 10 | import jinja2 11 | 12 | 13 | def csv_date(date_str: str, now_str: str) -> str: 14 | """Format a date for CSV.""" 15 | if date_str > now_str: 16 | # Future, add italics 17 | return f"*{date_str}*" 18 | return date_str 19 | 20 | 21 | def parse_date(date_str: str) -> dt.date: 22 | if len(date_str) == len("yyyy-mm"): 23 | # We need a full yyyy-mm-dd, so let's approximate 24 | return dt.date.fromisoformat(date_str + "-01") 25 | return dt.date.fromisoformat(date_str) 26 | 27 | 28 | def parse_version(ver: str) -> list[int]: 29 | return [int(i) for i in ver["key"].split(".")] 30 | 31 | 32 | class Versions: 33 | """For converting JSON to CSV and SVG.""" 34 | 35 | def __init__(self, *, limit_to_active=False, special_py27=False) -> None: 36 | with open("include/release-cycle.json", encoding="UTF-8") as in_file: 37 | self.versions = json.load(in_file) 38 | 39 | # Generate a few additional fields 40 | for key, version in self.versions.items(): 41 | version["key"] = key 42 | ver_info = parse_version(version) 43 | if ver_info >= [3, 13]: 44 | full_years = 2 45 | else: 46 | full_years = 1.5 47 | version["first_release_date"] = r1 = parse_date(version["first_release"]) 48 | version["start_security_date"] = r1 + dt.timedelta(days=full_years * 365) 49 | version["end_of_life_date"] = parse_date(version["end_of_life"]) 50 | 51 | self.cutoff = min(ver["first_release_date"] for ver in self.versions.values()) 52 | 53 | if limit_to_active: 54 | self.cutoff = min( 55 | version["first_release_date"] 56 | for version in self.versions.values() 57 | if version["status"] != "end-of-life" 58 | ) 59 | self.versions = { 60 | key: version 61 | for key, version in self.versions.items() 62 | if version["end_of_life_date"] >= self.cutoff 63 | or (special_py27 and key == "2.7") 64 | } 65 | if special_py27: 66 | self.cutoff = min(self.cutoff, dt.date(2019, 8, 1)) 67 | self.id_key = "active" 68 | else: 69 | self.id_key = "all" 70 | 71 | self.sorted_versions = sorted( 72 | self.versions.values(), 73 | key=parse_version, 74 | reverse=True, 75 | ) 76 | 77 | # Set the row (Y coordinate) for the chart, to allow a gap between 2.7 78 | # and the rest 79 | y = len(self.sorted_versions) + (1 if special_py27 else 0) 80 | for version in self.sorted_versions: 81 | if special_py27 and version["key"] == "2.7": 82 | y -= 1 83 | version["y"] = y 84 | y -= 1 85 | 86 | def write_csv(self) -> None: 87 | """Output CSV files.""" 88 | now_str = str(dt.datetime.now(dt.timezone.utc)) 89 | 90 | versions_by_category = {"branches": {}, "end-of-life": {}} 91 | headers = None 92 | for details in self.sorted_versions: 93 | row = { 94 | "Branch": details["branch"], 95 | "Schedule": f":pep:`{details['pep']}`", 96 | "Status": details["status"], 97 | "First release": csv_date(details["first_release"], now_str), 98 | "End of life": csv_date(details["end_of_life"], now_str), 99 | "Release manager": details["release_manager"], 100 | } 101 | headers = row.keys() 102 | cat = "end-of-life" if details["status"] == "end-of-life" else "branches" 103 | versions_by_category[cat][details["key"]] = row 104 | 105 | for cat, versions in versions_by_category.items(): 106 | with open(f"include/{cat}.csv", "w", encoding="UTF-8", newline="") as file: 107 | csv_file = csv.DictWriter(file, fieldnames=headers, lineterminator="\n") 108 | csv_file.writeheader() 109 | csv_file.writerows(versions.values()) 110 | 111 | def write_svg(self, today: str, out_path: str) -> None: 112 | """Output SVG file.""" 113 | env = jinja2.Environment( 114 | loader=jinja2.FileSystemLoader("_tools/"), 115 | autoescape=True, 116 | lstrip_blocks=True, 117 | trim_blocks=True, 118 | undefined=jinja2.StrictUndefined, 119 | ) 120 | template = env.get_template("release_cycle_template.svg.jinja") 121 | 122 | # Scale. Should be roughly the pixel size of the font. 123 | # All later sizes are multiplied by this, so you can think of all other 124 | # numbers being multiples of the font size, like using `em` units in 125 | # CSS. 126 | # (Ideally we'd actually use `em` units, but SVG viewBox doesn't take 127 | # those.) 128 | 129 | # Uppercase sizes are un-scaled 130 | SCALE = 18 131 | 132 | # Width of the drawing and main parts 133 | DIAGRAM_WIDTH = 46 134 | LEGEND_WIDTH = 7 135 | RIGHT_MARGIN = 0.5 136 | 137 | # Height of one line. If you change this you'll need to tweak 138 | # some positioning numbers in the template as well. 139 | LINE_HEIGHT = 1.5 140 | 141 | first_date = self.cutoff 142 | last_date = max(ver["end_of_life_date"] for ver in self.sorted_versions) 143 | 144 | def date_to_x(date: dt.date) -> float: 145 | """Convert datetime.date to an SVG X coordinate""" 146 | num_days = (date - first_date).days 147 | total_days = (last_date - first_date).days 148 | ratio = num_days / total_days 149 | x = ratio * (DIAGRAM_WIDTH - LEGEND_WIDTH - RIGHT_MARGIN) 150 | return (x + LEGEND_WIDTH) * SCALE 151 | 152 | def year_to_x(year: int) -> float: 153 | """Convert year number to an SVG X coordinate of 1st January""" 154 | return date_to_x(dt.date(year, 1, 1)) 155 | 156 | def format_year(year: int) -> str: 157 | """Format year number for display""" 158 | return f"'{year % 100:02}" 159 | 160 | with open(out_path, "w", encoding="UTF-8", newline="\n") as f: 161 | template.stream( 162 | SCALE=SCALE, 163 | diagram_width=DIAGRAM_WIDTH * SCALE, 164 | diagram_height=(self.sorted_versions[0]["y"] + 2) * LINE_HEIGHT * SCALE, 165 | years=range(first_date.year, last_date.year + 1), 166 | line_height=LINE_HEIGHT * SCALE, 167 | legend_width=LEGEND_WIDTH * SCALE, 168 | right_margin=RIGHT_MARGIN * SCALE, 169 | versions=list(reversed(self.sorted_versions)), 170 | today=dt.datetime.strptime(today, "%Y-%m-%d").date(), 171 | year_to_x=year_to_x, 172 | date_to_x=date_to_x, 173 | format_year=format_year, 174 | id_key=self.id_key, 175 | ).dump(f) 176 | 177 | 178 | def main() -> None: 179 | parser = argparse.ArgumentParser( 180 | description=__doc__, formatter_class=argparse.ArgumentDefaultsHelpFormatter 181 | ) 182 | parser.add_argument( 183 | "--today", 184 | default=str(dt.date.today()), 185 | metavar=" YYYY-MM-DD", 186 | help="Override today for testing", 187 | ) 188 | args = parser.parse_args() 189 | 190 | versions = Versions() 191 | assert len(versions.versions) > 10 192 | versions.write_csv() 193 | versions.write_svg(args.today, "include/release-cycle-all.svg") 194 | 195 | versions = Versions(limit_to_active=True, special_py27=True) 196 | versions.write_svg(args.today, "include/release-cycle.svg") 197 | 198 | 199 | if __name__ == "__main__": 200 | main() 201 | -------------------------------------------------------------------------------- /_tools/release_cycle_template.svg.jinja: -------------------------------------------------------------------------------- 1 | <?xml version="1.0" encoding="UTF-8"?> 2 | <svg 3 | xmlns="http://www.w3.org/2000/svg" 4 | class="release-cycle-chart" 5 | viewBox="0 0 {{ diagram_width }} {{ diagram_height }}" 6 | > 7 | <defs> 8 | <linearGradient id="release-cycle-mask-gradient-{{ id_key }}"> 9 | <stop stop-color="black" offset="0%" /> 10 | <stop stop-color="white" offset="100%" /> 11 | </linearGradient> 12 | </defs> 13 | 14 | {% for version in versions %} 15 | {% set y = version.y * line_height %} 16 | 17 | {% if version.y % 2 %} 18 | <!-- Row shading --> 19 | <rect 20 | class="release-cycle-row-shade" 21 | x="0em" 22 | y="{{ y - 1.125 * SCALE }}" 23 | width="{{ diagram_width }}" 24 | height="{{ line_height }}" 25 | /> 26 | {% endif %} 27 | {% endfor %} 28 | 29 | {% for year in years %} 30 | <text 31 | class="release-cycle-year-text" 32 | x="{{ (year_to_x(year) + year_to_x(year + 1)) / 2 }}" 33 | y="{{ diagram_height - line_height }}" 34 | font-size="{{ SCALE * 0.75 }}" 35 | text-anchor="middle" 36 | > 37 | {{ format_year(year) }} 38 | </text> 39 | {% if not loop.last %} 40 | <line 41 | class="release-cycle-year-line" 42 | x1="{{ year_to_x(year + 1) }}" 43 | x2="{{ year_to_x(year + 1) }}" 44 | y1="0" 45 | y2="{{ diagram_height - line_height }}" 46 | font-size="{{ SCALE }}" 47 | /> 48 | {% endif %} 49 | {% endfor %} 50 | 51 | <!-- Gradient mask to fade out end-of-life versions --> 52 | <mask id="release-cycle-mask-{{ id_key }}"> 53 | <rect 54 | x="0" 55 | y="0" 56 | width="{{ legend_width }}" 57 | height="{{ diagram_height }}" 58 | fill="black" 59 | /> 60 | <rect 61 | x="{{ legend_width - right_margin }}" 62 | y="0" 63 | width="{{ right_margin }}" 64 | height="{{ diagram_height }}" 65 | fill="url(#release-cycle-mask-gradient-{{ id_key }})" 66 | /> 67 | <rect 68 | x="{{ legend_width }}" 69 | y="0" 70 | width="{{ diagram_width }}" 71 | height="{{ diagram_height }}" 72 | fill="white" 73 | /> 74 | </mask> 75 | 76 | {% for version in versions %} 77 | <!-- Colourful blob with a label. --> 78 | 79 | {% set top_y = version.y * line_height - 1 * SCALE %} 80 | {% set height = 1.25 * SCALE %} 81 | {% set start_x = date_to_x(version.first_release_date) %} 82 | {% set end_x = date_to_x(version.end_of_life_date) %} 83 | {% set radius = 0.25 * SCALE %} 84 | 85 | {% set small_text_y = version.y * line_height - 0.1 * SCALE %} 86 | 87 | <!-- bugfix/security blobs need to be split between the two phases. 88 | Draw the rectangle with two path elements instead. 89 | Thanks Claude.ai for the initial conversion. 90 | --> 91 | {% set middle_x = ([end_x, date_to_x(version.start_security_date)]|min) %} 92 | {% set left_width = (middle_x - start_x) %} 93 | {% set right_width = (end_x - middle_x) %} 94 | 95 | {% if version.status != "end-of-life" %} 96 | <!-- Split the blob using path operations 97 | (Move-to, Vertical/Horizontal, Arc, Z=close shape; 98 | lowercase means relative to the last point.) 99 | We start drawing from the top of the straight boundary 100 | between the half-blobs. 101 | --> 102 | <path 103 | class="release-cycle-blob release-cycle-status-bugfix" 104 | d=" 105 | M{{ middle_x }},{{ top_y }} {#- start -#} 106 | v{{ height }} {#- down -#} 107 | H{{ start_x + radius }} {#- left -#} 108 | a{{ radius }},{{ radius }} 90 0 1 {#- rounded corner -#} 109 | {{ -radius }} {{ -radius }} 110 | v{{ -height + 2*radius }} {#- up -#} 111 | a{{ radius }},{{ radius }} 90 0 1 {#- rounded corner -#} 112 | {{ radius }} {{ -radius }} 113 | Z {#- right -#} 114 | " 115 | /> 116 | <path 117 | class="release-cycle-blob release-cycle-status-security" 118 | d=" 119 | M{{ middle_x }},{{ top_y }} {#- start -#} 120 | v{{ height }} {#- down -#} 121 | H{{ end_x - radius }} {#- right -#} 122 | a{{ radius }},{{ radius }} 90 0 0 {#- rounded corner -#} 123 | {{ radius }} {{ -radius }} 124 | v{{ -height + 2*radius }} {#- up -#} 125 | a{{ radius }},{{ radius }} 90 0 0 {#- rounded corner -#} 126 | {{ -radius }} {{ -radius }} 127 | Z {#- left -#} 128 | " 129 | /> 130 | <!-- Add a common border --> 131 | <rect 132 | class="release-cycle-border release-cycle-status-{{ version.status }}" 133 | x="{{ start_x }}" 134 | y="{{ top_y }}" 135 | width="{{ (end_x - start_x) }}" 136 | height="{{ height }}" 137 | rx="{{ radius }}" 138 | ry="{{ radius }}" 139 | /> 140 | {% else %} 141 | <!-- For EOL releases, use a single rounded rectangle --> 142 | <rect 143 | class="release-cycle-blob release-cycle-blob-full 144 | release-cycle-status-{{ version.status }}" 145 | x="{{ start_x }}" 146 | y="{{ top_y }}" 147 | width="{{ (end_x - start_x) }}" 148 | height="{{ height }}" 149 | rx="{{ radius }}" 150 | ry="{{ radius }}" 151 | mask="url(#release-cycle-mask-{{ id_key }})" 152 | /> 153 | {% endif %} 154 | 155 | <!-- Add text before/after/inside the blob --> 156 | <text 157 | class="release-cycle-blob-label release-cycle-status-{{ version.status }}" 158 | font-size="{{ SCALE * 0.75 }}" 159 | y="{{ small_text_y }}" 160 | {% if version.status == "bugfix" %} 161 | x="{{ (start_x + middle_x) / 2 }}" 162 | text-anchor="middle" 163 | {% elif version.status == "security" %} 164 | x="{{ (middle_x + end_x) / 2 }}" 165 | text-anchor="middle" 166 | {% elif version.status == "end-of-life" %} 167 | x="{{ end_x + (0.25 * SCALE) }}" 168 | text-anchor="start" 169 | {% else %} 170 | x="{{ start_x - (0.25 * SCALE) }}" 171 | text-anchor="end" 172 | {% endif %} 173 | > 174 | {{ version.status }} 175 | </text> 176 | 177 | <!-- Legend on the left --> 178 | <text 179 | class="release-cycle-version-label" 180 | x="{{ 0.5 * SCALE }}" 181 | y="{{ version.y * line_height }}" 182 | font-size="{{ SCALE }}" 183 | > 184 | Python {{ version.key }} 185 | </text> 186 | {% endfor %} 187 | 188 | <!-- A line for today --> 189 | <line 190 | class="release-cycle-today-line" 191 | x1="{{ date_to_x(today) }}" 192 | x2="{{ date_to_x(today) }}" 193 | y1="0" 194 | y2="{{ diagram_height - line_height }}" 195 | font-size="{{ SCALE }}" 196 | /> 197 | </svg> 198 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | extensions = [ 2 | 'notfound.extension', 3 | 'sphinx.ext.extlinks', 4 | 'sphinx.ext.intersphinx', 5 | 'sphinx.ext.todo', 6 | 'sphinx_copybutton', 7 | 'sphinx_inline_tabs', 8 | 'sphinxext.opengraph', 9 | 'sphinxext.rediraffe', 10 | ] 11 | 12 | # The master toctree document. 13 | master_doc = 'index' 14 | 15 | # General information about the project. 16 | project = "Python Developer's Guide" 17 | copyright = '2011 Python Software Foundation' 18 | 19 | # List of patterns, relative to source directory, that match files and 20 | # directories to ignore when looking for source files. 21 | exclude_patterns = [ 22 | '_build', 23 | 'venv*', 24 | 'env*', 25 | 'README.rst', 26 | '.github', 27 | ] 28 | 29 | nitpicky = True 30 | 31 | 32 | html_theme = 'furo' 33 | html_theme_options = { 34 | "source_repository": "https://github.com/python/devguide", 35 | "source_branch": "main", 36 | } 37 | html_static_path = ['_static'] 38 | html_css_files = [ 39 | 'devguide_overrides.css', 40 | ] 41 | html_js_files = [ 42 | "activate_tab.js", 43 | ] 44 | html_logo = "_static/python-logo.svg" 45 | html_favicon = "_static/favicon.png" 46 | 47 | # Set to '' to prevent appending "documentation" to the site title 48 | html_title = "" 49 | 50 | linkcheck_allowed_redirects = { 51 | # Edit page 52 | r"https://docs.google.com/document/d/.*/": r"https://docs.google.com/document/d/.*/edit", # noqa: E501 53 | # Canonical 54 | r"https://docs.python.org/": r"https://docs.python.org/3/", 55 | # Translations with country codes 56 | r"https://docs.python.org/[a-z-]+/": r"https://docs.python.org/[a-z-]+/3/", 57 | # Personal /my/ links redirect to login page 58 | r"https://discuss.python.org/my/.*": r"https://discuss.python.org/login-preferences", # noqa: E501 59 | # Category number URL to full slug 60 | r"https://discuss.python.org/c/\d+": r"https://discuss.python.org/c/.*", 61 | # Login page 62 | r"https://github.com/python/buildmaster-config/issues/new.*": r"https://github.com/login.*", # noqa: E501 63 | r"https://github.com/python/core-workflow/issues/new.*": r"https://github.com/login.*", # noqa: E501 64 | r"https://github.com/orgs/python/teams.*": r"https://github.com/login.*", # noqa: E501 65 | # Archive redirect 66 | r"https://github.com/python/cpython/archive/main.zip": r"https://codeload.github.com/python/cpython/zip/refs/heads/main", # noqa: E501 67 | # Blob to tree 68 | r"https://github.com/python/cpython/blob/.*": r"https://github.com/python/cpython/tree/.*", # noqa: E501 69 | # HackMD shortcuts 70 | r"https://hackmd.io/s/.*": r"https://hackmd.io/@.*", 71 | # Read the Docs 72 | r"https://python-docs-tr.readthedocs.io/": r"https://python-docs-tr.readthedocs.io/tr/.*", # noqa: E501 73 | r"https://virtualenv.pypa.io/": r"https://virtualenv.pypa.io/en/latest/", 74 | r"https://www.sphinx-doc.org/": r"https://www.sphinx-doc.org/en/master/", 75 | # Cookie consent 76 | r"https://www.youtube.com/playlist.*": r"https://consent.youtube.com/.*", 77 | } 78 | 79 | # ignore linkcheck anchors for /#/$ANCHOR since it is used for 80 | # dynamic pages such as http://buildbot.python.org/all/#/console 81 | # http://www.sphinx-doc.org/en/stable/config.html?highlight=linkcheck#confval-linkcheck_anchors_ignore 82 | linkcheck_anchors_ignore = [ 83 | # match any anchor that starts with a '/' since this is an invalid HTML anchor 84 | r'\/.*', 85 | ] 86 | 87 | linkcheck_ignore = [ 88 | # Checks fail due to rate limits 89 | r'https://github.com/.*', 90 | # The Discourse groups are private unless you are logged in 91 | 'https://discuss.python.org/groups/staff', 92 | 'https://discuss.python.org/groups/moderators', 93 | 'https://discuss.python.org/groups/admins', 94 | # "Anchor not found": 95 | r'https://packaging.python.org/.*#', 96 | # "-rate limited-", causing a timeout 97 | r'https://stackoverflow.com/.*', 98 | # Discord doesn't allow robot crawlers: "403 Client Error: Forbidden" 99 | r'https://support.discord.com/hc/en-us/articles/219070107-Server-Nicknames', 100 | # Patreon also gives 403 to the GHA linkcheck runner 101 | r'https://www.patreon.com/.*', 102 | ] 103 | 104 | rediraffe_redirects = { 105 | # Development Tools 106 | "clang.rst": "development-tools/clang.rst", 107 | "gdb.rst": "development-tools/gdb.rst", 108 | # Advanced Tools was renamed Development Tools in gh-1149 109 | "advanced-tools/clang.rst": "development-tools/clang.rst", 110 | "advanced-tools/gdb.rst": "development-tools/gdb.rst", 111 | # Core Developers 112 | "coredev.rst": "core-developers/become-core-developer.rst", 113 | "committing.rst": "core-developers/committing.rst", 114 | "developers.rst": "core-developers/developer-log.rst", 115 | "experts.rst": "core-developers/experts.rst", 116 | "motivations.rst": "core-developers/motivations.rst", 117 | # Developer Workflow 118 | "c-api.rst": "developer-workflow/c-api.rst", 119 | "communication.rst": "developer-workflow/communication-channels.rst", 120 | "devcycle.rst": "developer-workflow/development-cycle.rst", 121 | "extensions.rst": "developer-workflow/extension-modules.rst", 122 | "grammar.rst": "developer-workflow/grammar.rst", 123 | "langchanges.rst": "developer-workflow/lang-changes.rst", 124 | "porting.rst": "developer-workflow/porting.rst", 125 | "stdlibchanges.rst": "developer-workflow/stdlib.rst", 126 | # Documentation 127 | "docquality.rst": "documentation/help-documenting.rst", 128 | "documenting.rst": "documentation/start-documenting.rst", 129 | # Getting Started 130 | "fixingissues.rst": "getting-started/fixing-issues.rst", 131 | "help.rst": "getting-started/getting-help.rst", 132 | "gitbootcamp.rst": "getting-started/git-boot-camp.rst", 133 | "pullrequest.rst": "getting-started/pull-request-lifecycle.rst", 134 | "setup.rst": "getting-started/setup-building.rst", 135 | # CPython Internals 136 | "compiler.rst": "internals/compiler.rst", 137 | "exploring.rst": "internals/exploring.rst", 138 | "garbage_collector.rst": "internals/garbage-collector.rst", 139 | "parser.rst": "internals/parser.rst", 140 | # Testing and Buildbots 141 | "buildbots.rst": "testing/buildbots.rst", 142 | "coverage.rst": "testing/coverage.rst", 143 | "buildworker.rst": "testing/new-buildbot-worker.rst", 144 | "runtests.rst": "testing/run-write-tests.rst", 145 | "silencewarnings.rst": "testing/silence-warnings.rst", 146 | # Issues and Triaging 147 | "gh-faq.rst": "triage/github-bpo-faq.rst", 148 | "tracker.rst": "triage/issue-tracker.rst", 149 | "gh-labels.rst": "triage/labels.rst", 150 | "triaging.rst": "triage/triaging.rst", 151 | } 152 | 153 | intersphinx_mapping = { 154 | 'python': ('https://docs.python.org/3', None), 155 | 'diataxis': ('https://diataxis.fr/', None), 156 | } 157 | 158 | todo_include_todos = True 159 | 160 | # sphinx-notfound-page 161 | notfound_urls_prefix = "/" 162 | 163 | # prolog and epilogs 164 | rst_prolog = """ 165 | .. |draft| replace:: 166 | This is part of a **Draft** of the Python Contributor's Guide. 167 | Text in square brackets are notes about content to fill in. 168 | Currently, the devguide and this new Contributor's Guide co-exist in the 169 | repo. We are using Sphinx include directives to demonstrate the re-organization. 170 | The final Contributor's Guide will replace the devguide with content in only one 171 | place. 172 | We welcome help with this! 173 | 174 | .. |purpose| replace:: 175 | The :ref:`contrib-plan` page has more details about the current state of this draft 176 | and **how you can help**. See more info about the Contributor Guide in the 177 | discussion forum: `Refactoring the DevGuide`_. 178 | 179 | .. _Refactoring the DevGuide: https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409 180 | 181 | """ 182 | 183 | # sphinx.ext.extlinks 184 | # This config is a dictionary of external sites, 185 | # mapping unique short aliases to a base URL and a prefix. 186 | # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html 187 | _repo = "https://github.com/python/cpython" 188 | extlinks = { 189 | "cpy-file": (f"{_repo}/blob/main/%s", "%s"), 190 | "gh-label": (f"{_repo}/labels/%s", "%s"), 191 | "github": ("https://github.com/%s", "%s"), 192 | "github-user": ("https://github.com/%s", "@%s"), 193 | "pypi": ("https://pypi.org/project/%s/", "%s"), 194 | "pypi-org": ("https://pypi.org/org/%s/", "%s"), 195 | } 196 | 197 | # sphinxext-opengraph config 198 | ogp_site_url = "https://devguide.python.org/" 199 | ogp_site_name = "Python Developer's Guide" 200 | ogp_image = "_static/og-image-200x200.png" 201 | ogp_custom_meta_tags = [ 202 | '<meta property="og:image:width" content="200">', 203 | '<meta property="og:image:height" content="200">', 204 | '<meta name="theme-color" content="#3776ab">', 205 | ] 206 | 207 | # Strip the dollar prompt when copying code 208 | # https://sphinx-copybutton.readthedocs.io/en/latest/use.html#strip-and-configure-input-prompts-for-code-cells 209 | copybutton_prompt_text = "$ " 210 | # https://sphinx-copybutton.readthedocs.io/en/latest/use.html#honor-line-continuation-characters-when-copying-multline-snippets 211 | copybutton_line_continuation_character = "\\" 212 | -------------------------------------------------------------------------------- /contrib/code/developer-workflow.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | Development workflow 3 | ==================== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | [This is the existing :ref:`dev-workflow` page from the devguide] 12 | 13 | .. toctree:: 14 | :maxdepth: 5 15 | 16 | ../../developer-workflow/communication-channels 17 | ../../developer-workflow/development-cycle 18 | ../../developer-workflow/stdlib 19 | ../../developer-workflow/extension-modules 20 | ../../developer-workflow/c-api 21 | ../../developer-workflow/lang-changes 22 | ../../developer-workflow/grammar 23 | ../../developer-workflow/porting 24 | ../../developer-workflow/sbom 25 | ../../developer-workflow/psrt 26 | -------------------------------------------------------------------------------- /contrib/code/development-tools.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | Development tools 3 | ================= 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | [This is the existing :ref:`development-tools` page from the devguide.] 12 | 13 | .. toctree:: 14 | :maxdepth: 5 15 | 16 | ../../development-tools/clinic 17 | ../../development-tools/gdb 18 | ../../development-tools/clang 19 | ../../development-tools/warnings 20 | -------------------------------------------------------------------------------- /contrib/code/git.rst: -------------------------------------------------------------------------------- 1 | ======== 2 | Git tips 3 | ======== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | [More git help for advanced things needed by code contributors.] 12 | -------------------------------------------------------------------------------- /contrib/code/index.rst: -------------------------------------------------------------------------------- 1 | .. _c_code: 2 | 3 | ================== 4 | Code contributions 5 | ================== 6 | 7 | .. important:: 8 | 9 | |draft| 10 | 11 | |purpose| 12 | 13 | [The main page for code contributors.] 14 | 15 | [We'll include code-focused content from the :ref:`main devguide page <devguide-main>`: Quick 16 | reference, Quick links, Proposing changes, and so on.] 17 | 18 | [The existing :ref:`internals` section of the devguide will be fully 19 | migrated into the Python repo.] 20 | 21 | 22 | .. toctree:: 23 | :maxdepth: 5 24 | 25 | setup 26 | git 27 | pull-request-lifecycle 28 | developer-workflow 29 | testing 30 | development-tools 31 | -------------------------------------------------------------------------------- /contrib/code/pull-request-lifecycle.rst: -------------------------------------------------------------------------------- 1 | .. _code-pull-request-lifecycle: 2 | 3 | ====================== 4 | Pull request lifecycle 5 | ====================== 6 | 7 | .. important:: 8 | 9 | |draft| 10 | 11 | |purpose| 12 | 13 | 14 | [Details of pull requests for code contributions. The existing 15 | :ref:`pull-request-lifecycle` page is long and includes many details. 16 | Some only apply to code contributions, but many are common to all 17 | contributions. Should we keep a common page, with extra steps here, or 18 | should this page have all of the details even if they are duplicated 19 | elsewhere?] 20 | 21 | [See :ref:`docs-pull-request-lifecycle` for the documentation half of this conundrum.] 22 | -------------------------------------------------------------------------------- /contrib/code/setup.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | Setup and building 3 | ================== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | [More setup and build instructions specifically for code contributors, building 12 | on the basics from the :ref:`Getting Started <getting-started>` section.] 13 | -------------------------------------------------------------------------------- /contrib/code/testing.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | Testing and buildbots 3 | ===================== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | [This is the existing :ref:`testing` page from the devguide.] 12 | 13 | .. toctree:: 14 | :maxdepth: 5 15 | 16 | ../../testing/run-write-tests 17 | ../../testing/silence-warnings 18 | ../../testing/coverage 19 | ../../testing/buildbots 20 | ../../testing/new-buildbot-worker 21 | -------------------------------------------------------------------------------- /contrib/contrib-plan.rst: -------------------------------------------------------------------------------- 1 | .. _contrib-plan: 2 | 3 | ================================== 4 | [Plan for the Contributor's Guide] 5 | ================================== 6 | 7 | .. important:: 8 | 9 | |draft| 10 | 11 | |purpose| 12 | 13 | We are in the process of updating and refactoring the devguide to be a 14 | Contributor's Guide. It will highlight the different kinds of contribution 15 | possible, and how to succeed at each kind. 16 | 17 | Currently, the Contibutor's Guide is a draft in this new last section of the 18 | devguide. We welcome feedback, but please understand that some of the current 19 | content is moving or skeletal. 20 | 21 | Repo structure 22 | ============== 23 | 24 | While the reorganization is happening, we are keeping the old devguide as it 25 | is. The new Contributor's Guide is represented in this last section, but will 26 | eventually be the only content in the guide. To avoid copying content, we're 27 | using Sphinx include directives to display existing devguide content in its new 28 | Contributor's Guide location. That is not how the eventual Guide will be 29 | built. Once we are ready to make the Contributor's Guide real, we will 30 | rearrange content into its new location. 31 | 32 | How to help 33 | =========== 34 | 35 | To help, you can: 36 | 37 | - `Write an issue`_ detailing a change you'd like to see here. 38 | - `Make a pull request`_ in this repo to add content. 39 | - Join us in the `Python Docs Discord`_ to collaborate with other docs-minded 40 | community members. 41 | - Get in touch with the `Docs Editorial Board`_ to discuss larger documentation 42 | concerns. 43 | 44 | .. _Write an issue: https://github.com/python/devguide/issues 45 | .. _Make a pull request: https://github.com/python/devguide/pulls 46 | .. _Python Docs Discord: https://discord.gg/qcfPbnM2zH 47 | .. _Docs Editorial Board: https://python.github.io/editorial-board/ 48 | -------------------------------------------------------------------------------- /contrib/core-team/committing.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | 8 | [This is the existing core developers :ref:`committing` page from the devguide. We'll 9 | adjust "core developer" to "core team" where appropriate.] 10 | 11 | .. include:: ../../core-developers/committing.rst 12 | -------------------------------------------------------------------------------- /contrib/core-team/developer-log.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | 8 | [This is the existing core developers :ref:`developer-log` page from the devguide. We'll 9 | adjust "core developer" to "core team" where appropriate.] 10 | 11 | .. include:: ../../core-developers/developer-log.rst 12 | -------------------------------------------------------------------------------- /contrib/core-team/experts.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | 8 | [This is the existing core developers :ref:`experts` page from the devguide. We'll 9 | adjust "core developer" to "core team" where appropriate.] 10 | 11 | .. include:: ../../core-developers/experts.rst 12 | -------------------------------------------------------------------------------- /contrib/core-team/index.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | 8 | .. _c_coreteam: 9 | 10 | ========= 11 | Core team 12 | ========= 13 | 14 | [This is mostly re-organized from the :ref:`core-dev` section of the devguide, 15 | but with "core developer" language changed to "core team" where possible.] 16 | 17 | .. toctree:: 18 | :maxdepth: 5 19 | 20 | responsibilities 21 | committing 22 | experts 23 | developer-log 24 | motivations 25 | join-team 26 | -------------------------------------------------------------------------------- /contrib/core-team/join-team.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | 8 | [This is the existing core developers :ref:`become-core-developer` page from the devguide with the title changed. We'll 9 | adjust "core developer" to "core team" where appropriate.] 10 | 11 | ========================= 12 | How to join the core team 13 | ========================= 14 | 15 | .. include:: ../../core-developers/become-core-developer.rst 16 | :start-line: 7 17 | -------------------------------------------------------------------------------- /contrib/core-team/motivations.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | 8 | [This is the existing core developers :ref:`motivations` page from the devguide. We'll 9 | adjust "core developer" to "core team" where appropriate.] 10 | 11 | .. include:: ../../core-developers/motivations.rst 12 | -------------------------------------------------------------------------------- /contrib/core-team/responsibilities.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | 8 | [This is the existing core developers :ref:`responsibilities` page from the devguide. We'll 9 | adjust "core developer" to "core team" where appropriate.] 10 | 11 | .. include:: ../../core-developers/responsibilities.rst 12 | -------------------------------------------------------------------------------- /contrib/doc/devguide.rst: -------------------------------------------------------------------------------- 1 | ================================== 2 | Helping with the Developer's Guide 3 | ================================== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | 12 | [This is the existing :ref:`devguide` page from the devguide.] 13 | -------------------------------------------------------------------------------- /contrib/doc/help-documenting.rst: -------------------------------------------------------------------------------- 1 | ========================== 2 | Helping with documentation 3 | ========================== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | 12 | [This is the existing :ref:`help-documenting` page from the devguide.] 13 | -------------------------------------------------------------------------------- /contrib/doc/index.rst: -------------------------------------------------------------------------------- 1 | .. _c_docs: 2 | 3 | =========================== 4 | Documentation contributions 5 | =========================== 6 | 7 | .. important:: 8 | 9 | |draft| 10 | 11 | |purpose| 12 | 13 | 14 | [The main page for documentation contributors.] 15 | 16 | [We'll include docs-focused content from the :ref:`main devguide page <devguide-main>`: Quick 17 | reference, Quick links, and so on.] 18 | 19 | 20 | .. toctree:: 21 | :maxdepth: 5 22 | 23 | start-documenting 24 | help-documenting 25 | style-guide 26 | markup 27 | pull-request-lifecycle 28 | translating 29 | devguide 30 | -------------------------------------------------------------------------------- /contrib/doc/markup.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | reStructuredText markup 3 | ======================= 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | 12 | [This is the existing :ref:`markup` page from the devguide.] 13 | -------------------------------------------------------------------------------- /contrib/doc/pull-request-lifecycle.rst: -------------------------------------------------------------------------------- 1 | .. _docs-pull-request-lifecycle: 2 | 3 | ====================== 4 | Pull request lifecycle 5 | ====================== 6 | 7 | .. important:: 8 | 9 | |draft| 10 | 11 | |purpose| 12 | 13 | 14 | [Details of pull requests for documentation contributions. The existing 15 | :ref:`pull-request-lifecycle` page is long and includes many details. 16 | Some only apply to code contributions, but many are common to all 17 | contributions. Should we keep a common page, with documentation tweaks here, or 18 | should this page have only the documentation details even if they are duplicated 19 | elsewhere?] 20 | 21 | [See :ref:`code-pull-request-lifecycle` for the code half of this conundrum.] 22 | -------------------------------------------------------------------------------- /contrib/doc/start-documenting.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Getting started 3 | =============== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | 12 | [This is the existing documentation :ref:`start-documenting` page from the devguide.] 13 | -------------------------------------------------------------------------------- /contrib/doc/style-guide.rst: -------------------------------------------------------------------------------- 1 | =========== 2 | Style guide 3 | =========== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | 12 | [This is the existing documentation :ref:`style-guide` page from the devguide.] 13 | -------------------------------------------------------------------------------- /contrib/doc/translating.rst: -------------------------------------------------------------------------------- 1 | =========== 2 | Translating 3 | =========== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | 12 | [This is the existing :ref:`translating` page from the devguide.] 13 | -------------------------------------------------------------------------------- /contrib/index.rst: -------------------------------------------------------------------------------- 1 | .. _c_root: 2 | 3 | ================================== 4 | Python Contributor's Guide (draft) 5 | ================================== 6 | 7 | .. raw:: html 8 | 9 | <script> 10 | document.addEventListener('DOMContentLoaded', function() { 11 | activateTab(getOS()); 12 | }); 13 | </script> 14 | 15 | 16 | .. important:: 17 | 18 | |draft| 19 | 20 | |purpose| 21 | 22 | 23 | [Open question: how to divide content between this Introduction and the 24 | :ref:`introduction <c_intro>`?] 25 | 26 | This guide is a comprehensive resource for :ref:`contributing <contributing>` 27 | to Python_ -- for both new and experienced contributors. It is :ref:`maintained 28 | <devguide>` by the same community that maintains Python. We welcome your 29 | contributions to Python! 30 | 31 | We encourage everyone to contribute to Python. This guide should have 32 | everything you need to get started and be productive. If you still have 33 | questions after reviewing the material in this guide, the `Core Python 34 | Mentorship`_ group is available to help you through the process. 35 | 36 | There are a number of ways to contribute including code, documentation, and 37 | triaging issues. We've organized this guide to provide specifics based on the 38 | type of activity you'll be engaged in. 39 | 40 | 41 | Using this guide 42 | ================ 43 | 44 | We recommend reading this guide as needed. You can stop where you feel 45 | comfortable and begin contributing immediately without reading and 46 | understanding everything. If you do choose to skip around this guide, be aware 47 | that it is written assuming preceding sections have been read so you may need 48 | to backtrack to fill in missing concepts and terminology. 49 | 50 | No matter what kind of contribution you'll be making, you should start with 51 | these common sections: 52 | 53 | * :ref:`c_intro` 54 | * :ref:`c_project` 55 | 56 | Then choose a path based on your type of activity: 57 | 58 | *[The original table on the devguide home had a fourth column for Core 59 | Developers. That made the table wider and more confusing. I don't think core 60 | team members need a quick intro path since they will have been through the 61 | devguide before.]* 62 | 63 | *[I haven't adjusted the links in the table yet other than to add a link to the 64 | major section at the top of each column.]* 65 | 66 | .. list-table:: 67 | :widths: 10 10 10 68 | :header-rows: 1 69 | 70 | * - :ref:`Documentation <c_docs>` 71 | - :ref:`Code <c_code>` 72 | - :ref:`Triaging <c_triage>` 73 | * - 74 | * :ref:`docquality` 75 | * :ref:`documenting` 76 | * :ref:`style-guide` 77 | * :ref:`rst-primer` 78 | * :ref:`translating` 79 | * :ref:`devguide` 80 | - 81 | * :ref:`setup` 82 | * :ref:`help` 83 | * :ref:`pullrequest` 84 | * :ref:`runtests` 85 | * :ref:`fixingissues` 86 | * :ref:`communication` 87 | * :ref:`gitbootcamp` 88 | * :ref:`devcycle` 89 | - 90 | * :ref:`tracker` 91 | * :ref:`triaging` 92 | * :ref:`helptriage` 93 | * :ref:`experts` 94 | * :ref:`labels` 95 | * :ref:`gh-faq` 96 | * :ref:`triage-team` 97 | 98 | Core team members will find guidance in the :ref:`c_coreteam` section. 99 | 100 | Contents 101 | ======== 102 | 103 | .. toctree:: 104 | :maxdepth: 3 105 | 106 | contrib-plan 107 | intro/index 108 | project/index 109 | triage/index 110 | doc/index 111 | code/index 112 | core-team/index 113 | user-success 114 | security 115 | workflows/index 116 | 117 | 118 | .. _Python: https://www.python.org/ 119 | .. _Core Python Mentorship: https://www.python.org/dev/core-mentorship/ 120 | -------------------------------------------------------------------------------- /contrib/intro/index.rst: -------------------------------------------------------------------------------- 1 | .. _c_intro: 2 | 3 | ============ 4 | Introduction 5 | ============ 6 | 7 | .. important:: 8 | 9 | |draft| 10 | 11 | |purpose| 12 | 13 | 14 | 15 | [Open question: how to divide content between this Introduction and the 16 | :ref:`home page <c_root>`?] 17 | 18 | Welcome! 19 | 20 | New to open source? 21 | =================== 22 | 23 | Python is an open source project, with culture and techniques from the broader 24 | open source world. You might find it helpful to read about open source in 25 | general. A number of individuals from the Python community have contributed to 26 | a series of excellent guides at `Open Source Guides 27 | <https://opensource.guide/>`_. 28 | 29 | Anyone will find the following guides useful: 30 | 31 | * `How to Contribute to Open Source <https://opensource.guide/how-to-contribute/>`_ 32 | * `Building Welcoming Communities <https://opensource.guide/building-community/>`_ 33 | 34 | 35 | Healthy collaboration 36 | ===================== 37 | 38 | [Importance of healthy inclusive collaboration] 39 | 40 | [While code is a large part of the project's success, project management, documentation, governance, sprint outreach, etc. matter.] 41 | 42 | [We respect the individual skills people bring to the project and strive to create and maintain a culture of inclusion.] 43 | 44 | About this guide 45 | ================ 46 | 47 | Types of contribution 48 | ===================== 49 | 50 | [Pathways for contributors] 51 | 52 | Helping with this guide 53 | ======================= 54 | -------------------------------------------------------------------------------- /contrib/project/channels.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | 8 | ====================== 9 | Communication channels 10 | ====================== 11 | 12 | * Repos 13 | * Discourse 14 | * Discord 15 | * Mailing lists (deprioritize) 16 | * Where to get help 17 | -------------------------------------------------------------------------------- /contrib/project/conduct.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Code of Conduct 3 | =============== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | 12 | [Brief summary of the code of conduct, with links to official source.] 13 | 14 | * Standard for communication 15 | * How to report 16 | * Enforcement details 17 | -------------------------------------------------------------------------------- /contrib/project/directory-structure.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | .. _c_directory_structure: 8 | 9 | =================== 10 | Directory structure 11 | =================== 12 | 13 | [This is the :ref:`build_directory_structure` section from the devguide.] 14 | 15 | .. include:: ../../getting-started/setup-building.rst 16 | :start-after: c_directory_structure_start 17 | :end-before: c_directory_structure_end 18 | -------------------------------------------------------------------------------- /contrib/project/generative-ai.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | 8 | [This is the existing :ref:`generative-ai` page from the devguide.] 9 | 10 | .. include:: ../../getting-started/generative-ai.rst 11 | -------------------------------------------------------------------------------- /contrib/project/github.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | ====== 8 | GitHub 9 | ====== 10 | 11 | [Where are the actual artifacts?] 12 | 13 | * Main CPython repos 14 | * Core workflow repos 15 | * Infrastructure repos 16 | -------------------------------------------------------------------------------- /contrib/project/governance.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | 8 | ========== 9 | Governance 10 | ========== 11 | 12 | [How decisions are made, who is involved, how to participate.] 13 | 14 | Steering Council 15 | ================ 16 | 17 | Documentation Editorial Board 18 | ============================= 19 | 20 | Typing Council 21 | ============== 22 | 23 | 24 | Others? 25 | ======= 26 | -------------------------------------------------------------------------------- /contrib/project/index.rst: -------------------------------------------------------------------------------- 1 | .. _c_project: 2 | 3 | =================== 4 | The CPython project 5 | =================== 6 | 7 | .. important:: 8 | 9 | |draft| 10 | 11 | |purpose| 12 | 13 | 14 | [Give the reader an understanding of the project as a whole. What are the 15 | moving parts, who is involved, how do they interact?] 16 | 17 | * Structure 18 | 19 | .. toctree:: 20 | :maxdepth: 5 21 | 22 | conduct 23 | roles 24 | governance 25 | generative-ai.rst 26 | github 27 | directory-structure.rst 28 | channels 29 | outreach 30 | -------------------------------------------------------------------------------- /contrib/project/outreach.rst: -------------------------------------------------------------------------------- 1 | ======== 2 | Outreach 3 | ======== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | 12 | * Sprints 13 | -------------------------------------------------------------------------------- /contrib/project/roles.rst: -------------------------------------------------------------------------------- 1 | ===== 2 | Roles 3 | ===== 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | 12 | [Quick overview of the roles people play. Core team has its own section.] 13 | 14 | * Core team 15 | * Triager 16 | * Contributors 17 | * types of contributions 18 | -------------------------------------------------------------------------------- /contrib/security.rst: -------------------------------------------------------------------------------- 1 | ========================================= 2 | Security and infrastructure contributions 3 | ========================================= 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | * Security 12 | * Infrastructure 13 | * Core workflow 14 | -------------------------------------------------------------------------------- /contrib/triage/index.rst: -------------------------------------------------------------------------------- 1 | .. _c_triage: 2 | 3 | =================== 4 | Issues and triaging 5 | =================== 6 | 7 | .. toctree:: 8 | :maxdepth: 5 9 | 10 | issue-tracker 11 | triaging 12 | labels 13 | reviewing 14 | triage-team 15 | -------------------------------------------------------------------------------- /contrib/triage/issue-tracker.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | [This is the existing :ref:`issue-tracker` page from the devguide] 8 | 9 | .. include:: ../../triage/issue-tracker.rst 10 | -------------------------------------------------------------------------------- /contrib/triage/labels.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | [This is the existing :ref:`labels` page from the devguide] 8 | 9 | .. include:: ../../triage/labels.rst 10 | -------------------------------------------------------------------------------- /contrib/triage/reviewing.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | 8 | ========= 9 | Reviewing 10 | ========= 11 | 12 | * How? Etiquette? 13 | * How to request a review? 14 | -------------------------------------------------------------------------------- /contrib/triage/triage-team.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | [This is the existing :ref:`triage-team` page from the devguide] 8 | 9 | .. include:: ../../triage/triage-team.rst 10 | -------------------------------------------------------------------------------- /contrib/triage/triaging.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | [This is the existing :ref:`triaging` page from the devguide] 8 | 9 | .. include:: ../../triage/triaging.rst 10 | -------------------------------------------------------------------------------- /contrib/user-success.rst: -------------------------------------------------------------------------------- 1 | ======================================= 2 | Accessibility, design, and user success 3 | ======================================= 4 | 5 | .. important:: 6 | 7 | |draft| 8 | 9 | |purpose| 10 | 11 | 12 | * Accessibility 13 | * Design 14 | * User success 15 | -------------------------------------------------------------------------------- /contrib/workflows/codespaces.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | .. _c_using_codespaces: 8 | 9 | ======================= 10 | Using GitHub Codespaces 11 | ======================= 12 | 13 | [This is the :ref:`using-codespaces` section from the devguide.] 14 | 15 | .. include:: ../../getting-started/setup-building.rst 16 | :start-after: c_codespaces_start 17 | :end-before: c_codespaces_end 18 | -------------------------------------------------------------------------------- /contrib/workflows/compile.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | .. _c_compiling: 8 | 9 | ================= 10 | Compile and build 11 | ================= 12 | 13 | .. note:: 14 | [This is the :ref:`compiling` section from the devguide. I think this page 15 | is too long and could be split by build target, but we can leave that for a 16 | later time.] 17 | 18 | .. include:: ../../getting-started/setup-building.rst 19 | :start-after: c_compile_and_build_start 20 | :end-before: c_compile_and_build_end 21 | 22 | .. include:: ../../links.rst 23 | -------------------------------------------------------------------------------- /contrib/workflows/get-source.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | .. _c_checkout: 8 | 9 | =================== 10 | Get the source code 11 | =================== 12 | 13 | .. note:: 14 | [This is the :ref:`checkout` section from the devguide. We might need to edit 15 | it to clarify that some steps are only needed for code contribution.] 16 | 17 | .. include:: ../../getting-started/setup-building.rst 18 | :start-after: c_get_source_code_start 19 | :end-before: c_get_source_code_end 20 | -------------------------------------------------------------------------------- /contrib/workflows/index.rst: -------------------------------------------------------------------------------- 1 | .. _c_workflows: 2 | 3 | ========= 4 | Workflows 5 | ========= 6 | 7 | .. important:: 8 | 9 | |draft| 10 | 11 | |purpose| 12 | 13 | 14 | This section contains details of workflows needed for all kinds of 15 | contribution. 16 | 17 | .. toctree:: 18 | 19 | install-git.rst 20 | get-source.rst 21 | install-dependencies.rst 22 | compile.rst 23 | regenerate.rst 24 | troubleshooting.rst 25 | codespaces.rst 26 | -------------------------------------------------------------------------------- /contrib/workflows/install-dependencies.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | .. _c_build-dependencies: 8 | 9 | ==================== 10 | Install Dependencies 11 | ==================== 12 | 13 | [This is the :ref:`build-dependencies` section from the devguide.] 14 | 15 | .. include:: ../../getting-started/setup-building.rst 16 | :start-after: c_install_dependencies_start 17 | :end-before: c_install_dependencies_end 18 | -------------------------------------------------------------------------------- /contrib/workflows/install-git.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | .. _c_vcsetup: 8 | 9 | =========== 10 | Install Git 11 | =========== 12 | 13 | [This is the :ref:`vcsetup` section from the devguide.] 14 | 15 | .. include:: ../../getting-started/setup-building.rst 16 | :start-after: c_install_git_start 17 | :end-before: c_install_git_end 18 | -------------------------------------------------------------------------------- /contrib/workflows/regenerate.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | .. _c_regenerating: 8 | 9 | =============================== 10 | Regenerating auto-created files 11 | =============================== 12 | 13 | .. note:: 14 | [These are two similar sections from the is the :ref:`setup-building` section from the devguide.] 15 | 16 | Regenerate ``configure`` 17 | ======================== 18 | 19 | .. include:: ../../getting-started/setup-building.rst 20 | :start-after: c_regenerate_configure_start 21 | :end-before: c_regenerate_configure_end 22 | 23 | Regenerate the ABI dump 24 | ======================= 25 | 26 | .. include:: ../../getting-started/setup-building.rst 27 | :start-after: c_regenerate_abi_start 28 | :end-before: c_regenerate_abi_end 29 | -------------------------------------------------------------------------------- /contrib/workflows/troubleshooting.rst: -------------------------------------------------------------------------------- 1 | .. important:: 2 | 3 | |draft| 4 | 5 | |purpose| 6 | 7 | .. _c_build_troubleshooting: 8 | 9 | =========== 10 | Install Git 11 | =========== 12 | 13 | [This is the :ref:`build_troubleshooting` section from the devguide.] 14 | 15 | .. include:: ../../getting-started/setup-building.rst 16 | :start-after: c_build_troubleshooting_start 17 | :end-before: c_build_troubleshooting_end 18 | -------------------------------------------------------------------------------- /core-developers/become-core-developer.rst: -------------------------------------------------------------------------------- 1 | .. _become-core-developer: 2 | .. _coredev: 3 | 4 | ============================== 5 | How to become a core developer 6 | ============================== 7 | 8 | What it takes 9 | ============= 10 | 11 | When you have consistently made contributions which meet quality standards 12 | without requiring extensive rewrites prior to being committed, 13 | you may qualify for commit privileges and become a core developer of Python. 14 | You must also work well with other core developers (and people in general) 15 | as you become an ambassador for the Python project. 16 | 17 | Typically a core developer will offer you the chance to gain commit privilege. 18 | The person making the offer will become your mentor and watch your commits for 19 | a while to make sure you understand the development process. If other core 20 | developers agree that you should gain commit privileges you are then extended 21 | an official offer. How core developers come to that agreement are outlined in 22 | :pep:`13`. 23 | 24 | 25 | Gaining commit privileges 26 | ========================= 27 | 28 | After a candidate has demonstrated consistent contributions, commit privileges 29 | are granted through these steps: 30 | 31 | #. A core developer (submitter, usually the mentor) starts a poll 32 | (see the :ref:`template <coredev-template>` below) in 33 | the `Committers category`_ on the `Python Discourse`_. 34 | 35 | - open for 7 days 36 | - results shown only upon closing 37 | 38 | #. If the candidate receives at least two-thirds positive votes when the poll closes 39 | (as per :pep:`13`), the submitter `emails the steering council 40 | <mailto:steering-council@python.org>`_ with the candidate's email address 41 | requesting that the council either accept or reject the proposed membership. Technically, the 42 | council may only `veto a positive vote <https://peps.python.org/pep-0013/#membership>`_. 43 | 44 | #. Assuming the steering council does not veto the positive vote, a member of the council or its 45 | delegate (approver, usually in practice a :ref:`Developer-in-Residence <current owners>`) will 46 | email the candidate: 47 | 48 | - A request for account details as required by 49 | `🔒 python/voters <https://github.com/python/voters>`_. 50 | - A reminder about the `Code of Conduct`_ and guidance on reporting issues 51 | to the PSF Conduct WG. 52 | 53 | #. Once the candidate has provided the pertinent details, the approver will: 54 | 55 | - Enable the various new privileges. 56 | - Remove the new committer from the triage team, if applicable. 57 | - Add their details to `🔒 python/voters <https://github.com/python/voters>`_. 58 | - Update the devguide to publicly list their team membership 59 | at :ref:`developers`. 60 | - Post an announcement in the `Committers Discourse category 61 | <https://discuss.python.org/c/committers/5>`_. The past few announcements 62 | were in the form of a separate post on the already open topic with 63 | the poll. 64 | 65 | Getting a python.org email address 66 | ---------------------------------- 67 | 68 | Members of the core team can get an email address on the python.org domain. 69 | For more details refer to the `python.org email policy 70 | <https://www.python.org/psf/records/board/policies/email/>`_. 71 | 72 | 73 | Poll template 74 | ============= 75 | 76 | .. _coredev-template: 77 | 78 | While Discourse uses Markdown for formatting, the poll functionality is 79 | custom and somewhat resembles BBcode. There's a creator for polls in the 80 | UI (click the cog icon in the edit box toolbar and choose "Build Poll"). 81 | Here's what it outputs, you can copy and paste it for your poll: 82 | 83 | .. code-block:: bbcode 84 | 85 | [poll type=regular results=on_close public=false chartType=bar groups=committers close=2024-07-15T21:15:00.000Z] 86 | * Promote Basil Fawlty 87 | * Do not promote 88 | [/poll] 89 | 90 | The important options in the poll builder set to get this result: 91 | - Show who voted: **disabled** (``public=false``) 92 | - Limit voting to these groups: **committers** (``groups=committers``) 93 | - Automatically close poll: **in 7 days** (``close=...``) 94 | - Show results: **When poll is closed** (``results=on_close``) 95 | 96 | .. raw:: html 97 | 98 | <script> 99 | for (let span of document.querySelectorAll('span')) { 100 | if (span.textContent === '2024-07-15T21:15:00.000Z') { 101 | const nextWeek = new Date(); 102 | nextWeek.setDate(nextWeek.getDate() + 7); 103 | nextWeek.setSeconds(0); 104 | nextWeek.setMilliseconds(0); 105 | span.textContent = nextWeek.toISOString(); 106 | break; 107 | } 108 | } 109 | </script> 110 | 111 | .. _Code of Conduct: https://policies.python.org/python.org/code-of-conduct/ 112 | .. _Committers category: https://discuss.python.org/c/committers/5 113 | .. _Python Discourse: https://discuss.python.org 114 | -------------------------------------------------------------------------------- /core-developers/developer-log.rst: -------------------------------------------------------------------------------- 1 | .. _developer-log: 2 | .. _developers: 3 | 4 | Developer log 5 | ============= 6 | 7 | This page lists the historical members of the Python development team. (The 8 | master list is kept in a private repository due to containing sensitive contact 9 | information.) 10 | 11 | .. csv-table:: 12 | :header: "Name", "GitHub username", "Joined", "Left", "Notes" 13 | :file: developers.csv 14 | :encoding: "utf-8" 15 | 16 | Procedure for granting or dropping access 17 | ----------------------------------------- 18 | 19 | To be granted the ability to manage who is a committer, you must be a 20 | team maintainer of the `Python core team`_ on GitHub. Once you have 21 | that privilege you can add people to the team. They will be asked to 22 | accept the membership which they can do by visiting 23 | https://github.com/python and clicking on the appropriate button that 24 | will be displayed to them in the upper part of the page. 25 | 26 | .. _Python core team: https://github.com/orgs/python/teams/python-core 27 | -------------------------------------------------------------------------------- /core-developers/index.rst: -------------------------------------------------------------------------------- 1 | .. _core-dev: 2 | 3 | =============== 4 | Core developers 5 | =============== 6 | 7 | .. toctree:: 8 | :maxdepth: 5 9 | 10 | responsibilities 11 | committing 12 | experts 13 | developer-log 14 | motivations 15 | become-core-developer 16 | memorialization 17 | -------------------------------------------------------------------------------- /core-developers/memorialization.rst: -------------------------------------------------------------------------------- 1 | .. _memorialize-core-developer: 2 | 3 | =============== 4 | Memorialization 5 | =============== 6 | 7 | Rationale 8 | ========= 9 | 10 | When a core developer passes away, memorializing accounts helps create 11 | a space for remembering the contributor and protects against attempted 12 | logins and fraudulent activity. 13 | 14 | The process 15 | =========== 16 | 17 | The memorialization process is performed by a member of the PSF staff 18 | with administrative access to current and historical systems where 19 | core developers have access. 20 | 21 | After the status of the core developer in question is confirmed, 22 | access to the systems listed below is revoked and some changes are 23 | made to how the user displays to others. 24 | 25 | To respect the choices that someone made while alive, we aim to preserve 26 | content of their accounts without changes after they've passed away. 27 | To support the bereaved, in some instances, we may remove or change 28 | certain content when the legacy contact or family members request it. 29 | 30 | GitHub 31 | ------ 32 | 33 | * The user is removed from the `python/ <https://github.com/orgs/python/>`_ 34 | organization on GitHub; 35 | * The user is removed from the `psf/ <https://github.com/orgs/psf/>`_ 36 | organization on GitHub; 37 | * The user is removed from the `pypa/ <https://github.com/orgs/pypa/>`_ 38 | organization on GitHub. 39 | 40 | The PSF staff does not follow up with GitHub with regards to GitHub account 41 | cancellation as this action is reserved for next-of-kin or designated by 42 | the deceased GitHub user to act as an account successor. 43 | 44 | The general policy regarding deceased users on GitHub is described on their 45 | `Deceased User Policy <https://docs.github.com/en/site-policy/other-site-policies/github-deceased-user-policy>`_ 46 | page. 47 | 48 | Repositories in the organization 49 | -------------------------------- 50 | 51 | * The user's GitHub handle is removed from ``/.github/CODEOWNERS``. 52 | To see all that need action, perform 53 | `this query <https://github.com/search?q=org%3Apython+path%3A**%2F.github%2FCODEOWNERS+USERNAME&type=code>`_. 54 | * The user is marked as deceased in the private 55 | `voters/python-core.toml <https://github.com/python/voters/blob/main/python-core.toml>`_ 56 | file with the ``left=`` field set to the day of passing, if known. 57 | 58 | discuss.python.org 59 | ------------------ 60 | 61 | * The user's "custom status" is set to 🕊 ``in memoriam``; 62 | * The user's "about me" is amended with ``$firstname passed away on $date. [In memoriam.]($in_memoriam_post_url)``; 63 | * In the user's security "recently used devices" the staff member 64 | chooses "Log out all"; 65 | * In the user's permissions the staff member chooses "Deactivate account"; 66 | * The user's trust level is reset to ``1: basic user`` (trust level 0 67 | doesn't allow links in "About Me"); 68 | * The user's "associated accounts" (like GitHub) that provide an 69 | alternative login method, are all disconnected; 70 | * The user's API keys are revoked; 71 | * The user's admin or moderator right is revoked; 72 | * The user's primary email address is reset to 73 | ``USERNAME@in-memoriam.invalid`` and secondary email addresses are 74 | removed (this step requires the administrator to contact Discourse.org 75 | staff via ``team@discourse.org``). 76 | 77 | The "in memoriam" Discourse topic mentioned above is best created by 78 | a community member close to the deceased. 79 | 80 | The general best practice for deceased community members on 81 | Discourse-powered forums is described on their 82 | `Best practices for deceased community members <https://meta.discourse.org/t/best-practices-for-deceased-community-members/146210>`_ 83 | page. 84 | 85 | python.org email account 86 | ------------------------ 87 | 88 | The PSF staff member emails ``postmaster@python.org`` to ask the email 89 | administrator to: 90 | 91 | * remove SMTP access from ``USERNAME@python.org``; 92 | * reset the password to POP3/IMAP for ``USERNAME@python.org``; 93 | * disable email forwarding, if set up, for ``USERNAME@python.org`` and 94 | leave a record permanently as "in memoriam" to avoid future account 95 | name reuse; 96 | * remove this email from all mailing lists under ``@python.org``; 97 | * remove any known alternate emails for the same user from all mailing 98 | lists under ``@python.org``. 99 | 100 | In case the email shutdown causes issues for the estate executors, the 101 | PSF will reasonably try to help if contacted directly. 102 | 103 | python.org admin 104 | ---------------- 105 | 106 | * The user's account (``/admin/users/user``) is deactivated (NOT deleted) 107 | and their staff and superuser status is unchecked; 108 | * The user's password is reset to a long random string; 109 | * The user's primary email address is set to 110 | ``USERNAME@in-memoriam.invalid`` and set as unverified; 111 | * The user's secondary email addresses are deleted; 112 | * The user's API keys (both on the account and ``tastypie``) are deleted; 113 | * The user's "I would like to be a PSF Voting Member" field is cleared. 114 | 115 | devguide.python.org 116 | ------------------- 117 | 118 | * The user is marked as deceased in `developers.csv <https://github.com/python/devguide/blob/main/core-developers/developers.csv>`_; 119 | * The user is removed from the `Experts Index <https://github.com/python/devguide/blob/main/core-developers/experts.rst>`_. 120 | 121 | bugs.python.org 122 | --------------- 123 | 124 | While the issue tracker was migrated to GitHub, the Roundup instance 125 | is still up for historical purposes. 126 | 127 | * the PSF staff member logs into ``bugs.nyc1.psf.io``; 128 | * the PSF staff member runs ``roundup-admin`` to set the user's email 129 | address to ``USERNAME@in-memoriam.invalid``; 130 | * the user's alternate emails are removed; 131 | * the user's password is reset to a long random string; 132 | * the PSF staff member removes any active login sessions from Postgres. 133 | 134 | Other PSF-related infrastructure 135 | -------------------------------- 136 | 137 | * The PSF staff member notifies administrators of the Python Core Devs 138 | Discord server to remove the user from the server. The PSF staff 139 | does not follow up with Discord with regards to Discord account 140 | cancellation. The general policy regarding deceased users on Discord 141 | is available on their `Deceased or Incapacitated Users <https://support.discord.com/hc/en-us/articles/19872987802263--Deceased-or-Incapacitated-Users>`_ 142 | page. 143 | 144 | * The user is removed from Salt configuration for the PSF infrastructure 145 | in `/pillar/base/users <https://github.com/python/psf-salt/tree/main/pillar/base/users>`_ 146 | that allows SSH access to PSF-controlled servers. 147 | 148 | * The user might have ran a buildbot worker. The PSF staff member will 149 | look for that in the 150 | `buildmaster-config <https://github.com/search?q=repo%3Apython%2Fbuildmaster-config%20USERNAME&type=code>`_ 151 | repository. 152 | 153 | PyPI 154 | ---- 155 | 156 | * The PSF staff member notifies PyPI admins by emailing them at 157 | ``admin@pypi.org`` to mark the user as inactive, remove their email 158 | addresses, prohibit their password resets, and revoke all API keys. 159 | -------------------------------------------------------------------------------- /core-developers/responsibilities.rst: -------------------------------------------------------------------------------- 1 | .. _responsibilities: 2 | 3 | ================ 4 | Responsibilities 5 | ================ 6 | 7 | As contributors to the CPython project, our shared responsibility is to 8 | collaborate constructively with other contributors, including core developers. 9 | This responsibility covers all forms of contribution, whether that's submitting 10 | pull requests to the implementation or documentation, reviewing other peoples' 11 | pull requests, triaging issues on the issue tracker, or discussing design and 12 | development ideas on the core 13 | :ref:`communication channels <communication-channels>`. 14 | 15 | Core developers accept key additional responsibilities around the ongoing 16 | management of the project: 17 | 18 | * core developers bear the additional responsibility of handling the 19 | consequences of accepting a change into the code base or documentation. 20 | That includes reverting or fixing it if it causes problems in the 21 | Buildbot fleet or someone spots a problem in post-commit review, as well 22 | as helping out the release manager in resolving any problems found during 23 | the pre-release testing cycle. While all contributors are free to help out 24 | with this part of the process, and it is most welcome when they do, the 25 | actual responsibility rests with the core developer that merged the change 26 | * core developers also bear the primary responsibility for deciding when 27 | changes proposed on the issue tracker should be escalated to 28 | the appropriate :ref:`Discourse <communication-discourse>` category 29 | for wider discussion, as well as suggesting the use of the 30 | Python Enhancement Proposal process to manage the design and justification 31 | of complex changes, or changes with a potentially significant impact on 32 | end users 33 | 34 | As a result of the additional responsibilities they accept, core developers 35 | gain the privilege of being able to approve proposed changes, as well as being 36 | able to reject them as inappropriate. Core developers are also able to request 37 | that even already merged changes be escalated to 38 | :ref:`Discourse <communication-discourse>` for further discussion, 39 | and potentially even reverted prior to release. 40 | 41 | Becoming a core developer isn't a binary "all-or-nothing" status - CPython 42 | is a large project, and different core developers accept responsibility for 43 | making design and development decisions in different areas (as documented 44 | in the :ref:`experts` and :ref:`developers`). 45 | 46 | 47 | Communication channels and bug notifications 48 | ============================================ 49 | 50 | Mailing lists have generally been replaced by the 51 | `Discourse forum <https://discuss.python.org/>`_ (``discuss.python.org``). 52 | Refer to the :ref:`mailinglists` and :ref:`communication-discourse` sections 53 | for more information. 54 | 55 | If you want notification of new issues, you can use the appropriate GitHub notification 56 | settings for the `python/cpython <https://github.com/python/cpython>`_ repository — 57 | follow the link and click on the :guilabel:`Watch` button to set your notification options. 58 | 59 | 60 | .. _contributor_agreement: 61 | 62 | Sign a contributor agreement 63 | ============================ 64 | 65 | Submitting a `contributor form for Python`_ licenses any code you contribute to 66 | the Python Software Foundation. While you retain the copyright, giving the PSF 67 | the ability to license your code means it can be put under the PSF license so 68 | it can be legally distributed with Python. 69 | 70 | This is a very important step! Hopefully you have already submitted a 71 | contributor agreement if you have been submitting pull requests. But if you have not 72 | done this yet, it is best to do this ASAP, probably before you even do your 73 | first commit so as to not forget. Also do not forget to enter your GitHub 74 | username into your details on the issue tracker. 75 | 76 | 77 | .. _contributor form for Python: https://www.python.org/psf/contrib/ 78 | 79 | 80 | Pull request merging 81 | ==================== 82 | 83 | Once you have your commit privileges on GitHub you will be able to accept 84 | pull requests on GitHub. You should plan to continue to submit your own 85 | changes through pull requests as if you weren't a core developer to benefit 86 | from various things such as automatic integration testing, but you 87 | can accept your own pull requests if you feel comfortable doing so. 88 | 89 | 90 | Expectations 91 | ============ 92 | 93 | As a core developer, there are certain things that are expected of you. 94 | 95 | First and foremost, be a good person. This might sound melodramatic, but you 96 | are now a member of the Python project and thus represent the project and your 97 | fellow core developers whenever you discuss Python with anyone. We have a 98 | reputation for being a very nice group of people and we would like to keep it 99 | that way. Core developers responsibilities include following the `PSF Code of 100 | Conduct`_. 101 | 102 | Second, please be prompt in responding to questions. Many contributors to Python 103 | are volunteers so what little free time they can dedicate to Python should be 104 | spent being productive. If you have been asked to respond to an issue or answer 105 | a question and you put it off it ends up stalling other people's work. It is 106 | completely acceptable to say you are too busy, but you need to say that instead 107 | of leaving people waiting for an answer. This also applies to anything you 108 | do on the issue tracker. 109 | 110 | Third, please list what areas you want to be considered an expert in the 111 | :ref:`experts`. This allows triagers to direct issues to you which involve 112 | an area you are an expert in. But, as stated in the second point above, if you 113 | do not have the time to answer questions promptly then please remove yourself as 114 | needed from the file so that you will not be bothered in the future. Once again, 115 | we all understand how life gets in the way, so no one will be insulted if you 116 | remove yourself from the list. 117 | 118 | Fourth, please consider whether or not you wish to add your name to the 119 | :ref:`motivations` list. Core contributor participation in the list helps the 120 | wider Python community to better appreciate the perspectives currently 121 | represented amongst the core development team, the Python Software Foundation 122 | to better assess the sustainability of current contributions to CPython core 123 | development, and also serves as a referral list for organisations seeking 124 | commercial Python support from the core development community. 125 | 126 | And finally, enjoy yourself! Contributing to open source software should be fun 127 | (overall). If you find yourself no longer enjoying the work then either take a 128 | break or figure out what you need to do to make it enjoyable again. 129 | 130 | .. _PSF Code of Conduct: https://policies.python.org/python.org/code-of-conduct/ 131 | -------------------------------------------------------------------------------- /developer-workflow/grammar.rst: -------------------------------------------------------------------------------- 1 | .. _grammar: 2 | 3 | ========================== 4 | Changing CPython's grammar 5 | ========================== 6 | 7 | This document is now part of the 8 | `CPython Internals Docs <https://github.com/python/cpython/blob/main/InternalDocs/changing_grammar.md>`_. 9 | -------------------------------------------------------------------------------- /developer-workflow/index.rst: -------------------------------------------------------------------------------- 1 | .. _dev-workflow: 2 | 3 | ==================== 4 | Development workflow 5 | ==================== 6 | 7 | .. toctree:: 8 | :maxdepth: 5 9 | 10 | communication-channels 11 | development-cycle 12 | stdlib 13 | extension-modules 14 | c-api 15 | lang-changes 16 | grammar 17 | porting 18 | sbom 19 | psrt 20 | -------------------------------------------------------------------------------- /developer-workflow/lang-changes.rst: -------------------------------------------------------------------------------- 1 | .. _lang-changes: 2 | .. _langchanges: 3 | 4 | Changing the Python language 5 | ============================ 6 | On occasion people come up with an idea on how to change or improve Python as a 7 | programming language. This document is meant to explain exactly what changes 8 | have a reasonable chance of being considered and what the process is to propose 9 | changes to the language. 10 | 11 | 12 | What qualifies 13 | -------------- 14 | First and foremost, it must be understood that changes to the Python 15 | programming language are difficult to make. When the language changes, 16 | **every** Python programmer already in existence and all Python programmers to 17 | come will end up eventually learning about the change you want to propose. 18 | Books will need updating, code will be changed, and a new way to do things will 19 | need to be learned. Changes to the Python programming language are never taken 20 | lightly. 21 | 22 | Because of the seriousness that language changes carry, any change must be 23 | beneficial to a large proportion of Python users. If the change only benefits a 24 | small percentage of Python developers then the change will not be made. A good 25 | way to see if your idea would work for a large portion of the Python community 26 | is to ask in the `Ideas Discourse category`_. You can also 27 | go through Python's stdlib and find examples of code which would benefit from 28 | your proposed change (which helps communicate the usefulness of your change to 29 | others). For further guidance, see :ref:`suggesting-changes`. 30 | 31 | Your proposed change also needs to be *Pythonic*. While only the Steering 32 | Council can truly classify something as Pythonic, you can read the 33 | :pep:`Zen of Python <20>` for guidance. 34 | 35 | 36 | .. index:: 37 | single: PEP process 38 | 39 | .. _suggesting-changes: 40 | 41 | Suggesting new features and language changes 42 | -------------------------------------------- 43 | 44 | The `Ideas Discourse category`_ 45 | is specifically intended for discussion of new features and language changes. 46 | Please don't be disappointed if your idea isn't met with universal approval: 47 | as the :pep:`long list of Withdrawn and Rejected PEPs 48 | <0#rejected-superseded-and-withdrawn-peps>` 49 | in the :pep:`PEP Index <0>` attests, 50 | and as befits a reasonably mature programming language, 51 | getting significant changes into Python isn't a simple task. 52 | 53 | If the idea is reasonable, someone will suggest posting it as a feature 54 | request on the `issue tracker`_, or, for larger changes, 55 | writing it up as PEP following the :ref:`lang-changes-pep-process`. 56 | 57 | Sometimes core developers will differ in opinion, 58 | or merely be collectively unconvinced. 59 | When there isn't an obvious victor, then the `Status Quo Wins a Stalemate`_. 60 | 61 | For some examples on language changes that were accepted, 62 | see `Justifying Python Language Changes`_. 63 | 64 | 65 | .. index:: PEP process 66 | 67 | .. _lang-changes-pep-process: 68 | 69 | PEP process 70 | ----------- 71 | 72 | Once you are certain you have a language change proposal 73 | which will appeal to the general Python community, 74 | you can begin the :abbr:`PEP (Python enhancement proposal)` process 75 | to officially propose the change. 76 | See :pep:`1` for information on PEPs and the PEP process, 77 | and the :pep:`PEP Index <0>` for examples. 78 | 79 | If the PEP is accepted, then your proposed language change will be introduced 80 | in the next release of Python. 81 | Otherwise, your PEP will be recorded as rejected along with an explanation, 82 | to inform others who may propose a similar language change in the future. 83 | 84 | 85 | .. _issue tracker: https://github.com/python/cpython/issues 86 | .. _Ideas Discourse category: https://discuss.python.org/c/ideas/6 87 | .. _Status Quo Wins a Stalemate: https://www.curiousefficiency.org/posts/2011/02/status-quo-wins-stalemate.html 88 | .. _Justifying Python Language Changes: https://www.curiousefficiency.org/posts/2011/02/justifying-python-language-changes.html 89 | -------------------------------------------------------------------------------- /developer-workflow/porting.rst: -------------------------------------------------------------------------------- 1 | .. _porting: 2 | 3 | ========================= 4 | Porting to a new platform 5 | ========================= 6 | 7 | The first step is to familiarize yourself with the development toolchain on 8 | the platform in question, notably the C compiler. Make sure you can compile and 9 | run a hello-world program using the target compiler. 10 | 11 | Next, learn how to compile and run the Python interpreter on a platform to 12 | which it has already been ported; preferably Unix, but Windows will 13 | do, too. The build process for Python, in particular the ``Makefile`` in the 14 | source distribution, will give you a hint on which files to compile 15 | for Python. Not all source files are relevant: some are platform-specific, 16 | and others are only used in emergencies (for example, ``getopt.c``). 17 | 18 | It is not recommended to start porting Python without at least a medium-level 19 | understanding of your target platform; how it is generally used, how to 20 | write platform-specific apps, and so on. Also, some Python knowledge is required, or 21 | you will be unable to verify that your port is working correctly. 22 | 23 | You will need a ``pyconfig.h`` file tailored for your platform. You can 24 | start with ``pyconfig.h.in``, read the comments, and turn on definitions that 25 | apply to your platform. Also, you will need a ``config.c`` file, which lists 26 | the built-in modules you support. Again, starting with 27 | ``Modules/config.c.in`` is recommended. 28 | 29 | Finally, you will run into some things that are not supported on your 30 | target platform. Forget about the ``posix`` module in the beginning. You can 31 | simply comment it out of the ``config.c`` file. 32 | 33 | Keep working on it until you get a ``>>>`` prompt. You may have to disable the 34 | importing of ``site.py`` by passing the ``-S`` option. When you have a prompt, 35 | bang on it until it executes very simple Python statements. 36 | 37 | At some point you will want to use the ``os`` module; this is the time to start 38 | thinking about what to do with the ``posix`` module. It is okay to simply 39 | comment out functions in the ``posix`` module that cause problems; the 40 | remaining ones will be quite useful. 41 | 42 | Before you are done, it is highly recommended to run the Python regression test 43 | suite, as described in :ref:`runtests`. 44 | -------------------------------------------------------------------------------- /developer-workflow/psrt.rst: -------------------------------------------------------------------------------- 1 | Python Security Response Team (PSRT) 2 | ==================================== 3 | 4 | The Python Security Response Team (PSRT) is responsible for handling 5 | vulnerability reports for CPython and pip. 6 | 7 | Vulnerability report triage 8 | --------------------------- 9 | 10 | Vulnerability reports are sent to one of two locations, 11 | the long-standing ``security@python.org`` mailing list 12 | or using the private vulnerability reporting feature 13 | of GitHub Security Advisories (GHSA). 14 | 15 | For reports sent to ``security@python.org``, a PSRT admin 16 | will triage the report and if the report seems plausible 17 | (that is, not spam and for the correct project) will reply with 18 | instructions on how to report the vulnerability on GitHub. 19 | 20 | If the reporter doesn't want to use GitHub's Security Advisories feature 21 | then the PSRT admins can create a draft report on behalf of the reporter. 22 | 23 | Coordinating a vulnerability report 24 | ----------------------------------- 25 | 26 | Each report will have a member of the PSRT assigned as the "coordinator". 27 | The coordinator will be responsible for following the below process and 28 | will be publicly credited on vulnerability records post-publication. 29 | 30 | If a coordinator can't complete the process for any reason (time obligation, 31 | vacation, etc.) they must find a replacement coordinator in the PSRT 32 | and reassign the vulnerability report appropriately. 33 | 34 | Coordinators are expected to collaborate with other PSRT members and core developers 35 | when needed for guidance on whether the report is an actual vulnerability, 36 | severity, advisory text, and fixes. 37 | 38 | **The vulnerability coordination process is:** 39 | 40 | * Coordinator will determine whether the report constitutes a vulnerability. If the report isn't a vulnerability, 41 | the reporter should be notified appropriately. Close the GHSA report, the report can be reopened if 42 | sufficient evidence is later obtained that the report is a vulnerability. 43 | 44 | * After a vulnerability report is accepted, a Common Vulnerabilities and Exposures (CVE) ID must be assigned. If this is not done 45 | automatically, then a CVE ID can be obtained by the coordinator sending an email to ``cna@python.org``. 46 | No details about the vulnerability report need to be shared with the PSF CVE Numbering Authority (CNA) for a CVE ID to be reserved. 47 | 48 | * If the report is a vulnerability, the coordinator will determine the severity of the vulnerability. Severity is one of: 49 | **Low**, **Medium**, **High**, and **Critical**. Coordinators can use their knowledge of the code, how the code is likely used, 50 | or another mechanism like Common Vulnerability Scoring System (CVSS) for determining a severity. Add this information to the GitHub Security Advisory. 51 | 52 | * Once a CVE ID is assigned, the coordinator will share the acceptance and CVE ID with the reporter. 53 | Use this CVE ID for referencing the vulnerability. The coordinator will ask the reporter 54 | if the reporter would like to be credited publicly for the report and if so, how they would like to be credited. 55 | Add this information to the GitHub Security Advisory. 56 | 57 | * The coordinator authors the vulnerability advisory text. The advisory must include the following information: 58 | 59 | * Title should be a brief description of the vulnerability and affected component 60 | (for example, "Buffer over-read in SSLContext.set_npn_protocols()") 61 | 62 | * Short description of the vulnerability, impact, and the conditions where the affected component is vulnerable, if applicable. 63 | 64 | * Affected versions. This could be "all versions", but if the vulnerability exists in a new feature 65 | or removed feature then this could be different. Include versions that are end-of-life in this calculation 66 | (for example, "Python 3.9 and earlier", "Python 3.10 and later", "all versions of Python"). 67 | 68 | * Affected components and APIs. The module, function, class, or method must be specified so users can 69 | search their codebase for usage. For issues affecting the entire project, this can be omitted. 70 | 71 | * Mitigations for the vulnerability beyond upgrading to a fixed version, if applicable. 72 | 73 | This can all be done within the GitHub Security Advisory UI for easier collaboration between reporter and coordinator. 74 | 75 | * The coordinator determines the fix approach and who will provide a fix. 76 | Some reporters are willing to provide or collaborate to create a fix, 77 | otherwise relevant core developers can be invited to collaborate by 78 | the coordinator. 79 | 80 | * For **Low** and **Medium** severity vulnerabilities it is acceptable 81 | to develop a fix in public. 82 | The pull request must be marked with the ``security`` and ``release-blocker`` 83 | labels so that a release is not created without including the fix. 84 | 85 | * For **High** and **Critical** severity vulnerabilities the fix must be 86 | developed privately using GitHub Security Advisories' "Private Forks" feature. 87 | Core developers can be added to the GitHub Security Advisory via "collaborators" 88 | to work on the fix together. Once a fix is approved privately and tested, 89 | a public issue and pull request can be created with 90 | the ``security`` and ``release-blocker`` labels. 91 | 92 | * Once the pull request is merged the advisory can be published. The coordinator will send the advisory by email 93 | to ``security-announce@python.org`` using the below template. Backport labels must be added as appropriate. 94 | After the advisory is published a CVE record can be created. 95 | 96 | Template responses 97 | ------------------ 98 | 99 | These template responses should be used as guidance for messaging 100 | in various points in the process above. They are not required to be sent as-is, 101 | please feel free to adapt them as needed for the current context. 102 | 103 | **Directing to GitHub Security Advisories:** 104 | 105 | .. highlight:: none 106 | 107 | :: 108 | 109 | Thanks for submitting this report. 110 | We use GitHub Security Advisories for triaging vulnerability reports, 111 | are you able to submit your report directly to GitHub? 112 | 113 | https://github.com/python/cpython/security/advisories/new 114 | 115 | If you're unable to submit a report to GitHub (due to not having a GitHub 116 | account or something else) let me know and I will create a GitHub Security 117 | Advisory on your behalf, although you won't be able to participate directly 118 | in discussions. 119 | 120 | **Rejecting a vulnerability report:** 121 | 122 | :: 123 | 124 | Thanks for your report. We've determined that the report doesn't constitute 125 | a vulnerability. Let us know if you disagree with this determination. 126 | If you are interested in working on this further, you can optionally open a 127 | public issue on GitHub. 128 | 129 | **Accepting a vulnerability report:** 130 | 131 | :: 132 | 133 | Thanks for your report. We've determined that the report 134 | is a vulnerability. We've assigned {CVE-YYYY-XXXX} and determined 135 | a severity of {Low,Medium,High,Critical}. Let us know if you disagree 136 | with the determined severity. 137 | 138 | If you would like to be publicly credited for this vulnerability as the 139 | reporter, please indicate that, along with how you would like to be 140 | credited (name or organization). 141 | 142 | Please keep this vulnerability report private until we've published 143 | an advisory to ``security-announce@python.org``. 144 | 145 | **Advisory email:** 146 | 147 | :: 148 | 149 | Title: [{CVE-YYYY-XXXX}] {title} 150 | 151 | There is a {LOW, MEDIUM, HIGH, CRITICAL} severity vulnerability 152 | affecting {project}. 153 | 154 | {description} 155 | 156 | Please see the linked CVE ID for the latest information on 157 | affected versions: 158 | 159 | * https://www.cve.org/CVERecord?id={CVE-YYYY-XXXX} 160 | * {pull request URL} 161 | -------------------------------------------------------------------------------- /developer-workflow/sbom.rst: -------------------------------------------------------------------------------- 1 | Software Bill-of-Materials (SBOM) 2 | ================================= 3 | 4 | Software Bill-of-Materials (abbreviated as "SBOM") is a document for sharing 5 | information about software and how it's been composed. This format is used 6 | most often in the security space for checking software and its dependencies 7 | for vulnerabilities using vulnerability databases like 8 | `CVE <https://www.cve.org/>`_ and `OSV <https://osv.dev/>`_. The SBOM format 9 | that the CPython project uses is `SPDX <https://spdx.github.io/spdx-spec/v2.3/>`_ 10 | which can be transformed into other formats if necessary by consumers. 11 | 12 | There are multiple sources of third-party dependencies for CPython. 13 | Some are vendored into the source code of CPython itself (like ``mpdecimal`` 14 | vendored at :cpy-file:`Modules/_decimal/libmpdec`) or they could be optionally pulled 15 | in during builds like Windows using dependencies from the 16 | `python/cpython-source-deps <https://github.com/python/cpython-source-deps>`_ 17 | repository. 18 | 19 | Whenever adding or updating a third-party dependency, an update will likely 20 | need to be done to the SBOM in order to track the version and software identifiers. 21 | 22 | Updating a dependency 23 | --------------------- 24 | 25 | The SBOM for CPython's bundled dependencies is kept at 26 | :cpy-file:`Misc/sbom.spdx.json`. When updating a dependency to a new version 27 | you'll need to edit the version and other metadata about this dependency in 28 | the SBOM. 29 | 30 | The recommended workflow is: 31 | 32 | 1. Download the new dependency as an archive. Take note of the new version, download 33 | URL, and checksum of the downloaded archive. 34 | 2. Update the vendored code in the CPython source tree. 35 | 3. Edit :cpy-file:`Misc/sbom.spdx.json` to add the new ``versionInfo``, 36 | ``downloadLocation``, ``checksums``, and ``externalReferences`` for the 37 | corresponding ``package``. For most of these updates all that's needed is to 38 | update the embedded version within URLs and project identifiers. 39 | Don't update any information in ``files`` and ``relationships`` as this will 40 | be generated automatically by the SBOM tool. 41 | 4. Run ``make regen-sbom`` or ``python Tools/build/generate_sbom.py``. 42 | Ensure that this doesn't fail with validation errors. 43 | 5. Run ``git diff Misc/sbom.spdx.json`` and check the diff matches the 44 | expected changes. 45 | 6. Commit the changes to :cpy-file:`Misc/sbom.spdx.json` along with the 46 | update to the dependency code. 47 | 48 | Adding a new dependency 49 | ----------------------- 50 | 51 | When adding a dependency it's important to have the following information: 52 | 53 | * Name, version, and download URL of the project 54 | * License of the project as an `SPDX License Expression <https://spdx.org/licenses/>`_ 55 | * Software identifiers that match values in vulnerability databases 56 | (`CPE <https://nvd.nist.gov/products/cpe>`_ and 57 | `Package URLs <https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst>`_ 58 | or "PURLs") 59 | * Paths to include and exclude in the CPython source tree corresponding to this dependency 60 | 61 | After gathering this information: 62 | 63 | 1. Add the information into a new entry in ``packages`` in the file 64 | :cpy-file:`Misc/sbom.spdx.json`. Don't worry about formatting, the tool will 65 | auto-format your manually written JSON. The fields to fill out include: 66 | 67 | * ``name`` for the project name. 68 | * ``SPDXID`` which will be ``"SPDXRef-PACKAGE-{name}"``. 69 | * ``licenseConcluded`` for the SPDX license identifier of the project license. 70 | * ``versionInfo`` for the version of the project. 71 | * ``downloadLocation`` should be an HTTPS URL for the project download as an archive. 72 | * ``checksums[0].checksumValue`` and ``.algorithm`` will be the SHA-256 73 | checksum of the downloaded archive. 74 | * ``originator`` for the original author information, prefix with either an 75 | ``Organization:`` or ``Person:`` depending on the author/maintenance situation. 76 | * ``primaryPackagePurpose`` will likely be ``"SOURCE"``. 77 | * ``externalReferences`` is a list of one or more project identifiers, 78 | either CPE or Package URL. The value for ``referenceLocator`` must include 79 | the value in ``versionInfo`` to ensure the identifier 80 | corresponds to the correct release of the software. You can read more about 81 | external references in the `SPDX SBOM specification`_. 82 | 2. If a new license ID is to be used, add the license expression to 83 | ``ALLOWED_LICENSE_EXPRESSIONS`` in the :cpy-file:`Tools/build/generate_sbom.py`. 84 | 3. Add the paths to include and exclude into a ``PackageFiles`` instance 85 | with a key corresponding to the SBOM ID for the package (``SPDXID`` without the 86 | ``SPDXRef-PACKAGE-*`` prefix) in :cpy-file:`Tools/build/generate_sbom.py`. 87 | 4. Run the tool with ``make regen-sbom`` or ``python Tools/build/generate_sbom.py``. 88 | Ensure that the tool doesn't fail with any validation errors. 89 | 5. Compare the changes to :cpy-file:`Misc/sbom.spdx.json` with ``git diff``, check 90 | that all information appears correct. 91 | 6. Commit the changes to :cpy-file:`Misc/sbom.spdx.json` and 92 | :cpy-file:`Tools/build/generate_sbom.py`. 93 | 94 | .. _SPDX SBOM specification: https://spdx.github.io/spdx-spec/v2-draft/external-repository-identifiers/ 95 | 96 | Removing a dependency 97 | --------------------- 98 | 99 | When removing a dependency: 100 | 101 | 1. Remove the entry from the :cpy-file:`Misc/sbom.spdx.json` 102 | under the ``packages`` field. 103 | 2. Remove the corresponding ``PackageFiles`` entry in :cpy-file:`Tools/build/generate_sbom.py` 104 | 3. Run the tool with ``make regen-sbom`` or ``python Tools/build/generate_sbom.py``. 105 | Ensure that the tool doesn't fail with any validation errors. 106 | 4. Compare the changes to :cpy-file:`Misc/sbom.spdx.json` with ``git diff``, check 107 | that correct package is removed from the SBOM. 108 | 5. Commit the changes to :cpy-file:`Misc/sbom.spdx.json` and 109 | :cpy-file:`Tools/build/generate_sbom.py`. 110 | -------------------------------------------------------------------------------- /developer-workflow/stdlib.rst: -------------------------------------------------------------------------------- 1 | .. _stdlib: 2 | .. _stdlibchanges: 3 | 4 | Adding to the stdlib 5 | ==================== 6 | 7 | While the stdlib contains a great amount of useful code, sometimes you want 8 | more than is provided. This document is meant to explain how you can get either 9 | a new addition to a pre-existing module in the stdlib or add an entirely new 10 | module. 11 | 12 | Changes to pre-existing code is not covered as that is considered a bugfix and 13 | thus is treated as a bug that should be filed on the `issue tracker`_. 14 | 15 | 16 | Adding to a pre-existing module 17 | ------------------------------- 18 | 19 | If you have found that a function, method, or class is useful and you believe 20 | it would be useful to the general Python community, there are some steps to go 21 | through in order to see it added to the stdlib. 22 | 23 | First, you should gauge the usefulness of the code, 24 | which is typically done by sharing the code publicly. 25 | This is not a required step, but it is suggested. 26 | You have a several options for this: 27 | 28 | * Search the `issue tracker`_ for discussion related to the proposed addition. 29 | This may turn up an issue that explains why the suggestion wasn't accepted. 30 | * Open a new thread in the `Ideas Discourse category`_ 31 | to gather feedback directly from the Python core developers and community. 32 | * Write a blog post about the code, which may also help gather useful feedback. 33 | 34 | If you have found general acceptance and usefulness for your code from people, 35 | you can open an issue on the `issue tracker`_ with the code attached as a 36 | :ref:`pull request <pullrequest>`. If possible, also submit a 37 | :ref:`contributor agreement <contributor_agreement>`. 38 | 39 | If a core developer decides that your code would be useful to the general 40 | Python community, they will then commit your code. If your code is not picked 41 | up by a core developer and committed then please do not take this personally. 42 | Through your public sharing of your code in order to gauge community support 43 | for it you at least can know that others will come across it who may find it 44 | useful. 45 | 46 | .. _Ideas Discourse category: https://discuss.python.org/c/ideas/6 47 | 48 | 49 | Adding a new module 50 | ------------------- 51 | 52 | It must be stated upfront that getting a new module into the stdlib is very 53 | difficult. Adding any significant amount of code to the stdlib increases the 54 | burden placed upon core developers. It also means that the module somewhat 55 | becomes "sanctioned" by the core developers as a good way to do something, 56 | typically leading to the rest of the Python community to using the new module 57 | over other available solutions. All of this means that additions to the stdlib 58 | are not taken lightly. 59 | 60 | 61 | Acceptable types of modules 62 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 63 | 64 | Typically two types of modules get added to the stdlib. One type is a module 65 | which implements something that is difficult to get right. A good example of 66 | this is the :py:mod:`multiprocessing` package. Working out the various OS 67 | issues, working through concurrency issues, etc. are all very difficult to get 68 | right. 69 | 70 | The second type of module is one that implements something that people 71 | re-implement constantly. The :py:mod:`itertools` module is a good example of 72 | this type as its constituent parts are not necessarily complex, but are used 73 | regularly in a wide range of programs and can be a little tricky to get right. 74 | Modules that parse widely used data formats also fall under this type of module 75 | that the stdlib consists of. 76 | 77 | While a new stdlib module does not need to appeal to all users of Python, it 78 | should be something that a large portion of the community will find useful. 79 | This makes sure that the developer burden placed upon core developers is worth 80 | it. 81 | 82 | 83 | Requirements 84 | ^^^^^^^^^^^^ 85 | 86 | In order for a module to even be considered for inclusion into the stdlib, a 87 | couple of requirements must be met. 88 | 89 | The most basic is that the code must meet 90 | :ref:`standard pull request requirements <pullrequest>`. For code that has 91 | been developed outside the stdlib typically this means making sure the coding 92 | style guides are followed and that the proper tests have been written. 93 | 94 | The module needs to have been out in the community for at least a year. Because 95 | of Python's conservative nature when it comes to backwards-compatibility, when 96 | a module is added to the stdlib its API becomes frozen. This means that a module 97 | should only enter the stdlib when it is mature and gone through its 98 | "growing pains". 99 | 100 | The module needs to be considered best-of-breed. When something is included in 101 | the stdlib it tends to be chosen first for products over other third-party 102 | solutions. By virtue of having been available to the public for at least a 103 | year, a module needs to have established itself as (one of) the top choices by 104 | the community for solving the problem the module is intended for. 105 | 106 | The development of the module must move into Python's 107 | infrastructure (that is, the module is no longer directly maintained outside of 108 | Python). This prevents a divergence between the code that is included in the 109 | stdlib and that which is released outside the stdlib (typically done to provide 110 | the module to older versions of Python). It also removes the burden of forcing 111 | core developers to have to redirect bug reports or changes to an external issue 112 | tracker and :abbr:`VCS (version control system)`. 113 | 114 | Someone involved with the development of the 115 | module must promise to help maintain the module in the stdlib for two years. 116 | This not only helps out other core developers by alleviating workload from bug 117 | reports that arrive from the first Python release containing the module, but 118 | also helps to make sure that the overall design of the module continues to be 119 | uniform. 120 | 121 | 122 | Proposal process 123 | ^^^^^^^^^^^^^^^^ 124 | 125 | If the module you want to propose adding to the stdlib meets the requirements, 126 | you may propose its inclusion 127 | by following the :abbr:`PEP (Python Enhancement Proposal)` process. 128 | See :pep:`1` for details, 129 | and the :pep:`PEP index <0>` for previously-accepted PEPs 130 | that have proposed a module for inclusion. 131 | 132 | If the PEP is accepted, then the module will be added to the stdlib 133 | once the authors of the module sign 134 | :ref:`contributor agreements <contributor_agreement>`. 135 | 136 | .. _issue tracker: https://github.com/python/cpython/issues 137 | 138 | Adding a new environment variable 139 | --------------------------------- 140 | 141 | Names of environment variables should be uppercase and, from Python 3.13 142 | onwards, use underscores for readability and accessibility. 143 | 144 | For example, use ``PYTHON_CPU_COUNT`` instead of ``PYTHONCPUCOUNT``. 145 | 146 | See also: 147 | 148 | * :ref:`python:using-on-envvars` 149 | * `"Change environment variable style" Discourse discussion 150 | <https://discuss.python.org/t/change-environment-variable-style/35180>`__ 151 | -------------------------------------------------------------------------------- /development-tools/gdb.rst: -------------------------------------------------------------------------------- 1 | .. _gdb: 2 | 3 | =========== 4 | GDB support 5 | =========== 6 | 7 | .. highlight:: none 8 | 9 | Page moved 10 | ========== 11 | 12 | Information on debugging CPython using GDB is now in the main Python 13 | documentation, since it is relevant for C extension modules as well. 14 | Please read it first: :ref:`python:gdb` 15 | 16 | 17 | CPython tips 18 | ============ 19 | 20 | This document includes a few additional tips that are useful specifically for 21 | debugging CPython internals. 22 | 23 | 24 | Breaking at labels 25 | ------------------ 26 | 27 | You will most often set breakpoints at the start of functions, but 28 | this approach is less helpful when debugging the runtime virtual 29 | machine, since the main interpreter loop function, 30 | ``_PyEval_EvalFrameDefault``, is well over 4,000 lines long as of Python 3.12. 31 | Fortunately, among the `many ways to set breakpoints 32 | <https://sourceware.org/gdb/current/onlinedocs/gdb.html/Location-Specifications.html>`_, 33 | you can break at C labels, such as those generated for computed gotos. 34 | If you are debugging an interpreter compiled with computed goto support 35 | (generally true, certainly when using GCC), each instruction will be 36 | prefaced with a label named ``TARGET_<instruction>``, for example, 37 | ``TARGET_LOAD_CONST``. You can then set a breakpoint with a command 38 | like:: 39 | 40 | (gdb) break ceval.c:_PyEval_EvalFrameDefault:TARGET_LOAD_CONST 41 | 42 | Add commands, save to a file, then reload in future sessions without 43 | worrying that the starting line number of individual instructions 44 | change over time. 45 | 46 | Saving and loading breakpoints 47 | ------------------------------ 48 | 49 | With extended exposure to particular parts of the Python runtime, you 50 | might find it helpful to define a routine set of breakpoints and 51 | commands to execute when they are hit. 52 | For convenience, save your breakpoints to a file and load them in future 53 | sessions using the ``save breakpoints`` command:: 54 | 55 | (gdb) save breakpoints python.brk 56 | 57 | You can edit the file to your heart's content, then load it in a later 58 | session:: 59 | 60 | (gdb) source python.brk 61 | -------------------------------------------------------------------------------- /development-tools/index.rst: -------------------------------------------------------------------------------- 1 | .. _development-tools: 2 | 3 | ================= 4 | Development tools 5 | ================= 6 | 7 | .. toctree:: 8 | :maxdepth: 5 9 | 10 | clinic 11 | gdb 12 | clang 13 | warnings 14 | -------------------------------------------------------------------------------- /development-tools/warnings.rst: -------------------------------------------------------------------------------- 1 | .. warnings: 2 | 3 | Tools for tracking compiler warnings 4 | ==================================== 5 | 6 | .. highlight:: bash 7 | 8 | The compiler warning tracking tooling is intended to alert developers about new 9 | compiler warnings introduced by their contributions. The tooling consists of 10 | a Python script which is ran by the following GitHub workflows: 11 | 12 | * Ubuntu/build and test (:cpy-file:`.github/workflows/reusable-ubuntu.yml`) 13 | * macOS/build and test (:cpy-file:`.github/workflows/reusable-macos.yml`) 14 | 15 | You can check the documentation for the :cpy-file:`Tools/build/check_warnings.py` tool 16 | by running:: 17 | 18 | python Tools/build/check_warnings.py --help 19 | 20 | The script can be run locally by providing the compiler output file 21 | (where the output is saved) and the compiler output type 22 | (either ``gcc`` or ``clang``) to see a list of unique warnings:: 23 | 24 | python Tools/build/check_warnings.py --compiler-output-file-path=compiler_output.txt --compiler-output-type=gcc 25 | 26 | .. _warning-check-failure: 27 | 28 | What to do if a warning check fails GitHub CI 29 | --------------------------------------------- 30 | 31 | The :cpy-file:`Tools/build/check_warnings.py` tool will fail if the compiler generates 32 | more or less warnings than expected for a given source file as defined in the 33 | platform-specific warning ignore file. The warning ignore file is either 34 | :cpy-file:`Tools/build/.warningignore_ubuntu` or 35 | :cpy-file:`Tools/build/.warningignore_macos` depending on the platform. 36 | 37 | If a warning check fails with: 38 | 39 | * Unexpected warnings 40 | * Attempt to refactor the code to avoid the warning. 41 | * If it is not possible to avoid the warning document in the PR why it is 42 | reasonable to ignore and add the warning to the platform-specific 43 | warning ignore file. If the file exists in the warning ignore file 44 | increment the count by the number of newly introduced warnings. 45 | * Unexpected improvements (less warnings) 46 | * Document in the PR that the change reduces the number of compiler 47 | warnings. Decrement the count in the platform-specific warning 48 | ignore file or remove the file if the count is now zero. 49 | 50 | .. _updating-warning-ignore-file: 51 | 52 | Updating the warning ignore file 53 | -------------------------------- 54 | 55 | The warning ignore files can be found in the :cpy-file:`Tools/build/` directory. 56 | Both files and directories can be added to the ignore file. Files can have an explicit warning count or a wildcard count. 57 | Directories must be followed by a wildcard count. Wildcards indicate that 0 or more warnings will be ignored. 58 | The following is an example of the warning ignore file format:: 59 | 60 | Modules/_ctypes/_ctypes_test_generated.c.h * 61 | Objects/longobject.c 46 62 | Objects/methodobject.c 1 63 | Objects/mimalloc/ * 64 | 65 | Using wildcards is reserved for code that is not maintained by CPython, or code that is for tests. 66 | Keep lines in warning ignore files sorted lexicographically. 67 | -------------------------------------------------------------------------------- /documentation/devguide.rst: -------------------------------------------------------------------------------- 1 | .. _devguide: 2 | 3 | ================================== 4 | Helping with the Developer's Guide 5 | ================================== 6 | 7 | .. raw:: html 8 | 9 | <script> 10 | document.addEventListener('DOMContentLoaded', function() { 11 | activateTab(getOS()); 12 | }); 13 | </script> 14 | 15 | .. highlight:: console 16 | 17 | The Developer's Guide (what you're reading now) uses the same process as the 18 | main Python documentation, except for some small differences. The source 19 | lives in a `separate repository`_ and bug reports should be submitted to the 20 | `devguide GitHub tracker`_. 21 | 22 | Changes to the Developer's Guide are published when pull requests are merged. 23 | 24 | Changes to the Python documentation are published regularly, 25 | ususally within 48 hours of the change being committed. 26 | The documentation is also `published for each release <https://docs.python.org/release/>`_, 27 | which may also be used by redistributors. 28 | 29 | 30 | Developer's Guide workflow 31 | ========================== 32 | 33 | To submit a :ref:`pull request <pullrequest>`, you can fork the 34 | `devguide repo`_ to your GitHub account and clone it using:: 35 | 36 | $ git clone https://github.com/<your_username>/devguide 37 | 38 | For your PR to be accepted, you will also need to sign the 39 | :ref:`contributor agreement <cla>`. 40 | 41 | To build the devguide, some additional dependencies are required (most 42 | importantly, `Sphinx`_), and the standard way to install dependencies in 43 | Python projects is to create a virtualenv, and then install dependencies from 44 | a ``requirements.txt`` file. For your convenience, this is all *automated for 45 | you*. 46 | 47 | To build the devguide from the checkout directory: 48 | 49 | .. tab:: Unix/macOS 50 | 51 | .. code-block:: shell 52 | 53 | make html 54 | 55 | .. tab:: Windows 56 | 57 | .. code-block:: dosbatch 58 | 59 | .\make html 60 | 61 | You will find the generated files in ``_build/html``. 62 | 63 | .. tip:: * Replace ``html`` with ``htmlview`` to open the docs in a web browser 64 | once the build completes. 65 | * Replace ``html`` with ``htmllive`` to rebuild the docs, 66 | start a local server, and automatically reload the page in your 67 | browser when you make changes to reST files (Unix only). 68 | 69 | Note that ``make check`` runs automatically when you submit 70 | a :ref:`pull request <pullrequest>`. You may wish to run ``make check`` 71 | and ``make linkcheck`` to make sure that it runs without errors. 72 | 73 | .. _separate repository: 74 | .. _devguide repo: https://github.com/python/devguide 75 | .. _devguide GitHub tracker: https://github.com/python/devguide/issues 76 | .. _Sphinx: https://www.sphinx-doc.org/ 77 | -------------------------------------------------------------------------------- /documentation/help-documenting.rst: -------------------------------------------------------------------------------- 1 | .. _help-documenting: 2 | .. _docquality: 3 | 4 | ========================== 5 | Helping with documentation 6 | ========================== 7 | 8 | Python is known for having well-written documentation. Maintaining the 9 | documentation's accuracy and keeping a high level of quality takes a lot of 10 | effort. Community members, like you, help with writing, editing, and updating 11 | content, and these contributions are appreciated and welcomed. 12 | 13 | This high-level **Helping with Documentation** section provides: 14 | 15 | * an overview of Python's documentation 16 | * how to help with documentation issues 17 | * information on proofreading 18 | 19 | You will find extensive and detailed information on how to write documentation 20 | and submit changes on the :ref:`Documenting Python <documenting>` page. 21 | 22 | 23 | Python documentation 24 | ==================== 25 | 26 | The :ref:`Documenting Python <documenting>` section covers the details of how 27 | Python's documentation works. It includes information about the markup 28 | language used, specific formats, and style recommendations. Looking at 29 | pre-existing documentation source files can be very helpful when getting 30 | started. :ref:`How to build the documentation <building-doc>` walks you through 31 | the steps to create a draft build which lets you see how your changes will look 32 | and validates that your new markup is correct. 33 | 34 | You can view the documentation built from :ref:`in-development <indevbranch>` 35 | and :ref:`maintenance <maintbranch>` branches at https://docs.python.org/dev/. 36 | The in-development and recent maintenance branches are rebuilt once per day. 37 | 38 | If you would like to be more involved with documentation, consider subscribing 39 | to the `Documentation category on the Python Discourse 40 | <https://discuss.python.org/c/documentation/26>`_ and the 41 | `docs@python.org <https://mail.python.org/mailman3/lists/docs.python.org/>`_ mailing list 42 | where user issues are raised and documentation toolchain, projects, and standards 43 | are discussed. 44 | 45 | 46 | Helping with documentation issues 47 | ================================= 48 | 49 | If you look at `documentation issues`_ on the `issue tracker`_, you 50 | will find various documentation problems that may need work. Issues vary from 51 | typos to unclear documentation and items lacking documentation. 52 | 53 | If you see a documentation issue that you would like to tackle, you can: 54 | 55 | * check to see if there is pull request icon to the right of the issue's title, 56 | or an open pull request listed under :guilabel:`Linked PRs` in the issue body. 57 | If there is, then someone has already created a pull 58 | request for the issue. 59 | * leave a comment on the issue saying you are going to try and create a pull 60 | request and roughly how long you think you will take to do so (this allows 61 | others to take on the issue if you happen to forget or lose interest). 62 | * submit a :ref:`pull request <pullrequest>` for the issue. 63 | 64 | By following the steps in the :ref:`Quick Guide to Pull Requests <pullrequest-quickguide>`, 65 | you will learn the workflow for documentation pull requests. 66 | 67 | .. _documentation issues: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocs 68 | .. _octocat: https://github.com/logos 69 | 70 | 71 | Proofreading 72 | ============ 73 | 74 | While an issue filed on the `issue tracker`_ means there is a known issue 75 | somewhere, that does not mean there are not other issues lurking about in the 76 | documentation. Proofreading a part of the documentation, such as a "How to" or 77 | OS specific document, can often uncover problems (for example, documentation that 78 | needs updating for Python 3). 79 | 80 | If you decide to proofread, read a section of the documentation from start 81 | to finish, filing issues in the issue tracker for each major type of problem 82 | you find. Simple typos don't require issues of their own, but, instead, submit 83 | a pull request directly. It's best to avoid filing a single issue for an entire 84 | section containing multiple problems; instead, file several issues so that it 85 | is easier to break the work up for multiple people and more efficient review. 86 | 87 | For help with the finer points of English technical writing, mention the 88 | `@python/proofreaders <https://github.com/orgs/python/teams/proofreaders>`__ 89 | team in your issue or pull request in any `@python <https://github.com/python/>`__ 90 | repo. If you'd like to join the team, 91 | `open a core-workflow issue <https://github.com/python/core-workflow/issues/new/choose>`__ 92 | similar to 93 | `python/core-workflow#461 <https://github.com/python/core-workflow/issues/461>`__. 94 | 95 | .. _issue tracker: https://github.com/python/cpython/issues 96 | -------------------------------------------------------------------------------- /documentation/index.rst: -------------------------------------------------------------------------------- 1 | ============= 2 | Documentation 3 | ============= 4 | 5 | .. toctree:: 6 | :maxdepth: 5 7 | 8 | start-documenting 9 | help-documenting 10 | style-guide 11 | markup 12 | translating 13 | devguide 14 | -------------------------------------------------------------------------------- /documentation/start-documenting.rst: -------------------------------------------------------------------------------- 1 | .. _start-documenting: 2 | .. _documenting: 3 | 4 | =============== 5 | Getting started 6 | =============== 7 | 8 | .. raw:: html 9 | 10 | <script> 11 | document.addEventListener('DOMContentLoaded', function() { 12 | activateTab(getOS()); 13 | }); 14 | </script> 15 | 16 | .. highlight:: rest 17 | 18 | The Python language has a substantial body of documentation, much of it 19 | contributed by various authors. The markup used for the Python documentation is 20 | `reStructuredText`_, developed by the `docutils`_ project, amended by custom 21 | directives and using a toolset named `Sphinx`_ to post-process the HTML output. 22 | 23 | The documentation in HTML, PDF or EPUB format is generated from text files 24 | written using the :ref:`reStructuredText format <markup>` and contained in the 25 | :ref:`CPython Git repository <setup>`. 26 | 27 | .. _reStructuredText: https://docutils.sourceforge.io/rst.html 28 | 29 | .. note:: 30 | 31 | If you're interested in contributing to Python's documentation, there's no 32 | need to write reStructuredText if you're not so inclined; plain text 33 | contributions are more than welcome as well. Send an e-mail to 34 | docs@python.org or open an issue on the :ref:`tracker <reporting-bugs>`. 35 | 36 | 37 | Introduction 38 | ============ 39 | 40 | Python's documentation has long been considered to be good for a free 41 | programming language. There are a number of reasons for this, the most 42 | important being the early commitment of Python's creator, Guido van Rossum, to 43 | providing documentation on the language and its libraries, and the continuing 44 | involvement of the user community in providing assistance for creating and 45 | maintaining documentation. 46 | 47 | The involvement of the community takes many forms, from authoring to bug reports 48 | to just plain complaining when the documentation could be more complete or 49 | easier to use. 50 | 51 | This section is aimed at authors and potential authors of documentation for 52 | Python. More specifically, it is for people contributing to the standard 53 | documentation and developing additional documents using the same tools as the 54 | standard documents. This guide will be less useful for authors using the Python 55 | documentation tools for topics other than Python, and less useful still for 56 | authors not using the tools at all. 57 | 58 | If your interest is in contributing to the Python documentation, but you don't 59 | have the time or inclination to learn reStructuredText and the markup structures 60 | documented here, there's a welcoming place for you among the Python contributors 61 | as well. Any time you feel that you can clarify existing documentation or 62 | provide documentation that's missing, the existing documentation team will 63 | gladly work with you to integrate your text, dealing with the markup for you. 64 | Please don't let the material in this section stand between the documentation 65 | and your desire to help out! 66 | 67 | 68 | .. _building-doc: 69 | 70 | Building the documentation 71 | ========================== 72 | 73 | .. highlight:: bash 74 | 75 | To build the documentation, follow the steps in one of the sections below. 76 | You can view the documentation after building the HTML 77 | by opening the file :file:`Doc/build/html/index.html` in a web browser. 78 | 79 | .. note:: 80 | 81 | The following instructions all assume your current working dir is 82 | the ``Doc`` subdirectory in your :ref:`CPython repository clone <checkout>`. 83 | Make sure to switch to it with ``cd Doc`` if necessary. 84 | 85 | 86 | .. _doc-create-venv: 87 | 88 | Create a virtual environment 89 | ---------------------------- 90 | 91 | .. _doc-create-venv-unix: 92 | .. _doc-create-venv-windows: 93 | 94 | You can create a new :mod:`venv` with the required dependencies using: 95 | 96 | .. tab:: Unix/macOS 97 | 98 | .. code-block:: shell 99 | 100 | make venv 101 | 102 | Building the docs with :program:`make` will automatically use this environment 103 | without you having to activate it. 104 | 105 | .. tab:: Windows 106 | 107 | `Create a new virtual environment <venv-create_>`__ manually. 108 | Always be sure to `activate this environment <venv-activate_>`__ 109 | before building the documentation. 110 | 111 | 112 | .. _building-using-make: 113 | .. _using-make-make-bat: 114 | .. _doc-build-make: 115 | 116 | Build using make / make.bat 117 | --------------------------- 118 | 119 | .. tab:: Unix/macOS 120 | 121 | A Unix ``Makefile`` is provided, :cpy-file:`Doc/Makefile`. 122 | 123 | .. tab:: Windows 124 | 125 | A Windows ``make.bat`` is provided, :cpy-file:`Doc/make.bat`, which 126 | attempts to emulate the Unix ``Makefile`` as closely as practical. 127 | 128 | .. important:: 129 | 130 | The Windows ``make.bat`` batch file lacks a ``make venv`` target. 131 | Instead, it automatically installs any missing dependencies 132 | into the currently activated environment (or the base Python, if none). 133 | Make sure the environment you :ref:`created above <doc-create-venv-windows>` 134 | is `activated <venv-activate_>`__ before running ``make.bat``. 135 | 136 | To build the docs as HTML, run: 137 | 138 | .. tab:: Unix/macOS 139 | 140 | .. code-block:: shell 141 | 142 | make html 143 | 144 | .. tab:: Windows 145 | 146 | .. code-block:: dosbatch 147 | 148 | .\make html 149 | 150 | .. tip:: * Replace ``html`` with ``htmlview`` to open the docs in a web browser 151 | once the build completes. 152 | * Replace ``html`` with ``htmllive`` to rebuild the docs, 153 | start a local server, and automatically reload the page in your 154 | browser when you make changes to reST files (Unix only). 155 | 156 | To check the docs for common errors with `Sphinx Lint`_ 157 | (which is run on all :ref:`pull requests <pullrequest>`), use: 158 | 159 | .. tab:: Unix/macOS 160 | 161 | .. code-block:: shell 162 | 163 | make check 164 | 165 | .. tab:: Windows 166 | 167 | .. code-block:: dosbatch 168 | 169 | .\make check 170 | 171 | To list other supported :program:`make` targets, run: 172 | 173 | .. tab:: Unix/macOS 174 | 175 | .. code-block:: shell 176 | 177 | make help 178 | 179 | .. tab:: Windows 180 | 181 | .. code-block:: dosbatch 182 | 183 | .\make help 184 | 185 | See :cpy-file:`Doc/README.rst` for more information. 186 | 187 | 188 | .. _using-sphinx-build: 189 | .. _doc-build-sphinx: 190 | 191 | Build using Sphinx directly 192 | --------------------------- 193 | 194 | Advanced users may want to invoke Sphinx directly, 195 | to pass specialized options or to handle specific use cases. 196 | 197 | Make sure the environment you :ref:`created above <doc-create-venv-windows>` 198 | is `activated <venv-activate_>`__. 199 | Then, install the documentation requirements, :cpy-file:`Doc/requirements.txt`. 200 | Using pip:: 201 | 202 | python -m pip install --upgrade -r requirements.txt 203 | 204 | Finally, directly invoke Sphinx with:: 205 | 206 | python -m sphinx -b html . build/html 207 | 208 | To use a different `Sphinx builder`_, 209 | replace ``html`` above with the desired builder ``name``. 210 | 211 | 212 | .. _docutils: https://docutils.sourceforge.io/ 213 | .. _Sphinx: https://www.sphinx-doc.org/ 214 | .. _Sphinx builder: https://www.sphinx-doc.org/en/master/usage/builders/index.html 215 | .. _Sphinx Lint: https://github.com/sphinx-contrib/sphinx-lint 216 | .. _venv-activate: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment 217 | .. _venv-create: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment 218 | -------------------------------------------------------------------------------- /getting-started/fixing-issues.rst: -------------------------------------------------------------------------------- 1 | .. _fixing-issues: 2 | .. _fixingissues: 3 | 4 | ================================= 5 | Fixing "easy" issues (and beyond) 6 | ================================= 7 | 8 | When you feel comfortable enough to want to help tackle issues by trying to 9 | create a pull request to fix an issue, you can start by looking at the `"easy" 10 | issues`_. These issues *should* be ones where it should take no longer than a 11 | day or weekend to fix. But because the "easy" classification is typically done 12 | at triage time it can turn out to be inaccurate, so do feel free to leave a 13 | comment if you think the classification no longer applies. 14 | 15 | For the truly adventurous looking for a challenge, you can look for issues that 16 | are not considered easy and try to fix those. It must be warned, though, that 17 | it is quite possible that a bug that has been left open has been left into that 18 | state because of the difficulty compared to the benefit of the fix. It could 19 | also still be open because no consensus has been reached on how to fix the 20 | issue, although having a pull request that proposes a fix can turn the tides of the 21 | discussion to help bring it to a close. Regardless of why the issue is open, 22 | you can also always provide useful comments if you do attempt a fix, successful 23 | or not. 24 | 25 | .. _"easy" issues: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Aeasy 26 | -------------------------------------------------------------------------------- /getting-started/generative-ai.rst: -------------------------------------------------------------------------------- 1 | .. _generative-ai: 2 | 3 | ============= 4 | Generative AI 5 | ============= 6 | 7 | Generative AI has evolved rapidly over the past decade and will continue in the future. 8 | Using generative AI and large language models (LLMs) can be helpful tools for contributors. 9 | Their overuse can also be problematic, such as generation of incorrect code, inaccurate documentation, and unneeded code churn. 10 | Discretion, good judgement, and critical thinking **must** be used when opening issues and pull requests. 11 | 12 | Acceptable uses 13 | =============== 14 | 15 | Some of the acceptable uses of generative AI include: 16 | 17 | - Assistance with writing comments, especially in a non-native language 18 | - Gaining understanding of existing code 19 | - Supplementing contributor knowledge for code, tests, and documentation 20 | 21 | Unacceptable uses 22 | ================= 23 | 24 | Maintainers may close issues and PRs that are not useful or productive, including 25 | those that are fully generated by AI. If a contributor repeatedly opens unproductive 26 | issues or PRs, they may be blocked. 27 | -------------------------------------------------------------------------------- /getting-started/getting-help.rst: -------------------------------------------------------------------------------- 1 | .. _getting-help: 2 | .. _help: 3 | 4 | Where to get help 5 | ================= 6 | 7 | If you are working on Python it is very possible you will come across an issue 8 | where you need some assistance to solve it (this happens to core developers 9 | all the time). 10 | 11 | Should you require help, there are a :ref:`variety of options available 12 | <communication>` to seek assistance. If the question involves process or tool 13 | usage then please check the rest of this guide first as it should answer your 14 | question. 15 | 16 | 17 | .. _help-discourse: 18 | 19 | Discourse 20 | --------- 21 | 22 | Python has a hosted Discourse instance at `discuss.python.org <Discourse_>`_. 23 | This forum has many different categories, 24 | most of which are open for all users to read and post. 25 | Those particularly relevant for help contributing to Python itself include: 26 | 27 | * `Core Development`_ for most general questions and help 28 | * `Ideas`_ to discuss new ideas for the Python language 29 | * `Core Workflow`_ for questions about the dev infrastructure and bots 30 | 31 | .. seealso:: 32 | :ref:`communication-discourse` for more information on how to get started. 33 | 34 | .. _Discourse: https://discuss.python.org/ 35 | .. _Core Development: https://discuss.python.org/c/core-dev/23 36 | .. _Core Workflow: https://discuss.python.org/c/core-workflow/8 37 | .. _Ideas: https://discuss.python.org/c/ideas/6 38 | 39 | 40 | Ask #python-dev 41 | --------------- 42 | 43 | If you are comfortable with IRC you can try asking on ``#python-dev`` (on 44 | the `Libera.Chat`_ network). Typically there are a number of experienced 45 | developers, ranging from triagers to core developers, who can answer 46 | questions about developing for Python. As with the mailing lists, 47 | ``#python-dev`` is for questions involving the development *of* Python 48 | whereas ``#python`` is for questions concerning development *with* Python. 49 | 50 | .. note:: 51 | 52 | You may not be able to access the history of this channel, so it cannot 53 | be used as a "knowledge base" of sorts. 54 | 55 | .. _Libera.Chat: https://libera.chat/ 56 | 57 | Core mentorship 58 | --------------- 59 | 60 | If you are interested in improving Python and contributing to its development, 61 | but don’t yet feel entirely comfortable with the public channels mentioned 62 | above, `Python Mentors`_ are here to help you. Python is fortunate to have a 63 | community of volunteer core developers willing to mentor anyone wishing to 64 | contribute code, work on bug fixes or improve documentation. Everyone is 65 | welcomed and encouraged to contribute. 66 | 67 | .. _Python Mentors: https://www.python.org/dev/core-mentorship/ 68 | 69 | 70 | File a bug 71 | ---------- 72 | 73 | If you strongly suspect you have stumbled on a bug (be it in the build 74 | process, in the test suite, or in other areas), then open an issue on the 75 | `issue tracker`_. As with every bug report it is strongly advised that 76 | you detail which conditions triggered it (including the OS name and version, 77 | and what you were trying to do), as well as the exact error message you 78 | encountered. 79 | 80 | .. _issue tracker: https://github.com/python/cpython/issues 81 | -------------------------------------------------------------------------------- /getting-started/index.rst: -------------------------------------------------------------------------------- 1 | .. _getting-started: 2 | 3 | =============== 4 | Getting started 5 | =============== 6 | 7 | .. toctree:: 8 | :maxdepth: 5 9 | 10 | setup-building 11 | fixing-issues 12 | git-boot-camp 13 | pull-request-lifecycle 14 | getting-help 15 | generative-ai 16 | -------------------------------------------------------------------------------- /include/release-cycle.json: -------------------------------------------------------------------------------- 1 | { 2 | "3.15": { 3 | "branch": "main", 4 | "pep": 790, 5 | "status": "feature", 6 | "first_release": "2026-10-01", 7 | "end_of_life": "2031-10", 8 | "release_manager": "Hugo van Kemenade" 9 | }, 10 | "3.14": { 11 | "branch": "3.14", 12 | "pep": 745, 13 | "status": "prerelease", 14 | "first_release": "2025-10-07", 15 | "end_of_life": "2030-10", 16 | "release_manager": "Hugo van Kemenade" 17 | }, 18 | "3.13": { 19 | "branch": "3.13", 20 | "pep": 719, 21 | "status": "bugfix", 22 | "first_release": "2024-10-07", 23 | "end_of_life": "2029-10", 24 | "release_manager": "Thomas Wouters" 25 | }, 26 | "3.12": { 27 | "branch": "3.12", 28 | "pep": 693, 29 | "status": "security", 30 | "first_release": "2023-10-02", 31 | "end_of_life": "2028-10", 32 | "release_manager": "Thomas Wouters" 33 | }, 34 | "3.11": { 35 | "branch": "3.11", 36 | "pep": 664, 37 | "status": "security", 38 | "first_release": "2022-10-24", 39 | "end_of_life": "2027-10", 40 | "release_manager": "Pablo Galindo Salgado" 41 | }, 42 | "3.10": { 43 | "branch": "3.10", 44 | "pep": 619, 45 | "status": "security", 46 | "first_release": "2021-10-04", 47 | "end_of_life": "2026-10", 48 | "release_manager": "Pablo Galindo Salgado" 49 | }, 50 | "3.9": { 51 | "branch": "3.9", 52 | "pep": 596, 53 | "status": "security", 54 | "first_release": "2020-10-05", 55 | "end_of_life": "2025-10", 56 | "release_manager": "Łukasz Langa" 57 | }, 58 | "3.8": { 59 | "branch": "3.8", 60 | "pep": 569, 61 | "status": "end-of-life", 62 | "first_release": "2019-10-14", 63 | "end_of_life": "2024-10-07", 64 | "release_manager": "Łukasz Langa" 65 | }, 66 | "3.7": { 67 | "branch": "3.7", 68 | "pep": 537, 69 | "status": "end-of-life", 70 | "first_release": "2018-06-27", 71 | "end_of_life": "2023-06-27", 72 | "release_manager": "Ned Deily" 73 | }, 74 | "3.6": { 75 | "branch": "3.6", 76 | "pep": 494, 77 | "status": "end-of-life", 78 | "first_release": "2016-12-23", 79 | "end_of_life": "2021-12-23", 80 | "release_manager": "Ned Deily" 81 | }, 82 | "3.5": { 83 | "branch": "3.5", 84 | "pep": 478, 85 | "status": "end-of-life", 86 | "first_release": "2015-09-13", 87 | "end_of_life": "2020-09-30", 88 | "release_manager": "Larry Hastings" 89 | }, 90 | "3.4": { 91 | "branch": "3.4", 92 | "pep": 429, 93 | "status": "end-of-life", 94 | "first_release": "2014-03-16", 95 | "end_of_life": "2019-03-18", 96 | "release_manager": "Larry Hastings" 97 | }, 98 | "3.3": { 99 | "branch": "3.3", 100 | "pep": 398, 101 | "status": "end-of-life", 102 | "first_release": "2012-09-29", 103 | "end_of_life": "2017-09-29", 104 | "release_manager": "Georg Brandl, Ned Deily (3.3.7+)" 105 | }, 106 | "3.2": { 107 | "branch": "3.2", 108 | "pep": 392, 109 | "status": "end-of-life", 110 | "first_release": "2011-02-20", 111 | "end_of_life": "2016-02-20", 112 | "release_manager": "Georg Brandl" 113 | }, 114 | "2.7": { 115 | "branch": "2.7", 116 | "pep": 373, 117 | "status": "end-of-life", 118 | "first_release": "2010-07-03", 119 | "end_of_life": "2020-01-01", 120 | "release_manager": "Benjamin Peterson" 121 | }, 122 | "3.1": { 123 | "branch": "3.1", 124 | "pep": 375, 125 | "status": "end-of-life", 126 | "first_release": "2009-06-27", 127 | "end_of_life": "2012-04-09", 128 | "release_manager": "Benjamin Peterson" 129 | }, 130 | "3.0": { 131 | "branch": "3.0", 132 | "pep": 361, 133 | "status": "end-of-life", 134 | "first_release": "2008-12-03", 135 | "end_of_life": "2009-06-27", 136 | "release_manager": "Barry Warsaw" 137 | }, 138 | "2.6": { 139 | "branch": "2.6", 140 | "pep": 361, 141 | "status": "end-of-life", 142 | "first_release": "2008-10-01", 143 | "end_of_life": "2013-10-29", 144 | "release_manager": "Barry Warsaw" 145 | } 146 | } 147 | -------------------------------------------------------------------------------- /internals/compiler.rst: -------------------------------------------------------------------------------- 1 | .. _compiler: 2 | 3 | =============== 4 | Compiler design 5 | =============== 6 | 7 | .. highlight:: none 8 | 9 | This document is now part of the 10 | `CPython Internals Docs <https://github.com/python/cpython/blob/main/InternalDocs/compiler.md>`_. 11 | -------------------------------------------------------------------------------- /internals/exploring.rst: -------------------------------------------------------------------------------- 1 | .. _exploring: 2 | 3 | =================== 4 | CPython source code 5 | =================== 6 | 7 | This section gives an overview of CPython's code structure and provides 8 | a summary of file locations for modules and built-ins. 9 | 10 | 11 | Source code layout 12 | ================== 13 | 14 | For a Python :term:`module`, the typical layout is: 15 | 16 | * :file:`Lib/{<module>}.py` 17 | * :file:`Modules/_{<module>}.c` (if there's also a C accelerator module) 18 | * :file:`Lib/test/test_{<module>}.py` 19 | * :file:`Doc/library/{<module>}.rst` 20 | 21 | For an :term:`extension module`, the typical layout is: 22 | 23 | * :file:`Modules/{<module>}module.c` 24 | * :file:`Lib/test/test_{<module>}.py` 25 | * :file:`Doc/library/{<module>}.rst` 26 | 27 | For :ref:`bltin-types`, the typical layout is: 28 | 29 | * :file:`Objects/{<builtin>}object.c` 30 | * :file:`Lib/test/test_{<builtin>}.py` 31 | * :cpy-file:`Doc/library/stdtypes.rst` 32 | 33 | For :ref:`built-in-funcs`, the typical layout is: 34 | 35 | * :cpy-file:`Python/bltinmodule.c` 36 | * :cpy-file:`Lib/test/test_builtin.py` 37 | * :cpy-file:`Doc/library/functions.rst` 38 | 39 | Some exceptions to these layouts are: 40 | 41 | * built-in type ``int`` is at :cpy-file:`Objects/longobject.c` 42 | * built-in type ``str`` is at :cpy-file:`Objects/unicodeobject.c` 43 | * built-in module ``sys`` is at :cpy-file:`Python/sysmodule.c` 44 | * built-in module ``marshal`` is at :cpy-file:`Python/marshal.c` 45 | * Windows-only module ``winreg`` is at :cpy-file:`PC/winreg.c` 46 | 47 | 48 | Additional references 49 | ===================== 50 | 51 | The CPython code base is constantly changing and evolving. 52 | Here's a sample of references about CPython's architecture aimed at 53 | building your understanding of CPython internals and its evolution: 54 | 55 | .. csv-table:: **Current references** 56 | :header: "Title", "Brief", "Author", "Version" 57 | :widths: 50, 50, 20, 5 58 | 59 | "`A guide from parser to objects, observed using GDB`_", "Code walk from Parser, AST, Sym Table and Objects", Louie Lu, 3.7.a0 60 | "`Green Tree Snakes`_", "The missing Python AST docs", Thomas Kluyver, 3.6 61 | "`Yet another guided tour of CPython`_", "A guide for how CPython REPL works", Guido van Rossum, 3.5 62 | "`Python Asynchronous I/O Walkthrough`_", "How CPython async I/O, generator and coroutine works", Philip Guo, 3.5 63 | "`Coding Patterns for Python Extensions`_", "Reliable patterns of coding Python Extensions in C", Paul Ross, 3.9+ 64 | "`Your Guide to the CPython Source Code`_", "Your Guide to the CPython Source Code", Anthony Shaw, 3.8 65 | 66 | .. csv-table:: **Historical references** 67 | :header: "Title", "Brief", "Author", "Version" 68 | :widths: 50, 50, 20, 5 69 | 70 | "`Python's Innards Series`_", "ceval, objects, pystate and miscellaneous topics", Yaniv Aknin, 3.1 71 | "`Eli Bendersky's Python Internals`_", "Objects, Symbol tables and miscellaneous topics", Eli Bendersky, 3.x 72 | "`A guide from parser to objects, observed using Eclipse`_", "Code walk from Parser, AST, Sym Table and Objects", Prashanth Raghu, 2.7.12 73 | "`CPython internals: A ten-hour codewalk through the Python interpreter source code`_", "Code walk from source code to generators", Philip Guo, 2.7.8 74 | 75 | 76 | .. _A guide from parser to objects, observed using GDB: https://hackmd.io/s/ByMHBMjFe 77 | 78 | .. _Green Tree Snakes: https://greentreesnakes.readthedocs.io/en/latest/ 79 | 80 | .. _Yet another guided tour of CPython: https://paper.dropbox.com/doc/Yet-another-guided-tour-of-CPython-XY7KgFGn88zMNivGJ4Jzv 81 | 82 | .. _Python Asynchronous I/O Walkthrough: https://www.youtube.com/playlist?list=PLpEcQSRWP2IjVRlTUptdD05kG-UkJynQT 83 | 84 | .. _Coding Patterns for Python Extensions: https://pythonextensionpatterns.readthedocs.io/en/latest/ 85 | 86 | .. _Your Guide to the CPython Source Code: https://realpython.com/cpython-source-code-guide/ 87 | 88 | .. _Python's Innards Series: https://tech.blog.aknin.name/category/my-projects/pythons-innards/ 89 | 90 | .. _Eli Bendersky's Python Internals: https://eli.thegreenplace.net/tag/python-internals 91 | 92 | .. _A guide from parser to objects, observed using Eclipse: https://docs.google.com/document/d/1nzNN1jeNCC_bg1LADCvtTuGKvcyMskV1w8Ad2iLlwoI/ 93 | 94 | .. _CPython internals\: A ten-hour codewalk through the Python interpreter source code: https://www.youtube.com/playlist?list=PLzV58Zm8FuBL6OAv1Yu6AwXZrnsFbbR0S 95 | -------------------------------------------------------------------------------- /internals/garbage-collector.rst: -------------------------------------------------------------------------------- 1 | .. _garbage-collector: 2 | .. _gc: 3 | .. _garbage_collector: 4 | 5 | ======================== 6 | Garbage collector design 7 | ======================== 8 | 9 | .. highlight:: none 10 | 11 | This document is now part of the 12 | `CPython Internals Docs <https://github.com/python/cpython/blob/main/InternalDocs/garbage_collector.md>`_. 13 | -------------------------------------------------------------------------------- /internals/index.rst: -------------------------------------------------------------------------------- 1 | .. _internals: 2 | 3 | =================== 4 | CPython's internals 5 | =================== 6 | 7 | This guide describes the basics of CPython's internals. 8 | It explains the layout of CPython's source code. 9 | It also explains how the parser, compiler, and interpreter 10 | work together to run your Python code. 11 | Finally, it covers the garbage collector and how it manages memory. 12 | 13 | .. toctree:: 14 | :maxdepth: 3 15 | 16 | exploring 17 | parser 18 | compiler 19 | interpreter 20 | garbage-collector 21 | -------------------------------------------------------------------------------- /internals/interpreter.rst: -------------------------------------------------------------------------------- 1 | .. _interpreter: 2 | 3 | ======================== 4 | The bytecode interpreter 5 | ======================== 6 | 7 | This document is now part of the 8 | `CPython Internals Docs <https://github.com/python/cpython/blob/main/InternalDocs/interpreter.md>`_. 9 | -------------------------------------------------------------------------------- /internals/parser.rst: -------------------------------------------------------------------------------- 1 | .. _parser: 2 | 3 | =================== 4 | Guide to the parser 5 | =================== 6 | 7 | .. highlight:: none 8 | 9 | This document is now part of the 10 | `CPython Internals Docs <https://github.com/python/cpython/blob/main/InternalDocs/parser.md>`_. 11 | -------------------------------------------------------------------------------- /links.rst: -------------------------------------------------------------------------------- 1 | .. Links for use anywhere. Include this file to use them. 2 | 3 | .. _issue tracker: https://github.com/python/cpython/issues 4 | 5 | .. _clang: https://clang.llvm.org/ 6 | .. _ccache: https://ccache.dev/ 7 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | REM Command file for Sphinx documentation 4 | 5 | setlocal 6 | 7 | pushd %~dp0 8 | 9 | if "%PYTHON%" == "" ( 10 | set PYTHON=py -3 11 | ) 12 | 13 | set BUILDDIR=_build 14 | set SPHINXOPTS=--fail-on-warning 15 | set _ALL_SPHINX_OPTS=%SPHINXOPTS% 16 | 17 | if "%1" == "check" goto check 18 | 19 | if "%1" == "" goto help 20 | if "%1" == "help" ( 21 | :help 22 | echo.Please use `make ^<target^>` where ^<target^> is one of 23 | echo. html to make standalone HTML files 24 | echo. htmlview to open the index page built by the html target in your browser 25 | echo. dirhtml to make HTML files named index.html in directories 26 | echo. singlehtml to make a single large HTML file 27 | echo. pickle to make pickle files 28 | echo. json to make JSON files 29 | echo. htmlhelp to make HTML files and a HTML help project 30 | echo. qthelp to make HTML files and a qthelp project 31 | echo. devhelp to make HTML files and a Devhelp project 32 | echo. epub to make an epub 33 | echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter 34 | echo. text to make text files 35 | echo. man to make manual pages 36 | echo. changes to make an overview over all changed/added/deprecated items 37 | echo. linkcheck to check all external links for integrity 38 | echo. doctest to run all doctests embedded in the documentation if enabled 39 | echo. check to check for stylistic and formal issues using sphinx-lint 40 | goto end 41 | ) 42 | 43 | if "%1" == "clean" ( 44 | for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i 45 | del /q /s %BUILDDIR%\* 46 | goto end 47 | ) 48 | 49 | if "%1" == "versions" ( 50 | %PYTHON% _tools/generate_release_cycle.py 51 | if errorlevel 1 exit /b 1 52 | echo. 53 | echo Release cycle data generated. 54 | goto end 55 | ) 56 | 57 | rem Targets other than "clean", "check", "help", or "" need the 58 | rem Sphinx build command, which the user may define via SPHINXBUILD. 59 | 60 | if not defined SPHINXBUILD ( 61 | rem If it is not defined, we build in a virtual environment 62 | if not exist venv ( 63 | echo. Setting up the virtual environment 64 | %PYTHON% -m venv venv 65 | echo. Installing requirements 66 | venv\Scripts\python -m pip install -r requirements.txt 67 | ) 68 | set PYTHON=venv\Scripts\python 69 | set SPHINXBUILD=venv\Scripts\sphinx-build 70 | set SPHINXAUTOBUILD=venv\Scripts\sphinx-autobuild 71 | ) 72 | 73 | if "%1" == "htmlview" ( 74 | cmd /C %this% html 75 | 76 | if EXIST "%BUILDDIR%\html\index.html" ( 77 | echo.Opening "%BUILDDIR%\html\index.html" in the default web browser... 78 | start "" "%BUILDDIR%\html\index.html" 79 | ) 80 | 81 | goto end 82 | ) 83 | 84 | if "%1" == "htmllive" ( 85 | %SPHINXAUTOBUILD% --re-ignore="/\.idea/|/venv/" --open-browser --delay 0 --port 55301 . %BUILDDIR%/html 86 | if errorlevel 1 exit /b 1 87 | goto end 88 | ) 89 | 90 | %SPHINXBUILD% -M %1 "." %BUILDDIR% %_ALL_SPHINX_OPTS% 91 | goto end 92 | 93 | :check 94 | if not defined SPHINXLINT ( 95 | rem If it is not defined, we build in a virtual environment 96 | if not exist venv ( 97 | echo. Setting up the virtual environment 98 | %PYTHON% -m venv venv 99 | echo. Installing requirements 100 | venv\Scripts\python -m pip install -r requirements.txt 101 | ) 102 | set PYTHON=venv\Scripts\python 103 | set SPHINXLINT=%PYTHON% -m sphinxlint 104 | ) 105 | 106 | rem Ignore the tools and venv dirs and check that the default role is not used. 107 | cmd /S /C "%SPHINXLINT% -i tools -i venv --enable default-role" 108 | goto end 109 | 110 | :end 111 | popd 112 | endlocal 113 | -------------------------------------------------------------------------------- /make.ps1: -------------------------------------------------------------------------------- 1 | # Command file for Sphinx documentation 2 | 3 | param ( 4 | [string]$target = "help" 5 | ) 6 | 7 | Set-StrictMode -Version 3.0 8 | $ErrorActionPreference = "Stop" 9 | 10 | $BUILDDIR = "_build" 11 | $SPHINXOPTS = "--fail-on-warning" 12 | $_ALL_SPHINX_OPTS = $SPHINXOPTS 13 | 14 | $_PYTHON = $Env:PYTHON ?? "py -3" 15 | $_SPHINX_BUILD = $Env:SPHINXBUILD ?? ".\venv\Scripts\sphinx-build" 16 | $_SPHINX_LINT = $Env:SPHINXLINT ?? ".\venv\Scripts\sphinx-lint" 17 | $_VENV_DIR = "venv" 18 | 19 | function New-VirtualEnviromnent 20 | { 21 | Write-Host "Creating venv in $_VENV_DIR" 22 | if (Get-Command "uv" -ErrorAction SilentlyContinue) { 23 | & uv venv $_VENV_DIR 24 | $Env:VIRTUAL_ENV = $_VENV_DIR 25 | & uv pip install -r requirements.txt 26 | Remove-Item Env:VIRTUAL_ENV 27 | } else { 28 | & $_PYTHON -m venv venv 29 | Write-Host "Installing requirements" 30 | & venv\Scripts\python -m pip install -r requirements.txt 31 | $Script:_PYTHON = "venv\Scripts\python" 32 | } 33 | } 34 | 35 | function Invoke-SphinxBuild 36 | { 37 | param ( 38 | [string]$BuilderName, 39 | [string]$BuildDir, 40 | [string]$Options 41 | ) 42 | if (-Not (Test-Path -Path $_VENV_DIR)) { New-VirtualEnviromnent } 43 | & $_SPHINX_BUILD -M $BuilderName "." $BuildDir $Options.Split(" ") 44 | } 45 | 46 | function Invoke-Check { 47 | if (-Not (Test-Path -Path $_VENV_DIR)) { New-VirtualEnviromnent } 48 | & $_SPHINX_LINT -i tools -i venv --enable default-role 49 | } 50 | 51 | if ($target -Eq "help") { 52 | Write-Host "Please use `make <target>` where <target> is one of" 53 | Write-Host " venv to create a venv with necessary tools" 54 | Write-Host " html to make standalone HTML files" 55 | Write-Host " linkcheck to check all external links for integrity" 56 | Write-Host " htmlview to open the index page built by the html target in your browser" 57 | Write-Host " clean to remove the venv and build files" 58 | Write-Host " check to check for stylistic and formal issues using sphinx-lint" 59 | Write-Host " versions to update release cycle after changing release-cycle.json" 60 | Exit 61 | } 62 | 63 | if ($target -Eq "clean") { 64 | $ToClean = @( 65 | $BUILDDIR, 66 | $_VENV_DIR, 67 | "include/branches.csv", "include/end-of-life.csv", 68 | "include/release-cycle.svg", "include/release-cycle-all.svg" 69 | ) 70 | foreach ($item in $ToClean) { 71 | if (Test-Path -Path $item) { 72 | Remove-Item -Path $item -Force -Recurse 73 | } 74 | } 75 | Exit $LASTEXITCODE 76 | } 77 | 78 | if ($target -Eq "check") { 79 | Invoke-Check 80 | Exit $LASTEXITCODE 81 | } 82 | 83 | if ($target -Eq "versions") { 84 | & $_PYTHON _tools/generate_release_cycle.py 85 | if ($LASTEXITCODE -Ne 0) { exit 1 } 86 | Write-Host "Release cycle data generated." 87 | Exit $LASTEXITCODE 88 | } 89 | 90 | if ($target -Eq "htmlview") { 91 | Invoke-SphinxBuild "html" "$BUILDDIR" "$_ALL_SPHINX_OPTS" 92 | if (Test-Path -Path "$BUILDDIR\html\index.html") { 93 | Write-Host "Opening $BUILDDIR\html\index.html in the default web browser..." 94 | Start-Process "$BUILDDIR\html\index.html" 95 | } 96 | Exit $LASTEXITCODE 97 | } 98 | 99 | Invoke-SphinxBuild "$target" "$BUILDDIR" "$_ALL_SPHINX_OPTS" 100 | Exit $LASTEXITCODE 101 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | furo>=2022.6.4 2 | jinja2 3 | sphinx-autobuild>=2024.9.19 4 | sphinx-inline-tabs>=2023.4.21 5 | sphinx-lint==1.0.0 6 | sphinx-notfound-page>=1.0.0 7 | sphinx_copybutton>=0.3.3 8 | sphinxext-opengraph>=0.7.1 9 | sphinxext-rediraffe 10 | Sphinx~=8.2.1 11 | -------------------------------------------------------------------------------- /testing/index.rst: -------------------------------------------------------------------------------- 1 | .. _testing: 2 | 3 | ===================== 4 | Testing and buildbots 5 | ===================== 6 | 7 | .. toctree:: 8 | :maxdepth: 5 9 | 10 | run-write-tests 11 | silence-warnings 12 | coverage 13 | buildbots 14 | new-buildbot-worker 15 | -------------------------------------------------------------------------------- /testing/silence-warnings.rst: -------------------------------------------------------------------------------- 1 | .. _silence-warnings: 2 | .. _silencewarnings: 3 | 4 | ==================================== 5 | Silence warnings from the test suite 6 | ==================================== 7 | 8 | When running Python's test suite, no warnings should result when you run it 9 | under :ref:`strenuous testing conditions <strenuous_testing>` (you can ignore 10 | the extra flags passed to ``test`` that cause randomness and parallel execution 11 | if you want). Unfortunately new warnings are added to Python on occasion which 12 | take some time to eliminate (for example, ``ResourceWarning``). Typically the easy 13 | warnings are dealt with quickly, but the more difficult ones that require some 14 | thought and work do not get fixed immediately. 15 | 16 | If you decide to tackle a warning you have found, open an issue on the `issue 17 | tracker`_ (if one has not already been opened) and say you are going to try and 18 | tackle the issue, and then proceed to fix the issue. 19 | 20 | .. _issue tracker: https://github.com/python/cpython/issues 21 | -------------------------------------------------------------------------------- /triage/github-bpo-faq.rst: -------------------------------------------------------------------------------- 1 | .. _github-bpo-faq: 2 | .. _gh-faq: 3 | 4 | =========================== 5 | GitHub issues for BPO users 6 | =========================== 7 | 8 | Here are some frequently asked questions about how to do things in 9 | GitHub issues that you used to be able to do on `bpo`_. 10 | 11 | Before you ask your own question, make sure you read :ref:`tracker` 12 | and :ref:`triaging` (specifically including :ref:`gh-labels`) as those 13 | pages include a lot of introductory material. 14 | 15 | How to format my comments nicely? 16 | ================================= 17 | 18 | There is a wonderful `beginner guide to writing and formatting on GitHub 19 | <https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github>`_. 20 | Highly recommended. 21 | 22 | One pro-tip we can sell you right here is that if you want to paste 23 | some longer log as a comment, attach a file instead (see how below). 24 | If you still insist on pasting it in your comment, do it like this:: 25 | 26 | <details> 27 | <summary>This is the summary text, click me to expand</summary> 28 | 29 | Here goes the long, long text. 30 | It will be collapsed by default! 31 | </details> 32 | 33 | How to attach files to an issue? 34 | ================================ 35 | 36 | Drag them into the comment field, wait until the file uploads, and GitHub 37 | will automatically put a link to your file in your comment text. 38 | 39 | How to link to file paths in the repository when writing comments? 40 | ================================================================== 41 | 42 | Use Markdown links. If you link to the default GitHub path, the file 43 | will link to the latest current version on the given branch. 44 | 45 | You can get a permanent link to a given revision of a given file by 46 | `pressing "y" <https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files>`_. 47 | 48 | How to do advanced searches? 49 | ============================ 50 | 51 | Use the `GitHub search syntax`_ or the interactive `advanced search`_ form 52 | that generates search queries for you. 53 | 54 | Where is the "nosy list"? 55 | ========================= 56 | 57 | Subscribe another person to the issue by tagging them in the comment with 58 | ``@username``. 59 | 60 | If you want to subscribe yourself to an issue, click the 61 | :guilabel:`🔔 Subscribe` button in the sidebar. 62 | 63 | Similarly, if you were tagged by somebody else but 64 | decided this issue is not for you, you might click the 65 | :guilabel:`🔕 Unsubscribe` button in the sidebar. 66 | 67 | There is no exact equivalent of the "nosy list" feature, so to preserve 68 | this information during the transfer, we list the previous members of 69 | this list in the first message on the migrated issue. 70 | 71 | How to add issue dependencies? 72 | ============================== 73 | 74 | Add a checkbox list like this in the issue description:: 75 | 76 | - [x] #739 77 | - [ ] https://github.com/octo-org/octo-repo/issues/740 78 | - [ ] Add delight to the experience when all tasks are complete :tada: 79 | 80 | then those will become sub-tasks on the given issue. Moreover, GitHub will 81 | automatically mark a task as complete if the other referenced issue is 82 | closed. More details in the `official GitHub documentation 83 | <https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists>`_. 84 | 85 | What on earth is a "mannequin"? 86 | =============================== 87 | 88 | For issues migrated to GitHub from `bpo`_ where the authors or commenters 89 | are not core developers, we opted not to link to their GitHub accounts 90 | directly. Users not in the `python organization on GitHub 91 | <https://github.com/orgs/python/people>`_ might not like comments to 92 | appear under their name from an automated import. Others never linked GitHub on 93 | `bpo`_ in the first place so linking their account, if any, would be impossible. 94 | 95 | In those cases a "mannequin" account is present to help follow the conversation 96 | that happened in the issue. In case the user did share their GitHub account 97 | name in their `bpo`_ profile, we use that. Otherwise, their classic `bpo`_ 98 | username is used instead. 99 | 100 | Where did the "resolution" field go? 101 | ==================================== 102 | 103 | Based on historical data we found it not being used very often. 104 | 105 | Where did the "low", "high", and "critical" priorities go? 106 | ========================================================== 107 | 108 | Based on historical data we found those not being used very often. 109 | 110 | How to find a random issue? 111 | =========================== 112 | 113 | This is not supported by GitHub. 114 | 115 | Where are regression labels? 116 | ============================ 117 | 118 | We rarely updated this information and it turned out not to be 119 | particularly useful outside of the change log. 120 | 121 | 122 | .. _bpo: https://bugs.python.org/ 123 | .. _GitHub search syntax: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax 124 | .. _advanced search: https://github.com/search/advanced 125 | -------------------------------------------------------------------------------- /triage/index.rst: -------------------------------------------------------------------------------- 1 | =================== 2 | Issues and triaging 3 | =================== 4 | 5 | .. toctree:: 6 | :maxdepth: 5 7 | 8 | issue-tracker 9 | triaging 10 | labels 11 | github-bpo-faq 12 | triage-team 13 | -------------------------------------------------------------------------------- /triage/issue-tracker.rst: -------------------------------------------------------------------------------- 1 | .. _issue-tracker: 2 | .. _tracker: 3 | 4 | ============= 5 | Issue tracker 6 | ============= 7 | 8 | 9 | Using the issue tracker 10 | ======================= 11 | 12 | If you think you have found a bug in Python, you can report it to the 13 | `issue tracker`_. The `issue tracker`_ is now hosted on GitHub, alongside 14 | the codebase and pull requests. Documentation bugs can also be reported there. 15 | 16 | If you would like to file an issue about this devguide, please do so at the 17 | `devguide repo`_. 18 | 19 | .. note:: 20 | Prior to moving the issue tracker to GitHub, 21 | Python used to use a dedicated `Roundup`_ instance as its issue tracker. 22 | That `old bug tracker`_ was hosted under the domain ``bugs.python.org`` 23 | (sometimes called ``bpo`` for short). A read-only version is 24 | available on that domain for historical purposes. All ``bpo`` data has been 25 | migrated to the current `issue tracker`_ on GitHub. 26 | 27 | If you're familiar with ``bpo`` and would like to learn more about GitHub 28 | issues, please read this page, and the :ref:`triaging` page as they 29 | provide good introductory material. There is also a :ref:`gh-faq` 30 | document to answer some of the more popular questions. 31 | 32 | Checking if a bug already exists 33 | -------------------------------- 34 | 35 | The first step before filing an issue report is to see whether the problem has 36 | already been reported. Checking if the problem is an existing issue will: 37 | 38 | * help you see if the problem has already been resolved or has been fixed for 39 | the next release 40 | * save time for you and the developers 41 | * help you learn what needs to be done to fix it 42 | * determine if additional information, such as how to replicate the issue, 43 | is needed 44 | 45 | To see if an issue already exists, search the bug database using the search box 46 | above the list of bugs on the issues page. A form-based `advanced search`_ query 47 | builder is also available on GitHub to help creating the text query you need. 48 | 49 | Reporting an issue 50 | ------------------ 51 | 52 | If the problem you're reporting is not already in the `issue tracker`_, you 53 | can report it using the green :guilabel:`New issue` button on the right of the search 54 | box above the list of bugs. If you're not already signed in to GitHub, it 55 | will ask you to do so now. 56 | 57 | First you need to select what kind of problem you want to report. The 58 | available choices include, for example: 59 | 60 | * **Bug report**: an existing feature isn't working as expected. 61 | * **Documentation**: there is missing, invalid, or misleading documentation. 62 | * **Feature or enhancement**: suggest a new feature for Python. 63 | * **Report a security vulnerability**: privately report a security vulnerability. 64 | 65 | Depending on your choice, a dedicated form template will appear. 66 | In particular, you'll notice that the last button actually takes you to 67 | the `Python Discourse`_ (``discuss.python.org``), 68 | where many Python-related discussions take place. 69 | 70 | The submission form has only two fields that you need to fill: 71 | 72 | * in the **Title** field, enter a *very* short description of the problem; 73 | less than ten words is good; 74 | * in the **Write** field, describe the problem in detail using hints from 75 | the template that was put in that field for you. Be sure to include what 76 | you expected to happen, what did happen, and how to replicate the 77 | problem. Be sure to include whether any extension modules were involved, 78 | and what hardware and software platform you were using (including version 79 | information as appropriate). In particular, *what version of Python* you 80 | were using. 81 | 82 | You can tag someone, with :samp:`@{username}` in a comment, 83 | if you think the issue should be brought to their attention. 84 | Use the :ref:`experts` to know who wants to be 85 | tagged or assigned for specific areas. 86 | 87 | There are a number of additional fields like **Assignees**, **Labels**, 88 | and **Projects**. Those are filled by triagers and core 89 | developers and are covered in the :ref:`triaging` page. You don't need 90 | to worry about those when reporting issues as a Python user. 91 | 92 | Adding special links 93 | -------------------- 94 | 95 | The following abbreviations can be used in a comment to generate a link: 96 | 97 | * :samp:`GH-{NNN}`: to link to another issue or PR; 98 | * :samp:`PEP-{NNN}`: to link to a specific PEP; 99 | * :samp:`BPO-{NNN}`: to link to a bugs.python.org issue; 100 | 101 | See also the `list of autolinks supported by GitHub <autolinks_>`_. 102 | 103 | Following issues 104 | ---------------- 105 | 106 | If you want to subscribe yourself to an issue, click the :guilabel:`🔔 Subscribe` 107 | button in the sidebar. Similarly, if you were tagged by somebody else but 108 | decided this issue is not for you, click the :guilabel:`🔕 Unsubscribe` 109 | button in the sidebar. Note that you are automatically subscribed to 110 | issues you created. 111 | 112 | Tracking dependencies and duplicates 113 | ------------------------------------ 114 | 115 | It is possible to use `checklists`_ to track dependencies or, 116 | in case of meta-issues, to link to the other related issues. 117 | 118 | By writing :samp:`Duplicate of #{NNN}` in a comment, you can 119 | `mark issues and PRs as duplicates <duplicates_>`_. 120 | 121 | 122 | Disagreement with a resolution on the issue tracker 123 | =================================================== 124 | 125 | As humans, we will have differences of opinions from time to time. First and 126 | foremost, please be respectful that care, thought, and volunteer time went into 127 | the resolution. 128 | 129 | With this in mind, take some time to consider any comments made in association 130 | with the resolution of the issue. On reflection, the resolution steps may seem 131 | more reasonable than you initially thought. 132 | 133 | If you still feel the resolution is incorrect, then raise a thoughtful question 134 | on the `Core Development Discourse category`_. 135 | Further argument and disrespectful responses 136 | after a consensus has been reached amongst the core developers is unlikely to 137 | win any converts. 138 | 139 | As a reminder, issues closed by a core developer have already been carefully 140 | considered. Please do not reopen a closed issue. An issue can be closed with 141 | reason either as ``complete`` or ``not planned``. 142 | 143 | .. seealso:: 144 | 145 | `The Python issue tracker <issue tracker_>`_ 146 | Where to report issues about Python. 147 | 148 | 149 | .. _issue tracker: https://github.com/python/cpython/issues 150 | .. _advanced search: https://github.com/search/advanced 151 | .. _devguide repo: https://github.com/python/devguide/issues 152 | .. _Roundup: https://www.roundup-tracker.org/ 153 | .. _Python Discourse: https://discuss.python.org/ 154 | .. _autolinks: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls 155 | .. _checklists: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists 156 | .. _duplicates: https://docs.github.com/en/issues/tracking-your-work-with-issues/administering-issues/marking-issues-or-pull-requests-as-a-duplicate 157 | .. _Core Development Discourse category: https://discuss.python.org/c/core-dev/23 158 | .. _old bug tracker: https://bugs.python.org/ 159 | -------------------------------------------------------------------------------- /triage/labels.rst: -------------------------------------------------------------------------------- 1 | .. _labels: 2 | .. _gh-labels: 3 | 4 | ============= 5 | GitHub labels 6 | ============= 7 | 8 | Triagers, core developers and bots can add labels on GitHub 9 | to categorize issues and pull requests. 10 | Many labels are shared for both use cases, while some are dedicated 11 | only to one. Below is a possibly inexhaustive list, but it should get 12 | you going. For a full list, see `here <https://github.com/python/cpython/issues/labels>`_. 13 | 14 | 15 | .. _general-purpose-labels: 16 | .. _Type: 17 | .. _labels-type: 18 | 19 | Type labels 20 | =========== 21 | 22 | These labels are used to specify the type of issue: 23 | 24 | * :gh-label:`type-bug`: for unexpected behaviors, bugs, or exceptions 25 | (not hard crashes). 26 | * :gh-label:`type-crash`: for hard crashes of the interpreter, possibly with a 27 | core dump. 28 | * :gh-label:`type-feature`: for feature requests or enhancements. 29 | Feature requests do not need :ref:`version labels <Version labels>`; 30 | it is implicit that features are added to the ``main`` branch only. 31 | The `Ideas Discourse category`_ can be used to discuss enhancements 32 | before filing an issue. 33 | * :gh-label:`type-security`: for security issues. 34 | See also `Reporting security issues in Python`_. 35 | 36 | 37 | .. _Component: 38 | .. _labels-component: 39 | 40 | Component labels 41 | ================ 42 | 43 | These labels are mostly used to specify which :ref:`part of the codebase 44 | <build_directory_structure>` is affected by the issue/PR: 45 | 46 | * :gh-label:`stdlib`: for standard library modules in the :cpy-file:`Lib` 47 | directory (written in Python). 48 | * :gh-label:`extension-modules`: for standard library modules in the 49 | :cpy-file:`Modules` directory (written in C). 50 | * :gh-label:`interpreter-core`: for changes related to the interpreter core in 51 | the :cpy-file:`Objects`, :cpy-file:`Python`, :cpy-file:`Grammar`, 52 | and :cpy-file:`Parser` dirs (written mostly in C). 53 | * :gh-label:`docs`: for documentation in the :cpy-file:`Doc` directory 54 | (written in :ref:`reStructuredText <markup>`), docstrings, and code comments. 55 | * :gh-label:`tests`: for tests in the :cpy-file:`Lib/test` directory 56 | (written in Python) and other changes related to tests, :mod:`unittest`, 57 | or :mod:`doctest`. 58 | 59 | OS labels 60 | ========= 61 | 62 | These labels are used to specify which operating systems are affected. 63 | Since most issues either affect all systems or are specific to Unix, 64 | we don't have a dedicated Unix label. 65 | 66 | * :gh-label:`OS-android` 67 | * :gh-label:`OS-freebsd` 68 | * :gh-label:`OS-ios` 69 | * :gh-label:`OS-linux` 70 | * :gh-label:`OS-windows` 71 | 72 | Use the :gh-label:`OS-unsupported` label for issues on platforms outside the 73 | support tiers defined in :pep:`11`. Applying this label adds the issue to 74 | `a GitHub project <https://github.com/orgs/python/projects/27/views/1>`_ where 75 | it can be categorized further. 76 | See also the :ref:`Platform experts list <platform-experts>`. 77 | 78 | .. _Expert labels: 79 | .. _Topic labels: 80 | 81 | Topic labels 82 | ============ 83 | 84 | These labels are used to denote the specific topic area, if any, of 85 | the issue/PR. This includes both specific modules/packages and generic 86 | interest areas. 87 | 88 | Adding these labels is also a way to notify the relevant experts, since 89 | they are encouraged to subscribe to them. Depending on the label, 90 | this might also automatically add the issue to a GitHub project. 91 | 92 | You can see the `full list of topic labels on GitHub 93 | <https://github.com/python/cpython/labels?q=topic>`_. 94 | 95 | 96 | .. _Version labels: 97 | 98 | Version labels 99 | ============== 100 | 101 | These labels are used to indicate which versions of Python are affected. 102 | The available version labels (with the form :samp:`3.{N}`) are updated 103 | whenever new feature releases are created or retired. 104 | 105 | See also :ref:`the branch status page <branchstatus>` 106 | for a list of active branches. 107 | 108 | 109 | .. _Keywords: 110 | .. _Other: 111 | .. _Priority: 112 | .. _labels-other: 113 | 114 | Other labels 115 | ============ 116 | 117 | * :gh-label:`build`/:gh-label:`performance`: for issues related 118 | to the build process or performance, respectively. 119 | * :gh-label:`easy`: for issues that are considered easy. 120 | * :gh-label:`infra`: for issues related to the infrastructure of the 121 | project (for example, GitHub Actions, dependabot, the buildbots). 122 | * :gh-label:`pending`: for issues/PRs that will be closed unless further 123 | feedback is provided. 124 | * :gh-label:`release-blocker`/:gh-label:`deferred-blocker`: for issues/PRs 125 | that, unless fixed, will hold the current or next release respectively. 126 | Triagers may set these labels for issues that must be fixed before a release, 127 | and the :ref:`branch's release manager <branchstatus>` 128 | will review them and determine if they indeed qualify, 129 | removing or retaining the label as appropriate. 130 | * :gh-label:`sprint`: for easier filtering of issues/PRs being worked on 131 | during official sprints. 132 | * :gh-label:`stale`: for issues/PRs that have been inactive for a while. 133 | * :gh-label:`triaged`: for issues that have been accepted as valid by a triager. 134 | 135 | 136 | .. _GitHub Labels for PRs: 137 | .. _github-pr-labels: 138 | 139 | Labels specific to PRs 140 | ====================== 141 | 142 | The following labels only apply to :ref:`Pull Requests <pullrequest>`. 143 | They are either set automatically by bots, or added by humans 144 | to trigger specific bot behaviors. 145 | 146 | * :gh-label:`DO-NOT-MERGE`: for PRs that shouldn't be merged in their current 147 | state. It also prevents `miss-islington`_ from being able to automatically 148 | merge the PR. 149 | * :samp:`needs backport to {X.Y}`: used to indicate which branches the PR 150 | should be backported to. Once the PR is merged, ``miss-islington`` will 151 | automatically attempt to create backport PRs for the versions indicated 152 | by these labels. 153 | See also :ref:`the status of the Python branches <branchstatus>` for a list 154 | of branches and the type of PRs that can be backported to them. 155 | * :gh-label:`skip issue <skip%20issue>`: for trivial changes (such as 156 | typo fixes, comment 157 | changes, and section rephrases) that don't require a corresponding issue. 158 | * :gh-label:`skip news <skip%20news>`: for PRs that don't need a NEWS entry. 159 | The :ref:`news-entry` section covers in details in which cases the NEWS entry 160 | can be skipped. 161 | * :gh-label:`test-with-buildbots`: used to test the latest commit with 162 | the :ref:`buildbot fleet <buildbots>` whenever more testing is required 163 | before merging. This may take multiple hours to complete. 164 | * :samp:`awaiting {action}`: these labels are applied and used by `bedevere`_ 165 | to indicate the stage of a PR and should not be applied manually. 166 | 167 | 168 | .. _Reporting security issues in Python: https://www.python.org/dev/security/ 169 | .. _Ideas Discourse category: https://discuss.python.org/c/ideas/6 170 | .. _miss-islington: https://github.com/python/miss-islington 171 | .. _bedevere: https://github.com/python/bedevere/#pr-state-machine 172 | -------------------------------------------------------------------------------- /triage/triage-team.rst: -------------------------------------------------------------------------------- 1 | .. _triage-team: 2 | .. _triagers: 3 | 4 | =========== 5 | Triage Team 6 | =========== 7 | 8 | The Python triage team is a group dedicated towards improving workflow 9 | efficiency through thoughtful review and triage of open issues and pull 10 | requests. This helps contributors receive timely feedback and enables core 11 | developers to focus on reviewed items which reduces their workload. The 12 | expectations of this role expand upon the "Triager" role on the 13 | :ref:`issue tracker <tracker>`. The responsibilities listed below are primarily centered 14 | around the Python GitHub repositories. This extends beyond CPython, and, as 15 | needed, to other repos such as devguide and core-workflow. 16 | 17 | Responsibilities include: 18 | 19 | * Classifying issues and PRs 20 | * Applying appropriate :ref:`labels <gh-labels>` to issues/PRs 21 | * Notifying appropriate core developers 22 | * :ref:`Reviewing PRs <reviewing-prs>` 23 | * Assisting contributors 24 | 25 | Although triagers have the power to close PRs, they should generally not do so 26 | without first consulting a core developer. By having triagers and core developers work together, 27 | the author receives a careful consideration of their PR. This encourages future 28 | contributions, regardless of whether their PR is accepted or closed. 29 | 30 | Nonetheless, triagers should feel free to close a PR if they judge that the 31 | chance of the PR being merged would be exceedingly low, even if substantial 32 | revisions were made to the PR. This includes (but is not limited to) the 33 | following: 34 | 35 | * PRs proposing solely cosmetic changes 36 | * PRs proposing changes to deprecated modules 37 | * PRs that are no longer relevant. This includes: 38 | 39 | - PRs proposing fixes for bugs that can no longer be reproduced 40 | - PRs proposing changes that have been rejected by Python core developers 41 | elsewhere (for example, in an issue or a PEP rejection notice) 42 | 43 | If a triager has any doubt about whether to close a PR, 44 | they should consult a core developer before taking any action. 45 | 46 | Triagers can also make use of the :gh-label:`pending` and :gh-label:`stale` 47 | labels to suggest that a PR may be suitable for closure. 48 | For more information, see the entries in the :ref:`labels-other` section. 49 | 50 | Note that it is of paramount importance to treat every contributor to the Python 51 | project kindly and with respect. Regardless of whether they're entirely new 52 | or a veteran core developer, they're actively choosing to voluntarily donate their 53 | time towards the improvement of Python. As is the case with any member of 54 | the Python Software Foundation, always follow the `PSF Code of Conduct`_. 55 | 56 | .. _PSF Code of Conduct: https://policies.python.org/python.org/code-of-conduct/ 57 | 58 | 59 | Becoming a member of the Python triage team 60 | =========================================== 61 | 62 | All Python core developers are welcome to invite a Python contributor to the 63 | Python triage team. Triagers will be responsible to handle not just issues, but 64 | also pull requests, and even managing backports. A Python triager has access to 65 | more repositories than just CPython. 66 | 67 | When you have consistently shown the ability to properly 68 | help triage issues without guidance, you may request that you 69 | be given the "Triager" role on the :ref:`issue tracker <tracker>`. 70 | You can make the request to any core developer. If they decide you are ready 71 | to gain the extra privileges on the tracker they will then act as a mentor to 72 | you until you are ready to do things entirely on your own. There is no set rule 73 | as to how many issues you need to have helped with before or how long you have 74 | been participating. The key requirements are that you show the desire to 75 | help, you are able to work well with others (especially those already with the 76 | Triager role), and that have a firm grasp of how to do things on the issue 77 | tracker properly on your own. 78 | 79 | Gaining the Triager role will allow you to set any value on any issue in the 80 | tracker, releasing you from the burden of having to ask others to set values on 81 | an issue for you in order to properly triage something. This will not only help 82 | speed up and simplify your work in helping out, but also help lessen the 83 | workload for everyone by gaining your help. 84 | 85 | Any existing active contributor to the Python repository on GitHub can 86 | transition into becoming a Python triager. They can request this to any core 87 | developer, either confidentially via a DM in Discourse, or 88 | publicly by opening an `issue in the core-workflow repository 89 | <https://github.com/python/core-workflow/issues/new?template=triage_membership.md>`_. 90 | If the core developer decides you are ready to gain the extra privileges on the 91 | tracker, they will ask a :ref:`Python organization admin <current owners>` 92 | to invite you to the Python organisation, and then act as a mentor to you until 93 | you are ready to do things entirely on your own. 94 | 95 | For every new triager, it would be great to announce them in the 96 | `Committers category <https://discuss.python.org/c/committers/5>`_ 97 | on the `Python Discourse <https://discuss.python.org/>`_ 98 | (`example announcement 99 | <https://discuss.python.org/t/abhilash-raj-has-been-granted-triage-role-on-github/2089>`__). 100 | -------------------------------------------------------------------------------- /triage/triaging.rst: -------------------------------------------------------------------------------- 1 | .. _triaging: 2 | 3 | ================= 4 | Triaging an issue 5 | ================= 6 | 7 | This section of the devguide documents the :ref:`issue tracker <tracker>` for 8 | users and developers. 9 | 10 | 11 | Checklist for triaging 12 | ====================== 13 | 14 | * Read the initial message and the comments. 15 | * Check that the title is reasonably concise, while including enough specifics 16 | so that those scanning the list of issues can quickly identify its topic. 17 | * For pull requests, ensure that the corresponding issue is added before 18 | the title (:samp:`gh-NNNNN: {Title}`). 19 | * Set all the relevant :ref:`labels <gh-labels>`. 20 | * Where appropriate, set the :guilabel:`Assignees`, :guilabel:`Reviewers`, 21 | :guilabel:`Project` fields, and possibly @mention relevant people. 22 | * You might also leave a brief comment about the proposed next action needed. 23 | If there is a long message list, a summary can be very helpful. 24 | * If the issue is clearly invalid (unrelated to CPython, duplicate, spam, etc), 25 | you can use GitHub's "Close as not planned" option. 26 | 27 | Assignees 28 | --------- 29 | 30 | This field indicates who is expected to take the next step in resolving 31 | the issue. 32 | 33 | It is acceptable to assign an issue to someone if the issue cannot move 34 | forward without their help; for example, they need to make a technical decision on 35 | how to proceed. Also consult the :ref:`experts` as certain 36 | stdlib modules should always be assigned to a specific person. 37 | 38 | Note that in order to assign an issue to someone, that person **must** be 39 | a team member, likely a triager or a core developer. 40 | 41 | .. The Assignees subsection was copied from the labels.rst page in #930. 42 | For consistency, the other fields mentioned above should be documented too. 43 | 44 | 45 | .. _helptriage: 46 | 47 | Helping triage issues 48 | ===================== 49 | 50 | Once you know your way around how Python's source files are 51 | structured and you are comfortable with the workflow, a great way to 52 | contribute is to help triage issues. Do realize, though, that experience 53 | working on Python is needed in order to effectively help triage. 54 | 55 | Around the clock, new issues are being opened on the :ref:`issue tracker 56 | <tracker>` and existing issues are being updated. Every issue needs to be 57 | triaged to make sure everything runs smoothly. 58 | 59 | Classifying reports 60 | ------------------- 61 | 62 | For bugs, an issue needs to: 63 | 64 | * clearly explain the bug so it can be reproduced 65 | * include all relevant platform details 66 | * state what version(s) of Python are affected by the bug. 67 | 68 | These are things you can help with once you have experience developing for 69 | Python: 70 | 71 | * Try reproducing the bug: if it is not explained clearly 72 | enough for you to reproduce it, then there is a good chance a core developer 73 | won't be able to either. 74 | * See if the issue happens on a different Python version: it is always helpful 75 | to know if a bug not only affects the in-development version of Python, but 76 | whether it also affects other versions in maintenance mode. 77 | * Write a unit test: if the bug lacks a unit test that should end up in 78 | Python's test suite, having that written can be very helpful. 79 | 80 | This is all helpful as it allows members of the :ref:`triage team <triage-team>` 81 | to properly classify an issue so it can be handled by the right core developers 82 | in a timely fashion. 83 | 84 | Reviewing pull requests 85 | ----------------------- 86 | 87 | If an issue has a linked pull request that has not been reviewed, 88 | you can help by making sure the pull request: 89 | 90 | * is a good solution to the problem it is trying to solve 91 | * follows the style guides (:pep:`7`, :pep:`8`, :ref:`style-guide`, etc.) 92 | * includes proper tests 93 | * includes proper documentation changes 94 | * includes a :ref:`NEWS entry <news-entry>` (if needed) 95 | * includes the author in ``Misc/ACKS``, either already or the pull request adds them 96 | * doesn't have conflicts with the ``main`` branch 97 | * :ref:`doesn't have failing CI checks <keeping-ci-green>` 98 | 99 | Doing all of this allows core developers and :ref:`triagers <triage-team>` 100 | to more quickly look for subtle issues that only people with extensive 101 | experience working on Python's code base will notice. 102 | 103 | See also :ref:`committing`. 104 | 105 | Finding an issue you can help with 106 | ---------------------------------- 107 | 108 | If you want to help with triaging, you might also want to search for issues 109 | in modules for which you have a working knowledge. Search for the name of a 110 | module in the issue tracker, filter by label, or use the `advanced search`_ 111 | to find these issues. 112 | 113 | .. _advanced search: https://github.com/search/advanced 114 | -------------------------------------------------------------------------------- /versions.rst: -------------------------------------------------------------------------------- 1 | .. _versions: 2 | .. _branchstatus: 3 | 4 | ========================= 5 | Status of Python versions 6 | ========================= 7 | 8 | The ``main`` branch is currently the future Python 3.14, and is the only 9 | branch that accepts new features. The latest release for each Python 10 | version can be found on the `download page <https://www.python.org/downloads/>`_. 11 | 12 | 13 | .. raw:: html 14 | :file: include/release-cycle.svg 15 | 16 | (See :ref:`below <full-chart>` for a chart with older versions. 17 | Another useful visualization is `endoflife.date/python <https://endoflife.date/python>`_.) 18 | 19 | 20 | Supported versions 21 | ================== 22 | 23 | Dates shown in *italic* are scheduled and can be adjusted. 24 | 25 | .. csv-table:: 26 | :header-rows: 1 27 | :width: 100% 28 | :file: include/branches.csv 29 | 30 | .. Remember to update main branch in the paragraph above too 31 | 32 | 33 | Unsupported versions 34 | ==================== 35 | 36 | .. csv-table:: 37 | :header-rows: 1 38 | :width: 100% 39 | :file: include/end-of-life.csv 40 | 41 | 42 | .. _full-chart: 43 | 44 | Full chart 45 | ========== 46 | 47 | .. raw:: html 48 | :file: include/release-cycle-all.svg 49 | 50 | 51 | Status key 52 | ========== 53 | 54 | Python releases go through five phases, as described in :pep:`602`. Release 55 | managers can adjust specific dates as needed. 56 | 57 | :feature: Before the first beta, the next full release can accept new features, 58 | bug fixes, and security fixes. 59 | 60 | :prerelease: After the first beta, no new features can go in, but feature fixes 61 | (including significant changes to new features), bug fixes, and security fixes 62 | are accepted for the upcoming feature release. 63 | 64 | :bugfix: Once a version has been fully released, bug fixes and security fixes are 65 | accepted. New binaries are built and released roughly every two months. This 66 | phase is also called **maintenance** mode or **stable** release. 67 | 68 | :security: After two years (18 months for versions before 3.13), only security 69 | fixes are accepted and no more binaries are released. New source-only versions 70 | can be released as needed. 71 | 72 | :end-of-life: Five years after a release, support ends. The release cycle is 73 | frozen; no further changes are allowed. 74 | 75 | See also the :ref:`devcycle` page for more information about branches and backporting. 76 | --------------------------------------------------------------------------------