datafiles

What it is and what it does

Datafiles bridges Python dataclasses and the filesystem by automatically persisting object state to files and reloading changes from disk. You decorate a dataclass with a file path pattern, then read and write the object normally—changes sync bidirectionally without explicit save/load calls. It supports YAML, JSON, TOML, and JSON5 formats, preserving comments and formatting where possible.

The library is designed for configuration management, test fixtures, version-controlled state, and prototyping data models before committing to a database backend. It depends on ruamel.yaml, tomlkit, json-five, parse, minilog, classproperties, and cached_property to handle format-specific serialization and property introspection.

Use it for:

• Store application configuration in YAML or TOML files that remain human-editable while staying type-safe in Python.
• Load test fixtures from files into dataclass instances, automatically coercing types and validating structure.
• Synchronize application state across machines using file-sharing services by treating the filesystem as a shared data layer.
• Prototype data models with file-based persistence before migrating to a database backend.
• Version-control program state and configuration by keeping dataclass instances synchronized to committed files.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Datafiles is a file-based ORM that automatically synchronizes Python dataclasses to disk files (YAML, JSON, TOML, JSON5) and back, treating the filesystem as a bidirectional persistence layer with minimal boilerplate.

Yes. Datafiles is actively maintained, has no known vulnerabilities, uses a permissive MIT license, and offers a clean, low-friction way to persist dataclasses to disk with bidirectional sync. Install it if you need automatic file-based persistence for configuration, state, or fixtures; skip it if you require a traditional database or need Python versions below 3.10.

Install

datafiles on PyPI

pip install datafiles

uv add datafiles

poetry add datafiles

Installing datafiles

Before you install

Low friction: pure Python wheel with seven runtime dependencies (cached_property, classproperties, json-five, minilog, parse, ruamel.yaml, tomlkit). Active maintenance with last commit 2026-08-05 and 213 repository stars; supports Python 3.10–3.14.

License in practice

MIT license (permissive) imposes no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

from dataclasses import dataclass
from datafiles import datafile

@datafile("config/{self.name}.yml")
@dataclass
class Config:
    name: str
    value: int = 0

config = Config("app")
config.value = 1  # automatically saved to config/app.yml

Requires Python 3.10 or later (minimum 3.10, maximum <4.0).

Verify before relying

• Whether round-trip formatting preservation works equally well across all supported formats (YAML, JSON, TOML, JSON5).
• Performance characteristics when synchronizing large dataclass instances or deeply nested structures.
• Behavior when multiple processes or threads modify the same dataclass instance concurrently.

Package facts

Evidence: datafiles-2.5-py3-none-any.whl

Keywords: dataclasses, serialization, type-annotations, object-relational mapping, YAML, JSON, JSON5, TOML

Tags

More Software Development packages