aiopath 0.2.0

📁 Async pathlib for Python

📁 Async pathlib for Python

aiopath is a complete implementation of pathlib from Python 3.4+ that is compatible with asyncio and the async/await syntax. All I/O performed is asynchronous and awaitable.

aiopath is extensively typed with Python type annotations. aiopath also takes advantage of libaio on Linux.

Usage

aiopath.Path has the same API as pathlib.Path, and aiopath.AsyncPurePath works the same way as pathlib.PurePath. The only difference is that with aiopath, methods that perform I/O are asynchronous and awaitable, and methods that returned iterators now return async generators.

To run the following examples with top-level await expressions, launch an asynchronous Python REPL using python3 -m asyncio.

Basic

All of pathlib.Path's methods that perform synchronous I/O are reimplemented as asynchronous methods.

import tempfile
from pathlib import Path
from aiopath import AsyncPath


with tempfile.NamedTemporaryFile() as temp:
  path = Path(temp.name)
  apath = AsyncPath(temp.name)

  # check existence
  ## sync
  assert path.exists()
  ## async
  assert await apath.exists()

  # check if file
  ## sync
  assert path.is_file()
  ## async
  assert await apath.is_file()

  # touch
  path.touch()
  await apath.touch()

  # read and write text
  text = "example"
  await apath.write_text(text)
  assert text == await apath.read_text()

assert not path.exists()
assert not await apath.exists()

You can convert pathlib.Path objects to aiopath.Path objects easily:

from pathlib import Path
from aiopath import AsyncPath


home: Path = Path.home()
ahome: AsyncPath = AsyncPath(home)

assert isinstance(home, Path)
assert isinstance(ahome, AsyncPath)

Opening a file

You can get an asynchronous file-like object handle by using asynchronous context managers.

import tempfile
from aiopath import AsyncPath


text: str = 'example'

with tempfile.NamedTemporaryFile() as temp:
  apath = AsyncPath(temp.name)

  async with apath.open(mode='w') as afile:
    await afile.write(text)

  result: str = await apath.read_text()
  assert result == text

Globbing

aiopath implements pathlib globbing using async I/O and async generators.

from typing import List
from aiopath import AsyncPath


home: AsyncPath = await AsyncPath.home()

async for path in home.glob('*'):
  assert isinstance(path, AsyncPath)
  print(path)

downloads: AsyncPath = home / 'Downloads'

if await downloads.exists():
  # caution! this might take awhile
  paths: List[AsyncPath] = \
    [path async for path in downloads.glob('**/*')]

Installation

Dependencies

• A POSIX compliant OS, or Windows
• Python 3.7+
• requirements.txt

PyPI

$ python3 -m pip install aiopath

GitHub

$ python3 -m pip install -r requirements.txt
$ python3 setup.py install

Linux

This library will take advantage of libaio, which is compatible with Linux 4.18 and up.

sudo apt install libaio1

Support

Want to support this project and other open-source software like this?

License

See LICENSE. If you'd like to use this project with a different license, please get in touch.

Credit

See CREDIT.md.