# Client Reference

## Client Session

Client session is the recommended interface for making HTTP requests.

Session encapsulates a connection pool (connector instance) and supports keepalives by default. Unless you are connecting to a large, unknown number of different servers over the lifetime of your application, it is suggested you use a single session for the lifetime of your application to benefit from connection pooling.

Usage example:

    import aiohttp
    import asyncio

    async def fetch(client):
        async with client.get('http://python.org') as resp:
            assert resp.status == 200
            return await resp.text()

    async def main():
        async with aiohttp.ClientSession() as client:
            html = await fetch(client)
            print(html)

    asyncio.run(main())

The client session supports the context manager protocol for self closing.

class aiohttp.ClientSession(base_url=None, *, connector=None, cookies=None, headers=None, skip_auto_headers=None, auth=None, json_serialize=json.dumps, request_class=ClientRequest, response_class=ClientResponse, ws_response_class=ClientWebSocketResponse, version=aiohttp.HttpVersion11, cookie_jar=None, connector_owner=True, raise_for_status=False, timeout=sentinel, auto_decompress=True, trust_env=False, requote_redirect_url=True, trace_configs=None, read_bufsize=2**16, max_line_size=8190, max_field_size=8190, fallback_charset_resolver=lambda r, b: ...)

  The class for creating client sessions and making requests.

  Parameters:

    - base_url –

      Base part of the URL (optional) If set, it allows to skip the base part (https://docs.aiohttp.org) in request calls. It must not include a path (as in https://docs.aiohttp.org/en/stable).

      Added in version 3.8.

    - connector (aiohttp.BaseConnector) – BaseConnector sub-class instance to support connection pooling.

    - cookies (dict) – Cookies to send with the request (optional)

    - headers –

      HTTP Headers to send with every request (optional).

      May be either iterable of key-value pairs or `Mapping` (e.g. `dict`, `CIMultiDict`).

    - 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. Note that `Content-Length` autogeneration can’t be skipped.

      Iterable of `str` or `istr` (optional)

    - auth (aiohttp.BasicAuth) – an object that represents HTTP Basic Authorization (optional). It will be included with any request to any origin and will not be removed, event during redirect to a different origin.

    - json_serialize (collections.abc.Callable) –

      Json serializer callable.

      By default `json.dumps()` function.

    - request_class (aiohttp.ClientRequest) – Custom class to use for client requests.

    - response_class (ClientResponse) – Custom class to use for client responses.

    - ws_response_class (ClientWebSocketResponse) – Custom class to use for websocket responses.

    - version – supported HTTP version, `HTTP 1.1` by default.

    - cookie_jar –

      Cookie Jar, `AbstractCookieJar` instance.

      By default every session instance has own private cookie jar for automatic cookies processing but user may redefine this behavior by providing own jar implementation.

      One example is not processing cookies at all when working in proxy mode.

      If no cookie processing is needed, a `aiohttp.DummyCookieJar` instance can be provided.

    - connector_owner (bool) –

      Close connector instance on session closing.

      Setting the parameter to `False` allows to share connection pool between sessions without sharing session state: cookies etc.

    - raise_for_status (bool) –

      Automatically call `ClientResponse.raise_for_status()` for each response, `False` by default.

      This parameter can be overridden when making a request, e.g.:

          client_session = aiohttp.ClientSession(raise_for_status=True)
          resp = await client_session.get(url, raise_for_status=False)
          async with resp:
              assert resp.status == 200

      Set the parameter to `True` if you need `raise_for_status` for most of cases but override `raise_for_status` for those requests where you need to handle responses with status 400 or higher.

      You can also provide a coroutine which takes the response as an argument and can raise an exception based on custom logic, e.g.:

          async def custom_check(response):
              if response.status not in {201, 202}:
                  raise RuntimeError('expected either 201 or 202')
              text = await response.text()
              if 'apple pie' not in text:
                  raise RuntimeError('I wanted to see "apple pie" in response')

          client_session = aiohttp.ClientSession(raise_for_status=custom_check)
          ...

      As with boolean values, you’re free to set this on the session and/or overwrite it on a per-request basis.

    - timeout –

      a `ClientTimeout` settings structure, 300 seconds (5min)

        total timeout, 30 seconds socket connect timeout by default.

      Added in version 3.3.

      Changed in version 3.10.9: The default value for the `sock_connect` timeout has been changed to 30 seconds.

    - auto_decompress (bool) –

      Automatically decompress response body (`True` by default).

      Added in version 2.3.

    - trust_env (bool) –

      Trust environment settings for proxy configuration if the parameter is `True` (`False` by default). See Proxy support for more information.

      Get proxy credentials from `~/.netrc` file if present.

      Get HTTP Basic Auth credentials from `~/.netrc` file if present.

      If `NETRC` environment variable is set, read from file specified there rather than from `~/.netrc`.

      See also

      `.netrc` documentation: https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html

      Added in version 2.3.

      Changed in version 3.0: Added support for `~/.netrc` file.

      Changed in version 3.9: Added support for reading HTTP Basic Auth credentials from `~/.netrc` file.

    - requote_redirect_url (bool) –

      Apply URL requoting for redirection URLs if

        automatic redirection is enabled (`True` by default).

      Added in version 3.5.

    - trace_configs – A list of `TraceConfig` instances used for client tracing. `None` (default) is used for request tracing disabling. See Tracing Reference for more information.

    - read_bufsize (int) –

      Size of the read buffer (`ClientResponse.content`).

        64 KiB by default.

      Added in version 3.7.

    - max_line_size (int) – Maximum allowed size of lines in responses.

    - max_field_size (int) – Maximum allowed size of header fields in responses.

    - fallback_charset_resolver (Callable[[ClientResponse,bytes],str]) –

      A callable that accepts a `ClientResponse` and the `bytes` contents, and returns a `str` which will be used as the encoding parameter to `bytes.decode()`.

      This function will be called when the charset is not known (e.g. not specified in the Content-Type header). The default function simply defaults to `utf-8`.

      Added in version 3.8.6.

  closed

    `True` if the session has been closed, `False` otherwise.

    A read-only property.

  connector

    `aiohttp.BaseConnector` derived instance used for the session.

    A read-only property.

  cookie_jar

    The session cookies, `AbstractCookieJar` instance.

    Gives access to cookie jar’s content and modifiers.

    A read-only property.

  requote_redirect_url

    aiohttp re quote’s redirect urls by default, but some servers require exact url from location header. To disable re-quote system set `requote_redirect_url` attribute to `False`.

    Added in version 2.1.

    Note

    This parameter affects all subsequent requests.

    Deprecated since version 3.5: The attribute modification is deprecated.

  loop

    A loop instance used for session creation.

    A read-only property.

    Deprecated since version 3.5.

  timeout

    Default client timeouts, `ClientTimeout` instance. The value can be tuned by passing timeout parameter to `ClientSession` constructor.

    Added in version 3.7.

  headers

    HTTP Headers that sent with every request

    May be either iterable of key-value pairs or `Mapping` (e.g. `dict`, `CIMultiDict`).

    Added in version 3.7.

  skip_auto_headers

    Set of headers for which autogeneration skipped.

    `frozenset` of `str` or `istr` (optional)

    Added in version 3.7.

  auth

    An object that represents HTTP Basic Authorization.

    `BasicAuth` (optional)

    Added in version 3.7.

  json_serialize

    Json serializer callable.

    By default `json.dumps()` function.

    Added in version 3.7.

  connector_owner

    Should connector be closed on session closing

    `bool` (optional)

    Added in version 3.7.

  raise_for_status

    Should `ClientResponse.raise_for_status()` be called for each response

    Either `bool` or `collections.abc.Callable`

    Added in version 3.7.

  auto_decompress

    Should the body response be automatically decompressed

    `bool` default is `True`

    Added in version 3.7.

  trust_env

    Trust environment settings for proxy configuration or ~/.netrc file if present. See Proxy support for more information.

    `bool` default is `False`

    Added in version 3.7.

  trace_config

    A list of `TraceConfig` instances used for client tracing. `None` (default) is used for request tracing disabling. See Tracing Reference for more information.

    Added in version 3.7.

  async request(method, url, *, params=None, data=None, json=None, cookies=None, headers=None, skip_auto_headers=None, auth=None, allow_redirects=True, max_redirects=10, compress=None, 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, auto_decompress=None, max_line_size=None, max_field_size=None)

    Performs an asynchronous HTTP request. Returns a response object that should be used as an async context manager.

    Parameters:

      - method (str) – HTTP method

      - url – Request URL, `URL` or `str` that will be encoded with `URL` (see `URL` to skip encoding).

      - 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:

        - `collections.abc.Mapping` e.g. `dict`, `multidict.MultiDict` or `multidict.MultiDictProxy`

        - `collections.abc.Iterable` e.g. `tuple` or `list`

        - `str` with preferably url-encoded content (Warning: content will not be encoded by aiohttp)

      - data – The data to send in the body of the request. This can be a `FormData` object or anything that can be passed into `FormData`, e.g. a dictionary, bytes, or file-like object. (optional)

      - json – Any json compatible python object (optional). json and data parameters could not be used at the same time.

      - cookies (dict) –

        HTTP Cookies to send with

          the request (optional)

        Global session cookies and the explicitly set cookies will be merged when sending the request.

        Added in version 3.5.

      - headers (dict) – HTTP Headers to send with the request (optional)

      - 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 `str` or `istr` (optional)

      - auth (aiohttp.BasicAuth) – an object that represents HTTP Basic Authorization (optional)

      - allow_redirects (bool) – If set to `False`, do not follow redirects. `True` by default (optional).

      - max_redirects (int) – Maximum number of redirects to follow. `10` by default.

      - compress (bool) – Set to `True` if request has to be compressed with deflate encoding. If compress can not be combined with a Content-Encoding and Content-Length headers. `None` by default (optional).

      - chunked (int) – Enable chunked transfer encoding. 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).

      - expect100 (bool) – Expect 100-continue response from server. `False` by default (optional).

      - raise_for_status (bool) –

        Automatically call `ClientResponse.raise_for_status()` for

          response if set to `True`. If set to `None` value from `ClientSession` will be used. `None` by default (optional).

        Added in version 3.4.

      - read_until_eof (bool) – Read response until EOF if response does not have Content-Length header. `True` by default (optional).

      - proxy – Proxy URL, `str` or `URL` (optional)

      - proxy_auth (aiohttp.BasicAuth) – an object that represents proxy HTTP Basic Authorization (optional)

      - timeout (int) –

        override the session’s timeout.

        Changed in version 3.3: The parameter is `ClientTimeout` instance, `float` is still supported for sake of backward compatibility.

        If `float` is passed it is a total timeout (in seconds).

      - ssl –

        SSL validation mode. `True` for default SSL check

          (`ssl.create_default_context()` is used), `False` for skip SSL certificate validation, `aiohttp.Fingerprint` for fingerprint validation, `ssl.SSLContext` for custom SSL certificate validation.

          Supersedes verify_ssl, ssl_context and fingerprint parameters.

        Added in version 3.0.

      - server_hostname (str) –

        Sets or overrides the host name that the target server’s certificate will be matched against.

        See `asyncio.loop.create_connection()` for more information.

        Added in version 3.9.

      - proxy_headers (collections.abc.Mapping) –

        HTTP headers to send to the proxy if the parameter proxy has been provided.

        Added in version 2.3.

      - trace_request_ctx –

        Object used to give as a kw param for each new `TraceConfig` object instantiated, used to give information to the tracers that is only available at request time.

        > Added in version 3.0.

      - read_bufsize (int) –

        Size of the read buffer (`ClientResponse.content`).

          `None` by default, it means that the session global value is used.

        Added in version 3.7.

      - auto_decompress (bool) – Automatically decompress response body. Overrides `ClientSession.auto_decompress`. May be used to enable/disable auto decompression on a per-request basis.

      - max_line_size (int) – Maximum allowed size of lines in responses.

      - max_field_size (int) – Maximum allowed size of header fields in responses.

    Return ClientResponse:

      a `client response` object.

  async get(url, *, allow_redirects=True, **kwargs)

    Perform a `GET` request. Returns an async context manager.

    In order to modify inner `request` parameters, provide kwargs.

    Parameters:

      - url – Request URL, `str` or `URL`

      - allow_redirects (bool) – If set to `False`, do not follow redirects. `True` by default (optional).

    Return ClientResponse:

      a `client response` object.

  async post(url, *, data=None, **kwargs)

    Perform a `POST` request. Returns an async context manager.

    In order to modify inner `request` parameters, provide kwargs.

    Parameters:

      - url – Request URL, `str` or `URL`

      - data – Data to send in the body of the request; see `request` for details (optional)

    Return ClientResponse:

      a `client response` object.

  async put(url, *, data=None, **kwargs)

    Perform a `PUT` request. Returns an async context manager.

    In order to modify inner `request` parameters, provide kwargs.

    Parameters:

      - url – Request URL, `str` or `URL`

      - data – Data to send in the body of the request; see `request` for details (optional)

    Return ClientResponse:

      a `client response` object.

  async delete(url, **kwargs)

    Perform a `DELETE` request. Returns an async context manager.

    In order to modify inner `request` parameters, provide kwargs.

    Parameters:

      url – Request URL, `str` or `URL`

    Return ClientResponse:

      a `client response` object.

  async head(url, *, allow_redirects=False, **kwargs)

    Perform a `HEAD` request. Returns an async context manager.

    In order to modify inner `request` parameters, provide kwargs.

    Parameters:

      - url – Request URL, `str` or `URL`

      - allow_redirects (bool) – If set to `False`, do not follow redirects. `False` by default (optional).

    Return ClientResponse:

      a `client response` object.

  async options(url, *, allow_redirects=True, **kwargs)

    Perform an `OPTIONS` request. Returns an async context manager.

    In order to modify inner `request` parameters, provide kwargs.

    Parameters:

      - url – Request URL, `str` or `URL`

      - allow_redirects (bool) – If set to `False`, do not follow redirects. `True` by default (optional).

    Return ClientResponse:

      a `client response` object.

  async patch(url, *, data=None, **kwargs)

    Perform a `PATCH` request. Returns an async context manager.

    In order to modify inner `request` parameters, provide kwargs.

    Parameters:

      - url – Request URL, `str` or `URL`

      - data – Data to send in the body of the request; see `request` for details (optional)

    Return ClientResponse:

      a `client response` object.

  async ws_connect(url, *, method='GET', protocols=(), timeout=10.0, receive_timeout=None, auth=None, autoclose=True, autoping=True, heartbeat=None, origin=None, params=None, headers=None, proxy=None, proxy_auth=None, ssl=True, verify_ssl=None, fingerprint=None, ssl_context=None, proxy_headers=None, compress=0, max_msg_size=4194304)

    Create a websocket connection. Returns a `ClientWebSocketResponse` async context manager object.

    Parameters:

      - url – Websocket server url, `URL` or `str` that will be encoded with `URL` (see `URL` to skip encoding).

      - protocols (tuple) – Websocket protocols

      - timeout (float) – Timeout for websocket to close. `10` seconds by default

      - receive_timeout (float) – Timeout for websocket to receive complete message. `None` (unlimited) seconds by default

      - auth (aiohttp.BasicAuth) – an object that represents HTTP Basic Authorization (optional)

      - autoclose (bool) – Automatically close websocket connection on close message from server. If autoclose is False then close procedure has to be handled manually. `True` by default

      - autoping (bool) – automatically send pong on ping message from server. `True` by default

      - heartbeat (float) – Send ping message every heartbeat seconds and wait pong response, if pong response is not received then close connection. The timer is reset on any data reception.(optional)

      - origin (str) – Origin header to send to server(optional)

      - 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:

        - `collections.abc.Mapping` e.g. `dict`, `multidict.MultiDict` or `multidict.MultiDictProxy`

        - `collections.abc.Iterable` e.g. `tuple` or `list`

        - `str` with preferably url-encoded content (Warning: content will not be encoded by aiohttp)

      - headers (dict) – HTTP Headers to send with the request (optional)

      - proxy (str) – Proxy URL, `str` or `URL` (optional)

      - proxy_auth (aiohttp.BasicAuth) – an object that represents proxy HTTP Basic Authorization (optional)

      - ssl –

        SSL validation mode. `True` for default SSL check

          (`ssl.create_default_context()` is used), `False` for skip SSL certificate validation, `aiohttp.Fingerprint` for fingerprint validation, `ssl.SSLContext` for custom SSL certificate validation.

          Supersedes verify_ssl, ssl_context and fingerprint parameters.

        Added in version 3.0.

      - verify_ssl (bool) –

        Perform SSL certificate validation for HTTPS requests (enabled by default). May be disabled to skip validation for sites with invalid certificates.

        Added in version 2.3.

        Deprecated since version 3.0: Use `ssl=False`

      - fingerprint (bytes) –

        Pass the SHA256 digest of the expected certificate in DER format to verify that the certificate the server presents matches. Useful for certificate pinning.

        Note: use of MD5 or SHA1 digests is insecure and deprecated.

        Added in version 2.3.

        Deprecated since version 3.0: Use `ssl=aiohttp.Fingerprint(digest)`

      - ssl_context (ssl.SSLContext) –

        ssl context used for processing HTTPS requests (optional).

        ssl_context may be used for configuring certification authority channel, supported SSL options etc.

        Added in version 2.3.

        Deprecated since version 3.0: Use `ssl=ssl_context`

      - proxy_headers (dict) –

        HTTP headers to send to the proxy if the parameter proxy has been provided.

        Added in version 2.3.

      - compress (int) –

        Enable Per-Message Compress Extension support.

          0 for disable, 9 to 15 for window bit support. Default value is 0.

        Added in version 2.3.

      - max_msg_size (int) –

        maximum size of read websocket message,

          4 MB by default. To disable the size limit use `0`.

        Added in version 3.3.

      - method (str) –

        HTTP method to establish WebSocket connection,

          `'GET'` by default.

        Added in version 3.5.

  async close()

    Close underlying connector.

    Release all acquired resources.

  detach()

    Detach connector from session without closing the former.

    Session is switched to closed state anyway.

