efro.dataclassio

Functionality for importing, exporting, and validating dataclasses.

This allows complex nested dataclasses to be flattened to json-compatible data and restored from said data. It also gracefully handles and preserves unrecognized attribute data, allowing older clients to interact with newer data formats in a nondestructive manner.

 1# Released under the MIT License. See LICENSE for details.
 2#
 3"""Functionality for importing, exporting, and validating dataclasses.
 4
 5This allows complex nested dataclasses to be flattened to json-compatible
 6data and restored from said data. It also gracefully handles and preserves
 7unrecognized attribute data, allowing older clients to interact with newer
 8data formats in a nondestructive manner.
 9"""
10
11from __future__ import annotations
12
13from efro.util import set_canonical_module_names
14from efro.dataclassio._base import (
15    Codec,
16    IOAttrs,
17    IOExtendedData,
18    IOMultiType,
19    EXTRA_ATTRS_ATTR,
20)
21from efro.dataclassio._prep import (
22    ioprep,
23    ioprepped,
24    will_ioprep,
25    is_ioprepped_dataclass,
26)
27from efro.dataclassio._pathcapture import DataclassFieldLookup
28from efro.dataclassio._api import (
29    JsonStyle,
30    dataclass_to_dict,
31    dataclass_to_json,
32    dataclass_from_dict,
33    dataclass_from_json,
34    dataclass_validate,
35)
36
37__all__ = [
38    'Codec',
39    'DataclassFieldLookup',
40    'EXTRA_ATTRS_ATTR',
41    'IOAttrs',
42    'IOExtendedData',
43    'IOMultiType',
44    'JsonStyle',
45    'dataclass_from_dict',
46    'dataclass_from_json',
47    'dataclass_to_dict',
48    'dataclass_to_json',
49    'dataclass_validate',
50    'ioprep',
51    'ioprepped',
52    'is_ioprepped_dataclass',
53    'will_ioprep',
54]
55
56# Have these things present themselves cleanly as 'thismodule.SomeClass'
57# instead of 'thismodule._internalmodule.SomeClass'
58set_canonical_module_names(globals())
class Codec(enum.Enum):
29class Codec(Enum):
30    """Specifies expected data format exported to or imported from."""
31
32    # Use only types that will translate cleanly to/from json: lists,
33    # dicts with str keys, bools, ints, floats, and None.
34    JSON = 'json'
35
36    # Mostly like JSON but passes bytes and datetime objects through
37    # as-is instead of converting them to json-friendly types.
38    FIRESTORE = 'firestore'

Specifies expected data format exported to or imported from.

JSON = <Codec.JSON: 'json'>
FIRESTORE = <Codec.FIRESTORE: 'firestore'>
Inherited Members
enum.Enum
name
value
class DataclassFieldLookup(typing.Generic[~T]):
 61class DataclassFieldLookup(Generic[T]):
 62    """Get info about nested dataclass fields in type-safe way."""
 63
 64    def __init__(self, cls: type[T]) -> None:
 65        self.cls = cls
 66
 67    def path(self, callback: Callable[[T], Any]) -> str:
 68        """Look up a path on child dataclass fields.
 69
 70        example:
 71          DataclassFieldLookup(MyType).path(lambda obj: obj.foo.bar)
 72
 73        The above example will return the string 'foo.bar' or something
 74        like 'f.b' if the dataclasses have custom storage names set.
 75        It will also be static-type-checked, triggering an error if
 76        MyType.foo.bar is not a valid path. Note, however, that the
 77        callback technically allows any return value but only nested
 78        dataclasses and their fields will succeed.
 79        """
 80
 81        # We tell the type system that we are returning an instance
 82        # of our class, which allows it to perform type checking on
 83        # member lookups. In reality, however, we are providing a
 84        # special object which captures path lookups, so we can build
 85        # a string from them.
 86        if not TYPE_CHECKING:
 87            out = callback(_PathCapture(self.cls))
 88            if not isinstance(out, _PathCapture):
 89                raise TypeError(
 90                    f'Expected a valid path under'
 91                    f' the provided object; got a {type(out)}.'
 92                )
 93            return out.path
 94        return ''
 95
 96    def paths(self, callback: Callable[[T], list[Any]]) -> list[str]:
 97        """Look up multiple paths on child dataclass fields.
 98
 99        Functionality is identical to path() but for multiple paths at once.
100
101        example:
102          DataclassFieldLookup(MyType).paths(lambda obj: [obj.foo, obj.bar])
103        """
104        outvals: list[str] = []
105        if not TYPE_CHECKING:
106            outs = callback(_PathCapture(self.cls))
107            assert isinstance(outs, list)
108            for out in outs:
109                if not isinstance(out, _PathCapture):
110                    raise TypeError(
111                        f'Expected a valid path under'
112                        f' the provided object; got a {type(out)}.'
113                    )
114                outvals.append(out.path)
115        return outvals

