Merge branch 'master' into easy-releasing

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ ci:
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -19,11 +19,11 @@ repos:
       - id: sort-simple-yaml
         files: .pre-commit-config.yaml
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 24.3.0
+    rev: 24.4.2
     hooks:
       - id: black
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.3.4
+    rev: v0.4.4
     hooks:
       - id: ruff
         types: [file]

docs-requirements.in

@@ -6,6 +6,8 @@ sphinx_rtd_theme
 sphinxcontrib-jquery
 sphinxcontrib-trio
 towncrier
+sphinx-hoverxref
+sphinx-codeautolink
 
 # Trio's own dependencies
 cffi; os_name == "nt"

docs-requirements.txt

@@ -12,6 +12,8 @@ attrs==23.2.0
     #   outcome
 babel==2.14.0
     # via sphinx
+beautifulsoup4==4.12.3
+    # via sphinx-codeautolink
 certifi==2024.2.2
     # via requests
 cffi==1.16.0
@@ -26,19 +28,19 @@ docutils==0.20.1
     # via
     #   sphinx
     #   sphinx-rtd-theme
-exceptiongroup==1.2.0
+exceptiongroup==1.2.1
     # via -r docs-requirements.in
-idna==3.6
+idna==3.7
     # via
     #   -r docs-requirements.in
     #   requests
 imagesize==1.4.1
     # via sphinx
 immutables==0.20
     # via -r docs-requirements.in
-importlib-metadata==7.0.1
+importlib-metadata==7.1.0
     # via sphinx
-importlib-resources==6.1.2
+importlib-resources==6.4.0
     # via towncrier
 incremental==22.10.0
     # via towncrier
@@ -51,13 +53,13 @@ markupsafe==2.1.5
     # via jinja2
 outcome==1.3.0.post0
     # via -r docs-requirements.in
-packaging==23.2
+packaging==24.0
     # via sphinx
-pycparser==2.21
+pycparser==2.22
     # via cffi
 pygments==2.17.2
     # via sphinx
-pyopenssl==24.0.0
+pyopenssl==24.1.0
     # via -r docs-requirements.in
 pytz==2024.1
     # via babel
@@ -69,12 +71,20 @@ snowballstemmer==2.2.0
     # via sphinx
 sortedcontainers==2.4.0
     # via -r docs-requirements.in
+soupsieve==2.5
+    # via beautifulsoup4
 sphinx==7.1.2
     # via
     #   -r docs-requirements.in
+    #   sphinx-codeautolink
+    #   sphinx-hoverxref
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
     #   sphinxcontrib-trio
+sphinx-codeautolink==0.15.0
+    # via -r docs-requirements.in
+sphinx-hoverxref==1.3.0
+    # via -r docs-requirements.in
 sphinx-rtd-theme==2.0.0
     # via -r docs-requirements.in
 sphinxcontrib-applehelp==1.0.4
@@ -86,6 +96,7 @@ sphinxcontrib-htmlhelp==2.0.1
 sphinxcontrib-jquery==4.1
     # via
     #   -r docs-requirements.in
+    #   sphinx-hoverxref
     #   sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
@@ -101,7 +112,7 @@ towncrier==23.11.0
     # via -r docs-requirements.in
 urllib3==2.2.1
     # via requests
-zipp==3.17.0
+zipp==3.18.1
     # via
     #   importlib-metadata
     #   importlib-resources

docs/source/awesome-trio-libraries.rst

@@ -91,15 +91,15 @@ RPC
 Testing
 -------
 * `pytest-trio <https://github.com/python-trio/pytest-trio>`__ - Pytest plugin for trio.
-* `hypothesis-trio <https://github.com/python-trio/hypothesis-trio>`__ - Hypothesis plugin for trio.
+* `hypothesis-trio <https://github.com/python-trio/hypothesis-trio>`__ - Hypothesis supports Trio out of the box for
+  ``@given(...)`` tests; this extension provides Trio-compatible stateful testing.
 * `trustme <https://github.com/python-trio/trustme>`__ - #1 quality TLS certs while you wait, for the discerning tester.
 * `pytest-aio <https://github.com/klen/pytest-aio>`_ - Pytest plugin with support for trio, curio, asyncio
 * `logot <https://github.com/etianen/logot>`_ - Test whether your async code is logging correctly.
 
 
 Tools and Utilities
 -------------------
