Skip to main content

File-based ORM for dataclasses.

Project description

Datafiles: A file-based ORM for Python 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.

Linux Build Windows Build Code Coverage PyPI License PyPI Version PyPI Downloads Gitter

Some common use cases include:

  • Coercing user-editable files into the proper Python types
  • Storing program configuration and state 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

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.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

datafiles-2.3.3.tar.gz (23.8 kB view details)

Uploaded Source

Built Distribution

datafiles-2.3.3-py3-none-any.whl (32.4 kB view details)

Uploaded Python 3

File details

Details for the file datafiles-2.3.3.tar.gz.

File metadata

  • Download URL: datafiles-2.3.3.tar.gz
  • Upload date:
  • Size: 23.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.0.1 CPython/3.11.11 Darwin/23.6.0

File hashes

Hashes for datafiles-2.3.3.tar.gz
Algorithm Hash digest
SHA256 39a77d1fdebc7e99d0a05748eced6a93d6065551923e4139166a7a4b91311ee7
MD5 5bf26538e77f20591b35f79e41062731
BLAKE2b-256 d442b0e71a2be7c76506f766eb359808a833c59297d68fb9140f162500e9adfc

See more details on using hashes here.

File details

Details for the file datafiles-2.3.3-py3-none-any.whl.

File metadata

  • Download URL: datafiles-2.3.3-py3-none-any.whl
  • Upload date:
  • Size: 32.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.0.1 CPython/3.11.11 Darwin/23.6.0

File hashes

Hashes for datafiles-2.3.3-py3-none-any.whl
Algorithm Hash digest
SHA256 228b9402aba415c24bd10aa57f3b77fbac151ba508292b7f22b067dc998f0763
MD5 a88303dd59d8f73196e1591ca80d7413
BLAKE2b-256 1b2c0cbc9d112d77d30d7e1a1df62be956941fd5dfddb047cc9ae64d3a8c9ac3

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page