Get info about nested dataclass fields in type-safe way.

DataclassFieldLookup(cls: type[~T])
64    def __init__(self, cls: type[T]) -> None:
65        self.cls = cls
cls
def path(self, callback: Callable[[~T], Any]) -> str:
67    def path(self, callback: Callable[[T], Any]) -> str:
68        """Look up a path on child dataclass fields.
69
70        example:
71          DataclassFieldLookup(MyType).path(lambda obj: obj.foo.bar)
72
73        The above example will return the string 'foo.bar' or something
74        like 'f.b' if the dataclasses have custom storage names set.
75        It will also be static-type-checked, triggering an error if
76        MyType.foo.bar is not a valid path. Note, however, that the
77        callback technically allows any return value but only nested
78        dataclasses and their fields will succeed.
79        """
80
81        # We tell the type system that we are returning an instance
82        # of our class, which allows it to perform type checking on
83        # member lookups. In reality, however, we are providing a
84        # special object which captures path lookups, so we can build
85        # a string from them.
86        if not TYPE_CHECKING:
87            out = callback(_PathCapture(self.cls))
88            if not isinstance(out, _PathCapture):
89                raise TypeError(
90                    f'Expected a valid path under'
91                    f' the provided object; got a {type(out)}.'
92                )
93            return out.path
94        return ''

Look up a path on child dataclass fields.

example: DataclassFieldLookup(MyType).path(lambda obj: obj.foo.bar)

The above example will return the string 'foo.bar' or something like 'f.b' if the dataclasses have custom storage names set. It will also be static-type-checked, triggering an error if MyType.foo.bar is not a valid path. Note, however, that the callback technically allows any return value but only nested dataclasses and their fields will succeed.

def paths(self, callback: Callable[[~T], list[Any]]) -> list[str]:
 96    def paths(self, callback: Callable[[T], list[Any]]) -> list[str]:
 97        """Look up multiple paths on child dataclass fields.
 98
 99        Functionality is identical to path() but for multiple paths at once.
100
101        example:
102          DataclassFieldLookup(MyType).paths(lambda obj: [obj.foo, obj.bar])
103        """
104        outvals: list[str] = []
105        if not TYPE_CHECKING:
106            outs = callback(_PathCapture(self.cls))
107            assert isinstance(outs, list)
108            for out in outs:
109                if not isinstance(out, _PathCapture):
110                    raise TypeError(
111                        f'Expected a valid path under'
112                        f' the provided object; got a {type(out)}.'
113                    )
114                outvals.append(out.path)
115        return outvals

Look up multiple paths on child dataclass fields.

Functionality is identical to path() but for multiple paths at once.

example: DataclassFieldLookup(MyType).paths(lambda obj: [obj.foo, obj.bar])

