aiofiles: 为asyncio提供文件支持

aiofiles是一个Apache2许可的库，用Python编写，用于在asyncio应用程序中处理本地磁盘文件。

普通的本地文件IO是阻塞的，不能很容易且便携地实现异步。这意味着文件IO可能会干扰asyncio应用程序，而应用程序不应该阻塞执行线程。aiofiles通过引入支持将操作委托给单独线程池的文件异步版本来解决这个问题。

async with aiofiles.open('filename', mode='r') as f:
    contents = await f.read()
print(contents)
'My file contents'

还支持异步迭代。

async with aiofiles.open('filename') as f:
    async for line in f:
        ...

为tempfile模块提供异步接口。

async with aiofiles.tempfile.TemporaryFile('wb') as f:
    await f.write(b'Hello, World!')

特性

• 与Python标准、阻塞API非常相似的文件API
• 支持缓冲和非缓冲的二进制文件以及缓冲的文本文件
• 支持async/await（PEP 492）构造
• 为tempfile模块提供异步接口

安装

要安装aiofiles，请

$ pip install aiofiles

使用方法

文件使用aiofiles.open()协程打开，该协程除了镜像内置的open，还接受可选的loop和executor参数。如果loop不存在，将使用默认循环，如异步策略所设置。如果没有指定executor，将使用默认的事件循环执行器。

在成功的情况下，返回一个异步文件对象，其API与普通文件相同，以下方法除外是协程并委托给执行器

• close
• flush
• isatty
• read
• readall
• read1
• readinto
• readline
• readlines
• seek
• seekable
• tell
• truncate
• writable
• write
• writelines

失败的情况下，将抛出常见的异常之一。

aiofiles.stdin、aiofiles.stdout、aiofiles.stderr、aiofiles.stdin_bytes、aiofiles.stdout_bytes 和 aiofiles.stderr_bytes 提供了对 sys.stdin、sys.stdout、sys.stderr 及其相应 .buffer 属性的异步访问。

aiofiles.os 模块包含处理文件的几个有用 os 函数的执行器启用协程版本。

• stat
• statvfs
• sendfile
• rename
• renames
• replace
• remove
• unlink
• mkdir
• makedirs
• rmdir
• removedirs
• link
• symlink
• readlink
• listdir
• scandir
• access
• getcwd
• path.abspath
• path.exists
• path.isfile
• path.isdir
• path.islink
• path.ismount
• path.getsize
• path.getatime
• path.getctime
• path.samefile
• path.sameopenfile

Tempfile

aiofiles.tempfile 实现以下接口

• TemporaryFile
• NamedTemporaryFile
• SpooledTemporaryFile
• TemporaryDirectory

结果通过上下文管理器返回，允许使用 async with 和 async for。

async with aiofiles.tempfile.NamedTemporaryFile('wb+') as f:
    await f.write(b'Line1\n Line2')
    await f.seek(0)
    async for line in f:
        print(line)

async with aiofiles.tempfile.TemporaryDirectory() as d:
    filename = os.path.join(d, "file.ext")

为 aiofiles 编写测试

可以通过修补 aiofiles.threadpool.sync_open 来模拟实际的文件 IO。返回类型还需要在 aiofiles.threadpool.wrap 分发器中注册。

aiofiles.threadpool.wrap.register(mock.MagicMock)(
    lambda *args, **kwargs: aiofiles.threadpool.AsyncBufferedIOBase(*args, **kwargs)
)

async def test_stuff():
    write_data = 'data'
    read_file_chunks = [
        b'file chunks 1',
        b'file chunks 2',
        b'file chunks 3',
        b'',
    ]
    file_chunks_iter = iter(read_file_chunks)

    mock_file_stream = mock.MagicMock(
        read=lambda *args, **kwargs: next(file_chunks_iter)
    )

    with mock.patch('aiofiles.threadpool.sync_open', return_value=mock_file_stream) as mock_open:
        async with aiofiles.open('filename', 'w') as f:
            await f.write(write_data)
            assert f.read() == b'file chunks 1'

        mock_file_stream.write.assert_called_once_with(write_data)

历史记录

24.1.0 (2024-06-24)

