change imports to from Y import X as X for compatibility with pyright --verifytypes

.coveragerc

@@ -8,6 +8,8 @@ omit=
   */ipython_custom_exc.py
 # Omit the generated files in trio/_core starting with _generated_
   */trio/_core/_generated_*
+# script used to check type completeness that isn't run in tests
+  */trio/_tests/check_type_completeness.py
 # The test suite spawns subprocesses to test some stuff, so make sure
 # this doesn't corrupt the coverage files
 parallel=True

check.sh

@@ -37,6 +37,13 @@ if git status --porcelain | grep -q "requirements.txt"; then
     EXIT_STATUS=1
 fi
 
+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 diff trio/_tests/verify_types.json
+    EXIT_STATUS=1
+fi
+
 # Finally, leave a really clear warning of any issues and exit
 if [ $EXIT_STATUS -ne 0 ]; then
     cat <<EOF

ci.sh

@@ -2,6 +2,10 @@
 
 set -ex -o pipefail
 
+# disable warnings about pyright being out of date
+# used in test_exports and in check.sh
+export PYRIGHT_PYTHON_IGNORE_WARNINGS=1
+
 # Log some general info about the environment
 uname -a
 env | sort

test-requirements.in

@@ -2,6 +2,7 @@
 pytest >= 5.0         # for faulthandler in core
 pytest-cov >= 2.6.0
 async_generator >= 1.9
+pyright
 # ipython 7.x is the last major version supporting Python 3.7
 ipython < 7.35        # for the IPython traceback integration tests
 pyOpenSSL >= 22.0.0   # for the ssl + DTLS tests

test-requirements.txt

@@ -75,6 +75,8 @@ mypy-extensions==1.0.0 ; implementation_name == "cpython"
     #   -r test-requirements.in
     #   black
     #   mypy
+nodeenv==1.7.0
+    # via pyright
 outcome==1.2.0
     # via -r test-requirements.in
 packaging==23.1
@@ -116,6 +118,8 @@ pyopenssl==23.2.0
     # via -r test-requirements.in
 pyproject-hooks==1.0.0
     # via build
+pyright==1.1.310
+    # via -r test-requirements.in
 pytest==7.3.1
     # via
     #   -r test-requirements.in

trio/__init__.py

@@ -12,87 +12,104 @@
 #
 # This file pulls together the friendly public API, by re-exporting the more
 # innocuous bits of the _core API + the higher-level tools from trio/*.py.
+#
+# Uses `from x import y as y` for compatibility with `pyright --verifytypes` (#2625)
 
+# pyright explicitly does not care about `__version__`
+# see https://github.com/microsoft/pyright/blob/main/docs/typed-libraries.md#type-completeness
 from ._version import __version__
 
 from ._core import (
-    TrioInternalError,
-    RunFinishedError,
-    WouldBlock,
-    Cancelled,
-    BusyResourceError,
-    ClosedResourceError,
-    run,
-    open_nursery,
-    CancelScope,
-    current_effective_deadline,
-    TASK_STATUS_IGNORED,
-    current_time,
-    BrokenResourceError,
-    EndOfChannel,
-    Nursery,
+    TrioInternalError as TrioInternalError,
+    RunFinishedError as RunFinishedError,
+    WouldBlock as WouldBlock,
+    Cancelled as Cancelled,
+    BusyResourceError as BusyResourceError,
+    ClosedResourceError as ClosedResourceError,
+    run as run,
+    open_nursery as open_nursery,
+    CancelScope as CancelScope,
+    current_effective_deadline as current_effective_deadline,
+    TASK_STATUS_IGNORED as TASK_STATUS_IGNORED,
+    current_time as current_time,
+    BrokenResourceError as BrokenResourceError,
+    EndOfChannel as EndOfChannel,
+    Nursery as Nursery,
 )
 
 from ._timeouts import (
-    move_on_at,
-    move_on_after,
-    sleep_forever,
-    sleep_until,
-    sleep,
-    fail_at,
-    fail_after,
-    TooSlowError,
+    move_on_at as move_on_at,
+    move_on_after as move_on_after,
+    sleep_forever as sleep_forever,
+    sleep_until as sleep_until,
+    sleep as sleep,
+    fail_at as fail_at,
+    fail_after as fail_after,
+    TooSlowError as TooSlowError,
 )
 
 from ._sync import (
-    Event,
-    CapacityLimiter,
-    Semaphore,
-    Lock,
-    StrictFIFOLock,
-    Condition,
+    Event as Event,
+    CapacityLimiter as CapacityLimiter,
+    Semaphore as Semaphore,
+    Lock as Lock,
+    StrictFIFOLock as StrictFIFOLock,
+    Condition as Condition,
 )
 