EXTRA_ATTRS_ATTR = '_DCIOEXATTRS'
class IOAttrs:
108class IOAttrs:
109    """For specifying io behavior in annotations.
110
111    'storagename', if passed, is the name used when storing to json/etc.
112    'store_default' can be set to False to avoid writing values when equal
113        to the default value. Note that this requires the dataclass field
114        to define a default or default_factory or for its IOAttrs to
115        define a soft_default value.
116    'whole_days', if True, requires datetime values to be exactly on day
117        boundaries (see efro.util.utc_today()).
118    'whole_hours', if True, requires datetime values to lie exactly on hour
119        boundaries (see efro.util.utc_this_hour()).
120    'whole_minutes', if True, requires datetime values to lie exactly on minute
121        boundaries (see efro.util.utc_this_minute()).
122    'soft_default', if passed, injects a default value into dataclass
123        instantiation when the field is not present in the input data.
124        This allows dataclasses to add new non-optional fields while
125        gracefully 'upgrading' old data. Note that when a soft_default is
126        present it will take precedence over field defaults when determining
127        whether to store a value for a field with store_default=False
128        (since the soft_default value is what we'll get when reading that
129        same data back in when the field is omitted).
130    'soft_default_factory' is similar to 'default_factory' in dataclass
131        fields; it should be used instead of 'soft_default' for mutable types
132        such as lists to prevent a single default object from unintentionally
133        changing over time.
134    """
135
136    # A sentinel object to detect if a parameter is supplied or not.  Use
137    # a class to give it a better repr.
138    class _MissingType:
139        pass
140
141    MISSING = _MissingType()
142
143    storagename: str | None = None
144    store_default: bool = True
145    whole_days: bool = False
146    whole_hours: bool = False
147    whole_minutes: bool = False
148    soft_default: Any = MISSING
149    soft_default_factory: Callable[[], Any] | _MissingType = MISSING
150
151    def __init__(
152        self,
153        storagename: str | None = storagename,
154        store_default: bool = store_default,
155        whole_days: bool = whole_days,
156        whole_hours: bool = whole_hours,
157        whole_minutes: bool = whole_minutes,
158        soft_default: Any = MISSING,
159        soft_default_factory: Callable[[], Any] | _MissingType = MISSING,
160    ):
161        # Only store values that differ from class defaults to keep
162        # our instances nice and lean.
163        cls = type(self)
164        if storagename != cls.storagename:
165            self.storagename = storagename
166        if store_default != cls.store_default:
167            self.store_default = store_default
168        if whole_days != cls.whole_days:
169            self.whole_days = whole_days
170        if whole_hours != cls.whole_hours:
171            self.whole_hours = whole_hours
172        if whole_minutes != cls.whole_minutes:
173            self.whole_minutes = whole_minutes
174        if soft_default is not cls.soft_default:
175            # Do what dataclasses does with its default types and
176            # tell the user to use factory for mutable ones.
177            if isinstance(soft_default, (list, dict, set)):
178                raise ValueError(
179                    f'mutable {type(soft_default)} is not allowed'
180                    f' for soft_default; use soft_default_factory.'
181                )
182            self.soft_default = soft_default
183        if soft_default_factory is not cls.soft_default_factory:
184            self.soft_default_factory = soft_default_factory
185            if self.soft_default is not cls.soft_default:
186                raise ValueError(
187                    'Cannot set both soft_default and soft_default_factory'
188                )
189
190    def validate_for_field(self, cls: type, field: dataclasses.Field) -> None:
191        """Ensure the IOAttrs instance is ok to use with the provided field."""
192
193        # Turning off store_default requires the field to have either
194        # a default or a default_factory or for us to have soft equivalents.
195
196        if not self.store_default:
197            field_default_factory: Any = field.default_factory
198            if (
199                field_default_factory is dataclasses.MISSING
200                and field.default is dataclasses.MISSING
201                and self.soft_default is self.MISSING
202                and self.soft_default_factory is self.MISSING
203            ):
204                raise TypeError(
205                    f'Field {field.name} of {cls} has'
206                    f' neither a default nor a default_factory'
207                    f' and IOAttrs contains neither a soft_default'
208                    f' nor a soft_default_factory;'
209                    f' store_default=False cannot be set for it.'
210                )
211
212    def validate_datetime(
213        self, value: datetime.datetime, fieldpath: str
214    ) -> None:
215        """Ensure a datetime value meets our value requirements."""
216        if self.whole_days:
217            if any(
218                x != 0
219                for x in (
220                    value.hour,
221                    value.minute,
222                    value.second,
223                    value.microsecond,
224                )
225            ):
226                raise ValueError(
227                    f'Value {value} at {fieldpath} is not a whole day.'
228                )
229        elif self.whole_hours:
230            if any(
231                x != 0 for x in (value.minute, value.second, value.microsecond)
232            ):
233                raise ValueError(
234                    f'Value {value} at {fieldpath}' f' is not a whole hour.'
235                )
236        elif self.whole_minutes:
237            if any(x != 0 for x in (value.second, value.microsecond)):
238                raise ValueError(
239                    f'Value {value} at {fieldpath}' f' is not a whole minute.'
240                )

For specifying io behavior in annotations.

