Merge remote-tracking branch 'upstream/main' into add-extensions-tuto…

…rial

# Conflicts:
#	conf.py

.editorconfig

@@ -11,5 +11,5 @@ indent_size = 4
 [*.rst]
 indent_size = 3
 
-[*.yml]
+[*.{css,yml}]
 indent_size = 2

_static/devguide_overrides.css

@@ -38,7 +38,7 @@
 
 .release-cycle-chart .release-cycle-blob {
     stroke-width: 1.6px;
-    /* default colours, overriden below for individual statuses */
+    /* default colours, overridden below for individual statuses */
     fill: var(--color-background-primary);
     stroke: var(--color-foreground-primary);
 }
@@ -85,3 +85,12 @@
 .bad pre {
   border-left: 3px solid rgb(244, 76, 78);
 }
+
+.extlink-cpy-file,
+.extlink-gh-label {
+  border: 1px solid var(--color-background-border);
+  border-radius: .2em;
+  font-family: var(--font-stack--monospace);
+  font-size: var(--font-size--small--2);
+  padding: .1em .2em;
+}

conf.py

@@ -1,10 +1,5 @@
-import os
-import sys
 import time
 
-# Location of custom extensions.
-sys.path.insert(0, os.path.abspath(".") + "/_extensions")
-
 extensions = [
     'custom_roles',
     'ubuntu_version',
@@ -177,7 +172,10 @@
 # This config is a dictionary of external sites,
 # mapping unique short aliases to a base URL and a prefix.
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
+_repo = "https://github.com/python/cpython"
 extlinks = {
+    "cpy-file": (f"{_repo}/blob/main/%s", "%s"),
+    "gh-label": (f"{_repo}/labels/%s", "%s"),
     "github": ("https://github.com/%s", "%s"),
     "github-user": ("https://github.com/%s", "@%s"),
     "pypi": ("https://pypi.org/project/%s/", "%s"),

core-developers/developers.csv

@@ -1,3 +1,4 @@
+Ned Batchelder,nedbat,2024-07-16,,
 Michael Droetboom,mdboom,2024-06-06,,
 Tian Gao,gaogaotiantian,2024-06-06,,
 Russell Keith-Magee,freakboy3742,2024-05-30,,

developer-workflow/index.rst

@@ -14,3 +14,4 @@ Development workflow
    grammar
    porting
    sbom
+   psrt

developer-workflow/psrt.rst

@@ -0,0 +1,160 @@
+Python Security Response Team (PSRT)
+====================================
+
+The Python Security Response Team (PSRT) is responsible for handling
+vulnerability reports for CPython and pip.
+
+Vulnerability report triage
+---------------------------
+
+Vulnerability reports are sent to one of two locations,
+the long-standing ``[email protected]`` mailing list
+or using the private vulnerability reporting feature
+of GitHub Security Advisories (GHSA).
+
+For reports sent to ``[email protected]``, a PSRT admin
+will triage the report and if the report seems plausible
+(that is, not spam and for the correct project) will reply with
+instructions on how to report the vulnerability on GitHub.
+
+If the reporter doesn't want to use GitHub's Security Advisories feature
+then the PSRT admins can create a draft report on behalf of the reporter.
+
+Coordinating a vulnerability report
+-----------------------------------
+
+Each report will have a member of the PSRT assigned as the "coordinator".
+The coordinator will be responsible for following the below process and
+will be publicly credited on vulnerability records post-publication.
+
+If a coordinator can't complete the process for any reason (time obligation,
+vacation, etc.) they must find a replacement coordinator in the PSRT
+and reassign the vulnerability report appropriately.
+
+Coordinators are expected to collaborate with other PSRT members and core developers
+when needed for guidance on whether the report is an actual vulnerability,
+severity, advisory text, and fixes.
+
+**The vulnerability coordination process is:**
+
+* Coordinator will determine whether the report constitutes a vulnerability. If the report isn't a vulnerability,
+  the reporter should be notified appropriately. Close the GHSA report, the report can be reopened if
+  sufficient evidence is later obtained that the report is a vulnerability.
+
+* After a vulnerability report is accepted, a Common Vulnerabilities and Exposures (CVE) ID must be assigned. If this is not done
+  automatically, then a CVE ID can be obtained by the coordinator sending an email to ``[email protected]``.
+  No details about the vulnerability report need to be shared with the PSF CVE Numbering Authority (CNA) for a CVE ID to be reserved.
+
+* If the report is a vulnerability, the coordinator will determine the severity of the vulnerability. Severity is one of:
+  **Low**, **Medium**, **High**, and **Critical**. Coordinators can use their knowledge of the code, how the code is likely used,
+  or another mechanism like Common Vulnerability Scoring System (CVSS) for determining a severity. Add this information to the GitHub Security Advisory.
+
+* Once a CVE ID is assigned, the coordinator will share the acceptance and CVE ID with the reporter.
+  Use this CVE ID for referencing the vulnerability. The coordinator will ask the reporter
+  if the reporter would like to be credited publicly for the report and if so, how they would like to be credited.
+  Add this information to the GitHub Security Advisory.
+
+* The coordinator authors the vulnerability advisory text. The advisory must include the following information:
+
+  * Title should be a brief description of the vulnerability and affected component
+    (for example, "Buffer over-read in SSLContext.set_npn_protocols()")
+
+  * Short description of the vulnerability, impact, and the conditions where the affected component is vulnerable, if applicable.
+
+  * Affected versions. This could be "all versions", but if the vulnerability exists in a new feature
+    or removed feature then this could be different. Include versions that are end-of-life in this calculation
+    (for example, "Python 3.9 and earlier", "Python 3.10 and later", "all versions of Python").
+
+  * Affected components and APIs. The module, function, class, or method must be specified so users can
+    search their codebase for usage. For issues affecting the entire project, this can be omitted.
+
+  * Mitigations for the vulnerability beyond upgrading to a patched version, if applicable.
+
+  This can all be done within the GitHub Security Advisory UI for easier collaboration between reporter and coordinator.
+
+* The coordinator determines the fix approach and who will provide a patch.
+  Some reporters are willing to provide or collaborate to create a patch,
+  otherwise relevant core developers can be invited to collaborate by
+  the coordinator.
+
+  * For **Low** and **Medium** severity vulnerabilities it is acceptable
+    to develop a patch in public.
+    The pull request must be marked with the ``security`` and ``release-blocker``
+    labels so that a release is not created without including the patch.
+
+  * For **High** and **Critical** severity vulnerabilities the patch must be
+    developed privately using GitHub Security Advisories' "Private Forks" feature.
+    Core developers can be added to the GitHub Security Advisory via "collaborators"
+    to work on the fix together. Once a patch is approved privately and tested,
+    a public issue and pull request can be created with
+    the ``security`` and ``release-blocker`` labels.
+
+* Once the pull request is merged the advisory can be published. The coordinator will send the advisory by email
+  to ``[email protected]`` using the below template. Backport labels must be added as appropriate.
+  After the advisory is published a CVE record can be created.
+
+Template responses
+------------------
+
+These template responses should be used as guidance for messaging
+in various points in the process above. They are not required to be sent as-is,
+please feel free to adapt them as needed for the current context.
+
+**Directing to GitHub Security Advisories:**
+
+.. highlight:: none
+
+::
+
+   Thanks for submitting this report.
+   We use GitHub Security Advisories for triaging vulnerability reports,
+   are you able to submit your report directly to GitHub?
+
+   https://github.com/python/cpython/security/advisories/new
+
+   If you're unable to submit a report to GitHub (due to not having a GitHub
+   account or something else) let me know and I will create a GitHub Security
+   Advisory on your behalf, although you won't be able to participate directly
+   in discussions.
+
+**Rejecting a vulnerability report:**
+
+::
+
+   Thanks for your report. We've determined that the report doesn't constitute
+   a vulnerability. Let us know if you disagree with this determination.
+   If you are interested in working on this further, you can optionally open a
+   public issue on GitHub.
+
+**Accepting a vulnerability report:**
+
+::
+
+   Thanks for your report. We've determined that the report
+   is a vulnerability. We've assigned {CVE-YYYY-XXXX} and determined
+   a severity of {Low,Medium,High,Critical}. Let us know if you disagree
+   with the determined severity.
+
+   If you would like to be publicly credited for this vulnerability as the
+   reporter, please indicate that, along with how you would like to be
+   credited (name or organization).
+
+   Please keep this vulnerability report private until we've published
+   an advisory to ``[email protected]``.
+
+**Advisory email:**
+
+::
+
+   Title: [{CVE-YYYY-XXXX}] {title}
+
+   There is a {LOW, MEDIUM, HIGH, CRITICAL} severity vulnerability
+   affecting {project}.
+
+   {description}
+
+   Please see the linked CVE ID for the latest information on
+   affected versions:
+
+   * https://www.cve.org/CVERecord?id={CVE-YYYY-XXXX}
+   * {pull request URL}

