README.md

async-files

async-files is a fast, lightweight, and extensible asyncio file library, written in pure python and inspired by aiofiles. This works just like aiofiles which delegates file IO operations to a separate thread pool. Although, async-files have been completely re-written from scratch to use modern async...await... syntax and with extensibility and flexibility in mind.

Usage

Files can be opened with async context manager or by calling FileIO instance.

async with FileIO("README.md") as f:
    s = await f.read()
    print(s)

or

f = await FileIO("README.md")()  # __init__ can't be asynchronous.
s = await f.read()
print(s)
await f.close()

Asynchronous iteration is also supported.

async with FileIO("README.md") as f:
    async for line in f:
        print(line, end="")

You can also extend functionality of FileIO to support other classes like tempfile.TemporaryFile very easily:

from tempfile import TemporaryFile as _TemporaryFile
from async_files import FileIO

class TemporaryFile(FileIO):
    OPEN = _TemporaryFile

You can do same for any other IO classes like gzip.GzipFile, zipfile.ZipFile, etc. I have added async version of tempfile and gzip modules in the v0.2 since they are commonly used modules and I will add more modules in the future releases. You can use these modules just like you use standard library module, only difference is you need to await coroutine methods. You can request for support for new modules by creating new issue.

You can also create coroutine from any blocking function by using async-files's utility function async_wraps. For example:

import shutil
from async_files.utils import async_wraps
async_rmtree = async_wraps(shutil.rmtree)

You can also use async_wraps as a decorator for your custom function.

Note: Only use async_wraps if target function is IO-bound.

Following are asynchronous attributes of the FileIO object.

close: Callable[[], Awaitable[None]]
flush: Callable[[], Awaitable[None]]
isatty: Callable[[], Awaitable[bool]]
read: Callable[[], Awaitable[Union[str, bytes]]]
read1: Callable[[], Awaitable[bytes]]
readinto: Callable[[bytearray], Awaitable[int]]
readinto1: Callable[[bytearray], Awaitable[int]]
readline: Callable[[], Awaitable[Union[str, bytes]]]
readlines: Callable[[], Awaitable[List[Union[str, bytes]]]]
seek: Callable[[], Awaitable[int]]
tell: Callable[[], Awaitable[int]]
truncate: Callable[[], Awaitable[int]]
write: Callable[[Union[str, bytes]], Awaitable[int]]
writelines: Callable[[List[Union[str, bytes]]], Awaitable[None]]

Other attributes are synchronous just like standard library fileobj.

Feedback & Contributions

Bugs and feature requests can be made via GitHub issues. Be aware that these issues are not private, so take care when providing output to make sure you are not disclosing security issues in other products.

Pull requests are also welcome via git.

The async-files uses sourcery, restyled and code factor bots to ensure code quality of the PR.