python_api_issue.md

Issues with FreeCAD's Python API in general

• Document objects are mixed with other attributes in App.ActiveDocument. I would suggest to use doc instead of App.ActiveDocument and e.g. objs.Box instead of App.ActiveDocument.Box. doc.Objects would continue to be the list of children.
• App.Rotation takes angle(s) in degrees as input but Rotation.Angle is in radians.
• App.Quantity.getValueAs returns a unit-less quantity instead of a float
• getGlobalPlacement does not return the global placement.
• App.GuiUp is not available at the start of FreeCAD.
• FreeCAD has it's own PySide but not under a different name.
• There are several way to import FreeCAD (import FreeCAD as App and import freecad as App) but they are not equivalent.
• The tolerance for Placement.isSame() is 0.0 by default. It should be two reasonnably small numnbers by default, one for the translation and one for the rotation.
• App.getUserMacroDir() return the default path by default. It should default to the configured path.
• App.getUserMacroDir() vs. App.getTempPath and similar. Either Dir or Path everywhere.
• App.ActiveDocument.Box.getPaths() is not implemented.
• App.ActiveDocument.Box.setEditorMode() is redundant with setPropertyStatus.
• Some basic functions are not implemented: get_global_placement
• Not that important but the API is not Pythonic.
• There are two ways to create plugins (Init.py vs __init__.py).
• Gui.addIconPath(str(ICON_PATH)) does not work as it should because returning e.g. return my_object.svg in getIcon works only after workbench activation.

Issues with parametric objects (Python proxies)

• The __init__ function of proxies is not called on document restore.
• View provider proxies are complex (__init__ vs attach, vobj.Proxy = self provokes a call to attach).
• There is no standard way to know when all properties are defined and onChanged is called before as soon as a property is defined so that implementers have to check this by themselves. There should exist a way to turn off callbacks and reactivate them when all properties are defined (this would not be an API-breaking change).
• There is no standard way to identify the type of a App.FeaturePython The Draft workbench uses the Type attribute in proxies but this is not a standard.