Merge branch 'main' into xin

Author: xinetzone

.github/workflows/ci.yml

@@ -3,7 +3,7 @@ name: Tests
 on:
   pull_request:
   push:
-    branches: master
+    branches: main
 
 jobs:
   test:
@@ -13,14 +13,14 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.9"]
+        python-version: ["3.10"]
 
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/cache@v1
+      - uses: actions/cache@v2
         with:
           path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
           restore-keys: |
             ${{ runner.os }}-pip-
       - uses: actions/setup-python@v2

.hgignore

@@ -0,0 +1,20 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+sphinx:
+  builder: dirhtml
+  configuration: conf.py
+
+formats: all
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.10"
+
+python:
+  install:
+    - requirements: requirements.txt

.readthedocs.yml

@@ -101,8 +101,44 @@ No changes that break the Stable ABI are allowed.
 The Limited API should be defined in ``Include/``, excluding the
 ``cpython`` and ``internal`` subdirectories.
 
-Guidelines for changing the Limited API
----------------------------------------
+
+Guidelines for changing the Limited API, and removing items from it
+-------------------------------------------------------------------
+
+While the *Stable ABI*  must not be broken, the existing Limited API can be
+changed, and items can be removed from it, if:
+
+- the Backwards Compatibility Policy (:pep:`387`) is followed, and
+- the Stable ABI is not broken -- that is, extensions compiled with
+  Limited API of older versions of Python continue to work on
+  newer versions of Python.
+
+This is tricky to do and requires careful thought.
+Some examples:
+
+- Functions, structs etc. accessed by macros in *any version* of the
+  Limited API are part of the Stable ABI, even if they are named with
+  an underscore. They must not be removed and their signature must not change.
+  (Their implementation may change, though.)
+- Structs members cannot be rearranged if they were part of any version of
+  the Limited API.
+- If the Limited API allows users to allocate a struct directly,
+  its size must not change.
+- Exported symbols (functions and data) must continue to be available
+  as exported symbols. Specifically, a function can only be converted
+  to a ``static inline`` function (or macro) if Python also continues to
+  provide the actual function.
+  For an example, see the ``Py_NewRef`` `macro`_ and `redefinition`_ in 3.10.
+
+.. _macro: https://github.com/python/cpython/blob/v3.10.1/Include/object.h#L591-L595
+.. _redefinition: https://github.com/python/cpython/blob/v3.10.1/Objects/object.c#L2298-L2308
+
+It is possible to remove items marked as part of the Stable ABI, but only
+if there was no way to use them in any past version of the Limited API.
+
+
+Guidelines for adding to the Limited API
+----------------------------------------
 
 - Guidelines for the general :ref:`public-capi` apply.
 

c-api.rst

@@ -244,11 +244,11 @@ manually -- ``generic``, ``identifier`` and ``int``.  These types are found in
 for creating ``asdl_xx_seq *`` types are as follows:
 
 ``_Py_asdl_generic_seq_new(Py_ssize_t, PyArena *)``
-        Allocate memory for an ``asdl_int_seq`` of the specified length
+        Allocate memory for an ``asdl_generic_seq`` of the specified length
 ``_Py_asdl_identifier_seq_new(Py_ssize_t, PyArena *)``
         Allocate memory for an ``asdl_identifier_seq`` of the specified length
 ``_Py_asdl_int_seq_new(Py_ssize_t, PyArena *)``
-        Allocate memory for an ``asdl_generic_seq`` of the specified length
+        Allocate memory for an ``asdl_int_seq`` of the specified length
 
 In addition to the three types mentioned above, some ASDL sequence types are
 automatically generated by :file:`Parser/asdl_c.py` and found in

compiler.rst

@@ -78,20 +78,20 @@ The steps to gaining commit privileges are:
    email you asking for:
 
    - Account details as required by
-     https://github.com/python/voters/
+     🔒 https://github.com/python/voters/
    - Your preferred email address to
      subscribe to python-committers with
    - A reminder about the `Code of Conduct`_ and to report issues to the PSF
      Conduct WG
 
 6. Once you have provided the pertinent details, your various new privileges
    will be turned on
-7. Your details will be added to https://github.com/python/voters/
+7. Your details will be added to 🔒 https://github.com/python/voters/
 8. They will update the devguide to publicly list your team membership at
    :ref:`developers`
 9. An announcement email by the steering council member handling your new
    membership will be sent to python-committers
-   
+
 .. _Code of Conduct: https://www.python.org/psf/conduct/
 
 

coredev.rst

@@ -131,6 +131,8 @@ For reference, here are the Python versions that most recently reached their end
 +------------------+--------------+----------------+----------------+----------------------------------+
 | Branch           | Schedule     | First release  | End-of-life    | Release manager                  |
 +==================+==============+================+================+==================================+