## Basic API

While we encourage `ClientSession` usage we also provide simple coroutines for making HTTP requests.

Basic API is good for performing simple HTTP requests without keepaliving, cookies and complex connection stuff like properly configured SSL certification chaining.

async aiohttp.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, raise_for_status=False, read_bufsize=None, connector=None, loop=None, read_until_eof=True, timeout=sentinel)

  Asynchronous context manager for performing an asynchronous HTTP request. Returns a `ClientResponse` response object. Use as an async context manager.

  Parameters:

    - method (str) – HTTP method

    - url – Request URL, `URL` or `str` that will be encoded with `URL` (see `URL` to skip encoding).

    - params (dict) – Parameters to be sent in the query string of the new request (optional)

    - data – The data to send in the body of the request. This can be a `FormData` object or anything that can be passed into `FormData`, e.g. a dictionary, bytes, or file-like object. (optional)

    - json – Any json compatible python object (optional). json and data parameters could not be used at the same time.

    - headers (dict) – HTTP Headers to send with the request (optional)

    - cookies (dict) – Cookies to send with the request (optional)

    - auth (aiohttp.BasicAuth) – an object that represents HTTP Basic Authorization (optional)

    - allow_redirects (bool) – If set to `False`, do not follow redirects. `True` by default (optional).

    - version (aiohttp.protocol.HttpVersion) – Request HTTP version (optional)

    - compress (bool) – Set to `True` if request has to be compressed with deflate encoding. `False` instructs aiohttp to not compress data. `None` by default (optional).

    - chunked (int) – Enables chunked transfer encoding. `None` by default (optional).

    - expect100 (bool) – Expect 100-continue response from server. `False` by default (optional).

    - raise_for_status (bool) –

      Automatically call

        `ClientResponse.raise_for_status()` for response if set to `True`. If set to `None` value from `ClientSession` will be used. `None` by default (optional).

      Added in version 3.4.

    - connector (aiohttp.BaseConnector) – BaseConnector sub-class instance to support connection pooling.

    - read_until_eof (bool) – Read response until EOF if response does not have Content-Length header. `True` by default (optional).

    - read_bufsize (int) –

      Size of the read buffer (`ClientResponse.content`).

        `None` by default, it means that the session global value is used.

      Added in version 3.7.

    - timeout – a `ClientTimeout` settings structure, 300 seconds (5min) total timeout, 30 seconds socket connect timeout by default.

    - loop –

      event loop

        used for processing HTTP requests. If param is `None`, `asyncio.get_event_loop()` is used for getting default event loop.

      Deprecated since version 2.0.

  Return ClientResponse:

    a `client response` object.

  Usage:

      import aiohttp

      async def fetch():
          async with aiohttp.request('GET',
                  'http://python.org/') as resp:
              assert resp.status == 200
              print(await resp.text())

