File Formats
The following formats are supported for serialization.
YAML
By default, datafiles uses the YAML language for serialization. Any of the following file extensions will use this format:
.yml
.yaml
- (no extension)
Sample output:
my_dict:
value: 0
my_list:
- value: 1
- value: 2
my_bool: true
my_float: 1.23
my_int: 42
my_str: Hello, world!
Where possible, comments and whitespace are preserved in files as shown in this Jupyter Notebook.
JSON
The JSON language is also supported. Any of the following file extensions will use this format:
.json
Sample output:
{
"my_dict": {
"value": 0
},
"my_list": [
{
"value": 1
},
{
"value": 2
}
],
"my_bool": true,
"my_float": 1.23,
"my_int": 42,
"my_str": "Hello, world!"
}
Additional examples can be found in this Jupyter Notebook.
TOML
The TOML language is also supported. Any of the following file extensions will use this format:
.toml
Sample output:
my_bool = true
my_float = 1.23
my_int = 42
my_str = "Hello, world!"
[[my_list]]
value = 1
[[my_list]]
value = 2
[my_dict]
value = 0
Additional examples can be found in this Jupyter Notebook.
Custom Formats
Additional formats are supported through a registration system.
Map Existing
To map one of the existing formatter classes to a new file extension:
from datafile import datafile, formats
formats.register('.conf', formats.YAML)
@datafile("my-file-path.conf")
class MyConfig:
...
New Format
To support new formats, extend the datafiles.formats.Formatter
base class:
from datafile import datafile, formats
class MyFormat(formats.Format):
@classmethod
def extensions(cls) -> List[str]:
return ['.my_ext']
@classmethod
@abstractmethod
def deserialize(cls, file_object: IO) -> Dict:
# Read `file_object` and return a dictionary
@classmethod
@abstractmethod
def serialize(cls, data: Dict) -> str:
# Convert `data` to a string
formats.register('.my_ext', MyFormat)
@datafile("my-file-path.my_ext")
class MyConfig:
...