utils

Various utility functions and classes.

MissingRequiredFieldError

Bases: ValueError

Error type for a missing required field.

Source code in fancy_dataclass/utils.py

class MissingRequiredFieldError(ValueError):
    """Error type for a missing required field."""

    def __init__(self, name: str, alias: Optional[str] = None) -> None:
        """Constructor for `MissingRequiredFieldError`.

        Args:
            name: name of the missing field
            alias: alias of the missing field (e.g. when converting a JSON key)"""
        self.name = name
        self.alias = alias
        msg = f'{self.name!r} field'
        if alias:
            msg += f' (alias {alias!r})'
        msg += ' is required'
        super().__init__(msg)

__init__(name, alias=None)

Constructor for MissingRequiredFieldError.

Parameters:

Name	Type	Description	Default
name	str	name of the missing field	required
alias	Optional[str]	alias of the missing field (e.g. when converting a JSON key)	None

Source code in fancy_dataclass/utils.py

def __init__(self, name: str, alias: Optional[str] = None) -> None:
    """Constructor for `MissingRequiredFieldError`.

    Args:
        name: name of the missing field
        alias: alias of the missing field (e.g. when converting a JSON key)"""
    self.name = name
    self.alias = alias
    msg = f'{self.name!r} field'
    if alias:
        msg += f' (alias {alias!r})'
    msg += ' is required'
    super().__init__(msg)

TypeConversionError

Bases: ValueError

Error type for type conversion.

Source code in fancy_dataclass/utils.py

class TypeConversionError(ValueError):
    """Error type for type conversion."""

    def __init__(self, tp: type, val: Any) -> None:
        """Constructor for `TypeConversionError`.

        Args:
            tp: type to convert to
            val: value to convert"""
        self.tp = tp
        self.val = val
        tp_name = re.sub("'>$", '', re.sub(r"^<\w+ '", '', str(tp)))
        super().__init__(f'could not convert {val!r} to type {tp_name!r}')

__init__(tp, val)

Constructor for TypeConversionError.

Parameters:

Name	Type	Description	Default
tp	type	type to convert to	required
val	Any	value to convert	required

Source code in fancy_dataclass/utils.py

def __init__(self, tp: type, val: Any) -> None:
    """Constructor for `TypeConversionError`.

    Args:
        tp: type to convert to
        val: value to convert"""
    self.tp = tp
    self.val = val
    tp_name = re.sub("'>$", '', re.sub(r"^<\w+ '", '', str(tp)))
    super().__init__(f'could not convert {val!r} to type {tp_name!r}')

all_subclasses(cls)

Gets all subclasses of a given class, including the class itself.

Parameters:

Name	Type	Description	Default
cls	Type[T]	Input class	required

Returns:

Type	Description
List[Type[T]]	List of subclasses of the input class

Source code in fancy_dataclass/utils.py

def all_subclasses(cls: Type[T]) -> List[Type[T]]:
    """Gets all subclasses of a given class, including the class itself.

    Args:
        cls: Input class

    Returns:
        List of subclasses of the input class"""
    subclasses = [cls]
    for subcls in cls.__subclasses__():
        subclasses += all_subclasses(subcls)
    # for some arcane reason, we need to resolve the ids of the classes to prevent strange behavior
    [id(subcls) for subcls in subclasses]
    return subclasses

camel_case_to_kebab_case(name)

Converts a string from camel case to kebab case.

Parameters:

Name	Type	Description	Default
name	str	String to convert	required

Returns:

Type	Description
str	Kebab case version of the string

Source code in fancy_dataclass/utils.py

def camel_case_to_kebab_case(name: str) -> str:
    """Converts a string from camel case to kebab case.

    Args:
        name: String to convert

    Returns:
        Kebab case version of the string"""
    segs = []
    n = len(name)
    name = name.replace('_', '-')
    for (i, c) in enumerate(name):
        if c.isupper():
            if ((i < n - 1) and name[i + 1].islower()) or ((i > 0) and (name[i - 1].islower())):
                segs.append('-' + c.lower())
            else:
                segs.append(c.lower())
        else:
            segs.append(c)
    return ''.join(segs).lstrip('-')

check_dataclass(cls)

Checks whether a given type is a dataclass, raising a TypeError otherwise.

Parameters:

Name	Type	Description	Default
cls	type	A Python type	required

Raises:

Type	Description
TypeError	If the given type is not a dataclass

Source code in fancy_dataclass/utils.py

def check_dataclass(cls: type) -> TypeGuard[Type['DataclassInstance']]:
    """Checks whether a given type is a dataclass, raising a `TypeError` otherwise.

    Args:
        cls: A Python type

    Raises:
        TypeError: If the given type is not a dataclass"""
    if not is_dataclass(cls):
        raise TypeError(f'{cls.__name__} is not a dataclass')
    return True

coerce_to_dataclass(cls, obj)

Coerces the fields from an arbitrary object to an instance of a dataclass type.

Any missing attributes will be set to the dataclass's default values.

Parameters:

Name	Type	Description	Default
cls	Type[T]	Target dataclass type	required
obj	object	Object to coerce	required

Returns:

Type	Description
T	A new object of the desired type, coerced from the input object

Source code in fancy_dataclass/utils.py

def coerce_to_dataclass(cls: Type[T], obj: object) -> T:
    """Coerces the fields from an arbitrary object to an instance of a dataclass type.

    Any missing attributes will be set to the dataclass's default values.

    Args:
        cls: Target dataclass type
        obj: Object to coerce

    Returns:
        A new object of the desired type, coerced from the input object"""
    kwargs = {}
    for fld in dataclasses.fields(cls):  # type: ignore[arg-type]
        if hasattr(obj, fld.name):
            val = getattr(obj, fld.name)
            if is_dataclass_type(fld.type):  # type: ignore[arg-type]
                val = coerce_to_dataclass(fld.type, val)
            else:
                origin_type = get_origin(fld.type)
                if origin_type and issubclass_safe(origin_type, Iterable):
                    if issubclass(origin_type, dict):
                        (_, val_type) = get_args(fld.type)
                        if is_dataclass_type(val_type):
                            val = type(val)({key: coerce_to_dataclass(val_type, elt) for (key, elt) in val.items()})
                    elif issubclass(origin_type, tuple):
                        val = type(val)(coerce_to_dataclass(tp, elt) if is_dataclass_type(tp) else elt for (tp, elt) in zip(get_args(fld.type), val))
                    else:
                        (elt_type,) = get_args(fld.type)
                        if is_dataclass_type(elt_type):
                            val = type(val)(coerce_to_dataclass(elt_type, elt) for elt in val)
            kwargs[fld.name] = val
    return cls(**kwargs)

dataclass_field_type(cls, name)

Given a dataclass type and field name, gets the dataclass field's type annotation.

If the annotation is a string, resolves it to a type (see PEP 563, 649).

Parameters:

Name	Type	Description	Default
cls	Type[DataclassInstance]	Dataclass type	required
name	str	Name of field	required

Returns:

Type	Description
type	Fully evaluated type

Source code in fancy_dataclass/utils.py

def dataclass_field_type(cls: Type['DataclassInstance'], name: str) -> type:
    """Given a dataclass type and field name, gets the dataclass field's type annotation.

    If the annotation is a string, resolves it to a type (see PEP 563, 649).

    Args:
        cls: Dataclass type
        name: Name of field

    Returns:
        Fully evaluated type"""
    try:
        return cast(type, get_type_hints(cls)[name])
    except NameError:  # try to resolve string annotation manually
        field_type_str = cls.__annotations__[name]
        assert isinstance(field_type_str, str)
        return eval_type_str(field_type_str)

dataclass_kw_only(**kwargs)

Identical to the usual dataclass decorator, but adds kw_only=True (if Python version is >= 3.10).

Source code in fancy_dataclass/utils.py

@dataclass_transform(kw_only_default=True)
def dataclass_kw_only(**kwargs: Any) -> Callable[[Type[T]], Type[T]]:
    """Identical to the usual dataclass decorator, but adds kw_only=True (if Python version is >= 3.10)."""
    # TODO: remove this once we no longer support < 3.10
    if sys.version_info[:2] >= (3, 10):
        return partial(dataclass, kw_only=True)
    return dataclass

dataclass_type_map(cls, func)

Applies a type function to all dataclass field types, recursively through container types.

Parameters:

Name	Type	Description	Default
cls	Type[DataclassInstance]	Target dataclass type to manipulate	required
func	Callable[[type], type]	Function to map onto basic (non-container) field types	required

Returns:

Type	Description
Type[DataclassInstance]	A new dataclass type whose field types have been mapped by the function

Source code in fancy_dataclass/utils.py

def dataclass_type_map(cls: Type['DataclassInstance'], func: Callable[[type], type]) -> Type['DataclassInstance']:
    """Applies a type function to all dataclass field types, recursively through container types.

    Args:
        cls: Target dataclass type to manipulate
        func: Function to map onto basic (non-container) field types

    Returns:
        A new dataclass type whose field types have been mapped by the function"""
    def _map_func(tp: type) -> type:
        return func(dataclass_type_map(tp, func)) if is_dataclass(tp) else func(tp)
    # for Py3.8 compatibility, can only subscript typing classes
    container_type_map: Dict[type, type] = {dict: Dict, tuple: Tuple, list: List}  # type: ignore[dict-item]
    field_data = []
    for fld in get_dataclass_fields(cls, include_all=True):
        new_fld = copy(fld)
        origin_type = get_origin(fld.type)
        if origin_type and (not _is_instance(fld.type, _AnnotatedAlias)) and issubclass_safe(origin_type, Iterable):
            otype = container_type_map.get(origin_type, origin_type)
            if issubclass(origin_type, dict):
                (key_type, val_type) = get_args(fld.type)
                tp = otype[key_type, _map_func(val_type)]
            elif issubclass(origin_type, tuple):
                tp = otype[tuple([_map_func(elt_type) for elt_type in get_args(fld.type)])]
            else:
                (elt_type,) = get_args(fld.type)
                tp = otype[_map_func(elt_type)]
        else:
            tp = _map_func(fld.type)  # type: ignore[arg-type]
        field_data.append((fld.name, tp, new_fld))
    return make_dataclass(cls.__name__, field_data, bases=cls.__bases__, namespace=dict(cls.__dict__))

eval_type_str(type_str)

Gets the fully-evaluated type from a "stringized" type.

Parameters:

Name	Type	Description	Default
type_str	str	String representing a type	required

Returns:

Type	Description
type	Fully evaluated type

Source code in fancy_dataclass/utils.py

def eval_type_str(type_str: str) -> type:
    """Gets the fully-evaluated type from a "stringized" type.

    Args:
        type_str: String representing a type

    Returns:
        Fully evaluated type"""
    # TODO: this may become obsolete once PEP 649 becomes available
    # see: https://peps.python.org/pep-0649
    tp = None
    if '.' in type_str:  # fully qualified: import module and retrieve the type
        with suppress(ModuleNotFoundError):
            tp = get_object_from_fully_qualified_name(type_str)
    # otherwise, a builtin type, locally defined type, or type with complex annotations
    if tp is None:
        # since names from typing/typing_extensions are common, we import all the names
        globs = {}
        for mod_name in ['typing_extensions', 'typing']:
            mod = importlib.import_module(mod_name)
            globs[mod_name] = mod
            globs.update(mod.__dict__)
        globs.update(globals())
        try:
            tp = eval(type_str, globs)
        except NameError:
            # NOTE: globals do not get carried from up the stack.
            # Some names may be missing, so we include them here.
            globs = {**_get_all_stack_variables(), **globs}
            tp = eval(type_str, globs)
    return cast(type, tp)

fully_qualified_class_name(cls)