-from ._highlevel_generic import aclose_forcefully, StapledStream
+from ._highlevel_generic import (
+    aclose_forcefully as aclose_forcefully,
+    StapledStream as StapledStream,
+)
 
 from ._channel import (
-    open_memory_channel,
-    MemorySendChannel,
-    MemoryReceiveChannel,
+    open_memory_channel as open_memory_channel,
+    MemorySendChannel as MemorySendChannel,
+    MemoryReceiveChannel as MemoryReceiveChannel,
 )
 
-from ._signals import open_signal_receiver
+from ._signals import open_signal_receiver as open_signal_receiver
 
-from ._highlevel_socket import SocketStream, SocketListener
+from ._highlevel_socket import (
+    SocketStream as SocketStream,
+    SocketListener as SocketListener,
+)
 
-from ._file_io import open_file, wrap_file
+from ._file_io import open_file as open_file, wrap_file as wrap_file
 
-from ._path import Path
+from ._path import Path as Path
 
-from ._subprocess import Process, run_process
+from ._subprocess import Process as Process, run_process as run_process
 
-from ._ssl import SSLStream, SSLListener, NeedHandshakeError
+from ._ssl import (
+    SSLStream as SSLStream,
+    SSLListener as SSLListener,
+    NeedHandshakeError as NeedHandshakeError,
+)
 
-from ._dtls import DTLSEndpoint, DTLSChannel
+from ._dtls import DTLSEndpoint as DTLSEndpoint, DTLSChannel as DTLSChannel
 
-from ._highlevel_serve_listeners import serve_listeners
+from ._highlevel_serve_listeners import serve_listeners as serve_listeners
 
-from ._highlevel_open_tcp_stream import open_tcp_stream
+from ._highlevel_open_tcp_stream import open_tcp_stream as open_tcp_stream
 
-from ._highlevel_open_tcp_listeners import open_tcp_listeners, serve_tcp
+from ._highlevel_open_tcp_listeners import (
+    open_tcp_listeners as open_tcp_listeners,
+    serve_tcp as serve_tcp,
+)
 
-from ._highlevel_open_unix_stream import open_unix_socket
+from ._highlevel_open_unix_stream import open_unix_socket as open_unix_socket
 
 from ._highlevel_ssl_helpers import (
-    open_ssl_over_tcp_stream,
-    open_ssl_over_tcp_listeners,
-    serve_ssl_over_tcp,
+    open_ssl_over_tcp_stream as open_ssl_over_tcp_stream,
+    open_ssl_over_tcp_listeners as open_ssl_over_tcp_listeners,
+    serve_ssl_over_tcp as serve_ssl_over_tcp,
 )
 
 from ._core._multierror import MultiError as _MultiError
 from ._core._multierror import NonBaseMultiError as _NonBaseMultiError
 
-from ._deprecate import TrioDeprecationWarning
+from ._deprecate import TrioDeprecationWarning as TrioDeprecationWarning
 
 # Submodules imported by default
 from . import lowlevel
@@ -106,7 +123,7 @@
 if False:
     from . import testing
 
-from . import _deprecate
+from . import _deprecate as _deprecate
 
 _deprecate.enable_attribute_deprecations(__name__)
 

