Merge remote-tracking branch 'upstream/main' into reduce_dependencty_on_compiler

Author: iritkatriel

.github/workflows/doc.yml

@@ -23,6 +23,7 @@ on:
     paths:
     - 'Doc/**'
     - 'Misc/**'
+    - '.github/workflows/doc.yml'
 
 permissions:
   contents: read
@@ -35,6 +36,38 @@ jobs:
     - uses: actions/checkout@v3
     - name: Register Sphinx problem matcher
       run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
+    - name: 'Set up Python'
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3'
+        cache: 'pip'
+        cache-dependency-path: 'Doc/requirements.txt'
+    - name: 'Install build dependencies'
+      run: make -C Doc/ venv
+    - name: 'Check documentation'
+      run: make -C Doc/ check
+    - name: 'Build HTML documentation'
+      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
+    - name: 'Upload'
+      uses: actions/upload-artifact@v3
+      with:
+        name: doc-html
+        path: Doc/build/html
+
+  # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
+  doctest:
+    name: 'Doctest'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Register Sphinx problem matcher
+      run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
+    - uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ubuntu-doc-${{ hashFiles('Doc/requirements.txt') }}
+        restore-keys: |
+          ubuntu-doc-
     - name: 'Install Dependencies'
       run: sudo ./.github/workflows/posix-deps-apt.sh && sudo apt-get install wamerican
     - name: 'Configure CPython'
@@ -43,17 +76,6 @@ jobs:
       run: make -j4
     - name: 'Install build dependencies'
       run: make -C Doc/ PYTHON=../python venv
-    # Run "check doctest html" as 3 steps to get a more readable output
-    # in the web UI
-    - name: 'Check documentation'
-      run: make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going" check
     # Use "xvfb-run" since some doctest tests open GUI windows
     - name: 'Run documentation doctest'
-      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going" doctest
-    - name: 'Build HTML documentation'
-      run: make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going" html
-    - name: 'Upload'
-      uses: actions/upload-artifact@v3
-      with:
-        name: doc-html
-        path: Doc/build/html
+      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" doctest

Doc/c-api/sys.rst

@@ -21,10 +21,12 @@ Operating System Utilities
 
    Return true (nonzero) if the standard I/O file *fp* with name *filename* is
    deemed interactive.  This is the case for files for which ``isatty(fileno(fp))``
-   is true.  If the global flag :c:data:`Py_InteractiveFlag` is true, this function
+   is true.  If the :c:member:`PyConfig.interactive` is non-zero, this function
    also returns true if the *filename* pointer is ``NULL`` or if the name is equal to
    one of the strings ``'<stdin>'`` or ``'???'``.
 
+   This function must not be called before Python is initialized.
+
 
 .. c:function:: void PyOS_BeforeFork()
 

Doc/library/socket.rst

@@ -2076,10 +2076,10 @@ the interface::
    # Include IP headers
    s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)
 
-   # receive all packages
+   # receive all packets
    s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)
 
-   # receive a package
+   # receive a packet
    print(s.recvfrom(65565))
 
    # disabled promiscuous mode

Doc/library/sqlite3.rst

@@ -336,9 +336,9 @@ Module functions and constants
    float, str or bytes.
 
 
-.. function:: complete_statement(sql)
+.. function:: complete_statement(statement)
 
-   Returns :const:`True` if the string *sql* contains one or more complete SQL
+   Returns :const:`True` if the string *statement* contains one or more complete SQL
    statements terminated by semicolons. It does not verify that the SQL is
    syntactically correct, only that there are no unclosed string literals and the
    statement is terminated by a semicolon.
@@ -457,11 +457,11 @@ Connection Objects
       :meth:`~Cursor.executescript` on it with the given *sql_script*.
       Return the new cursor object.
 
-   .. method:: create_function(name, num_params, func, *, deterministic=False)
+   .. method:: create_function(name, narg, func, *, deterministic=False)
 
       Creates a user-defined function that you can later use from within SQL
