Exposing Cplusplus to Python: Difference between revisions
(stub, needs more work) |
m (format link to forum discussion) |
||
(7 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
{{VeryImportantMessage|This documentation is a stub and needs more work, perhaps a written example + links to commits demonstrating in the commit history}} |
{{VeryImportantMessage|This documentation is a stub and needs more work, perhaps a written example + links to commits demonstrating in the commit history}} |
||
== How to expose c++ functionality to Python == |
== How to expose c++ functionality to Python == |
||
It becomes necessary at times to expand the FreeCAD API further by exposing functions that are available in the source code in c++ to the python. In so doing, providing an ability to trigger deep internal functionality with Python in real-time instead of needing to compile. |
It becomes necessary at times to expand the FreeCAD API further by exposing functions that are available in the source code in c++ to the python. In so doing, providing an ability to trigger deep internal functionality with Python in real-time instead of needing to compile. |
||
Line 12: | Line 14: | ||
* return the <tt>Py</tt> object. |
* return the <tt>Py</tt> object. |
||
=== Further Elaboration === |
|||
⚫ | |||
There are two source files required to implement a new Python binding. Assuming we wanted to expose some methods from [https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/TopoShape.cpp <tt>FreeCAD/src/Mod/Part/TopoShape.cpp</tt>], we would need to make: |
|||
* <tt>TopoShapePy.xml</tt> - definitions of the functions for be exposed in XML format. This file is used to generate header files for our next file... |
|||
* <tt>TopoShapePyImp.cpp</tt> - the actual C++ code that bridges from Python to C++. |
|||
These 2 files need to be added to '''<tt>../Mod/yourModule/App/CMakeLists.txt</tt>'''. See [https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/AppPartPy.cpp <tt>FreeCAD/src/Mod/Part/App/CMakeLists.txt</tt>] for an example. |
|||
You can extend the Python version of your module by adding to '''<tt>../Mod/yourModule/App/AppmyModulePy.cpp</tt>''' (see [https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/AppPartPy.cpp <tt>FreeCAD/src/Mod/Part/AppPartPy.cpp</tt>]). The additions are accessed in Python by "<tt>import myModule</tt>". |
|||
Note: |
|||
# <tt>xxxxxPyImp</tt> routines return a <tt>PyObject*</tt> pointer (see <tt>TopoShapePyImp.cpp</tt>) |
|||
# <tt>AppmyModulePy.cpp</tt> routines return a <tt>Py::Object</tt> (see [https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/AppPartPy.cpp <tt>FreeCAD/src/Mod/Part/AppPartPy.cpp</tt>]). |
|||
=== Related Links === |
|||
⚫ | |||
* [https://forum.freecadweb.org/viewtopic.php?p=560639#p560639 Forum discussion: Adding Commands in Python to C++ Workbench] |
|||
* [[Workbench creation]] |
|||
[[Category:Developer Documentation]] |
[[Category:Developer Documentation]] |
Revision as of 12:50, 20 February 2022
How to expose c++ functionality to Python
It becomes necessary at times to expand the FreeCAD API further by exposing functions that are available in the source code in c++ to the python. In so doing, providing an ability to trigger deep internal functionality with Python in real-time instead of needing to compile.
Below is an explanation of how one can achieve this.
The basic structure of a program to expose functionality to Python is something like this:
- get the Py object parameters and convert them to c++ variables using PyArg_ParseTuple(),
- use various c++ routines from OpenCascade and/or FreeCAD to produce the desired result,
- convert the c++ result into Py object using routines like PyLong_AsLong(), Py::asObject(), etc,
- return the Py object.
Further Elaboration
There are two source files required to implement a new Python binding. Assuming we wanted to expose some methods from FreeCAD/src/Mod/Part/TopoShape.cpp, we would need to make:
- TopoShapePy.xml - definitions of the functions for be exposed in XML format. This file is used to generate header files for our next file...
- TopoShapePyImp.cpp - the actual C++ code that bridges from Python to C++.
These 2 files need to be added to ../Mod/yourModule/App/CMakeLists.txt. See FreeCAD/src/Mod/Part/App/CMakeLists.txt for an example.
You can extend the Python version of your module by adding to ../Mod/yourModule/App/AppmyModulePy.cpp (see FreeCAD/src/Mod/Part/AppPartPy.cpp). The additions are accessed in Python by "import myModule".
Note:
- xxxxxPyImp routines return a PyObject* pointer (see TopoShapePyImp.cpp)
- AppmyModulePy.cpp routines return a Py::Object (see FreeCAD/src/Mod/Part/AppPartPy.cpp).