# Datafiles: A file-based ORM for Python dataclasses
Datafiles is a bidirectional serialization library for Python [dataclasses](https://docs.python.org/3/library/dataclasses.html) 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.
[](https://github.com/jacebrowning/datafiles/actions)
[](https://ci.appveyor.com/project/jacebrowning/datafiles)
[
](https://codecov.io/gh/jacebrowning/datafiles)
[](https://pypi.org/project/datafiles)
[](https://pypi.org/project/datafiles)
[](https://pypistats.org/packages/datafiles)
[](https://gitter.im/jacebrowning/datafiles)
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](https://www.youtube.com/watch?v=moYkuNrmc1I&feature=youtu.be&t=1225) for a demo of this in action!
## Overview
Take an existing dataclass such as [this example](https://docs.python.org/3/library/dataclasses.html#module-dataclasses) from the documentation:
```python
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:
```python
from datafiles import datafile
@datafile("inventory/items/{self.name}.yml")
class InventoryItem:
...
```
Then, work with instances of the class as normal:
```python
>>> item = InventoryItem("widget", 3)
```
```yaml
# inventory/items/widget.yml
unit_price: 3.0
```
Changes to the object are automatically saved to the filesystem:
```python
>>> item.quantity_on_hand += 100
```
```yaml
# inventory/items/widget.yml
unit_price: 3.0
quantity_on_hand: 100
```
Changes to the filesystem are automatically reflected in the object:
```yaml
# inventory/items/widget.yml
unit_price: 2.5 # <= manually changed from "3.0"
quantity_on_hand: 100
```
```python
>>> item.unit_price
2.5
```
Objects can also be restored from the filesystem:
```python
>>> 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](https://poetry.eustace.io/) project:
```
$ poetry add datafiles
```
## Documentation
To see additional synchronization and formatting options, please consult the [full documentation](https://datafiles.readthedocs.io).
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/datafiles",
"name": "datafiles",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "dataclasses, serialization, type-annotations, object-relational mapping, YAML, JSON, JSON5, TOML",
"author": "Jace Browning",
"author_email": "jacebrowning@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a1/e4/1074af4f69ad1ce9074250473e43afe1581b903aaff021e775e34c640eb6/datafiles-2.3.1.tar.gz",
"platform": null,
"description": "# Datafiles: A file-based ORM for Python dataclasses\n\nDatafiles is a bidirectional serialization library for Python [dataclasses](https://docs.python.org/3/library/dataclasses.html) 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.\n\n[](https://github.com/jacebrowning/datafiles/actions)\n[](https://ci.appveyor.com/project/jacebrowning/datafiles)\n[\n](https://codecov.io/gh/jacebrowning/datafiles)\n[](https://pypi.org/project/datafiles)\n[](https://pypi.org/project/datafiles)\n[](https://pypistats.org/packages/datafiles)\n[](https://gitter.im/jacebrowning/datafiles)\n\nSome common use cases include:\n\n- Coercing user-editable files into the proper Python types\n- Storing program configuration and state in version control\n- Loading data fixtures for demonstration or testing purposes\n- Synchronizing application state using file sharing services\n- Prototyping data models agnostic of persistence backends\n\nWatch [my lightning talk](https://www.youtube.com/watch?v=moYkuNrmc1I&feature=youtu.be&t=1225) for a demo of this in action!\n\n## Overview\n\nTake an existing dataclass such as [this example](https://docs.python.org/3/library/dataclasses.html#module-dataclasses) from the documentation:\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass InventoryItem:\n \"\"\"Class for keeping track of an item in inventory.\"\"\"\n\n name: str\n unit_price: float\n quantity_on_hand: int = 0\n\n def total_cost(self) -> float:\n return self.unit_price * self.quantity_on_hand\n```\n\nand decorate it with a directory pattern to synchronize instances:\n\n```python\nfrom datafiles import datafile\n\n@datafile(\"inventory/items/{self.name}.yml\")\nclass InventoryItem:\n ...\n```\n\nThen, work with instances of the class as normal:\n\n```python\n>>> item = InventoryItem(\"widget\", 3)\n```\n\n```yaml\n# inventory/items/widget.yml\n\nunit_price: 3.0\n```\n\nChanges to the object are automatically saved to the filesystem:\n\n```python\n>>> item.quantity_on_hand += 100\n```\n\n```yaml\n# inventory/items/widget.yml\n\nunit_price: 3.0\nquantity_on_hand: 100\n```\n\nChanges to the filesystem are automatically reflected in the object:\n\n```yaml\n# inventory/items/widget.yml\n\nunit_price: 2.5 # <= manually changed from \"3.0\"\nquantity_on_hand: 100\n```\n\n```python\n>>> item.unit_price\n2.5\n```\n\nObjects can also be restored from the filesystem:\n\n```python\n>>> from datafiles import Missing\n>>> item = InventoryItem(\"widget\", Missing)\n>>> item.unit_price\n2.5\n>>> item.quantity_on_hand\n100\n```\n\n## Installation\n\nInstall this library directly into an activated virtual environment:\n\n```\n$ pip install datafiles\n```\n\nor add it to your [Poetry](https://poetry.eustace.io/) project:\n\n```\n$ poetry add datafiles\n```\n\n## Documentation\n\nTo see additional synchronization and formatting options, please consult the [full documentation](https://datafiles.readthedocs.io).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "File-based ORM for dataclasses.",
"version": "2.3.1",
"project_urls": {
"Documentation": "https://datafiles.readthedocs.io",
"Homepage": "https://pypi.org/project/datafiles",
"Repository": "https://github.com/jacebrowning/datafiles"
},
"split_keywords": [
"dataclasses",
" serialization",
" type-annotations",
" object-relational mapping",
" yaml",
" json",
" json5",
" toml"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "08b743ead94946903ce92df80791d3a9a783ca96672b38486f901b542fba93df",
"md5": "a18a224f71096a056bad38b9397649bb",
"sha256": "641b68e54038c7abab6ca1978ce3fa0c49c269d0686c17013e7f84f2e8267c5c"
},
"downloads": -1,
"filename": "datafiles-2.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a18a224f71096a056bad38b9397649bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 32396,
"upload_time": "2025-02-11T04:28:50",
"upload_time_iso_8601": "2025-02-11T04:28:50.036184Z",
"url": "https://files.pythonhosted.org/packages/08/b7/43ead94946903ce92df80791d3a9a783ca96672b38486f901b542fba93df/datafiles-2.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a1e41074af4f69ad1ce9074250473e43afe1581b903aaff021e775e34c640eb6",
"md5": "fd21cce1f3baa909770e5fae4037521e",
"sha256": "4f77f8c910c6f7f39158864aa92d88a2846ec94419e855f788f33cfb937a2dfe"
},
"downloads": -1,
"filename": "datafiles-2.3.1.tar.gz",
"has_sig": false,
"md5_digest": "fd21cce1f3baa909770e5fae4037521e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 25312,
"upload_time": "2025-02-11T04:28:54",
"upload_time_iso_8601": "2025-02-11T04:28:54.151004Z",
"url": "https://files.pythonhosted.org/packages/a1/e4/1074af4f69ad1ce9074250473e43afe1581b903aaff021e775e34c640eb6/datafiles-2.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-11 04:28:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jacebrowning",
"github_project": "datafiles",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"appveyor": true,
"lcname": "datafiles"
}
JSON
