dataclass_wizard.utils package

Submodules

dataclass_wizard.utils.dataclass_compat module

Pulling some functions removed in recent versions of Python into the module for continued compatibility. All function names and bodies are left exactly as they were prior to being removed.

dataclass_wizard.utils.dict_helper module

Dict helper module

class dataclass_wizard.utils.dict_helper.DictWithLowerStore(data=None, **kwargs)

Bases: dict

A dict-like object with a lower-cased key store.

All keys are expected to be strings. The structure remembers the case of the lower-cased key to be set, and methods like get() and get_key() will use the lower-cased store. However, querying and contains testing is case sensitive:

dls = DictWithLowerStore()
dls['Accept'] = 'application/json'
dls['aCCEPT'] == 'application/json'         # False (raises KeyError)
dls['Accept'] == 'application/json'         # True
dls.get('aCCEPT') == 'application/json'     # True

dls.get_key('aCCEPT') == 'Accept'           # True
list(dls) == ['Accept']                     # True

Note

I don’t want to use the CaseInsensitiveDict from request.structures, because it turns out the lookup via that dict implementation is rather slow. So this version is somewhat of a trade-off, where I retain the same speed on lookups as a plain dict, but I also have a lower-cased key store, in case I ever need to use it.

copy()

Return a shallow copy of the dict.

get(key)

Do a case-insensitive lookup. This lower-cases key and looks up from the lower-cased key store.

get_key(key)

Return the original cased key

Return type:

str

lower_items()

Like iteritems(), but with all lowercase keys.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

class dataclass_wizard.utils.dict_helper.NestedDict

Bases: dict

A dictionary that automatically creates nested dictionaries for missing keys.

This class extends the built-in dict to simplify working with deeply nested structures. If a key is accessed but does not exist, it will be created automatically with a new NestedDict as its value.

Source: https://stackoverflow.com/a/5369984/10237506

Example:

>>> nd = NestedDict()
>>> nd['a']['b']['c'] = 42
>>> nd
{'a': {'b': {'c': 42}}}

>>> nd['x']['y']
{}

dataclass_wizard.utils.function_builder module

class dataclass_wizard.utils.function_builder.FunctionBuilder

Bases: object

add_line(line)

Add a line to the current function’s body with proper indentation.

Parameters:

line (str)

add_lines(*lines)

Add lines to the current function’s body with proper indentation.

Parameters:

lines (str)

break_()

Equivalent to the break statement in Python.

create_functions(_globals=None)

Create functions by compiling the code.

current_function

decrease_indent()

Decrease indentation level.

elif_(condition)

Equivalent to the elif statement in Python.

Sample Usage:

>>> with FunctionBuilder().elif_('something is True'):
>>>     ...

Will generate the following code:

>>> elif something is True:
>>>     ...

Return type:

FunctionBuilder

Parameters:

condition (str)

else_()

Equivalent to the else statement in Python.

Sample Usage:

>>> with FunctionBuilder().else_():
>>>     ...

Will generate the following code:

>>> else:
>>>     ...

Return type:

FunctionBuilder

except_(cls, var_name=None, *custom_classes)

Equivalent to the except block in Python.

Sample Usage:

>>> with FunctionBuilder().except_(TypeError, 'exc'):
>>>     ...

Will generate the following code:

>>> except TypeError as exc:
>>>     ...

Parameters:

• cls (type[Exception])

• var_name (str | None)

• custom_classes (type[Exception])

except_multi(*classes)

Equivalent to the except block in Python.

Sample Usage:

>>> with FunctionBuilder().except_multi(AttributeError, TypeError, ValueError):
>>>     ...

Will generate the following code:

>>> except (AttributeError, TypeError, ValueError):
>>>     ...

Parameters:

classes (type[Exception])

finalize_function()

Finalize the function code and add to the list of functions.

for_(condition)

Equivalent to the for statement in Python.

Sample Usage:

>>> with FunctionBuilder().for_('i in range(3)'):
>>>     ...

Will generate the following code:

>>> for i in range(3):
>>>     ...

Return type:

FunctionBuilder

Parameters:

condition (str)

function(name, args, return_type=<dataclasses._MISSING_TYPE object>, locals=None)

