Merge branch 'master' into bump_pyright

Author: CoolCat467

.pre-commit-config.yaml

@@ -19,11 +19,11 @@ repos:
       - id: sort-simple-yaml
         files: .pre-commit-config.yaml
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 23.12.0
+    rev: 23.12.1
     hooks:
       - id: black
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.8
+    rev: v0.1.11
     hooks:
       - id: ruff
         types: [file]

check.sh

@@ -57,12 +57,12 @@ echo "::group::Mypy"
 rm -f mypy_annotate.dat
 # Pipefail makes these pipelines fail if mypy does, even if mypy_annotate.py succeeds.
 set -o pipefail
-mypy src/trio --show-error-end --platform linux | python ./src/trio/_tools/mypy_annotate.py --dumpfile mypy_annotate.dat --platform Linux \
+mypy --show-error-end --platform linux | python ./src/trio/_tools/mypy_annotate.py --dumpfile mypy_annotate.dat --platform Linux \
     || { echo "* Mypy (Linux) found type errors." >> "$GITHUB_STEP_SUMMARY"; MYPY=1; }
 # Darwin tests FreeBSD too
-mypy src/trio --show-error-end --platform darwin | python ./src/trio/_tools/mypy_annotate.py --dumpfile mypy_annotate.dat --platform Mac \
+mypy --show-error-end --platform darwin | python ./src/trio/_tools/mypy_annotate.py --dumpfile mypy_annotate.dat --platform Mac \
     || { echo "* Mypy (Mac) found type errors." >> "$GITHUB_STEP_SUMMARY"; MYPY=1; }
-mypy src/trio --show-error-end --platform win32 | python ./src/trio/_tools/mypy_annotate.py --dumpfile mypy_annotate.dat --platform Windows \
+mypy --show-error-end --platform win32 | python ./src/trio/_tools/mypy_annotate.py --dumpfile mypy_annotate.dat --platform Windows \
     || { echo "* Mypy (Windows) found type errors." >> "$GITHUB_STEP_SUMMARY"; MYPY=1; }
 set +o pipefail
 # Re-display errors using Github's syntax, read out of mypy_annotate.dat

docs-requirements.in

@@ -1,5 +1,6 @@
-# RTD is currently installing 1.5.3, which has a bug in :lineno-match:
-sphinx >= 4.0, < 6.2
+# RTD is currently installing 1.5.3, which has a bug in :lineno-match: (??)
+# sphinx 5.3 doesn't work with our _NoValue workaround
+sphinx >= 6.0
 jinja2
 sphinx_rtd_theme
 sphinxcontrib-jquery

docs-requirements.txt

@@ -6,7 +6,7 @@
 #
 alabaster==0.7.13
     # via sphinx
-attrs==23.1.0
+attrs==23.2.0
     # via
     #   -r docs-requirements.in
     #   outcome
@@ -22,7 +22,7 @@ click==8.1.7
     # via towncrier
 cryptography==41.0.7
     # via pyopenssl
-docutils==0.19
+docutils==0.20.1
     # via
     #   sphinx
     #   sphinx-rtd-theme
@@ -36,7 +36,7 @@ imagesize==1.4.1
     # via sphinx
 immutables==0.20
     # via -r docs-requirements.in
-importlib-metadata==7.0.0
+importlib-metadata==7.0.1
     # via sphinx
 importlib-resources==6.1.1
     # via towncrier
@@ -69,7 +69,7 @@ snowballstemmer==2.2.0
     # via sphinx
 sortedcontainers==2.4.0
     # via -r docs-requirements.in
-sphinx==6.1.3
+sphinx==7.1.2
     # via
     #   -r docs-requirements.in
     #   sphinx-rtd-theme

docs/source/conf.py

@@ -16,8 +16,16 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+from __future__ import annotations
+
+import collections.abc
 import os
 import sys
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import Inventory
 
 # For our local_customization module
 sys.path.insert(0, os.path.abspath("."))
@@ -41,6 +49,21 @@
             check=True,
         )
 
+# Sphinx is very finicky, and somewhat buggy, so we have several different
+# methods to help it resolve links.
+# 1. The ones that are not possible to fix are added to `nitpick_ignore`
+# 2. some can be resolved with a simple alias in `autodoc_type_aliases`,
+#    even if that is primarily meant for TypeAliases
+# 3. autodoc_process_signature is hooked up to an event, and we use it for
+#    whole-sale replacing types in signatures where internal details are not
+#    relevant or hard to read.
+# 4. add_intersphinx manually modifies the intersphinx mappings after
+#    objects.inv has been parsed, to resolve bugs and version differences
+#    that causes some objects to be looked up incorrectly.
+# 5. docs/source/typevars.py handles redirecting `typing_extensions` objects to `typing`, and linking `TypeVar`s to `typing.TypeVar` instead of sphinx wanting to link them to their individual definitions.
+# It's possible there's better methods for resolving some of the above
+# problems, but this works for now:tm:
+
 # Warn about all references to unknown targets
 nitpicky = True
 # Except for these ones, which we expect to point to unknown targets:
@@ -51,36 +74,37 @@
     ("py:class", "trio.lowlevel.RunLocal"),
     # trio.abc is documented at random places scattered throughout the docs
     ("py:mod", "trio.abc"),
-    ("py:class", "math.inf"),
     ("py:exc", "Anything else"),
     ("py:class", "async function"),
     ("py:class", "sync function"),
-    # why aren't these found in stdlib?
-    ("py:class", "types.FrameType"),
-    # these are not defined in https://docs.python.org/3/objects.inv
+    # these do not have documentation on python.org
+    # nor entries in objects.inv
     ("py:class", "socket.AddressFamily"),
     ("py:class", "socket.SocketKind"),
-    ("py:class", "Buffer"),  # collections.abc.Buffer, in 3.12
 ]
 autodoc_inherit_docstrings = False
 default_role = "obj"
 
-# These have incorrect __module__ set in stdlib and give the error
-# `py:class reference target not found`
-# Some of the nitpick_ignore's above can probably be fixed with this.
-# See https://github.com/sphinx-doc/sphinx/issues/8315#issuecomment-751335798
+
+# A dictionary for users defined type aliases that maps a type name to the full-qualified object name. It is used to keep type aliases not evaluated in the document.
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_type_aliases
+# but it can also be used to help resolve various linking problems
 autodoc_type_aliases = {
-    # aliasing doesn't actually fix the warning for types.FrameType, but displaying
-    # "types.FrameType" is more helpful than just "frame"
-    "FrameType": "types.FrameType",
     # SSLListener.accept's return type is seen as trio._ssl.SSLStream
     "SSLStream": "trio.SSLStream",
 }
 
 
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#event-autodoc-process-signature
 def autodoc_process_signature(
-    app, what, name, obj, options, signature, return_annotation
-):
+    app: Sphinx,
+    what: object,
+    name: str,
+    obj: object,
+    options: object,
+    signature: str,
+    return_annotation: str,
+) -> tuple[str, str]:
     """Modify found signatures to fix various issues."""
     if signature is not None:
         signature = signature.replace("~_contextvars.Context", "~contextvars.Context")
@@ -103,7 +127,7 @@ def autodoc_process_signature(
 # is shipped (should be in the release after 0.2.4)
 # ...note that this has since grown to contain a bunch of other CSS hacks too
 # though.
-def setup(app):
+def setup(app: Sphinx) -> None:
     app.add_css_file("hackrtd.css")
     app.connect("autodoc-process-signature", autodoc_process_signature)
     # After Intersphinx runs, add additional mappings.
@@ -138,15 +162,49 @@ def setup(app):
 }
 
 
-def add_intersphinx(app) -> None:
-    """Add some specific intersphinx mappings."""
+def add_intersphinx(app: Sphinx) -> None:
+    """Add some specific intersphinx mappings.
+
+    Hooked up to builder-inited. app.builder.env.interpshinx_inventory is not an official API, so this may break on new sphinx versions.
+    """
+
+    def add_mapping(
+        reftype: str,
+        library: str,
+        obj: str,
+        version: str = "3.12",
+        target: str | None = None,
+    ) -> None:
+        """helper function"""
+        url_version = "3" if version == "3.12" else version
+        if target is None:
+            target = f"{library}.{obj}"
+
+        # sphinx doing fancy caching stuff makes this attribute invisible
+        # to type checkers
+        inventory = app.builder.env.intersphinx_inventory  # type: ignore[attr-defined]
+        assert isinstance(inventory, dict)
+        inventory = cast("Inventory", inventory)
+
+        inventory[f"py:{reftype}"][f"{target}"] = (
+            "Python",
+            version,
+            f"https://docs.python.org/{url_version}/library/{library}.html/{obj}",
+            "-",
+        )
+
     # This has been removed in Py3.12, so add a link to the 3.11 version with deprecation warnings.
-    app.builder.env.intersphinx_inventory["py:method"]["pathlib.Path.link_to"] = (
-        "Python",
-        "3.11",
-        "https://docs.python.org/3.11/library/pathlib.html#pathlib.Path.link_to",
-        "-",
-    )
+    add_mapping("method", "pathlib", "Path.link_to", "3.11")
+    # defined in py:data in objects.inv, but sphinx looks for a py:class
+    add_mapping("class", "math", "inf")
+    # `types.FrameType.__module__` is "builtins", so sphinx looks for
+    # builtins.FrameType.
+    # See https://github.com/sphinx-doc/sphinx/issues/11802
+    add_mapping("class", "types", "FrameType")
+    # new in py3.12, and need target because sphinx is unable to look up
+    # the module of the object if compiling on <3.12
+    if not hasattr(collections.abc, "Buffer"):
+        add_mapping("class", "collections.abc", "Buffer", target="Buffer")
 
 
 autodoc_member_order = "bysource"
@@ -193,7 +251,7 @@ def add_intersphinx(app) -> None:
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = []
+exclude_patterns: list[str] = []
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "default"
@@ -252,7 +310,7 @@ def add_intersphinx(app) -> None:
 
 # -- Options for LaTeX output ---------------------------------------------
 