## Connectors

Connectors are transports for aiohttp client API.

There are standard connectors:

1. `TCPConnector` for regular TCP sockets (both HTTP and HTTPS schemes supported).

2. `UnixConnector` for connecting via UNIX socket (it’s used mostly for testing purposes).

All connector classes should be derived from `BaseConnector`.

By default all connectors support keep-alive connections (behavior is controlled by force_close constructor’s parameter).

class aiohttp.BaseConnector(*, keepalive_timeout=15, force_close=False, limit=100, limit_per_host=0, enable_cleanup_closed=False, loop=None)

  Base class for all connectors.

  Parameters:

    - keepalive_timeout (float) – timeout for connection reusing after releasing (optional). Values `0`. For disabling keep-alive feature use `force_close=True` flag.

    - limit (int) – total number simultaneous connections. If limit is `0` the connector has no limit (default: 100).

    - limit_per_host (int) – limit simultaneous connections to the same endpoint. Endpoints are the same if they are have equal `(host, port, is_ssl)` triple. If limit is `0` the connector has no limit (default: 0).

    - force_close (bool) – close underlying sockets after connection releasing (optional).

    - enable_cleanup_closed (bool) –

      some SSL servers do not properly complete SSL shutdown process, in that case asyncio leaks SSL connections. If this parameter is set to True, aiohttp additionally aborts underlining transport after 2 seconds. It is off by default.

      For Python version 3.12.7+, or 3.13.1 and later, this parameter is ignored because the asyncio SSL connection leak is fixed in these versions of Python.

    - loop –

      event loop used for handling connections. If param is `None`, `asyncio.get_event_loop()` is used for getting default event loop.

      Deprecated since version 2.0.

  closed

    Read-only property, `True` if connector is closed.

  force_close

    Read-only property, `True` if connector should ultimately close connections on releasing.

  limit

    The total number for simultaneous connections. If limit is 0 the connector has no limit. The default limit size is 100.

  limit_per_host

    The limit for simultaneous connections to the same endpoint.

    Endpoints are the same if they are have equal `(host, port, is_ssl)` triple.

    If limit_per_host is `0` the connector has no limit per host.

    Read-only property.

  async close()

    Close all opened connections.

  async connect(request)

    Get a free connection from pool or create new one if connection is absent in the pool.

    The call may be paused if `limit` is exhausted until used connections returns to pool.

    Parameters:

      request (aiohttp.ClientRequest) – request object which is connection initiator.

    Returns:

      `Connection` object.

  async _create_connection(req)

    Abstract method for actual connection establishing, should be overridden in subclasses.