Gets the fully qualified name of a class (including full module path and class name).

Parameters:

Name	Type	Description	Default
cls	type	A Python class	required

Returns:

Type	Description
str	Fully qualified name of the class

Source code in fancy_dataclass/utils.py

def fully_qualified_class_name(cls: type) -> str:
    """Gets the fully qualified name of a class (including full module path and class name).

    Args:
        cls: A Python class

    Returns:
        Fully qualified name of the class"""
    return f'{cls.__module__}.{cls.__qualname__}'

get_annotations(cls)

Given a type, gets a dict mapping from field names to types.

Source code in fancy_dataclass/utils.py

def get_annotations(cls: type) -> Dict[str, Any]:
    """Given a type, gets a dict mapping from field names to types."""
    anns: Dict[str, Any] = {}
    for tp in cls.mro()[::-1]:
        anns.update(getattr(tp, '__annotations__', {}))
    return anns

get_dataclass_fields(obj, include_all=False)

Variant of dataclasses.fields which can optionally include ClassVars and InitVars.

Parameters:

Name	Type	Description	Default
obj	Union[type, object]	Python class or object	required
include_all	bool	Whether to include ClassVar and InitVar fields	False

Returns:

Type	Description
Tuple[Field, ...]	Tuple of dataclasses.Field objects for the dataclass

Source code in fancy_dataclass/utils.py

def get_dataclass_fields(obj: Union[type, object], include_all: bool = False) -> Tuple[Field, ...]:  # type: ignore[type-arg]
    """Variant of `dataclasses.fields` which can optionally include ClassVars and InitVars.

    Args:
        obj: Python class or object
        include_all: Whether to include `ClassVar` and `InitVar` fields

    Returns:
        Tuple of `dataclasses.Field` objects for the dataclass"""
    if include_all:
        try:
            return tuple(obj.__dataclass_fields__.values())  # type: ignore[union-attr]
        except AttributeError:
            raise TypeError('must be called with a dataclass type or instance') from None
    return dataclasses.fields(obj)  # type: ignore[arg-type]

get_object_from_fully_qualified_name(name)

Given a fully-qualified name of some object, gets the object, importing the module as needed.

Parameters:

Name	Type	Description	Default
name	str	Fully qualified object name	required

Returns:

Type	Description
object	Object with the fully qualified name

Raises:

Type	Description
ValueError	If the name does not have a . character

Source code in fancy_dataclass/utils.py

def get_object_from_fully_qualified_name(name: str) -> object:
    """Given a fully-qualified name of some object, gets the object, importing the module as needed.

    Args:
        name: Fully qualified object name

    Returns:
        Object with the fully qualified name

    Raises:
        ValueError: If the name does not have a . character"""
    if '.' not in name:
        raise ValueError(f'{name!r} is not a fully qualified name')
    toks = name.split('.')
    mod_name, obj_name = '.'.join(toks[:-1]), toks[-1]
    mod = importlib.import_module(mod_name)
    return getattr(mod, obj_name)

get_subclass_with_name(cls, name)

Gets the subclass of a class with the given name.

Parameters:

Name	Type	Description	Default
cls	Type[T]	A Python class	required
name	str	Name of the subclass	required

Returns:

Type	Description
Type[T]	Subclass of cls with the given name

Raises:

Type	Description
ValueError	If no subclass with the given name exists

Source code in fancy_dataclass/utils.py

def get_subclass_with_name(cls: Type[T], name: str) -> Type[T]:
    """Gets the subclass of a class with the given name.

    Args:
        cls: A Python class
        name: Name of the subclass

    Returns:
        Subclass of `cls` with the given name

    Raises:
        ValueError: If no subclass with the given name exists"""
    fully_qualified = '.' in name
    cls_name = fully_qualified_class_name(cls) if fully_qualified else cls.__name__
    if cls_name == name:
        return cls
    if fully_qualified:  # import the module
        _ = get_object_from_fully_qualified_name(name)
    for subcls in all_subclasses(cls):
        subcls_name = fully_qualified_class_name(subcls) if fully_qualified else subcls.__name__
        if subcls_name == name:
            return subcls
    else:
        raise ValueError(f'{name} is not a known subclass of {cls.__name__}')

