Merge branch 'main' into background_with_channel

jakkdl · web-flow · commit ec61a1fb0ab2 · 2025-03-03T15:05:28.000+01:00
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -24,7 +24,7 @@ repos:
     hooks:
       - id: black
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.9.6
+    rev: v0.9.9
     hooks:
       - id: ruff
         types: [file]
@@ -38,15 +38,15 @@ repos:
           # tomli needed on 3.10. tomllib is available in stdlib on 3.11+
           - tomli
   - repo: https://github.com/crate-ci/typos
-    rev: typos-dict-v0.12.5
+    rev: typos-dict-v0.12.6
     hooks:
       - id: typos
   - repo: https://github.com/sphinx-contrib/sphinx-lint
     rev: v1.0.0
     hooks:
       - id: sphinx-lint
   - repo: https://github.com/woodruffw/zizmor-pre-commit
-    rev: v1.3.1
+    rev: v1.4.1
     hooks:
       - id: zizmor
   - repo: local
@@ -59,7 +59,7 @@ repos:
         additional_dependencies: ["astor", "attrs", "black", "ruff"]
         files: ^src\/trio\/_core\/(_run|(_i(o_(common|epoll|kqueue|windows)|nstrumentation)))\.py$
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.6.1
+    rev: 0.6.3
     hooks:
       # Compile requirements
       - id: pip-compile
diff --git a/README.rst b/README.rst
@@ -56,13 +56,13 @@ I/O-oriented programs easier, less error-prone, and just plain more
 fun. `Perhaps you'll find the same
 <https://github.com/python-trio/trio/wiki/Testimonials>`__.
 
-This project is young and still somewhat experimental: the overall
-design is solid, and the existing features are fully tested and
-documented, but you may encounter missing functionality or rough
-edges. We *do* encourage you to use it, but you should `read and
-subscribe to issue #1
-<https://github.com/python-trio/trio/issues/1>`__ to get a warning and a
-chance to give feedback about any compatibility-breaking changes.
+Trio is a mature and well-tested project: the overall design is solid,
+and the existing features are fully documented and widely used in
+production. While we occasionally make minor interface adjustments,
+breaking changes are rare. We encourage you to use Trio with confidence,
+but if you rely on long-term API stability, consider `subscribing to
+issue #1 <https://github.com/python-trio/trio/issues/1>`__ for advance
+notice of any compatibility updates.
 
 
 Where to next?
diff --git a/docs-requirements.in b/docs-requirements.in
@@ -23,5 +23,4 @@ exceptiongroup >= 1.0.0rc9
 immutables >= 0.6
 
 # types used in annotations
-# TODO: fix support for importing typing-extensions
-pyOpenSSL < 25.0.0
+pyOpenSSL
diff --git a/docs-requirements.txt b/docs-requirements.txt
@@ -8,7 +8,7 @@ attrs==25.1.0
     #   outcome
 babel==2.17.0
     # via sphinx
-beautifulsoup4==4.12.3
+beautifulsoup4==4.13.3
     # via sphinx-codeautolink
 certifi==2025.1.31
     # via requests
@@ -55,10 +55,12 @@ pycparser==2.22 ; os_name == 'nt' or platform_python_implementation != 'PyPy'
     # via cffi
 pygments==2.19.1
     # via sphinx
-pyopenssl==24.3.0
+pyopenssl==25.0.0
     # via -r docs-requirements.in
 requests==2.32.3
     # via sphinx
+roman-numerals-py==3.1.0
+    # via sphinx
 sniffio==1.3.1
     # via -r docs-requirements.in
 snowballstemmer==2.2.0
@@ -67,15 +69,15 @@ sortedcontainers==2.4.0
     # via -r docs-requirements.in
 soupsieve==2.6
     # via beautifulsoup4
-sphinx==8.1.3
+sphinx==8.2.1
     # via
     #   -r docs-requirements.in
     #   sphinx-codeautolink
     #   sphinx-hoverxref
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
     #   sphinxcontrib-trio
-sphinx-codeautolink==0.16.2
+sphinx-codeautolink==0.17.1
     # via -r docs-requirements.in
 sphinx-hoverxref==1.4.2
     # via -r docs-requirements.in
