{"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,"search_vec":"'2.5':21 '2023':27 'base':5 'cadenc':23 'current':19 'dataclass':9,29 'datafil':1 'file':4,18 'file-bas':3 'irregular':24 'json':15,31 'latest':25 'object':12 'orm':6,28 'python':8 'releas':22 'serial':33 'store':11 'toml':17,32 'version':20 'yaml':14,30","created_at":"2026-05-01T06:02:13.686609+00:00","updated_at":"2026-05-01T06:02:13.686609+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.5","cli_name":"","cli_version":null,"type":"library","homepage":"https://pypi.org/project/datafiles","github":"https://github.com/jacebrowning/datafiles","docs":"https://datafiles.readthedocs.io","changelog":null,"pypi":"https://pypi.org/project/datafiles/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-29","last_verified":"2026-06-29","next_check":"2026-07-29","install_tag":null}}