Model API

A model is created by either extending the Model class or using the datafile() decorator.

Decorator

Given this example dataclass:

from dataclasses import dataclass

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

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

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:

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:

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

Attributes included in the filename pattern are automatically excluded from the file contents. Filename patterns are relative to the file in which models are defined unless <pattern> is an absolute path or explicitly relative to the current directory:

Absolute: /tmp/items/{self.name}.yml
Relative to model: items/{self.name}.yml
Relative to current directory: ./items/{self.name}.yml

Options

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

Name	Type	Description	Default
`attrs`	`dict`	Map of attributes to `datafile.converters` classes for serialization.	`{}` ¹
`manual`	`bool`	Synchronize object and file changes manually.	`False`
`defaults`	`bool`	Include attributes with default values when serializing.	`False`
`infer`	`bool`	Automatically infer new attributes from the file.	`False`

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

For example:

from datafiles import datafile

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

@datafile("config.yml", infer=True)
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:

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

Base class

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

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