Catch up with main

Author: brandtbucher

.github/CODEOWNERS

@@ -8,7 +8,7 @@
 .github/**                    @ezio-melotti
 
 # asyncio
-**/*asyncio*                  @1st1 @asvetlov @gvanrossum
+**/*asyncio*                  @1st1 @asvetlov @gvanrossum @kumaraditya303
 
 # Core
 **/*context*                  @1st1
@@ -154,3 +154,6 @@ Lib/ast.py                    @isidentical
 
 # pathlib
 **/*pathlib*                  @brettcannon
+
+# zipfile.Path
+**/*zipfile/*_path.py         @jaraco

.github/workflows/doc.yml

@@ -50,9 +50,14 @@ jobs:
       run: make -C Doc/ venv
     - name: 'Check documentation'
       run: make -C Doc/ check
+    - name: 'Upload NEWS'
+      uses: actions/upload-artifact@v3
+      with:
+        name: NEWS
+        path: Doc/build/NEWS
     - name: 'Build HTML documentation'
       run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
-    - name: 'Upload'
+    - name: 'Upload docs'
       uses: actions/upload-artifact@v3
       with:
         name: doc-html

Doc/Makefile

@@ -21,10 +21,7 @@ PAPEROPT_letter = -D latex_elements.papersize=letterpaper
 ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees $(PAPEROPT_$(PAPER)) -j auto \
                 $(SPHINXOPTS) $(SPHINXERRORHANDLING) . build/$(BUILDER) $(SOURCES)
 
-.PHONY: help build html htmlhelp latex text texinfo epub changes linkcheck \
-	coverage doctest pydoc-topics htmlview clean clean-venv venv dist check serve \
-	autobuild-dev autobuild-dev-html autobuild-stable autobuild-stable-html
-
+.PHONY: help
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  clean      to remove build files"
@@ -44,6 +41,7 @@ help:
 	@echo "  dist       to create a \"dist\" directory with archived docs for download"
 	@echo "  check      to run a check for frequent markup errors"
 
+.PHONY: build
 build:
 	-mkdir -p build
 # Look first for a Misc/NEWS file (building from a source release tarball
@@ -70,70 +68,85 @@ build:
 	$(SPHINXBUILD) $(ALLSPHINXOPTS)
 	@echo
 
+.PHONY: html
 html: BUILDER = html
 html: build
 	@echo "Build finished. The HTML pages are in build/html."
 
+.PHONY: htmlhelp
 htmlhelp: BUILDER = htmlhelp
 htmlhelp: build
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      "build/htmlhelp/pydoc.hhp project file."
 
+.PHONY: latex
 latex: BUILDER = latex
 latex: build
 	@echo "Build finished; the LaTeX files are in build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
+.PHONY: text
 text: BUILDER = text
 text: build
 	@echo "Build finished; the text files are in build/text."
 
+.PHONY: texinfo
 texinfo: BUILDER = texinfo
 texinfo: build
 	@echo "Build finished; the python.texi file is in build/texinfo."
 	@echo "Run \`make info' in that directory to run it through makeinfo."
 
+.PHONY: epub
 epub: BUILDER = epub
 epub: build
 	@echo "Build finished; the epub files are in build/epub."
 
+.PHONY: changes
 changes: BUILDER = changes
 changes: build
 	@echo "The overview file is in build/changes."
 
+.PHONY: linkcheck
 linkcheck: BUILDER = linkcheck
 linkcheck:
 	@$(MAKE) build BUILDER=$(BUILDER) || { \
 	echo "Link check complete; look for any errors in the above output" \
 	     "or in build/$(BUILDER)/output.txt"; \
 	false; }
 
+.PHONY: coverage
 coverage: BUILDER = coverage
 coverage: build
 	@echo "Coverage finished; see c.txt and python.txt in build/coverage"
 
+.PHONY: doctest
 doctest: BUILDER = doctest
 doctest:
 	@$(MAKE) build BUILDER=$(BUILDER) || { \
 	echo "Testing of doctests in the sources finished, look at the" \
 	     "results in build/doctest/output.txt"; \
 	false; }
 
+.PHONY: pydoc-topics
 pydoc-topics: BUILDER = pydoc-topics
 pydoc-topics: build
 	@echo "Building finished; now run this:" \
 	      "cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py"
 
+.PHONY: htmlview
 htmlview: html
 	$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))"
 
+.PHONY: clean
 clean: clean-venv
 	-rm -rf build/*
 
+.PHONY: clean-venv
 clean-venv:
 	rm -rf $(VENVDIR)
 
+.PHONY: venv
 venv:
 	@if [ -d $(VENVDIR) ] ; then \
 		echo "venv already exists."; \
@@ -145,6 +158,7 @@ venv:
 		echo "The venv has been created in the $(VENVDIR) directory"; \
 	fi
 
+.PHONY: dist
 dist:
 	rm -rf dist
 	mkdir -p dist
@@ -199,12 +213,14 @@ dist:
 	rm -r dist/python-$(DISTVERSION)-docs-texinfo
 	rm dist/python-$(DISTVERSION)-docs-texinfo.tar
 
+.PHONY: check
 check:
 	# Check the docs and NEWS files with sphinx-lint.
 	# Ignore the tools and venv dirs and check that the default role is not used.
 	$(SPHINXLINT) -i tools -i $(VENVDIR) --enable default-role
 	$(SPHINXLINT) --enable default-role ../Misc/NEWS.d/next/
 
+.PHONY: serve
 serve:
 	@echo "The serve target was removed, use htmlview instead (see bpo-36329)"
 
@@ -216,22 +232,26 @@ serve:
 # output files)
 
 # for development releases: always build
+.PHONY: autobuild-dev
 autobuild-dev:
 	make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
 
 # for quick rebuilds (HTML only)
+.PHONY: autobuild-dev-html
 autobuild-dev-html:
 	make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
 
 # for stable releases: only build if not in pre-release stage (alpha, beta)
 # release candidate downloads are okay, since the stable tree can be in that stage
+.PHONY: autobuild-stable
 autobuild-stable:
 	@case $(DISTVERSION) in *[ab]*) \
 		echo "Not building; $(DISTVERSION) is not a release version."; \
 		exit 1;; \
 	esac
 	@make autobuild-dev
 
+.PHONY: autobuild-stable-html
 autobuild-stable-html:
 	@case $(DISTVERSION) in *[ab]*) \
 		echo "Not building; $(DISTVERSION) is not a release version."; \

Doc/_static/og-image.png

@@ -115,3 +115,51 @@ bound into a function.
    the free variables. On error, ``NULL`` is returned and an exception is raised.
 
    .. versionadded:: 3.11
+
+.. c:function:: int PyCode_AddWatcher(PyCode_WatchCallback callback)
+
+   Register *callback* as a code object watcher for the current interpreter.
+   Return an ID which may be passed to :c:func:`PyCode_ClearWatcher`.
+   In case of error (e.g. no more watcher IDs available),
+   return ``-1`` and set an exception.
+
+   .. versionadded:: 3.12
+
+.. c:function:: int PyCode_ClearWatcher(int watcher_id)
+
+   Clear watcher identified by *watcher_id* previously returned from
+   :c:func:`PyCode_AddWatcher` for the current interpreter.
+   Return ``0`` on success, or ``-1`` and set an exception on error
+   (e.g. if the given *watcher_id* was never registered.)
+
+   .. versionadded:: 3.12
+
+.. c:type:: PyCodeEvent
+
+   Enumeration of possible code object watcher events:
+   - ``PY_CODE_EVENT_CREATE``
+   - ``PY_CODE_EVENT_DESTROY``
+
+   .. versionadded:: 3.12
+
+.. c:type:: int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject* co)
+
+   Type of a code object watcher callback function.
+
+   If *event* is ``PY_CODE_EVENT_CREATE``, then the callback is invoked
+   after `co` has been fully initialized. Otherwise, the callback is invoked
+   before the destruction of *co* takes place, so the prior state of *co*
+   can be inspected.
+
+   Users of this API should not rely on internal runtime implementation
+   details. Such details may include, but are not limited to, the exact
+   order and timing of creation and destruction of code objects. While
+   changes in these details may result in differences observable by watchers
+   (including whether a callback is invoked or not), it does not change
+   the semantics of the Python code being executed.
+
+   If the callback returns with an exception set, it must return ``-1``; this
+   exception will be printed as an unraisable exception using
+   :c:func:`PyErr_WriteUnraisable`. Otherwise it should return ``0``.
+
+   .. versionadded:: 3.12

Doc/c-api/code.rst

@@ -19,6 +19,24 @@ can be used to get a frame object.
 
 See also :ref:`Reflection <reflection>`.
 
+.. c:var:: PyTypeObject PyFrame_Type
+
+   The type of frame objects.
+   It is the same object as :py:class:`types.FrameType` in the Python layer.
+
+   .. versionchanged:: 3.11
+
+      Previously, this type was only available after including
+      ``<frameobject.h>``.
+
+.. c:function:: int PyFrame_Check(PyObject *obj)
+
+   Return non-zero if *obj* is a frame object.
+
+   .. versionchanged:: 3.11
+
+      Previously, this function was only available after including
+      ``<frameobject.h>``.
 
 .. c:function:: PyFrameObject* PyFrame_GetBack(PyFrameObject *frame)
 
@@ -87,6 +105,8 @@ See also :ref:`Reflection <reflection>`.
    * Raise :exc:`NameError` and return ``NULL`` if the variable does not exist.
    * Raise an exception and return ``NULL`` on error.
 
+   *name* type must be a :class:`str`.
+
    .. versionadded:: 3.12
 
 

Doc/c-api/frame.rst

@@ -118,3 +118,63 @@ There are a few functions specific to Python functions.
    must be a dictionary or ``Py_None``.
 
    Raises :exc:`SystemError` and returns ``-1`` on failure.
+
+
+.. c:function:: int PyFunction_AddWatcher(PyFunction_WatchCallback callback)
+
+   Register *callback* as a function watcher for the current interpreter.
+   Return an ID which may be passed to :c:func:`PyFunction_ClearWatcher`.
+   In case of error (e.g. no more watcher IDs available),
+   return ``-1`` and set an exception.
+
+   .. versionadded:: 3.12
+
+
+.. c:function:: int PyFunction_ClearWatcher(int watcher_id)
+
+   Clear watcher identified by *watcher_id* previously returned from
+   :c:func:`PyFunction_AddWatcher` for the current interpreter.
+   Return ``0`` on success, or ``-1`` and set an exception on error
+   (e.g.  if the given *watcher_id* was never registered.)
+
+   .. versionadded:: 3.12
+
+
+.. c:type:: PyFunction_WatchEvent
+
+   Enumeration of possible function watcher events:
+   - ``PyFunction_EVENT_CREATE``
+   - ``PyFunction_EVENT_DESTROY``
+   - ``PyFunction_EVENT_MODIFY_CODE``
+   - ``PyFunction_EVENT_MODIFY_DEFAULTS``
+   - ``PyFunction_EVENT_MODIFY_KWDEFAULTS``
+
+   .. versionadded:: 3.12
+
+
+.. c:type:: int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)
+
+   Type of a function watcher callback function.
+
+   If *event* is ``PyFunction_EVENT_CREATE`` or ``PyFunction_EVENT_DESTROY``
+   then *new_value* will be ``NULL``. Otherwise, *new_value* will hold a
+   :term:`borrowed reference` to the new value that is about to be stored in
+   *func* for the attribute that is being modified.
+
+   The callback may inspect but must not modify *func*; doing so could have
+   unpredictable effects, including infinite recursion.
+
+   If *event* is ``PyFunction_EVENT_CREATE``, then the callback is invoked
+   after `func` has been fully initialized. Otherwise, the callback is invoked
+   before the modification to *func* takes place, so the prior state of *func*
+   can be inspected. The runtime is permitted to optimize away the creation of
+   function objects when possible. In such cases no event will be emitted.
+   Although this creates the possitibility of an observable difference of
+   runtime behavior depending on optimization decisions, it does not change
+   the semantics of the Python code being executed.
+
+   If the callback returns with an exception set, it must return ``-1``; this
+   exception will be printed as an unraisable exception using
+   :c:func:`PyErr_WriteUnraisable`. Otherwise it should return ``0``.
+
+   .. versionadded:: 3.12

Doc/c-api/function.rst

@@ -254,7 +254,7 @@ PyPreConfig
 
    .. c:member:: int configure_locale
 
-      Set the LC_CTYPE locale to the user preferred locale?
+      Set the LC_CTYPE locale to the user preferred locale.
 
       If equals to ``0``, set :c:member:`~PyPreConfig.coerce_c_locale` and
       :c:member:`~PyPreConfig.coerce_c_locale_warn` members to ``0``.