+| 3.6              | :pep:`494`   | 2016-12-23     | 2021-12-23     | Ned Deily                        |
++------------------+--------------+----------------+----------------+----------------------------------+
 | 3.5              | :pep:`478`   | 2015-09-13     | 2020-09-30     | Larry Hastings                   |
 +------------------+--------------+----------------+----------------+----------------------------------+
 | 3.4              | :pep:`429`   | 2014-03-16     | 2019-03-18     | Larry Hastings                   |
@@ -283,8 +285,6 @@ Current Owners
 +----------------------+--------------------------------+-----------------+
 | Donald Stufft        | Infrastructure Staff           | dstufft         |
 +----------------------+--------------------------------+-----------------+
-| Ewa Jodlowska        | PSF Executive Director         | ejodlowska      |
-+----------------------+--------------------------------+-----------------+
 | Ee Durbin            | PSF Director of Infrastructure | ewdurbin        |
 +----------------------+--------------------------------+-----------------+
 | Van Lindberg         | PSF General Counsel            | VanL            |
@@ -329,7 +329,7 @@ Current Administrators
 +-------------------+----------------------------------------------------------+-----------------+
 | Ned Deily         | Python 3.6 and 3.7 Release Manager                       | ned-deily       |
 +-------------------+----------------------------------------------------------+-----------------+
-| Lary Hastings     | Retired Release Manager (for Python 3.4 and 3.5)         | larryhastings   |
+| Larry Hastings    | Retired Release Manager (for Python 3.4 and 3.5)         | larryhastings   |
 +-------------------+----------------------------------------------------------+-----------------+
 | Berker Peksag     | Maintainer of bpo-linkify and cpython-emailer-webhook    | berkerpeksag    |
 +-------------------+----------------------------------------------------------+-----------------+

devcycle.rst

@@ -32,8 +32,7 @@ and validates that your new markup is correct.
 
 You can view the documentation built from :ref:`in-development <indevbranch>`
 and :ref:`maintenance <maintbranch>` branches at https://docs.python.org/dev/.
-The in-development and most recent 3.x (as well as 2.x) maintenance
-branches are rebuilt once per day.
+The in-development and recent maintenance branches are rebuilt once per day.
 
 If you would like to be more involved with documentation, consider subscribing
 to the `[email protected] <https://mail.python.org/mailman/listinfo/docs>`_

docquality.rst

@@ -37,9 +37,6 @@ The existence of this list is not meant to indicate that these people
 by non-committers to find responsible parties, and by committers who do
 not feel qualified to make a decision in a particular context.
 
-See also :PEP:`291` and :PEP:`360` for information about certain modules
-with special rules.
-
 
 Stdlib
 ------
@@ -50,7 +47,7 @@ __future__
 __main__              gvanrossum, ncoghlan
 _dummy_thread         brett.cannon
 _thread
-_testbuffer           
+_testbuffer
 abc
 aifc                  r.david.murray
 argparse              rhettinger*
@@ -141,7 +138,7 @@ itertools             rhettinger*
 json                  bob.ippolito (inactive), ezio.melotti, rhettinger
 keyword
 lib2to3               benjamin.peterson
-libmpdec              
+libmpdec
 linecache
 locale                lemburg
 logging               vinay.sajip
@@ -187,7 +184,7 @@ pydoc
 queue                 rhettinger*
 quopri
 random                rhettinger, mark.dickinson
-re                    effbot (inactive), ezio.melotti, serhiy.storchaka
+re                    ezio.melotti, serhiy.storchaka
 readline              twouters
 reprlib
 resource              twouters
@@ -254,13 +251,13 @@ wave
 weakref               fdrake
 webbrowser
 winreg                stutzbach
-winsound              effbot (inactive)
+winsound
 wsgiref               pje
 xdrlib
 xml.dom
 xml.dom.minidom
 xml.dom.pulldom
-xml.etree             effbot (inactive), eli.bendersky*, scoder
+xml.etree             eli.bendersky*, scoder
 xml.parsers.expat
 xml.sax
 xml.sax.handler
@@ -310,12 +307,12 @@ Interest Area       Maintainers
 ==================  ==========================================================
 algorithms          rhettinger*
 argument clinic     larry
-ast/compiler        benjamin.peterson, brett.cannon, yselivanov, pablogsal, Mark.Shannon, BTaskaya
+ast/compiler        benjamin.peterson, brett.cannon, yselivanov, pablogsal, Mark.Shannon, BTaskaya, brandtbucher
 autoconf/makefiles  twouters*
 bsd
 bug tracker         ezio.melotti
 buildbots           zach.ware, pablogsal
-bytecode            benjamin.peterson, yselivanov, Mark.Shannon
+bytecode            benjamin.peterson, yselivanov, Mark.Shannon, brandtbucher
 context managers    ncoghlan
 core workflow       mariatta
 coverity scan       christian.heimes, brett.cannon, twouters
