Added info about RequestKey & ResponseKey to docs

Author: gsoldatov

docs/faq.rst

@@ -87,8 +87,15 @@ support the :class:`dict` interface.
 
 Therefore, data may be stored inside a request object. ::
 
-   async def handler(request):
-       request['unique_key'] = data
+    request_id_key = web.RequestKey("request_id_key", str)
+
+    @web.middleware
+    async def request_id_middleware(request, handler):
+        request[request_id_key] = "some_request_id"
+        return await handler(request)
+
+    async def handler(request):
+        request_id = request[request_id_key]
 
 See https://github.com/aio-libs/aiohttp_session code for an example.
 The ``aiohttp_session.get_session(request)`` method uses ``SESSION_KEY``

docs/web_advanced.rst

@@ -446,10 +446,13 @@ Request's storage
 ^^^^^^^^^^^^^^^^^
 
 Variables that are only needed for the lifetime of a :class:`Request`, can be
-stored in a :class:`Request`::
+stored in a :class:`Request`. Similarly to :class:`Application`, :class:`RequestKey`
+instances or strings can be used as keys::
+
+    my_private_key = web.RequestKey("my_private_key", str)
 
     async def handler(request):
-      request['my_private_key'] = "data"
+      request[my_private_key] = "data"
       ...
 
 This is mostly useful for :ref:`aiohttp-web-middlewares` and
@@ -464,9 +467,11 @@ also support :class:`collections.abc.MutableMapping` interface. This is useful
 when you want to share data with signals and middlewares once all the work in
 the handler is done::
 
+    my_metric_key = web.ResponseKey("my_metric_key", int)
+
     async def handler(request):
       [ do all the work ]
-      response['my_metric'] = 123
+      response[my_metric_key] = 123
       return response
 
 
@@ -722,18 +727,20 @@ In contrast, when accessing the stream directly (not recommended in middleware):
 
 When working with raw stream data that needs to be shared between middleware and handlers::
 
+    raw_body_key = web.RequestKey("raw_body_key", bytes)
+
     async def stream_parsing_middleware(
         request: web.Request,
         handler: Callable[[web.Request], Awaitable[web.StreamResponse]]
     ) -> web.StreamResponse:
         # Read stream once and store the data
         raw_data = await request.content.read()
-        request['raw_body'] = raw_data
+        request[raw_body_key] = raw_data
         return await handler(request)
 
     async def handler(request: web.Request) -> web.Response:
         # Access the stored data instead of reading the stream again
-        raw_data = request.get('raw_body', b'')
+        raw_data = request.get(raw_body_key, b'')
         return web.Response(body=raw_data)
 
 Example

docs/web_reference.rst

@@ -534,6 +534,21 @@ and :ref:`aiohttp-web-signals` handlers.
       request copy with changed *path*, *method* etc.
 
 
+.. class:: RequestKey(name, t)
+
+   This class should be used for the keys in :class:`Request` and
+   :class:`BaseRequest`. 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`
+                is used).
+
+   :param t: The type that should be used for the value in the dict (e.g.
+             `str`, `Iterator[int]` etc.)
+
+
 
 
 .. _aiohttp-web-response:
@@ -1357,6 +1372,23 @@ content type and *data* encoded by ``dumps`` parameter
 (:func:`json.dumps` by default).
 
 
+.. class:: ResponseKey(name, t)
+
+   This class should be used for the keys in :class:`Response`,
+   :class:`FileResponse` and :class:`StreamResponse`. They provide
+   a type-safe alternative to `str` keys when checking your code
+   with a type checker (e.g. mypy). They also avoid name clasheswith 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`
+                is used).
+
+   :param t: The type that should be used for the value in the dict (e.g.
+             `str`, `Iterator[int]` etc.)
+
+
+
+
 .. _aiohttp-web-app-and-router:
 
 Application and Router
@@ -1631,6 +1663,7 @@ Application and Router
    :param t: The type that should be used for the value in the dict (e.g.
              `str`, `Iterator[int]` etc.)
 
+
 .. class:: Server
 
    A protocol factory compatible with