'storagename', if passed, is the name used when storing to json/etc. 'store_default' can be set to False to avoid writing values when equal to the default value. Note that this requires the dataclass field to define a default or default_factory or for its IOAttrs to define a soft_default value. 'whole_days', if True, requires datetime values to be exactly on day boundaries (see efro.util.utc_today()). 'whole_hours', if True, requires datetime values to lie exactly on hour boundaries (see efro.util.utc_this_hour()). 'whole_minutes', if True, requires datetime values to lie exactly on minute boundaries (see efro.util.utc_this_minute()). 'soft_default', if passed, injects a default value into dataclass instantiation when the field is not present in the input data. This allows dataclasses to add new non-optional fields while gracefully 'upgrading' old data. Note that when a soft_default is present it will take precedence over field defaults when determining whether to store a value for a field with store_default=False (since the soft_default value is what we'll get when reading that same data back in when the field is omitted). 'soft_default_factory' is similar to 'default_factory' in dataclass fields; it should be used instead of 'soft_default' for mutable types such as lists to prevent a single default object from unintentionally changing over time.

IOAttrs( storagename: str | None = None, store_default: bool = True, whole_days: bool = False, whole_hours: bool = False, whole_minutes: bool = False, soft_default: Any = <efro.dataclassio._base.IOAttrs._MissingType object>, soft_default_factory: Union[Callable[[], Any], efro.dataclassio._base.IOAttrs._MissingType] = <efro.dataclassio._base.IOAttrs._MissingType object>)
151    def __init__(
152        self,
153        storagename: str | None = storagename,
154        store_default: bool = store_default,
155        whole_days: bool = whole_days,
156        whole_hours: bool = whole_hours,
157        whole_minutes: bool = whole_minutes,
158        soft_default: Any = MISSING,
159        soft_default_factory: Callable[[], Any] | _MissingType = MISSING,
160    ):
161        # Only store values that differ from class defaults to keep
162        # our instances nice and lean.
163        cls = type(self)
164        if storagename != cls.storagename:
165            self.storagename = storagename
166        if store_default != cls.store_default:
167            self.store_default = store_default
168        if whole_days != cls.whole_days:
169            self.whole_days = whole_days
170        if whole_hours != cls.whole_hours:
171            self.whole_hours = whole_hours
172        if whole_minutes != cls.whole_minutes:
173            self.whole_minutes = whole_minutes
174        if soft_default is not cls.soft_default:
175            # Do what dataclasses does with its default types and
176            # tell the user to use factory for mutable ones.
177            if isinstance(soft_default, (list, dict, set)):
178                raise ValueError(
179                    f'mutable {type(soft_default)} is not allowed'
180                    f' for soft_default; use soft_default_factory.'
181                )
182            self.soft_default = soft_default
183        if soft_default_factory is not cls.soft_default_factory:
184            self.soft_default_factory = soft_default_factory
185            if self.soft_default is not cls.soft_default:
186                raise ValueError(
187                    'Cannot set both soft_default and soft_default_factory'
188                )
MISSING = <efro.dataclassio._base.IOAttrs._MissingType object>
storagename: str | None = None
store_default: bool = True
whole_days: bool = False
whole_hours: bool = False
whole_minutes: bool = False
soft_default: Any = <efro.dataclassio._base.IOAttrs._MissingType object>
soft_default_factory: Union[Callable[[], Any], efro.dataclassio._base.IOAttrs._MissingType] = <efro.dataclassio._base.IOAttrs._MissingType object>
def validate_for_field(self, cls: type, field: dataclasses.Field) -> None:
190    def validate_for_field(self, cls: type, field: dataclasses.Field) -> None:
191        """Ensure the IOAttrs instance is ok to use with the provided field."""
192
193        # Turning off store_default requires the field to have either
194        # a default or a default_factory or for us to have soft equivalents.
195
196        if not self.store_default:
197            field_default_factory: Any = field.default_factory
198            if (
199                field_default_factory is dataclasses.MISSING
200                and field.default is dataclasses.MISSING
201                and self.soft_default is self.MISSING
202                and self.soft_default_factory is self.MISSING
203            ):
204                raise TypeError(
205                    f'Field {field.name} of {cls} has'
206                    f' neither a default nor a default_factory'
207                    f' and IOAttrs contains neither a soft_default'
208                    f' nor a soft_default_factory;'
209                    f' store_default=False cannot be set for it.'
210                )

Ensure the IOAttrs instance is ok to use with the provided field.

def validate_datetime(self, value: datetime.datetime, fieldpath: str) -> None:
212    def validate_datetime(
213        self, value: datetime.datetime, fieldpath: str
214    ) -> None:
215        """Ensure a datetime value meets our value requirements."""
216        if self.whole_days:
217            if any(
218                x != 0
219                for x in (
220                    value.hour,
221                    value.minute,
222                    value.second,
223                    value.microsecond,
224                )
225            ):
226                raise ValueError(
227                    f'Value {value} at {fieldpath} is not a whole day.'
228                )
229        elif self.whole_hours:
230            if any(
231                x != 0 for x in (value.minute, value.second, value.microsecond)
232            ):
233                raise ValueError(
234                    f'Value {value} at {fieldpath}' f' is not a whole hour.'
235                )
236        elif self.whole_minutes:
237            if any(x != 0 for x in (value.second, value.microsecond)):
238                raise ValueError(
239                    f'Value {value} at {fieldpath}' f' is not a whole minute.'
240                )

Ensure a datetime value meets our value requirements.

class IOExtendedData:
41class IOExtendedData:
42    """A class that data types can inherit from for extra functionality."""
43
44    def will_output(self) -> None:
45        """Called before data is sent to an outputter.
46
47        Can be overridden to validate or filter data before
48        sending it on its way.
49        """
50
51    @classmethod
52    def will_input(cls, data: dict) -> None:
53        """Called on raw data before a class instance is created from it.
54
55        Can be overridden to migrate old data formats to new, etc.
56        """
57
58    def did_input(self) -> None:
59        """Called on a class instance after created from data.
60
61        Can be useful to correct values from the db, etc. in the
62        type-safe form.
63        """

A class that data types can inherit from for extra functionality.

def will_output(self) -> None:
44    def will_output(self) -> None:
45        """Called before data is sent to an outputter.
46
47        Can be overridden to validate or filter data before
48        sending it on its way.
49        """

Called before data is sent to an outputter.

Can be overridden to validate or filter data before sending it on its way.

@classmethod
def will_input(cls, data: dict) -> None:
51    @classmethod
52    def will_input(cls, data: dict) -> None:
53        """Called on raw data before a class instance is created from it.
54
55        Can be overridden to migrate old data formats to new, etc.
56        """

Called on raw data before a class instance is created from it.

Can be overridden to migrate old data formats to new, etc.

def did_input(self) -> None:
58    def did_input(self) -> None:
59        """Called on a class instance after created from data.
60
61        Can be useful to correct values from the db, etc. in the
62        type-safe form.
63        """

Called on a class instance after created from data.

Can be useful to correct values from the db, etc. in the type-safe form.

class IOMultiType(typing.Generic[~EnumT]):
 69class IOMultiType(Generic[EnumT]):
 70    """A base class for types that can map to multiple dataclass types.
 71
 72    This enables usage of high level base classes (for example
 73    a 'Message' type) in annotations, with dataclassio automatically
 74    serializing & deserializing dataclass subclasses based on their
 75    type ('MessagePing', 'MessageChat', etc.)
 76
 77    Standard usage involves creating a class which inherits from this
 78    one which acts as a 'registry', and then creating dataclass classes
 79    inheriting from that registry class. Dataclassio will then do the
 80    right thing when that registry class is used in type annotations.
 81
 82    See tests/test_efro/test_dataclassio.py for examples.
 83    """
 84
 85    # Dataclasses inheriting from an IOMultiType will store a type-id
 86    # with this key in their serialized data. This value can be
 87    # overridden in IOMultiType subclasses as desired.
 88    ID_STORAGE_NAME = '_dciotype'
 89
 90    @classmethod
 91    def get_type(cls, type_id: EnumT) -> type[Self]:
 92        """Return a specific subclass given a type-id."""
 93        raise NotImplementedError()
 94
 95    @classmethod
 96    def get_type_id(cls) -> EnumT:
 97        """Return the type-id for this subclass."""
 98        raise NotImplementedError()
 99
100    @classmethod
101    def get_type_id_type(cls) -> type[EnumT]:
102        """Return the Enum type this class uses as its type-id."""
103        out: type[EnumT] = cls.__orig_bases__[0].__args__[0]  # type: ignore
104        assert issubclass(out, Enum)
105        return out

A base class for types that can map to multiple dataclass types.

This enables usage of high level base classes (for example a 'Message' type) in annotations, with dataclassio automatically serializing & deserializing dataclass subclasses based on their type ('MessagePing', 'MessageChat', etc.)

Standard usage involves creating a class which inherits from this one which acts as a 'registry', and then creating dataclass classes inheriting from that registry class. Dataclassio will then do the right thing when that registry class is used in type annotations.

See tests/test_efro/test_dataclassio.py for examples.

ID_STORAGE_NAME = '_dciotype'
@classmethod
def get_type(cls, type_id: ~EnumT) -> type[typing.Self]:
90    @classmethod
91    def get_type(cls, type_id: EnumT) -> type[Self]:
92        """Return a specific subclass given a type-id."""
93        raise NotImplementedError()

Return a specific subclass given a type-id.

@classmethod
def get_type_id(cls) -> ~EnumT:
95    @classmethod
96    def get_type_id(cls) -> EnumT:
97        """Return the type-id for this subclass."""
98        raise NotImplementedError()

Return the type-id for this subclass.

@classmethod
def get_type_id_type(cls) -> type[~EnumT]:
100    @classmethod
101    def get_type_id_type(cls) -> type[EnumT]:
102        """Return the Enum type this class uses as its type-id."""
103        out: type[EnumT] = cls.__orig_bases__[0].__args__[0]  # type: ignore
104        assert issubclass(out, Enum)
105        return out

Return the Enum type this class uses as its type-id.

class JsonStyle(enum.Enum):
27class JsonStyle(Enum):
28    """Different style types for json."""
29
30    # Single line, no spaces, no sorting. Not deterministic.
31    # Use this where speed is more important than determinism.
32    FAST = 'fast'
33
34    # Single line, no spaces, sorted keys. Deterministic.
35    # Use this when output may be hashed or compared for equality.
36    SORTED = 'sorted'
37
38    # Multiple lines, spaces, sorted keys. Deterministic.
39    # Use this for pretty human readable output.
40    PRETTY = 'pretty'

Different style types for json.

FAST = <JsonStyle.FAST: 'fast'>
SORTED = <JsonStyle.SORTED: 'sorted'>
PRETTY = <JsonStyle.PRETTY: 'pretty'>
Inherited Members
enum.Enum
name
value
def dataclass_from_dict( cls: type[~T], values: dict, codec: Codec = <Codec.JSON: 'json'>, coerce_to_float: bool = True, allow_unknown_attrs: bool = True, discard_unknown_attrs: bool = False) -> ~T:
 95def dataclass_from_dict(
 96    cls: type[T],
 97    values: dict,
 98    codec: Codec = Codec.JSON,
 99    coerce_to_float: bool = True,
100    allow_unknown_attrs: bool = True,
101    discard_unknown_attrs: bool = False,
102) -> T:
103    """Given a dict, return a dataclass of a given type.
104
105    The dict must be formatted to match the specified codec (generally
106    json-friendly object types). This means that sequence values such as
107    tuples or sets should be passed as lists, enums should be passed as
108    their associated values, nested dataclasses should be passed as dicts,
109    etc.
110
111    All values are checked to ensure their types/values are valid.
112
113    Data for attributes of type Any will be checked to ensure they match
114    types supported directly by json. This does not include types such
115    as tuples which are implicitly translated by Python's json module
116    (as this would break the ability to do a lossless round-trip with
117    data).
118
119    If coerce_to_float is True, int values passed for float typed fields
120    will be converted to float values. Otherwise, a TypeError is raised.
121
122    If `allow_unknown_attrs` is False, AttributeErrors will be raised for
123    attributes present in the dict but not on the data class. Otherwise,
124    they will be preserved as part of the instance and included if it is
125    exported back to a dict, unless `discard_unknown_attrs` is True, in
126    which case they will simply be discarded.
127    """
128    val = _Inputter(
129        cls,
130        codec=codec,
131        coerce_to_float=coerce_to_float,
132        allow_unknown_attrs=allow_unknown_attrs,
133        discard_unknown_attrs=discard_unknown_attrs,
134    ).run(values)
135    assert isinstance(val, cls)
136    return val

Given a dict, return a dataclass of a given type.

The dict must be formatted to match the specified codec (generally json-friendly object types). This means that sequence values such as tuples or sets should be passed as lists, enums should be passed as their associated values, nested dataclasses should be passed as dicts, etc.

All values are checked to ensure their types/values are valid.

Data for attributes of type Any will be checked to ensure they match types supported directly by json. This does not include types such as tuples which are implicitly translated by Python's json module (as this would break the ability to do a lossless round-trip with data).

If coerce_to_float is True, int values passed for float typed fields will be converted to float values. Otherwise, a TypeError is raised.

If allow_unknown_attrs is False, AttributeErrors will be raised for attributes present in the dict but not on the data class. Otherwise, they will be preserved as part of the instance and included if it is exported back to a dict, unless discard_unknown_attrs is True, in which case they will simply be discarded.

def dataclass_from_json( cls: type[~T], json_str: str, coerce_to_float: bool = True, allow_unknown_attrs: bool = True, discard_unknown_attrs: bool = False) -> ~T:
139def dataclass_from_json(
140    cls: type[T],
141    json_str: str,
142    coerce_to_float: bool = True,
143    allow_unknown_attrs: bool = True,
144    discard_unknown_attrs: bool = False,
145) -> T:
146    """Utility function; return a dataclass instance given a json string.
147
148    Basically dataclass_from_dict(json.loads(...))
149    """
150    import json
151
152    return dataclass_from_dict(
153        cls=cls,
154        values=json.loads(json_str),
155        coerce_to_float=coerce_to_float,
156        allow_unknown_attrs=allow_unknown_attrs,
157        discard_unknown_attrs=discard_unknown_attrs,
158    )

Utility function; return a dataclass instance given a json string.

Basically dataclass_from_dict(json.loads(...))

def dataclass_to_dict( obj: Any, codec: Codec = <Codec.JSON: 'json'>, coerce_to_float: bool = True) -> dict:
43def dataclass_to_dict(
44    obj: Any,
45    codec: Codec = Codec.JSON,
46    coerce_to_float: bool = True,
47) -> dict:
48    """Given a dataclass object, return a json-friendly dict.
49
50    All values will be checked to ensure they match the types specified
51    on fields. Note that a limited set of types and data configurations is
52    supported.
53
54    Values with type Any will be checked to ensure they match types supported
55    directly by json. This does not include types such as tuples which are
56    implicitly translated by Python's json module (as this would break
57    the ability to do a lossless round-trip with data).
58
59    If coerce_to_float is True, integer values present on float typed fields
60    will be converted to float in the dict output. If False, a TypeError
61    will be triggered.
62    """
63
64    out = _Outputter(
65        obj, create=True, codec=codec, coerce_to_float=coerce_to_float
66    ).run()
67    assert isinstance(out, dict)
68    return out

Given a dataclass object, return a json-friendly dict.

All values will be checked to ensure they match the types specified on fields. Note that a limited set of types and data configurations is supported.

Values with type Any will be checked to ensure they match types supported directly by json. This does not include types such as tuples which are implicitly translated by Python's json module (as this would break the ability to do a lossless round-trip with data).

If coerce_to_float is True, integer values present on float typed fields will be converted to float in the dict output. If False, a TypeError will be triggered.

def dataclass_to_json( obj: Any, coerce_to_float: bool = True, pretty: bool = False, sort_keys: bool | None = None) -> str:
71def dataclass_to_json(
72    obj: Any,
73    coerce_to_float: bool = True,
74    pretty: bool = False,
75    sort_keys: bool | None = None,
76) -> str:
77    """Utility function; return a json string from a dataclass instance.
78
79    Basically json.dumps(dataclass_to_dict(...)).
80    By default, keys are sorted for pretty output and not otherwise, but
81    this can be overridden by supplying a value for the 'sort_keys' arg.
82    """
83    import json
84
85    jdict = dataclass_to_dict(
86        obj=obj, coerce_to_float=coerce_to_float, codec=Codec.JSON
87    )
88    if sort_keys is None:
89        sort_keys = pretty
90    if pretty:
91        return json.dumps(jdict, indent=2, sort_keys=sort_keys)
92    return json.dumps(jdict, separators=(',', ':'), sort_keys=sort_keys)

Utility function; return a json string from a dataclass instance.

Basically json.dumps(dataclass_to_dict(...)). By default, keys are sorted for pretty output and not otherwise, but this can be overridden by supplying a value for the 'sort_keys' arg.

def dataclass_validate( obj: Any, coerce_to_float: bool = True, codec: Codec = <Codec.JSON: 'json'>) -> None:
161def dataclass_validate(
162    obj: Any, coerce_to_float: bool = True, codec: Codec = Codec.JSON
163) -> None:
164    """Ensure that values in a dataclass instance are the correct types."""
165
166    # Simply run an output pass but tell it not to generate data;
167    # only run validation.
168    _Outputter(
169        obj, create=False, codec=codec, coerce_to_float=coerce_to_float
170    ).run()

Ensure that values in a dataclass instance are the correct types.

def ioprep(cls: type, globalns: dict | None = None) -> None:
46def ioprep(cls: type, globalns: dict | None = None) -> None:
47    """Prep a dataclass type for use with this module's functionality.
48
49    Prepping ensures that all types contained in a data class as well as
50    the usage of said types are supported by this module and pre-builds
51    necessary constructs needed for encoding/decoding/etc.
52
53    Prepping will happen on-the-fly as needed, but a warning will be
54    emitted in such cases, as it is better to explicitly prep all used types
55    early in a process to ensure any invalid types or configuration are caught
56    immediately.
57
58    Prepping a dataclass involves evaluating its type annotations, which,
59    as of PEP 563, are stored simply as strings. This evaluation is done
60    with localns set to the class dict (so that types defined in the class
61    can be used) and globalns set to the containing module's class.
62    It is possible to override globalns for special cases such as when
63    prepping happens as part of an execed string instead of within a
64    module.
65    """
66    PrepSession(explicit=True, globalns=globalns).prep_dataclass(
67        cls, recursion_level=0
68    )

Prep a dataclass type for use with this module's functionality.

Prepping ensures that all types contained in a data class as well as the usage of said types are supported by this module and pre-builds necessary constructs needed for encoding/decoding/etc.

Prepping will happen on-the-fly as needed, but a warning will be emitted in such cases, as it is better to explicitly prep all used types early in a process to ensure any invalid types or configuration are caught immediately.

Prepping a dataclass involves evaluating its type annotations, which, as of PEP 563, are stored simply as strings. This evaluation is done with localns set to the class dict (so that types defined in the class can be used) and globalns set to the containing module's class. It is possible to override globalns for special cases such as when prepping happens as part of an execed string instead of within a module.

def ioprepped(cls: type[~T]) -> type[~T]:
71def ioprepped(cls: type[T]) -> type[T]:
72    """Class decorator for easily prepping a dataclass at definition time.
73
74    Note that in some cases it may not be possible to prep a dataclass
75    immediately (such as when its type annotations refer to forward-declared
76    types). In these cases, dataclass_prep() should be explicitly called for
77    the class as soon as possible; ideally at module import time to expose any
78    errors as early as possible in execution.
79    """
80    ioprep(cls)
81    return cls

Class decorator for easily prepping a dataclass at definition time.

Note that in some cases it may not be possible to prep a dataclass immediately (such as when its type annotations refer to forward-declared types). In these cases, dataclass_prep() should be explicitly called for the class as soon as possible; ideally at module import time to expose any errors as early as possible in execution.

def is_ioprepped_dataclass(obj: Any) -> bool:
101def is_ioprepped_dataclass(obj: Any) -> bool:
102    """Return whether the obj is an ioprepped dataclass type or instance."""
103    cls = obj if isinstance(obj, type) else type(obj)
104    return dataclasses.is_dataclass(cls) and hasattr(cls, PREP_ATTR)

Return whether the obj is an ioprepped dataclass type or instance.

def will_ioprep(cls: type[~T]) -> type[~T]:
84def will_ioprep(cls: type[T]) -> type[T]:
85    """Class decorator hinting that we will prep a class later.
86
87    In some cases (such as recursive types) we cannot use the @ioprepped
88    decorator and must instead call ioprep() explicitly later. However,
89    some of our custom pylint checking behaves differently when the
90    @ioprepped decorator is present, in that case requiring type annotations
91    to be present and not simply forward declared under an "if TYPE_CHECKING"
92    block. (since they are used at runtime).
93
94    The @will_ioprep decorator triggers the same pylint behavior
95    differences as @ioprepped (which are necessary for the later ioprep() call
96    to work correctly) but without actually running any prep itself.
97    """
98    return cls

Class decorator hinting that we will prep a class later.

In some cases (such as recursive types) we cannot use the @ioprepped decorator and must instead call ioprep() explicitly later. However, some of our custom pylint checking behaves differently when the @ioprepped decorator is present, in that case requiring type annotations to be present and not simply forward declared under an "if TYPE_CHECKING" block. (since they are used at runtime).

The @will_ioprep decorator triggers the same pylint behavior differences as @ioprepped (which are necessary for the later ioprep() call to work correctly) but without actually running any prep itself.