Skip to content

freecad_port

freecad.datamanager_wb.ports.freecad_port

Ports and adapters for FreeCAD runtime access.

This module defines a small "port" interface that encapsulates the parts of the FreeCAD runtime needed by UI-facing orchestration code.

The goal is to keep FreeCAD-specific quirks (optional GUI module, duck-typed objects, and defensive getattr usage) localized to a single adapter.

FreeCadContextAdapter(ctx) dataclass

Runtime adapter that implements :class:FreeCadPort using FreeCadContext.

ctx instance-attribute

add_selection(*, doc_name, obj_name)

Add an object to GUI selection if the GUI is available.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
150
151
152
153
154
155
156
157
158
159
160
def add_selection(self, *, doc_name: str, obj_name: str) -> None:
    """Add an object to GUI selection if the GUI is available."""
    gui = getattr(self.ctx, "gui", None)
    selection = getattr(gui, "Selection", None) if gui is not None else None
    adder = getattr(selection, "addSelection", None)
    if not callable(adder):
        return
    try:
        adder(doc_name, obj_name)
    except Exception:  # pylint: disable=broad-exception-caught
        return

clear_selection()

Clear GUI selection if the GUI is available.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
138
139
140
141
142
143
144
145
146
147
148
def clear_selection(self) -> None:
    """Clear GUI selection if the GUI is available."""
    gui = getattr(self.ctx, "gui", None)
    selection = getattr(gui, "Selection", None) if gui is not None else None
    clearer = getattr(selection, "clearSelection", None)
    if not callable(clearer):
        return
    try:
        clearer()
    except Exception:  # pylint: disable=broad-exception-caught
        return

get_active_document()

Return the active document, if any.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
70
71
72
73
74
75
def get_active_document(self) -> object | None:
    """Return the active document, if any."""
    doc = self.ctx.app.ActiveDocument
    if doc is None:
        return None
    return doc

get_object(doc, name)

Return an object by name from the given document, if possible.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
77
78
79
80
81
82
83
84
85
def get_object(self, doc: object, name: str) -> object | None:
    """Return an object by name from the given document, if possible."""
    getter = getattr(doc, "getObject", None)
    if not callable(getter):
        return None
    try:
        return cast(object | None, getter(name))
    except Exception:  # pylint: disable=broad-exception-caught
        return None

get_typed_object(doc, name, *, type_id)

Return an object by name only if its TypeId matches.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
87
88
89
90
91
92
def get_typed_object(self, doc: object, name: str, *, type_id: str) -> object | None:
    """Return an object by name only if its `TypeId` matches."""
    obj = self.get_object(doc, name)
    if obj is None or getattr(obj, "TypeId", None) != type_id:
        return None
    return obj

log(text)

Write an informational message to the FreeCAD console/log.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
105
106
107
108
109
110
111
112
113
114
def log(self, text: str) -> None:
    """Write an informational message to the FreeCAD console/log."""
    console = getattr(self.ctx.app, "Console", None)
    printer = getattr(console, "PrintLog", None)
    if not callable(printer):
        return
    try:
        printer(text)
    except Exception:  # pylint: disable=broad-exception-caught
        return

message(text)

Write a normal message to the FreeCAD console/log.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
127
128
129
130
131
132
133
134
135
136
def message(self, text: str) -> None:
    """Write a normal message to the FreeCAD console/log."""
    console = getattr(self.ctx.app, "Console", None)
    printer = getattr(console, "PrintMessage", None)
    if not callable(printer):
        return
    try:
        printer(text)
    except Exception:  # pylint: disable=broad-exception-caught
        return

translate(context, text)

Translate the given text for UI display.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
def translate(self, context: str, text: str) -> str:
    """Translate the given text for UI display."""
    qt = getattr(self.ctx.app, "Qt", None)
    translate = getattr(qt, "translate", None)
    if not callable(translate):
        return text
    try:
        return str(translate(context, text))
    except Exception:  # pylint: disable=broad-exception-caught
        return text

try_recompute_active_document()

