Merge branch 'master' into fix_1271

.github/workflows/ci.yml

@@ -42,7 +42,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Setup python
         uses: actions/setup-python@v2
         with:
@@ -71,12 +71,6 @@ jobs:
     name: 'Ubuntu (${{ matrix.python }}${{ matrix.extra_name }})'
     timeout-minutes: 10
     runs-on: 'ubuntu-latest'
-    # https://docs.github.com/en/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions#changing-github_token-permissions
-    permissions:
-      pull-requests: write
-      issues: write
-      repository-projects: write
-      contents: write
     strategy:
       fail-fast: false
       matrix:
@@ -106,9 +100,7 @@ jobs:
       }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
-        with:
-          ref: ${{ github.event.pull_request.head.ref  }}
+        uses: actions/checkout@v3
       - name: Setup python
         uses: actions/setup-python@v2
         if: "!endsWith(matrix.python, '-dev')"
@@ -128,9 +120,33 @@ jobs:
           CHECK_FORMATTING: '${{ matrix.check_formatting }}'
           # Should match 'name:' up above
           JOB_NAME: 'Ubuntu (${{ matrix.python }}${{ matrix.extra_name }})'
+
+  autofmt:
+    name: Autoformat dependabot PR
+    timeout-minutes: 10
+    if: github.actor == 'dependabot[bot]'
+    runs-on: 'ubuntu-latest'
+    # https://docs.github.com/en/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions#changing-github_token-permissions
+    permissions:
+      pull-requests: write
+      issues: write
+      repository-projects: write
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+      - name: Setup python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+      - name: Check formatting
+        run: |
+          python -m pip install -r test-requirements.txt
+          ./check.sh
       - name: Commit autoformatter changes
-        continue-on-error: true
-        if: failure() && matrix.check_formatting == '1' && github.actor == 'dependabot[bot]'
+        if: failure()
         run: |
           black setup.py trio
           git config user.name 'github-actions[bot]'
@@ -153,7 +169,7 @@ jobs:
             extra_name: ', pypy 3.8 nightly'
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Setup python
         uses: actions/setup-python@v2
         with:

docs-requirements.in

@@ -1,6 +1,6 @@
 # RTD is currently installing 1.5.3, which has a bug in :lineno-match:
 # sphinx-3.4 causes warnings about some trio._abc classes: GH#2338
-sphinx >= 1.7.0, < 3.4
+sphinx >= 1.7.0, < 6.2
 # jinja2-3.1 causes importerror with sphinx<4.0
 jinja2 < 3.1
 sphinx_rtd_theme

docs-requirements.txt

@@ -16,15 +16,15 @@ babel==2.12.1
     # via sphinx
 certifi==2022.12.7
     # via requests
-charset-normalizer==3.0.1
+charset-normalizer==3.1.0
     # via requests
 click==8.1.3
     # via
     #   click-default-group
     #   towncrier
 click-default-group==1.2.2
     # via towncrier
-docutils==0.17.1
+docutils==0.18.1
     # via
     #   sphinx
     #   sphinx-rtd-theme
@@ -38,6 +38,8 @@ imagesize==1.4.1
     # via sphinx
 immutables==0.19
     # via -r docs-requirements.in
+importlib-metadata==6.0.0
+    # via sphinx
 incremental==22.10.0
     # via towncrier
 jinja2==3.0.3
@@ -63,7 +65,7 @@ snowballstemmer==2.2.0
     # via sphinx
 sortedcontainers==2.4.0
     # via -r docs-requirements.in
-sphinx==3.3.1
+sphinx==6.1.3
     # via
     #   -r docs-requirements.in
     #   sphinx-rtd-theme
@@ -92,6 +94,8 @@ towncrier==22.12.0
     # via -r docs-requirements.in
 urllib3==1.26.14
     # via requests
+zipp==3.15.0
+    # via importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
 # setuptools

docs/source/_templates/layout.html

@@ -4,8 +4,13 @@
 {% extends "!layout.html" %}
 
 {% block sidebartitle %}
