DOCSEARCHbyAlgolia
Submit Docs

CPython Developer's Guide

repository·main·Indexed 24 days ago

https://github.com/python/devguide

Instructions and documentation for contributing to the CPython project. Includes guidance on joining the core team, gaining commit privileges, understanding C API tiers, and using the CPython Experts Index to identify maintainers for the standard library, tools, and platform-specific implementations.

Tokens
52.5K
Snippets
104
Records
283
Agent score
84%

What's inside python-devguide

  1. Overview of contributing to Python

    main

    The Python Developer's Guide is a resource for contributing to CPython (the reference Python interpreter). Contributions are categorized into three main areas:

    1. Documentation: Includes doc quality, documenting, style guides, RST usage, translating, and the devguide itself.
    2. Code: Includes setup, getting help, pull requests, running tests, fixing issues, the developer lifecycle, git bootcamp, and communication.
    3. Triage: Includes using the issue tracker, triaging issues, helping with triage, identifying experts, using labels, GitHub FAQs, and the triage team.

    New contributors can also seek guidance through the Core Python Mentorship group.

  2. Identify the status of Python branches

    main

    The main branch represents the future version of Python and is the only branch that accepts new features. For all other versions, the development status (Supported vs. Unsupported) determines the type of fixes available.

    To find the current status of specific versions, refer to the release cycle charts or the official Python download page.

  4. Responsibilities of the Python triage team

    main

    The Python triage team improves workflow efficiency by reviewing and triaging open issues and pull requests (PRs) across Python GitHub repositories (including CPython, devguide, and core-workflow).

    Key responsibilities include:

    • Classifying issues and PRs.
    • Applying appropriate GitHub labels.
    • Notifying relevant core developers.
    • Reviewing PRs.
    • Assisting contributors.

    Guidelines for closing PRs: Triagers should generally consult a core developer before closing a PR to ensure the author receives careful consideration. However, triagers are encouraged to close PRs if the chance of merging is exceedingly low, such as:

    • PRs proposing solely cosmetic changes.
    • PRs proposing changes to deprecated modules.
    • PRs that are no longer relevant (e.g., bugs that can no longer be reproduced or changes previously rejected by core developers in a PEP rejection notice).

    Triagers may use the pending and stale labels to suggest a PR is suitable for closure. Always follow the PSF Code of Conduct and treat all contributors with respect.

  5. What is the Limited API and how to use it

    main

    The Limited API is a subset of the C API designed to guarantee ABI stability across Python 3 versions. By defining the macro Py_LIMITED_API, an extension limits its exposed API to this stable subset. This ensures that extensions compiled against an older version of the Limited API continue to work on newer Python versions without recompilation.

    Key Constraints:

    • No changes that break the Stable ABI are allowed.
    • The Limited API should be defined in the Include/ directory, excluding cpython/ and internal/ subdirectories.
    • Functions dealing with FILE* or other types with ABI portability issues should not be added to the Limited API.

  6. What is Argument Clinic and how does it work?

    main

    Argument Clinic is a preprocessor for CPython C files used to provide introspection signatures and generate boilerplate code for argument parsing in CPython builtins, module-level functions, and class methods.

    The Argument Clinic Block

    Argument Clinic operates on a specific structure within a C file called a block. A block consists of:

    1. Start line: /*[clinic input] (opens a C block comment).
    2. Input: The text between the start line and the end line. This is where you define your argument logic.
    3. End line: [clinic start generated code]*/ (closes the C block comment and marks the start of generated code).
    4. Output: The generated C code produced by Argument Clinic.
    5. Checksum line: /*[clinic end generated code: ...]*/ (marks the end of the block and contains a hash used to detect if the input or output has changed).

    Important: Never modify the generated output directly. If you change the output, Argument Clinic will detect a checksum mismatch and overwrite your changes with regenerated code. To change the behavior of the generated code, you must modify the input instead.

    /*[clinic input]
... clinic input goes here ...
[clinic start generated code]*/
... clinic output goes here ...
/*[clinic end generated code: ...]*/

  7. Which Python versions are eligible for CVE IDs?

    main

    Python assigns CVE IDs only to supported versions with a status of bugfix or security.

    • Ineligible Versions: feature or prerelease (alphas, betas, release candidates) are not eligible for CVE IDs. Issues in these versions should be reported as regular bugs.
    • Experimental Features: Features marked as "experimental" in stable versions are not eligible for security vulnerability status; report these via public GitHub issues.
    • Platform Support: Vulnerabilities must affect platforms supported per PEP 11. Issues exclusively affecting unsupported platforms are treated as third-party port issues. If reporting such an issue, include the relevant platform and maintainer context; the PSRT may forward these to platform maintainers.

  8. PyPI organization policy for publishing packages

    main

    The Python core team uses two distinct PyPI organizations for publishing packages. Choosing the correct one depends on the target audience and relationship to CPython:

    • cpython organization: Use this for development tools closely tied to CPython development (e.g., blurb, cherry-picker).
    • python organization: Use this for general-audience projects maintained by the Python core team (e.g., pyperformance, python-docs-theme, tzdata).

  9. Understand the Python release lifecycle phases

    main

    Python releases follow five distinct phases as defined in PEP 602. Understanding these phases helps developers know when new features are being added or when a version is only receiving security updates.

    • feature: The phase before the first beta. The version accepts new features, bug fixes, and security fixes.
    • prerelease: Occurs after the first beta. No new features are allowed, but feature fixes (including changes to new features), bug fixes, and security fixes are accepted.
    • bugfix: The stable/maintenance phase after a full release. Only bug fixes and security fixes are accepted. New binaries are typically released every two months.
    • security: Occurs after two years (or 18 months for versions prior to 3.13). Only security fixes are accepted; no new binaries are released, though source-only versions may be released as needed.
    • end-of-life: Support ends five years after release. The release cycle is frozen and no further changes are allowed.

  10. Core team responsibilities and privileges

    main

    Core team members accept additional responsibilities for the ongoing management of CPython, including:

    • Handling consequences: Managing the impact of accepted changes, such as reverting or fixing code that causes problems in the Buildbot fleet or post-commit review, and assisting release managers during pre-release testing.
    • Escalation and Design: Deciding when issue tracker discussions should be escalated to the Discourse forum and suggesting the use of the Python Enhancement Proposal (PEP) process for complex or high-impact changes.

    In exchange for these responsibilities, core team members gain the privilege to:

    • Approve or reject proposed changes.
    • Request that merged changes be escalated to Discourse for further discussion or potentially reverted prior to release.

  11. Access CPython internals via Py_BUILD_CORE macros

    main

    If your extension module requires internal headers from Include/internal, you must define one of the following macros before including them:

    • Py_BUILD_CORE_BUILTIN: Use if the module is a built-in extension.
    • Py_BUILD_CORE_MODULE: Use if the module is a shared extension.

    Defining either macro automatically implies Py_BUILD_CORE.

    /* For built-in modules */
