TOML conversion
The TOMLDataclass
mixin provides automatic conversion to and from TOML. This uses the tomlkit
library under the hood.
to_dict
/from_dict
convert to and from Python dicts.to_toml
/from_toml
convert to and from TOML file-like objects.save
/load
convert to and from a TOML file-like object or path.to_toml_string
/from_toml_string
convert to and from TOML strings.
Usage Example
Define a TOMLDataclass
.
from dataclasses import dataclass
from fancy_dataclass import TOMLDataclass
@dataclass
class Database(TOMLDataclass):
server: str
ports: list[int]
connection_max: int = 5000
enabled: bool = True
Save data to a TOML file.
>>> db_config = Database(server='192.168.1.1', ports=[8001, 8001, 8002])
>>> with open('db_config.toml', 'w') as f:
db_config.to_toml(f)
View the TOML file db_config.toml
:
Load the data from a TOML file:
>>> with open('db_config.toml') as f:
db_config = Database.from_toml(f)
>>> print(db_config)
Database(server='192.168.1.1', ports=[8001, 8001, 8002], connection_max=5000, enabled=True)
Details
TOMLDataclass
inherits from DictDataclass
, which can be used to convert dataclasses to/from Python dicts via to_dict
and from_dict
. You may use DictDataclass
if you do not need to interact with TOML serialized data.
Class and Field Settings
The class and field settings for TOMLDataclass
are identical to those for JSONDataclass
. See DictDataclassSettings
for the list of class settings, and DictDataclassFieldSettings
for the list of field-specific settings.
TOML is intended as more of a configuration format than a data storage format. Consequently, unlike JSONDataclass
, TOMLDataclass
does not suppress default field values in its output by default. To opt into this behavior, you can set the class setting suppress_defaults=True
.
Field Comments
Unlike JSON, the TOML format supports comments, which are lines beginning with #
. You can use the doc
attribute of each TOMLDataclass
field to prepend a comment in the TOML output. For example:
from dataclasses import dataclass, field
from fancy_dataclass import TOMLDataclass
@dataclass
class Rectangle(TOMLDataclass):
width: float = field(metadata={'doc': 'width (in cm)'})
height: float = field(metadata={'doc': 'height (in cm)'})
>>> print(Rectangle(48.5, 30).to_toml_string())
# width (in cm)
width = 48.5
# height (in cm)
height = 30
Note
You can also use the Annotated
/Doc
syntax (PEP 727) to specify field comments. See DocFieldSettings
.
Top-level Comments
You may also want to include comment lines at the top of the TOML file or section. To do this, you can set parameters for the class-level settings in one of the following ways:
- Set the
comment
setting to a string. - Set the
doc_as_comment
flag toTrue
. In this case, the class's docstring will be used as a top-level comment.
These options are mutually exclusive (an error will be thrown if doc_as_comment=True
and comment
is also set).
For example, suppose we modify the definition of Rectangle
above to:
@dataclass
class Rectangle(TOMLDataclass, doc_as_comment=True):
"""Rectangle: A quadrilateral with all right angles."""
width: float = field(metadata={'doc': 'width (in cm)'})
height: float = field(metadata={'doc': 'height (in cm)'})
Then the TOML output becomes: