utils
Various utility functions and classes.
DataclassConverter
dataclass
Bases: Generic[T, U]
Class for converting values from one dataclass type to another.
Source code in fancy_dataclass/utils.py
TypeConversionError
Bases: ValueError
Error type for type conversion.
Source code in fancy_dataclass/utils.py
__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
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
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
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
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
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
get_dataclass_fields(obj, include_classvars=False)
Variant of dataclasses.fields
which can optionally include ClassVars.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
obj |
Union[type, object]
|
Python class or object |
required |
include_classvars |
bool
|
Whether to include |
False
|
Returns:
Type | Description |
---|---|
Tuple[Field, ...]
|
Tuple of |
Source code in fancy_dataclass/utils.py
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 |
Raises:
Type | Description |
---|---|
ValueError
|
If no subclass with the given name exists |
Source code in fancy_dataclass/utils.py
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
|
|
Raises:
Type | Description |
---|---|
TypeError
|
If |
Source code in fancy_dataclass/utils.py
make_dataclass_with_constructors(cls_name, fields, constructors, **kwargs)
Type factory for dataclasses with custom constructors.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
cls_name |
str
|
Name of the dataclass type |
required |
fields |
Sequence[Union[str, Tuple[str, type]]]
|
List of field names, or pairs of field names and types |
required |
constructors |
Sequence[Constructor]
|
List of one-argument constructors for each field |
required |
kwargs |
Any
|
Additional keyword arguments to pass to |
{}
|
Returns:
Type | Description |
---|---|
Type[DataclassInstance]
|
A dataclass type with the given fields and constructors |
Source code in fancy_dataclass/utils.py
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 ClassVar
s 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
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 |
safe_dict_insert(d, key, val)
Inserts a (key, value) pair into a dict, if the key is not already present.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
d |
Dict[Any, Any]
|
Dict to modify |
required |
key |
str
|
Key to insert |
required |
val |
Any
|
Value to insert |
required |
Raises:
Type | Description |
---|---|
ValueError
|
If the key is already in the dict |
Source code in fancy_dataclass/utils.py
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
traverse_dataclass(cls)
Iterates through the fields of a dataclass, yielding (name, field) pairs.
If the dataclass contains nested dataclasses, recursively iterates through their fields, in depth-first order.
Nesting is indicated in the field names via "record path" syntax, e.g. outer.middle.inner
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
cls |
type
|
Dataclass type |
required |
Returns:
Type | Description |
---|---|
Iterator[Tuple[RecordPath, Field]]
|
Generator of (name, field) pairs, where each field is a |
Raises:
Type | Description |
---|---|
TypeError
|
if the type cannot be traversed |
Source code in fancy_dataclass/utils.py
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 |