Reflow web example for two-stage routing, document upstr

Author: asvetlov

docs/multidict.rst

@@ -335,3 +335,45 @@ CIMultiDictProxy
    Raises :exc:`TypeError` is *multidict* is not :class:`CIMultiDict` instance.
 
    The class is inherited from :class:`MultiDict`.
+
+
+upstr
+-----
+
+:class:`CIMultiDict` accepts :class:`str` as *key* argument for dict
+lookups but converts it to upper case internally.
+
+For more effective processing it shoult to know if *key* is already upper cased.
+
+To skip :meth:`~str.upper()` call you may create upper cased string by
+hands, e.g::
+
+   >>> key = upstr('Key')
+   >>> key
+   'KEY'
+   >>> mdict = CIMultiDict(key='value')
+   >>> key in mdict
+   True
+   >>> mdict[key]
+   'value'
+
+For performance you should create :class:`upstr` strings once and
+store it globally, like :mod:`aiohttp.hdrs` does.
+
+.. class:: upstr(object='')
+           upstr(bytes_or_buffer[, encoding[, errors]])
+
+      Create a new **upper cased** string object from the given
+      *object*. If *encoding* or *errors* is specified, then the
+      object must expose a data buffer that will be decoded using the
+      given encoding and error handler.
+
+      Otherwise, returns the result of ``object.__str__()`` (if defined)
+      or ``repr(object)``.
+
+      *encoding* defaults to ``sys.getdefaultencoding()``.
+
+      *errors* defaults to ``'strict'``.
+
+      The class is inherited from :class:`str` and has all regular
+      string methods.

docs/web.rst

@@ -137,19 +137,22 @@ While :class:`UrlDispatcher` doesn't accept extra criterias there is
 easy way to do the task by implementing the second routing layer by
 hands.
 
-The example shows custom processing based on *HTTP Accept* header::
+The example shows custom processing based on *HTTP Accept* header:
 
-   class Handler:
+.. code-block:: python
+
+   class AcceptChooser:
 
        def __init__(self):
            self._accepts = {}
 
        @asyncio.coroutine
        def do_route(self, request):
-           acceptor = self._accepts.get(request.headers.get('ACCEPT'))
-           if acceptor is None:
-               raise HTTPNotAcceptable()
-           return (yield from acceptor(request))
+           for accept in request.headers.getall('ACCEPT', []):
+                acceptor = self._accepts.get(accept):
+                if acceptor is not None:
+                    return (yield from acceptor(request))
+           raise HTTPNotAcceptable()
 
        def reg_acceptor(self, accept, handler):
            self._accepts[accept] = handler
@@ -163,10 +166,11 @@ The example shows custom processing based on *HTTP Accept* header::
    def handle_xml(request):
        # do xml handling
 
-   handler = Handler()
-   app.router.add_route('GET', '/', handler.do_route)
-   handler.reg_acceptor('application/json', handle_json)
-   handler.reg_acceptor('application/xml', handle_xml)
+   chooser = AcceptChooser()
+   app.router.add_route('GET', '/', chooser.do_route)
+
+   chooser.reg_acceptor('application/json', handle_json)
+   chooser.reg_acceptor('application/xml', handle_xml)