{"id":23064,"library":"datafiles","title":"datafiles","description":"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.","status":"active","version":"2.5","language":"python","source_language":"en","source_url":"https://github.com/jacebrowning/datafiles","tags":["orm","dataclass","yaml","json","toml","serialization"],"install":[{"cmd":"pip install datafiles","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required for YAML file support.","package":"PyYAML","optional":false},{"reason":"Required for TOML file support.","package":"toml","optional":true}],"imports":[{"note":"datafiles uses decorators, not direct import of a class named datafile.","wrong":"from datafiles import datafile","symbol":"datafiles","correct":"import datafiles"},{"note":"The decorator is in the datafiles package.","wrong":"import datafile","symbol":"datafile","correct":"from datafiles import datafile"}],"quickstart":{"code":"from dataclasses import dataclass\nfrom datafiles import datafile\n\n@datafile(\"data/{self.name}.yml\")\nclass Person:\n    name: str\n    age: int = 0\n\np = Person(\"Alice\")\np.age = 30\nprint(p.age)  # 30\n","lang":"python","description":"Define a dataclass decorated with @datafile to map its instances to a YAML file."},"warnings":[{"fix":"Update file patterns to use explicit paths or migrate existing data.","message":"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.","severity":"breaking","affected_versions":">=2.0"},{"fix":"Specify the extra dependency.","message":"Support for TOML format requires the `toml` library, which is not installed by default. Install with `pip install datafiles[toml]`.","severity":"deprecated","affected_versions":">=2.0"},{"fix":"Include unique identifiers in the pattern, e.g., '{self.name}'.","message":"File patterns can be ambiguous. If multiple objects map to the same file, they will overwrite each other. Use unique patterns per class.","severity":"gotcha","affected_versions":"all"},{"fix":"Add migration logic or manually update stored files.","message":"Changing a field name after data has been stored will break deserialization because the file format uses field names as keys.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `pip install datafiles`.","cause":"The library is not installed.","error":"ModuleNotFoundError: No module named 'datafiles'"},{"fix":"Run `pip install datafiles[yaml]` or `pip install PyYAML`.","cause":"PyYAML is required for YAML files and not installed.","error":"ModuleNotFoundError: No module named 'yaml'"},{"fix":"Add `@datafile(...)` decorator to the dataclass.","cause":"The class was not decorated with @datafile.","error":"AttributeError: 'Person' object has no attribute '_datafile_'"},{"fix":"Use `@datafile('path/to/file.{self.attr}.yml')`.","cause":"The @datafile decorator requires a file pattern argument.","error":"TypeError: datafile() missing 1 required positional argument: 'pattern'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}