Merge branch 'master' into lsp_assets

.coveragerc

@@ -16,13 +16,15 @@ parallel=True
 
 [report]
 precision = 1
+skip_covered = True
 exclude_lines =
   pragma: no cover
   abc.abstractmethod
   if TYPE_CHECKING:
   if _t.TYPE_CHECKING:
   if t.TYPE_CHECKING:
   @overload
+  class .*\bProtocol\b.*\):
 
 partial_branches =
   pragma: no branch

.gitattributes

@@ -2,5 +2,3 @@
 trio/_core/_generated*    linguist-generated=true
 # Treat generated files as binary in git diff
 trio/_core/_generated*    -diff
-# don't merge the generated json file, let the user (script) handle it
-trio/_tests/verify_types.json merge=binary

.github/workflows/ci.yml

@@ -104,8 +104,7 @@ jobs:
     continue-on-error: >-
       ${{
         (
-          matrix.check_formatting == '1'
-          || endsWith(matrix.python, '-dev')
+          endsWith(matrix.python, '-dev')
           || endsWith(matrix.python, '-nightly')
         )
         && true

.gitignore

@@ -49,6 +49,9 @@ pyvenv.cfg
 nosetests.xml
 coverage.xml
 
+# Temp file during Mypy processing
+mypy_annotate.dat
+
 # Translations
 *.mo
 

.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+      - id: check-case-conflict
+  - repo: https://github.com/psf/black
+    rev: 23.7.0
+    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
+    hooks:
+      - id: flake8
+        additional_dependencies:
+          - "flake8-pyproject==1.2.3"
+        types: [file]
+        types_or: [python, pyi]
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.5
+    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

MANIFEST.in

@@ -2,6 +2,7 @@ include LICENSE LICENSE.MIT LICENSE.APACHE2
 include README.rst
 include CODE_OF_CONDUCT.md CONTRIBUTING.md
 include test-requirements.txt
+include trio/py.typed
 recursive-include trio/_tests/test_ssl_certs *.pem
 recursive-include docs *
 prune docs/build

check.sh

@@ -4,49 +4,101 @@ set -ex
 
 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
+fi
+
 # Test if the generated code is still up to date
+echo "::group::Generate Exports"
 python ./trio/_tools/gen_exports.py --test \
     || EXIT_STATUS=$?
+echo "::endgroup::"
 
 # Autoformatter *first*, to avoid double-reporting errors
 # (we'd like to run further autoformatters but *after* merging;
 # see https://forum.bors.tech/t/pre-test-and-pre-merge-hooks/322)
 # autoflake --recursive --in-place .
 # pyupgrade --py3-plus $(find . -name "*.py")
+echo "::group::Black"
 if ! black --check setup.py trio; then
+    echo "* Black found issues" >> $GITHUB_STEP_SUMMARY
     EXIT_STATUS=1
     black --diff setup.py trio
+    echo "::endgroup::"
+    echo "::error:: Black found issues"
+else
+    echo "::endgroup::"
 fi
 
+echo "::group::ISort"
 if ! isort --check setup.py trio; then
+    echo "* isort found issues." >> $GITHUB_STEP_SUMMARY
     EXIT_STATUS=1
     isort --diff setup.py trio
+    echo "::endgroup::"
+    echo "::error:: isort 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 -m trio -m trio.testing --platform linux || EXIT_STATUS=$?
-mypy -m trio -m trio.testing --platform darwin || EXIT_STATUS=$?  # tests FreeBSD too
-mypy -m trio -m trio.testing --platform win32 || EXIT_STATUS=$?
+# MYPY is set if any of them fail.
+MYPY=0
+echo "::group::Mypy"
+# Cleanup previous runs.
+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; }
+# 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; }
+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; }
+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
+# Then discard.
+rm -f mypy_annotate.dat
+echo "::endgroup::"
+# Display a big error if we failed, outside the group so it can't be collapsed.
+if [ $MYPY -ne 0 ]; then
+    echo "::error:: Mypy found type errors."
+    EXIT_STATUS=1
+fi
 
 # Check pip compile is consistent
+echo "::group::Pip Compile - Tests"
 pip-compile test-requirements.in
+echo "::endgroup::"
+echo "::group::Pip Compile - Docs"
 pip-compile docs-requirements.in
+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
     git status --porcelain
     git --no-pager diff --color *requirements.txt
     EXIT_STATUS=1
+    echo "::endgroup::"
 fi
 
 codespell || EXIT_STATUS=$?
 
 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!"
-    git --no-pager diff --color trio/_tests/verify_types.json
+if git status --porcelain trio/_tests/verify_types*.json | grep -q "M"; then
+    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
 
@@ -71,4 +123,5 @@ in your local checkout.
 EOF
     exit 1
 fi
+echo "# Formatting checks succeeded." >> $GITHUB_STEP_SUMMARY
 exit 0

ci.sh

@@ -7,8 +7,10 @@ set -ex -o pipefail
 export PYRIGHT_PYTHON_IGNORE_WARNINGS=1
 
 # Log some general info about the environment
+echo "::group::Environment"
 uname -a
 env | sort
+echo "::endgroup::"
 
 # Curl's built-in retry system is not very robust; it gives up on lots of
 # network errors that we want to retry on. Wget might work better, but it's
