5
This module contains type aliases used internally by the Requests library.
6
These types are not part of the public API and must not be relied upon
10
from __future__ import annotations
12
from collections.abc import Callable, Iterable, Mapping, MutableMapping, Sequence
22
_T_co = TypeVar("_T_co", covariant=True)
23
_KT_co = TypeVar("_KT_co", covariant=True)
24
_VT_co = TypeVar("_VT_co", covariant=True)
28
class SupportsRead(Protocol[_T_co]):
29
def read(self, length: int = ..., /) -> _T_co: ...
32
def has_read(obj: Any) -> TypeIs[SupportsRead[str | bytes]]:
33
"""Check if obj supports read, including __getattr__ based proxies."""
34
return isinstance(obj, SupportsRead) or hasattr(obj, "read")
38
class SupportsItems(Protocol[_KT_co, _VT_co]):
39
def items(self) -> Iterable[tuple[_KT_co, _VT_co]]: ...
42
# These are needed at runtime for default_hooks() return type
43
HookType: TypeAlias = Callable[["Response"], Any]
44
HooksInputType: TypeAlias = Mapping[str, Iterable[HookType] | HookType]
47
def is_prepared(request: PreparedRequest) -> TypeIs[_ValidatedRequest]:
48
"""Verify a PreparedRequest has been fully prepared."""
50
return request.url is not None and request.method is not None
51
# noop at runtime to avoid AssertionError
48
"""Verify a PreparedRequest has been fully prepared."""
50
return request.url is not None and request.method is not None
51
# noop at runtime to avoid AssertionError
56
from http.cookiejar import CookieJar
57
from typing import TypeAlias, TypedDict
59
from typing_extensions import (
60
Buffer, # TODO: move to collections.abc when Python >= 3.12
61
TypeIs, # TODO: move to typing when Python >= 3.13
64
from .auth import AuthBase
65
from .cookies import RequestsCookieJar
66
from .models import PreparedRequest, Response
67
from .structures import CaseInsensitiveDict
69
class _ValidatedRequest(PreparedRequest):
70
"""Subtype asserting a PreparedRequest has been fully prepared before calling.
72
The override suppression is required because mutable attribute types are
73
invariant (Liskov), but we only narrow after preparation is complete. This
74
is the explicit contract for Requests but Python's typing doesn't have a
75
better way to represent the requirement.
78
url: str # type: ignore[reportIncompatibleVariableOverride]
79
method: str # type: ignore[reportIncompatibleVariableOverride]
81
# Type aliases for core API concepts (ordered by request() signature)
82
UriType: TypeAlias = str | bytes
84
_ParamsMappingKeyType: TypeAlias = str | bytes | int | float
85
_ParamsMappingValueType: TypeAlias = (
86
str | bytes | int | float | Iterable[str | bytes | int | float] | None
88
ParamsType: TypeAlias = (
89
SupportsItems[_ParamsMappingKeyType, _ParamsMappingValueType]
90
| tuple[tuple[_ParamsMappingKeyType, _ParamsMappingValueType], ...]
91
| Iterable[tuple[_ParamsMappingKeyType, _ParamsMappingValueType]]
91
| Iterable[tuple[_ParamsMappingKeyType, _ParamsMappingValueType]]
97
KVDataType: TypeAlias = Iterable[tuple[Any, Any]] | SupportsItems[Any, Any]
99
RawDataType: TypeAlias = KVDataType | str | bytes
100
StreamDataType: TypeAlias = SupportsRead[str | bytes]
101
EncodableDataType: TypeAlias = RawDataType | StreamDataType
103
DataType: TypeAlias = (
105
| Iterable[bytes | str]
109
| SupportsRead[str | bytes]
113
BodyType: TypeAlias = (
114
bytes | str | Iterable[bytes | str] | SupportsRead[bytes | str] | None
117
HeadersType: TypeAlias = Mapping[str, str | bytes] | None
119
CookiesType: TypeAlias = RequestsCookieJar | Mapping[str, str]
121
# Building blocks for FilesType
122
_FileName: TypeAlias = str | None
123
_FileContent: TypeAlias = SupportsRead[str | bytes] | str | bytes
124
_FileSpecBasic: TypeAlias = tuple[_FileName, _FileContent]
125
_FileSpecWithContentType: TypeAlias = tuple[_FileName, _FileContent, str]
126
_FileSpecWithHeaders: TypeAlias = tuple[
127
_FileName, _FileContent, str, CaseInsensitiveDict[str] | Mapping[str, str]
129
_FileSpec: TypeAlias = (
130
_FileContent | _FileSpecBasic | _FileSpecWithContentType | _FileSpecWithHeaders
132
FilesType: TypeAlias = (
133
Mapping[str, _FileSpec] | Iterable[tuple[str, _FileSpec]] | None
130
_FileContent | _FileSpecBasic | _FileSpecWithContentType | _FileSpecWithHeaders
132
FilesType: TypeAlias = (
133
Mapping[str, _FileSpec] | Iterable[tuple[str, _FileSpec]] | None
136
AuthType: TypeAlias = (
137
tuple[str, str] | AuthBase | Callable[[PreparedRequest], PreparedRequest] | None
140
TimeoutType: TypeAlias = float | tuple[float | None, float | None] | None
141
ProxiesType: TypeAlias = MutableMapping[str, str]
142
HooksType: TypeAlias = dict[str, list[HookType]] | None
143
VerifyType: TypeAlias = bool | str
144
CertType: TypeAlias = str | tuple[str, str] | None
145
JsonType: TypeAlias = (
151
| Sequence["JsonType"]
152
| Mapping[str, "JsonType"]
155
# TypedDicts for Unpack kwargs (PEP 692)
157
class BaseRequestKwargs(TypedDict, total=False):
159
cookies: RequestsCookieJar | CookieJar | dict[str, str] | None
163
allow_redirects: bool
164
proxies: dict[str, str] | None
165
hooks: HooksInputType | None
167
verify: VerifyType | None
170
class RequestKwargs(BaseRequestKwargs, total=False):
171
"""kwargs for request(), options(), head(), delete()."""
171
"""kwargs for request(), options(), head(), delete()."""
177
class GetKwargs(BaseRequestKwargs, total=False):
181
class PostKwargs(BaseRequestKwargs, total=False):
184
class DataKwargs(BaseRequestKwargs, total=False):
185
"""kwargs for put(), patch()."""