Update for PyPy3.11 (and some other related bits)

Signed-off-by: Michał Górny <mgorny@gentoo.org>

basic.rst

@@ -21,11 +21,13 @@ the list of Python implementations supported by the package.
 The valid values are:
 
 - ``pythonX_Y`` for CPython X.Y
-- ``pypy3`` for PyPy3.
+- ``pythonX_Yt`` for CPython X.Y freethreading
+- ``pypy3`` for PyPy3.10
+- ``pypy3_Y`` for PyPy3.Y (used with PyPy 3.11 and newer)
 
 Typical use::
 
-    PYTHON_COMPAT=( python3_{10..13} pypy3 )
+    PYTHON_COMPAT=( python3_{10..13} pypy3 pypy3_11 )
     inherit python-single-r1
 
 

depend.rst

@@ -174,8 +174,9 @@ The implementation arguments can be:
            ' 3.8)
        "
 
-   The advantage of this form is that the dependencies automatically
-   adjust as we switch PyPy3 to a newer stdlib version.
+   The advantage of this form is that it matches all the Python
+   implementations (currently CPython and PyPy) using a specific stdlib
+   version.
 
 An important feature of ``python_gen_cond_dep`` is that it handles
 removal of old implementations gracefully.  When one of the listed

distutils-legacy.rst

@@ -174,8 +174,7 @@ the following logic:
 3. Otherwise, fall back to ``pkg_resources``.  It is provided
    by ``dev-python/setuptools``.
 
-Since Python 3.7 is no longer present in Gentoo (we are not considering
-PyPy3.7 correctness important for the time being), new ebuilds do not
+Since Python 3.7 is no longer present in Gentoo, new ebuilds do not
 need any additional dependencies for entry points and should use
 the default value (i.e. remove ``DISTUTILS_USE_SETUPTOOLS``).
 

expert-multi.rst

@@ -79,8 +79,8 @@ dependencies to available targets.
     "
 
     python_test() {
-        # tests hang with pypy & pypy3
-        [[ ${EPYTHON} == pypy* ]] && continue
+        # tests hang with PyPy
+        [[ ${EPYTHON} == pypy3* ]] && continue
 
         epytest
     }

interpreter-maintenance.rst

@@ -51,36 +51,34 @@ PyPy
 ----
 Due to high resource requirements and long build time, PyPy on Gentoo
 is provided both in source and precompiled form.  This creates a bit
-unusual ebuild structure:
+unusual ebuild structure (the package names given here are for
+the newest approach, used with PyPy3.11):
 
-- ``dev-python/pypy-exe`` provides the PyPy executable and generated
+- ``dev-lang/pypy3-exe`` provides the PyPy executable and generated
   files built from source,
-- ``dev-python/pypy-exe-bin`` does the same in precompiled binary form,
-- ``dev-python/pypy`` combines the above with the common files.  This
-  is the package that runs tests and satisfies the PyPy target.
-
-Matching ``dev-python/pypy3*`` exist for PyPy3.
-
-When bumping PyPy, ``pypy-exe`` needs to be updated first.  Then it
-should be used to build a binary package and bump ``pypy-exe-bin``.
-Technically, ``pypy`` can be bumped after ``pypy-exe`` and used to test
-it but it should not be pushed before ``pypy-exe-bin`` is ready, as it
+- ``dev-lang/pypy3-exe-bin`` does the same in precompiled binary form,
+- ``dev-lang/pypy`` combines the above with the common files.  This
+  is the package that satisfies the PyPy targets.
+
+When bumping PyPy, ``pypy3-exe`` needs to be updated first.  Then it
+should be used to build a binary package and bump ``pypy3-exe-bin``.
+Technically, ``pypy`` can be bumped after ``pypy3-exe`` and used to test
+it but it should not be pushed before ``pypy3-exe-bin`` is ready, as it
 would force all users to switch to source form implicitly.
 
 The binary packages are built using Docker_ nowadays, using
 binpkg-docker_ scripts.  To produce them, create a ``local.diff``
-containing changes related to PyPy bump and run ``amd64-pypy``
-(and/or ``amd64-pypy3``) and ``x86-pypy`` (and/or ``x86-pypy3``) make
-targets::
+containing changes related to PyPy bump and run ``${arch}-pypy${ver}``.
+For example::
 
     git clone https://github.com/mgorny/binpkg-docker
     cd binpkg-docker
     (cd ~/git/gentoo && git diff origin) > local.diff
-    make amd64-pypy amd64-pypy3 x86-pypy x86-pypy3
+    make {amd64,arm64,ppc64le,x86}{,-musl}-pypy{,3_10,3_11}
 
 The resulting binary packages will be placed in your home directory,
 in ``~/binpkg/${arch}/pypy``.  Upload them and use them to bump
-``pypy-exe-bin``.
+``pypy*-exe-bin``.
 
 
 Adding a new Python implementation

interpreter.rst

@@ -133,9 +133,7 @@ at the moment.
 PyPy does not hold specific ABI stability guarantees.  Gentoo packages
 use subslots to declare the current ABI version, and the eclasses use
 slot operators in dependencies to enforce rebuilds whenever the ABI
-version changes.  Fortunately, lately this has only occurred whenever
-Gentoo switched to the next PyPy branch (i.e. the one corresponding
-to the next Python language version).
+version changes.  Fortunately, this has not happened recently.
 
 
 Alternative Python implementations
@@ -151,9 +149,10 @@ It maintains quite good compatibility with CPython, except when programs
 rely on its implementation details or GC behavior.
 
 PyPy upstream provides PyPy variants compatible with Python 2.7
-and one version of Python 3.  Gentoo supports building packages against
-PyPy3.  PyPy2.7 is provided as ``dev-python/pypy``, while PyPy3 is
-provided as ``dev-python/pypy3``.
+and at least one version of Python 3.  Gentoo supports building packages
+against the current version of PyPy3 (and the previous version during
+transition periods).  The different versions are available as slots
+of ``dev-lang/pypy``.
 
 Jython_ is an implementation of Python written in Java.  Besides being
 a stand-alone Python interpreter, it supports bidirectional interaction

porting.rst

@@ -71,7 +71,7 @@ automatically.  A common approach is to combine checks for PyPy with
 .. code-block:: bash
 
     python_compile() {
-        if ! use native-extensions || [[ ${EPYTHON} == pypy3 ]]; then
+        if ! use native-extensions || [[ ${EPYTHON} == pypy3* ]]; then
             local -x MULTIDICT_NO_EXTENSIONS=1
         fi