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
orprint
instead ofainput
andaprint
will push a message immediately to the console, potentially conflicting withainput
oraprint
. - Using
ainput
oraprint
instead oflock.ainput
andlock.aprint
may produce deadlock due to having to wait for the lock to release. As such, thelock
is equipped with a defaulttimeout
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
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 05dd34e3e234e52e5a2e98648e78f26df9f9c914c3072bf4c43e6daebd844859 |
|
MD5 | 219f9f9660cfbe028b1369122b864e83 |
|
BLAKE2b-256 | abf786efb81abda2ce58b1164c04a43eccabfa27910871f59cca9fc9d210ec53 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | ceda42cd5be4777d99dded369cc5698d4b8bbae484102b7e57685294a93f805a |
|
MD5 | 5ddfa28dc07764a0a5ff43cc5d1a34c8 |
|
BLAKE2b-256 | 16d052501da33d9f5f692d499e3d33a2aef34db4223e33d8877a6438a232cb83 |