Start a new function definition with optional return type.

Return type:

FunctionBuilder

Parameters:

• name (str)

• args (list)

functions

globals

if_(condition, comment='')

Equivalent to the if statement in Python.

Sample Usage:

>>> with FunctionBuilder().if_('something is True'):
>>>     ...

Will generate the following code:

>>> if something is True:
>>>     ...

Return type:

FunctionBuilder

Parameters:

• condition (str)

• comment (Any)

increase_indent()

Increase indentation level for nested code.

indent_level

namespace

prev_function

try_()

Equivalent to the try block in Python.

Sample Usage:

>>> with FunctionBuilder().try_():
>>>     ...

Will generate the following code:

>>> try:
>>>     ...

Return type:

FunctionBuilder

dataclass_wizard.utils.function_builder.is_builtin_class(cls)

Check if a class is a builtin in Python.

Return type:

bool

Parameters:

cls (type)

dataclass_wizard.utils.json_util module

JSON Helper Utilities - only internally used in errors.py, i.e. for rendering exceptions.

Note

This module should not be imported anywhere at the top-level of another library module!

dataclass_wizard.utils.json_util.safe_dumps(o, cls=<class 'dataclass_wizard.utils.json_util.SafeEncoder'>, **kwargs)

dataclass_wizard.utils.lazy_loader module

Utility for lazy loading Python modules.

Credits: https://wil.yegelwel.com/lazily-importing-python-modules/

class dataclass_wizard.utils.lazy_loader.LazyLoader(parent_module_globals, name, extra=None, local_name=None, warning=None)

Bases: ModuleType

Lazily import a module, mainly to avoid pulling in large dependencies. contrib, and ffmpeg are examples of modules that are large and not always needed, and this allows them to only be loaded when they are used.

dataclass_wizard.utils.object_path module

dataclass_wizard.utils.object_path.safe_get(data, path, default=<dataclasses._MISSING_TYPE object>, raise_=True)

dataclass_wizard.utils.object_path.split_object_path(_input)

dataclass_wizard.utils.object_path.v1_env_safe_get(data, first_key, path, raise_)

dataclass_wizard.utils.object_path.v1_safe_get(data, path, raise_)

dataclass_wizard.utils.string_conv module

dataclass_wizard.utils.string_conv.normalize(string)

Normalize a string - typically a dataclass field name - for comparison purposes.

Return type:

str

Parameters:

string (str)

dataclass_wizard.utils.string_conv.possible_env_vars(field, lookup_strat)

Maps a dataclass field name to its possible var names in an env.

This function checks multiple naming conventions (e.g., camelCase, PascalCase, kebab-case, etc.) to find the matching key in the JSON object o. It also caches the mapping for future use.

Return type:

list[str]

Parameters:

• field (str)

• lookup_strat (EnvKeyStrategy)

Args:

field (str): The dataclass field name to map. lookup_strat (EnvKeyStrategy): The environment key strategy to use.

Returns:

list[str]: The possible JSON keys for the given field.

dataclass_wizard.utils.string_conv.possible_json_keys(field)

Maps a dataclass field name to its possible keys in a JSON object.

This function checks multiple naming conventions (e.g., camelCase, PascalCase, kebab-case, etc.) to find the matching key in the JSON object o. It also caches the mapping for future use.

Return type:

list[str]

Parameters:

field (str)

Args:

field (str): The dataclass field name to map.

Returns:

list[str]: The possible JSON keys for the given field.

dataclass_wizard.utils.string_conv.repl_or_with_union(s)

Replace all occurrences of PEP 604- style annotations (i.e. like X | Y) with the Union type from the typing module, i.e. like Union[X, Y].

This is a recursive function that splits a complex annotation in order to traverse and parse it, i.e. one that is declared as follows:

dict[str | Optional[int], list[list[str] | tuple[int | bool] | None]]

Parameters:

s (str)

dataclass_wizard.utils.string_conv.to_camel_case(string)

Convert a string to Camel Case.

Examples:

>>> to_camel_case("device_type")
'deviceType'

Return type:

str

Parameters:

string (str)

dataclass_wizard.utils.string_conv.to_lisp_case(string)

Make a hyphenated, lowercase form from the expression in the string.

