Macros & Python Scripting

Relevant source files

The following files were used as context for generating this wiki page:

• src/Mod/Draft/coding_conventions.md
• [src/Mod/CAM/Roadmap/Functionality/Scripting and automation.md](https://github.com/TryParashell/Parashell/blob/44ee26aec7068593a3b395d52c51e27d893d9283/src/Mod/CAM/Roadmap/Functionality/Scripting and automation.md)
• src/Mod/Fem/coding_conventions.md
• src/App/CMakeLists.txt
• src/Mod/Test/TestData/content_items.xml
• src/Doc/sphinx/conf.py

Macros and Python scripting serve as the primary extensibility layer within the project, allowing users and developers to automate workflows, define custom features, and interact with the 3D modeling kernel. The system is designed to expose both low-level Application (App) and high-level Graphical User Interface (Gui) modules to a Python interpreter, enabling the creation of complex scripts that can manipulate document objects, properties, and the viewport.

The scripting architecture supports various levels of integration, from simple .FCMacro files used for recording and replaying user actions to fully parametric "FeaturePython" objects that behave like native C++ components. While scripting is deeply integrated, certain workbenches, such as CAM, currently have limited headless support, often requiring the GUI to be loaded for specific functions.

Sources: src/Mod/CAM/Roadmap/Functionality/Scripting and automation.md:7-11, src/Mod/Draft/coding_conventions.md:52-56, src/App/CMakeLists.txt:130-135

Scripting Architecture and Integration

The project architecture bridges C++ implementations with a Python interface. The build system generates Python wrappers for core classes such as Document, DocumentObject, and PropertyContainer. This allows for a seamless data flow where objects created in C++ can be inspected and modified via the Python console or external scripts.

Core Components

The following diagram illustrates the relationship between the C++ Application layer and the Python scripting environment.

The diagram shows how C++ source files are processed by the build system to create the Python interface.
Sources: src/App/CMakeLists.txt:1-5, src/App/CMakeLists.txt:88-107, src/App/CMakeLists.txt:110-128

Key Scripting Modules

Module	Description	Implementation Basis
FreeCAD (App)	Provides access to documents, objects, and unit systems.	Application.cpp, Document.cpp
FreeCADGui (Gui)	Manages the 3D view, workbenches, and UI commands.	FreeCADGui.showMainWindow()
FeaturePython	Allows defining parametric objects entirely in Python.	FeaturePython.cpp

Sources: src/Doc/sphinx/conf.py:53-55, src/App/CMakeLists.txt:147-150

Macro Management

Macros are stored as .FCMacro files and are recognized as specific content items within the package metadata. They can be defined with version requirements (freecadmin, freecadmax) to ensure compatibility with specific project releases.

Macro Lifecycle

1. Creation: Users record actions in the UI or write Python scripts manually.
2. Metadata: Macros are described in package.xml files for discovery by the Addon Manager.
3. Execution: The script is passed to the Python interpreter which interacts with the FreeCAD and FreeCADGui modules.

This sequence highlights the flow from macro invocation to kernel object creation.
Sources: src/Mod/Test/TestData/content_items.xml:51-60, src/Mod/CAM/Roadmap/Functionality/Scripting and automation.md:7-9

Coding Conventions for Scripts

To maintain stability and readability, the project enforces strict Python coding conventions, particularly for workbenches like Draft and FEM. Scripts are expected to follow PEP 8 and PEP 257 (docstrings).

Critical Scripting Rules

• Gui Separation: The import of FreeCADGui must be guarded by an if FreeCAD.GuiUp: test to ensure scripts can run in headless/console mode.
• Console-Only Functions: Code should be structured to separate logic from graphical interface implementations (GuiCommands).
• Printing: Scripts should use FreeCAD.Console.PrintMessage() instead of standard print() for production code to integrate with the project's internal logging system.
• Imports: Asterisk imports (from module import *) are prohibited to maintain validation capabilities.

Sources: src/Mod/Draft/coding_conventions.md:27-31, src/Mod/Draft/coding_conventions.md:52-60, src/Mod/Fem/coding_conventions.md:120-125

Scripting and Automation Roadmap

The project identifies several areas for improving scripting capabilities, particularly within the CAM (Computer-Aided Manufacturing) domain.

Professional Grade Automation

Feature	Current Assessment	Goal
Headless Batch Jobs	Limited	Run toolpath generation and export without UI interaction.
Parametric Workflows	Partial	Ensure operations update automatically via Python recomputes.
External Integration	None	Embed the pipeline into other automated systems.

Sources: src/Mod/CAM/Roadmap/Functionality/Scripting and automation.md:7-30

Conclusion

Macros and Python scripting provide the essential toolkit for extending the project's core functionality. By leveraging a generated wrapper system, the project exposes its C++ logic to a flexible Python environment. Adherence to coding conventions—such as guarding GUI imports and using internal console methods—is critical for creating robust, portable scripts that can function across both graphical and headless environments. Continuing efforts are focused on expanding headless batch job support and refining parametric recompute triggers via the Python API.