Skip to main content

The purpose of this package is to provide asynchronous variants of the builtin `input` and `print` functions.

Project description

aio_stdout

Asynchronous Input Output - Stdout

The purpose of this package is to provide asynchronous variants of the builtin input and print functions. print is known to be relatively slow compared to other operations. input is even slower because it has to wait for user input. While these slow IO operations are being ran, code using asyncio should be able to continuously run.

PIP Installing

For Unix/macOS:

python3 -m pip install aio-stdout

For Windows:

py -m pip install aio-stdout

ainput and aprint

With aio_stdout, the aio_stdout.ainput and aio_stdout.aprint functions provide easy to use functionality with organized behaviour.

import asyncio
from aio_stdout import ainput, aprint

async def countdown(n: int) -> None:
    """Count down from `n`, taking `n` seconds to run."""
    for i in range(n, 0, -1):
        await aprint(i)
        await asyncio.sleep(1)

async def get_name() -> str:
    """Ask the user for their name."""
    name = await ainput("What is your name? ")
    await aprint(f"Your name is {name}.")
    return name

async def main() -> None:
    await asyncio.gather(countdown(15), get_name())

if __name__ == "__main__":
    asyncio.run(main())

Example output:

15
What is your name? Jane
14
13
12
11
10
9
8
Your name is Jane.
7
6
5
4
3
2
1

Notice that while the prompt "What is your name? " is being waited for, the countdown continues to aprint in the background, without becoming blocked. The countdown does not, however, display its results until the ainput is completed. Instead it waits for the ainput to finish before flushing out all of the queued messages.

It is worth noting that with naive threading, a normal attempt to use print while waiting on an input leads to overlapping messages. Fixing this behavior requires a lot more work than should be needed to use a simple print or input function, which is why this package exists. To remedy this problem, queues are used to store messages until they are ready to be printed.

IO Locks

Although the asynchronization behaviors of ainput and aprint are nice, sometimes we want to be able to synchronize our messages even more. IO locks provide a way to group messages together, locking the global aio_stdout queues until it finishes or yields access.

import asyncio
from aio_stdout import IOLock, ainput, aprint

async def countdown(n: int) -> None:
    """Count down from `n`, taking `n` seconds to run."""
    async with IOLock(n=5) as lock:
        for i in range(n, 0, -1):
            await lock.aprint(i)
            await asyncio.sleep(1)

async def get_name() -> str:
    """Ask the user for their name."""
    async with IOLock() as lock:
        name = await lock.ainput("What is your name? ")
        await lock.aprint(f"Your name is {name}.")
    return name

async def main() -> None:
    await asyncio.gather(countdown(15), get_name())

if __name__ == "__main__":
    asyncio.run(main())

Let's try the example again now using the new locks:

15
14
13
12
11
What is your name? Jane
Your name is Jane.
10
9
8
7
6
5
4
3
2
1

Notice that this time the countdown does not immediately yield to the get_name. Instead, it runs 5 messages before yielding control over to get_name. Now, after the lock.ainput finishes, it does not yield to countdown. Instead, it runs its own lock.aprint first. In the meantime, countdown continues to run in the background and flushes all of its buffered messages afterwards.

Flushing

Since messages may be delayed, it is possible for your asynchronous code to finish running before all messages are displayed, producing confusing results. As such, the best recommended practice is to flush from main before terminating.

from aio_stdout import flush

@flush
async def main() -> None:
    ...

Final Example

Combining all best practices, the final example should look something like this:

import asyncio
from aio_stdout import IOLock, ainput, aprint, flush

async def countdown(n: int) -> None:
    """Count down from `n`, taking `n` seconds to run."""
    for i in range(n, 0, -1):
        await aprint(i)
        await asyncio.sleep(1)

async def get_name() -> str:
    """Ask the user for their name."""
    async with IOLock() as lock:
        name = await lock.ainput("What is your name? ")
        await lock.aprint(f"Your name is {name}.")
    return name

@flush
async def main() -> None:
    await asyncio.gather(countdown(15), get_name())

if __name__ == "__main__":
    asyncio.run(main())

Common Gotchas

  • Using input or print instead of ainput and aprint will push a message immediately to the console, potentially conflicting with ainput or aprint.
  • Using ainput or aprint instead of lock.ainput and lock.aprint may produce deadlock due to having to wait for the lock to release. As such, the lock is equipped with a default timeout limit of 10 seconds to avoid deadlock and explain to users this potential problem.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aio-stdout-0.0.5.tar.gz (11.0 kB view details)

Uploaded Source

Built Distribution

aio_stdout-0.0.5-py3-none-any.whl (13.0 kB view details)

Uploaded Python 3

File details

Details for the file aio-stdout-0.0.5.tar.gz.

File metadata

  • Download URL: aio-stdout-0.0.5.tar.gz
  • Upload date:
  • Size: 11.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.7.1 importlib_metadata/4.10.1 pkginfo/1.8.2 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.5

File hashes

Hashes for aio-stdout-0.0.5.tar.gz
Algorithm Hash digest
SHA256 05dd34e3e234e52e5a2e98648e78f26df9f9c914c3072bf4c43e6daebd844859
MD5 219f9f9660cfbe028b1369122b864e83
BLAKE2b-256 abf786efb81abda2ce58b1164c04a43eccabfa27910871f59cca9fc9d210ec53

See more details on using hashes here.

File details

Details for the file aio_stdout-0.0.5-py3-none-any.whl.

File metadata

  • Download URL: aio_stdout-0.0.5-py3-none-any.whl
  • Upload date:
  • Size: 13.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.7.1 importlib_metadata/4.10.1 pkginfo/1.8.2 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.5

File hashes

Hashes for aio_stdout-0.0.5-py3-none-any.whl
Algorithm Hash digest
SHA256 ceda42cd5be4777d99dded369cc5698d4b8bbae484102b7e57685294a93f805a
MD5 5ddfa28dc07764a0a5ff43cc5d1a34c8
BLAKE2b-256 16d052501da33d9f5f692d499e3d33a2aef34db4223e33d8877a6438a232cb83

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page