Utilities
The following functions exist to provide additional high-level functionality.
auto()
Given an arbitrary file, this library can attempt to map its structure into a Python object synchronized back to that file. For example, a YAML file named sample.yml
containing the following:
names:
- Alice
- Bob
numbers:
- 1
- 2
can be loaded into an object:
>>> from datafiles import auto
>>> sample = auto("sample.yml")
>>> sample.names
["Alice", "Bob"]
where modified attributes:
>>> sample.numbers.append(3)
are automatically reflected in the file:
names:
- Alice
- Bob
numbers:
- 1
- 2
- 3
Additional examples can be found in this Jupyter Notebook.
frozen()
This context manager can be used to temporarily disable saving objects to the filesystem:
import datafiles
from .models import MyModel
instance = MyModel()
with datafiles.frozen():
instance.a = 1
instance.b = 2
instance.c = 3
instance.d = 4
This is useful when changes manipulate a complex object's structure in such a way that references to synchronized attributes are lost or to improve performance when making lots of changes.
Thawing Objects
Unless manual=True
is set, the next modification outside of the context manager will trigger a save. To do this automatically, include the objects as arguments:
...
with datafiles.frozen(instance):
instance.a = 1
instance.b = 2
instance.c = 3
sync()
This helper can be used to enable file synchronization on an arbitrary object:
from dataclasses import dataclass
@dataclass
class InventoryItem:
name: str
unit_price: float
quantity_on_hand: int = 0
by providing it a path or directory pattern:
>>> from datafiles import sync
>>> item = InventoryItem("widget", 3)
>>> sync(item, "inventory/items/{self.name}.yml")