@@ -102,5 +104,9 @@ sphinxcontrib-trio==1.1.2
     # via -r docs-requirements.in
 towncrier==24.8.0
     # via -r docs-requirements.in
+typing-extensions==4.12.2
+    # via
+    #   beautifulsoup4
+    #   pyopenssl
 urllib3==2.3.0
     # via requests
diff --git a/docs/source/code-of-conduct.rst b/docs/source/code-of-conduct.rst
@@ -138,9 +138,9 @@ members. This section covers actual concrete steps.
 Contacting Maintainers
 ~~~~~~~~~~~~~~~~~~~~~~
 
-As a small and young project, we don't yet have a Code of Conduct
-enforcement team. Hopefully that will be addressed as we grow, but for
-now, any issues should be addressed to `Nathaniel J. Smith
+As a small project, we don't have a Code of Conduct enforcement team.
+Hopefully that will be addressed as we grow, but for now, any issues
+should be addressed to `Nathaniel J. Smith
 <https://github.com/njsmith>`__, via `email <mailto:njs@pobox.com>`__
 or any other medium that you feel comfortable with. Using words like
 "Trio code of conduct" in your subject will help make sure your
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -25,6 +25,8 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, cast
 
+from sphinx.util.inventory import _InventoryItem
+
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.util.typing import Inventory
@@ -266,11 +268,11 @@ def add_mapping(
         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}",
-            "-",
+        inventory[f"py:{reftype}"][f"{target}"] = _InventoryItem(
+            project_name="Python",
+            project_version=version,
+            uri=f"https://docs.python.org/{url_version}/library/{library}.html/{obj}",
+            display_name="-",
         )
 
     # This has been removed in Py3.12, so add a link to the 3.11 version with deprecation warnings.
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -318,7 +318,7 @@ format all our code to a standard style. While you're editing code you
 can be as sloppy as you like about whitespace; and then before you commit,
 just run:
 
-.. code-block::
+.. code-block:: text
 
     pip install -U pre-commit
     pre-commit
