core

Core parser functions and constants.

CLASS	DESCRIPTION
QName	QName represents a qualified name in the form {uri}local.

FUNCTION	DESCRIPTION
convert_dataclass	Converts a dataclass object into a dictionary representation.
convert_dict	Converts a dictionary by transforming its keys and values and omitting entries depending on a given predicate.
dataclass_to_dict	Recursively convert a dataclass instance to a plain Python structure (dicts/lists/etc.).
default_empty_predicate	Default predicate for determining if a value is considered empty.
get_fields_by_metadata	Get fields from a data class based on metadata.
index_ids	Indexes all ‘id’ fields within a dataclass object or its nested attributes.

Classes

QName dataclass

QName(local: str, uri: Optional[str] = None)

QName represents a qualified name in the form {uri}local.

METHOD	DESCRIPTION
from_str	Parse a QName from a string.

Functions

from_str classmethod

from_str(
    qname: str,
    nsmap: Optional[dict[str, str]] = None,
    default_prefix: Optional[str] = None,
    default_uri: Optional[str] = None,
) -> QName

Parse a QName from a string.

Functions

convert_dataclass

convert_dataclass(
    value: Any,
    *,
    skip_empty: bool = False,
    empty_predicate: Callable[[Any], bool] | None = None,
    enum_as: str = "value"
) -> dict[str, Any]

Converts a dataclass object into a dictionary representation.

The function processes each field of a dataclass, transforming its value if needed. It can optionally omit fields based on specific conditions, such as empty values. Additionally, it incorporates any extra key-value pairs provided by the dataclass’s __extra_kwargs__ attribute.

PARAMETER	DESCRIPTION
value	The dataclass instance to be converted. TYPE: Any
skip_empty	Whether to skip empty fields. Defaults to False. TYPE: bool DEFAULT: False
empty_predicate	A function to determine if a value is empty. Defaults to None. TYPE: Callable[[Any], bool] | None DEFAULT: None
enum_as	How to represent Enum members: “value” (default) or “name”. TYPE: str DEFAULT: 'value'

RETURNS	DESCRIPTION
dict[str, Any]	A dictionary representation of the dataclass instance, possibly excluding empty fields.

convert_dict

convert_dict(
    value: dict,
    *,
    empty_predicate: Callable[[Any], bool] | None,
    enum_as: str,
    skip_empty: bool
) -> dict[Any, Any]

Converts a dictionary by transforming its keys and values and omitting entries depending on a given predicate.

Summary: - Keys that are Enum instances are processed based on the provided enum_as behavior. - Remaining keys are left unaltered. - Values are always recursively converted using internal conversion logic. - Entries can be skipped if skip_empty is set to True and the predicate function indicates that the value is considered empty.

PARAMETER	DESCRIPTION
value	The dictionary to be converted. TYPE: dict
empty_predicate	A predicate function that determines whether a value is considered empty. If None, no predicate is applied. TYPE: Callable[[Any], bool] | None
enum_as	Specifies the behavior for converting Enum instances. Accepted values depend on internal Enum conversion logic. TYPE: str
skip_empty	A flag indicating whether to skip entries where the predicate function identifies the value as empty. TYPE: bool

RETURNS	DESCRIPTION
dict[Any, Any]	A newly converted dictionary with potentially altered keys and values and with entries optionally
dict[Any, Any]	removed based on the given predicate.

dataclass_to_dict

dataclass_to_dict(
    obj: Any,
    *,
    skip_empty: bool = False,
    empty_predicate: Callable[[Any], bool] | None = None,
    enum_as: str = "value"
) -> Any

Recursively convert a dataclass instance to a plain Python structure (dicts/lists/etc.).

• Handles nested dataclasses, dicts, lists/tuples/sets, and basic types.
• Optionally skips fields whose converted value is considered “empty”.
• Basic handling for Enum values (choose name or value via enum_as).

PARAMETER	DESCRIPTION
obj	The object to convert (typically a dataclass instance, but dicts/lists/etc. are accepted). TYPE: Any
skip_empty	If True, fields/items with empty values are omitted from the result. TYPE: bool DEFAULT: False
empty_predicate	A function that returns True if a value should be considered empty. If None, the default considers: - None as empty - Empty strings/bytes as empty - Any object with len(x) == 0 as empty (lists, tuples, sets, dicts, etc.) Note: False and 0 are NOT considered empty by default. TYPE: Callable[[Any], bool] | None DEFAULT: None
enum_as	How to represent Enum members: “value” (default) or “name”. TYPE: str DEFAULT: 'value'

RETURNS	DESCRIPTION
Any	A structure of plain dicts/lists/tuples with primitive values (and optionally Enums mapped to name/value).

Notes

• Cyclic references are not handled; they will cause recursion errors.
• Non-dataclass arbitrary objects are converted via vars(obj) when possible.

default_empty_predicate

default_empty_predicate(x: Any) -> bool

Default predicate for determining if a value is considered empty.

get_fields_by_metadata

get_fields_by_metadata(data_class: Any, key: str, val: Any) -> dict[str, Any]

Get fields from a data class based on metadata.

index_ids

index_ids(obj: Any) -> dict[str, Any]

Indexes all ‘id’ fields within a dataclass object or its nested attributes.

The IDs are organized into a dictionary where the keys are the IDs and the values are the corresponding dataclass instances.

PARAMETER	DESCRIPTION
obj	The input object to process and extract IDs from. TYPE: Any

RETURNS	DESCRIPTION
dict[str, Any]	A dictionary mapping IDs to their corresponding dataclass instances.