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:
    ...