class aiohttp.TCPConnector(*, ssl=True, verify_ssl=True, fingerprint=None, use_dns_cache=True, ttl_dns_cache=10, family=0, ssl_context=None, local_addr=None, resolver=None, keepalive_timeout=sentinel, force_close=False, limit=100, limit_per_host=0, enable_cleanup_closed=False, timeout_ceil_threshold=5, happy_eyeballs_delay=0.25, interleave=None, loop=None)

  Connector for working with HTTP and HTTPS via TCP sockets.

  The most common transport. When you don’t know what connector type to use, use a `TCPConnector` instance.

  `TCPConnector` inherits from `BaseConnector`.

  Constructor accepts all parameters suitable for `BaseConnector` plus several TCP-specific ones:

  > param ssl:
  >   SSL validation mode. `True` for default SSL check

  >     (`ssl.create_default_context()` is used), `False` for skip SSL certificate validation, `aiohttp.Fingerprint` for fingerprint validation, `ssl.SSLContext` for custom SSL certificate validation.

  >     Supersedes verify_ssl, ssl_context and fingerprint parameters.

  >   Added in version 3.0.

  Parameters:

    - verify_ssl (bool) –

      perform SSL certificate validation for HTTPS requests (enabled by default). May be disabled to skip validation for sites with invalid certificates.

      Deprecated since version 2.3: Pass verify_ssl to `ClientSession.get()` etc.

    - fingerprint (bytes) –

      pass the SHA256 digest of the expected certificate in DER format to verify that the certificate the server presents matches. Useful for certificate pinning.

      Note: use of MD5 or SHA1 digests is insecure and deprecated.

      Deprecated since version 2.3: Pass verify_ssl to `ClientSession.get()` etc.

    - use_dns_cache (bool) –

      use internal cache for DNS lookups, `True` by default.

      Enabling an option may speedup connection establishing a bit but may introduce some side effects also.

    - ttl_dns_cache (int) –

      expire after some seconds the DNS entries, `None` means cached forever. By default 10 seconds (optional).

      In some environments the IP addresses related to a specific HOST can change after a specific time. Use this option to keep the DNS cache updated refreshing each entry after N seconds.

    - limit (int) – total number simultaneous connections. If limit is `0` the connector has no limit (default: 100).

    - limit_per_host (int) – limit simultaneous connections to the same endpoint. Endpoints are the same if they are have equal `(host, port, is_ssl)` triple. If limit is `0` the connector has no limit (default: 0).

    - resolver (aiohttp.abc.AbstractResolver) –

      custom resolver instance to use. `aiohttp.DefaultResolver` by default (asynchronous if `aiodns>=1.1` is installed).

      Custom resolvers allow to resolve hostnames differently than the way the host is configured.

      The resolver is `aiohttp.ThreadedResolver` by default, asynchronous version is pretty robust but might fail in very rare cases.

    - family (int) –

      TCP socket family, both IPv4 and IPv6 by default. For IPv4 only use `socket.AF_INET`, for IPv6 only – `socket.AF_INET6`.

      family is `0` by default, that means both IPv4 and IPv6 are accepted. To specify only concrete version please pass `socket.AF_INET` or `socket.AF_INET6` explicitly.

    - ssl_context (ssl.SSLContext) –

      SSL context used for processing HTTPS requests (optional).

      ssl_context may be used for configuring certification authority channel, supported SSL options etc.

    - local_addr (tuple) – tuple of `(local_host, local_port)` used to bind socket locally if specified.

    - force_close (bool) – close underlying sockets after connection releasing (optional).

    - enable_cleanup_closed (bool) – Some ssl servers do not properly complete SSL shutdown process, in that case asyncio leaks SSL connections. If this parameter is set to True, aiohttp additionally aborts underlining transport after 2 seconds. It is off by default.

    - happy_eyeballs_delay (float) –

      The amount of time in seconds to wait for a connection attempt to complete, before starting the next attempt in parallel. This is the “Connection Attempt Delay” as defined in RFC 8305. To disable Happy Eyeballs, set this to `None`. The default value recommended by the RFC is 0.25 (250 milliseconds).

      > Added in version 3.10.

    - interleave (int) –

      controls address reordering when a host name resolves to multiple IP addresses. If `0` or unspecified, no reordering is done, and addresses are tried in the order returned by the resolver. If a positive integer is specified, the addresses are interleaved by address family, and the given integer is interpreted as “First Address Family Count” as defined in RFC 8305. The default is `0` if happy_eyeballs_delay is not specified, and `1` if it is.

      > Added in version 3.10.

  family

    TCP socket family e.g. `socket.AF_INET` or `socket.AF_INET6`

    Read-only property.

  dns_cache

    Use quick lookup in internal DNS cache for host names if `True`.

    Read-only `bool` property.

  cached_hosts

    The cache of resolved hosts if `dns_cache` is enabled.

    Read-only `types.MappingProxyType` property.

  clear_dns_cache(self, host=None, port=None)

    Clear internal DNS cache.

    Remove specific entry if both host and port are specified, clear all cache otherwise.