• 条件导入 os.link 以修复 android 上的导入问题。#175
• 当在 Windows 上运行时，从 aiofiles.os.__all__ 中删除多余的条目。
• 切换到更现代的异步约定：删除 types.coroutine 并将 AiofilesContextManager 转换为可等待的，而不是协程。
• 添加了 aiofiles.os.path.abspath 和 aiofiles.os.getcwd。#174
• aiofiles 现在也在 Python 3.13 上进行了测试。#184
• 已删除 Python 3.7 支持。如果您需要它，请使用版本 23.2.1。

23.2.1 (2023-08-09)

• 条件导入 os.statvfs 以修复非 UNIX 系统上的导入问题。#171 #172
• aiofiles 现在也在 Windows 上进行了测试。

23.2.0 (2023-08-09)

• aiofiles 现在也在 Python 3.12 上进行了测试。#166 #168
• 在 Python 3.12 中，aiofiles.tempfile.NamedTemporaryFile 现在接受一个 delete_on_close 参数，就像 stdlib 版本一样。
• 在 Python 3.12 中，aiofiles.tempfile.NamedTemporaryFile 不再公开一个 delete 属性，就像 stdlib 版本一样。
• 添加了 aiofiles.os.statvfs 和 aiofiles.os.path.ismount。#162
• 使用 PDM 而不是 Poetry。#169

23.1.0 (2023-02-09)

• 添加了 aiofiles.os.access。#146
• 删除了 aiofiles.tempfile.temptypes.AsyncSpooledTemporaryFile.softspace。#151
• 添加了 aiofiles.stdin、aiofiles.stdin_bytes 和其他 stdio 流。#154
• 在内部过渡到 asyncio.get_running_loop（而不是 asyncio.get_event_loop）。

22.1.0 (2022-09-04)

• 添加了 aiofiles.os.path.islink。#126
• 添加了 aiofiles.os.readlink。#125
• 添加了 aiofiles.os.symlink。#124
• 添加了 aiofiles.os.unlink。#123
• 增加了 aiofiles.os.link。 #121
• 增加了 aiofiles.os.renames。 #120
• 增加了 aiofiles.os.{listdir, scandir}。 #143
• 切换到 CalVer。
• 停止支持 Python 3.6。如需使用，请使用版本 0.8.0。
• aiofiles 现已测试在 Python 3.11 上。

0.8.0 (2021-11-27)

• aiofiles 现已测试在 Python 3.10 上。
• 增加了 aiofiles.os.replace。 #107
• 增加了 aiofiles.os.{makedirs, removedirs}。
• 增加了 aiofiles.os.path.{exists, isfile, isdir, getsize, getatime, getctime, samefile, sameopenfile}。 #63
• 为 aiofiles.tempfile.TemporaryDirectory 增加了 suffix、prefix 和 dir 参数。 #116

0.7.0 (2021-05-17)

• 增加了用于异步临时文件的 aiofiles.tempfile 模块。 #56
• 切换到 Poetry 和 GitHub actions。
• 停止支持 3.5。

0.6.0 (2020-10-27)

• aiofiles 现已测试在 ppc64le 上。
• 为异步文件对象增加了 name 和 mode 属性。 #82
• 内部修复了 DeprecationWarning。 #75
• 支持 Python 3.9 和测试。

0.5.0 (2020-04-12)

• 支持 Python 3.8。代码库现代化（使用 async/await 代替 asyncio.coroutine/yield from）。
• 增加了 aiofiles.os.remove、aiofiles.os.rename、aiofiles.os.mkdir 和 aiofiles.os.rmdir。 #62

0.4.0 (2018-08-11)

• 支持 Python 3.7。
• 移除 Python 3.3/3.4 支持。如果您使用这些版本，请坚持使用 aiofiles 0.3.x。

0.3.2 (2017-09-23)

• 现在将 LICENSE 包含在 sdist 中。 #31

0.3.1 (2017-03-10)

• 引入了变更日志。
• 如果标准 os 模块包含 sendfile 函数，则 aiofiles.os.sendfile 现在将正常工作。

贡献

欢迎贡献。可以使用 tox 运行测试，请在提交拉取请求之前确保覆盖率至少保持不变。