datafiles 0.9

File-based ORM for dataclasses.

Datafiles: A file-based ORM for dataclasses

Datafiles is a bidirectional serialization library for Python dataclasses to synchronizes objects to the filesystem using type annotations. It supports a variety of file formats with round-trip preservation of formatting and comments, where possible. Object changes are automatically saved to disk and only include the minimum data needed to restore each object.

Popular use cases include:

• Coercing user-editable files into the proper Python types
• Storing program configuration and data in version control
• Loading data fixtures for demonstration or testing purposes
• Prototyping data models agnostic of persistence backends

Watch my lightning talk for a demo of this in action!

Overview

Take an existing dataclass such as this example from the documentation:

from dataclasses import dataclass

@dataclass
class InventoryItem:
    """Class for keeping track of an item in inventory."""

    name: str
    unit_price: float
    quantity_on_hand: int = 0

    def total_cost(self) -> float:
        return self.unit_price * self.quantity_on_hand

and decorate it with a directory pattern to synchronize instances:

from datafiles import datafile

@datafile("inventory/items/{self.name}.yml")
@dataclass
class InventoryItem:
    ...

Then, work with instances of the class as normal:

>>> item = InventoryItem("widget", 3)

# inventory/items/widget.yml

unit_price: 3.0

Changes to the object are automatically saved to the filesystem:

>>> item.quantity_on_hand += 100

# inventory/items/widget.yml

unit_price: 3.0
quantity_on_hand: 100

Changes to the filesystem are automatically reflected in the object:

# inventory/items/widget.yml

unit_price: 2.5  # <= manually changed from "3.0"
quantity_on_hand: 100

>>> item.unit_price
2.5

Objects can also be restored from the filesystem:

>>> from datafiles import Missing
>>> item = InventoryItem("widget", Missing)
>>> item.unit_price
2.5
>>> item.quantity_on_hand
100

Installation

Because datafiles relies on dataclasses and type annotations, Python 3.7+ is required. Install this library directly into an activated virtual environment:

$ pip install datafiles

or add it to your Poetry project:

$ poetry add datafiles

Documentation

To see additional synchronization and formatting options, please consult the full documentation.