requests: improve _Data type (#8762)

Rogdham · web-flow · commit b3db49abbd56 · 2022-09-21T16:35:09.000-07:00
requests: improve _Data type

This allows to pass an Iterable[bytes] for streaming request data.
diff --git a/stubs/requests/requests/sessions.pyi b/stubs/requests/requests/sessions.pyi
@@ -1,6 +1,6 @@
 from _typeshed import Self, SupportsItems, SupportsRead
 from collections.abc import Callable, Iterable, Mapping, MutableMapping
-from typing import IO, Any, Union
+from typing import Any, Union
 from typing_extensions import TypeAlias, TypedDict
 
 from urllib3._collections import RecentlyUsedContainer
@@ -45,7 +45,25 @@ 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]
+_Data: TypeAlias = (
+    # used in requests.models.PreparedRequest.prepare_body
+    #
+    # case: is_stream
+    # see requests.adapters.HTTPAdapter.send
+    # will be sent directly to http.HTTPConnection.send(...) (through urllib3)
+    Iterable[bytes]
+    # case: not is_stream
+    # will be modified before being sent to urllib3.HTTPConnectionPool.urlopen(body=...)
+    # see requests.models.RequestEncodingMixin._encode_params
+    # see requests.models.RequestEncodingMixin._encode_files
+    # note that keys&values are converted from Any to str by urllib.parse.urlencode
+    | str
+    | bytes
+    | SupportsRead[str | bytes]
+    | list[tuple[Any, Any]]
+    | tuple[tuple[Any, Any], ...]
+    | Mapping[Any, Any]
+)
 _Auth: TypeAlias = Union[tuple[str, str], _auth.AuthBase, Callable[[PreparedRequest], PreparedRequest]]
 _Cert: TypeAlias = Union[str, tuple[str, str]]
 # Files is passed to requests.utils.to_key_val_list()
