Merge branch 'master' into sig

Author: Fuyukai

.github/workflows/ci.yml

@@ -88,6 +88,16 @@ jobs:
           - python: '3.8'  # <- not actually used
             pypy_nightly_branch: 'py3.8'
             extra_name: ', pypy 3.8 nightly'
+    continue-on-error: >-
+      ${{
+        (
+          matrix.check_formatting == '1'
+          || matrix.pypy_nightly_branch == 'py3.7'
+          || endsWith(matrix.python, '-dev')
+        )
+        && true
+        || false
+      }}
     steps:
       - name: Checkout
         uses: actions/checkout@v2
@@ -138,3 +148,21 @@ jobs:
         env:
           # Should match 'name:' up above
           JOB_NAME: 'macOS (${{ matrix.python }})'
+
+  # https://github.com/marketplace/actions/alls-green#why
+  check:  # This job does nothing and is only used for the branch protection
+
+    if: always()
+
+    needs:
+      - Windows
+      - Ubuntu
+      - macOS
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}

docs-requirements.in

@@ -1,5 +1,8 @@
 # RTD is currently installing 1.5.3, which has a bug in :lineno-match:
-sphinx >= 1.7.0
+# sphinx-3.4 causes warnings about some trio._abc classes: GH#2338
+sphinx >= 1.7.0, < 3.4
+# jinja2-3.1 causes importerror with sphinx<4.0
+jinja2 < 3.1
 sphinx_rtd_theme
 sphinxcontrib-trio
 towncrier
@@ -13,6 +16,7 @@ async_generator >= 1.9
 idna
 outcome
 sniffio
+exceptiongroup >= 1.0.0rc9
 
 # See note in test-requirements.in
 immutables >= 0.6

docs-requirements.txt

@@ -1,22 +1,22 @@
 #
-# This file is autogenerated by pip-compile
+# This file is autogenerated by pip-compile with python 3.7
 # To update, run:
 #
-#    pip-compile --output-file docs-requirements.txt docs-requirements.in
+#    pip-compile docs-requirements.in
 #
 alabaster==0.7.12
     # via sphinx
 async-generator==1.10
     # via -r docs-requirements.in
-attrs==21.4.0
+attrs==22.1.0
     # via
     #   -r docs-requirements.in
     #   outcome
-babel==2.9.1
+babel==2.11.0
     # via sphinx
-certifi==2022.5.18.1
+certifi==2022.9.24
     # via requests
-charset-normalizer==2.0.12
+charset-normalizer==2.1.1
     # via requests
 click==8.1.3
     # via
@@ -28,35 +28,38 @@ docutils==0.17.1
     # via
     #   sphinx
     #   sphinx-rtd-theme
-idna==3.3
+exceptiongroup==1.0.1
+    # via -r docs-requirements.in
+idna==3.4
     # via
     #   -r docs-requirements.in
     #   requests
-imagesize==1.3.0
+imagesize==1.4.1
     # via sphinx
-immutables==0.18
+immutables==0.19
     # via -r docs-requirements.in
-incremental==21.3.0
+incremental==22.10.0
     # via towncrier
 jinja2==3.0.3
     # via
+    #   -r docs-requirements.in
     #   sphinx
     #   towncrier
 markupsafe==2.1.1
     # via jinja2
-outcome==1.1.0
+outcome==1.2.0
     # via -r docs-requirements.in
 packaging==21.3
     # via sphinx
-pygments==2.10.0
+pygments==2.12.0
     # via sphinx
 pyparsing==3.0.9
     # via packaging
-pytz==2022.1
+pytz==2022.4
     # via babel
-requests==2.27.1
+requests==2.28.1
     # via sphinx
-sniffio==1.2.0
+sniffio==1.3.0
     # via -r docs-requirements.in
 snowballstemmer==2.2.0
     # via sphinx
@@ -67,7 +70,7 @@ sphinx==3.3.1
     #   -r docs-requirements.in
     #   sphinx-rtd-theme
     #   sphinxcontrib-trio
