Add more typing hints for requests (#7696)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> Co-authored-by: Akuli <akuviljanen17@gmail.com>
2025-12-08 21:14:48 +08:00 · 2022-04-27 13:40:20 +02:00
parent fa4677424a
commit ae09e4e866
3 changed files with 211 additions and 212 deletions
--- a/stubs/requests/@tests/stubtest_allowlist.txt
+++ b/stubs/requests/@tests/stubtest_allowlist.txt
@@ -1,39 +1,9 @@
-requests.Session.delete
-requests.Session.get
-requests.Session.head
-requests.Session.options
-requests.Session.patch
-requests.Session.post
-requests.Session.put
 requests.adapters.PoolManager.connection_from_host
 requests.adapters.PoolManager.connection_from_url
 requests.adapters.PoolManager.urlopen
-requests.api.delete
-requests.api.get
-requests.api.head
-requests.api.options
-requests.api.patch
-requests.api.post
-requests.api.put
-requests.api.request
-requests.delete
-requests.get
-requests.head
 requests.models.RequestField.__init__
 requests.models.RequestField.from_tuples
-requests.options
 requests.packages.VendorAlias
-requests.patch
-requests.post
-requests.put
-requests.request
-requests.sessions.Session.delete
-requests.sessions.Session.get
-requests.sessions.Session.head
-requests.sessions.Session.options
-requests.sessions.Session.patch
-requests.sessions.Session.post
-requests.sessions.Session.put
 requests.sessions.SessionRedirectMixin.resolve_redirects
 requests.structures.LookupDict.__getattr__
 requests.structures.LookupDict.get
--- a/stubs/requests/requests/api.pyi
+++ b/stubs/requests/requests/api.pyi
@@ -1,142 +1,150 @@
 from typing import Any

 from .models import Response
-from .sessions import _Data, _Params
+from .sessions import RequestsCookieJar, _Auth, _Cert, _Data, _Files, _HooksInput, _Params, _TextMapping, _Timeout, _Verify

 def request(
    method: str | bytes,
    url: str | bytes,
+    *,
    params: _Params | None = ...,
-    data: Any | None = ...,
-    headers: Any | None = ...,
-    cookies: Any | None = ...,
-    files: Any | None = ...,
-    auth: Any | None = ...,
-    timeout: Any | None = ...,
+    data: _Data | None = ...,
+    headers: _TextMapping | None = ...,
+    cookies: RequestsCookieJar | _TextMapping | None = ...,
+    files: _Files | None = ...,
+    auth: _Auth | None = ...,
+    timeout: _Timeout | None = ...,
    allow_redirects: bool = ...,
-    proxies: Any | None = ...,
-    hooks: Any | None = ...,
-    stream: Any | None = ...,
-    verify: Any | None = ...,
-    cert: Any | None = ...,
+    proxies: _TextMapping | None = ...,
+    hooks: _HooksInput | None = ...,
+    stream: bool | None = ...,
+    verify: _Verify | None = ...,
+    cert: _Cert | None = ...,
    json: Any | None = ...,
 ) -> Response: ...
 def get(
    url: str | bytes,
    params: _Params | None = ...,
-    data: Any | None = ...,
-    headers: Any | None = ...,
-    cookies: Any | None = ...,
-    files: Any | None = ...,
-    auth: Any | None = ...,
-    timeout: Any | None = ...,
+    *,
+    data: _Data | None = ...,
+    headers: _TextMapping | None = ...,
+    cookies: RequestsCookieJar | _TextMapping | None = ...,
+    files: _Files | None = ...,
+    auth: _Auth | None = ...,
+    timeout: _Timeout | None = ...,
    allow_redirects: bool = ...,
-    proxies: Any | None = ...,
-    hooks: Any | None = ...,
-    stream: Any | None = ...,
-    verify: Any | None = ...,
-    cert: Any | None = ...,
+    proxies: _TextMapping | None = ...,
+    hooks: _HooksInput | None = ...,
+    stream: bool | None = ...,
+    verify: _Verify | None = ...,
+    cert: _Cert | None = ...,
    json: Any | None = ...,
 ) -> Response: ...
 def options(
    url: str | bytes,
+    *,
    params: _Params | None = ...,
-    data: Any | None = ...,
-    headers: Any | None = ...,
-    cookies: Any | None = ...,
-    files: Any | None = ...,
-    auth: Any | None = ...,
-    timeout: Any | None = ...,
+    data: _Data | None = ...,
+    headers: _TextMapping | None = ...,
+    cookies: RequestsCookieJar | _TextMapping | None = ...,
+    files: _Files | None = ...,
+    auth: _Auth | None = ...,
+    timeout: _Timeout | None = ...,
    allow_redirects: bool = ...,
-    proxies: Any | None = ...,
-    hooks: Any | None = ...,
-    stream: Any | None = ...,
-    verify: Any | None = ...,
-    cert: Any | None = ...,
+    proxies: _TextMapping | None = ...,
+    hooks: _HooksInput | None = ...,
+    stream: bool | None = ...,
+    verify: _Verify | None = ...,
+    cert: _Cert | None = ...,
    json: Any | None = ...,
 ) -> Response: ...
 def head(
    url: str | bytes,
+    *,
    params: _Params | None = ...,
-    data: Any | None = ...,
-    headers: Any | None = ...,
-    cookies: Any | None = ...,
-    files: Any | None = ...,
-    auth: Any | None = ...,
-    timeout: Any | None = ...,
+    data: _Data | None = ...,
+    headers: _TextMapping | None = ...,
+    cookies: RequestsCookieJar | _TextMapping | None = ...,
+    files: _Files | None = ...,
+    auth: _Auth | None = ...,
+    timeout: _Timeout | None = ...,
    allow_redirects: bool = ...,
-    proxies: Any | None = ...,
-    hooks: Any | None = ...,
-    stream: Any | None = ...,
-    verify: Any | None = ...,
-    cert: Any | None = ...,
+    proxies: _TextMapping | None = ...,
+    hooks: _HooksInput | None = ...,
+    stream: bool | None = ...,
+    verify: _Verify | None = ...,
+    cert: _Cert | None = ...,
    json: Any | None = ...,
 ) -> Response: ...
 def post(
    url: str | bytes,
-    data: _Data = ...,
+    data: _Data | None = ...,
    json: Any | None = ...,
+    *,
    params: _Params | None = ...,
-    headers: Any | None = ...,
-    cookies: Any | None = ...,
-    files: Any | None = ...,
-    auth: Any | None = ...,
-    timeout: Any | None = ...,
+    headers: _TextMapping | None = ...,
+    cookies: RequestsCookieJar | _TextMapping | None = ...,
+    files: _Files | None = ...,
+    auth: _Auth | None = ...,
+    timeout: _Timeout | None = ...,
    allow_redirects: bool = ...,
-    proxies: Any | None = ...,
-    hooks: Any | None = ...,
-    stream: Any | None = ...,
-    verify: Any | None = ...,
-    cert: Any | None = ...,
+    proxies: _TextMapping | None = ...,
+    hooks: _HooksInput | None = ...,
+    stream: bool | None = ...,
+    verify: _Verify | None = ...,
+    cert: _Cert | None = ...,
 ) -> Response: ...
 def put(
    url: str | bytes,
-    data: _Data = ...,
+    data: _Data | None = ...,
+    *,
    params: _Params | None = ...,
-    headers: Any | None = ...,
-    cookies: Any | None = ...,
-    files: Any | None = ...,
-    auth: Any | None = ...,
-    timeout: Any | None = ...,
+    headers: _TextMapping | None = ...,
+    cookies: RequestsCookieJar | _TextMapping | None = ...,
+    files: _Files | None = ...,
+    auth: _Auth | None = ...,
+    timeout: _Timeout | None = ...,
    allow_redirects: bool = ...,
-    proxies: Any | None = ...,
-    hooks: Any | None = ...,
-    stream: Any | None = ...,
-    verify: Any | None = ...,
-    cert: Any | None = ...,
+    proxies: _TextMapping | None = ...,
+    hooks: _HooksInput | None = ...,
+    stream: bool | None = ...,
+    verify: _Verify | None = ...,
+    cert: _Cert | None = ...,
    json: Any | None = ...,
 ) -> Response: ...
 def patch(
    url: str | bytes,
-    data: _Data = ...,
+    data: _Data | None = ...,
+    *,
    params: _Params | None = ...,
-    headers: Any | None = ...,
-    cookies: Any | None = ...,
-    files: Any | None = ...,
-    auth: Any | None = ...,
-    timeout: Any | None = ...,
+    headers: _TextMapping | None = ...,
+    cookies: RequestsCookieJar | _TextMapping | None = ...,
+    files: _Files | None = ...,
+    auth: _Auth | None = ...,
+    timeout: _Timeout | None = ...,
    allow_redirects: bool = ...,
-    proxies: Any | None = ...,
-    hooks: Any | None = ...,
-    stream: Any | None = ...,
-    verify: Any | None = ...,
-    cert: Any | None = ...,
+    proxies: _TextMapping | None = ...,
+    hooks: _HooksInput | None = ...,
+    stream: bool | None = ...,
+    verify: _Verify | None = ...,
+    cert: _Cert | None = ...,
    json: Any | None = ...,
 ) -> Response: ...
 def delete(
    url: str | bytes,
+    *,
    params: _Params | None = ...,
-    data: Any | None = ...,
-    headers: Any | None = ...,
-    cookies: Any | None = ...,
-    files: Any | None = ...,
-    auth: Any | None = ...,
-    timeout: Any | None = ...,
+    data: _Data | None = ...,
+    headers: _TextMapping | None = ...,
+    cookies: RequestsCookieJar | _TextMapping | None = ...,
+    files: _Files | None = ...,
+    auth: _Auth | None = ...,
+    timeout: _Timeout | None = ...,
    allow_redirects: bool = ...,
-    proxies: Any | None = ...,
-    hooks: Any | None = ...,
-    stream: Any | None = ...,
-    verify: Any | None = ...,
-    cert: Any | None = ...,
+    proxies: _TextMapping | None = ...,
+    hooks: _HooksInput | None = ...,
+    stream: bool | None = ...,
+    verify: _Verify | None = ...,
+    cert: _Cert | None = ...,
    json: Any | None = ...,
 ) -> Response: ...
--- a/stubs/requests/requests/sessions.pyi
+++ b/stubs/requests/requests/sessions.pyi
@@ -45,8 +45,15 @@ class SessionRedirectMixin:
    def rebuild_proxies(self, prepared_request, proxies): ...
    def should_strip_auth(self, old_url, new_url): ...

-_Data: TypeAlias = str | bytes | Mapping[str, Any] | Iterable[tuple[str, str | None]] | IO[Any] | None
-
+_Data: TypeAlias = str | bytes | Mapping[str, Any] | Iterable[tuple[str, str | None]] | IO[Any]
+_Auth: TypeAlias = Union[tuple[str, str], _auth.AuthBase, Callable[[PreparedRequest], PreparedRequest]]
+_Cert: TypeAlias = Union[str, tuple[str, str]]
+_Files: TypeAlias = (
+    MutableMapping[str, IO[Any]]
+    | MutableMapping[str, tuple[str, IO[Any]]]
+    | MutableMapping[str, tuple[str, IO[Any], str]]
+    | MutableMapping[str, tuple[str, IO[Any], str, _TextMapping]]
+)
 _Hook: TypeAlias = Callable[[Response], Any]
 _Hooks: TypeAlias = MutableMapping[str, _Hook | list[_Hook]]
 _HooksInput: TypeAlias = MutableMapping[str, Iterable[_Hook] | _Hook]
@@ -60,11 +67,13 @@ _Params: TypeAlias = Union[
    str | bytes,
 ]
 _TextMapping: TypeAlias = MutableMapping[str, str]
+_Timeout: TypeAlias = Union[float, tuple[float, float], tuple[float, None]]
+_Verify: TypeAlias = bool | str

 class Session(SessionRedirectMixin):
    __attrs__: Any
    headers: CaseInsensitiveDict[str]
-    auth: None | tuple[str, str] | _auth.AuthBase | Callable[[PreparedRequest], PreparedRequest]
+    auth: _Auth | None
    proxies: _TextMapping
    hooks: _Hooks
    params: _Params
@@ -82,155 +91,167 @@ class Session(SessionRedirectMixin):
    def prepare_request(self, request: Request) -> PreparedRequest: ...
    def request(
        self,
-        method: str,
+        method: str | bytes,
        url: str | bytes,
        params: _Params | None = ...,
-        data: _Data = ...,
+        data: _Data | None = ...,
        headers: _TextMapping | None = ...,
        cookies: None | RequestsCookieJar | _TextMapping = ...,
-        files: MutableMapping[str, IO[Any]]
-        | MutableMapping[str, tuple[str, IO[Any]]]
-        | MutableMapping[str, tuple[str, IO[Any], str]]
-        | MutableMapping[str, tuple[str, IO[Any], str, _TextMapping]]
-        | None = ...,
-        auth: None | tuple[str, str] | _auth.AuthBase | Callable[[PreparedRequest], PreparedRequest] = ...,
-        timeout: None | float | tuple[float, float] | tuple[float, None] = ...,
-        allow_redirects: bool | None = ...,
+        files: _Files | None = ...,
+        auth: _Auth | None = ...,
+        timeout: _Timeout | None = ...,
+        allow_redirects: bool = ...,
        proxies: _TextMapping | None = ...,
        hooks: _HooksInput | None = ...,
        stream: bool | None = ...,
-        verify: None | bool | str = ...,
-        cert: str | tuple[str, str] | None = ...,
+        verify: _Verify | None = ...,
+        cert: _Cert | None = ...,
        json: Any | None = ...,
    ) -> Response: ...
    def get(
        self,
        url: str | bytes,
+        *,
        params: _Params | None = ...,
-        data: Any | None = ...,
-        headers: Any | None = ...,
-        cookies: Any | None = ...,
-        files: Any | None = ...,
-        auth: Any | None = ...,
-        timeout: Any | None = ...,
+        data: _Data | None = ...,
+        headers: _TextMapping | None = ...,
+        cookies: RequestsCookieJar | _TextMapping | None = ...,
+        files: _Files | None = ...,
+        auth: _Auth | None = ...,
+        timeout: _Timeout | None = ...,
        allow_redirects: bool = ...,
-        proxies: Any | None = ...,
-        hooks: Any | None = ...,
-        stream: Any | None = ...,
-        verify: Any | None = ...,
-        cert: Any | None = ...,
+        proxies: _TextMapping | None = ...,
+        hooks: _HooksInput | None = ...,
+        stream: bool | None = ...,
+        verify: _Verify | None = ...,
+        cert: _Cert | None = ...,
        json: Any | None = ...,
    ) -> Response: ...
    def options(
        self,
        url: str | bytes,
+        *,
        params: _Params | None = ...,
-        data: Any | None = ...,
-        headers: Any | None = ...,
-        cookies: Any | None = ...,
-        files: Any | None = ...,
-        auth: Any | None = ...,
-        timeout: Any | None = ...,
+        data: _Data | None = ...,
+        headers: _TextMapping | None = ...,
+        cookies: RequestsCookieJar | _TextMapping | None = ...,
+        files: _Files | None = ...,
+        auth: _Auth | None = ...,
+        timeout: _Timeout | None = ...,
        allow_redirects: bool = ...,
-        proxies: Any | None = ...,
-        hooks: Any | None = ...,
-        stream: Any | None = ...,
-        verify: Any | None = ...,
-        cert: Any | None = ...,
+        proxies: _TextMapping | None = ...,
+        hooks: _HooksInput | None = ...,
+        stream: bool | None = ...,
+        verify: _Verify | None = ...,
+        cert: _Cert | None = ...,
        json: Any | None = ...,
    ) -> Response: ...
    def head(
        self,
        url: str | bytes,
+        *,
        params: _Params | None = ...,
-        data: Any | None = ...,
-        headers: Any | None = ...,
-        cookies: Any | None = ...,
-        files: Any | None = ...,
-        auth: Any | None = ...,
-        timeout: Any | None = ...,
+        data: _Data | None = ...,
+        headers: _TextMapping | None = ...,
+        cookies: RequestsCookieJar | _TextMapping | None = ...,
+        files: _Files | None = ...,
+        auth: _Auth | None = ...,
+        timeout: _Timeout | None = ...,
        allow_redirects: bool = ...,
-        proxies: Any | None = ...,
-        hooks: Any | None = ...,
-        stream: Any | None = ...,
-        verify: Any | None = ...,
-        cert: Any | None = ...,
+        proxies: _TextMapping | None = ...,
+        hooks: _HooksInput | None = ...,
+        stream: bool | None = ...,
+        verify: _Verify | None = ...,
+        cert: _Cert | None = ...,
        json: Any | None = ...,
    ) -> Response: ...
    def post(
        self,
        url: str | bytes,
-        data: _Data = ...,
+        data: _Data | None = ...,
        json: Any | None = ...,
+        *,
        params: _Params | None = ...,
-        headers: Any | None = ...,
-        cookies: Any | None = ...,
-        files: Any | None = ...,
-        auth: Any | None = ...,
-        timeout: Any | None = ...,
+        headers: _TextMapping | None = ...,
+        cookies: RequestsCookieJar | _TextMapping | None = ...,
+        files: _Files | None = ...,
+        auth: _Auth | None = ...,
+        timeout: _Timeout | None = ...,
        allow_redirects: bool = ...,
-        proxies: Any | None = ...,
-        hooks: Any | None = ...,
-        stream: Any | None = ...,
-        verify: Any | None = ...,
-        cert: Any | None = ...,
+        proxies: _TextMapping | None = ...,
+        hooks: _HooksInput | None = ...,
+        stream: bool | None = ...,
+        verify: _Verify | None = ...,
+        cert: _Cert | None = ...,
    ) -> Response: ...
    def put(
        self,
        url: str | bytes,
-        data: _Data = ...,
+        data: _Data | None = ...,
+        *,
        params: _Params | None = ...,
-        headers: Any | None = ...,
-        cookies: Any | None = ...,
-        files: Any | None = ...,
-        auth: Any | None = ...,
-        timeout: Any | None = ...,
+        headers: _TextMapping | None = ...,
+        cookies: RequestsCookieJar | _TextMapping | None = ...,
+        files: _Files | None = ...,
+        auth: _Auth | None = ...,
+        timeout: _Timeout | None = ...,
        allow_redirects: bool = ...,
-        proxies: Any | None = ...,
-        hooks: Any | None = ...,
-        stream: Any | None = ...,
-        verify: Any | None = ...,
-        cert: Any | None = ...,
+        proxies: _TextMapping | None = ...,
+        hooks: _HooksInput | None = ...,
+        stream: bool | None = ...,
+        verify: _Verify | None = ...,
+        cert: _Cert | None = ...,
        json: Any | None = ...,
    ) -> Response: ...
    def patch(
        self,
        url: str | bytes,
-        data: _Data = ...,
+        data: _Data | None = ...,
+        *,
        params: _Params | None = ...,
-        headers: Any | None = ...,
-        cookies: Any | None = ...,
-        files: Any | None = ...,
-        auth: Any | None = ...,
-        timeout: Any | None = ...,
+        headers: _TextMapping | None = ...,
+        cookies: RequestsCookieJar | _TextMapping | None = ...,
+        files: _Files | None = ...,
+        auth: _Auth | None = ...,
+        timeout: _Timeout | None = ...,
        allow_redirects: bool = ...,
-        proxies: Any | None = ...,
-        hooks: Any | None = ...,
-        stream: Any | None = ...,
-        verify: Any | None = ...,
-        cert: Any | None = ...,
+        proxies: _TextMapping | None = ...,
+        hooks: _HooksInput | None = ...,
+        stream: bool | None = ...,
+        verify: _Verify | None = ...,
+        cert: _Cert | None = ...,
        json: Any | None = ...,
    ) -> Response: ...
    def delete(
        self,
        url: str | bytes,
+        *,
        params: _Params | None = ...,
-        data: Any | None = ...,
-        headers: Any | None = ...,
-        cookies: Any | None = ...,
-        files: Any | None = ...,
-        auth: Any | None = ...,
-        timeout: Any | None = ...,
+        data: _Data | None = ...,
+        headers: _TextMapping | None = ...,
+        cookies: RequestsCookieJar | _TextMapping | None = ...,
+        files: _Files | None = ...,
+        auth: _Auth | None = ...,
+        timeout: _Timeout | None = ...,
        allow_redirects: bool = ...,
-        proxies: Any | None = ...,
-        hooks: Any | None = ...,
-        stream: Any | None = ...,
-        verify: Any | None = ...,
-        cert: Any | None = ...,
+        proxies: _TextMapping | None = ...,
+        hooks: _HooksInput | None = ...,
+        stream: bool | None = ...,
+        verify: _Verify | None = ...,
+        cert: _Cert | None = ...,
        json: Any | None = ...,
    ) -> Response: ...
    def send(
-        self, request: PreparedRequest, *, stream=..., verify=..., cert=..., proxies=..., allow_redirects: bool = ..., **kwargs
+        self,
+        request: PreparedRequest,
+        *,
+        stream: bool | None = ...,
+        verify: _Verify | None = ...,
+        proxies: _TextMapping | None = ...,
+        cert: _Cert | None = ...,
+        timeout: _Timeout | None = ...,
+        allow_redirects: bool = ...,
+        **kwargs: Any,
    ) -> Response: ...
    def merge_environment_settings(self, url, proxies, stream, verify, cert): ...
    def get_adapter(self, url: str) -> _BaseAdapter: ...