#ifndef Py_BUILD_CORE_MODULE
#  define Py_BUILD_CORE_BUILTIN 1
#endif

/* For shared modules */
#ifndef Py_BUILD_CORE_BUILTIN
#  define Py_BUILD_CORE_MODULE 1
#endif

  12. Use optional groups in Argument Clinic

    main

    Optional groups allow you to group parameters that must be passed together. This is a legacy mechanism intended only for converting existing CPython builtins that use multiple PyArg_ParseTuple calls (e.g., functions like range or curses.window.addch).

    Constraints and Rules

    • Use Case: Only for legacy code. Do not use for new code.
    • Parameter Type: Optional groups can only contain positional-only parameters.
    • Syntax: Wrap the parameters in [ and ] on their own lines.
    • Python Visibility: Functions using optional groups cannot have accurate signatures in Python because Python does not natively support this concept.

    Implementation Details

    For every optional group, the implementation function receives an additional int parameter named group_{direction}_{number}:

    • {direction} is left or right depending on the group's position relative to required arguments.
    • {number} is a monotonically increasing integer starting at 1.
    • The value is 0 if the group was unused, and non-zero if the group was used.

    If no required arguments exist, groups are treated as being to the right.

    /*[clinic input]

curses.window.addch

    [
    x: int
      X-coordinate.
    y: int
      Y-coordinate.
    ]

    ch: object
      Character to add.

    [
    attr: long
      Attributes for the character.
    ]
    /

...