-* `trio-typing <https://github.com/python-trio/trio-typing>`__ - Type hints for Trio and related projects.
 * `trio-util <https://github.com/groove-x/trio-util>`__ - An assortment of utilities for the Trio async/await framework.
 * `flake8-trio <https://github.com/Zac-HD/flake8-trio>`__ - Highly opinionated linter for various sorts of problems in Trio and/or AnyIO. Can run as a flake8 plugin, or standalone with support for autofixing some errors.
 * `tricycle <https://github.com/oremanj/tricycle>`__ - This is a library of interesting-but-maybe-not-yet-fully-proven extensions to Trio.
@@ -109,8 +109,9 @@ Tools and Utilities
 * `triotp <https://linkdd.github.io/triotp>`__ - OTP framework for Python Trio
 * `aioresult <https://github.com/arthur-tacca/aioresult>`__ - Get the return value of a background async function in Trio or anyio, along with a simple Future class and wait utilities
 
+
 Trio/Asyncio Interoperability
 -----------------------------
-* `anyio <https://github.com/agronholm/anyio>`__ - AnyIO is a asynchronous compatibility API that allows applications and libraries written against it to run unmodified on asyncio, curio and trio.
+* `anyio <https://github.com/agronholm/anyio>`__ - AnyIO is a asynchronous compatibility API that allows applications and libraries written against it to run unmodified on asyncio or trio.
 * `sniffio <https://github.com/python-trio/sniffio>`__ - This is a tiny package whose only purpose is to let you detect which async library your code is running under.
 * `trio-asyncio <https://github.com/python-trio/trio-asyncio>`__ - Trio-Asyncio lets you use many asyncio libraries from your Trio app.

docs/source/conf.py

@@ -150,6 +150,8 @@ def setup(app: Sphinx) -> None:
     "sphinx.ext.napoleon",
     "sphinxcontrib_trio",
     "sphinxcontrib.jquery",
+    "hoverxref.extension",
+    "sphinx_codeautolink",
     "local_customization",
     "typevars",
 ]
@@ -159,8 +161,34 @@ def setup(app: Sphinx) -> None:
     "outcome": ("https://outcome.readthedocs.io/en/latest/", None),
     "pyopenssl": ("https://www.pyopenssl.org/en/stable/", None),
     "sniffio": ("https://sniffio.readthedocs.io/en/latest/", None),
+    "trio-util": ("https://trio-util.readthedocs.io/en/latest/", None),
 }
 
