forked from psf/requests
-
-
Notifications
You must be signed in to change notification settings - Fork 17
/
api.rst
149 lines (106 loc) · 5.23 KB
/
api.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
.. _api:
Developer Interface
===================
.. module:: requests
This part of the documentation covers all the interfaces of Niquests. For
parts where Niquests depends on external libraries, we document the most
important right here and provide links to the canonical documentation.
Main Interface
--------------
All of Niquests' functionality can be accessed by these 7 methods.
They all return an instance of the :class:`Response <Response>` object.
.. autofunction:: request
.. autofunction:: head
.. autofunction:: get
.. autofunction:: post
.. autofunction:: put
.. autofunction:: patch
.. autofunction:: delete
Exceptions
----------
.. autoexception:: niquests.RequestException
.. autoexception:: niquests.ConnectionError
.. autoexception:: niquests.HTTPError
.. autoexception:: niquests.URLRequired
.. autoexception:: niquests.TooManyRedirects
.. autoexception:: niquests.ConnectTimeout
.. autoexception:: niquests.ReadTimeout
.. autoexception:: niquests.Timeout
.. autoexception:: niquests.JSONDecodeError
Request Sessions
----------------
.. _sessionapi:
.. autoclass:: Session
:inherited-members:
Lower-Level Classes
-------------------
.. autoclass:: niquests.Request
:inherited-members:
.. autoclass:: Response
:inherited-members:
Lower-Lower-Level Classes
-------------------------
.. autoclass:: niquests.PreparedRequest
:inherited-members:
.. autoclass:: niquests.adapters.BaseAdapter
:inherited-members:
.. autoclass:: niquests.adapters.HTTPAdapter
:inherited-members:
Authentication
--------------
.. autoclass:: niquests.auth.AuthBase
.. autoclass:: niquests.auth.HTTPBasicAuth
.. autoclass:: niquests.auth.HTTPProxyAuth
.. autoclass:: niquests.auth.HTTPDigestAuth
.. _api-cookies:
Cookies
-------
.. autofunction:: niquests.utils.dict_from_cookiejar
.. autofunction:: niquests.utils.add_dict_to_cookiejar
.. autofunction:: niquests.cookies.cookiejar_from_dict
.. autoclass:: niquests.cookies.RequestsCookieJar
:inherited-members:
.. autoclass:: niquests.cookies.CookieConflictError
:inherited-members:
Status Code Lookup
------------------
.. autoclass:: niquests.codes
.. automodule:: niquests.status_codes
Migrating to 3.x
----------------
Compared with the 2.0 release, there were relatively few backwards
incompatible changes, but there are still a few issues to be aware of with
this major release.
Removed
~~~~~~~
* Property ``apparent_encoding`` in favor of a discrete internal inference.
* Support for the legacy ``chardet`` detector in case it was present in environment.
Extra ``chardet_on_py3`` is now unavailable.
* **requests.compat** no longer hold reference to _chardet_.
* Deprecated ``requests.packages`` that was meant to avoid breakage from people importing ``urllib3`` or ``chardet`` within this package.
They were _vendored_ in early versions of Requests. A long time ago.
* Deprecated function ``get_encodings_from_content`` from utils.
* Deprecated function ``get_unicode_from_response`` from utils.
* BasicAuth middleware no-longer support anything else than ``bytes`` or ``str`` for username and password.
* ``requests.compat`` is stripped of every reference that no longer vary between supported interpreter version.
* Charset fall back **ISO-8859-1** when content-type is text and no charset was specified.
* Main function ``get``, ``post``, ``put``, ``patch``, ``delete``, and ``head`` no longer accept **kwargs**. They have a fixed list of typed argument.
It is no longer possible to specify non-supported additional keyword argument from a ``Session`` instance or directly through ``requests.api`` functions.
e.g. function ``delete`` no-longer accept ``json``, or ``files`` arguments. as per RFCs specifications. You can still override this behavior through the ``request`` function.
* Mixin classes ``RequestEncodingMixin``, and ``RequestHooksMixin`` due to OOP violations. Now deported directly into child classes.
* Function ``unicode_is_ascii`` as it is part of the stable ``str`` stdlib on Python 3 or greater.
* Alias function ``session`` for ``Session`` context manager that was kept for BC reasons since the v1.
* pyOpenSSL/urllib3 injection in case built-in ssl module does not have SNI support as it is not the case anymore for every supported interpreters.
* Constant ``DEFAULT_CA_BUNDLE_PATH``, and submodule ``certs`` due to dropping ``certifi``.
* Function ``extract_zipped_paths`` because rendered useless as it was made to handle an edge case where ``certifi`` is "zipped".
* Extra ``security`` when installing this package. It was previously emptied in the previous major.
* Warning emitted when passing a file opened in text-mode instead of binary. urllib3.future can overrule
the content-length if it detects an error. You should not encounter broken request being sent.
* Support for ``simplejson`` if was present in environment.
* Submodule ``compat``.
* Dependency check at runtime for ``urllib3``. There's no more check and warnings at runtime for that subject. Ever.
Behavioural Changes
~~~~~~~~~~~~~~~~~~~
* Niquests negotiate for a HTTP/2 connection by default, fallback to HTTP/1.1 if not available.
* Support for HTTP/3 can be present by default if your platform support the pre-built wheel for qh3.
* Server capability for HTTP/3 is remembered automatically (in-memory) for subsequent requests.