Merge branch 'main' into pythongh-81079-glob-case-sensitive-arg-2

Author: barneygale

Doc/c-api/import.rst

@@ -186,10 +186,10 @@ Importing Modules
 
    .. versionadded:: 3.2
    .. versionchanged:: 3.3
-      Uses :func:`imp.source_from_cache()` in calculating the source path if
+      Uses :func:`!imp.source_from_cache()` in calculating the source path if
       only the bytecode path is provided.
    .. versionchanged:: 3.12
-      No longer uses the removed ``imp`` module.
+      No longer uses the removed :mod:`!imp` module.
 
 
 .. c:function:: long PyImport_GetMagicNumber()

Doc/c-api/type.rst

@@ -256,8 +256,13 @@ The following functions and structs are used to create
    The metaclass *metaclass* is used to construct the resulting type object.
    When *metaclass* is ``NULL``, the metaclass is derived from *bases*
    (or *Py_tp_base[s]* slots if *bases* is ``NULL``, see below).
-   Note that metaclasses that override
-   :c:member:`~PyTypeObject.tp_new` are not supported.
+
+   Metaclasses that override :c:member:`~PyTypeObject.tp_new` are not
+   supported.
+   (For backwards compatibility, other ``PyType_From*`` functions allow
+   such metaclasses. They ignore ``tp_new``, which may result in incomplete
+   initialization. This is deprecated and in Python 3.14+ such metaclasses will
+   not be supported.)
 
    The *bases* argument can be used to specify base classes; it can either
    be only one class or a tuple of classes.
@@ -305,6 +310,11 @@ The following functions and structs are used to create
       The function now finds and uses a metaclass corresponding to the provided
       base classes.  Previously, only :class:`type` instances were returned.
 
+      The :c:member:`~PyTypeObject.tp_new` of the metaclass is *ignored*.
+      which may result in incomplete initialization.
+      Creating classes whose metaclass overrides
+      :c:member:`~PyTypeObject.tp_new` is deprecated and in Python 3.14+ it
+      will be no longer allowed.
 
 .. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
 
@@ -317,6 +327,12 @@ The following functions and structs are used to create
       The function now finds and uses a metaclass corresponding to the provided
       base classes.  Previously, only :class:`type` instances were returned.
 
+      The :c:member:`~PyTypeObject.tp_new` of the metaclass is *ignored*.
+      which may result in incomplete initialization.
+      Creating classes whose metaclass overrides
+      :c:member:`~PyTypeObject.tp_new` is deprecated and in Python 3.14+ it
+      will be no longer allowed.
+
 .. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
 
    Equivalent to ``PyType_FromMetaclass(NULL, NULL, spec, NULL)``.
@@ -327,6 +343,12 @@ The following functions and structs are used to create
       base classes provided in *Py_tp_base[s]* slots.
       Previously, only :class:`type` instances were returned.
 
+      The :c:member:`~PyTypeObject.tp_new` of the metaclass is *ignored*.
+      which may result in incomplete initialization.
+      Creating classes whose metaclass overrides
+      :c:member:`~PyTypeObject.tp_new` is deprecated and in Python 3.14+ it
+      will be no longer allowed.
+
 .. c:type:: PyType_Spec
 
    Structure defining a type's behavior.

Doc/howto/curses.rst

@@ -4,6 +4,8 @@
   Curses Programming with Python
 **********************************
 
+.. currentmodule:: curses
+
 :Author: A.M. Kuchling, Eric S. Raymond
 :Release: 2.04
 
@@ -65,7 +67,7 @@ The Python module is a fairly simple wrapper over the C functions provided by
 curses; if you're already familiar with curses programming in C, it's really
 easy to transfer that knowledge to Python.  The biggest difference is that the
 Python interface makes things simpler by merging different C functions such as
-:c:func:`addstr`, :c:func:`mvaddstr`, and :c:func:`mvwaddstr` into a single
+:c:func:`!addstr`, :c:func:`!mvaddstr`, and :c:func:`!mvwaddstr` into a single
 :meth:`~curses.window.addstr` method.  You'll see this covered in more
 detail later.
 
@@ -82,7 +84,7 @@ Before doing anything, curses must be initialized.  This is done by
 calling the :func:`~curses.initscr` function, which will determine the
 terminal type, send any required setup codes to the terminal, and
 create various internal data structures.  If successful,
-:func:`initscr` returns a window object representing the entire
+:func:`!initscr` returns a window object representing the entire
 screen; this is usually called ``stdscr`` after the name of the
 corresponding C variable. ::
 
@@ -151,8 +153,8 @@ importing the :func:`curses.wrapper` function and using it like this::
 
 The :func:`~curses.wrapper` function takes a callable object and does the
 initializations described above, also initializing colors if color
-support is present.  :func:`wrapper` then runs your provided callable.
-Once the callable returns, :func:`wrapper` will restore the original
+support is present.  :func:`!wrapper` then runs your provided callable.
+Once the callable returns, :func:`!wrapper` will restore the original
 state of the terminal.  The callable is called inside a
 :keyword:`try`...\ :keyword:`except` that catches exceptions, restores
 the state of the terminal, and then re-raises the exception.  Therefore