trio/_tests/check_type_completeness.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+# this file is not run as part of the tests, instead it's run standalone from check.sh
+import subprocess
+import json
+from pathlib import Path
+import sys
+import argparse
+
+# the result file is not marked in MANIFEST.in so it's not included in the package
+RESULT_FILE = Path(__file__).parent / "verify_types.json"
+failed = False
+
+
+# TODO: consider checking manually without `--ignoreexternal`, and/or
+# removing it from the below call later on.
+def run_pyright():
+    return subprocess.run(
+        ["pyright", "--verifytypes=trio", "--outputjson", "--ignoreexternal"],
+        capture_output=True,
+    )
+
+
+def check_less_than(key, current_dict, last_dict, /, invert=False):
+    global failed
+    current = current_dict[key]
+    last = last_dict[key]
+    assert isinstance(current, (float, int))
+    assert isinstance(last, (float, int))
+    if current == last:
+        return
+    if (current > last) ^ invert:
+        failed = True
+        print("ERROR: ", end="")
+    if isinstance(current, float):
+        strcurrent = f"{current:.4}"
+        strlast = f"{last:.4}"
+    else:
+        strcurrent = str(current)
+        strlast = str(last)
+    print(
+        f"{key} has gone {'down' if current<last else 'up'} from {strlast} to {strcurrent}"
+    )
+
+
+def check_zero(key, current_dict):
+    global failed
+    if current_dict[key] != 0:
+        failed = True
+        print(f"ERROR: {key} is {current_dict[key]}")
+
+
+def main(args: argparse.Namespace) -> int:
+    print("*" * 20, "\nChecking type completeness hasn't gone down...")
+
+    res = run_pyright()
+    current_result = json.loads(res.stdout)
+    py_typed_file: Path | None = None
+
+    # check if py.typed file was missing
+    if (
+        current_result["generalDiagnostics"]
+        and current_result["generalDiagnostics"][0]["message"]
+        == "No py.typed file found"
+    ):
+        print("creating py.typed")
+        py_typed_file = (
+            Path(current_result["typeCompleteness"]["packageRootDirectory"])
+            / "py.typed"
+        )
+        py_typed_file.write_text("")
+
+        res = run_pyright()
+        current_result = json.loads(res.stdout)
+
+    if res.stderr:
+        print(res.stderr)
+
+    last_result = json.loads(RESULT_FILE.read_text())
+
+    for key in "errorCount", "warningCount", "informationCount":
+        check_zero(key, current_result["summary"])
+
+    for key, invert in (
+        ("missingFunctionDocStringCount", False),
+        ("missingClassDocStringCount", False),
+        ("missingDefaultParamCount", False),
+        ("completenessScore", True),
+    ):
+        check_less_than(
+            key,
+            current_result["typeCompleteness"],
+            last_result["typeCompleteness"],
+            invert=invert,
+        )
+
+    for key, invert in (
+        ("withUnknownType", False),
+        ("withAmbiguousType", False),
+        ("withKnownType", True),
+    ):
+        check_less_than(
+            key,
+            current_result["typeCompleteness"]["exportedSymbolCounts"],
+            last_result["typeCompleteness"]["exportedSymbolCounts"],
+            invert=invert,
+        )
+
+    assert (
+        res.returncode != 0
+    ), "Fully type complete! Delete this script and instead directly run `pyright --verifytypes=trio` (consider `--ignoreexternal`) in CI and checking exit code."
+
+    if args.overwrite_file:
+        print("Overwriting file")
+
+        # don't care about differences in time taken
+        del current_result["time"]
+        del current_result["summary"]["timeInSec"]
+
+        # don't fail on version diff so pyright updates can be automerged
+        del current_result["version"]
+
+        for key in (
+            # don't save path (because that varies between machines)
+            "moduleRootDirectory",
+            "packageRootDirectory",
+            "pyTypedPath",
+        ):
+            del current_result["typeCompleteness"][key]
+
+        # prune the symbols to only be the name of the symbols with
+        # errors, instead of saving a huge file.
+        new_symbols = []
+        for symbol in current_result["typeCompleteness"]["symbols"]:
+            if symbol["diagnostics"]:
+                new_symbols.append(symbol["name"])
+                continue
+
+        current_result["typeCompleteness"]["symbols"] = new_symbols
+
+        with open(RESULT_FILE, "w") as file:
+            json.dump(current_result, file, sort_keys=True, indent=2)
+            # add newline at end of file so it's easier to manually modify
+            file.write("\n")
+
+    if py_typed_file is not None:
+        print("deleting py.typed")
+        py_typed_file.unlink()
+
+    print("*" * 20)
+
+    return int(failed)
+
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--overwrite-file", action="store_true", default=False)
+args = parser.parse_args()
+
+assert __name__ == "__main__", "This script should be run standalone"
+sys.exit(main(args))