documentation/style-guide.rst

@@ -54,10 +54,15 @@ starting it with a lowercase letter should be avoided.
 Many special names are used in the Python documentation, including the names of
 operating systems, programming languages, standards bodies, and the like. Most
 of these entities are not assigned any special markup, but the preferred
-spellings are given here to aid authors in maintaining the consistency of
-presentation in the Python documentation.
+spellings are given in :ref:`specific words` to aid authors in maintaining the
+consistency of presentation in the Python documentation.
 
-Other terms and words deserve special mention as well; these conventions should
+.. _specific words:
+
+Specific words
+==============
+
+Some terms and words deserve special mention. These conventions should
 be used to ensure consistency throughout the documentation:
 
 C API
@@ -79,6 +84,12 @@ reST
    used to produce Python documentation.  When spelled out, it is
    always one word and both forms start with a lowercase 'r'.
 
+time zone
+   When referring to a Python term like a module, class, or argument spell it
+   as one word with appropriate markup (for example, ``:mod:`timezone```).
+   When talking about the real-world concept spell it as two words with no
+   markup.
+
 Unicode
    The name of a character coding system. This is always written
    capitalized.

internals/interpreter.rst

@@ -178,38 +178,15 @@ Then the interpreter function (``_PyEval_EvalFrameDefault()``) returns ``NULL``.
 
 However, if an exception is raised in a ``try`` block, the interpreter must jump to the corresponding ``except`` or ``finally`` block.
 In 3.10 and before, there was a separate "block stack" which was used to keep track of nesting ``try`` blocks.