Attempt to recompute the active document, swallowing exceptions.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
162
163
164
165
166
167
168
169
170
171
172
def try_recompute_active_document(self) -> None:
    """Attempt to recompute the active document, swallowing exceptions."""
    doc = self.ctx.app.ActiveDocument
    if doc is None:
        return
    try:
        recompute = getattr(doc, "recompute", None)
        if callable(recompute):
            recompute()
    except Exception:  # pylint: disable=broad-exception-caught
        pass

try_update_gui()

Attempt to update the GUI, swallowing exceptions.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
174
175
176
177
178
179
180
181
182
def try_update_gui(self) -> None:
    """Attempt to update the GUI, swallowing exceptions."""
    try:
        gui = self.ctx.gui
        updater = getattr(gui, "updateGui", None) if gui is not None else None
        if callable(updater):
            updater()
    except Exception:  # pylint: disable=broad-exception-caught
        pass

warn(text)

Write a warning message to the FreeCAD console/log.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
116
117
118
119
120
121
122
123
124
125
def warn(self, text: str) -> None:
    """Write a warning message to the FreeCAD console/log."""
    console = getattr(self.ctx.app, "Console", None)
    printer = getattr(console, "PrintWarning", None)
    if not callable(printer):
        return
    try:
        printer(text)
    except Exception:  # pylint: disable=broad-exception-caught
        return

FreeCadPort

Port interface for the small slice of FreeCAD used by controllers.

add_selection(*, doc_name, obj_name)

Add an object to GUI selection if the GUI is available.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
48
49
def add_selection(self, *, doc_name: str, obj_name: str) -> None:
    """Add an object to GUI selection if the GUI is available."""

clear_selection()

Clear GUI selection if the GUI is available.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
45
46
def clear_selection(self) -> None:
    """Clear GUI selection if the GUI is available."""

get_active_document()

Return the active document, if any.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
24
25
def get_active_document(self) -> object | None:
    """Return the active document, if any."""

get_object(doc, name)

Return an object by name from the given document, if possible.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
27
28
def get_object(self, doc: object, name: str) -> object | None:
    """Return an object by name from the given document, if possible."""

get_typed_object(doc, name, *, type_id)

Return an object by name only if its TypeId matches.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
30
31
def get_typed_object(self, doc: object, name: str, *, type_id: str) -> object | None:
    """Return an object by name only if its `TypeId` matches."""

log(text)

Write an informational message to the FreeCAD console/log.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
36
37
def log(self, text: str) -> None:
    """Write an informational message to the FreeCAD console/log."""

message(text)

Write a normal message to the FreeCAD console/log.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
42
43
def message(self, text: str) -> None:
    """Write a normal message to the FreeCAD console/log."""

translate(context, text)

Translate the given text for UI display.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
33
34
def translate(self, context: str, text: str) -> str:
    """Translate the given text for UI display."""

try_recompute_active_document()

Attempt to recompute the active document.

This method must swallow all exceptions to keep the UI responsive.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
51
52
53
54
55
def try_recompute_active_document(self) -> None:
    """Attempt to recompute the active document.

    This method must swallow all exceptions to keep the UI responsive.
    """

try_update_gui()

Attempt to update the FreeCAD GUI.

This method must swallow all exceptions to keep the UI responsive.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
57
58
59
60
61
def try_update_gui(self) -> None:
    """Attempt to update the FreeCAD GUI.

    This method must swallow all exceptions to keep the UI responsive.
    """

warn(text)

Write a warning message to the FreeCAD console/log.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
39
40
def warn(self, text: str) -> None:
    """Write a warning message to the FreeCAD console/log."""

get_port(ctx=None)

Return a :class:FreeCadPort backed by the given context.

When ctx is not provided, this function obtains the real FreeCAD runtime context via :func:get_runtime_context.

Source code in freecad/datamanager_wb/ports/freecad_port.py 
185
186
187
188
189
190
191
192
193
def get_port(ctx: FreeCadContext | None = None) -> FreeCadPort:
    """Return a :class:`FreeCadPort` backed by the given context.

    When `ctx` is not provided, this function obtains the real FreeCAD runtime
    context via :func:`get_runtime_context`.
    """
    if ctx is None:
        ctx = get_runtime_context()
    return FreeCadContextAdapter(ctx)