dat

datafiles

A file-based ORM for Python dataclasses.

Showing:

Popularity

Downloads/wk

0

GitHub Stars

138

Maintenance

Last Commit

22d ago

Contributors

6

Package

Dependencies

7

License

MIT

Categories

Readme

Datafiles: A file-based ORM for dataclasses

Datafiles is a bidirectional serialization library for Python dataclasses to synchronize 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.

Travis CI AppVeyor Coveralls PyPI License PyPI Version Gitter

Some common 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
  • Synchronizing application state using file sharing services
  • 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")
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.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100