Manager API
Object-relational mapping (ORM) methods are available on all model classes via the objects
proxy. The following sections assume an empty filesystem and the following sample datafile definition:
from datafiles import datafile
@datafile("my_models/{self.my_key}.yml")
class MyModel:
my_key: str
my_value: int = 0
Many of the following examples are also shown in this notebook.
get()
Instantiate an object from an existing file. If no matching file exist, or if any other problem occurs, an appropriate exception will be raised.
>>> MyModel.objects.get("foobar")
Traceback (most recent call last):
...
FileNotFoundError: [Errno 2] No such file or directory: "foobar.yml"
>>> m = MyModel("foobar", 42)
>>> MyModel.objects.get("foobar")
MyModel(my_key="foobar", my_value=42)
get_or_none()
Instantiate an object from an existing file or return None
if no matching file exists:
>>> MyModel.objects.get_or_none("foobar")
None
>>> m = MyModel("foobar", 42)
>>> MyModel.objects.get_or_none("foobar")
MyModel(my_key="foobar", my_value=42)
get_or_create()
Instantiate an object from an existing file or create one if no matching file exists:
>>> m = MyModel("foo", 42)
>>> MyModel.objects.get_or_create("foo")
MyModel(my_key="foo", my_value=42)
>>> MyModel.objects.get_or_create("bar")
MyModel(my_key="bar", my_value=0)
all()
Iterate over all objects matching the pattern:
>>> generator = MyModel.objects.all()
>>> list(generator)
[]
>>> m1 = MyModel("foo")
>>> m2 = MyModel("bar", 42)
>>> for m in MyModel.objects.all():
... print(m)
...
MyModel(my_key="foo" my_value=0)
MyModel(my_key="bar", my_value=42)
Exclude objects from ever being loaded and returned with _exclude
:
>>> generator = MyModel.objects.all(_exclude="foo")
filter()
Iterate all objects matching the pattern with additional required attribute values:
>>> generator = MyModel.objects.filter(my_value=42)
>>> list(generator)
[MyModel(my_key="foo", my_value=42)]
Exclude objects from ever being loaded and returned with _exclude
:
>>> generator = MyModel.objects.filter(_exclude="foo")
Nested dataclass values can be queried using __
as a delimiter:
>>> generator = NestedModel.objects.filter(foo__bar__qux=42)