aiohttp-0.11.0.tar.gz

.. _aiohttp-web: .. highlight:: python High-level HTTP Server ====================== .. module:: aiohttp.web .. versionadded:: 0.10 Run a simple web server ----------------------- For implementing a web server, first create a :ref:`request handler<aiohttp-web-handler>`. Handler is a :ref:`coroutine<coroutine>` or a regular function that accepts only *request* parameter of type :class:`Request` and returns :class:`Response` instance:: import asyncio from aiohttp import web @asyncio.coroutine def hello(request): return web.Response(request, b"Hello, world") Next, you have to create a :class:`Application` instance and register :ref:`handler<aiohttp-web-handler>` in the application's router pointing *HTTP method*, *path* and *handler*:: app = web.Application() app.router.add_route('GET', '/', hello) After that, create a server and run the *asyncio loop* as usual:: loop = asyncio.get_event_loop() f = loop.create_server(app.make_handler, '0.0.0.0', 8080) srv = loop.run_until_complete(f) print('serving on', srv.sockets[0].getsockname()) try: loop.run_forever() except KeyboardInterrupt: pass That's it. .. _aiohttp-web-handler: Handler ------- Handler is an any *callable* that accepts a single :class:`Request` argument and returns a :class:`StreamResponse` derived (e.g. :class:`Response`) instance. Handler **can** be a :ref:`coroutine<coroutine>`, :mod:`aiohttp.web` will **unyield** returned result by applying ``yield from`` to the handler. Handlers are connected to the :class:`Application` via routes:: handler = Handler() app.router.add_route('GET', '/', handler) .. _aiohttp-web-variable-handler: You can also use *variable routes*. If route contains string like ``'/a/{name}/c'`` that means the route matches to the path like ``'/a/b/c'`` or ``'/a/1/c'``. Parsed *path part* will be available in the *request handler* as ``request.match_info['name']``:: @asyncio.coroutine def variable_handler(request): return web.Response( request, "Hello, {}".format(request.match_info['name']).encode('utf8')) app.router.add_route('GET', '/{name}', variable_handler) Handlers can be first-class functions, e.g.:: @asyncio.coroutine def hello(request): return web.Response(request, b"Hello, world") app.router.add_route('GET', '/', hello) Sometimes you would like to group logically coupled handlers into a python class. :mod:`aiohttp.web` doesn't dictate any implementation details, so application developer can use classes if he wants:: class Handler: def __init__(self): pass def handle_intro(self, request): return web.Response(request, b"Hello, world") @asyncio.coroutine def handle_greeting(self, request): name = request.match_info.get('name') txt = "Hello, {}".format(name) return web.Response(request, txt.encode('utf-8') handler = Handler() app.router.add_route('GET', '/intro', handler.handle_intro) app.router.add_route('GET', '/greet/{name}', handler.handle_greeting) .. _aiohttp-web-file-upload: File Uploads ------------ There are two steps necessary for handling file uploads. The first is to make sure that you have a form that has been setup correctly to accept files. This means adding enctype attribute to your form element with the value of *multipart/form-data*. A very simple example would be a form that accepts a mp3 file. Notice, we have set up the form as previously explained and also added the *input* element of the *file* type:: <form action="/store_mp3" method="post" accept-charset="utf-8" enctype="multipart/form-data"> <label for="mp3">Mp3</label> <input id="mp3" name="mp3" type="file" value="" /> <input type="submit" value="submit" /> </form> The second step is handling the file upload in your :ref:`request handler<aiohttp-web-handler>` (here assumed to answer on */store_mp3*). The uploaded file is added to the request object as a :class:`FileField` object accessible through the :meth:`Request.POST` coroutine. The two properties we are interested in are *file* and *filename* and we will use those to read a file's name and a content:: import os import uuid from aiohttp.web import Response def store_mp3_view(request): data = yield from request.POST() # ``filename`` contains the name of the file in string format. filename = data['mp3'].filename # ``input_file`` contains the actual file data which needs to be # stored somewhere. input_file = data['mp3'].file content = input_file.read() return Response(request, content, headers=MultiDict([('CONTENT-DISPOSITION', input-file)]) .. _aiohttp-web-request: Request ------- The Request object contains all the information about an incoming HTTP request. Every :ref:`handler<aiohttp-web-handler>` accepts a request instance as the first positional parameter. .. note:: You should never create the :class:`Request` instance manually -- :mod:`aiohttp.web` does it for you. .. class:: Request .. attribute:: method *HTTP method*, Read-only property. The value is upper-cased :class:`str` like ``"GET"``, ``"POST"``, ``"PUT"`` etc. .. attribute:: version *HTTP version* of request, Read-only property. Returns :class:`aiohttp.protocol.HttpVersion` instance. .. attribute:: host *HOST* header of request, Read-only property. Returns :class:`str` or ``None`` if HTTP request has no *HOST* header. .. attribute:: path_qs The URL including PATH_INFO and the query string. e.g, ``/app/blog?id=10`` Read-only :class:`str` property. .. attribute:: path The URL including *PATH INFO* without the host or scheme. e.g., ``/app/blog`` Read-only :class:`str` property. .. attribute:: query_string The query string in the URL, e.g., ``id=10`` Read-only :class:`str` property. .. attribute:: GET A multidict with all the variables in the query string. Read-only :class:`~aiohttp.multidict.MultiDict` lazy property. .. attribute:: headers A case-insensitive multidict with all headers. Read-only :class:`~aiohttp.multidict.CaseInsensitiveMultiDict` lazy property. .. attribute:: keep_alive ``True`` if keep-alive connection enabled by HTTP client and protocol version supports it, otherwise ``False``. Read-only :class:`bool` property. .. attribute:: match_info Read-only property with :class:`~aiohttp.abc.AbstractMatchInfo` instance for result of route resolving. .. note:: Exact type of property depends on used router. If ``app.router`` is :class:`UrlDispatcher` the property contains :class:`UrlMappingMatchInfo` instance. .. attribute:: app An :class:`Application` instance used to call :ref:`request handler <aiohttp-web-handler>`, Read-only property. .. attribute:: transport An :ref:`transport<asyncio-transport>` used to process request, Read-only property. The property can be used, for example, for getting IP address of client's peer:: peername = request.transport.get_extra('peername') if peername is not None: host, port = peername .. attribute:: cookies A multidict of all request's cookies. Read-only :class:`~aiohttp.multidict.MultiDict` lazy property. .. attribute:: payload A :class:`~aiohttp.streams.FlowControlStreamReader` instance, input stream for reading request's *BODY*. Read-only property. .. attribute:: content_type Read-only property with *content* part of *Content-Type* header. Returns :class:`str` like ``'text/html'`` .. note:: Returns value is ``'application/octet-stream'`` if no