[requests] add argument names for api and session methods (#5149)

Most of these types are Any, but we should now have slightly better auto complete for the argument names Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
2025-12-16 00:37:10 +08:00 · 2021-04-08 06:24:54 -04:00
parent fd2a176094
commit f4625cb511
2 changed files with 274 additions and 31 deletions
--- a/stubs/requests/requests/api.pyi
+++ b/stubs/requests/requests/api.pyi
@@ -1,28 +1,142 @@
-from _typeshed import SupportsItems
-from typing import Iterable, Optional, Text, Tuple, Union
+from typing import Any, Optional, Text, Union

 from .models import Response
-from .sessions import _Data
+from .sessions import _Data, _Params

-_ParamsMappingKeyType = Union[Text, bytes, int, float]
-_ParamsMappingValueType = Union[Text, bytes, int, float, Iterable[Union[Text, bytes, int, float]], None]
-
-def request(method: str, url: str, **kwargs) -> Response: ...
+def request(
+    method: Union[Text, bytes],
+    url: Union[Text, bytes],
+    params: Optional[_Params] = ...,
+    data: Optional[Any] = ...,
+    headers: Optional[Any] = ...,
+    cookies: Optional[Any] = ...,
+    files: Optional[Any] = ...,
+    auth: Optional[Any] = ...,
+    timeout: Optional[Any] = ...,
+    allow_redirects: bool = ...,
+    proxies: Optional[Any] = ...,
+    hooks: Optional[Any] = ...,
+    stream: Optional[Any] = ...,
+    verify: Optional[Any] = ...,
+    cert: Optional[Any] = ...,
+    json: Optional[Any] = ...,
+) -> Response: ...
 def get(
    url: Union[Text, bytes],
-    params: Optional[
-        Union[
-            SupportsItems[_ParamsMappingKeyType, _ParamsMappingValueType],
-            Tuple[_ParamsMappingKeyType, _ParamsMappingValueType],
-            Iterable[Tuple[_ParamsMappingKeyType, _ParamsMappingValueType]],
-            Union[Text, bytes],
-        ]
-    ] = ...,
-    **kwargs,
+    params: Optional[_Params] = ...,
+    data: Optional[Any] = ...,
+    headers: Optional[Any] = ...,
+    cookies: Optional[Any] = ...,
+    files: Optional[Any] = ...,
+    auth: Optional[Any] = ...,
+    timeout: Optional[Any] = ...,
+    allow_redirects: bool = ...,
+    proxies: Optional[Any] = ...,
+    hooks: Optional[Any] = ...,
+    stream: Optional[Any] = ...,
+    verify: Optional[Any] = ...,
+    cert: Optional[Any] = ...,
+    json: Optional[Any] = ...,
+) -> Response: ...
+def options(
+    url: Union[Text, bytes],
+    params: Optional[_Params] = ...,
+    data: Optional[Any] = ...,
+    headers: Optional[Any] = ...,
+    cookies: Optional[Any] = ...,
+    files: Optional[Any] = ...,
+    auth: Optional[Any] = ...,
+    timeout: Optional[Any] = ...,
+    allow_redirects: bool = ...,
+    proxies: Optional[Any] = ...,
+    hooks: Optional[Any] = ...,
+    stream: Optional[Any] = ...,
+    verify: Optional[Any] = ...,
+    cert: Optional[Any] = ...,
+    json: Optional[Any] = ...,
+) -> Response: ...
+def head(
+    url: Union[Text, bytes],
+    params: Optional[_Params] = ...,
+    data: Optional[Any] = ...,
+    headers: Optional[Any] = ...,
+    cookies: Optional[Any] = ...,
+    files: Optional[Any] = ...,
+    auth: Optional[Any] = ...,
+    timeout: Optional[Any] = ...,
+    allow_redirects: bool = ...,
+    proxies: Optional[Any] = ...,
+    hooks: Optional[Any] = ...,
+    stream: Optional[Any] = ...,
+    verify: Optional[Any] = ...,
+    cert: Optional[Any] = ...,
+    json: Optional[Any] = ...,
+) -> Response: ...
+def post(
+    url: Union[Text, bytes],
+    data: _Data = ...,
+    json: Optional[Any] = ...,
+    params: Optional[_Params] = ...,
+    headers: Optional[Any] = ...,
+    cookies: Optional[Any] = ...,
+    files: Optional[Any] = ...,
+    auth: Optional[Any] = ...,
+    timeout: Optional[Any] = ...,
+    allow_redirects: bool = ...,
+    proxies: Optional[Any] = ...,
+    hooks: Optional[Any] = ...,
+    stream: Optional[Any] = ...,
+    verify: Optional[Any] = ...,
+    cert: Optional[Any] = ...,
+) -> Response: ...
+def put(
+    url: Union[Text, bytes],
+    data: _Data = ...,
+    params: Optional[_Params] = ...,
+    headers: Optional[Any] = ...,
+    cookies: Optional[Any] = ...,
+    files: Optional[Any] = ...,
+    auth: Optional[Any] = ...,
+    timeout: Optional[Any] = ...,
+    allow_redirects: bool = ...,
+    proxies: Optional[Any] = ...,
+    hooks: Optional[Any] = ...,
+    stream: Optional[Any] = ...,
+    verify: Optional[Any] = ...,
+    cert: Optional[Any] = ...,
+    json: Optional[Any] = ...,
+) -> Response: ...
+def patch(
+    url: Union[Text, bytes],
+    data: _Data = ...,
+    params: Optional[_Params] = ...,
+    headers: Optional[Any] = ...,
+    cookies: Optional[Any] = ...,
+    files: Optional[Any] = ...,
+    auth: Optional[Any] = ...,
+    timeout: Optional[Any] = ...,
+    allow_redirects: bool = ...,
+    proxies: Optional[Any] = ...,
+    hooks: Optional[Any] = ...,
+    stream: Optional[Any] = ...,
+    verify: Optional[Any] = ...,
+    cert: Optional[Any] = ...,
+    json: Optional[Any] = ...,
+) -> Response: ...
+def delete(
+    url: Union[Text, bytes],
+    params: Optional[_Params] = ...,
+    data: Optional[Any] = ...,
+    headers: Optional[Any] = ...,
+    cookies: Optional[Any] = ...,
+    files: Optional[Any] = ...,
+    auth: Optional[Any] = ...,
+    timeout: Optional[Any] = ...,
+    allow_redirects: bool = ...,
+    proxies: Optional[Any] = ...,
+    hooks: Optional[Any] = ...,
+    stream: Optional[Any] = ...,
+    verify: Optional[Any] = ...,
+    cert: Optional[Any] = ...,
+    json: Optional[Any] = ...,
 ) -> Response: ...
-def options(url: Union[Text, bytes], **kwargs) -> Response: ...
-def head(url: Union[Text, bytes], **kwargs) -> Response: ...
-def post(url: Union[Text, bytes], data: _Data = ..., json=..., **kwargs) -> Response: ...
-def put(url: Union[Text, bytes], data: _Data = ..., json=..., **kwargs) -> Response: ...
-def patch(url: Union[Text, bytes], data: _Data = ..., json=..., **kwargs) -> Response: ...
-def delete(url: Union[Text, bytes], **kwargs) -> Response: ...
--- a/stubs/requests/requests/sessions.pyi
+++ b/stubs/requests/requests/sessions.pyi
@@ -1,3 +1,4 @@
+from _typeshed import SupportsItems
 from typing import IO, Any, Callable, Iterable, List, Mapping, MutableMapping, Optional, Text, Tuple, Union

 from . import adapters, auth as _auth, compat, cookies, exceptions, hooks, models, status_codes, structures, utils
@@ -47,13 +48,22 @@ _Hook = Callable[[Response], Any]
 _Hooks = MutableMapping[Text, List[_Hook]]
 _HooksInput = MutableMapping[Text, Union[Iterable[_Hook], _Hook]]

+_ParamsMappingKeyType = Union[Text, bytes, int, float]
+_ParamsMappingValueType = Union[Text, bytes, int, float, Iterable[Union[Text, bytes, int, float]], None]
+_Params = Union[
+    SupportsItems[_ParamsMappingKeyType, _ParamsMappingValueType],
+    Tuple[_ParamsMappingKeyType, _ParamsMappingValueType],
+    Iterable[Tuple[_ParamsMappingKeyType, _ParamsMappingValueType]],
+    Union[Text, bytes],
+]
+
 class Session(SessionRedirectMixin):
    __attrs__: Any
    headers: CaseInsensitiveDict[Text]
    auth: Union[None, Tuple[Text, Text], _auth.AuthBase, Callable[[PreparedRequest], PreparedRequest]]
    proxies: MutableMapping[Text, Text]
    hooks: _Hooks
-    params: Union[bytes, MutableMapping[Text, Union[Text, List[Text]]]]
+    params: _Params
    stream: bool
    verify: Union[None, bool, Text]
    cert: Union[None, Text, Tuple[Text, Text]]
@@ -70,7 +80,7 @@ class Session(SessionRedirectMixin):
        self,
        method: str,
        url: Union[str, bytes, Text],
-        params: Union[None, bytes, MutableMapping[Text, Union[Text, List[Text]]]] = ...,
+        params: Optional[_Params] = ...,
        data: _Data = ...,
        headers: Optional[MutableMapping[Text, Text]] = ...,
        cookies: Union[None, RequestsCookieJar, MutableMapping[Text, Text]] = ...,
@@ -85,13 +95,132 @@ class Session(SessionRedirectMixin):
        cert: Union[Text, Tuple[Text, Text], None] = ...,
        json: Optional[Any] = ...,
    ) -> Response: ...
