Merge remote-tracking branch 'cpython/main' into pythongh-83180

Doc/c-api/datetime.rst

@@ -8,11 +8,54 @@ DateTime Objects
 Various date and time objects are supplied by the :mod:`datetime` module.
 Before using any of these functions, the header file :file:`datetime.h` must be
 included in your source (note that this is not included by :file:`Python.h`),
-and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
+and the macro :c:macro:`!PyDateTime_IMPORT` must be invoked, usually as part of
 the module initialisation function.  The macro puts a pointer to a C structure
-into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
+into a static variable, :c:data:`!PyDateTimeAPI`, that is used by the following
 macros.
 
+.. c:type:: PyDateTime_Date
+
+   This subtype of :c:type:`PyObject` represents a Python date object.
+
+.. c:type:: PyDateTime_DateTime
+
+   This subtype of :c:type:`PyObject` represents a Python datetime object.
+
+.. c:type:: PyDateTime_Time
+
+   This subtype of :c:type:`PyObject` represents a Python time object.
+
+.. c:type:: PyDateTime_Delta
+
+   This subtype of :c:type:`PyObject` represents the difference between two datetime values.
+
+.. c:var:: PyTypeObject PyDateTime_DateType
+
+   This instance of :c:type:`PyTypeObject` represents the Python date type;
+   it is the same object as :class:`datetime.date` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_DateTimeType
+
+   This instance of :c:type:`PyTypeObject` represents the Python datetime type;
+   it is the same object as :class:`datetime.datetime` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_TimeType
+
+   This instance of :c:type:`PyTypeObject` represents the Python time type;
+   it is the same object as :class:`datetime.time` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_DeltaType
+
+   This instance of :c:type:`PyTypeObject` represents Python type for
+   the difference between two datetime values;
+   it is the same object as :class:`datetime.timedelta` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_TZInfoType
+
+   This instance of :c:type:`PyTypeObject` represents the Python time zone info type;
+   it is the same object as :class:`datetime.tzinfo` in the Python layer.
+
+
 Macro for access to the UTC singleton:
 
 .. c:var:: PyObject* PyDateTime_TimeZone_UTC
@@ -28,7 +71,7 @@ Type-check macros:
 .. c:function:: int PyDate_Check(PyObject *ob)
 
    Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
-   :c:data:`PyDateTime_DateType`.  *ob* must not be ``NULL``.  This function always
+   :c:data:`!PyDateTime_DateType`.  *ob* must not be ``NULL``.  This function always
    succeeds.
 
 
@@ -41,7 +84,7 @@ Type-check macros:
 .. c:function:: int PyDateTime_Check(PyObject *ob)
 
    Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
-   :c:data:`PyDateTime_DateTimeType`.  *ob* must not be ``NULL``.  This function always
+   :c:data:`!PyDateTime_DateTimeType`.  *ob* must not be ``NULL``.  This function always
    succeeds.
 
 
@@ -54,7 +97,7 @@ Type-check macros:
 .. c:function:: int PyTime_Check(PyObject *ob)
 
    Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
-   :c:data:`PyDateTime_TimeType`.  *ob* must not be ``NULL``.  This function always
+   :c:data:`!PyDateTime_TimeType`.  *ob* must not be ``NULL``.  This function always
    succeeds.
 
 
@@ -67,7 +110,7 @@ Type-check macros:
 .. c:function:: int PyDelta_Check(PyObject *ob)
 
    Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
-   :c:data:`PyDateTime_DeltaType`.  *ob* must not be ``NULL``.  This function always
+   :c:data:`!PyDateTime_DeltaType`.  *ob* must not be ``NULL``.  This function always
    succeeds.
 
 
@@ -80,7 +123,7 @@ Type-check macros:
 .. c:function:: int PyTZInfo_Check(PyObject *ob)
 
    Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
-   :c:data:`PyDateTime_TZInfoType`.  *ob* must not be ``NULL``.  This function always
+   :c:data:`!PyDateTime_TZInfoType`.  *ob* must not be ``NULL``.  This function always
    succeeds.
 
 
@@ -133,15 +176,15 @@ Macros to create objects:
    :class:`datetime.timedelta` objects.
 
 
-.. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)
+.. c:function:: PyObject* PyTimeZone_FromOffset(PyObject *offset)
 
    Return a :class:`datetime.timezone` object with an unnamed fixed offset
    represented by the *offset* argument.
 
    .. versionadded:: 3.7
 
 
-.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name)
+.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)
 
    Return a :class:`datetime.timezone` object with a fixed offset represented
    by the *offset* argument and with tzname *name*.
@@ -150,8 +193,8 @@ Macros to create objects:
 
 
 Macros to extract fields from date objects.  The argument must be an instance of
-:c:data:`PyDateTime_Date`, including subclasses (such as
-:c:data:`PyDateTime_DateTime`).  The argument must not be ``NULL``, and the type is
+:c:type:`PyDateTime_Date`, including subclasses (such as
+:c:type:`PyDateTime_DateTime`).  The argument must not be ``NULL``, and the type is
 not checked:
 
 .. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