-latex_elements = {
+latex_elements: dict[str, object] = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',

docs/source/local_customization.py

@@ -1,3 +1,7 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 from docutils.parsers.rst import directives as directives
 from sphinx import addnodes
 from sphinx.domains.python import PyClasslike
@@ -8,6 +12,10 @@
     Options as Options,
 )
 
+if TYPE_CHECKING:
+    from sphinx.addnodes import desc_signature
+    from sphinx.application import Sphinx
+
 """
 
 .. interface:: The nursery interface
@@ -18,13 +26,13 @@
 
 
 class Interface(PyClasslike):
-    def handle_signature(self, sig, signode):
+    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
         signode += addnodes.desc_name(sig, sig)
         return sig, ""
 
-    def get_index_text(self, modname, name_cls):
+    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
         return f"{name_cls[0]} (interface in {modname})"
 
 
-def setup(app):
+def setup(app: Sphinx) -> None:
     app.add_directive_to_domain("py", "interface", Interface)

docs/source/reference-core.rst

@@ -768,12 +768,6 @@ inside the handler function(s) with the ``nonlocal`` keyword::
         async with trio.open_nursery() as nursery:
             nursery.start_soon(broken1)
 
-For reasons of backwards compatibility, nurseries raise ``trio.MultiError`` and
-``trio.NonBaseMultiError`` which inherit from :exc:`BaseExceptionGroup` and
-:exc:`ExceptionGroup`, respectively. Users should refrain from attempting to raise or
-catch the Trio specific exceptions themselves, and treat them as if they were standard
-:exc:`BaseExceptionGroup` or :exc:`ExceptionGroup` instances instead.
-
 "Strict" versus "loose" ExceptionGroup semantics
 ++++++++++++++++++++++++++++++++++++++++++++++++
 

docs/source/reference-testing.rst

@@ -219,3 +219,16 @@ Testing checkpoints
 
 .. autofunction:: assert_no_checkpoints
    :with:
+
+
+ExceptionGroup helpers
+----------------------
+
+.. autoclass:: RaisesGroup
+   :members:
+
+.. autoclass:: Matcher
+   :members:
+
+.. autoclass:: trio.testing._raises_group._ExceptionInfo
+   :members:

docs/source/tutorial.rst

@@ -1168,7 +1168,7 @@ TODO: maybe a brief discussion of :exc:`KeyboardInterrupt` handling?
    you can stick anything inside a timeout block, even child tasks
 
      [show something like the first example but with a timeout – they
-     both get cancelled, the cancelleds get packed into a multierror, and
+     both get cancelled, the cancelleds get packed into an ExceptionGroup, and
      then the timeout block catches the cancelled]
 
    brief discussion of KI?

docs/source/typevars.py

@@ -60,7 +60,7 @@ def lookup_reference(
         new_node["reftarget"] = f"typing.{target[18:]}"
         # This fires off this same event, with our new modified node in order to fetch the right
         # URL to use.
-        return app.emit_firstresult(
+        return app.emit_firstresult(  # type: ignore[no-any-return]
             "missing-reference",
             env,
             new_node,

newsfragments/2785.feature.rst

@@ -0,0 +1,4 @@
+New helper classes: :class:`~.testing.RaisesGroup` and :class:`~.testing.Matcher`.
+
+In preparation for changing the default of ``strict_exception_groups`` to `True`, we're introducing a set of helper classes that can be used in place of `pytest.raises <https://docs.pytest.org/en/stable/reference/reference.html#pytest.raises>`_ in tests, to check for an expected `ExceptionGroup`.
+These are provisional, and only planned to be supplied until there's a good solution in ``pytest``. See https://github.com/pytest-dev/pytest/issues/11538

newsfragments/2891.deprecated.rst

@@ -0,0 +1 @@
+``MultiError`` has been fully removed, and all relevant trio functions now raise ExceptionGroups instead. This should not affect end users that have transitioned to using ``except*`` or catching ExceptionGroup/BaseExceptionGroup.

pyproject.toml

@@ -123,7 +123,6 @@ extend-exclude = [
 [tool.ruff.per-file-ignores]
 'src/trio/__init__.py' = ['F401']
 'src/trio/_core/__init__.py' = ['F401']
-'src/trio/_core/_tests/test_multierror_scripts/*' = ['F401']
 'src/trio/abc.py' = ['F401']
 'src/trio/lowlevel.py' = ['F401']
 'src/trio/socket.py' = ['F401']
@@ -137,6 +136,7 @@ fixture-parentheses = false
 
 [tool.mypy]
 python_version = "3.8"
+files = ["src/trio/", "docs/source/*.py"]
 
 # Be flexible about dependencies that don't have stubs yet (like pytest)
 ignore_missing_imports = true
@@ -236,9 +236,6 @@ showcontent = true
 branch = true
 source_pkgs = ["trio"]
 omit = [
-    # These are run in subprocesses, but still don't work. We follow
-    # coverage's documentation to no avail.
-    "*/trio/_core/_tests/test_multierror_scripts/*",
     # Omit the generated files in trio/_core starting with _generated_
     "*/trio/_core/_generated_*",
     # Type tests aren't intended to be run, just passed to type checkers.