-sphinx-rtd-theme==1.0.0
+sphinx-rtd-theme==1.1.1
     # via -r docs-requirements.in
 sphinxcontrib-applehelp==1.0.2
     # via sphinx
@@ -85,7 +88,10 @@ sphinxcontrib-trio==1.1.2
     # via -r docs-requirements.in
 tomli==2.0.1
     # via towncrier
-towncrier==21.9.0
+towncrier==22.8.0
     # via -r docs-requirements.in
-urllib3==1.26.9
+urllib3==1.26.12
     # via requests
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools

docs/source/code-of-conduct.rst

@@ -78,7 +78,7 @@ Examples of unacceptable behavior by participants include:
    electronic address, without explicit permission. This includes any
    sort of "outing" of any aspect of someone's identity without their
    consent.
--  Publishing private screenshots or quotes of interactions in the
+-  Publishing screenshots or quotes of private interactions in the
    context of this project without all quoted users' *explicit* consent.
 -  Publishing of private communication that doesn't have to do with
    reporting harassment.

docs/source/conf.py

@@ -84,9 +84,11 @@ def setup(app):
     'local_customization',
 ]
 
+# FIXME: change the "python" link back to /3 when Python 3.11 is released
 intersphinx_mapping = {
-    "python": ('https://docs.python.org/3', None),
+    "python": ('https://docs.python.org/3.11', None),
     "outcome": ('https://outcome.readthedocs.io/en/latest/', None),
+    "pyopenssl": ('https://www.pyopenssl.org/en/stable/', None),
 }
 
 autodoc_member_order = "bysource"

docs/source/design.rst

@@ -461,15 +461,9 @@ of our public APIs without having to modify Trio internals.
 Inside ``trio._core``
 ~~~~~~~~~~~~~~~~~~~~~
 
