datafiles

2.5 verified Fri May 01 auth: no python

A file-based ORM for Python dataclasses that stores objects in YAML, JSON, or TOML files. Current version: 2.5. Release cadence: irregular, latest in 2023.

pip install datafiles

Common errors

error ModuleNotFoundError: No module named 'datafiles' ↓

cause The library is not installed.

fix

Run pip install datafiles.

error ModuleNotFoundError: No module named 'yaml' ↓

cause PyYAML is required for YAML files and not installed.

fix

Run pip install datafiles[yaml] or pip install PyYAML.

error AttributeError: 'Person' object has no attribute '_datafile_' ↓

cause The class was not decorated with @datafile.

fix

Add @datafile(...) decorator to the dataclass.

error TypeError: datafile() missing 1 required positional argument: 'pattern' ↓

cause The @datafile decorator requires a file pattern argument.

fix

Use @datafile('path/to/file.{self.attr}.yml').

Warnings

breaking In version 2.0, the storage directory structure changed. Files are now saved by default under the 'data' subdirectory relative to the working directory, not the module's directory. ↓

fix Update file patterns to use explicit paths or migrate existing data.

deprecated Support for TOML format requires the `toml` library, which is not installed by default. Install with `pip install datafiles[toml]`. ↓

fix Specify the extra dependency.

gotcha File patterns can be ambiguous. If multiple objects map to the same file, they will overwrite each other. Use unique patterns per class. ↓

fix Include unique identifiers in the pattern, e.g., '{self.name}'.

gotcha Changing a field name after data has been stored will break deserialization because the file format uses field names as keys. ↓

fix Add migration logic or manually update stored files.

Imports

datafiles
wrong
```
from datafiles import datafile
```
correct
```
import datafiles
```
datafiles uses decorators, not direct import of a class named datafile.
datafile
wrong
```
import datafile
```
correct
```
from datafiles import datafile
```
The decorator is in the datafiles package.

Quickstart

Define a dataclass decorated with @datafile to map its instances to a YAML file.

from dataclasses import dataclass
from datafiles import datafile

@datafile("data/{self.name}.yml")
class Person:
    name: str
    age: int = 0

p = Person("Alice")
p.age = 30
print(p.age)  # 30