Merge branch 'main' into pyrepl/completions-below

Author: danielhollas

.github/CODEOWNERS

@@ -29,19 +29,21 @@ Objects/type*                 @markshannon
 Objects/codeobject.c          @markshannon
 Objects/frameobject.c         @markshannon
 Objects/call.c                @markshannon
-Python/ceval*.c               @markshannon @gvanrossum
-Python/ceval*.h               @markshannon @gvanrossum
+Python/ceval*.c               @markshannon
+Python/ceval*.h               @markshannon
 Python/compile.c              @markshannon @iritkatriel
 Python/assemble.c             @markshannon @iritkatriel
 Python/flowgraph.c            @markshannon @iritkatriel
 Python/ast_opt.c              @isidentical
-Python/bytecodes.c            @markshannon @gvanrossum
-Python/optimizer*.c           @markshannon @gvanrossum
+Python/bytecodes.c            @markshannon
+Python/optimizer*.c           @markshannon
 Python/optimizer_analysis.c   @Fidget-Spinner
 Python/optimizer_bytecodes.c  @Fidget-Spinner
+Lib/_pyrepl/*                 @pablogsal @lysnikolaou @ambv
 Lib/test/test_patma.py        @brandtbucher
 Lib/test/test_type_*.py       @JelleZijlstra
-Lib/test/test_capi/test_misc.py  @markshannon @gvanrossum
+Lib/test/test_capi/test_misc.py  @markshannon
+Lib/test/test_pyrepl/*        @pablogsal @lysnikolaou @ambv
 Tools/c-analyzer/             @ericsnowcurrently
 
 # dbm
@@ -150,7 +152,7 @@ Include/internal/pycore_time.h  @pganssle @abalkin
 /Lib/test/test_tokenize.py    @pablogsal @lysnikolaou
 
 # Code generator
-/Tools/cases_generator/        @gvanrossum
+/Tools/cases_generator/        @markshannon
 
 # AST
 Python/ast.c                  @isidentical

.github/workflows/build.yml

@@ -388,7 +388,7 @@ jobs:
       id: cache-hypothesis-database
       uses: actions/cache@v4
       with:
-        path: ./hypothesis
+        path: ${{ env.CPYTHON_BUILDDIR }}/.hypothesis/
         key: hypothesis-database-${{ github.head_ref || github.run_id }}
         restore-keys: |
           - hypothesis-database-
@@ -416,7 +416,7 @@ jobs:
       if: always()
       with:
         name: hypothesis-example-db
-        path: .hypothesis/examples/
+        path: ${{ env.CPYTHON_BUILDDIR }}/.hypothesis/examples/
 
 
   build_asan:

.github/workflows/jit.yml

@@ -26,8 +26,22 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  interpreter:
+    name: Interpreter (Debug)
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build tier two interpreter
+        run: |
+          ./configure --enable-experimental-jit=interpreter --with-pydebug
+          make all --jobs 4
+      - name: Test tier two interpreter
+        run: |
+          ./python -m test --multiprocess 0 --timeout 4500 --verbose2 --verbose3
   jit:
     name: ${{ matrix.target }} (${{ matrix.debug && 'Debug' || 'Release' }})
+    needs: interpreter
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 90
     strategy:
@@ -153,6 +167,7 @@ jobs:
 
   jit-with-disabled-gil:
     name: Free-Threaded (Debug)
+    needs: interpreter
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

Doc/Makefile

@@ -150,10 +150,14 @@ gettext: build
 htmlview: html
 	$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))"
 
+.PHONY: ensure-sphinx-autobuild
+ensure-sphinx-autobuild: venv
+	$(VENVDIR)/bin/sphinx-autobuild --version > /dev/null || $(VENVDIR)/bin/python3 -m pip install sphinx-autobuild
+
 .PHONY: htmllive
 htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild
 htmllive: SPHINXOPTS = --re-ignore="/venv/" --open-browser --delay 0
-htmllive: html
+htmllive: ensure-sphinx-autobuild html
 
 .PHONY: clean
 clean: clean-venv

Doc/c-api/buffer.rst

@@ -147,9 +147,9 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
       or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
       :c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
 
-   .. c:member:: const char *format
+   .. c:member:: char *format
 
-      A *NUL* terminated string in :mod:`struct` module style syntax describing
+      A *NULL* terminated string in :mod:`struct` module style syntax describing
       the contents of a single item. If this is ``NULL``, ``"B"`` (unsigned bytes)
       is assumed.
 

Doc/c-api/tuple.rst

@@ -105,6 +105,12 @@ Tuple Objects
       is being replaced; any reference in the tuple at position *pos* will be
       leaked.
 
+   .. warning::
+
+      This macro should *only* be used on tuples that are newly created.
+      Using this macro on a tuple that is already in use (or in other words, has
+      a refcount > 1) could lead to undefined behavior.
+
 
 .. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
 

Doc/c-api/weakref.rst

@@ -35,7 +35,7 @@ as much as it can.
    callable object that receives notification when *ob* is garbage collected; it
    should accept a single parameter, which will be the weak reference object
    itself. *callback* may also be ``None`` or ``NULL``.  If *ob* is not a
-   weakly referencable object, or if *callback* is not callable, ``None``, or
+   weakly referenceable object, or if *callback* is not callable, ``None``, or
    ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
 
 
@@ -47,7 +47,7 @@ as much as it can.
    be a callable object that receives notification when *ob* is garbage
    collected; it should accept a single parameter, which will be the weak
    reference object itself. *callback* may also be ``None`` or ``NULL``.  If *ob*
-   is not a weakly referencable object, or if *callback* is not callable,
+   is not a weakly referenceable object, or if *callback* is not callable,
    ``None``, or ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
 
 

Doc/extending/extending.rst

@@ -868,7 +868,7 @@ It is important to call :c:func:`free` at the right time.  If a block's address
 is forgotten but :c:func:`free` is not called for it, the memory it occupies
 cannot be reused until the program terminates.  This is called a :dfn:`memory
 leak`.  On the other hand, if a program calls :c:func:`free` for a block and then
-continues to use the block, it creates a conflict with re-use of the block
+continues to use the block, it creates a conflict with reuse of the block
 through another :c:func:`malloc` call.  This is called :dfn:`using freed memory`.
 It has the same bad consequences as referencing uninitialized data --- core
 dumps, wrong results, mysterious crashes.

Doc/extending/newtypes.rst

@@ -545,7 +545,7 @@ performance-critical objects (such as numbers).
 .. seealso::
    Documentation for the :mod:`weakref` module.
 
-For an object to be weakly referencable, the extension type must set the
+For an object to be weakly referenceable, the extension type must set the
 ``Py_TPFLAGS_MANAGED_WEAKREF`` bit of the :c:member:`~PyTypeObject.tp_flags`
 field. The legacy :c:member:`~PyTypeObject.tp_weaklistoffset` field should
 be left as zero.

Doc/faq/general.rst

@@ -122,6 +122,8 @@ available.  Consult `the Python Package Index <https://pypi.org>`_ to
 find packages of interest to you.
 
 
+.. _faq-version-numbering-scheme:
+
 How does the Python version numbering scheme work?
 --------------------------------------------------
 
@@ -183,8 +185,6 @@ information on getting the source code and compiling it.
 How do I get documentation on Python?
 -------------------------------------
 
-.. XXX mention py3k
-
 The standard documentation for the current stable version of Python is available
 at https://docs.python.org/3/.  PDF, plain text, and downloadable HTML versions are
 also available at https://docs.python.org/3/download.html.

Doc/faq/library.rst

@@ -541,84 +541,6 @@ Thus, to read *n* bytes from a pipe *p* created with :func:`os.popen`, you need
 use ``p.read(n)``.
 
 
-.. XXX update to use subprocess. See the :ref:`subprocess-replacements` section.
-
-   How do I run a subprocess with pipes connected to both input and output?
-   ------------------------------------------------------------------------
-
-   Use the :mod:`popen2` module.  For example::
-
-      import popen2
-      fromchild, tochild = popen2.popen2("command")
-      tochild.write("input\n")
-      tochild.flush()
-      output = fromchild.readline()
-
-   Warning: in general it is unwise to do this because you can easily cause a
-   deadlock where your process is blocked waiting for output from the child
-   while the child is blocked waiting for input from you.  This can be caused
-   by the parent expecting the child to output more text than it does or
-   by data being stuck in stdio buffers due to lack of flushing.
-   The Python parent can of course explicitly flush the data it sends to the
-   child before it reads any output, but if the child is a naive C program it
-   may have been written to never explicitly flush its output, even if it is
-   interactive, since flushing is normally automatic.
-
-   Note that a deadlock is also possible if you use :func:`popen3` to read
-   stdout and stderr. If one of the two is too large for the internal buffer
-   (increasing the buffer size does not help) and you ``read()`` the other one
-   first, there is a deadlock, too.
-
-   Note on a bug in popen2: unless your program calls ``wait()`` or
-   ``waitpid()``, finished child processes are never removed, and eventually
-   calls to popen2 will fail because of a limit on the number of child
-   processes.  Calling :func:`os.waitpid` with the :const:`os.WNOHANG` option can
-   prevent this; a good place to insert such a call would be before calling
-   ``popen2`` again.
-
-   In many cases, all you really need is to run some data through a command and
-   get the result back.  Unless the amount of data is very large, the easiest
-   way to do this is to write it to a temporary file and run the command with
-   that temporary file as input.  The standard module :mod:`tempfile` exports a
-   :func:`~tempfile.mktemp` function to generate unique temporary file names. ::
-
-      import tempfile
-      import os
-
-      class Popen3:
-          """
-          This is a deadlock-safe version of popen that returns
-          an object with errorlevel, out (a string) and err (a string).
-          (capturestderr may not work under windows.)
-          Example: print(Popen3('grep spam','\n\nhere spam\n\n').out)
-          """
-          def __init__(self,command,input=None,capturestderr=None):
-              outfile=tempfile.mktemp()
-              command="( %s ) > %s" % (command,outfile)
-              if input:
-                  infile=tempfile.mktemp()
-                  open(infile,"w").write(input)
-                  command=command+" <"+infile
-              if capturestderr:
-                  errfile=tempfile.mktemp()
-                  command=command+" 2>"+errfile
-              self.errorlevel=os.system(command) >> 8
-              self.out=open(outfile,"r").read()
-              os.remove(outfile)
-              if input:
-                  os.remove(infile)
-              if capturestderr:
-                  self.err=open(errfile,"r").read()
-                  os.remove(errfile)
-
-   Note that many interactive programs (e.g. vi) don't work well with pipes
-   substituted for standard input and output.  You will have to use pseudo ttys
-   ("ptys") instead of pipes. Or you can use a Python interface to Don Libes'
-   "expect" library.  A Python extension that interfaces to expect is called
-   "expy" and available from https://expectpy.sourceforge.net.  A pure Python
-   solution that works like expect is :pypi:`pexpect`.
-
-
 How do I access the serial (RS232) port?
 ----------------------------------------
 

Doc/glossary.rst

@@ -425,11 +425,11 @@ Glossary
       An object that tries to find the :term:`loader` for a module that is
       being imported.
 
-      Since Python 3.3, there are two types of finder: :term:`meta path finders
+      There are two types of finder: :term:`meta path finders
       <meta path finder>` for use with :data:`sys.meta_path`, and :term:`path
       entry finders <path entry finder>` for use with :data:`sys.path_hooks`.
 
-      See :pep:`302`, :pep:`420` and :pep:`451` for much more detail.
+      See :ref:`importsystem` and :mod:`importlib` for much more detail.
 
    floor division
       Mathematical division that rounds down to nearest integer.  The floor

Doc/howto/mro.rst

@@ -426,7 +426,7 @@ In this case the MRO is GFEF and the local precedence ordering is
 preserved.
 
 As a general rule, hierarchies such as the previous one should be
-avoided, since it is unclear if F should override E or viceversa.
+avoided, since it is unclear if F should override E or vice-versa.
 Python 2.3 solves the ambiguity by raising an exception in the creation
 of class G, effectively stopping the programmer from generating
 ambiguous hierarchies.  The reason for that is that the C3 algorithm

Doc/howto/pyporting.rst

@@ -18,9 +18,9 @@ please see :ref:`cporting-howto`.
 
 The archived python-porting_ mailing list may contain some useful guidance.
 
-Since Python 3.13 the original porting guide was discontinued.
+Since Python 3.11 the original porting guide was discontinued.
 You can find the old guide in the
-`archive <https://docs.python.org/3.12/howto/pyporting.html>`_.
+`archive <https://docs.python.org/3.10/howto/pyporting.html>`_.
 
 
 Third-party guides

Doc/library/base64.rst

@@ -193,7 +193,7 @@ The modern interface provides:
 
    *wrapcol* controls whether the output should have newline (``b'\n'``)
    characters added to it. If this is non-zero, each output line will be
-   at most this many characters long.
+   at most this many characters long, excluding the trailing newline.
 
    *pad* controls whether the input is padded to a multiple of 4
    before encoding. Note that the ``btoa`` implementation always pads.

Doc/library/cmath.rst

@@ -43,10 +43,7 @@ Conversions to and from polar coordinates
 
 A Python complex number ``z`` is stored internally using *rectangular*
 or *Cartesian* coordinates.  It is completely determined by its *real
-part* ``z.real`` and its *imaginary part* ``z.imag``.  In other
-words::
-
-   z == z.real + z.imag*1j
+part* ``z.real`` and its *imaginary part* ``z.imag``.
 
 *Polar coordinates* give an alternative way to represent a complex
 number.  In polar coordinates, a complex number *z* is defined by the
@@ -90,7 +87,7 @@ rectangular coordinates to polar coordinates and back.
 .. function:: rect(r, phi)
 
    Return the complex number *x* with polar coordinates *r* and *phi*.
-   Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``.
+   Equivalent to ``complex(r * math.cos(phi), r * math.sin(phi))``.
 
 
 Power and logarithmic functions

Doc/library/ctypes.rst

@@ -661,14 +661,18 @@ for debugging because they can provide useful information::
    guaranteed by the library to work in the general case.  Unions and
    structures with bit-fields should always be passed to functions by pointer.
 
-Structure/union alignment and byte order
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default, Structure and Union fields are aligned in the same way the C
-compiler does it. It is possible to override this behavior by specifying a
-:attr:`~Structure._pack_` class attribute in the subclass definition.
-This must be set to a positive integer and specifies the maximum alignment for the fields.
-This is what ``#pragma pack(n)`` also does in MSVC.
+Structure/union layout, alignment and byte order
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, Structure and Union fields are laid out in the same way the C
+compiler does it.  It is possible to override this behavior entirely by specifying a
+:attr:`~Structure._layout_` class attribute in the subclass definition; see
+the attribute documentation for details.
+
+It is possible to specify the maximum alignment for the fields by setting
+the :attr:`~Structure._pack_` class attribute to a positive integer.
+This matches what ``#pragma pack(n)`` does in MSVC.
+
 It is also possible to set a minimum alignment for how the subclass itself is packed in the
 same way ``#pragma align(n)`` works in MSVC.
 This can be achieved by specifying a ::attr:`~Structure._align_` class attribute
@@ -2540,6 +2544,31 @@ fields, or any other data types containing pointer type fields.
       the structure when being packed or unpacked to/from memory.
       Setting this attribute to 0 is the same as not setting it at all.
 
+   .. attribute:: _layout_
+
+      An optional string naming the struct/union layout. It can currently
+      be set to:
+
+      - ``"ms"``: the layout used by the Microsoft compiler (MSVC).
+        On GCC and Clang, this layout can be selected with
+        ``__attribute__((ms_struct))``.
+      - ``"gcc-sysv"``: the layout used by GCC with the System V or “SysV-like”
+        data model, as used on Linux and macOS.
+        With this layout, :attr:`~Structure._pack_` must be unset or zero.
+
+      If not set explicitly, ``ctypes`` will use a default that
+      matches the platform conventions. This default may change in future
+      Python releases (for example, when a new platform gains official support,
+      or when a difference between similar platforms is found).
+      Currently the default will be:
+
+      - On Windows: ``"ms"``
+      - When :attr:`~Structure._pack_` is specified: ``"ms"``
+      - Otherwise: ``"gcc-sysv"``
+
+      :attr:`!_layout_` must already be defined when
+      :attr:`~Structure._fields_` is assigned, otherwise it will have no effect.
+
    .. attribute:: _anonymous_
 
       An optional sequence that lists the names of unnamed (anonymous) fields.

Doc/library/curses.rst

@@ -924,7 +924,7 @@ the following methods and attributes:
 
 .. method:: window.getbegyx()
 
-   Return a tuple ``(y, x)`` of co-ordinates of upper-left corner.
+   Return a tuple ``(y, x)`` of coordinates of upper-left corner.
 
 
 .. method:: window.getbkgd()