+# See https://sphinx-hoverxref.readthedocs.io/en/latest/configuration.html
+hoverxref_auto_ref = True
+hoverxref_domains = ["py"]
+# Set the default style (tooltip) for all types to silence logging.
+# See https://github.com/readthedocs/sphinx-hoverxref/issues/211
+hoverxref_role_types = {
+    "attr": "tooltip",
+    "class": "tooltip",
+    "const": "tooltip",
+    "exc": "tooltip",
+    "func": "tooltip",
+    "meth": "tooltip",
+    "mod": "tooltip",
+    "obj": "tooltip",
+    "ref": "tooltip",
+    "data": "tooltip",
+}
+
+# See https://sphinx-codeautolink.readthedocs.io/en/latest/reference.html#configuration
+codeautolink_autodoc_inject = False
+codeautolink_global_preface = """
+import trio
+from trio import *
+"""
+
 
 def add_intersphinx(app: Sphinx) -> None:
     """Add some specific intersphinx mappings.

docs/source/contributing.rst

@@ -199,8 +199,12 @@ you'll have a chance to see and fix any remaining issues then.
 Every change should have 100% coverage for both code and tests. But,
 you can use ``# pragma: no cover`` to mark lines where
 lack-of-coverage isn't something that we'd want to fix (as opposed to
-it being merely hard to fix). For example::
+it being merely hard to fix). For example:
 
+.. code-block:: python
+
+    if ...:
+        ...
     else:  # pragma: no cover
         raise AssertionError("this can't happen!")
 
@@ -289,7 +293,9 @@ Instead of wasting time arguing about code formatting, we use `black
 <https://github.com/psf/black>`__ as well as other tools to automatically
 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::
+just run:
+
+.. code-block::
 
     pip install -U pre-commit
     pre-commit
@@ -301,20 +307,26 @@ names, writing useful comments, and making sure your docstrings are
 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::
+running:
+
+.. code-block::
 
     pre-commit install
 
 and now pre-commit will run before git commits. You can uninstall the
-pre-commit hook at any time by running::
+pre-commit hook at any time by running:
+
+.. code-block::
 
     pre-commit uninstall
 
 
 Very occasionally, you'll want to override black formatting. To do so,
 you can can add ``# fmt: off`` and ``# fmt: on`` comments.
 
-If you want to see what changes black will make, you can use::
+If you want to see what changes black will make, you can use:
+
+.. code-block::
 
     black --diff trio
 
@@ -396,7 +408,9 @@ whitelist in ``docs/source/conf.py``.
 To build the docs locally, use our handy ``docs-requirements.txt``
 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::
+docs directory. The whole process might look something like this:
+
+.. code-block::
 
     cd path/to/project/checkout/
     pip install -r docs-requirements.txt

docs/source/design.rst

@@ -312,7 +312,9 @@ mean.
 This is often a challenging rule to follow – for example, the call
 soon code has to jump through some hoops to make it happen – but its
 most dramatic influence can seen in Trio's task-spawning interface,
-where it motivates the use of "nurseries"::
+where it motivates the use of "nurseries":
+
+.. code-block:: python
 
    async def parent():
        async with trio.open_nursery() as nursery:
@@ -376,18 +378,22 @@ Specific style guidelines
   unconditionally act as cancel+schedule points.
 
 * Any function that takes a callable to run should have a signature
-  like::
+  like:
+
+  .. code-block:: python
 
-     def call_the_thing(fn, *args, kwonly1, kwonly2, ...)::
+     def call_the_thing(fn, *args, kwonly1, kwonly2):
          ...
 
   where ``fn(*args)`` is the thing to be called, and ``kwonly1``,
-  ``kwonly2``, ... are keyword-only arguments that belong to
+  ``kwonly2``, are keyword-only arguments that belong to
   ``call_the_thing``. This applies even if ``call_the_thing`` doesn't
   take any arguments of its own, i.e. in this case its signature looks
-  like::
+  like:
 
-     def call_the_thing(fn, *args)::
+  .. code-block:: python
+
+     def call_the_thing(fn, *args):
          ...
 
   This allows users to skip faffing about with
@@ -410,12 +416,14 @@ Specific style guidelines
   worse, and you get used to the convention pretty quick.
 
 * If it's desirable to have both blocking and non-blocking versions of
-  a function, then they look like::
+  a function, then they look like:
+
+  .. code-block:: python
 
-     async def OPERATION(...):
+     async def OPERATION(arg1, arg2):
          ...
 
-     def OPERATION_nowait(...):
+     def OPERATION_nowait(arg1, arg2):
          ...
 
   and the ``nowait`` version raises :exc:`trio.WouldBlock` if it would block.

docs/source/history.rst

@@ -5,6 +5,15 @@ Release history
 
 .. towncrier release notes start
 
+Trio 0.25.1 (2024-05-16)
+------------------------
+
+Bugfixes
+~~~~~~~~
+
+- Fix crash when importing trio in embedded Python on Windows, and other installs that remove docstrings. (`#2987 <https://github.com/python-trio/trio/issues/2987>`__)
+
+
 Trio 0.25.0 (2024-03-17)
 ------------------------
 
@@ -1248,7 +1257,9 @@ Highlights
 * The new nursery :meth:`~Nursery.start` method makes it
   easy to perform controlled start-up of long-running tasks. For
   example, given an appropriate ``http_server_on_random_open_port``
-  function, you could write::
+  function, you could write:
+
+  .. code-block:: python
 
       port = await nursery.start(http_server_on_random_open_port)
 
@@ -1490,7 +1501,9 @@ Other changes
   functions, if you're using asyncio you have to use asyncio
   functions, and so forth. (See the discussion of the "async sandwich"
   in the Trio tutorial for more details.) So for example, this isn't
-  going to work::
+  going to work:
+
+  .. code-block:: python
 
       async def main():
           # asyncio here