From f4625cb51197c9012bda997863cf05de3fdfae07 Mon Sep 17 00:00:00 2001
From: Christopher Dignam <chris@dignam.xyz>
Date: Thu, 8 Apr 2021 06:24:54 -0400
Subject: [PATCH] [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>
---
 stubs/requests/requests/api.pyi      | 158 +++++++++++++++++++++++----
 stubs/requests/requests/sessions.pyi | 147 +++++++++++++++++++++++--
 2 files changed, 274 insertions(+), 31 deletions(-)

diff --git a/stubs/requests/requests/api.pyi b/stubs/requests/requests/api.pyi
index 85d46fc28..26c120fe5 100644
--- 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: ...
diff --git a/stubs/requests/requests/sessions.pyi b/stubs/requests/requests/sessions.pyi
index 930a3cb72..332a23f79 100644
--- 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): ...