Documentation: Reproducing asyncio tests

[vEpiphyte]

Since the docs aren't in git, I can't make a PR to update them.

1. I'd suggest updating the asyncio documentation to include a work example that can be copied and pasted:

$ cat profile_asyncio.py 
import time
import asyncio

def burn_cpu(secs):
    t0 = time.process_time()
    elapsed = 0
    while (elapsed <= secs):
        for _ in range(1000):
            pass
        elapsed = time.process_time() - t0

async def burn_async_io(secs):
    await asyncio.sleep(secs)

def burn_io(secs):
    time.sleep(secs)

async def foo():
    burn_cpu(1.0)
    await burn_async_io(1.0)
    burn_io(1.0)
    await burn_async_io(1.0)

asyncio.run(foo())

2. Include an example of executing yappi against that code. I was a bit confused at first because just running that code produced different numbers due to cpu time vs. wall time.

# Confusing numbers
$ python -m yappi profile_asyncio.py | grep profile_asyncio
profile_asyncio.py:1 <module>         1      0.000047  1.083084  1.083084
profile_asyncio.py:21 foo             1      0.000097  1.000622  1.000622
profile_asyncio.py:5 burn_cpu         1      0.936388  1.000017  1.000017
profile_asyncio.py:13 burn_async_io   2      0.000053  0.000433  0.000216
profile_asyncio.py:17 burn_io         1      0.000020  0.000075  0.000075

# Consistent numbers with the documentation
$ python -m yappi -c wall profile_asyncio.py | grep profile_asyncio
profile_asyncio.py:1 <module>         1      0.000044  4.057246  4.057246
profile_asyncio.py:21 foo             1      0.000095  4.006760  4.006760
profile_asyncio.py:13 burn_async_io   2      0.000038  2.003446  1.001723
profile_asyncio.py:5 burn_cpu         1      0.955977  1.002077  1.002077
profile_asyncio.py:17 burn_io         1      0.000017  1.001142  1.001142

edit: Environment: Ubuntu 18.04, python 3.7.3, yappi 1.2.3

[sumerc]

You are right on that. Let's be more explicit on how we run the examples.

And plus: examples in the current documentation are very poor compared to the current feature set of Yappi, IMHO. I think we should be providing more and more examples explaining every subtle detail like this. Thanks for pointing out.

But I could not understand this part:

Since the docs aren't in git, I can't make a PR to update them.

You might have missed this one? : https://github.com/sumerc/yappi/tree/master/doc

I would be more than happy to accept any kind of PR related to giving examples on these. We can even write a full separate document dedicated only on usage examples.

[vEpiphyte]

Oopps! I totally missed that the docs were inline - for some reason i assumed they were github wiki pages. I can throw a PR up for fixing the asyncio example easily; however i'm uncertain how you generated the displayed blob of results.

[sumerc]

Yeah: they are generated for wall time as you guessed. (yappi -c wall)

[sumerc]

I will be closing this issue since I have included some examples on README.md in a new brach improve-filtering. Updated/Improved most of the docs and examples.