From 1c098522941b6723abce8ca175f2f43a51c18385 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Tue, 26 Jul 2022 09:32:09 -0400
Subject: [PATCH] Add partial types to GAIResolver and associated interfaces.

This corrects the type hints on IHostnameResolver.resolveHostName:

* addressTypes is a sequence of IAddress types, not IAddress instances.
* The return value should be IHostResolution, not IResolutionReceiver.

Ports matrix-org/synapse#11328.
---
 src/twisted/internet/_resolver.py  | 61 ++++++++++++++++++++++++------
 src/twisted/internet/interfaces.py |  5 ++-
 2 files changed, 53 insertions(+), 13 deletions(-)

diff --git a/src/twisted/internet/_resolver.py b/src/twisted/internet/_resolver.py
index 0d057b6a3a5..45e7c8e1812 100644
--- a/src/twisted/internet/_resolver.py
+++ b/src/twisted/internet/_resolver.py
@@ -15,9 +15,22 @@
     AF_UNSPEC,
     SOCK_DGRAM,
     SOCK_STREAM,
+    AddressFamily,
+    SocketKind,
     gaierror,
     getaddrinfo,
 )
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    List,
+    NoReturn,
+    Optional,
+    Sequence,
+    Tuple,
+    Type,
+    Union,
+)
 
 from zope.interface import implementer
 
@@ -26,8 +39,10 @@
 from twisted.internet.defer import Deferred
 from twisted.internet.error import DNSLookupError
 from twisted.internet.interfaces import (
+    IAddress,
     IHostnameResolver,
     IHostResolution,
+    IReactorThreads,
     IResolutionReceiver,
     IResolverSimple,
 )
@@ -35,6 +50,14 @@
 from twisted.logger import Logger
 from twisted.python.compat import nativeString
 
+if TYPE_CHECKING:
+    from twisted.python.runtime import platform
+
+    if platform.supportsThreads():
+        from twisted.python.threadpool import ThreadPool
+    else:
+        ThreadPool = object  # type: ignore[misc, assignment]
+
 
 @implementer(IHostResolution)
 class HostResolution:
@@ -42,13 +65,13 @@ class HostResolution:
     The in-progress resolution of a given hostname.
     """
 
-    def __init__(self, name):
+    def __init__(self, name: str):
         """
         Create a L{HostResolution} with the given name.
         """
         self.name = name
 
-    def cancel(self):
+    def cancel(self) -> NoReturn:
         # IHostResolution.cancel
         raise NotImplementedError()
 
@@ -77,6 +100,17 @@ def cancel(self):
 }
 
 
+_GETADDRINFO_RESULT = List[
+    Tuple[
+        AddressFamily,
+        SocketKind,
+        int,
+        str,
+        Union[Tuple[str, int], Tuple[str, int, int, int]],
+    ]
+]
+
+
 @implementer(IHostnameResolver)
 class GAIResolver:
     """
@@ -84,7 +118,12 @@ class GAIResolver:
     L{getaddrinfo} in a thread.
     """
 
-    def __init__(self, reactor, getThreadPool=None, getaddrinfo=getaddrinfo):
+    def __init__(
+        self,
+        reactor: IReactorThreads,
+        getThreadPool: Optional[Callable[[], "ThreadPool"]] = None,
+        getaddrinfo: Callable[[str, int, int, int], _GETADDRINFO_RESULT] = getaddrinfo,
+    ):
         """
         Create a L{GAIResolver}.
 
@@ -109,12 +148,12 @@ def __init__(self, reactor, getThreadPool=None, getaddrinfo=getaddrinfo):
 
     def resolveHostName(
         self,
-        resolutionReceiver,
-        hostName,
-        portNumber=0,
-        addressTypes=None,
-        transportSemantics="TCP",
-    ):
+        resolutionReceiver: IResolutionReceiver,
+        hostName: str,
+        portNumber: int = 0,
+        addressTypes: Optional[Sequence[Type[IAddress]]] = None,
+        transportSemantics: str = "TCP",
+    ) -> IHostResolution:
         """
         See L{IHostnameResolver.resolveHostName}
 
@@ -136,7 +175,7 @@ def resolveHostName(
         ]
         socketType = _transportToSocket[transportSemantics]
 
-        def get():
+        def get() -> _GETADDRINFO_RESULT:
             try:
                 return self._getaddrinfo(
                     hostName, portNumber, addressFamily, socketType
@@ -149,7 +188,7 @@ def get():
         resolutionReceiver.resolutionBegan(resolution)
 
         @d.addCallback
-        def deliverResults(result):
+        def deliverResults(result: _GETADDRINFO_RESULT) -> None:
             for family, socktype, proto, cannoname, sockaddr in result:
                 addrType = _afToType[family]
                 resolutionReceiver.addressResolved(
diff --git a/src/twisted/internet/interfaces.py b/src/twisted/internet/interfaces.py
index e995391985a..4452f80b6bb 100644
--- a/src/twisted/internet/interfaces.py
+++ b/src/twisted/internet/interfaces.py
@@ -18,6 +18,7 @@
     Optional,
     Sequence,
     Tuple,
+    Type,
     Union,
 )
 
@@ -190,9 +191,9 @@ def resolveHostName(
         resolutionReceiver: IResolutionReceiver,
         hostName: str,
         portNumber: int,
-        addressTypes: Sequence[IAddress],
+        addressTypes: Sequence[Type[IAddress]],
         transportSemantics: str,
-    ) -> IResolutionReceiver:
+    ) -> IHostResolution:
         """
         Initiate a hostname resolution.