is_dataclass_type(cls)

Returns True if the given type is a dataclass.

Parameters:

Name	Type	Description	Default
cls	type	A Python type	required

Returns:

Type	Description
TypeGuard[Type[DataclassInstance]]	True if cls is a dataclass

Source code in fancy_dataclass/utils.py

def is_dataclass_type(cls: type) -> TypeGuard[Type['DataclassInstance']]:
    """Returns True if the given type is a dataclass.

    Args:
        cls: A Python type

    Returns:
        True if `cls` is a dataclass"""
    return is_dataclass(cls)

issubclass_safe(type1, type2)

Calls issubclass(type1, type2), returning False if an error occurs.

Parameters:

Name	Type	Description	Default
type1	type	First type	required
type2	type	Second type	required

Returns:

Type	Description
bool	True if type1 is a subclass of type2

Raises:

Type	Description
TypeError	If type1 is something like a GenericAlias

Source code in fancy_dataclass/utils.py

def issubclass_safe(type1: type, type2: type) -> bool:
    """Calls `issubclass(type1, type2)`, returning `False` if an error occurs.

    Args:
        type1: First type
        type2: Second type

    Returns:
        `True` if `type1` is a subclass of `type2`

    Raises:
        TypeError: If `type1` is something like a `GenericAlias`"""
    try:
        return issubclass(type1, type2)
    except TypeError:
        return False

merge_dataclasses(*classes, cls_name='_', bases=None, allow_duplicates=False)

Merges multiple dataclasses together into a single dataclass whose fields have been combined. This preserves ClassVars but does not recursively merge subfields.

Parameters:

Name	Type	Description	Default
classes	type	Multiple dataclass types	()
cls_name	str	Name of the output dataclass	'_'
bases	Optional[Tuple[type, ...]]	Base classes for the new type	None
allow_duplicates	bool	Whether to allow duplicate field names	False

Returns:

Type	Description
type	The merged dataclass type

Raises:

Type	Description
TypeError	If there are any duplicate field names

Source code in fancy_dataclass/utils.py

def merge_dataclasses(*classes: type, cls_name: str = '_', bases: Optional[Tuple[type, ...]] = None, allow_duplicates: bool = False) -> type:
    """Merges multiple dataclasses together into a single dataclass whose fields have been combined.
    This preserves `ClassVar`s but does not recursively merge subfields.

    Args:
        classes: Multiple dataclass types
        cls_name: Name of the output dataclass
        bases: Base classes for the new type
        allow_duplicates: Whether to allow duplicate field names

    Returns:
        The merged dataclass type

    Raises:
        TypeError: If there are any duplicate field names"""
    # remove any parent classes (NOTE: this is quadratic in the number of classes)
    # this can prevent 'Cannot create a consistent method resolution order' errors among base classes
    filtered_classes = []
    for cls1 in classes:
        if all((cls2 is cls1) or (not issubclass(cls2, cls1)) for cls2 in classes):
            filtered_classes.append(cls1)
    classes = tuple(filtered_classes)
    flds = []
    field_type_map: Dict[str, type] = {}
    base_map: Dict[str, type] = {}
    @lru_cache
    def _get_field_names(tp: type) -> Set[str]:
        return {fld.name for fld in get_dataclass_fields(tp, include_all=True)}
    def _base_type_with_field(cls: type, name: str) -> type:
        for tp in cls.mro()[::-1]:
            with suppress(TypeError):
                if name in _get_field_names(tp):
                    return tp
        raise TypeError(f'no field named {name!r} for {cls}')
    for cls in classes:
        for fld in get_dataclass_fields(cls, include_all=True):
            base = _base_type_with_field(cls, fld.name)
            if fld.name in field_type_map:
                if allow_duplicates:
                    tp = dataclass_field_type(cls, fld.name)
                    if _is_subtype(field_type_map[fld.name], tp):
                        continue
                    if _is_subtype(tp, field_type_map[fld.name]):
                        field_type_map[fld.name] = tp
                        continue
                    raise TypeError(f'duplicate field name {fld.name!r} with mismatched types')
                # allow duplicate field if it came from the same ancestor class
                if base != base_map[fld.name]:
                    raise TypeError(f'duplicate field name {fld.name!r}')
            else:
                field_type_map[fld.name] = cast(type, fld.type)
                base_map[fld.name] = base
                flds.append((fld.name, fld.type, fld))
    # if bases are unspecified, use the original classes
    bases = classes if (bases is None) else bases
    cls = make_dataclass(cls_name, flds, bases=bases)
    # field ordering may get rearranged by make_dataclass (processes fields in reverse MRO order),
    # so we revert them back to their canonical ordering
    cls.__dataclass_fields__ = {name: cls.__dataclass_fields__[name] for (name, _, _) in flds}  # type: ignore[attr-defined]
    return cls

