[requests] Improve type annotations for several HTTPAdapter methods (#15778)

Author: mrhx01

stubs/requests/requests/adapters.pyi

@@ -1,7 +1,7 @@
 from _typeshed import Incomplete
 from collections.abc import Mapping
 from ssl import SSLContext
-from typing import Literal, TypedDict, type_check_only
+from typing import Any, Literal, TypedDict, type_check_only
 from typing_extensions import NotRequired, deprecated
 
 import urllib3
@@ -80,8 +80,27 @@ class HTTPAdapter(BaseAdapter):
         self, pool_connections: int = 10, pool_maxsize: int = 10, max_retries: Retry | int | None = 0, pool_block: bool = False
     ) -> None: ...
     poolmanager: Incomplete
-    def init_poolmanager(self, connections, maxsize, block=False, **pool_kwargs): ...
-    def proxy_manager_for(self, proxy, **proxy_kwargs): ...
+    def init_poolmanager(
+        self,
+        connections: int,
+        maxsize: int,
+        block: bool = False,
+        **pool_kwargs: Any,  # Any: Arbitrary keyword arguments passed directly to urllib3's PoolManager constructor.
+        # Allowed types depend on urllib3 version, but typically include:
+        # ssl_version (int), cert_reqs (str), ca_certs (str), ca_cert_dir (str),
+        # ssl_context (ssl.SSLContext), socket_options (list), etc.
+        # We use Any because the exact set is dynamic and not fully specified in stubs.
+    ) -> None: ...
+    def proxy_manager_for(
+        self,
+        proxy: str,
+        **proxy_kwargs: Any,  # Any: Same as pool_kwargs above, passed to ProxyManager or SOCKSProxyManager.
+        # May include: ssl_context, cert_reqs, ca_certs, ca_cert_dir, etc.
+    ) -> Any:  # Any: Returns either urllib3.ProxyManager (for HTTP/HTTPS proxies) or SOCKSProxyManager (for SOCKS).
+        # The exact return type depends on the proxy scheme and is not needed by callers; using Any avoids
+        # circular imports or complex union types. In practice, the object adheres to a common interface.
+        ...
+
     def cert_verify(self, conn, url, verify, cert): ...
     def build_response(self, req: PreparedRequest, resp: urllib3.BaseHTTPResponse) -> Response: ...
     def build_connection_pool_key_attributes(
@@ -97,9 +116,16 @@ class HTTPAdapter(BaseAdapter):
     @deprecated("Use get_connection_with_tls_context() instead.")
     def get_connection(self, url: _Uri, proxies: Mapping[str, str] | None = None) -> ConnectionPool: ...
     def close(self) -> None: ...
-    def request_url(self, request, proxies): ...
-    def add_headers(self, request, **kwargs): ...
-    def proxy_headers(self, proxy): ...
+    def request_url(self, request: PreparedRequest, proxies: Mapping[str, str] | None) -> str: ...
+    def add_headers(
+        self,
+        request: PreparedRequest,
+        **kwargs: Any,  # Any: Hook method for subclasses to add custom headers.
+        # The kwargs mirror the send() parameters: stream (bool), timeout (float|tuple),
+        # verify (bool|str), cert (str|tuple), proxies (dict). Base implementation ignores them.
+        # Using Any allows subclasses to access these arguments without repeating the full signature.
+    ) -> None: ...
+    def proxy_headers(self, proxy: str) -> dict[str, str]: ...
     def send(
         self,
         request: PreparedRequest,

stubs/requests/requests/utils.pyi

@@ -47,9 +47,9 @@ def dotted_netmask(mask: int) -> str: ...
 def is_ipv4_address(string_ip: str) -> bool: ...
 def is_valid_cidr(string_network: str) -> bool: ...
 def set_environ(env_name: str, value: None) -> _GeneratorContextManager[None]: ...
-def should_bypass_proxies(url: _Uri, no_proxy: Iterable[str] | None) -> bool: ...
+def should_bypass_proxies(url: _Uri, no_proxy: str | None) -> bool: ...
 def get_environ_proxies(url: _Uri, no_proxy: Iterable[str] | None = None) -> dict[Incomplete, Incomplete]: ...
-def select_proxy(url: _Uri, proxies: Mapping[str, str] | None) -> str: ...
+def select_proxy(url: _Uri, proxies: Mapping[str, str] | None) -> str | None: ...
 def resolve_proxies(
     request: Request | PreparedRequest, proxies: dict[str, str] | None, trust_env: bool = True
 ) -> dict[str, str]: ...