Replace public usages of functools.wraps (#2796)

* Replace public usages of `functools.wraps`

* Fix a couple CI errors

* Don't blank out on how `wraps` actually works....

* Don't try to pretend wrapped functions are what they wrap

* Fix pyright type completeness

* Finish off TODO

* Basic type test framework

* Small cleanup

* Also make sure to pass type checking on the type tests!

* Remove some unnecessary imports; oops

* Fix a pytest skipif mistake

* PR review changes

* Forgot to check against pyright too

* Mark wraps as a re-export from `_util` (hopefully flake8 likes this)

* Fix CI errors :(

* Possibly last fixes

* Fix weird mypy errors

* Remove redundent mypy run

---------

Co-authored-by: CoolCat467 <[email protected]>

check.sh

@@ -94,6 +94,7 @@ 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
@@ -102,6 +103,9 @@ if git status --porcelain trio/_tests/verify_types*.json | grep -q "M"; then
     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

trio/_core/_run.py

@@ -72,7 +72,7 @@
 DEADLINE_HEAP_MIN_PRUNE_THRESHOLD: Final = 1000
 
 # Passed as a sentinel
-_NO_SEND: Final = cast("Outcome[Any]", object())
+_NO_SEND: Final["Outcome[Any]"] = cast("Outcome[Any]", object())
 
 FnT = TypeVar("FnT", bound="Callable[..., Any]")
 StatusT = TypeVar("StatusT")

trio/_highlevel_open_tcp_stream.py

@@ -288,7 +288,7 @@ async def open_tcp_stream(
     reorder_for_rfc_6555_section_5_4(targets)
 
     # This list records all the connection failures that we ignored.
-    oserrors = []
+    oserrors: list[OSError] = []
 
     # Keeps track of the socket that we're going to complete with,
     # need to make sure this isn't automatically closed

trio/_path.py

@@ -6,7 +6,7 @@
 import sys
 import types
 from collections.abc import Awaitable, Callable, Iterable
-from functools import partial, wraps
+from functools import partial
 from io import BufferedRandom, BufferedReader, BufferedWriter, FileIO, TextIOWrapper
 from typing import (
     IO,
@@ -22,7 +22,7 @@
 
 import trio
 from trio._file_io import AsyncIOWrapper as _AsyncIOWrapper
-from trio._util import async_wraps, final
+from trio._util import async_wraps, final, wraps
 
 if TYPE_CHECKING:
     from _typeshed import (

trio/_socket.py

@@ -4,7 +4,6 @@
 import select
 import socket as _stdlib_socket
 import sys
-from functools import wraps as _wraps
 from operator import index
 from socket import AddressFamily, SocketKind
 from typing import (
@@ -22,6 +21,7 @@
 import idna as _idna
 
 import trio
+from trio._util import wraps as _wraps
 
 from . import _core
 
@@ -1180,7 +1180,7 @@ async def sendto(
     @_wraps(_stdlib_socket.socket.sendto, assigned=(), updated=())  # type: ignore[misc]
     async def sendto(self, *args: Any) -> int:
         """Similar to :meth:`socket.socket.sendto`, but async."""
-        # args is: data[, flags], address)
+        # args is: data[, flags], address
         # and kwargs are not accepted
         args_list = list(args)
         args_list[-1] = await self._resolve_address_nocp(args[-1], local=False)

trio/_tests/type_tests/check_wraps.py

@@ -0,0 +1,10 @@
+# https://github.com/python-trio/trio/issues/2775#issuecomment-1702267589
+# (except platform independent...)
+import typing_extensions
+
+import trio
+
+
+async def fn(s: trio.SocketStream) -> None:
+    result = await s.socket.sendto(b"a", "h")
+    typing_extensions.assert_type(result, int)

trio/_tests/verify_types_windows.json

@@ -53,6 +53,10 @@
         "message": "No docstring found for function \"trio.run_process\"",
         "name": "trio.run_process"
       },
+      {
+        "message": "No docstring found for function \"trio.socket.fromshare\"",
+        "name": "trio.socket.fromshare"
+      },
       {
         "message": "No docstring found for class \"trio.tests.TestsDeprecationWrapper\"",
         "name": "trio.tests.TestsDeprecationWrapper"
@@ -66,7 +70,7 @@
     "ignoreUnknownTypesFromImports": true,
     "missingClassDocStringCount": 1,
     "missingDefaultParamCount": 0,
-    "missingFunctionDocStringCount": 11,
+    "missingFunctionDocStringCount": 12,
     "moduleName": "trio",
     "modules": [
       {

trio/_util.py

@@ -389,3 +389,18 @@ def name_asyncgen(agen: AsyncGeneratorType[object, t.NoReturn]) -> str:
     except AttributeError:
         qualname = agen.ag_code.co_name
     return f"{module}.{qualname}"
+
+
+# work around a pyright error
+if t.TYPE_CHECKING:
+    Fn = t.TypeVar("Fn", bound=t.Callable[..., object])
+
+    def wraps(
+        wrapped: t.Callable[..., object],
+        assigned: t.Sequence[str] = ...,
+        updated: t.Sequence[str] = ...,
+    ) -> t.Callable[[Fn], Fn]:
+        ...
+
+else:
+    from functools import wraps  # noqa: F401  # this is re-exported