-      statements under the function name *name*. *num_params* is the number of
-      parameters the function accepts (if *num_params* is -1, the function may
+      statements under the function name *name*. *narg* is the number of
+      parameters the function accepts (if *narg* is -1, the function may
       take any number of arguments), and *func* is a Python callable that is
       called as the SQL function. If *deterministic* is true, the created function
       is marked as `deterministic <https://sqlite.org/deterministic.html>`_, which
@@ -480,12 +480,12 @@ Connection Objects
       .. literalinclude:: ../includes/sqlite3/md5func.py
 
 
-   .. method:: create_aggregate(name, num_params, aggregate_class)
+   .. method:: create_aggregate(name, n_arg, aggregate_class)
 
       Creates a user-defined aggregate function.
 
       The aggregate class must implement a ``step`` method, which accepts the number
-      of parameters *num_params* (if *num_params* is -1, the function may take
+      of parameters *n_arg* (if *n_arg* is -1, the function may take
       any number of arguments), and a ``finalize`` method which will return the
       final result of the aggregate.
 
@@ -580,15 +580,15 @@ Connection Objects
          Added support for disabling the authorizer using :const:`None`.
 
 
-   .. method:: set_progress_handler(handler, n)
+   .. method:: set_progress_handler(progress_handler, n)
 
       This routine registers a callback. The callback is invoked for every *n*
       instructions of the SQLite virtual machine. This is useful if you want to
       get called from SQLite during long-running operations, for example to update
       a GUI.
 
       If you want to clear any previously installed progress handler, call the
-      method with :const:`None` for *handler*.
+      method with :const:`None` for *progress_handler*.
 
       Returning a non-zero value from the handler function will terminate the
       currently executing query and cause it to raise a :exc:`DatabaseError`
@@ -628,7 +628,7 @@ Connection Objects
 
       Loadable extensions are disabled by default. See [#f1]_.
 
-      .. audit-event:: sqlite3.enable_load_extension connection,enabled sqlite3.enable_load_extension
+      .. audit-event:: sqlite3.enable_load_extension connection,enabled sqlite3.Connection.enable_load_extension
 
       .. versionadded:: 3.2
 
@@ -645,7 +645,7 @@ Connection Objects
 
       Loadable extensions are disabled by default. See [#f1]_.
 
-      .. audit-event:: sqlite3.load_extension connection,path sqlite3.load_extension
+      .. audit-event:: sqlite3.load_extension connection,path sqlite3.Connection.load_extension
 
       .. versionadded:: 3.2
 

Doc/library/test.rst

@@ -413,6 +413,51 @@ The :mod:`test.support` module defines the following constants:
 
 The :mod:`test.support` module defines the following functions:
 
+.. function:: busy_retry(timeout, err_msg=None, /, *, error=True)
+
+   Run the loop body until ``break`` stops the loop.
+
+   After *timeout* seconds, raise an :exc:`AssertionError` if *error* is true,
+   or just stop the loop if *error* is false.
+
+   Example::
+
+       for _ in support.busy_retry(support.SHORT_TIMEOUT):
+           if check():
+               break
+
+   Example of error=False usage::
+
+       for _ in support.busy_retry(support.SHORT_TIMEOUT, error=False):
+           if check():
+               break
+       else:
+           raise RuntimeError('my custom error')
+
+.. function:: sleeping_retry(timeout, err_msg=None, /, *, init_delay=0.010, max_delay=1.0, error=True)
+
+   Wait strategy that applies exponential backoff.
+
+   Run the loop body until ``break`` stops the loop. Sleep at each loop
+   iteration, but not at the first iteration. The sleep delay is doubled at
+   each iteration (up to *max_delay* seconds).
+
+   See :func:`busy_retry` documentation for the parameters usage.
+
+   Example raising an exception after SHORT_TIMEOUT seconds::
+
+       for _ in support.sleeping_retry(support.SHORT_TIMEOUT):
+           if check():
+               break
+
+   Example of error=False usage::
+
+       for _ in support.sleeping_retry(support.SHORT_TIMEOUT, error=False):
+           if check():
+               break
+       else:
+           raise RuntimeError('my custom error')
+
 .. function:: is_resource_enabled(resource)
 
    Return ``True`` if *resource* is enabled and available. The list of

Doc/whatsnew/3.12.rst

@@ -184,6 +184,14 @@ Removed
   * ``sqlite3.enable_shared_cache()``
   * ``sqlite3.OptimizedUnicode``
 
+  If a shared cache must be used, open the database in URI mode using the
+  ``cache=shared`` query parameter.
+
+  The ``sqlite3.OptimizedUnicode`` text factory has been an alias for
+  :class:`str` since Python 3.3. Code that previously set the text factory to
+  ``OptimizedUnicode`` can either use ``str`` explicitly, or rely on the
+  default value which is also ``str``.
+
   (Contributed by Erlend E. Aasland in :gh:`92548`)
 
 * The ``--experimental-isolated-subinterpreters`` configure flag

Include/boolobject.h

@@ -9,7 +9,7 @@ extern "C" {
 
 PyAPI_DATA(PyTypeObject) PyBool_Type;
 
-#define PyBool_Check(x) Py_IS_TYPE(x, &PyBool_Type)
+#define PyBool_Check(x) Py_IS_TYPE((x), &PyBool_Type)
 
 /* Py_False and Py_True are the only two bools in existence.
 Don't forget to apply Py_INCREF() when returning either!!! */

Include/bytearrayobject.h

@@ -21,8 +21,8 @@ PyAPI_DATA(PyTypeObject) PyByteArray_Type;
 PyAPI_DATA(PyTypeObject) PyByteArrayIter_Type;
 
 /* Type check macros */
-#define PyByteArray_Check(self) PyObject_TypeCheck(self, &PyByteArray_Type)
-#define PyByteArray_CheckExact(self) Py_IS_TYPE(self, &PyByteArray_Type)
+#define PyByteArray_Check(self) PyObject_TypeCheck((self), &PyByteArray_Type)
+#define PyByteArray_CheckExact(self) Py_IS_TYPE((self), &PyByteArray_Type)
 
 /* Direct API functions */
 PyAPI_FUNC(PyObject *) PyByteArray_FromObject(PyObject *);

Include/bytesobject.h

@@ -29,7 +29,7 @@ PyAPI_DATA(PyTypeObject) PyBytesIter_Type;
 
 #define PyBytes_Check(op) \
                  PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_BYTES_SUBCLASS)
-#define PyBytes_CheckExact(op) Py_IS_TYPE(op, &PyBytes_Type)
+#define PyBytes_CheckExact(op) Py_IS_TYPE((op), &PyBytes_Type)
 
 PyAPI_FUNC(PyObject *) PyBytes_FromStringAndSize(const char *, Py_ssize_t);
 PyAPI_FUNC(PyObject *) PyBytes_FromString(const char *);

Include/complexobject.h

@@ -10,8 +10,8 @@ extern "C" {
 
 PyAPI_DATA(PyTypeObject) PyComplex_Type;
 
-#define PyComplex_Check(op) PyObject_TypeCheck(op, &PyComplex_Type)
-#define PyComplex_CheckExact(op) Py_IS_TYPE(op, &PyComplex_Type)
+#define PyComplex_Check(op) PyObject_TypeCheck((op), &PyComplex_Type)
+#define PyComplex_CheckExact(op) Py_IS_TYPE((op), &PyComplex_Type)
 
 PyAPI_FUNC(PyObject *) PyComplex_FromDoubles(double real, double imag);