README.md

focal

Data Access Objects for local files.

focal re-exports the file-system stores of dol (Files, TextFiles, PickleFiles, ...) and adds multi_extension_wrap, which serializes by file extension.

Examples

The examples below run as doctests (pytest tests/test_readme.py).

a dict-like view of a folder

>>> import os, tempfile
>>> from focal import Files, TextFiles
>>>
>>> rootdir = tempfile.mkdtemp()
>>> store = Files(rootdir)  # keys are relative paths, values are bytes
>>> store['foo'] = b'baz'
>>> 'foo' in store
True
>>> store['foo']
b'baz'
>>> os.listdir(rootdir)  # it is a real file
['foo']
>>> texts = TextFiles(rootdir)  # same folder, values are str
>>> texts['foo']
'baz'
>>> del store['foo']

bytes contents of a file, and key validation

>>> import os, tempfile
>>> from focal import Files
>>>
>>> rootdir = tempfile.mkdtemp()
>>> s = Files(rootdir)
>>> s['hello.txt'] = b'import os'
>>> s['hello.txt'][:6]
b'import'
>>> s['../escape']  # keys outside the root folder are refused
Traceback (most recent call last):
    ...
dol.filesys.KeyValidationError: ...
>>> try:
...     s['no_such_file']
... except KeyError:
...     print("KeyError (not FileNotFoundError) was raised.")
KeyError (not FileNotFoundError) was raised.

serialize by extension

See focal.extension_store.multi_extension_wrap.