-In 3.11, this mechanism has been replaced by a statically generated table, ``code->co_exceptiontable``.
-The advantage of this approach is that entering and leaving a ``try`` block normally does not execute any code, making execution faster.
-But of course, this table needs to be generated by the compiler, and decoded (by ``get_exception_handler``) when an exception happens.
-
-Exception table format
-----------------------
-
-The table is conceptually a list of records, each containing four variable-length integer fields (in a unique format, see below):
-
-- start: start of ``try`` block, in code units from the start of the bytecode
-- length: size of the ``try`` block, in code units
-- target: start of the first instruction of the ``except`` or ``finally`` block, in code units from the start of the bytecode
-- depth_and_lasti: the low bit gives the "lasti" flag, the remaining bits give the stack depth
-
-The stack depth is used to clean up evaluation stack entries above this depth.
-The "lasti" flag indicates whether, after stack cleanup, the instruction offset of the raising instruction should be pushed (as a ``PyLongObject *``).
-For more information on the design, see :cpy-file:`Objects/exception_handling_notes.txt`.
-
-Each varint is encoded as one or more bytes.
-The high bit (bit 7) is reserved for random access -- it is set for the first varint of a record.
-The second bit (bit 6) indicates whether this is the last byte or not -- it is set for all but the last bytes of a varint.
-The low 6 bits (bits 0-5) are used for the integer value, in big-endian order.
-
-To find the table entry (if any) for a given instruction offset, we can use bisection without decoding the whole table.
-We bisect the raw bytes, at each probe finding the start of the record by scanning back for a byte with the high bit set, and then decode the first varint.
-See ``get_exception_handler()`` in :cpy-file:`Python/ceval.c` for the exact code (like all bisection algorithms, the code is a bit subtle).
+In 3.11, this mechanism has been replaced by a statically generated table, ``code->co_exceptiontable``,
+which is described in detail in the `internals documentation
+<https://github.com/python/cpython/blob/main/InternalDocs/exception_handling.md>`_.
 
 The locations table
 -------------------
 
 Whenever an exception is raised, we add a traceback entry to the exception.
-The ``tb_lineno`` field of a traceback entry must be set to the line number of the instruction that raised it.
+The ``tb_lineno`` field of a traceback entry is (lazily) set to the line number of the instruction that raised it.
 This field is computed from the locations table, ``co_linetable`` (this name is an understatement), using :c:func:`PyCode_Addr2Line`.
 This table has an entry for every instruction rather than for every ``try`` block, so a compact format is very important.
 

internals/parser.rst

@@ -537,7 +537,7 @@ parser (the one used by the interpreter) just execute: ::
 
     make regen-pegen
 
-using the :cpy-file:`!Makefile` in the main directory.  If you are on Windows you can
+using the ``Makefile`` in the main directory.  If you are on Windows you can
 use the Visual Studio project files to regenerate the parser or to execute: ::
 
     ./PCbuild/build.bat --regen

requirements.txt

@@ -7,4 +7,4 @@ sphinx-notfound-page>=1.0.0
 sphinx_copybutton>=0.3.3
 sphinxext-opengraph>=0.7.1
 sphinxext-rediraffe
-Sphinx~=7.3.7
+Sphinx~=7.4.0

testing/coverage.rst

@@ -306,5 +306,5 @@ about 20 to 30 minutes on a modern computer.
 
 .. _issue tracker: https://github.com/python/cpython/issues
 .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
-.. _lcov: https://ltp.sourceforge.net/coverage/lcov.php
+.. _lcov: https://github.com/linux-test-project/lcov
 .. _coverage.py: https://coverage.readthedocs.io/en/latest/