Improve client "hello world" in README

[ksamuel]

When looking at aiohttp README, the hello word looks like that:

import aiohttp
import asyncio

async def fetch(session, url):
    async with session.get(url) as response:
        return await response.text()

async def main():
    async with aiohttp.ClientSession() as session:
        html = await fetch(session, 'http://python.org')
        print(html)

if __name__ == '__main__':
    loop = asyncio.get_event_loop()
    loop.run_until_complete(main())

For requests, it looks like this:

>>> r = requests.get('https://api.github.com/user', auth=('user', 'pass'))
>>> r.status_code
200
>>> r.headers['content-type']
'application/json; charset=utf8'
>>> r.encoding
'utf-8'
>>> r.text
u'{"type":"User"...'
>>> r.json
{u'private_gists': 419, u'total_private_repos': 77, ...}

I can see three issues with the way aiohttp present itself:

• The snippet seems to have unnecessary complexity
• The snippet doesn't feature any quick scripting setup
• There is no explanation for the necessary complexity

Expected behaviour

First, extra complexity should be removed. I understand the benefit of if __name__ == "__main__", but in a hello word type of code, it's noise that makes the code seems bigger than necessary. If you have the skill to learn async, you know when to add it later.

Also, can the code go from:

async def fetch(session, url):
    async with session.get(url) as response:
        return await response.text()

async def main():
    async with aiohttp.ClientSession() as session:
        html = await fetch(session, 'http://python.org')
        print(html)

To:

async def main():
    async with aiohttp.ClientSession() as session:
        async with session.get('http://python.org') as response:
            return await response.text()

?

I'm guessing the first form exhibit some kind of best practice I'm missing but:

• since I'm missing it, I have no way to understand why it's best, and won't use it in the future
• it makes the code feels heavy, and hide the expressiveness of aiohttop behind the verbosity of the coroutine system
• the first time you grab for aiohttp, you probably just want to make a quick script out of it, not build a system with best practices

And lastly, even this is weird:

async def main():
    async with aiohttp.ClientSession() as session: # why session ?
        async with session.get('http://python.org') as response: # why can't I do that in one line ?
            return await response.text()

This is necessary complexity. It's done for a reason, but coming from requests, it's strange and seems uncalled for. The README should acknowledge that, then offer a link leading to and explanation of why this is necessary for an async lib, and the consequences of it. It there are shortcuts to that syntax for quick scripts with less performance/best practice needs, the README should mention THAT first, give a quick warning, then follow with the best practice.

aiohttp is the requests of async as for now. It's the first face a newcommer see when discovering the async world nowaday (well, after playing with asyncio.sleep in tutorials).

[asvetlov]

Thanks for raising an interesting question.

Making the best 'hello world' example is very important, sure.

I don't know how to achieve it; please let me add some comments. Consider it as an invite to the discussion, not a strong objection for your proposal.

async def main():
    async with aiohttp.ClientSession() as session: # why session ?
        async with session.get('http://python.org') as response: # why can't I do that in one line ?
            return await response.text()

why session?

How do you want to name it? The client also sounds good. Why is session needed at all? To control resources' lifetime. In sync request's world, everything is released on __del__, mostly implicitly. In asyncio it should be async operation, e.g. await resource.close(). async with provides better and more idiomatic approach than try/finally with await close() in finally block.

The same for async with session.get() as resp: the response object should be closed as well.

Why requests don't use the session concept? It does (see requests.Session class). The problem with implicit sessions is that the connection is recreated every time; it leads to performance lose if people use just resp = requests.get(url) because the lack of HTTP keep-alive.
I saw it very many times.

Splitting the example into 2 functions emphasizes that the session can be created once and reused by many fetches. Unfortunately, it doesn't work well; as I see newbies recreate sessions very often in their code :(

We had top-level get() / post() etc functions like requests have but these functions was designed bad. A backward-compatible fix was impossible, that's why these functions were removed. In aiohttp 4.x we can resurrect these functions with the following usage:

async with aiohttp.get(url) as resp:
    print(await resp.text())

I still not sure if we should do this: any real code should use ClientSession for better controls of resources; shortcut is good for 'hello world' only.
But the shortcut notation is too tempting and short; I expect that people will start using it everywhere without careful thinking.