class aiohttp.UnixConnector(path, *, conn_timeout=None, keepalive_timeout=30, limit=100, force_close=False, loop=None)

  Unix socket connector.

  Use `UnixConnector` for sending HTTP/HTTPS requests through UNIX Sockets as underlying transport.

  UNIX sockets are handy for writing tests and making very fast connections between processes on the same host.

  `UnixConnector` is inherited from `BaseConnector`.

  > Usage:

  >     conn = UnixConnector(path='/path/to/socket')
  >     session = ClientSession(connector=conn)
  >     async with session.get('http://python.org') as resp:
  >         ...

  Constructor accepts all parameters suitable for `BaseConnector` plus UNIX-specific one:

  Parameters:

    path (str) – Unix socket path

  path

    Path to UNIX socket, read-only `str` property.

class aiohttp.Connection

  Encapsulates single connection in connector object.

  End user should never create `Connection` instances manually but get it by `BaseConnector.connect()` coroutine.

  closed

    `bool` read-only property, `True` if connection was closed, released or detached.

  loop

    Event loop used for connection

    Deprecated since version 3.5.

  transport

    Connection transport

  close()

    Close connection with forcibly closing underlying socket.

  release()

    Release connection back to connector.

    Underlying socket is not closed, the connection may be reused later if timeout (30 seconds by default) for connection was not expired.

## Response object

class aiohttp.ClientResponse

  Client response returned by `aiohttp.ClientSession.request()` and family.

  User never creates the instance of ClientResponse class but gets it from API calls.

  `ClientResponse` supports async context manager protocol, e.g.:

      resp = await client_session.get(url)
      async with resp:
          assert resp.status == 200

  After exiting from `async with` block response object will be released (see `release()` method).

  version

    Response’s version, `HttpVersion` instance.

  status

    HTTP status code of response (`int`), e.g. `200`.

  reason

    HTTP status reason of response (`str`), e.g. `"OK"`.

  ok

    Boolean representation of HTTP status code (`bool`). `True` if `status` is less than `400`; otherwise, `False`.

  method

    Request’s method (`str`).

  url

    URL of request (`URL`).

  real_url

    Unmodified URL of request with URL fragment unstripped (`URL`).

    Added in version 3.2.

  connection

    `Connection` used for handling response.

  content

    Payload stream, which contains response’s BODY (`StreamReader`). It supports various reading methods depending on the expected format. When chunked transfer encoding is used by the server, allows retrieving the actual http chunks.

    Reading from the stream may raise `aiohttp.ClientPayloadError` if the response object is closed before response receives all data or in case if any transfer encoding related errors like malformed chunked encoding of broken compression data.

  cookies

    HTTP cookies of response (Set-Cookie HTTP header, `SimpleCookie`).

  headers

    A case-insensitive multidict proxy with HTTP headers of response, `CIMultiDictProxy`.

  raw_headers

    Unmodified HTTP headers of response as unconverted bytes, a sequence of `(key, value)` pairs.

  links

    Link HTTP header parsed into a `MultiDictProxy`.

    For each link, key is link param rel when it exists, or link url as `str` otherwise, and value is `MultiDictProxy` of link params and url at key url as `URL` instance.

    Added in version 3.2.

  content_type

    Read-only property with content part of Content-Type header.

    Note

    Returns value is `'application/octet-stream'` if no Content-Type header present in HTTP headers according to RFC 2616. To make sure Content-Type header is not present in the server reply, use `headers` or `raw_headers`, e.g. `'CONTENT-TYPE' not in resp.headers`.

  charset

    Read-only property that specifies the encoding for the request’s BODY.

    The value is parsed from the Content-Type HTTP header.

    Returns `str` like `'utf-8'` or `None` if no Content-Type header present in HTTP headers or it has no charset information.

  content_disposition

    Read-only property that specified the Content-Disposition HTTP header.

    Instance of `ContentDisposition` or `None` if no Content-Disposition header present in HTTP headers.

  history

    A `Sequence` of `ClientResponse` objects of preceding requests (earliest request first) if there were redirects, an empty sequence otherwise.

  close()

    Close response and underlying connection.

    For keep-alive support see `release()`.

  async read()

    Read the whole response’s body as `bytes`.

    Close underlying connection if data reading gets an error, release connection otherwise.

    Raise an `aiohttp.ClientResponseError` if the data can’t be read.

    Return bytes:

      read BODY.

    See also

    `close()`, `release()`.

  release()

    It is not required to call release on the response object. When the client fully receives the payload, the underlying connection automatically returns back to pool. If the payload is not fully read, the connection is closed

  raise_for_status()

    Raise an `aiohttp.ClientResponseError` if the response status is 400 or higher.

    Do nothing for success responses (less than 400).

  async text(encoding=None)

    Read response’s body and return decoded `str` using specified encoding parameter.

    If encoding is `None` content encoding is determined from the Content-Type header, or using the `fallback_charset_resolver` function.

    Close underlying connection if data reading gets an error, release connection otherwise.

    Parameters:

      encoding (str) – text encoding used for BODY decoding, or `None` for encoding autodetection (default).

    Raises:

      `UnicodeDecodeError` if decoding fails. See also `get_encoding()`.

    Return str:

      decoded BODY

  async json(*, encoding=None, loads=json.loads, content_type='application/json')

    Read response’s body as JSON, return `dict` using specified encoding and loader. If data is not still available a `read` call will be done.

    If response’s content-type does not match content_type parameter `aiohttp.ContentTypeError` get raised. To disable content type check pass `None` value.

    Parameters:

      - encoding (str) –

        text encoding used for BODY decoding, or `None` for encoding autodetection (default).

        By the standard JSON encoding should be `UTF-8` but practice beats purity: some servers return non-UTF responses. Autodetection works pretty fine anyway.

      - loads (collections.abc.Callable) – callable used for loading JSON data, `json.loads()` by default.

      - content_type (str) – specify response’s content-type, if content type does not match raise `aiohttp.ClientResponseError`. To disable content-type check, pass `None` as value. (default: application/json).

    Returns:

      BODY as JSON data parsed by loads parameter or `None` if BODY is empty or contains white-spaces only.

  request_info

    A namedtuple with request URL and headers from `ClientRequest` object, `aiohttp.RequestInfo` instance.

  get_encoding()

    Retrieve content encoding using `charset` info in `Content-Type` HTTP header. If no charset is present or the charset is not understood by Python, the `fallback_charset_resolver` function associated with the `ClientSession` is called.

    Added in version 3.0.

