Skip to main content

File support for asyncio.

Project description

https://img.shields.io/pypi/v/aiofiles.svg https://travis-ci.org/Tinche/aiofiles.svg?branch=master https://codecov.io/gh/Tinche/aiofiles/branch/master/graph/badge.svg Supported Python versions

aiofiles is an Apache2 licensed library, written in Python, for handling local disk files in asyncio applications.

Ordinary local file IO is blocking, and cannot easily and portably made asynchronous. This means doing file IO may interfere with asyncio applications, which shouldn’t block the executing thread. aiofiles helps with this by introducing asynchronous versions of files that support delegating operations to a separate thread pool.

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

Asynchronous iteration is also supported.

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

Features

  • a file API very similar to Python’s standard, blocking API

  • support for buffered and unbuffered binary files, and buffered text files

  • support for async/await (PEP 492) constructs

Installation

To install aiofiles, simply:

$ pip install aiofiles

Usage

Files are opened using the aiofiles.open() coroutine, which in addition to mirroring the builtin open accepts optional loop and executor arguments. If loop is absent, the default loop will be used, as per the set asyncio policy. If executor is not specified, the default event loop executor will be used.

In case of success, an asynchronous file object is returned with an API identical to an ordinary file, except the following methods are coroutines and delegate to an executor:

  • close

  • flush

  • isatty

  • read

  • readall

  • read1

  • readinto

  • readline

  • readlines

  • seek

  • seekable

  • tell

  • truncate

  • writable

  • write

  • writelines

In case of failure, one of the usual exceptions will be raised.

The aiofiles.os module contains executor-enabled coroutine versions of several useful os functions that deal with files:

  • stat

  • sendfile

  • rename

  • remove

  • mkdir

  • rmdir

Writing tests for aiofiles

Real file IO can be mocked by patching aiofiles.threadpool.sync_open as desired. The return type also needs to be registered with the aiofiles.threadpool.wrap dispatcher:

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

async def test_stuff():
    data = 'data'
    mock_file = mock.MagicMock()

    with mock.patch('aiofiles.threadpool.sync_open', return_value=mock_file) as mock_open:
        async with aiofiles.open('filename', 'w') as f:
            await f.write(data)

        mock_file.write.assert_called_once_with(data)

History

0.5.0 (2020-04-12)

  • Python 3.8 support. Code base modernization (using async/await instead of asyncio.coroutine/yield from).

  • Added aiofiles.os.remove, aiofiles.os.rename, aiofiles.os.mkdir, aiofiles.os.rmdir. #62

0.4.0 (2018-08-11)

  • Python 3.7 support.

  • Removed Python 3.3/3.4 support. If you use these versions, stick to aiofiles 0.3.x.

0.3.2 (2017-09-23)

  • The LICENSE is now included in the sdist. #31

0.3.1 (2017-03-10)

  • Introduced a changelog.

  • aiofiles.os.sendfile will now work if the standard os module contains a sendfile function.

Contributing

Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

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

aiofiles-0.5.0.tar.gz (9.5 kB view details)

Uploaded Source

Built Distribution

aiofiles-0.5.0-py3-none-any.whl (11.1 kB view details)

Uploaded Python 3

File details

Details for the file aiofiles-0.5.0.tar.gz.

File metadata

  • Download URL: aiofiles-0.5.0.tar.gz
  • Upload date:
  • Size: 9.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/35.0.2 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/3.6.1

File hashes

Hashes for aiofiles-0.5.0.tar.gz
Algorithm Hash digest
SHA256 98e6bcfd1b50f97db4980e182ddd509b7cc35909e903a8fe50d8849e02d815af
MD5 2243eff06072115e8afe8907677ca51d
BLAKE2b-256 2b64437053d6a4ba3b3eea1044131a25b458489320cb9609e19ac17261e4dc9b

See more details on using hashes here.

File details

Details for the file aiofiles-0.5.0-py3-none-any.whl.

File metadata

  • Download URL: aiofiles-0.5.0-py3-none-any.whl
  • Upload date:
  • Size: 11.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/35.0.2 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/3.6.1

File hashes

Hashes for aiofiles-0.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 377fdf7815cc611870c59cbd07b68b180841d2a2b79812d8c218be02448c2acb
MD5 2ff1a731a3bd9963a2234e42739b223d
BLAKE2b-256 f42b078a9771ae4b67e36b0c2a973df845260833a4eb088b81c84b738509b4c4

See more details on using hashes here.

Supported by

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