> built 2026-09-22 14:15 UTC from d11723b (master) · aiofiledol 0.0.8. Details: build_info.json

# index.html.md

<!-- generated by epythet -->

# aiofiledol

aiofile (async filesys operations) with a simple (dict-like or list-like) interface

To install:	`pip install aiofiledol`

Get the bytes contents of the file k.

```python
>>> import os
>>> from aiofiledol import AioFileBytesReader
>>> filepath = __file__
>>> dirpath = os.path.dirname(__file__)  # path of the directory where I (the module file) am
>>> s = AioFileBytesReader(dirpath, max_levels=0)
>>>
>>> ####### Get the first 9 characters (as bytes) of this module #####################
>>> t = await s.aget(filepath)
>>> t[:14]
b'import asyncio'
>>>
>>> ####### Test key validation #####################
>>> await s.aget('not_a_valid_key')  # this key is not valid since not under the dirpath folder
Traceback (most recent call last):
    ...
filesys.KeyValidationError: 'Key not valid (usually because does not exist or access not permitted): not_a_valid_key'
>>>
>>> ####### Test further exceptions (that should be wrapped in KeyError) #####################
>>> # this key is valid, since under dirpath, but the file itself doesn't exist (hopefully for this test)
>>> non_existing_file = os.path.join(dirpath, 'non_existing_file')
>>> try:
...     await s.aget(non_existing_file)
... except KeyError:
...     print("KeyError (not FileNotFoundError) was raised.")
KeyError (not FileNotFoundError) was raised.
```

Set the contents of file `k` to be some bytes.

```python
>>> from aiofiledol import AioFileBytesPersister
>>> from dol.filesys import mk_tmp_dol_dir
>>> import os
>>>
>>> rootdir = mk_tmp_dol_dir('test')
>>> rpath = lambda *p: os.path.join(rootdir, *p)
>>> s = AioFileBytesPersister(rootdir)
>>> k = rpath('foo')
>>> if k in s:
...     del s[k]  # delete key if present
...
>>> n = len(s)  # number of items in store
>>> await s.asetitem(k, b'bar')
>>> assert len(s) == n + 1  # there's one more item in store
>>> assert k in s
>>> assert (await s[k]) == b'bar'
```

<p class="epythet-aggregates">This documentation as a single file: <a href="aiofiledol.md">aiofiledol.md</a> (Markdown, for agents).</p>


# _autosummary/aiofiledol.html.md

# aiofiledol

aiofile (async filesys operations) with a simple (dict-like or list-like) interface

### Classes