## ClientWebSocketResponse

To connect to a websocket server `aiohttp.ws_connect()` or `aiohttp.ClientSession.ws_connect()` coroutines should be used, do not create an instance of class `ClientWebSocketResponse` manually.

class aiohttp.ClientWebSocketResponse

  Class for handling client-side websockets.

  closed

    Read-only property, `True` if `close()` has been called or `CLOSE` message has been received from peer.

  protocol

    Websocket subprotocol chosen after `start()` call.

    May be `None` if server and client protocols are not overlapping.

  get_extra_info(name, default=None)

    Reads optional extra information from the connection’s transport. If no value associated with `name` is found, `default` is returned.

    See `asyncio.BaseTransport.get_extra_info()`

    Parameters:

      - name (str) – The key to look up in the transport extra information.

      - default – Default value to be used when no value for `name` is found (default is `None`).

  exception()

    Returns exception if any occurs or returns None.

  async ping(message=b'')

    Send `PING` to peer.

    Parameters:

      message – optional payload of ping message, `str` (converted to UTF-8 encoded bytes) or `bytes`.

    Changed in version 3.0: The method is converted into coroutine

  async pong(message=b'')

    Send `PONG` to peer.

    Parameters:

      message – optional payload of pong message, `str` (converted to UTF-8 encoded bytes) or `bytes`.

    Changed in version 3.0: The method is converted into coroutine

  async send_str(data, compress=None)

    Send data to peer as `TEXT` message.

    Parameters:

      - data (str) – data to send.

      - compress (int) – sets specific level of compression for single message, `None` for not overriding per-socket setting.

    Raises:

      TypeError – if data is not `str`

    Changed in version 3.0: The method is converted into coroutine, compress parameter added.

  async send_bytes(data, compress=None)

    Send data to peer as `BINARY` message.

    Parameters:

      - data – data to send.

      - compress (int) – sets specific level of compression for single message, `None` for not overriding per-socket setting.

    Raises:

      TypeError – if data is not `bytes`, `bytearray` or `memoryview`.

    Changed in version 3.0: The method is converted into coroutine, compress parameter added.

  async send_json(data, compress=None, *, dumps=json.dumps)

    Send data to peer as JSON string.

    Parameters:

      - data – data to send.

      - compress (int) – sets specific level of compression for single message, `None` for not overriding per-socket setting.

      - dumps (collections.abc.Callable) – any callable that accepts an object and returns a JSON string (`json.dumps()` by default).

    Raises:

      - RuntimeError – if connection is not started or closing

      - ValueError – if data is not serializable object

      - TypeError – if value returned by `dumps(data)` is not `str`

    Changed in version 3.0: The method is converted into coroutine, compress parameter added.

  async close(*, code=WSCloseCode.OK, message=b'')

    A coroutine that initiates closing handshake by sending `CLOSE` message. It waits for close response from server. To add a timeout to close() call just wrap the call with asyncio.wait() or asyncio.wait_for().

    Parameters:

      - code (int) – closing code. See also `WSCloseCode`.

      - message – optional payload of close message, `str` (converted to UTF-8 encoded bytes) or `bytes`.

  async receive()

    A coroutine that waits upcoming data message from peer and returns it.

    The coroutine implicitly handles `PING`, `PONG` and `CLOSE` without returning the message.

    It process ping-pong game and performs closing handshake internally.

    Returns:

      `WSMessage`

  async receive_str()

    A coroutine that calls `receive()` but also asserts the message type is `TEXT`.

    Return str:

      peer’s message content.

    Raises:

      TypeError – if message is `BINARY`.

  async receive_bytes()

    A coroutine that calls `receive()` but also asserts the message type is `BINARY`.

    Return bytes:

      peer’s message content.

    Raises:

      TypeError – if message is `TEXT`.

  async receive_json(*, loads=json.loads)

    A coroutine that calls `receive_str()` and loads the JSON string to a Python dict.

    Parameters:

      loads (collections.abc.Callable) – any callable that accepts `str` and returns `dict` with parsed JSON (`json.loads()` by default).

    Return dict:

      loaded JSON content

    Raises:

      - TypeError – if message is `BINARY`.

      - ValueError – if message is not valid JSON.

## Utilities

class aiohttp.ClientTimeout(*, total=None, connect=None, sock_connect=None, sock_read=None)

  A data class for client timeout settings.

  See Timeouts for usage examples.

  total

    Total number of seconds for the whole request.

    `float`, `None` by default.

  connect

    Maximal number of seconds for acquiring a connection from pool. The time consists connection establishment for a new connection or waiting for a free connection from a pool if pool connection limits are exceeded.

    For pure socket connection establishment time use `sock_connect`.

    `float`, `None` by default.

  sock_connect

    Maximal number of seconds for connecting to a peer for a new connection, not given from a pool. See also `connect`.

    `float`, `None` by default.

  sock_read

    Maximal number of seconds for reading a portion of data from a peer.

    `float`, `None` by default.

  Added in version 3.3.

  Note

  Timeouts of 5 seconds or more are rounded for scheduling on the next second boundary (an absolute time where microseconds part is zero) for the sake of performance.

  E.g., assume a timeout is `10`, absolute time when timeout should expire is `loop.time() + 5`, and it points to `12345.67 + 10` which is equal to `12355.67`.

  The absolute time for the timeout cancellation is `12356`.

  It leads to grouping all close scheduled timeout expirations to exactly the same time to reduce amount of loop wakeups.

  Changed in version 3.7: Rounding to the next seconds boundary is disabled for timeouts smaller than 5 seconds for the sake of easy debugging.

  In turn, tiny timeouts can lead to significant performance degradation on production environment.

class aiohttp.ETag(name, is_weak=False)

  Represents ETag identifier.

  value

    Value of corresponding etag without quotes.

  is_weak

    Flag indicates that etag is weak (has W/ prefix).

  Added in version 3.8.

class aiohttp.ContentDisposition

  A data class to represent the Content-Disposition header, available as `ClientResponse.content_disposition` attribute.

  type

  A `str` instance. Value of Content-Disposition header itself, e.g. `attachment`.

  filename

  A `str` instance. Content filename extracted from parameters. May be `None`.

  parameters

  Read-only mapping contains all parameters.

class aiohttp.RequestInfo

  A data class with request URL and headers from `ClientRequest` object, available as `ClientResponse.request_info` attribute.

  url

    Requested url, `yarl.URL` instance.

  method

    Request HTTP method like `'GET'` or `'POST'`, `str`.

  headers

    HTTP headers for request, `multidict.CIMultiDict` instance.

  real_url

    Requested url with URL fragment unstripped, `yarl.URL` instance.

    Added in version 3.2.

class aiohttp.BasicAuth(login, password='', encoding='latin1')

  HTTP basic authentication helper.

  Parameters:

    - login (str) – login

    - password (str) – password

    - encoding (str) – encoding (`'latin1'` by default)

  Should be used for specifying authorization data in client API, e.g. auth parameter for `ClientSession.request()`.

  classmethod decode(auth_header, encoding='latin1')

    Decode HTTP basic authentication credentials.

    Parameters:

      - auth_header (str) – The `Authorization` header to decode.

      - encoding (str) – (optional) encoding (‘latin1’ by default)

    Returns:

      decoded authentication data, `BasicAuth`.

  classmethod from_url(url)

    Constructed credentials info from url’s user and password parts.

    Returns:

      credentials data, `BasicAuth` or `None` is credentials are not provided.

    Added in version 2.3.

  encode()

    Encode credentials into string suitable for `Authorization` header etc.

    Returns:

      encoded authentication data, `str`.

class aiohttp.CookieJar(*, unsafe=False, quote_cookie=True, treat_as_secure_origin=[])

  The cookie jar instance is available as `ClientSession.cookie_jar`.

  The jar contains `Morsel` items for storing internal cookie data.

  API provides a count of saved cookies:

      len(session.cookie_jar)

  These cookies may be iterated over:

      for cookie in session.cookie_jar:
          print(cookie.key)
          print(cookie["domain"])

  The class implements `collections.abc.Iterable`, `collections.abc.Sized` and `aiohttp.abc.AbstractCookieJar` interfaces.

  Implements cookie storage adhering to RFC 6265.

  Parameters:

    - unsafe (bool) – (optional) Whether to accept cookies from IPs.

    - quote_cookie (bool) –

      (optional) Whether to quote cookies according to

        RFC 2109. Some backend systems (not compatible with RFC mentioned above) does not support quoted cookies.

      Added in version 3.7.

    - treat_as_secure_origin –

      (optional) Mark origins as secure

        for cookies marked as Secured. Possible types are

        Possible types are:

        - `tuple` or `list` of `str` or `yarl.URL`

        - `str`

        - `yarl.URL`

      Added in version 3.8.

  update_cookies(cookies, response_url=None)

    Update cookies returned by server in `Set-Cookie` header.

    Parameters:

      - cookies – a `collections.abc.Mapping` (e.g. `dict`, `SimpleCookie`) or iterable of pairs with cookies returned by server’s response.

      - response_url (URL) – URL of response, `None` for shared cookies. Regular cookies are coupled with server’s URL and are sent only to this server, shared ones are sent in every client request.

  filter_cookies(request_url)

    Return jar’s cookies acceptable for URL and available in `Cookie` header for sending client requests for given URL.

    Parameters:

      response_url (URL) – request’s URL for which cookies are asked.

    Returns:

      `http.cookies.SimpleCookie` with filtered cookies for given URL.

  save(file_path)

    Write a pickled representation of cookies into the file at provided path.

    Parameters:

      file_path – Path to file where cookies will be serialized, `str` or `pathlib.Path` instance.

  load(file_path)

    Load a pickled representation of cookies from the file at provided path.

    Parameters:

      file_path – Path to file from where cookies will be imported, `str` or `pathlib.Path` instance.

  clear(predicate=None)

    Removes all cookies from the jar if the predicate is `None`. Otherwise remove only those `Morsel` that `predicate(morsel)` returns `True`.

    Parameters:

      predicate –

      callable that gets `Morsel` as a parameter and returns `True` if this `Morsel` must be deleted from the jar.

      Added in version 4.0.

  clear_domain(domain)

    Remove all cookies from the jar that belongs to the specified domain or its subdomains.

    Parameters:

      domain (str) – domain for which cookies must be deleted from the jar.

    Added in version 4.0.

class aiohttp.DummyCookieJar(*, loop=None)

  Dummy cookie jar which does not store cookies but ignores them.

  Could be useful e.g. for web crawlers to iterate over Internet without blowing up with saved cookies information.

  To install dummy cookie jar pass it into session instance:

      jar = aiohttp.DummyCookieJar()
      session = aiohttp.ClientSession(cookie_jar=DummyCookieJar())

class aiohttp.Fingerprint(digest)

  Fingerprint helper for checking SSL certificates by SHA256 digest.

  Parameters:

    digest (bytes) – SHA256 digest for certificate in DER-encoded binary form (see `ssl.SSLSocket.getpeercert()`).

  To check fingerprint pass the object into `ClientSession.get()` call, e.g.:

      import hashlib

      with open(path_to_cert, 'rb') as f:
          digest = hashlib.sha256(f.read()).digest()

      await session.get(url, ssl=aiohttp.Fingerprint(digest))

  Added in version 3.0.

### FormData

A `FormData` object contains the form data and also handles encoding it into a body that is either `multipart/form-data` or `application/x-www-form-urlencoded`. `multipart/form-data` is used if at least one field is an `io.IOBase` object or was added with at least one optional argument to `add_field` (`content_type`, `filename`, or `content_transfer_encoding`). Otherwise, `application/x-www-form-urlencoded` is used.

`FormData` instances are callable and return a `aiohttp.payload.Payload` on being called.

class aiohttp.FormData(fields, quote_fields=True, charset=None)

  Helper class for multipart/form-data and application/x-www-form-urlencoded body generation.

  Parameters:

    fields –

    A container for the key/value pairs of this form.

    Possible types are:

    - `dict`

    - `tuple` or `list`

    - `io.IOBase`, e.g. a file-like object

    - `multidict.MultiDict` or `multidict.MultiDictProxy`

    If it is a `tuple` or `list`, it must be a valid argument for `add_fields`.

    For `dict`, `multidict.MultiDict`, and `multidict.MultiDictProxy`, the keys and values must be valid name and value arguments to `add_field`, respectively.

  add_field(name, value, content_type=None, filename=None, content_transfer_encoding=None)

    Add a field to the form.

    Parameters:

      - name (str) – Name of the field

      - value –

        Value of the field

        Possible types are:

        - `str`

        - `bytes`, `bytearray`, or `memoryview`

        - `io.IOBase`, e.g. a file-like object

      - content_type (str) – The field’s content-type header (optional)

      - filename (str) –

        The field’s filename (optional)

        If this is not set and `value` is a `bytes`, `bytearray`, or `memoryview` object, the name argument is used as the filename unless `content_transfer_encoding` is specified.

        If `filename` is not set and `value` is an `io.IOBase` object, the filename is extracted from the object if possible.

      - content_transfer_encoding (str) – The field’s content-transfer-encoding header (optional)

  add_fields(fields)

    Add one or more fields to the form.

    Parameters:

      fields –

      An iterable containing:

      - `io.IOBase`, e.g. a file-like object

      - `multidict.MultiDict` or `multidict.MultiDictProxy`

      - `tuple` or `list` of length two, containing a name-value pair

