diff --git a/docs/client_reference.rst b/docs/client_reference.rst index 151fa8db51b..e82f5e6eb4c 100644 --- a/docs/client_reference.rst +++ b/docs/client_reference.rst @@ -34,11 +34,9 @@ Usage example:: print(html) loop = asyncio.get_event_loop() - loop.run_until_complete(main(loop)) + loop.run_until_complete(main()) -.. versionadded:: 0.17 - The client session supports the context manager protocol for self closing. .. class:: ClientSession(*, connector=None, loop=None, cookies=None, \ @@ -93,8 +91,6 @@ The client session supports the context manager protocol for self closing. :param version: supported HTTP version, ``HTTP 1.1`` by default. - .. versionadded:: 0.21 - :param cookie_jar: Cookie Jar, :class:`AbstractCookieJar` instance. By default every session instance has own private cookie jar for @@ -108,8 +104,6 @@ The client session supports the context manager protocol for self closing. :class:`aiohttp.helpers.DummyCookieJar` instance can be provided. - .. versionadded:: 0.22 - :param callable json_serialize: Json *serializer* callable. By default :func:`json.dumps` function. @@ -133,7 +127,7 @@ The client session supports the context manager protocol for self closing. Close connector instance on session closing. - Passing ``connector_owner=False`` to constructor allows to share + Setting the parameter to ``False`` allows to share connection pool between sessions without sharing session state: cookies etc. @@ -147,8 +141,19 @@ The client session supports the context manager protocol for self closing. *HTTPS_PROXY* environment variables if the parameter is ``True`` (``False`` by default). + Get proxy credentials from ``~/.netrc`` file if + present. + + .. seealso:: + + ``.netrc`` documentation: https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html + .. versionadded:: 2.3 + .. versionchanged:: 3.0 + + Added support for ``~/.netrc`` file. + .. attribute:: closed ``True`` if the session has been closed, ``False`` otherwise. @@ -170,8 +175,6 @@ The client session supports the context manager protocol for self closing. A read-only property. - .. versionadded:: 1.0 - .. attribute:: requote_redirect_url aiohttp re quote's redirect urls by default, but some servers @@ -302,18 +305,14 @@ The client session supports the context manager protocol for self closing. .. versionadded:: 2.3 - :return ClientResponse: a :class:`client response ` - object. - - .. versionadded:: 1.0 - - Added ``proxy`` and ``proxy_auth`` parameters. + :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. - Added ``timeout`` parameter. + .. versionadded:: 3.0 - .. versionchanged:: 1.1 - - URLs may be either :class:`str` or :class:`~yarl.URL` + :return ClientResponse: a :class:`client response ` + object. .. comethod:: get(url, *, allow_redirects=True, **kwargs) :async-with: @@ -322,7 +321,7 @@ The client session supports the context manager protocol for self closing. Perform a ``GET`` request. In order to modify inner - :meth:`request` + :meth:`request` parameters, provide `kwargs`. :param url: Request URL, :class:`str` or :class:`~yarl.URL` @@ -333,10 +332,6 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. versionchanged:: 1.1 - - URLs may be either :class:`str` or :class:`~yarl.URL` - .. comethod:: post(url, *, data=None, **kwargs) :async-with: :coroutine: @@ -344,7 +339,7 @@ The client session supports the context manager protocol for self closing. Perform a ``POST`` request. In order to modify inner - :meth:`request` + :meth:`request` parameters, provide `kwargs`. @@ -356,10 +351,6 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. versionchanged:: 1.1 - - URLs may be either :class:`str` or :class:`~yarl.URL` - .. comethod:: put(url, *, data=None, **kwargs) :async-with: :coroutine: @@ -367,7 +358,7 @@ The client session supports the context manager protocol for self closing. Perform a ``PUT`` request. In order to modify inner - :meth:`request` + :meth:`request` parameters, provide `kwargs`. @@ -379,10 +370,6 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. versionchanged:: 1.1 - - URLs may be either :class:`str` or :class:`~yarl.URL` - .. comethod:: delete(url, **kwargs) :async-with: :coroutine: @@ -390,7 +377,7 @@ The client session supports the context manager protocol for self closing. Perform a ``DELETE`` request. In order to modify inner - :meth:`request` + :meth:`request` parameters, provide `kwargs`. :param url: Request URL, :class:`str` or :class:`~yarl.URL` @@ -398,10 +385,6 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. versionchanged:: 1.1 - - URLs may be either :class:`str` or :class:`~yarl.URL` - .. comethod:: head(url, *, allow_redirects=False, **kwargs) :async-with: :coroutine: @@ -409,7 +392,7 @@ The client session supports the context manager protocol for self closing. Perform a ``HEAD`` request. In order to modify inner - :meth:`request` + :meth:`request` parameters, provide `kwargs`. :param url: Request URL, :class:`str` or :class:`~yarl.URL` @@ -420,10 +403,6 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. versionchanged:: 1.1 - - URLs may be either :class:`str` or :class:`~yarl.URL` - .. comethod:: options(url, *, allow_redirects=True, **kwargs) :async-with: :coroutine: @@ -431,7 +410,7 @@ The client session supports the context manager protocol for self closing. Perform an ``OPTIONS`` request. In order to modify inner - :meth:`request` + :meth:`request` parameters, provide `kwargs`. @@ -443,10 +422,6 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. versionchanged:: 1.1 - - URLs may be either :class:`str` or :class:`~yarl.URL` - .. comethod:: patch(url, *, data=None, **kwargs) :async-with: :coroutine: @@ -454,7 +429,7 @@ The client session supports the context manager protocol for self closing. Perform a ``PATCH`` request. In order to modify inner - :meth:`request` + :meth:`request` parameters, provide `kwargs`. :param url: Request URL, :class:`str` or :class:`~yarl.URL` @@ -466,10 +441,6 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. versionchanged:: 1.1 - - URLs may be either :class:`str` or :class:`~yarl.URL` - .. comethod:: ws_connect(url, *, protocols=(), timeout=10.0,\ receive_timeout=None,\ auth=None,\ @@ -569,6 +540,7 @@ The client session supports the context manager protocol for self closing. Session is switched to closed state anyway. + Basic API --------- @@ -580,18 +552,20 @@ keepaliving, cookies and complex connection stuff like properly configured SSL certification chaining. -.. coroutinefunction:: request(method, url, *, params=None, data=None, \ - json=None,\ - headers=None, cookies=None, auth=None, \ - allow_redirects=True, max_redirects=10, \ - encoding='utf-8', \ - version=HttpVersion(major=1, minor=1), \ - compress=None, chunked=None, expect100=False, \ - connector=None, loop=None,\ - read_until_eof=True) +.. cofunction:: request(method, url, *, params=None, data=None, \ + json=None,\ + headers=None, cookies=None, auth=None, \ + allow_redirects=True, max_redirects=10, \ + encoding='utf-8', \ + version=HttpVersion(major=1, minor=1), \ + compress=None, chunked=None, expect100=False, \ + connector=None, loop=None,\ + read_until_eof=True) + + :async-with: - Perform an asynchronous HTTP request. Return a response object - (:class:`ClientResponse` or derived from). + Asynchronous context manager for performing an asynchronous HTTP + request. Returns a :class:`ClientResponse` response object. :param str method: HTTP method @@ -654,10 +628,6 @@ certification chaining. assert resp.status == 200 print(await resp.text()) - .. versionchanged:: 1.1 - - URLs may be either :class:`str` or :class:`~yarl.URL` - .. _aiohttp-client-reference-connectors: @@ -727,8 +697,6 @@ BaseConnector Read-only property, ``True`` if connector should ultimately close connections on releasing. - .. versionadded:: 0.16 - .. attribute:: limit The total number for simultaneous connections. @@ -760,7 +728,7 @@ BaseConnector The call may be paused if :attr:`limit` is exhausted until used connections returns to pool. - :param aiohttp.client.ClientRequest request: request object + :param aiohttp.ClientRequest request: request object which is connection initiator. @@ -809,8 +777,6 @@ TCPConnector Note: use of MD5 or SHA1 digests is insecure and deprecated. - .. versionadded:: 0.16 - .. deprecated:: 2.3 Pass *verify_ssl* to ``ClientSession.get()`` etc. @@ -822,12 +788,6 @@ TCPConnector establishing a bit but may introduce some *side effects* also. - .. versionadded:: 0.17 - - .. versionchanged:: 1.0 - - The default is changed to ``True`` - :param int ttl_dns_cache: expire after some seconds the DNS entries, ``None`` means cached forever. By default 10 seconds. @@ -853,22 +813,19 @@ TCPConnector Custom resolvers allow to resolve hostnames differently than the way the host is configured. - .. versionchanged:: 1.1 - - The resolver is ``aiohttp.ThreadedResolver`` by default, - asynchronous version is not pretty robust but might fail in - very rare cases. + The resolver is ``aiohttp.ThreadedResolver`` by default, + asynchronous version is pretty robust but might fail in + very rare cases. :param int family: TCP socket family, both IPv4 and IPv6 by default. For *IPv4* only use :const:`socket.AF_INET`, for *IPv6* only -- :const:`socket.AF_INET6`. - .. versionchanged:: 0.18 - - *family* is `0` by default, that means both IPv4 and IPv6 are - accepted. To specify only concrete version please pass - :const:`socket.AF_INET` or :const:`socket.AF_INET6` - explicitly. + *family* is ``0`` by default, that means both + IPv4 and IPv6 are accepted. To specify only + concrete version please pass + :const:`socket.AF_INET` or + :const:`socket.AF_INET6` explicitly. :param ssl.SSLContext ssl_context: SSL context used for processing *HTTPS* requests (optional). @@ -879,8 +836,6 @@ TCPConnector :param tuple local_addr: tuple of ``(local_host, local_port)`` used to bind socket locally if specified. - .. versionadded:: 0.21 - :param bool force_close: close underlying sockets after connection releasing (optional). @@ -912,16 +867,12 @@ TCPConnector Read-only :class:`bool` property. - .. versionadded:: 0.17 - .. attribute:: cached_hosts The cache of resolved hosts if :attr:`dns_cache` is enabled. Read-only :class:`types.MappingProxyType` property. - .. versionadded:: 0.17 - .. attribute:: fingerprint MD5, SHA1, or SHA256 hash of the expected certificate in DER @@ -930,8 +881,6 @@ TCPConnector Read-only :class:`bytes` property. - .. versionadded:: 0.16 - .. method:: clear_dns_cache(self, host=None, port=None) Clear internal *DNS* cache. @@ -939,8 +888,6 @@ TCPConnector Remove specific entry if both *host* and *port* are specified, clear all cache otherwise. - .. versionadded:: 0.17 - UnixConnector ^^^^^^^^^^^^^ @@ -1039,10 +986,6 @@ Response object After exiting from ``async with`` block response object will be *released* (see :meth:`release` coroutine). - .. versionadded:: 0.18 - - Support for ``async with``. - .. attribute:: version Response's version, :class:`HttpVersion` instance. @@ -1109,13 +1052,20 @@ Response object .. attribute:: charset - Read-only property that specifies the *encoding* for the request's BODY. + Read-only property that specifies the *encoding* for the request's BODY. The value is parsed from the *Content-Type* HTTP header. Returns :class:`str` like ``'utf-8'`` or ``None`` if no *Content-Type* header present in HTTP headers or it has no charset information. + .. attribute:: content_disposition + + Read-only property that specified the *Content-Disposition* HTTP header. + + Instance of :class:`ContentDisposition` or ``None`` if no *Content-Disposition* + header present in HTTP headers. + .. attribute:: history A :class:`~collections.abc.Sequence` of :class:`ClientResponse` @@ -1223,6 +1173,15 @@ Response object A namedtuple with request URL and headers from :class:`ClientRequest` object, :class:`aiohttp.RequestInfo` instance. + .. method:: get_encoding() + + Automatically detect content encoding using ``charset`` info in + ``Content-Type`` HTTP header. If this info is not exists or there + are no appropriate codecs for encoding then :term:`cchardet` / + :term:`chardet` is used. + + .. versionadded:: 3.0 + ClientWebSocketResponse ----------------------- @@ -1256,7 +1215,7 @@ manually. Returns exception if any occurs or returns None. - .. method:: ping(message=b'') + .. comethod:: ping(message=b'') Send :const:`~aiohttp.WSMsgType.PING` to peer. @@ -1264,29 +1223,67 @@ manually. :class:`str` (converted to *UTF-8* encoded bytes) or :class:`bytes`. - .. comethod:: send_str(data) + .. versionchanged:: 3.0 + + The method is converted into :term:`coroutine` + + .. comethod:: pong(message=b'') + + Send :const:`~aiohttp.WSMsgType.PONG` to peer. + + :param message: optional payload of *pong* message, + :class:`str` (converted to *UTF-8* encoded bytes) + or :class:`bytes`. + + .. versionchanged:: 3.0 + + The method is converted into :term:`coroutine` + + .. comethod:: send_str(data, compress=None) Send *data* to peer as :const:`~aiohttp.WSMsgType.TEXT` message. :param str data: data to send. + :param int compress: sets specific level of compression for + single message, + ``None`` for not overriding per-socket setting. + :raise TypeError: if data is not :class:`str` - .. comethod:: send_bytes(data) + .. versionchanged:: 3.0 + + The method is converted into :term:`coroutine`, + *compress* parameter added. + + .. comethod:: send_bytes(data, compress=None) Send *data* to peer as :const:`~aiohttp.WSMsgType.BINARY` message. :param data: data to send. + :param int compress: sets specific level of compression for + single message, + ``None`` for not overriding per-socket setting. + :raise TypeError: if data is not :class:`bytes`, :class:`bytearray` or :class:`memoryview`. - .. comethod:: send_json(data, *, dumps=json.dumps) + .. versionchanged:: 3.0 + + The method is converted into :term:`coroutine`, + *compress* parameter added. + + .. comethod:: send_json(data, compress=None, *, dumps=json.dumps) Send *data* to peer as JSON string. :param data: data to send. + :param int compress: sets specific level of compression for + single message, + ``None`` for not overriding per-socket setting. + :param callable dumps: any :term:`callable` that accepts an object and returns a JSON string (:func:`json.dumps` by default). @@ -1298,6 +1295,11 @@ manually. :raise TypeError: if value returned by ``dumps(data)`` is not :class:`str` + .. versionchanged:: 3.0 + + The method is converted into :term:`coroutine`, + *compress* parameter added. + .. comethod:: close(*, code=1000, message=b'') A :ref:`coroutine` that initiates closing handshake by sending @@ -1561,6 +1563,23 @@ All exceptions are available as members of *aiohttp* module. Invalid URL, :class:`yarl.URL` instance. +.. class:: ContentDisposition + + Represent Content-Disposition header + + .. attribute:: value + + A :class:`str` instance. Value of Content-Disposition header + itself, e.g. ``attachment``. + + .. attribute:: filename + + A :class:`str` instance. Content filename extracted from + parameters. May be ``None``. + + .. attribute:: parameters + + Read-only mapping contains all parameters. Response errors ^^^^^^^^^^^^^^^