@@ -332,14 +332,14 @@ nicely formatted. (black doesn't reformat comments or docstrings.)
 If you would like, you can even have pre-commit run before you commit by
 running:
 
-.. code-block::
+.. code-block:: text
 
     pre-commit install
 
 and now pre-commit will run before git commits. You can uninstall the
 pre-commit hook at any time by running:
 
-.. code-block::
+.. code-block:: text
 
     pre-commit uninstall
 
@@ -349,7 +349,7 @@ you can can add ``# fmt: off`` and ``# fmt: on`` comments.
 
 If you want to see what changes black will make, you can use:
 
-.. code-block::
+.. code-block:: text
 
     black --diff trio
 
@@ -433,7 +433,7 @@ file to install all of the required packages (possibly using a
 virtualenv). After that, build the docs using ``make html`` in the
 docs directory. The whole process might look something like this:
 
-.. code-block::
+.. code-block:: text
 
     cd path/to/project/checkout/
     pip install -r docs-requirements.txt
diff --git a/docs/source/history.rst b/docs/source/history.rst
@@ -1504,14 +1504,14 @@ Highlights
 Breaking changes and deprecations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Trio is a young and ambitious project, but it also aims to become a
-stable, production-quality foundation for async I/O in Python.
-Therefore, our approach for now is to provide deprecation warnings
-where-ever possible, but on a fairly aggressive cycle as we push
-towards stability. If you use Trio you should `read and subscribe to
-issue #1 <https://github.com/python-trio/trio/issues/1>`__. We'd also
-welcome feedback on how this approach is working, whether our
-deprecation warnings could be more helpful, or anything else.
+Trio has matured into a stable, production-quality foundation for
+async I/O in Python. While we strive to maintain stability, we may
+make occasional breaking changes to improve the library. Whenever
+possible, we provide deprecation warnings on a reasonable timeline to
+ease transitions. If you use Trio, we recommend `subscribing to issue
+#1 <https://github.com/python-trio/trio/issues/1>`__ to stay informed
+about changes. We also welcome feedback on how our deprecation process
+is working and whether it could be improved.
 
 The tl;dr is: stop using ``socket.bind`` if you can, and then fix
 everything your test suite warns you about.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -33,13 +33,13 @@ the Python I/O library I always wanted; I find it makes building
 I/O-oriented programs easier, less error-prone, and just plain more
 fun. Perhaps you'll find the same.
 
-This project is young and still somewhat experimental: the overall
-design is solid and the existing features are fully tested and
-documented, but you may encounter missing functionality or rough
-edges. We *do* encourage you do use it, but you should `read and
-subscribe to issue #1
-<https://github.com/python-trio/trio/issues/1>`__ to get warning and a
-chance to give feedback about any compatibility-breaking changes.
+Trio is a mature and well-tested library, though it retains its
+“experimental” classification to allow for occasional breaking API
+changes as we push toward a 1.0 release. In practice, such changes are
+rare and typically minor. It is widely used in production environments,
+and we *do* encourage you do use it, but consider `subscribing to issue
+#1 <https://github.com/python-trio/trio/issues/1>`__ to get a warning
+and a chance to give feedback about any compatibility-breaking changes.
 
 Vital statistics:
 
diff --git a/docs/source/reference-core.rst b/docs/source/reference-core.rst
@@ -817,10 +817,10 @@ inside the handler function(s) with the ``nonlocal`` keyword:
 Designing for multiple errors
 +++++++++++++++++++++++++++++
 
-Structured concurrency is still a young design pattern, but there are a few patterns
-we've identified for how you (or your users) might want to handle groups of exceptions.
-Note that the final pattern, simply raising an `ExceptionGroup`, is the most common -
-and nurseries automatically do that for you.
+Structured concurrency is still a relatively new design pattern, but there are a few
+approaches we've identified for how you (or your users) might want to handle groups of
+exceptions. Note that the final pattern, simply raising an `ExceptionGroup`, is the most
+common - and nurseries automatically do that for you.
 
 **First**, you might want to 'defer to' a particular exception type, raising just that if
 there is any such instance in the group.  For example: `KeyboardInterrupt` has a clear
diff --git a/newsfragments/3216.doc.rst b/newsfragments/3216.doc.rst
@@ -0,0 +1 @@
+Update wording in documentation to more accurately reflect Trio's maturity.
diff --git a/pyproject.toml b/pyproject.toml
@@ -14,7 +14,7 @@ keywords = [
     "trio",
 ]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Framework :: Trio",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
diff --git a/src/trio/_core/_instrumentation.py b/src/trio/_core/_instrumentation.py
@@ -2,6 +2,7 @@
 
 import logging
 import types
+from collections import UserDict
 from typing import TYPE_CHECKING, TypeVar
 
 from .._abc import Instrument
@@ -21,7 +22,7 @@ def _public(fn: T) -> T:
     return fn
 
 
-class Instruments(dict[str, dict[Instrument, None]]):
+class Instruments(UserDict[str, dict[Instrument, None]]):
     """A collection of `trio.abc.Instrument` organized by hook.
 
     Instrumentation calls are rather expensive, and we don't want a
@@ -34,7 +35,7 @@ class Instruments(dict[str, dict[Instrument, None]]):
     __slots__ = ()
 
     def __init__(self, incoming: Sequence[Instrument]) -> None:
-        self["_all"] = {}
+        super().__init__({"_all": {}})
         for instrument in incoming:
             self.add_instrument(instrument)
 
@@ -48,9 +49,9 @@ def add_instrument(self, instrument: Instrument) -> None:
         If ``instrument`` is already active, does nothing.
 
         """
-        if instrument in self["_all"]:
+        if instrument in self.data["_all"]:
             return
-        self["_all"][instrument] = None
+        self.data["_all"][instrument] = None
         try:
             for name in dir(instrument):
                 if name.startswith("_"):
@@ -63,7 +64,7 @@ def add_instrument(self, instrument: Instrument) -> None:
                 if isinstance(impl, types.MethodType) and impl.__func__ is prototype:
                     # Inherited unchanged from _abc.Instrument
                     continue
-                self.setdefault(name, {})[instrument] = None
+                self.data.setdefault(name, {})[instrument] = None
         except:
             self.remove_instrument(instrument)
             raise
@@ -83,12 +84,12 @@ def remove_instrument(self, instrument: Instrument) -> None:
 
         """
         # If instrument isn't present, the KeyError propagates out
-        self["_all"].pop(instrument)
-        for hookname, instruments in list(self.items()):
+        self.data["_all"].pop(instrument)
+        for hookname, instruments in list(self.data.items()):
             if instrument in instruments:
                 del instruments[instrument]
                 if not instruments:
-                    del self[hookname]
+                    del self.data[hookname]
 
     def call(
         self,
@@ -103,7 +104,7 @@ def call(
             if "before_task_step" in instruments:
                 instruments.call("before_task_step", task)
         """
-        for instrument in list(self[hookname]):
+        for instrument in list(self.data[hookname]):
             try:
                 getattr(instrument, hookname)(*args)
             except BaseException:
diff --git a/src/trio/_deprecate.py b/src/trio/_deprecate.py
@@ -26,18 +26,18 @@
 class TrioDeprecationWarning(FutureWarning):
     """Warning emitted if you use deprecated Trio functionality.
 
-    As a young project, Trio is currently quite aggressive about deprecating
-    and/or removing functionality that we realize was a bad idea. If you use
-    Trio, you should subscribe to `issue #1
+    While a relatively mature project, Trio remains committed to refining its
+    design and improving usability. As part of this, we occasionally deprecate
+    or remove functionality that proves suboptimal. If you use Trio, we
+    recommend `subscribing to issue #1
     <https://github.com/python-trio/trio/issues/1>`__ to get information about
     upcoming deprecations and other backwards compatibility breaking changes.
 
     Despite the name, this class currently inherits from
-    :class:`FutureWarning`, not :class:`DeprecationWarning`, because while
-    we're in young-and-aggressive mode we want these warnings to be visible by
-    default. You can hide them by installing a filter or with the ``-W``
-    switch: see the :mod:`warnings` documentation for details.
-
+    :class:`FutureWarning`, not :class:`DeprecationWarning`, because until a
+    1.0 release, we want these warnings to be visible by default. You can hide
+    them by installing a filter or with the ``-W`` switch: see the
+    :mod:`warnings` documentation for details.
     """
 
 
diff --git a/src/trio/_tests/test_highlevel_open_tcp_listeners.py b/src/trio/_tests/test_highlevel_open_tcp_listeners.py
@@ -20,7 +20,7 @@
 from trio.testing import open_stream_to_socket_listener
 
 from .. import socket as tsocket
-from .._core._tests.tutil import binds_ipv6
+from .._core._tests.tutil import binds_ipv6, slow
 
 if sys.version_info < (3, 11):
     from exceptiongroup import BaseExceptionGroup
@@ -74,6 +74,7 @@ async def test_open_tcp_listeners_specific_port_specific_host() -> None:
 
 
 @binds_ipv6
+@slow
 async def test_open_tcp_listeners_ipv6_v6only() -> None:
     # Check IPV6_V6ONLY is working properly
     (ipv6_listener,) = await open_tcp_listeners(0, host="::1")
@@ -84,6 +85,8 @@ async def test_open_tcp_listeners_ipv6_v6only() -> None:
             OSError,
             match=r"(Error|all attempts to) connect(ing)* to (\(')*127\.0\.0\.1(', |:)\d+(\): Connection refused| failed)$",
         ):
+            # Windows retries failed connections so this takes seconds
+            # (and that's why this is marked @slow)
             await open_tcp_stream("127.0.0.1", port)
 
 
diff --git a/src/trio/_tests/test_socket.py b/src/trio/_tests/test_socket.py
diff --git a/src/trio/_tests/tools/test_gen_exports.py b/src/trio/_tests/tools/test_gen_exports.py
diff --git a/src/trio/testing/_memory_streams.py b/src/trio/testing/_memory_streams.py
diff --git a/src/trio/testing/_raises_group.py b/src/trio/testing/_raises_group.py
diff --git a/test-requirements.txt b/test-requirements.txt