Example:

>>> to_lisp_case("DeviceType")
'device-type'

Return type:

str

Parameters:

string (str)

dataclass_wizard.utils.string_conv.to_pascal_case(string)

Converts a string to Pascal Case (also known as “Upper Camel Case”)

Examples:

>>> to_pascal_case("device_type")
'DeviceType'

dataclass_wizard.utils.string_conv.to_snake_case(string)

Make an underscored, lowercase form from the expression in the string.

Example:

>>> to_snake_case("DeviceType")
'device_type'

Return type:

str

Parameters:

string (str)

dataclass_wizard.utils.type_conv module

dataclass_wizard.utils.type_conv.as_bool(o)

Return o if already a boolean, otherwise return the boolean value for o.

Parameters:

o (str | bool | int | float)

dataclass_wizard.utils.type_conv.as_date(o, base_type=<class 'datetime.date'>, default=None, raise_=True)

Attempt to convert an object o to a date object using the below logic.

• str: convert date strings (in ISO format) via the built-in fromisoformat method.

• Number (int or float): Convert a numeric timestamp via the

  built-in fromtimestamp method.

• date: Return object o if it’s already of this type or

  sub-type.

Otherwise, if we’re unable to convert the value of o to a date as expected, raise an error if the raise_ parameter is true; if not, return default instead.

Parameters:

o (str | Number | date)

dataclass_wizard.utils.type_conv.as_datetime(o, base_type=<class 'datetime.datetime'>, default=None, raise_=True)

Attempt to convert an object o to a datetime object using the below logic.

• str: convert datetime strings (in ISO format) via the built-in fromisoformat method.

• Number (int or float): Convert a numeric timestamp via the

  built-in fromtimestamp method, and return a UTC datetime.

• datetime: Return object o if it’s already of this type or

  sub-type.

Otherwise, if we’re unable to convert the value of o to a datetime as expected, raise an error if the raise_ parameter is true; if not, return default instead.

Parameters:

o (str | Number | datetime)

dataclass_wizard.utils.type_conv.as_dict(o, kv_sep='=', sep=',')

Return o if already a dict. If o is a string, split it on sep and then split each result by kv_sep, and return the dict result.

Parameters:

o (str | Iterable)

dataclass_wizard.utils.type_conv.as_enum(o, base_type, lookup_func=<function <lambda>>, transform_func=<function <lambda>>, raise_=True)

Return o if it’s already an Enum of type base_type. If o is None or an empty string, return None.

Otherwise, attempt to convert the object o to a base_type using the below logic:

• If o is a string, we’ll put it through our transform_func before a lookup. The default one upper-cases the string and replaces spaces with underscores, since that’s typically how we define Enum names.

• Then, convert to a base_type using the lookup_func. The one looks up by the Enum name field.

Raises:

ParseError – If the lookup for the Enum member fails, and the raise_ flag is enabled.

Return type:

Optional[TypeVar(E, bound= Enum)]

Parameters:

• o (AnyStr | int | float)

• base_type (Type[E])

dataclass_wizard.utils.type_conv.as_int(o, base_type=<class 'int'>, default=0, raise_=True)

Return o if already a int, otherwise return the int value for a string. If o is None or an empty string, return default instead.

If o cannot be converted to an int, raise an error if raise_ is true, other return default instead.

Raises:

• TypeError – If o is a bool (which is an int sub-class)

• ValueError – When o cannot be converted to an int, and the raise_ parameter is true

Parameters:

o (str | int | float | bool | None)

dataclass_wizard.utils.type_conv.as_list(o, sep=',')

Return o if already a list. If o is a string, split it on sep and return the list result.

Parameters:

o (str | Iterable)

dataclass_wizard.utils.type_conv.as_str(o, base_type=<class 'str'>)

Return o if already a str, otherwise return the string value for o. If o is None, return an empty string instead.

Parameters:

o (str | None)

dataclass_wizard.utils.type_conv.as_time(o, base_type=<class 'datetime.time'>, default=None, raise_=True)

Attempt to convert an object o to a time object using the below logic.

• str: convert time strings (in ISO format) via the built-in fromisoformat method.

• time: Return object o if it’s already of this type or

  sub-type.