-There are two notable sub-modules that are largely independent of
-the rest of Trio, and could (possibly should?) be extracted into their
-own independent packages:
-
-* ``_multierror.py``: Implements :class:`MultiError` and associated
-  infrastructure.
-
-* ``_ki.py``: Implements the core infrastructure for safe handling of
-  :class:`KeyboardInterrupt`.
+The ``_ki.py`` module implements the core infrastructure for safe handling
+of :class:`KeyboardInterrupt`.  It's largely independent of the rest of Trio,
+and could (possibly should?) be extracted into its own independent package.
 
 The most important submodule, where everything is integrated, is
 ``_run.py``. (This is also by far the largest submodule; it'd be nice

docs/source/history.rst

@@ -5,6 +5,54 @@ Release history
 
 .. towncrier release notes start
 
+Trio 0.22.0 (2022-09-28)
+------------------------
+
+Headline features
+~~~~~~~~~~~~~~~~~
+
+- ``MultiError`` has been deprecated in favor of the standard :exc:`BaseExceptionGroup`
+  (introduced in :pep:`654`). On Python versions below 3.11, this exception and its
+  derivative :exc:`ExceptionGroup` are provided by the backport_. Trio still raises
+  ``MultiError``, but it has been refactored into a subclass of :exc:`BaseExceptionGroup`
+  which users should catch instead of ``MultiError``. Uses of the ``MultiError.filter()``
+  class method should be replaced with :meth:`BaseExceptionGroup.split`. Uses of the
+  ``MultiError.catch()`` class method should be replaced with either ``except*`` clauses
+  (on Python 3.11+) or the ``exceptiongroup.catch()`` context manager provided by the
+  backport_.
+
+  See the :ref:`updated documentation <exceptiongroups>` for details.
+  (`#2211 <https://github.com/python-trio/trio/issues/2211>`__)
+
+  .. _backport: https://pypi.org/project/exceptiongroup/
+
+
+Features
+~~~~~~~~
+
+- Added support for `Datagram TLS
+  <https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security>`__,
+  for secure communication over UDP. Currently requires `PyOpenSSL
+  <https://pypi.org/p/pyopenssl>`__. (`#2010 <https://github.com/python-trio/trio/issues/2010>`__)
+
+
+Trio 0.21.0 (2022-06-07)
+----------------------------
+
+Features
+~~~~~~~~
+
+- Trio now supports Python 3.11. (`#2270
+  <https://github.com/python-trio/trio/issues/2270>`__, `#2318
+  <https://github.com/python-trio/trio/issues/2318>`__, `#2319
+  <https://github.com/python-trio/trio/issues/2319>`__)
+
+Deprecations and Removals
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Remove support for Python 3.6. (`#2210 <https://github.com/python-trio/trio/issues/2210>`__)
+
+
 Trio 0.20.0 (2022-02-21)
 ------------------------
 
@@ -31,8 +79,8 @@ Features
 Bugfixes
 ~~~~~~~~
 
-- Trio now avoids creating cyclic garbage when a `MultiError` is generated and filtered,
-  including invisibly within the cancellation system.  This means errors raised
+- Trio now avoids creating cyclic garbage when a ``MultiError`` is generated and
+  filtered, including invisibly within the cancellation system. This means errors raised
   through nurseries and cancel scopes should result in less GC latency. (`#2063 <https://github.com/python-trio/trio/issues/2063>`__)
 - Trio now deterministically cleans up file descriptors that were opened before
   subprocess creation fails. Previously, they would remain open until the next run of
@@ -271,9 +319,9 @@ Bugfixes
 - On Ubuntu systems, the system Python includes a custom
   unhandled-exception hook to perform `crash reporting
   <https://wiki.ubuntu.com/Apport>`__. Unfortunately, Trio wants to use
-  the same hook to print nice `MultiError` tracebacks, causing a
+  the same hook to print nice ``MultiError`` tracebacks, causing a
   conflict. Previously, Trio would detect the conflict, print a warning,
-  and you just wouldn't get nice `MultiError` tracebacks. Now, Trio has
+  and you just wouldn't get nice ``MultiError`` tracebacks. Now, Trio has
   gotten clever enough to integrate its hook with Ubuntu's, so the two
   systems should Just Work together. (`#1065 <https://github.com/python-trio/trio/issues/1065>`__)
 - Fixed an over-strict test that caused failures on Alpine Linux.
@@ -475,7 +523,7 @@ Features
   violated. (One common source of such violations is an async generator
   that yields within a cancel scope.) The previous behavior was an
   inscrutable chain of TrioInternalErrors. (`#882 <https://github.com/python-trio/trio/issues/882>`__)
-- MultiError now defines its ``exceptions`` attribute in ``__init__()``
+- ``MultiError`` now defines its ``exceptions`` attribute in ``__init__()``
   to better support linters and code autocompletion. (`#1066 <https://github.com/python-trio/trio/issues/1066>`__)
 - Use ``__slots__`` in more places internally, which should make Trio slightly faster. (`#984 <https://github.com/python-trio/trio/issues/984>`__)
 
@@ -496,7 +544,7 @@ Bugfixes
   :meth:`~trio.Path.cwd`, are now async functions.  Previously, a bug
   in the forwarding logic meant :meth:`~trio.Path.cwd` was synchronous
   and :meth:`~trio.Path.home` didn't work at all. (`#960 <https://github.com/python-trio/trio/issues/960>`__)
-- An exception encapsulated within a :class:`MultiError` doesn't need to be
+- An exception encapsulated within a ``MultiError`` doesn't need to be
   hashable anymore.
 
   .. note::
@@ -1287,7 +1335,7 @@ Other changes
   interfering with direct use of
   :func:`~trio.testing.wait_all_tasks_blocked` in the same test.
 
-* :meth:`MultiError.catch` now correctly preserves ``__context__``,
+* ``MultiError.catch()`` now correctly preserves ``__context__``,
   despite Python's best attempts to stop us (`#165
   <https://github.com/python-trio/trio/issues/165>`__)