@@ -30,8 +32,11 @@ function curl-harder() {
 # We have a Python environment!
 ################################################################
 
-python -c "import sys, struct, ssl; print('#' * 70); print('python:', sys.version); print('version_info:', sys.version_info); print('bits:', struct.calcsize('P') * 8); print('openssl:', ssl.OPENSSL_VERSION, ssl.OPENSSL_VERSION_INFO); print('#' * 70)"
+echo "::group::Versions"
+python -c "import sys, struct, ssl; print('python:', sys.version); print('version_info:', sys.version_info); print('bits:', struct.calcsize('P') * 8); print('openssl:', ssl.OPENSSL_VERSION, ssl.OPENSSL_VERSION_INFO)"
+echo "::endgroup::"
 
+echo "::group::Install dependencies"
 python -m pip install -U pip setuptools wheel
 python -m pip --version
 
@@ -40,6 +45,7 @@ python -m pip install dist/*.zip
 
 if [ "$CHECK_FORMATTING" = "1" ]; then
     python -m pip install -r test-requirements.txt
+    echo "::endgroup::"
     source check.sh
 else
     # Actual tests
@@ -93,6 +99,9 @@ else
         done
         netsh winsock show catalog
     fi
+    echo "::endgroup::"
+
+    echo "::group::Setup for tests"
 
     # We run the tests from inside an empty directory, to make sure Python
     # doesn't pick up any .py files from our working dir. Might have been
@@ -112,11 +121,15 @@ else
     # support subprocess spawning with coverage.py
     echo "import coverage; coverage.process_startup()" | tee -a "$INSTALLDIR/../sitecustomize.py"
 
-    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; then
+    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
         PASSED=true
     else
         PASSED=false
     fi
+    echo "::endgroup::"
+    echo "::group::Coverage"
 
     coverage combine --rcfile ../.coveragerc
     coverage report -m --rcfile ../.coveragerc
@@ -128,5 +141,6 @@ else
         netsh winsock reset
     fi
 
+    echo "::endgroup::"
     $PASSED
 fi

docs-requirements.in

@@ -1,17 +1,15 @@
 # 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, < 6.2
-# jinja2-3.1 causes importerror with sphinx<4.0
-jinja2 < 3.1
+sphinx >= 4.0, < 6.2
+jinja2
 sphinx_rtd_theme
+sphinxcontrib-jquery
 sphinxcontrib-trio
 towncrier
 
 # Trio's own dependencies
 cffi; os_name == "nt"
 attrs >= 19.2.0
 sortedcontainers
-async_generator >= 1.9
 idna
 outcome
 sniffio

docs-requirements.txt

@@ -6,8 +6,6 @@
 #
 alabaster==0.7.13
     # via sphinx
-async-generator==1.10
-    # via -r docs-requirements.in
 attrs==23.1.0
     # via
     #   -r docs-requirements.in
@@ -20,35 +18,35 @@ cffi==1.15.1
     # via cryptography
 charset-normalizer==3.2.0
     # via requests
-click==8.1.6
+click==8.1.7
     # via
     #   click-default-group
     #   towncrier
-click-default-group==1.2.2
+click-default-group==1.2.4
     # via towncrier
-cryptography==41.0.2
+cryptography==41.0.3
     # via pyopenssl
 docutils==0.18.1
     # via
     #   sphinx
     #   sphinx-rtd-theme
-exceptiongroup==1.1.2
+exceptiongroup==1.1.3
     # via -r docs-requirements.in
 idna==3.4
     # via
     #   -r docs-requirements.in
     #   requests
 imagesize==1.4.1
     # via sphinx
-immutables==0.19
+immutables==0.20
     # via -r docs-requirements.in
 importlib-metadata==6.8.0
     # via sphinx
-importlib-resources==6.0.0
+importlib-resources==6.0.1
     # via towncrier
 incremental==22.10.0
     # via towncrier
-jinja2==3.0.3
+jinja2==3.1.2
     # via
     #   -r docs-requirements.in
     #   sphinx
@@ -61,7 +59,7 @@ packaging==23.1
     # via sphinx
 pycparser==2.21
     # via cffi
-pygments==2.15.1
+pygments==2.16.1
     # via sphinx
 pyopenssl==23.2.0
     # via -r docs-requirements.in
@@ -81,7 +79,7 @@ sphinx==6.1.3
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
     #   sphinxcontrib-trio
-sphinx-rtd-theme==1.2.2
+sphinx-rtd-theme==1.3.0
     # via -r docs-requirements.in
 sphinxcontrib-applehelp==1.0.4
     # via sphinx
@@ -90,7 +88,9 @@ sphinxcontrib-devhelp==1.0.2
 sphinxcontrib-htmlhelp==2.0.1
     # via sphinx
 sphinxcontrib-jquery==4.1
-    # via sphinx-rtd-theme
+    # via
+    #   -r docs-requirements.in
+    #   sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-qthelp==1.0.3

docs/Makefile

@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/_static/hackrtd.css

@@ -12,6 +12,11 @@ pre {
     background-color: #ffe13b;
 }
 
+/* Make typevar/paramspec names distinguishable from classes. */
+.typevarref {
+    text-decoration: dashed underline;
+}
+
 /* Add a snakey triskelion ornament to <hr>
  * https://stackoverflow.com/questions/8862344/css-hr-with-ornament/18541258#18541258
  * but only do it to <hr>s in the content box, b/c the RTD popup control panel