Skip to content

Dataclasses

rn_forge.commons.lang.dataclasses

Dataclass serialisation and typed deserialisation.

:class:DataclassMixin rejects values that do not match their declared field types. :class:LenientDataclassMixin disables that check for records whose annotations dacite cannot validate, or whose input is intentionally ragged. :class:StrictDataclassMixin keeps the check and also rejects keys that name no field, at every nesting level.

Dacite cannot validate PEP 695 type aliases or unbound type variables, including when nested in a container. Classes with those annotations must use the lenient mixin and document the specific limitation.

Field exclusion ~~~~~~~~~~~~~~~

Mark a field with metadata={"exclude": True} to omit it from as_dict() (and therefore from JSON/YAML output)::

@dataclass
class User(DataclassMixin):
    name: str
    password: str = field(metadata={"exclude": True})

DataclassMixin

Mixin that adds serialisation helpers to a @dataclass.

Must be used together with @dataclasses.dataclass. The mixin itself does not apply the decorator — this keeps field declarations explicit and avoids any global side effects.

Example::

from dataclasses import dataclass, field
from rn_forge.commons import DataclassMixin

@dataclass
class AppConfig(DataclassMixin):
    host: str = "localhost"
    port: int = 8080
    secret: str = field(default="changeme", metadata={"exclude": True})

cfg = AppConfig()
print(cfg.to_json())   # {"host": "localhost", "port": 8080}
print(cfg.to_yaml())   # host: localhost\nport: 8080\n

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

LenientDataclassMixin

Bases: DataclassMixin

A :class:DataclassMixin that does not check field types.

Mismatched values pass through unchanged. Missing required fields and invalid enum members still raise :class:~rn_forge.commons.exceptions.AppException; container coercion and StrEnum reconstruction remain enabled.

Use this only when the input is intentionally ragged or dacite cannot validate the annotation, and document that reason on the subclass.

Example::

@dataclass(frozen=True, slots=True)
class UpstreamRow(LenientDataclassMixin):
    name: str
    weight: int          # the upstream feed sometimes sends "12"

UpstreamRow.from_dict({"name": "a", "weight": "12"}).weight
# '12'

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

StrictDataclassMixin

Bases: DataclassMixin

A :class:DataclassMixin that also rejects keys naming no field.

Type checking, container coercion and StrEnum reconstruction are unchanged. :meth:~DataclassMixin.from_dict additionally raises :class:~rn_forge.commons.exceptions.AppException when data — or any nested mapping that becomes a dataclass field — carries a key the target dataclass does not declare. The message names every such key by its dotted path. Nested dataclass fields are checked whether or not their own class uses this mixin.

Example::

@dataclass(frozen=True, slots=True)
class Repository(StrictDataclassMixin):
    name: str
    archetype: str = "python-tool"

@dataclass(frozen=True, slots=True)
class ProjectConfig(StrictDataclassMixin):
    repository: Repository

ProjectConfig.from_dict({"repository": {"name": "x", "archtype": "lib"}})
# AppException: Invalid ProjectConfig: unknown key(s) repository.archtype

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.