diff --git a/docs/client.rst b/docs/client.rst index 0c57de57472..78fbeae4ded 100644 --- a/docs/client.rst +++ b/docs/client.rst @@ -10,6 +10,7 @@ The page contains all information about aiohttp Client API: .. toctree:: :name: client + :maxdepth: 3 Quickstart Advanced Usage diff --git a/docs/client_reference.rst b/docs/client_reference.rst index 5956ac0bb97..05c39b540bb 100644 --- a/docs/client_reference.rst +++ b/docs/client_reference.rst @@ -941,9 +941,6 @@ By default all *connectors* support *keep-alive connections* (behavior is controlled by *force_close* constructor's parameter). -BaseConnector -^^^^^^^^^^^^^ - .. class:: BaseConnector(*, keepalive_timeout=15, \ force_close=False, limit=100, limit_per_host=0, \ enable_cleanup_closed=False, loop=None) @@ -1033,11 +1030,6 @@ BaseConnector overridden in subclasses. - - -TCPConnector -^^^^^^^^^^^^ - .. class:: TCPConnector(*, ssl=None, verify_ssl=True, fingerprint=None, \ use_dns_cache=True, ttl_dns_cache=10, \ family=0, ssl_context=None, local_addr=None, \ @@ -1173,9 +1165,6 @@ TCPConnector clear all cache otherwise. -UnixConnector -^^^^^^^^^^^^^ - .. class:: UnixConnector(path, *, conn_timeout=None, \ keepalive_timeout=30, limit=100, \ force_close=False, loop=None) @@ -1208,9 +1197,6 @@ UnixConnector Path to *UNIX socket*, read-only :class:`str` property. -Connection -^^^^^^^^^^ - .. class:: Connection Encapsulates single connection in connector object. @@ -1696,9 +1682,6 @@ Utilities --------- -ClientTimeout -^^^^^^^^^^^^^ - .. class:: ClientTimeout(*, total=None, connect=None, \ sock_connect=None, sock_read=None) @@ -1764,9 +1747,6 @@ ClientTimeout on production environment. -ETag -^^^^ - .. class:: ETag(name, is_weak=False) Represents `ETag` identifier. @@ -1781,8 +1761,6 @@ ETag .. versionadded:: 3.8 -RequestInfo -^^^^^^^^^^^ .. class:: RequestInfo() @@ -1808,9 +1786,6 @@ RequestInfo .. versionadded:: 3.2 -BasicAuth -^^^^^^^^^ - .. class:: BasicAuth(login, password='', encoding='latin1') HTTP basic authentication helper. @@ -1851,9 +1826,6 @@ BasicAuth :return: encoded authentication data, :class:`str`. -CookieJar -^^^^^^^^^ - .. class:: CookieJar(*, unsafe=False, quote_cookie=True, treat_as_secure_origin = []) The cookie jar instance is available as :attr:`ClientSession.cookie_jar`. diff --git a/docs/tracing_reference.rst b/docs/tracing_reference.rst index a89dadd7103..cf7264d8955 100644 --- a/docs/tracing_reference.rst +++ b/docs/tracing_reference.rst @@ -121,9 +121,8 @@ DNS resolving } -TraceConfig ------------ - +Classes +------- .. class:: TraceConfig(trace_config_ctx_factory=SimpleNamespace) @@ -278,8 +277,6 @@ TraceConfig .. versionadded:: 3.8 -TraceRequestStartParams ------------------------ .. class:: TraceRequestStartParams @@ -298,9 +295,6 @@ TraceRequestStartParams Headers that will be used for the request, can be mutated. -TraceRequestChunkSentParams ---------------------------- - .. class:: TraceRequestChunkSentParams .. versionadded:: 3.1 @@ -320,9 +314,6 @@ TraceRequestChunkSentParams Bytes of chunk sent -TraceResponseChunkReceivedParams --------------------------------- - .. class:: TraceResponseChunkReceivedParams .. versionadded:: 3.1 @@ -342,9 +333,6 @@ TraceResponseChunkReceivedParams Bytes of chunk received -TraceRequestEndParams ---------------------- - .. class:: TraceRequestEndParams See :attr:`TraceConfig.on_request_end` for details. @@ -366,9 +354,6 @@ TraceRequestEndParams Response :class:`ClientResponse`. -TraceRequestExceptionParams ---------------------------- - .. class:: TraceRequestExceptionParams See :attr:`TraceConfig.on_request_exception` for details. @@ -389,8 +374,6 @@ TraceRequestExceptionParams Exception raised during the request. -TraceRequestRedirectParams --------------------------- .. class:: TraceRequestRedirectParams @@ -412,8 +395,6 @@ TraceRequestRedirectParams Response :class:`ClientResponse` got from the redirect. -TraceConnectionQueuedStartParams --------------------------------- .. class:: TraceConnectionQueuedStartParams @@ -421,8 +402,6 @@ TraceConnectionQueuedStartParams There are no attributes right now. -TraceConnectionQueuedEndParams ------------------------------- .. class:: TraceConnectionQueuedEndParams @@ -430,8 +409,6 @@ TraceConnectionQueuedEndParams There are no attributes right now. -TraceConnectionCreateStartParams --------------------------------- .. class:: TraceConnectionCreateStartParams @@ -439,8 +416,6 @@ TraceConnectionCreateStartParams There are no attributes right now. -TraceConnectionCreateEndParams ------------------------------- .. class:: TraceConnectionCreateEndParams @@ -448,8 +423,6 @@ TraceConnectionCreateEndParams There are no attributes right now. -TraceConnectionReuseconnParams ------------------------------- .. class:: TraceConnectionReuseconnParams @@ -457,8 +430,6 @@ TraceConnectionReuseconnParams There are no attributes right now. -TraceDnsResolveHostStartParams ------------------------------- .. class:: TraceDnsResolveHostStartParams @@ -468,8 +439,6 @@ TraceDnsResolveHostStartParams Host that will be resolved. -TraceDnsResolveHostEndParams ----------------------------- .. class:: TraceDnsResolveHostEndParams @@ -479,8 +448,6 @@ TraceDnsResolveHostEndParams Host that has been resolved. -TraceDnsCacheHitParams ----------------------- .. class:: TraceDnsCacheHitParams @@ -490,8 +457,6 @@ TraceDnsCacheHitParams Host found in the cache. -TraceDnsCacheMissParams ------------------------ .. class:: TraceDnsCacheMissParams @@ -501,8 +466,6 @@ TraceDnsCacheMissParams Host didn't find the cache. -TraceRequestHeadersSentParams ------------------------------ .. class:: TraceRequestHeadersSentParams diff --git a/docs/utilities.rst b/docs/utilities.rst index 35e02a0d964..a82fbd8cea1 100644 --- a/docs/utilities.rst +++ b/docs/utilities.rst @@ -9,6 +9,7 @@ Miscellaneous API Shared between Client And Server. .. toctree:: :name: utilities + :maxdepth: 2 abc multipart diff --git a/docs/web.rst b/docs/web.rst index 6ec00026664..f21182d0424 100644 --- a/docs/web.rst +++ b/docs/web.rst @@ -10,6 +10,7 @@ The page contains all information about aiohttp Server API: .. toctree:: :name: server + :maxdepth: 3 Tutorial Quickstart diff --git a/docs/web_reference.rst b/docs/web_reference.rst index ab13c785285..6af022c7f84 100644 --- a/docs/web_reference.rst +++ b/docs/web_reference.rst @@ -588,8 +588,6 @@ and :ref:`aiohttp-web-signals` handlers:: Dict-like interface support. -StreamResponse -^^^^^^^^^^^^^^ .. class:: StreamResponse(*, status=200, reason=None) @@ -865,9 +863,6 @@ StreamResponse object are forbidden. -Response -^^^^^^^^ - .. class:: Response(*, body=None, status=200, reason=None, text=None, \ headers=None, content_type=None, charset=None, \ zlib_executor_size=sentinel, zlib_executor=None) @@ -921,9 +916,6 @@ Response :attr:`~aiohttp.StreamResponse.body`, represented as :class:`str`. -FileResponse -^^^^^^^^^^^^^^ - .. class:: FileResponse(*, path, chunk_size=256*1024, status=200, reason=None, headers=None) The response class used to send files, inherited from :class:`StreamResponse`. @@ -948,8 +940,6 @@ FileResponse response's ones. The ``Content-Type`` response header will be overridden if provided. -WebSocketResponse -^^^^^^^^^^^^^^^^^ .. class:: WebSocketResponse(*, timeout=10.0, receive_timeout=None, \ autoclose=True, autoping=True, heartbeat=None, \ @@ -1267,9 +1257,6 @@ WebSocketResponse .. seealso:: :ref:`WebSockets handling` -WebSocketReady -^^^^^^^^^^^^^^ - .. class:: WebSocketReady A named tuple for returning result from @@ -1293,9 +1280,6 @@ WebSocketReady .. seealso:: :meth:`WebSocketResponse.can_prepare` -json_response -^^^^^^^^^^^^^ - .. function:: json_response([data], *, text=None, body=None, \ status=200, reason=None, headers=None, \ content_type='application/json', \ @@ -1312,37 +1296,34 @@ Application and Router ---------------------- -Application -^^^^^^^^^^^ - -Application is a synonym for web-server. +.. class:: Application(*, logger=, middlewares=(), \ + handler_args=None, client_max_size=1024**2, \ + debug=...) -To get a fully working example, you have to make *application*, register -supported urls in *router* and pass it to :func:`aiohttp.web.run_app` -or :class:`aiohttp.web.AppRunner`. + Application is a synonym for web-server. -*Application* contains a *router* instance and a list of callbacks that -will be called during application finishing. + To get a fully working example, you have to make an *application*, register + supported urls in the *router* and pass it to :func:`aiohttp.web.run_app` + or :class:`aiohttp.web.AppRunner`. -:class:`Application` is a :obj:`dict`-like object, so you can use it for -:ref:`sharing data` globally by storing arbitrary -properties for later access from a :ref:`handler` via the -:attr:`Request.app` property:: + *Application* contains a *router* instance and a list of callbacks that + will be called during application finishing. - app = Application() - database = AppKey("database", AsyncEngine) - app[database] = await create_async_engine(db_url) + This class is a :obj:`dict`-like object, so you can use it for + :ref:`sharing data` globally by storing arbitrary + properties for later access from a :ref:`handler` via the + :attr:`Request.app` property:: - async def handler(request): - async with request.app[database].begin() as conn: - await conn.execute("DELETE * FROM table") + app = Application() + database = AppKey("database", AsyncEngine) + app[database] = await create_async_engine(db_url) -Although :class:`Application` is a :obj:`dict`-like object, it can't be -duplicated like one using :meth:`~aiohttp.web.Application.copy`. + async def handler(request): + async with request.app[database].begin() as conn: + await conn.execute("DELETE * FROM table") -.. class:: Application(*, logger=, middlewares=(), \ - handler_args=None, client_max_size=1024**2, \ - debug=...) + Although it` is a :obj:`dict`-like object, it can't be duplicated like one + using :meth:`~aiohttp.web.Application.copy`. The class inherits :class:`dict`. @@ -1561,16 +1542,12 @@ duplicated like one using :meth:`~aiohttp.web.Application.copy`. router for your application). -AppKey -^^^^^^ - -:class:`AppKey` should be used for the keys in :class:`Application`. They -provide type safety when checking your code with a type checker (e.g. mypy). - .. class:: AppKey(name, t) - The class provides a type-safe alternative to `str` keys. They also avoid - name clashes with keys from different libraries etc. + This class should be used for the keys in :class:`Application`. They + provide a type-safe alternative to `str` keys when checking your code + with a type checker (e.g. mypy). They also avoid name clashes with keys + from different libraries etc. :param name: A name to help with debugging. This should be the same as the variable name (much like how :class:`typing.TypeVar` @@ -1579,15 +1556,11 @@ provide type safety when checking your code with a type checker (e.g. mypy). :param t: The type that should be used for the value in the dict (e.g. `str`, `Iterator[int]` etc.) - -Server -^^^^^^ - -A protocol factory compatible with -:meth:`~asyncio.AbstractEventLoop.create_server`. - .. class:: Server + A protocol factory compatible with + :meth:`~asyncio.AbstractEventLoop.create_server`. + The class is responsible for creating HTTP protocol objects that can handle HTTP connections. @@ -1606,35 +1579,30 @@ A protocol factory compatible with connections. -Router -^^^^^^ - -For dispatching URLs to :ref:`handlers` -:mod:`aiohttp.web` uses *routers*. - -Router is any object that implements :class:`~aiohttp.abc.AbstractRouter` interface. - -:mod:`aiohttp.web` provides an implementation called :class:`UrlDispatcher`. - -:class:`Application` uses :class:`UrlDispatcher` as :meth:`~aiohttp.web.Application.router` by default. - .. class:: UrlDispatcher() - Straightforward url-matching router, implements + For dispatching URLs to :ref:`handlers` + :mod:`aiohttp.web` uses *routers*, which is any object that implements + :class:`~aiohttp.abc.AbstractRouter` interface. + + This class is a straightforward url-matching router, implementing :class:`collections.abc.Mapping` for access to *named routes*. - Before running :class:`Application` you should fill *route + :class:`Application` uses this class as + :meth:`~aiohttp.web.Application.router` by default. + + Before running an :class:`Application` you should fill *route table* first by calling :meth:`add_route` and :meth:`add_static`. :ref:`Handler` lookup is performed by iterating on added *routes* in FIFO order. The first matching *route* will be used - to call corresponding *handler*. + to call the corresponding *handler*. - If on route creation you specify *name* parameter the result is + If during route creation you specify *name* parameter the result is a *named route*. - *Named route* can be retrieved by ``app.router[name]`` call, checked for - existence by ``name in app.router`` etc. + A *named route* can be retrieved by a ``app.router[name]`` call, checking for + existence can be done with ``name in app.router`` etc. .. seealso:: :ref:`Route classes ` @@ -2984,9 +2952,6 @@ Constants Middlewares ----------- -Normalize path middleware -^^^^^^^^^^^^^^^^^^^^^^^^^ - .. function:: normalize_path_middleware(*, \ append_slash=True, \ remove_slash=False, \