obj_class_name(obj)

Gets the name of the class of an object.

Parameters:

Name	Type	Description	Default
obj	object	A Python object	required

Returns:

Type	Description
str	Name of the object's class

Source code in fancy_dataclass/utils.py

def obj_class_name(obj: object) -> str:
    """Gets the name of the class of an object.

    Args:
        obj: A Python object

    Returns:
        Name of the object's class"""
    return obj.__class__.__name__

safe_dict_update(d1, d2)

Updates the first dict with the second, in-place.

Parameters:

Name	Type	Description	Default
d1	Dict[str, Any]	First dict, to be updated	required
d2	Dict[str, Any]	Second dict	required

Raises:

Type	Description
ValueError	If any dict keys overlap

Source code in fancy_dataclass/utils.py

def safe_dict_update(d1: Dict[str, Any], d2: Dict[str, Any]) -> None:
    """Updates the first dict with the second, in-place.

    Args:
        d1: First dict, to be updated
        d2: Second dict

    Raises:
        ValueError: If any dict keys overlap"""
    for (key, val) in d2.items():
        if key in d1:
            raise ValueError(f'duplicate key {key!r}')
        d1[key] = val

snake_case_to_camel_case(name)

Converts a string from snake case to camel case.

Parameters:

Name	Type	Description	Default
name	str	String to convert	required

Returns:

Type	Description
str	Camel case version of the string

Source code in fancy_dataclass/utils.py

def snake_case_to_camel_case(name: str) -> str:
    """Converts a string from snake case to camel case.

    Args:
        name: String to convert

    Returns:
        Camel case version of the string"""
    capitalize = lambda s: (s[0].upper() + s[1:]) if s else ''
    return ''.join(map(capitalize, name.split('_')))

type_is_optional(tp)

Determines if a type is an Optional type.

Parameters:

Name	Type	Description	Default
tp	type	Type to check	required

Returns:

Type	Description
bool	True if the type is Optional

Source code in fancy_dataclass/utils.py

def type_is_optional(tp: type) -> bool:
    """Determines if a type is an Optional type.

    Args:
        tp: Type to check

    Returns:
        True if the type is Optional"""
    origin_type = get_origin(tp)
    args = get_args(tp)
    union_types: List[Any] = [Union]
    if hasattr(types, 'UnionType'):  # Python >= 3.10
        union_types.append(types.UnionType)  # novermin
    return (origin_type in union_types) and (type(None) in args)

type_is_union(tp)

Determines if a type is a Union type.

Parameters:

Name	Type	Description	Default
tp	type	Type to check	required

Returns:

Type	Description
bool	True if the type is a Union

Source code in fancy_dataclass/utils.py

def type_is_union(tp: type) -> bool:
    """Determines if a type is a Union type.

    Args:
        tp: Type to check

    Returns:
        True if the type is a Union"""
    origin_type = get_origin(tp)
    return origin_type in _UNION_TYPES