-<a class="logo" href="{{ pathto(master_doc) }}">
-  <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" />
+
+{# the logo helper function was removed in Sphinx 6 and deprecated since Sphinx 4 #}
+{# the master_doc variable was renamed to root_doc in Sphinx 4 (master_doc still exists in later Sphinx versions) #}
+{# check sphinx_rtd_theme/layout.html:sidebartitle if this snippet has become outdated #}
+
+<a class="logo" href="{{ pathto(root_doc) }}">
+  <img class="logo" src="{{ logo_url }}" />
   {%- set nav_version = version %}
   {% if READTHEDOCS and current_version %}
     {%- set nav_version = current_version %}

docs/source/code-of-conduct.rst

@@ -19,7 +19,7 @@ If you see a Code of Conduct violation, follow these steps:
    them to stop and/or edit their message(s) or commits.
 2. That person should immediately stop the behavior and correct the
    issue.
-3. If this doesn’t happen, or if you're uncomfortable speaking up,
+3. If this doesn't happen, or if you're uncomfortable speaking up,
    :ref:`contact the maintainers <coc-contacting-maintainers>`.
 4. As soon as possible, a maintainer will look into the issue, and take
    :ref:`further action (see below) <coc-further-enforcement>`, starting with

docs/source/conf.py

@@ -54,8 +54,14 @@
     ("py:class", "async function"),
     ("py:class", "sync function"),
     # https://github.com/sphinx-doc/sphinx/issues/7722
-    ("py:class", "SendType"),
-    ("py:class", "ReceiveType"),
+    # TODO: why do these need to be spelled out?
+    ("py:class", "trio._abc.ReceiveType"),
+    ("py:class", "trio._abc.SendType"),
+    ("py:class", "trio._abc.T"),
+    ("py:obj", "trio._abc.ReceiveType"),
+    ("py:obj", "trio._abc.SendType"),
+    ("py:obj", "trio._abc.T"),
+    ("py:obj", "trio._abc.T_resource"),
 ]
 autodoc_inherit_docstrings = False
 default_role = "obj"
@@ -132,7 +138,7 @@ def setup(app):
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/source/contributing.rst

@@ -556,7 +556,8 @@ then we'll figure something out.
 .. Possible references for future additions:
 
    """
-   Jumping into an unfamiliar codebase (or any for that matter) for the first time can be scary. Plus, if it’s your first time contributing to open source, it can even be scarier!
+   Jumping into an unfamiliar codebase (or any for that matter) for the first time can be scary.
+   Plus, if it's your first time contributing to open source, it can even be scarier!
 
    But, we at webpack believe:
 

newsfragments/970.doc.rst

@@ -0,0 +1 @@
+Documented that :obj:`Nursery.start_soon` does not guarantee task ordering.

test-requirements.txt

@@ -6,7 +6,7 @@
 #
 astor==0.8.1
     # via -r test-requirements.in
-astroid==2.14.2
+astroid==2.15.0
     # via pylint
 async-generator==1.10
     # via -r test-requirements.in
@@ -67,7 +67,7 @@ mccabe==0.6.1
     # via
     #   flake8
     #   pylint
-mypy==1.0.0 ; implementation_name == "cpython"
+mypy==1.0.1 ; implementation_name == "cpython"
     # via -r test-requirements.in
 mypy-extensions==1.0.0 ; implementation_name == "cpython"
     # via
@@ -91,7 +91,7 @@ pickleshare==0.7.5
     # via ipython
 pip-tools==6.12.3
     # via -r test-requirements.in
-platformdirs==3.0.0
+platformdirs==3.1.0
     # via
     #   black
     #   pylint
@@ -115,7 +115,7 @@ pyopenssl==23.0.0
     # via -r test-requirements.in
 pyproject-hooks==1.0.0
     # via build
-pytest==7.2.1
+pytest==7.2.2
     # via
     #   -r test-requirements.in
     #   pytest-cov

trio/_channel.py

@@ -17,24 +17,12 @@
 import attr
 from outcome import Error, Value
 
-from .abc import SendChannel, ReceiveChannel, Channel
+from ._abc import SendChannel, ReceiveChannel, Channel, ReceiveType, SendType, T
 from ._util import generic_function, NoPublicConstructor
 
 import trio
 from ._core import enable_ki_protection, Task, Abort, RaiseCancelT
 
-# A regular invariant generic type
-T = TypeVar("T")
-
-# The type of object produced by a ReceiveChannel (covariant because
-# ReceiveChannel[Derived] can be passed to someone expecting
-# ReceiveChannel[Base])
-ReceiveType = TypeVar("ReceiveType", covariant=True)
-
-# The type of object accepted by a SendChannel (contravariant because
-# SendChannel[Base] can be passed to someone expecting
-# SendChannel[Derived])
-SendType = TypeVar("SendType", contravariant=True)
 
 # Temporary TypeVar needed until mypy release supports Self as a type
 SelfT = TypeVar("SelfT")

trio/_core/_run.py

@@ -1022,18 +1022,17 @@ def aborted(raise_cancel):
     def start_soon(self, async_fn, *args, name=None):
         """Creates a child task, scheduling ``await async_fn(*args)``.
 
-        This and :meth:`start` are the two fundamental methods for
+        If you want to run a function and immediately wait for its result,
+        then you don't need a nursery; just use ``await async_fn(*args)``.
+        If you want to wait for the task to initialize itself before
+        continuing, see :meth:`start`, the other fundamental method for
         creating concurrent tasks in Trio.
 
         Note that this is *not* an async function and you don't use await
         when calling it. It sets up the new task, but then returns
-        immediately, *before* it has a chance to run. The new task won’t
-        actually get a chance to do anything until some later point when
-        you execute a checkpoint and the scheduler decides to run it.
-        If you want to run a function and immediately wait for its result,
-        then you don't need a nursery; just use ``await async_fn(*args)``.
-        If you want to wait for the task to initialize itself before
-        continuing, see :meth:`start`.
+        immediately, *before* the new task has a chance to do anything.
+        New tasks may start running in any order, and at any checkpoint the
+        scheduler chooses - at latest when the nursery is waiting to exit.
 
         It's possible to pass a nursery object into another task, which
         allows that task to start new child tasks in the first task's
@@ -1076,9 +1075,9 @@ async def start(self, async_fn, *args, name=None):
         The conventional way to define ``async_fn`` is like::
 
             async def async_fn(arg1, arg2, *, task_status=trio.TASK_STATUS_IGNORED):
-                ...
+                ...  # Caller is blocked waiting for this code to run
                 task_status.started()
-                ...
+                ...  # This async code can be interleaved with the caller
 
         :attr:`trio.TASK_STATUS_IGNORED` is a special global object with
         a do-nothing ``started`` method. This way your function supports