## Client exceptions

Exception hierarchy has been significantly modified in version 2.0. aiohttp defines only exceptions that covers connection handling and server response misbehaviors. For developer specific mistakes, aiohttp uses python standard exceptions like `ValueError` or `TypeError`.

Reading a response content may raise a `ClientPayloadError` exception. This exception indicates errors specific to the payload encoding. Such as invalid compressed data, malformed chunked-encoded chunks or not enough data that satisfy the content-length header.

All exceptions are available as members of aiohttp module.

exception aiohttp.ClientError

  Base class for all client specific exceptions.

  Derived from `Exception`

class aiohttp.ClientPayloadError

  This exception can only be raised while reading the response payload if one of these errors occurs:

  1. invalid compression

  2. malformed chunked encoding

  3. not enough data that satisfy `Content-Length` HTTP header.

  Derived from `ClientError`

exception aiohttp.InvalidURL

  URL used for fetching is malformed, e.g. it does not contain host part.

  Derived from `ClientError` and `ValueError`

  url

    > Invalid URL, `yarl.URL` instance.

    description

      Invalid URL description, `str` instance or `None`.

exception aiohttp.InvalidUrlClientError

  Base class for all errors related to client url.

  Derived from `InvalidURL`

exception aiohttp.RedirectClientError

  Base class for all errors related to client redirects.

  Derived from `ClientError`

exception aiohttp.NonHttpUrlClientError

  Base class for all errors related to non http client urls.

  Derived from `ClientError`

exception aiohttp.InvalidUrlRedirectClientError

  Redirect URL is malformed, e.g. it does not contain host part.

  Derived from `InvalidUrlClientError` and `RedirectClientError`

exception aiohttp.NonHttpUrlRedirectClientError

  Redirect URL does not contain http schema.

  Derived from `RedirectClientError` and `NonHttpUrlClientError`

### Response errors

exception aiohttp.ClientResponseError

  These exceptions could happen after we get response from server.

  Derived from `ClientError`

  request_info

    Instance of `RequestInfo` object, contains information about request.

  status

    HTTP status code of response (`int`), e.g. `400`.

  message

    Message of response (`str`), e.g. `"OK"`.

  headers

    Headers in response, a list of pairs.

  history

    History from failed response, if available, else empty tuple.

    A `tuple` of `ClientResponse` objects used for handle redirection responses.

  code

    HTTP status code of response (`int`), e.g. `400`.

    Deprecated since version 3.1.

class aiohttp.ContentTypeError

  Invalid content type.

  Derived from `ClientResponseError`

  Added in version 2.3.

class aiohttp.TooManyRedirects

  Client was redirected too many times.

  Maximum number of redirects can be configured by using parameter `max_redirects` in `request`.

  Derived from `ClientResponseError`

  Added in version 3.2.

class aiohttp.WSServerHandshakeError

  Web socket server response error.

  Derived from `ClientResponseError`

### Connection errors

class aiohttp.ClientConnectionError

  These exceptions related to low-level connection problems.

  Derived from `ClientError`

class aiohttp.ClientConnectionResetError

  Derived from `ClientConnectionError` and `ConnectionResetError`

class aiohttp.ClientOSError

  Subset of connection errors that are initiated by an `OSError` exception.

  Derived from `ClientConnectionError` and `OSError`

class aiohttp.ClientConnectorError

  Connector related exceptions.

  Derived from `ClientOSError`

class aiohttp.ClientConnectorDNSError

  DNS resolution error.

  Derived from `ClientConnectorError`

class aiohttp.ClientProxyConnectionError

  Derived from `ClientConnectorError`

class aiohttp.ClientSSLError

  Derived from `ClientConnectorError`

class aiohttp.ClientConnectorSSLError

  Response ssl error.

  Derived from `ClientSSLError` and `ssl.SSLError`

class aiohttp.ClientConnectorCertificateError

  Response certificate error.

  Derived from `ClientSSLError` and `ssl.CertificateError`

class aiohttp.UnixClientConnectorError

  Derived from `ClientConnectorError`

class aiohttp.ServerConnectionError

  Derived from `ClientConnectionError`

class aiohttp.ServerDisconnectedError

  Server disconnected.

  Derived from `ServerConnectionError`

  message

    Partially parsed HTTP message (optional).

class aiohttp.ServerFingerprintMismatch

  Server fingerprint mismatch.

  Derived from `ServerConnectionError`

class aiohttp.ServerTimeoutError

  Server operation timeout: read timeout, etc.

  To catch all timeouts, including the `total` timeout, use `asyncio.TimeoutError`.

  Derived from `ServerConnectionError` and `asyncio.TimeoutError`

class aiohttp.ConnectionTimeoutError

  Connection timeout on `connect` and `sock_connect` timeouts.

  Derived from `ServerTimeoutError`

class aiohttp.SocketTimeoutError

  Reading from socket timeout on `sock_read` timeout.

  Derived from `ServerTimeoutError`

### Hierarchy of exceptions

- `ClientError`

  - `ClientConnectionError`

    - `ClientConnectionResetError`

    - `ClientOSError`

      - `ClientConnectorError`

        - `ClientProxyConnectionError`

        - `ClientConnectorDNSError`

        - `ClientSSLError`

          - `ClientConnectorCertificateError`

          - `ClientConnectorSSLError`

        - `UnixClientConnectorError`

    - `ServerConnectionError`

      - `ServerDisconnectedError`

      - `ServerFingerprintMismatch`

      - `ServerTimeoutError`

        - `ConnectionTimeoutError`

        - `SocketTimeoutError`

  - `ClientPayloadError`

  - `ClientResponseError`

    - `ClientHttpProxyError`

    - `ContentTypeError`

    - `TooManyRedirects`

    - `WSServerHandshakeError`

  - `InvalidURL`

    - `InvalidUrlClientError`

      - `InvalidUrlRedirectClientError`

  - `NonHttpUrlClientError`

    - `NonHttpUrlRedirectClientError`

  - `RedirectClientError`

    - `InvalidUrlRedirectClientError`

    - `NonHttpUrlRedirectClientError`