Should we introduce a way that saves one line with 100% performance lost? I'm not sure.

What do you think?

[ksamuel]

That's the most open minded answer I received in a while :)

For the README part, here what it looks like when you simplify the snippet and add a quick explanation:

Getting Started
===============

Client example::

    import aiohttp
    import asyncio

    async def main():
        async with aiohttp.ClientSession() as session:
            async with session.get(url) as response:
                print(await response.text())

    loop = asyncio.get_event_loop()
    loop.run_until_complete(main())

Coming from requests or urllib ? Check out why your need all this with our explanations on `steps of an asynchronous HTTP request<LINK HERE>`_.

This assumes there is a documentation page named "steps of an asynchronous HTTP request", of course.

Now, about the simple API, it's a more controversial issue. Please consider it independently of my README proposal. Maybe I should open a new ticket ?

My take on it is that Python does a lot of things this way: easy first, most performant possible later if you want.

So I would definitely add some "quick and dirty" shortcut, built on top of the clean aiohttp recommended way. Something like:

def get(*args, **kwargs):
    # PreloadedClientResponse.text() returns self.body.decode(), not an awaitable
    async with aiohttp.ClientSession(response_class=PreloadedClientResponse) as session:
        async with session.get(*args, **kwargs) as response:
            await response.read()
            return response

So that you can do:

response = await aiohttp.get(url) # call .read() internally
print(response.text())

Of course, you need a warning below that with a link to the best practices.

I know it seems dangerous, but let's consider that:

• even inefficient aiohttp is faster than any sync alternative
• in simple scripts this is enough
• people needing the perf will read the doc eventually, and find the article on best practices. Migrating their code to use Session after the fact is not hard, thank to your very good design (love reading the aiohttp source code BTW, it's a pleasure).
• bad practices didn't prevent requests to power most HTTP related Python during the last decades.
• having to write this part of the doc would be nice anyway. When you look at the session object, you wonder when and where to create a session, for how long, when to destroy it, how to pass it around, how it plays out with contextvar, what are the consequences of having several sessions opened at the same time, should the same session be used for different domain names, etc. Having a definitive answer to this is great.

If you choose to go that road, then the README could look like this:

Getting Started
===============

 Simplest client example::

    import aiohttp
    import asyncio

    async def main():
        response = await aiohttp.get(url)  
        print(response.text())

    loop = asyncio.get_event_loop()
    loop.run_until_complete(main()) 

Please note **this syntax is intended for simple scripts only**. To get the best out of an aiohttp client, you should use `proper session management<LINK HERE>`_.

If this is something you are interested in, I'm ok with working on a PR under your guidance.

[asvetlov]

Agree, but I prefer to make aiohttp.get() and family async context manager that closes all resources: both client session and response at the exit from async with block.

Another thing can be the replacement of get_event_loop()/run_until_complete() with asyncio.run(). Python 3.7+ is enough widespread nowdays I guess.

[ksamuel]

Ok, can we get on a chat or phone call this week so we can discuss how you want me to proceed ? Le 27/10/2019 à 22:59, Andrew Svetlov a écrit :

…

Agree, but I prefer to make |aiohttp.get()| and family async context manager that closes all resources: both client session and response at the exit from |async with| block. Another thing can be the replacement of |get_event_loop()|/|run_until_complete()| with |asyncio.run()|. Python 3.7+ is enough widespread nowdays I guess. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#4272?email_source=notifications&email_token=AABWFPVYM2FGZHD63UFGRNDQQX6KPA5CNFSM4JFMPSO2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOECLJGKI#issuecomment-546738985>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABWFPRAQV3NBUBEHSI32ZTQQX6KPANCNFSM4JFMPSOQ>.

[asvetlov]

Let's start from chatting.
Does google talk or gitter work for you?

[ksamuel]

I just created a gitter account for that purpose and pinged you on it. I'm available this morning up to 11am. Same with tomorrow. Let me know when you have a moment.

[webknjaz]

@ksamuel FWIW it's usually important to mention the timezone on the Internet :)

[ksamuel]

Indeed. I realized my mistake a few moments later and sent the timezone, no worry.