spreadsheet_query

freecad.datamanager_wb.spreadsheets.spreadsheet_query

Query helpers for spreadsheet aliases.

Provides discovery of spreadsheet objects, enumeration of alias names, and searching expressions for alias references.

getSpreadsheetAliasNames(spreadsheet_name, *, ctx=None)

Return all alias names defined on a spreadsheet.

Parameters:

Name	Type	Description	Default
spreadsheet_name	str	Name of a Spreadsheet::Sheet.	required

Returns:

Type	Description
list[str]	Sorted list of alias names.

Source code in freecad/datamanager_wb/spreadsheets/spreadsheet_query.py

def getSpreadsheetAliasNames(
    spreadsheet_name: str,
    *,
    ctx: FreeCadContext | None = None,
) -> list[str]:
    """Return all alias names defined on a spreadsheet.

    Args:
        spreadsheet_name: Name of a `Spreadsheet::Sheet`.

    Returns:
        Sorted list of alias names.
    """
    port = get_port(ctx)
    doc = port.get_active_document()
    if doc is None:
        return []

    sheet = port.get_typed_object(doc, spreadsheet_name, type_id="Spreadsheet::Sheet")
    if sheet is None:
        return []

    names = sorted(_get_alias_map(sheet).keys())
    return names

getSpreadsheetAliasReferences(spreadsheet_name, alias_name=None, *, ctx=None)

Find expressions that reference a spreadsheet or a specific alias.

Parameters:

Name	Type	Description	Default
spreadsheet_name	str	Name of the spreadsheet.	required
alias_name	str | None	Optional alias name. When provided, searches for references to that alias; otherwise searches for references to the spreadsheet.	None

Returns:

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

Source code in freecad/datamanager_wb/spreadsheets/spreadsheet_query.py

def getSpreadsheetAliasReferences(
    spreadsheet_name: str,
    alias_name: str | None = None,
    *,
    ctx: FreeCadContext | None = None,
) -> dict[str, str]:
    """Find expressions that reference a spreadsheet or a specific alias.

    Args:
        spreadsheet_name: Name of the spreadsheet.
        alias_name: Optional alias name. When provided, searches for references
            to that alias; otherwise searches for references to the spreadsheet.

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

    sheet = _get_active_spreadsheet(spreadsheet_name, ctx=ctx)
    if sheet is None:
        return {}

    label_or_name = _sheet_label_or_name(sheet)

    patterns, alias_re = _build_alias_search(label_or_name=label_or_name, alias_name=alias_name)

    results: dict[str, str] = {}

    # Include spreadsheet-internal references (cell formulas referencing aliases).
    if alias_name is not None:
        _add_internal_alias_refs(sheet=sheet, alias_re=alias_re, results=results)

    engine_alias_re = None if alias_name is not None else alias_re
    results.update(
        _collect_expression_engine_refs(doc=doc, patterns=patterns, alias_re=engine_alias_re)
    )

    return results

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

Yield spreadsheet object names from the active document.

Parameters:

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

Yields:

Type	Description
str	The Name of each Spreadsheet::Sheet object.

Source code in freecad/datamanager_wb/spreadsheets/spreadsheet_query.py

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

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

    Yields:
        The `Name` of each `Spreadsheet::Sheet` 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="Spreadsheet::Sheet")
        if exclude_copy_on_change
        else set()
    )
    yield from _iter_filtered_sheet_names(
        doc=doc,
        excluded=excluded,
        exclude_copy_on_change=exclude_copy_on_change,
    )