Skip to content

index.rst

Latest commit

 

History

History
231 lines (147 loc) · 5.38 KB

index.rst

File metadata and controls

231 lines (147 loc) · 5.38 KB

Welcome to AIOHTTP

Asynchronous HTTP Client/Server for :term:`asyncio` and Python.

Current version is |release|.

Key Features

Library Installation

$ pip install aiohttp

For speeding up DNS resolving by client API you may install :term:`aiodns` as well. This option is highly recommended:

$ pip install aiodns

Installing all speedups in one command

The following will get you aiohttp along with :term:`aiodns` and Brotli in one bundle. No need to type separate commands anymore!

$ pip install aiohttp[speedups]

Getting Started

Client example

import aiohttp
import asyncio

async def main():

    async with aiohttp.ClientSession() as session:
        async with session.get('http://python.org') as response:

            print("Status:", response.status)
            print("Content-type:", response.headers['content-type'])

            html = await response.text()
            print("Body:", html[:15], "...")

asyncio.run(main())

This prints:

Status: 200
Content-type: text/html; charset=utf-8
Body: <!doctype html> ...

Coming from :term:`requests` ? Read :ref:`why we need so many lines <aiohttp-request-lifecycle>`.

Server example:

from aiohttp import web

async def handle(request):
    name = request.match_info.get('name', "Anonymous")
    text = "Hello, " + name
    return web.Response(text=text)

app = web.Application()
app.add_routes([web.get('/', handle),
                web.get('/{name}', handle)])

if __name__ == '__main__':
    web.run_app(app)

For more information please visit :ref:`aiohttp-client` and :ref:`aiohttp-web` pages.

Development mode

When writing your code, we recommend enabling Python's development mode (python -X dev). In addition to the extra features enabled for asyncio, aiohttp will:

  • Use a strict parser in the client code (which can help detect malformed responses from a server).
  • Enable some additional checks (resulting in warnings in certain situations).

What's new in aiohttp 3?

Go to :ref:`aiohttp_whats_new_3_0` page for aiohttp 3.0 major release changes.

Tutorial

:ref:`Polls tutorial <aiohttpdemos:aiohttp-demos-polls-beginning>`

Source code

The project is hosted on GitHub

Please feel free to file an issue on the bug tracker if you have found a bug or have some suggestion in order to improve the library.

Dependencies

Communication channels

aio-libs Discussions: https://github.com/aio-libs/aiohttp/discussions

Feel free to post your questions and ideas here.

Matrix: #aio-libs:matrix.org

We support Stack Overflow. Please add aiohttp tag to your question there.

Contributing

Please read the :ref:`instructions for contributors<aiohttp-contributing>` before making a Pull Request.

Authors and License

The aiohttp package is written mostly by Nikolay Kim and Andrew Svetlov.

It's Apache 2 licensed and freely available.

Feel free to improve this package and send a pull request to GitHub.

Policy for Backward Incompatible Changes

aiohttp keeps backward compatibility.

When a new release is published that deprecates a Public API (method, class, function argument, etc.), the library will guarantee its usage for at least a year and half from the date of release.

Deprecated APIs are reflected in their documentation, and their use will raise :exc:`DeprecationWarning`.

However, if there is a strong reason, we may be forced to break this guarantee. The most likely reason would be a critical bug, such as a security issue, which cannot be solved without a major API change. We are working hard to keep these breaking changes as rare as possible.

Table Of Contents

.. toctree::
   :name: mastertoc
   :maxdepth: 2

   client
   web
   utilities
   faq
   misc
   external
   contributing