Decorator

Given this example dataclass:

1
2
3
4
5
6
7
from dataclasses import dataclass

@dataclass
class Item:
    name: str
    count: int
    available: bool

Synchronization is enabled by add the @datafile(<pattern>) decorator:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from dataclasses import dataclass

from datafiles import datafile

@datafile("items/{self.name}.yml")
@dataclass
class Item:
    name: str
    count: int
    available: bool

or by replacing the @dataclass decorator entirely:

1
2
3
4
5
6
7
from datafiles import datafile

@datafile("items/{self.name}.yml")
class Item:
    name: str
    count: int
    available: bool

Filename

Instances of the class are synchronized to disk according to the <pattern> string:

1
2
Item("abc")  # <=> items/abc.yml
Item("def")  # <=> items/def.yml

Attributes included in the filename pattern are automatically excluded from the file contents.

Options

The following options can be passed to the @datafile() decorator:

Name Type Description Default
attrs dict Attributes to synchronize mapped to datafile.converters classes for serialization. {} 1
manual bool Synchronize object and file changes manually. False
defaults bool Include default values in files. False
auto_load bool Load automatically after saving.
If manual=True this option is ignored.
True
auto_save bool Save automatically after loading.
If manual=True this option is ignored.
True
auto_attr bool Automatically infer new attributes from the file. False

1 By default, synchronized attributes are inferred from the type annotations.

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from datafiles import datafile

@datafile("items/{self.name}.yml", manual=True, defaults=True)
class Item:
    name: str
    count: int
    available: bool

@datafile("config.yml", auto_save=False)
class Config:
    default_count: int = 42

Meta class

Alternatively, any of the above options can be configured through code by setting datafile_<option> in a Meta class:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
from datafiles import datafile, converters

@datafile("items/{self.name}.yml")
class Item:
    name: str
    count: int
    available: bool

    class Meta:
        datafile_attrs = {'count': converters.Integer}
        datafile_manual = True
        datafile_defaults = True
        datafiles_auto_load = False
        datafiles_auto_save = False

Base class

Finally, a datafile can explicitly extend datafiles.Model and set the pattern in the Meta class:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
from dataclasses import dataclass

from datafiles import Model, converters

@dataclass
class Item(Model):
    name: str
    count: int
    available: bool

    class Meta:
        datafile_pattern = "items/{self.name}.yml"
        datafile_attrs = {'count': converters.Integer}
        datafile_manual = True
        datafile_defaults = True