From 58346e905eed019c122c1c0fff08f26f8a2c3393 Mon Sep 17 00:00:00 2001 From: Cycloctane Date: Tue, 7 Jan 2025 18:48:46 +0800 Subject: [PATCH] Update docs for aiohttp.request (#10301) (cherry picked from commit 77f25a0a4da3cc20f4c5b6d12be9d273ea02f1df) --- docs/client_reference.rst | 125 +++++++++++++++++++++++++++++--------- 1 file changed, 97 insertions(+), 28 deletions(-) diff --git a/docs/client_reference.rst b/docs/client_reference.rst index e18785ea796..013c43a13e4 100644 --- a/docs/client_reference.rst +++ b/docs/client_reference.rst @@ -517,7 +517,7 @@ The client session supports the context manager protocol for self closing. .. versionadded:: 3.0 :param str server_hostname: Sets or overrides the host name that the - target server’s certificate will be matched against. + target server's certificate will be matched against. See :py:meth:`asyncio.loop.create_connection` for more information. @@ -854,14 +854,21 @@ certification chaining. .. function:: request(method, url, *, params=None, data=None, \ json=None,\ - headers=None, cookies=None, auth=None, \ + cookies=None, headers=None, skip_auto_headers=None, auth=None, \ allow_redirects=True, max_redirects=10, \ - encoding='utf-8', \ - version=HttpVersion(major=1, minor=1), \ - compress=None, chunked=None, expect100=False, raise_for_status=False, \ + compress=False, chunked=None, expect100=False, raise_for_status=None, \ + read_until_eof=True, \ + proxy=None, proxy_auth=None, \ + timeout=sentinel, ssl=True, \ + server_hostname=None, \ + proxy_headers=None, \ + trace_request_ctx=None, \ read_bufsize=None, \ - connector=None, loop=None,\ - read_until_eof=True, timeout=sentinel) + auto_decompress=None, \ + max_line_size=None, \ + max_field_size=None, \ + version=aiohttp.HttpVersion11, \ + connector=None) :async: Asynchronous context manager for performing an asynchronous HTTP @@ -874,8 +881,20 @@ certification chaining. be encoded with :class:`~yarl.URL` (see :class:`~yarl.URL` to skip encoding). - :param dict params: Parameters to be sent in the query - string of the new request (optional) + :param params: Mapping, iterable of tuple of *key*/*value* pairs or + string to be sent as parameters in the query + string of the new request. Ignored for subsequent + redirected requests (optional) + + Allowed values are: + + - :class:`collections.abc.Mapping` e.g. :class:`dict`, + :class:`multidict.MultiDict` or + :class:`multidict.MultiDictProxy` + - :class:`collections.abc.Iterable` e.g. :class:`tuple` or + :class:`list` + - :class:`str` with preferably url-encoded content + (**Warning:** content will not be encoded by *aiohttp*) :param data: The data to send in the body of the request. This can be a :class:`FormData` object or anything that can be passed into @@ -885,28 +904,46 @@ certification chaining. :param json: Any json compatible python object (optional). *json* and *data* parameters could not be used at the same time. + :param dict cookies: HTTP Cookies to send with the request (optional) + :param dict headers: HTTP Headers to send with the request (optional) - :param dict cookies: Cookies to send with the request (optional) + :param skip_auto_headers: set of headers for which autogeneration + should be skipped. + + *aiohttp* autogenerates headers like ``User-Agent`` or + ``Content-Type`` if these headers are not explicitly + passed. Using ``skip_auto_headers`` parameter allows to skip + that generation. + + Iterable of :class:`str` or :class:`~multidict.istr` + (optional) :param aiohttp.BasicAuth auth: an object that represents HTTP Basic Authorization (optional) :param bool allow_redirects: Whether to process redirects or not. - When ``True``, redirects are followed (up to ``max_redirects`` times) - and logged into :attr:`ClientResponse.history` and ``trace_configs``. - When ``False``, the original response is returned. - ``True`` by default (optional). + When ``True``, redirects are followed (up to ``max_redirects`` times) + and logged into :attr:`ClientResponse.history` and ``trace_configs``. + When ``False``, the original response is returned. + ``True`` by default (optional). - :param aiohttp.protocol.HttpVersion version: Request HTTP version (optional) + :param int max_redirects: Maximum number of redirects to follow. + :exc:`TooManyRedirects` is raised if the number is exceeded. + Ignored when ``allow_redirects=False``. + ``10`` by default. :param bool compress: Set to ``True`` if request has to be compressed - with deflate encoding. - ``False`` instructs aiohttp to not compress data. + with deflate encoding. If `compress` can not be combined + with a *Content-Encoding* and *Content-Length* headers. ``None`` by default (optional). :param int chunked: Enables chunked transfer encoding. - ``None`` by default (optional). + It is up to the developer + to decide how to chunk data streams. If chunking is enabled, aiohttp + encodes the provided chunks in the "Transfer-encoding: chunked" format. + If *chunked* is set, then the *Transfer-encoding* and *content-length* + headers are disallowed. ``None`` by default (optional). :param bool expect100: Expect 100-continue response from server. ``False`` by default (optional). @@ -920,28 +957,60 @@ certification chaining. .. versionadded:: 3.4 - :param aiohttp.BaseConnector connector: BaseConnector sub-class - instance to support connection pooling. - :param bool read_until_eof: Read response until EOF if response does not have Content-Length header. ``True`` by default (optional). + :param proxy: Proxy URL, :class:`str` or :class:`~yarl.URL` (optional) + + :param aiohttp.BasicAuth proxy_auth: an object that represents proxy HTTP + Basic Authorization (optional) + + :param timeout: a :class:`ClientTimeout` settings structure, 300 seconds (5min) + total timeout, 30 seconds socket connect timeout by default. + + :param ssl: SSL validation mode. ``True`` for default SSL check + (:func:`ssl.create_default_context` is used), + ``False`` for skip SSL certificate validation, + :class:`aiohttp.Fingerprint` for fingerprint + validation, :class:`ssl.SSLContext` for custom SSL + certificate validation. + + Supersedes *verify_ssl*, *ssl_context* and + *fingerprint* parameters. + + :param str server_hostname: Sets or overrides the host name that the + target server's certificate will be matched against. + + See :py:meth:`asyncio.loop.create_connection` + for more information. + + :param collections.abc.Mapping proxy_headers: HTTP headers to send to the proxy + if the parameter proxy has been provided. + + :param trace_request_ctx: Object used to give as a kw param for each new + :class:`TraceConfig` object instantiated, + used to give information to the + tracers that is only available at request time. + :param int read_bufsize: Size of the read buffer (:attr:`ClientResponse.content`). ``None`` by default, it means that the session global value is used. .. versionadded:: 3.7 - :param timeout: a :class:`ClientTimeout` settings structure, 300 seconds (5min) - total timeout, 30 seconds socket connect timeout by default. + :param bool auto_decompress: Automatically decompress response body. + May be used to enable/disable auto decompression on a per-request basis. - :param loop: :ref:`event loop` - used for processing HTTP requests. - If param is ``None``, :func:`asyncio.get_event_loop` - is used for getting default event loop. + :param int max_line_size: Maximum allowed size of lines in responses. - .. deprecated:: 2.0 + :param int max_field_size: Maximum allowed size of header fields in responses. + + :param aiohttp.protocol.HttpVersion version: Request HTTP version, + ``HTTP 1.1`` by default. (optional) + + :param aiohttp.BaseConnector connector: BaseConnector sub-class + instance to support connection pooling. (optional) :return ClientResponse: a :class:`client response ` object.