# 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/8f/68/9b5e4d15ec0d29d646dcd45ef041c665182a12b99d464a17ac62e16fd063/datafiles-2.3.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",
"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": "ea63abf17163b814ac8f7c91de403772e66af1235344def0829f890656de4249",
"md5": "bfbc9887b30cd116e7bbcd6b69f8d62e",
"sha256": "0fd602a760c3fe6e6309f02b34d04b0ebe692a5ee09293c6c922f3b26de0c3c7"
},
"downloads": -1,
"filename": "datafiles-2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bfbc9887b30cd116e7bbcd6b69f8d62e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 32652,
"upload_time": "2024-10-30T17:08:54",
"upload_time_iso_8601": "2024-10-30T17:08:54.069262Z",
"url": "https://files.pythonhosted.org/packages/ea/63/abf17163b814ac8f7c91de403772e66af1235344def0829f890656de4249/datafiles-2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f689b5e4d15ec0d29d646dcd45ef041c665182a12b99d464a17ac62e16fd063",
"md5": "3f3c6cbacb08f7c1a4f50af875c6e04b",
"sha256": "7cc24098ae7f834544e046e815a45f41fc1f280495903cc0335eec6e240941cb"
},
"downloads": -1,
"filename": "datafiles-2.3.tar.gz",
"has_sig": false,
"md5_digest": "3f3c6cbacb08f7c1a4f50af875c6e04b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 25582,
"upload_time": "2024-10-30T17:08:55",
"upload_time_iso_8601": "2024-10-30T17:08:55.722197Z",
"url": "https://files.pythonhosted.org/packages/8f/68/9b5e4d15ec0d29d646dcd45ef041c665182a12b99d464a17ac62e16fd063/datafiles-2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-30 17:08:55",
"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