| [`AioFileBytesPersister`](_autosummary/aiofiledol.html.md#aiofiledol.AioFileBytesPersister)(\*args[, delete_func])     | Async file persister with configurable deletion.   |
|---------------------------------------------------------------------------------------------------|----------------------------------------------------|
| [`AioFileBytesReader`](_autosummary/aiofiledol.html.md#aiofiledol.AioFileBytesReader)(rootdir[, subpath, ...])      |                                                    |
| [`AioFileStringPersister`](_autosummary/aiofiledol.html.md#aiofiledol.AioFileStringPersister)(\*args[, delete_func])    |                                                    |
| [`AioFileStringReader`](_autosummary/aiofiledol.html.md#aiofiledol.AioFileStringReader)(rootdir[, subpath, ...])     |                                                    |
| [`RelPathAioFileBytesReader`](_autosummary/aiofiledol.html.md#aiofiledol.RelPathAioFileBytesReader)(rootdir[, ...])        |                                                    |
| [`RelPathFileStringReader`](_autosummary/aiofiledol.html.md#aiofiledol.RelPathFileStringReader)(rootdir[, subpath, ...]) |                                                    |

### *class* aiofiledol.AioFileBytesPersister(\*args, delete_func=None, \*\*kwargs)

Bases: `LocalFileDeleteMixin`, [`AioFileBytesReader`](_autosummary/aiofiledol.html.md#aiofiledol.AioFileBytesReader), `KvPersister`

Async file persister with configurable deletion.

### Examples

```pycon
>>> from dol.filesys import mk_tmp_dol_dir
>>> rootdir = mk_tmp_dol_dir('aiofiledol_test')
>>> # Default: safe trash with warning on fallback
>>> store = AioFileBytesPersister(rootdir)
>>> # Permanent deletion without warnings
>>> from dol.trash import permanent_delete
>>> store = AioFileBytesPersister(rootdir, delete_func=permanent_delete)
```

#### asetitem(k, v)

Write bytes `v` to the file at key `k` (async).

```pycon
>>> import asyncio, os
>>> from dol.filesys import mk_tmp_dol_dir
>>> rootdir = mk_tmp_dol_dir('aiofiledol_test')
>>> rpath = lambda *p: os.path.join(rootdir, *p)
>>> s = AioFileBytesPersister(rootdir)
>>> k = rpath('foo')
>>> if k in s:
...     del s[k]  # delete key if present
>>> n = len(s)  # number of items in store
>>> asyncio.run(s.asetitem(k, b'bar'))
>>> len(s) == n + 1  # there's one more item in store
True
>>> k in s
True
>>> asyncio.run(s.aget(k))  # read it back (async reader; __getitem__ is disabled)
b'bar'
```

### *class* aiofiledol.AioFileBytesReader(rootdir, subpath='', pattern_for_field=None, max_levels=None, , include_hidden=False, assert_rootdir_existence=False)

Bases: `FileCollection`, `KvReader`

#### *async* aget(k)

Get the bytes contents of the file `k`.

Async examples are driven with `asyncio.run` so they run under a
plain `--doctest-modules` collection (top-level `await` is a
syntax error in doctests).

```pycon
>>> import asyncio, os
>>> from dol.filesys import mk_tmp_dol_dir
>>> rootdir = mk_tmp_dol_dir('aiofiledol_test')
>>> filepath = os.path.join(rootdir, 'greeting')
>>> with open(filepath, 'wb') as fp:
...     _ = fp.write(b'hello world')
>>> s = AioFileBytesReader(rootdir, max_levels=0)
>>> asyncio.run(s.aget(filepath))
b'hello world'
```

### *class* aiofiledol.AioFileStringPersister(\*args, delete_func=None, \*\*kwargs)

Bases: [`AioFileBytesPersister`](_autosummary/aiofiledol.html.md#aiofiledol.AioFileBytesPersister)

### *class* aiofiledol.AioFileStringReader(rootdir, subpath='', pattern_for_field=None, max_levels=None, , include_hidden=False, assert_rootdir_existence=False)

Bases: [`AioFileBytesReader`](_autosummary/aiofiledol.html.md#aiofiledol.AioFileBytesReader)

### *class* aiofiledol.RelPathAioFileBytesReader(rootdir, subpath='', pattern_for_field=None, max_levels=None, , include_hidden=False, assert_rootdir_existence=False)

Bases: `PrefixRelativizationMixin`, `Store`

#### is_valid_key(k, \*args, \_\_name='is_valid_key', \*\*kwargs)

`is_valid_key` on the inner key – see `mk_relative_path_store`.

#### validate_key(k, \*args, \_\_name='validate_key', \*\*kwargs)

`validate_key` on the inner key – see `mk_relative_path_store`.

### *class* aiofiledol.RelPathFileStringReader(rootdir, subpath='', pattern_for_field=None, max_levels=None, , include_hidden=False, assert_rootdir_existence=False)

Bases: `PrefixRelativizationMixin`, `Store`

#### is_valid_key(k, \*args, \_\_name='is_valid_key', \*\*kwargs)

`is_valid_key` on the inner key – see `mk_relative_path_store`.

#### validate_key(k, \*args, \_\_name='validate_key', \*\*kwargs)

`validate_key` on the inner key – see `mk_relative_path_store`.


# about-this-build.html.md

<!-- generated by epythet -->

# About this build

This documentation was built on **2026-09-22 14:15 UTC** from commit <a href="https://github.com/i2mint/aiofiledol/commit/d11723bfedc36ba983f426ca07559b93d4bd0c97"><code>d11723b</code></a> on branch <code>master</code>, for **aiofiledol 0.0.8** (from <code>pyproject.toml</code>).

#### NOTE
Nothing suggests a mismatch: the tree was clean at the commit above, and the documented version is the one on PyPI.

## Source

|                     |                                                                                                                                                          |
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| Commit              | <a href="https://github.com/i2mint/aiofiledol/commit/d11723bfedc36ba983f426ca07559b93d4bd0c97"><code>d11723bfedc36ba983f426ca07559b93d4bd0c97</code></a> |
| Branch              | <code>master</code>                                                                                                                                      |
| Tags at this commit | none                                                                                                                                                     |
| Working tree        | clean                                                                                                                                                    |
| Remote              | <code>https://github.com/i2mint/aiofiledol</code>                                                                                                        |

## Continuous integration

|              |                                                                                            |
|--------------|--------------------------------------------------------------------------------------------|
| Repository   | <code>i2mint/aiofiledol</code>                                                             |
| Run          | <a href="https://github.com/i2mint/aiofiledol/actions/runs/35738847715">35738847715</a>    |
| Ref          | <code>refs/heads/master</code>                                                             |
| Event commit | <code>d11723bfedc36ba983f426ca07559b93d4bd0c97</code> (in the history of the built commit) |

## Tools

|          |         |
|----------|---------|
| epythet  | 0.2.12  |
| Sphinx   | 9.1.0   |
| docutils | 0.22.4  |
| Python   | 3.12.14 |

## Configuration as resolved

|               |                                                                   |
|---------------|-------------------------------------------------------------------|
| theme         | <code>auto</code> (Sphinx theme <code>sphinxawesome_theme</code>) |
| accent        | <code>#00668a</code>                                              |
| api_generator | <code>autosummary</code>                                          |
| ignore        | <code>tests/</code>, <code>scrap/</code>, <code>examples/</code>  |
| agent_outputs | <code>true</code>                                                 |
| aggregates    | <code>md</code>                                                   |
| ai_artifacts  | <code>true</code>                                                 |

## Package on PyPI

Latest release: <a href="https://pypi.org/project/aiofiledol/0.0.8/">0.0.8</a>, the same as the documented version.

## Reproduce

```bash
git clone https://github.com/i2mint/aiofiledol && cd aiofiledol
git checkout d11723bfedc36ba983f426ca07559b93d4bd0c97
pip install "epythet==0.2.12"
epythet quickstart . --ignore tests/ scrap/ examples/
```

The same data, for machines: <a href="build_info.json"><code>build_info.json</code></a> (schema version 1).


# api.html.md

# API reference

| [`aiofiledol`](_autosummary/aiofiledol.html.md#module-aiofiledol)   | aiofile (async filesys operations) with a simple (dict-like or list-like) interface   |
|---------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|