Merge branch 'master' into memory_channel_named_tuple

.coveragerc

@@ -20,11 +20,12 @@ skip_covered = True
 exclude_lines =
   pragma: no cover
   abc.abstractmethod
-  if TYPE_CHECKING:
+  if TYPE_CHECKING.*:
   if _t.TYPE_CHECKING:
   if t.TYPE_CHECKING:
   @overload
   class .*\bProtocol\b.*\):
+  raise NotImplementedError
 
 partial_branches =
   pragma: no branch

.github/workflows/ci.yml

@@ -18,8 +18,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # pypy-3.10 is failing, see https://github.com/python-trio/trio/issues/2678
-        python: ['3.8', '3.9', '3.10', 'pypy-3.9-nightly'] #, 'pypy-3.10-nightly']
+        # pypy 3.9 and 3.10 are failing, see https://github.com/python-trio/trio/issues/2678 and https://github.com/python-trio/trio/issues/2776 respectively
+        python: ['3.8', '3.9', '3.10'] #, 'pypy-3.9-nightly', 'pypy-3.10-nightly']
         arch: ['x86', 'x64']
         lsp: ['']
         lsp_extract_file: ['']
@@ -96,11 +96,16 @@ jobs:
       matrix:
         python: ['pypy-3.9', 'pypy-3.10', '3.8', '3.9', '3.10', '3.11', '3.12-dev', 'pypy-3.9-nightly', 'pypy-3.10-nightly']
         check_formatting: ['0']
+        no_test_requirements: ['0']
         extra_name: ['']
         include:
           - python: '3.8'
             check_formatting: '1'
             extra_name: ', check formatting'