@@ -335,13 +332,13 @@ io                  benjamin.peterson, stutzbach
 locale              lemburg
 mathematics         mark.dickinson, lemburg, stutzbach, rhettinger
 memory management   tim.peters, lemburg, twouters
-memoryview          
+memoryview
 networking          giampaolo.rodola,
 object model        benjamin.peterson, twouters
 packaging           tarek, lemburg, alexis, eric.araujo, dstufft, paul.moore
 pattern matching    brandtbucher*
 peg parser          gvanrossum, pablogsal, lys.nikolaou
-performance         brett.cannon, vstinner, serhiy.storchaka, yselivanov, rhettinger, Mark.Shannon
+performance         brett.cannon, vstinner, serhiy.storchaka, yselivanov, rhettinger, Mark.Shannon, brandtbucher
 pip                 ncoghlan, dstufft, paul.moore, Marcus.Smith, pradyunsg
 py3 transition      benjamin.peterson
 release management  tarek, lemburg, benjamin.peterson, barry,

experts.rst

@@ -240,6 +240,32 @@ Commit the files:
 
    git commit -m "<message>"
 
+.. _diff-changes:
+
+Comparing Changes
+-----------------
+
+View all non-commited changes::
+
+   git diff
+
+Compare to the ``main`` branch::
+
+   git diff main
+
+Exclude generated files from diff using an ``attr``
+`pathspec <https://git-scm.com/docs/gitglossary#def_pathspec>`_ (note the
+single quotes)::
+
+   git diff main ':(attr:!generated)'
+
+Exclude generated files from diff by default::
+
+   git config diff.generated.binary true
+
+The ``generated`` `attribute <https://git-scm.com/docs/gitattributes>`_ is
+defined in :file:`.gitattributes`, found in the repository root.
+
 .. _push-changes:
 
 Pushing Changes
@@ -318,30 +344,30 @@ When it happens, you need to resolve conflict.  See these articles about resolvi
 - `About merge conflicts <https://help.github.com/en/articles/about-merge-conflicts>`_
 - `Resolving a merge conflict using the command line <https://help.github.com/en/articles/resolving-a-merge-conflict-using-the-command-line>`_
 
-.. _git_from_mercurial:
+.. _git_from_patch:
 
-Applying a Patch from Mercurial to Git
---------------------------------------
+Applying a Patch to Git
+-----------------------
 
 Scenario:
 
-- A Mercurial patch exists but there is no pull request for it.
+- A patch exists but there is no pull request for it.
 
 Solution:
 
 1. Download the patch locally.
 
 2. Apply the patch::
 
-       git apply /path/to/issueNNNN-git.patch
+       git apply /path/to/patch.diff
 
    If there are errors, update to a revision from when the patch was
    created and then try the ``git apply`` again:
 
    .. code-block:: bash
 
        git checkout $(git rev-list -n 1 --before="yyyy-mm-dd hh:mm:ss" main)
-       git apply /path/to/issueNNNN-git.patch
+       git apply /path/to/patch.diff
 
    If the patch still won't apply, then a patch tool will not be able to
    apply the patch and it will need to be re-implemented manually.
@@ -356,6 +382,9 @@ Solution:
        git rebase main
        git mergetool
 
+   For very old changes, ``git merge --no-ff`` may be easier than a rebase,
+   with regards to resolving conflicts.
+
 6. Push the changes and open a pull request.
 
 .. _git_pr:
@@ -368,7 +397,18 @@ Scenario:
 - A contributor made a pull request to CPython.
 - Before merging it, you want to be able to test their changes locally.
 
-On Unix and MacOS, set up the following git alias::
+If you've got `GitHub CLI <https://cli.github.com>`_ or
+`hub <https://hub.github.com>`_ installed, you can simply do::
+
+   $ gh pr checkout <pr_number>   # GitHub CLI
+   $ hub pr checkout <pr_number>  # hub
+
+Both of these tools will configure a remote URL for the branch, so you can
+``git push`` if the pull request author checked "Allow edits from maintainers"
+when creating the pull request.
+
+If you don't have GitHub CLI or hub installed, you can set up a git alias. On
+Unix and macOS::
 
    $ git config --global alias.pr '!sh -c "git fetch upstream pull/${1}/head:pr_${1} && git checkout pr_${1}" -'
 
@@ -383,15 +423,6 @@ local copy of a pull request as follows::
 
    git pr <pr_number>
 
-.. note::
-
-   `hub <https://github.com/github/hub>`_ command line utility makes this
-   workflow very easy.  You can check out the branch by
-   ``hub pr checkout <pr_number> [<branch_name>]``.
-   This command configures remote URL for the branch too.
-   So you can ``git push`` if the pull request author checked
-   "Allow edits from maintainers" when creating the pull request.
-
 .. _accepting-and-merging-a-pr:
 
 Accepting and Merging a Pull Request