-    def get(self, url: Union[Text, bytes], **kwargs) -> Response: ...
-    def options(self, url: Union[Text, bytes], **kwargs) -> Response: ...
-    def head(self, url: Union[Text, bytes], **kwargs) -> Response: ...
-    def post(self, url: Union[Text, bytes], data: _Data = ..., json: Optional[Any] = ..., **kwargs) -> Response: ...
-    def put(self, url: Union[Text, bytes], data: _Data = ..., **kwargs) -> Response: ...
-    def patch(self, url: Union[Text, bytes], data: _Data = ..., **kwargs) -> Response: ...
-    def delete(self, url: Union[Text, bytes], **kwargs) -> Response: ...
+    def get(
+        self,
+        url: Union[Text, bytes],
+        params: Optional[_Params] = ...,
+        data: Optional[Any] = ...,
+        headers: Optional[Any] = ...,
+        cookies: Optional[Any] = ...,
+        files: Optional[Any] = ...,
+        auth: Optional[Any] = ...,
+        timeout: Optional[Any] = ...,
+        allow_redirects: bool = ...,
+        proxies: Optional[Any] = ...,
+        hooks: Optional[Any] = ...,
+        stream: Optional[Any] = ...,
+        verify: Optional[Any] = ...,
+        cert: Optional[Any] = ...,
+        json: Optional[Any] = ...,
+    ) -> Response: ...
+    def options(
+        self,
+        url: Union[Text, bytes],
+        params: Optional[_Params] = ...,
+        data: Optional[Any] = ...,
+        headers: Optional[Any] = ...,
+        cookies: Optional[Any] = ...,
+        files: Optional[Any] = ...,
+        auth: Optional[Any] = ...,
+        timeout: Optional[Any] = ...,
+        allow_redirects: bool = ...,
+        proxies: Optional[Any] = ...,
+        hooks: Optional[Any] = ...,
+        stream: Optional[Any] = ...,
+        verify: Optional[Any] = ...,
+        cert: Optional[Any] = ...,
+        json: Optional[Any] = ...,
+    ) -> Response: ...
+    def head(
+        self,
+        url: Union[Text, bytes],
+        params: Optional[_Params] = ...,
+        data: Optional[Any] = ...,
+        headers: Optional[Any] = ...,
+        cookies: Optional[Any] = ...,
+        files: Optional[Any] = ...,
+        auth: Optional[Any] = ...,
+        timeout: Optional[Any] = ...,
+        allow_redirects: bool = ...,
+        proxies: Optional[Any] = ...,
+        hooks: Optional[Any] = ...,
+        stream: Optional[Any] = ...,
+        verify: Optional[Any] = ...,
+        cert: Optional[Any] = ...,
+        json: Optional[Any] = ...,
+    ) -> Response: ...
+    def post(
+        self,
+        url: Union[Text, bytes],
+        data: _Data = ...,
+        json: Optional[Any] = ...,
+        params: Optional[_Params] = ...,
+        headers: Optional[Any] = ...,
+        cookies: Optional[Any] = ...,
+        files: Optional[Any] = ...,
+        auth: Optional[Any] = ...,
+        timeout: Optional[Any] = ...,
+        allow_redirects: bool = ...,
+        proxies: Optional[Any] = ...,
+        hooks: Optional[Any] = ...,
+        stream: Optional[Any] = ...,
+        verify: Optional[Any] = ...,
+        cert: Optional[Any] = ...,
+    ) -> Response: ...
+    def put(
+        self,
+        url: Union[Text, bytes],
+        data: _Data = ...,
+        params: Optional[_Params] = ...,
+        headers: Optional[Any] = ...,
+        cookies: Optional[Any] = ...,
+        files: Optional[Any] = ...,
+        auth: Optional[Any] = ...,
+        timeout: Optional[Any] = ...,
+        allow_redirects: bool = ...,
+        proxies: Optional[Any] = ...,
+        hooks: Optional[Any] = ...,
+        stream: Optional[Any] = ...,
+        verify: Optional[Any] = ...,
+        cert: Optional[Any] = ...,
+        json: Optional[Any] = ...,
+    ) -> Response: ...
+    def patch(
+        self,
+        url: Union[Text, bytes],
+        data: _Data = ...,
+        params: Optional[_Params] = ...,
+        headers: Optional[Any] = ...,
+        cookies: Optional[Any] = ...,
+        files: Optional[Any] = ...,
+        auth: Optional[Any] = ...,
+        timeout: Optional[Any] = ...,
+        allow_redirects: bool = ...,
+        proxies: Optional[Any] = ...,
+        hooks: Optional[Any] = ...,
+        stream: Optional[Any] = ...,
+        verify: Optional[Any] = ...,
+        cert: Optional[Any] = ...,
+        json: Optional[Any] = ...,
+    ) -> Response: ...
+    def delete(
+        self,
+        url: Union[Text, bytes],
+        params: Optional[_Params] = ...,
+        data: Optional[Any] = ...,
+        headers: Optional[Any] = ...,
+        cookies: Optional[Any] = ...,
+        files: Optional[Any] = ...,
+        auth: Optional[Any] = ...,
+        timeout: Optional[Any] = ...,
+        allow_redirects: bool = ...,
+        proxies: Optional[Any] = ...,
+        hooks: Optional[Any] = ...,
+        stream: Optional[Any] = ...,
+        verify: Optional[Any] = ...,
+        cert: Optional[Any] = ...,
+        json: Optional[Any] = ...,
+    ) -> Response: ...
    def send(self, request: PreparedRequest, **kwargs) -> Response: ...
    def merge_environment_settings(self, url, proxies, stream, verify, cert): ...
    def get_adapter(self, url): ...