+          # separate test run that doesn't install test-requirements.txt
+          - python: '3.8'
+            no_test_requirements: '1'
+            extra_name: ', no test-requirements'
     continue-on-error: >-
       ${{
         (
@@ -129,6 +134,7 @@ jobs:
         run: ./ci.sh
         env:
           CHECK_FORMATTING: '${{ matrix.check_formatting }}'
+          NO_TEST_REQUIREMENTS: '${{ matrix.no_test_requirements }}'
       - if: always()
         uses: codecov/codecov-action@v3
         with:

.pre-commit-config.yaml

@@ -1,6 +1,13 @@
+ci:
+  autofix_commit_msg: "[pre-commit.ci] auto fixes from pre-commit.com hooks"
+  autofix_prs: false
+  autoupdate_commit_msg: "[pre-commit.ci] pre-commit autoupdate"
+  autoupdate_schedule: weekly
+  submodules: false
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -9,31 +16,20 @@ repos:
       - id: check-merge-conflict
       - id: mixed-line-ending
       - id: check-case-conflict
+      - id: sort-simple-yaml
+        files: .pre-commit-config.yaml
   - repo: https://github.com/psf/black
-    rev: 23.7.0
+    rev: 23.10.1
     hooks:
       - id: black
-  - repo: https://github.com/pycqa/isort
-    rev: 5.12.0
-    hooks:
-      - id: isort
-  - repo: https://github.com/pycqa/flake8
-    rev: 6.1.0
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.1
     hooks:
-      - id: flake8
-        additional_dependencies:
-          - "flake8-pyproject==1.2.3"
+      - id: ruff
         types: [file]
-        types_or: [python, pyi]
+        types_or: [python, pyi, toml]
+        args: ["--show-fixes"]
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.2.5
+    rev: v2.2.6
     hooks:
       - id: codespell
-
-ci:
-  autofix_commit_msg: "[pre-commit.ci] auto fixes from pre-commit.com hooks"
-  autofix_prs: true
-  autoupdate_commit_msg: "[pre-commit.ci] pre-commit autoupdate"
-  autoupdate_schedule: weekly
-  skip: [black,isort]
-  submodules: false

README.rst

@@ -92,8 +92,8 @@ demonstration of implementing the "Happy Eyeballs" algorithm in an
 older library versus Trio.
 
 **Cool, but will it work on my system?** Probably! As long as you have
-some kind of Python 3.8-or-better (CPython or [currently maintained versions of
-PyPy3](https://doc.pypy.org/en/latest/faq.html#which-python-versions-does-pypy-implement)
+some kind of Python 3.8-or-better (CPython or `currently maintained versions of
+PyPy3 <https://doc.pypy.org/en/latest/faq.html#which-python-versions-does-pypy-implement>`__
 are both fine), and are using Linux, macOS, Windows, or FreeBSD, then Trio
 will work. Other environments might work too, but those
 are the ones we test on. And all of our dependencies are pure Python,

check.sh

@@ -2,11 +2,13 @@
 
 set -ex
 
+ON_GITHUB_CI=true
 EXIT_STATUS=0
 
 # If not running on Github's CI, discard the summaries
 if [ -z "${GITHUB_STEP_SUMMARY+x}" ]; then
     GITHUB_STEP_SUMMARY=/dev/null
+    ON_GITHUB_CI=false
 fi
 
 # Test if the generated code is still up to date
@@ -22,7 +24,7 @@ echo "::endgroup::"
 # pyupgrade --py3-plus $(find . -name "*.py")
 echo "::group::Black"
 if ! black --check setup.py trio; then
-    echo "* Black found issues" >> $GITHUB_STEP_SUMMARY
+    echo "* Black found issues" >> "$GITHUB_STEP_SUMMARY"
     EXIT_STATUS=1
     black --diff setup.py trio
     echo "::endgroup::"
@@ -31,22 +33,22 @@ else
     echo "::endgroup::"
 fi
 
-echo "::group::ISort"
-if ! isort --check setup.py trio; then
-    echo "* isort found issues." >> $GITHUB_STEP_SUMMARY
+# Run ruff, configured in pyproject.toml
+echo "::group::Ruff"
+if ! ruff check .; then
+    echo "* ruff found issues." >> "$GITHUB_STEP_SUMMARY"
     EXIT_STATUS=1
-    isort --diff setup.py trio
+    if $ON_GITHUB_CI; then
+        ruff check --output-format github --diff .
+    else
+        ruff check --diff .
+    fi
     echo "::endgroup::"
-    echo "::error:: isort found issues"
+    echo "::error:: ruff found issues"
 else
     echo "::endgroup::"
 fi
 
-# Run flake8, configured in pyproject.toml
-echo "::group::Flake8"
-flake8 trio/ || EXIT_STATUS=$?
-echo "::endgroup::"
-
 # Run mypy on all supported platforms
 # MYPY is set if any of them fail.
 MYPY=0
@@ -56,12 +58,12 @@ rm -f mypy_annotate.dat
 # Pipefail makes these pipelines fail if mypy does, even if mypy_annotate.py succeeds.
 set -o pipefail
 mypy trio --show-error-end --platform linux | python ./trio/_tools/mypy_annotate.py --dumpfile mypy_annotate.dat --platform Linux \
-    || { echo "* Mypy (Linux) found type errors." >> $GITHUB_STEP_SUMMARY; MYPY=1; }
+    || { echo "* Mypy (Linux) found type errors." >> "$GITHUB_STEP_SUMMARY"; MYPY=1; }
 # Darwin tests FreeBSD too
 mypy trio --show-error-end --platform darwin | python ./trio/_tools/mypy_annotate.py --dumpfile mypy_annotate.dat --platform Mac \
-    || { echo "* Mypy (Mac) found type errors." >> $GITHUB_STEP_SUMMARY; MYPY=1; }
+    || { echo "* Mypy (Mac) found type errors." >> "$GITHUB_STEP_SUMMARY"; MYPY=1; }
 mypy trio --show-error-end --platform win32 | python ./trio/_tools/mypy_annotate.py --dumpfile mypy_annotate.dat --platform Windows \
-    || { echo "* Mypy (Windows) found type errors." >> $GITHUB_STEP_SUMMARY; MYPY=1; }
+    || { 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
 python ./trio/_tools/mypy_annotate.py --dumpfile mypy_annotate.dat
@@ -85,23 +87,27 @@ echo "::endgroup::"
 if git status --porcelain | grep -q "requirements.txt"; then
     echo "::error::requirements.txt changed."
     echo "::group::requirements.txt changed"
-    echo "* requirements.txt changed" >> $GITHUB_STEP_SUMMARY
+    echo "* requirements.txt changed" >> "$GITHUB_STEP_SUMMARY"
     git status --porcelain
-    git --no-pager diff --color *requirements.txt
+    git --no-pager diff --color ./*requirements.txt
     EXIT_STATUS=1
     echo "::endgroup::"
 fi
 
 codespell || EXIT_STATUS=$?
 
+echo "::group::Pyright interface tests"
 python trio/_tests/check_type_completeness.py --overwrite-file || EXIT_STATUS=$?
 if git status --porcelain trio/_tests/verify_types*.json | grep -q "M"; then
-    echo "* Type completeness changed, please update!" >> $GITHUB_STEP_SUMMARY
+    echo "* Type completeness changed, please update!" >> "$GITHUB_STEP_SUMMARY"
     echo "::error::Type completeness changed, please update!"
     git --no-pager diff --color trio/_tests/verify_types*.json
     EXIT_STATUS=1
 fi
 
+pyright trio/_tests/type_tests || EXIT_STATUS=$?
+echo "::endgroup::"
+
 # Finally, leave a really clear warning of any issues and exit
 if [ $EXIT_STATUS -ne 0 ]; then
     cat <<EOF
@@ -123,5 +129,5 @@ in your local checkout.
 EOF
     exit 1
 fi
-echo "# Formatting checks succeeded." >> $GITHUB_STEP_SUMMARY
+echo "# Formatting checks succeeded." >> "$GITHUB_STEP_SUMMARY"
 exit 0

ci.sh

@@ -49,7 +49,15 @@ if [ "$CHECK_FORMATTING" = "1" ]; then
     source check.sh
 else
     # Actual tests
-    python -m pip install -r test-requirements.txt
+    # expands to 0 != 1 if NO_TEST_REQUIREMENTS is not set, if set the `-0` has no effect
+    # https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_02
+    if [ ${NO_TEST_REQUIREMENTS-0} == 1 ]; then
+        python -m pip install pytest coverage
+        flags="--skip-optional-imports"
+    else
+        python -m pip install -r test-requirements.txt
+        flags=""
+    fi
 
     # So we can run the test for our apport/excepthook interaction working
     if [ -e /etc/lsb-release ] && grep -q Ubuntu /etc/lsb-release; then
@@ -112,9 +120,6 @@ else
     INSTALLDIR=$(python -c "import os, trio; print(os.path.dirname(trio.__file__))")
     cp ../pyproject.toml $INSTALLDIR
 
-    # TODO: remove this once we have a py.typed file
-    touch "$INSTALLDIR/py.typed"
-
     # get mypy tests a nice cache
     MYPYPATH=".." mypy --config-file= --cache-dir=./.mypy_cache -c "import trio" >/dev/null 2>/dev/null || true
 
@@ -123,7 +128,7 @@ else
 
     echo "::endgroup::"
     echo "::group:: Run Tests"
-    if COVERAGE_PROCESS_START=$(pwd)/../.coveragerc coverage run --rcfile=../.coveragerc -m pytest -r a -p trio._tests.pytest_plugin --junitxml=../test-results.xml --run-slow ${INSTALLDIR} --verbose --durations=10; then
+    if COVERAGE_PROCESS_START=$(pwd)/../.coveragerc coverage run --rcfile=../.coveragerc -m pytest -r a -p trio._tests.pytest_plugin --junitxml=../test-results.xml --run-slow ${INSTALLDIR} --verbose --durations=10 $flags; then
         PASSED=true
     else
         PASSED=false

docs-requirements.txt

@@ -10,21 +10,21 @@ attrs==23.1.0
     # via
     #   -r docs-requirements.in
     #   outcome
-babel==2.12.1
+babel==2.13.0
     # via sphinx
 certifi==2023.7.22
     # via requests
-cffi==1.15.1
+cffi==1.16.0
     # via cryptography
-charset-normalizer==3.2.0
+charset-normalizer==3.3.0
     # via requests
 click==8.1.7
     # via
     #   click-default-group
     #   towncrier
 click-default-group==1.2.4
     # via towncrier
-cryptography==41.0.3
+cryptography==41.0.4
     # via pyopenssl
 docutils==0.18.1
     # via
@@ -42,7 +42,7 @@ immutables==0.20
     # via -r docs-requirements.in
 importlib-metadata==6.8.0
     # via sphinx
-importlib-resources==6.0.1
+importlib-resources==6.1.0
     # via towncrier
 incremental==22.10.0
     # via towncrier
@@ -53,17 +53,17 @@ jinja2==3.1.2
     #   towncrier
 markupsafe==2.1.3
     # via jinja2
-outcome==1.2.0
+outcome==1.3.0
     # via -r docs-requirements.in
-packaging==23.1
+packaging==23.2
     # via sphinx
 pycparser==2.21
     # via cffi
 pygments==2.16.1
     # via sphinx
 pyopenssl==23.2.0
     # via -r docs-requirements.in
-pytz==2023.3
+pytz==2023.3.post1
     # via babel
 requests==2.31.0
     # via sphinx
@@ -103,9 +103,9 @@ tomli==2.0.1
     # via towncrier
 towncrier==23.6.0
     # via -r docs-requirements.in
-urllib3==2.0.4
+urllib3==2.0.7
     # via requests
-zipp==3.16.2
+zipp==3.17.0
     # via
     #   importlib-metadata
     #   importlib-resources

docs/source/conf.py

@@ -54,8 +54,6 @@
     ("py:class", "sync function"),
     # why aren't these found in stdlib?
     ("py:class", "types.FrameType"),
-    # TODO: temporary type
-    ("py:class", "_SocketType"),
     # these are not defined in https://docs.python.org/3/objects.inv
     ("py:class", "socket.AddressFamily"),
     ("py:class", "socket.SocketKind"),
@@ -72,9 +70,9 @@
     # aliasing doesn't actually fix the warning for types.FrameType, but displaying
     # "types.FrameType" is more helpful than just "frame"
     "FrameType": "types.FrameType",
-    # unaliasing these makes intersphinx able to resolve them
-    "Outcome": "outcome.Outcome",
     "Context": "OpenSSL.SSL.Context",
+    # SSLListener.accept's return type is seen as trio._ssl.SSLStream
+    "SSLStream": "trio.SSLStream",
 }
 
 
@@ -84,8 +82,6 @@ def autodoc_process_signature(
     """Modify found signatures to fix various issues."""
     if signature is not None:
         signature = signature.replace("~_contextvars.Context", "~contextvars.Context")
-        if name == "trio.lowlevel.start_guest_run":
-            signature = signature.replace("Outcome", "~outcome.Outcome")
         if name == "trio.lowlevel.RunVar":  # Typevar is not useful here.
             signature = signature.replace(": ~trio._core._local.T", "")
         if "_NoValue" in signature:
@@ -104,6 +100,8 @@ def autodoc_process_signature(
 def setup(app):
     app.add_css_file("hackrtd.css")
     app.connect("autodoc-process-signature", autodoc_process_signature)
+    # After Intersphinx runs, add additional mappings.
+    app.connect("builder-inited", add_intersphinx, priority=1000)
 
 
 # -- General configuration ------------------------------------------------
@@ -133,6 +131,18 @@ def setup(app):
     "sniffio": ("https://sniffio.readthedocs.io/en/latest/", None),
 }
 
+
+def add_intersphinx(app) -> None:
+    """Add some specific intersphinx mappings."""
+    # 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",
+        "-",
+    )
+
+
 autodoc_member_order = "bysource"
 
 # Add any paths that contain templates here, relative to this directory.