varset_query

freecad.datamanager_wb.varsets.varset_query

Query helpers for FreeCAD VarSets.

Provides functions to list varsets, list their variables, and find expression references to varset variables.

getVarsetReferences(varset_name, variable_name=None, *, ctx=None)

Find expression engine entries that reference a VarSet or variable.

Parameters:

Name	Type	Description	Default
varset_name	str	VarSet name.	required
variable_name	str | None	Optional variable name to scope matches. When omitted, all expressions containing <<VarSet>> are considered.	None

Returns:

Type	Description
dict[str, str]	Mapping of "Object.Property" -> expression string.

Source code in freecad/datamanager_wb/varsets/varset_query.py

def getVarsetReferences(
    varset_name: str,
    variable_name: str | None = None,
    *,
    ctx: FreeCadContext | None = None,
) -> dict[str, str]:
    """Find expression engine entries that reference a VarSet or variable.

    Args:
        varset_name: VarSet name.
        variable_name: Optional variable name to scope matches. When omitted,
            all expressions containing `<<VarSet>>` are considered.

    Returns:
        Mapping of ``"Object.Property"`` -> expression string.
    """
    doc = get_port(ctx).get_active_document()
    if doc is None:
        return {}

    patterns, internal_var_re = _build_varset_search(
        varset_name=varset_name,
        variable_name=variable_name,
    )

    results: dict[str, str] = {}
    port = get_port(ctx)
    for obj_name, lhs, expr_text in iter_named_expression_engine_entries(doc):
        if not _matches_varset_expression(
            expr_text=expr_text,
            patterns=patterns,
            internal_var_re=internal_var_re,
            obj=port.get_typed_object(doc, obj_name, type_id="App::VarSet") or object(),
            varset_name=varset_name,
        ):
            continue
        key = build_expression_key(obj_name=obj_name, lhs=lhs)
        results[key] = str(expr_text)
    return results

getVarsetVariableGroups(varset_name, *, ctx=None)

Return mapping of variable/property name -> group for a VarSet.

FreeCAD VarSet variables are stored as properties and may be organized into groups (property group). When no group is defined, FreeCAD uses "Base".

Source code in freecad/datamanager_wb/varsets/varset_query.py

def getVarsetVariableGroups(
    varset_name: str,
    *,
    ctx: FreeCadContext | None = None,
) -> dict[str, str]:
    """Return mapping of variable/property name -> group for a VarSet.

    FreeCAD VarSet variables are stored as properties and may be organized into
    groups (property group). When no group is defined, FreeCAD uses "Base".
    """

    doc = get_port(ctx).get_active_document()
    if doc is None:
        return {}

    varset = get_port(ctx).get_typed_object(doc, varset_name, type_id="App::VarSet")
    if varset is None:
        return {}

    groups: dict[str, str] = {}
    for prop in getattr(varset, "PropertiesList", []):
        if _is_excluded_varset_property(prop):
            continue
        name = str(prop)
        groups[name] = _get_varset_property_group(varset, name)
    return groups

getVarsetVariableNames(varset_name, *, ctx=None)

Return variable/property names defined on a VarSet.

Parameters:

Name	Type	Description	Default
varset_name	str	Name of the App::VarSet object.	required

Returns:

Type	Description
list[str]	Sorted list of variable/property names. Built-in FreeCAD properties
list[str]	(Label, Placement, etc.) are excluded.

Source code in freecad/datamanager_wb/varsets/varset_query.py

def getVarsetVariableNames(
    varset_name: str,
    *,
    ctx: FreeCadContext | None = None,
) -> list[str]:
    """Return variable/property names defined on a VarSet.

    Args:
        varset_name: Name of the `App::VarSet` object.

    Returns:
        Sorted list of variable/property names. Built-in FreeCAD properties
        (Label, Placement, etc.) are excluded.
    """
    doc = get_port(ctx).get_active_document()
    if doc is None:
        return []

    varset = get_port(ctx).get_typed_object(doc, varset_name, type_id="App::VarSet")
    if varset is None:
        return []

    return _collect_varset_variable_names(varset)

getVarsetVariableNamesForGroup(varset_name, group_name, *, ctx=None)

Return variable/property names defined on a VarSet, optionally filtered by group.

Source code in freecad/datamanager_wb/varsets/varset_query.py

def getVarsetVariableNamesForGroup(
    varset_name: str,
    group_name: str | None,
    *,
    ctx: FreeCadContext | None = None,
) -> list[str]:
    """Return variable/property names defined on a VarSet, optionally filtered by group."""

    names = getVarsetVariableNames(varset_name, ctx=ctx)
    if not group_name:
        return names

    wanted = group_name.strip() or "Base"
    groups = getVarsetVariableGroups(varset_name, ctx=ctx)
    filtered = [n for n in names if groups.get(n, "Base") == wanted]
    filtered.sort()
    return filtered

getVarsets(*, exclude_copy_on_change=False, ctx=None)

Yield VarSet object names from the active document.

Parameters:

Name	Type	Description	Default
exclude_copy_on_change	bool	When true, filters out VarSets that are created by FreeCAD's copy-on-change mechanism.	False

Yields:

Type	Description
str	The Name of each App::VarSet object.

Source code in freecad/datamanager_wb/varsets/varset_query.py

def getVarsets(
    *,
    exclude_copy_on_change: bool = False,
    ctx: FreeCadContext | None = None,
) -> Iterator[str]:
    """Yield VarSet object names from the active document.

    Args:
        exclude_copy_on_change: When true, filters out VarSets that are created
            by FreeCAD's copy-on-change mechanism.

    Yields:
        The `Name` of each `App::VarSet` object.
    """
    doc = get_port(ctx).get_active_document()
    if doc is None:
        return

    excluded: set[str] = (
        get_copy_on_change_names(doc=doc, type_id="App::VarSet")
        if exclude_copy_on_change
        else set()
    )
    yield from _iter_filtered_varset_names(
        doc=doc,
        excluded=excluded,
        exclude_copy_on_change=exclude_copy_on_change,
    )