@@ -200,7 +202,7 @@ This is because curses was originally written with slow 300-baud
 terminal connections in mind; with these terminals, minimizing the
 time required to redraw the screen was very important.  Instead curses
 accumulates changes to the screen and displays them in the most
-efficient manner when you call :meth:`refresh`.  For example, if your
+efficient manner when you call :meth:`!refresh`.  For example, if your
 program displays some text in a window and then clears the window,
 there's no need to send the original text because they're never
 visible.
@@ -210,7 +212,7 @@ really complicate programming with curses much. Most programs go into a flurry
 of activity, and then pause waiting for a keypress or some other action on the
 part of the user.  All you have to do is to be sure that the screen has been
 redrawn before pausing to wait for user input, by first calling
-``stdscr.refresh()`` or the :meth:`refresh` method of some other relevant
+:meth:`!stdscr.refresh` or the :meth:`!refresh` method of some other relevant
 window.
 
 A pad is a special case of a window; it can be larger than the actual display
@@ -234,15 +236,15 @@ displayed.  ::
    #          : filled with pad content.
    pad.refresh( 0,0, 5,5, 20,75)
 
-The :meth:`refresh` call displays a section of the pad in the rectangle
+The :meth:`!refresh` call displays a section of the pad in the rectangle
 extending from coordinate (5,5) to coordinate (20,75) on the screen; the upper
 left corner of the displayed section is coordinate (0,0) on the pad.  Beyond
 that difference, pads are exactly like ordinary windows and support the same
 methods.
 
 If you have multiple windows and pads on screen there is a more
 efficient way to update the screen and prevent annoying screen flicker
-as each part of the screen gets updated.  :meth:`refresh` actually
+as each part of the screen gets updated.  :meth:`!refresh` actually
 does two things:
 
 1) Calls the :meth:`~curses.window.noutrefresh` method of each window
@@ -251,8 +253,8 @@ does two things:
 2) Calls the function :func:`~curses.doupdate` function to change the
    physical screen to match the desired state recorded in the data structure.
 
-Instead you can call :meth:`noutrefresh` on a number of windows to
-update the data structure, and then call :func:`doupdate` to update
+Instead you can call :meth:`!noutrefresh` on a number of windows to
+update the data structure, and then call :func:`!doupdate` to update
 the screen.
 
 
@@ -261,11 +263,11 @@ Displaying Text
 
 From a C programmer's point of view, curses may sometimes look like a
 twisty maze of functions, all subtly different.  For example,
-:c:func:`addstr` displays a string at the current cursor location in
-the ``stdscr`` window, while :c:func:`mvaddstr` moves to a given y,x
-coordinate first before displaying the string. :c:func:`waddstr` is just
-like :c:func:`addstr`, but allows specifying a window to use instead of
-using ``stdscr`` by default. :c:func:`mvwaddstr` allows specifying both
+:c:func:`!addstr` displays a string at the current cursor location in
+the ``stdscr`` window, while :c:func:`!mvaddstr` moves to a given y,x
+coordinate first before displaying the string. :c:func:`!waddstr` is just
+like :c:func:`!addstr`, but allows specifying a window to use instead of
+using ``stdscr`` by default. :c:func:`!mvwaddstr` allows specifying both
 a window and a coordinate.
 
 Fortunately the Python interface hides all these details.  ``stdscr``
@@ -298,7 +300,7 @@ the next subsection.
 The :meth:`~curses.window.addstr` method takes a Python string or
 bytestring as the value to be displayed.  The contents of bytestrings
 are sent to the terminal as-is.  Strings are encoded to bytes using
-the value of the window's :attr:`encoding` attribute; this defaults to
+the value of the window's :attr:`~window.encoding` attribute; this defaults to
 the default system encoding as returned by :func:`locale.getencoding`.
 
 The :meth:`~curses.window.addch` methods take a character, which can be
@@ -444,15 +446,15 @@ There are two methods for getting input from a window:
 
 It's possible to not wait for the user using the
 :meth:`~curses.window.nodelay` window method. After ``nodelay(True)``,
-:meth:`getch` and :meth:`getkey` for the window become
-non-blocking. To signal that no input is ready, :meth:`getch` returns
-``curses.ERR`` (a value of -1) and :meth:`getkey` raises an exception.
+:meth:`!getch` and :meth:`!getkey` for the window become
+non-blocking. To signal that no input is ready, :meth:`!getch` returns
+``curses.ERR`` (a value of -1) and :meth:`!getkey` raises an exception.
 There's also a :func:`~curses.halfdelay` function, which can be used to (in
-effect) set a timer on each :meth:`getch`; if no input becomes
+effect) set a timer on each :meth:`!getch`; if no input becomes
 available within a specified delay (measured in tenths of a second),
 curses raises an exception.
 
-The :meth:`getch` method returns an integer; if it's between 0 and 255, it
+The :meth:`!getch` method returns an integer; if it's between 0 and 255, it
 represents the ASCII code of the key pressed.  Values greater than 255 are
 special keys such as Page Up, Home, or the cursor keys. You can compare the
 value returned to constants such as :const:`curses.KEY_PPAGE`,