Working with Python classes
Dumping Python classes
Only yaml = YAML(typ='unsafe') loads and dumps Python objects out-of-the-box. And since it loads any Python object, this can be unsafe, so don’t use it.
If you have instances of some class(es) that you want to dump or load, it is easy to allow the YAML instance to do that explicitly. You can either register the class with the YAML instance or decorate the class.
Registering is done with YAML.register_class():
import sys
import ruamel.yaml
class User:
def __init__(self, name, age):
self.name = name
self.age = age
yaml = ruamel.yaml.YAML()
yaml.register_class(User)
yaml.dump([User('Anthon', 18)], sys.stdout)
which gives as output:
- !User
name: Anthon
age: 18
The tag !User originates from the name of the class.
You can specify a different tag by adding the attribute yaml_tag, and explicitly specify dump and/or load classmethods which have to be named to_yaml resp. from_yaml:
import sys
import ruamel.yaml
class User:
yaml_tag = u'!user'
def __init__(self, name, age):
self.name = name
self.age = age
@classmethod
def to_yaml(cls, representer, node):
return representer.represent_scalar(cls.yaml_tag,
u'{.name}-{.age}'.format(node, node))
@classmethod
def from_yaml(cls, constructor, node):
return cls(*node.value.split('-'))
yaml = ruamel.yaml.YAML()
yaml.register_class(User)
yaml.dump([User('Anthon', 18)], sys.stdout)
which gives as output:
- !user Anthon-18
When using the decorator, which takes the YAML() instance as a parameter, the yaml = YAML() line needs to be moved up in the file:
import sys
from ruamel.yaml import YAML, yaml_object
yaml = YAML()
@yaml_object(yaml)
class User:
yaml_tag = u'!user'
def __init__(self, name, age):
self.name = name
self.age = age
@classmethod
def to_yaml(cls, representer, node):
return representer.represent_scalar(cls.yaml_tag,
u'{.name}-{.age}'.format(node, node))
@classmethod
def from_yaml(cls, constructor, node):
return cls(*node.value.split('-'))
yaml.dump([User('Anthon', 18)], sys.stdout)
The yaml_tag, from_yaml and to_yaml work in the same way as when using .register_class().
Alternatively you can use the register_class() method as decorator, This also requires you have the yaml instance available:
import sys
import ruamel.yaml
yaml = ruamel.yaml.YAML()
@yaml.register_class
class User:
yaml_tag = u'!user'
def __init__(self, name, age):
self.name = name
self.age = age
@classmethod
def to_yaml(cls, representer, node):
return representer.represent_scalar(cls.yaml_tag,
u'{.name}-{.age}'.format(node, node))
@classmethod
def from_yaml(cls, constructor, node):
return cls(*node.value.split('-'))
yaml.dump([User('Anthon', 18)], sys.stdout)
This also gives:
- !user Anthon-18
If your class is dumped as a YAML mapping or sequence, there might be an (indirect) reference to the object itself in one or more of the mapping keys (in YAML these don’t have to be simple scalars), mapping values or sequence entries.
That means that re-creating an object in to_yaml cannot generally just create a dict/list from the node parameter and then create and return a complete object. The solution for this is to create an empty object and yield that and then fill in the content data afterwards. That way, if there is a self reference, and the same node is encountered while creating the content for the object, there is an id (from the yielded object) created for that node which can be assigned.
from pathlib import Path
import ruamel.yaml
class Person:
def __init__(self, name, siblings=None):
self.name = name
self.siblings = [] if siblings is None else siblings
arya = Person('Arya')
sansa = Person('Sansa')
arya.siblings.append(sansa) # there are better ways to represent this
sansa.siblings.append(arya)
yaml = ruamel.yaml.YAML()
yaml.register_class(Person)
path = Path('/tmp/arya.yaml')
yaml.dump(arya, path)
print(path.read_text())
dumping as:
&id001 !Person
name: Arya
siblings:
- !Person
name: Sansa
siblings:
- *id001
And you can load the output:
from pathlib import Path
import ruamel.yaml
class Person:
def __init__(self, name, siblings=None):
self.name = name
self.siblings = [] if siblings is None else siblings
def __repr__(self):
return f'Person(name: {self.name}, siblings: {self.siblings})'
path = Path('/tmp/arya.yaml')
yaml = ruamel.yaml.YAML()
yaml.register_class(Person)
data = yaml.load(path)
print(data)
giving:
Person(name: Arya, siblings: [Person(name: Sansa, siblings: [Person(name: Arya, siblings: [...])])])
But if you provide a (too) simple loader:
from pathlib import Path
import ruamel.yaml
class Person:
def __init__(self, name, siblings=None):
self.name = name
self.siblings = [] if siblings is None else siblings
def __repr__(self):
return f'Person(name: {self.name}, siblings: {self.siblings})'
@classmethod
def from_yaml(cls, constructor, node):
data = ruamel.yaml.CommentedMap()
constructor.construct_mapping(node, maptyp=data, deep=True)
return cls(**data)
path = Path('/tmp/arya.yaml')
yaml = ruamel.yaml.YAML()
yaml.register_class(Person)
data = yaml.load(path)
print(data)
giving:
Person(name: Arya, siblings: [Person(name: Sansa, siblings: [None])])
As you can see, Sansa has no normal siblings after this load.
What you need to do is yield the empty Person instance, and fill it in afterwards:
from pathlib import Path
import ruamel.yaml
class Person:
def __init__(self, name, siblings=None):
self.name = name
self.siblings = [] if siblings is None else siblings
def __repr__(self):
return f'Person(name: {self.name}, siblings: {self.siblings})'
@classmethod
def from_yaml(cls, constructor, node):
person = Person(name='')
yield person
data = ruamel.yaml.CommentedMap()
constructor.construct_mapping(node, maptyp=data, deep=True)
for k, v in data.items():
setattr(person, k, v)
path = Path('/tmp/arya.yaml')
yaml = ruamel.yaml.YAML()
yaml.register_class(Person)
data = yaml.load(path)
print(data)
giving:
Person(name: Arya, siblings: [Person(name: Sansa, siblings: [Person(name: Arya, siblings: [...])])])
Dataclass
Although you could always register dataclasses, in 0.17.34 support was added to call __post_init__() on these classes, if available.
from typing import ClassVar
from dataclasses import dataclass
import ruamel.yaml
@dataclass
class DC:
yaml_tag: ClassVar = '!dc_example' # if you don't want !DC as tag
abc: int
klm: int
xyz: int = 0
def __post_init__(self) -> None:
self.xyz = self.abc + self.klm
yaml = ruamel.yaml.YAML()
yaml.register_class(DC)
dc = DC(abc=5, klm=42)
assert dc.xyz == 47
yaml_str = """\
!dc_example
abc: 13
klm: 37
"""
dc2 = yaml.load(yaml_str)
print(f'{dc2.xyz=}')
printing:
dc2.xyz=50