@@ -170,7 +213,7 @@ not checked:
 
 
 Macros to extract fields from datetime objects.  The argument must be an
-instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument
+instance of :c:type:`PyDateTime_DateTime`, including subclasses. The argument
 must not be ``NULL``, and the type is not checked:
 
 .. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
@@ -208,7 +251,7 @@ must not be ``NULL``, and the type is not checked:
 
 
 Macros to extract fields from time objects.  The argument must be an instance of
-:c:data:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
+:c:type:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
 and the type is not checked:
 
 .. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
@@ -246,7 +289,7 @@ and the type is not checked:
 
 
 Macros to extract fields from time delta objects.  The argument must be an
-instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must
+instance of :c:type:`PyDateTime_Delta`, including subclasses. The argument must
 not be ``NULL``, and the type is not checked:
 
 .. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)

Doc/c-api/exceptions.rst

@@ -222,17 +222,21 @@ For convenience, some of these functions will always return a
 
 .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
 
-   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
-   filename is given as a C string.  *filename* is decoded from the filesystem
-   encoding (:func:`os.fsdecode`).
+   Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior
+   that if *filename* is not ``NULL``, it is decoded from the filesystem
+   encoding (:func:`os.fsdecode`) and passed to the constructor of
+   :exc:`OSError` as a third parameter to be used to define the
+   :attr:`!filename` attribute of the exception instance.
 
    .. availability:: Windows.
 
 
 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
 
-   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
-   additional parameter specifying the exception type to be raised.
+   Similar to :c:func:`PyErr_SetExcFromWindowsErr`, with the additional behavior
+   that if *filename* is not ``NULL``, it is passed to the constructor of
+   :exc:`OSError` as a third parameter to be used to define the
+   :attr:`!filename` attribute of the exception instance.
 
    .. availability:: Windows.
 

Doc/c-api/init_config.rst

@@ -82,6 +82,8 @@ PyWideStringList
    If *length* is non-zero, *items* must be non-``NULL`` and all strings must be
    non-``NULL``.
 
+   .. c:namespace:: NULL
+
    Methods:
 
    .. c:function:: PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)
@@ -101,6 +103,8 @@ PyWideStringList
 
       Python must be preinitialized to call this function.
 
+   .. c:namespace:: PyWideStringList
+
    Structure fields:
 
    .. c:member:: Py_ssize_t length

Doc/c-api/module.rst

@@ -338,6 +338,7 @@ The available slot types are:
    The *value* pointer of this slot must point to a function of the signature:
 
    .. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
+      :noindex:
 
    The function receives a :py:class:`~importlib.machinery.ModuleSpec`
    instance, as defined in :PEP:`451`, and the module definition.
@@ -372,6 +373,7 @@ The available slot types are:
    The signature of the function is:
 
    .. c:function:: int exec_module(PyObject* module)
+      :noindex:
 
    If multiple ``Py_mod_exec`` slots are specified, they are processed in the
    order they appear in the *m_slots* array.
@@ -380,6 +382,8 @@ The available slot types are:
 
    Specifies one of the following values:
 
+   .. c:namespace:: NULL
+
    .. c:macro:: Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED
 
       The module does not support being imported in subinterpreters.

Doc/c-api/unicode.rst

@@ -1292,7 +1292,7 @@ the user settings on the machine running the codec.
 
    Encode the Unicode object using the specified code page and return a Python
    bytes object.  Return ``NULL`` if an exception was raised by the codec. Use
-   :c:macro:`CP_ACP` code page to get the MBCS encoder.
+   :c:macro:`!CP_ACP` code page to get the MBCS encoder.
 
    .. versionadded:: 3.3
 

Doc/extending/newtypes.rst

@@ -298,7 +298,7 @@ have an associated doc string simply by providing the text in the table.  An
 application can use the introspection API to retrieve the descriptor from the
 class object, and get the doc string using its :attr:`__doc__` attribute.
 
-As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.name` value
+As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value
 of ``NULL`` is required.
 
 .. XXX Descriptors need to be explained in more detail somewhere, but not here.

Doc/howto/isolating-extensions.rst

@@ -64,7 +64,7 @@ Enter Per-Module State
 
 Instead of focusing on per-interpreter state, Python's C API is evolving
 to better support the more granular *per-module* state.
-This means that C-level data is be attached to a *module object*.
+This means that C-level data should be attached to a *module object*.
 Each interpreter creates its own module object, keeping the data separate.
 For testing the isolation, multiple module objects corresponding to a single
 extension can even be loaded in a single interpreter.

Doc/library/ast.rst

@@ -2122,10 +2122,12 @@ Async and await
 Apart from the node classes, the :mod:`ast` module defines these utility functions
 and classes for traversing abstract syntax trees:
 
-.. function:: parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None)
+.. function:: parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None, optimize=-1)
 
    Parse the source into an AST node.  Equivalent to ``compile(source,
-   filename, mode, ast.PyCF_ONLY_AST)``.
+   filename, mode, flags=FLAGS_VALUE, optimize=optimize)``,
+   where ``FLAGS_VALUE`` is ``ast.PyCF_ONLY_AST`` if ``optimize <= 0``
+   and ``ast.PyCF_OPTIMIZED_AST`` otherwise.
 
    If ``type_comments=True`` is given, the parser is modified to check
    and return type comments as specified by :pep:`484` and :pep:`526`.
@@ -2171,6 +2173,7 @@ and classes for traversing abstract syntax trees:
 
    .. versionchanged:: 3.13
       The minimum supported version for feature_version is now (3,7)
+      The ``optimize`` argument was added.
 
 
 .. function:: unparse(ast_obj)

Doc/library/asyncio-dev.rst

@@ -99,7 +99,7 @@ To schedule a coroutine object from a different OS thread, the
      # Wait for the result:
      result = future.result()
 
-To handle signals and to execute subprocesses, the event loop must be
+To handle signals the event loop must be
 run in the main thread.
 
 The :meth:`loop.run_in_executor` method can be used with a

Doc/library/enum.rst

@@ -241,6 +241,10 @@ Data Types
         >>> list(reversed(Color))
         [<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]
 
+   .. versionadded:: 3.11
+
+      Before 3.11 ``enum`` used ``EnumMeta`` type, which is kept as an alias.
+
 
 .. class:: Enum
 

Doc/library/io.rst

@@ -1044,6 +1044,22 @@ Text I/O
       .. versionchanged:: 3.11
          The method supports ``encoding="locale"`` option.
 
+   .. method:: seek(cookie, whence=os.SEEK_SET, /)
+
+      Set the stream position.
+      Return the new stream position as an :class:`int`.
+
+      Four operations are supported,
+      given by the following argument combinations:
+
+      * ``seek(0, SEEK_SET)``: Rewind to the start of the stream.
+      * ``seek(cookie, SEEK_SET)``: Restore a previous position;
+        *cookie* **must be** a number returned by :meth:`!tell`.
+      * ``seek(0, SEEK_END)``: Fast-forward to the end of the stream.
+      * ``seek(0, SEEK_CUR)``: Leave the current stream position unchanged.
+
+      Any other argument combinations are invalid,
+      and may raise exceptions.
 
 .. class:: StringIO(initial_value='', newline='\n')
 

Doc/library/sqlite3.rst

@@ -630,6 +630,12 @@ Connection objects
       * :ref:`sqlite3-connection-shortcuts`
       * :ref:`sqlite3-connection-context-manager`
 
+
+   .. versionchanged:: 3.13
+
+      A :exc:`ResourceWarning` is emitted if :meth:`close` is not called before
+      a :class:`!Connection` object is deleted.
+
    An SQLite database connection has the following attributes and methods:
 
    .. method:: cursor(factory=Cursor)
@@ -758,7 +764,7 @@ Connection objects
          ('acbd18db4cc2f85cedef654fccc4a4d8',)
 
 
-   .. method:: create_aggregate(name, /, n_arg, aggregate_class)
+   .. method:: create_aggregate(name, n_arg, aggregate_class)
 
       Create or remove a user-defined SQL aggregate function.
 
@@ -898,7 +904,7 @@ Connection objects
 
          [('a', 9), ('b', 12), ('c', 16), ('d', 12), ('e', 9)]
 
-   .. method:: create_collation(name, callable)
+   .. method:: create_collation(name, callable, /)
 
       Create a collation named *name* using the collating function *callable*.
       *callable* is passed two :class:`string <str>` arguments,

Doc/tools/.nitignore

@@ -2,7 +2,6 @@
 # as tested on the CI via check-warnings.py in reusable-docs.yml.
 # Keep lines sorted lexicographically to help avoid merge conflicts.
 
-Doc/c-api/datetime.rst
 Doc/c-api/descriptor.rst
 Doc/c-api/exceptions.rst
 Doc/c-api/file.rst
@@ -21,7 +20,6 @@ Doc/c-api/structures.rst
 Doc/c-api/sys.rst
 Doc/c-api/type.rst
 Doc/c-api/typeobj.rst
-Doc/c-api/unicode.rst
 Doc/extending/extending.rst
 Doc/extending/newtypes.rst
 Doc/glossary.rst

Doc/using/configure.rst

@@ -185,6 +185,15 @@ General Options
 
    .. versionadded:: 3.11
 
+.. cmdoption:: --disable-gil
+
+   Enables **experimental** support for running Python without the
+   :term:`global interpreter lock` (GIL).
+
+   See :pep:`703` "Making the Global Interpreter Lock Optional in CPython".
+
+   .. versionadded:: 3.13
+
 WebAssembly Options
 -------------------