Otherwise, if we’re unable to convert the value of o to a time as expected, raise an error if the raise_ parameter is true; if not, return default instead.

Parameters:

o (str | time)

dataclass_wizard.utils.type_conv.as_timedelta(o, base_type=<class 'datetime.timedelta'>, default=None, raise_=True)

Attempt to convert an object o to a timedelta object using the below logic.

• str: If the string is in a numeric form like “1.23”, we convert it to a float and assume it’s in seconds. Otherwise, we convert strings via the pytimeparse.parse function.

• int or float: A numeric value is assumed to be in seconds. In this case, it is passed in to the constructor like timedelta(seconds=...)

• timedelta: Return object o if it’s already of this type or

  sub-type.

Otherwise, if we’re unable to convert the value of o to a timedelta as expected, raise an error if the raise_ parameter is true; if not, return default instead.

Parameters:

o (str | int | float | timedelta)

dataclass_wizard.utils.type_conv.date_to_timestamp(d)

Retrieves the epoch timestamp of a date object, as an int

https://stackoverflow.com/a/15661036/10237506

Return type:

int

Parameters:

d (date)

dataclass_wizard.utils.typing_compat module

Utility module for checking generic types provided by the typing library.

dataclass_wizard.utils.typing_compat.eval_forward_ref(base_type, cls)

Evaluate a forward reference using the class globals, and return the underlying type reference.

Parameters:

• base_type (FREF)

• cls (type)

dataclass_wizard.utils.typing_compat.eval_forward_ref_if_needed(base_type, base_cls)

If needed, evaluate a forward reference using the class globals, and return the underlying type reference.

Parameters:

• base_type (type | FREF)

• base_cls (type)

dataclass_wizard.utils.typing_compat.get_args(tp)

Get type arguments with all substitutions performed.

For unions, basic simplifications used by Union constructor are performed. Examples:

get_args(Dict[str, int]) == (str, int)
get_args(int) == ()
get_args(Union[int, Union[T, int], str][int]) == (int, str)
get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
get_args(Callable[[], T][int]) == ([], int)

dataclass_wizard.utils.typing_compat.get_keys_for_typed_dict(cls)

Given a TypedDict sub-class, returns a pair of (required_keys, optional_keys)

dataclass_wizard.utils.typing_compat.get_origin(cls, raise_=False)

Get the un-subscripted value of a type. If we’re unable to retrieve this value, return type cls if raise_ is false.

This supports generic types, Callable, Tuple, Union, Literal, Final and ClassVar. Return None for unsupported types.

Examples:

get_origin(Literal[42]) is Literal
get_origin(int) is int
get_origin(ClassVar[int]) is ClassVar
get_origin(Generic) is Generic
get_origin(Generic[T]) is Generic
get_origin(Union[T, int]) is Union
get_origin(List[Tuple[T, T]][int]) == list

Raises:

AttributeError – When the raise_ flag is enabled, and we are unable to retrieve the un-subscripted value.

dataclass_wizard.utils.typing_compat.get_origin_v2(cls)

dataclass_wizard.utils.typing_compat.is_annotated(cls)

Detects a typing.Annotated class.

dataclass_wizard.utils.typing_compat.is_generic(cls)

Detects any kind of generic, for example List or List[int]. This includes “special” types like Union, Any ,and Tuple - anything that’s subscriptable, basically.

https://stackoverflow.com/a/52664522/10237506

dataclass_wizard.utils.typing_compat.is_literal(cls)

Return type:

bool

dataclass_wizard.utils.typing_compat.is_typed_dict(cls)

Checks if cls is a sub-class of TypedDict

Return type:

bool

Parameters:

cls (type)

dataclass_wizard.utils.typing_compat.is_typed_dict_type_qualifier(cls)

Return type:

bool

dataclass_wizard.utils.typing_compat.is_union(cls)

Return type:

bool

dataclass_wizard.utils.wrappers module

Wrapper utilities

class dataclass_wizard.utils.wrappers.FuncWrapper(f)

Bases: object

Wraps a callable f - which is occasionally useful, for example when defining functions as Enum values. See below answer for more details.

https://stackoverflow.com/a/40339397/10237506

Parameters:

f (Callable)

f

Module contents