Metadata-Version: 2.5
Name: focal
Version: 0.1.15
Summary: Data Access Objects for local files
Project-URL: Homepage, https://github.com/i2mint/focal
Author: Thor Whalen
License-Expression: MIT
License-File: LICENSE
Keywords: data access,data preparation,file system,orm,storage
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.10
Requires-Dist: dol>=0.3.71
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
Requires-Dist: sphinx>=6.0; extra == 'docs'
Provides-Extra: excel
Requires-Dist: openpyxl; extra == 'excel'
Description-Content-Type: text/markdown

# focal
Data Access Objects for local files.

`focal` re-exports the file-system stores of [`dol`](https://github.com/i2mint/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

```pydocstring
>>> 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

```pydocstring
>>> 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`.
