Exposing Cplusplus to Python: Difference between revisions

From FreeCAD Documentation
No edit summary
(UnfinishedDocu)
 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{UnfinishedDocu}}
{{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 15:
* return the <tt>Py</tt> object.
* return the <tt>Py</tt> object.


=== Further Elaboration ===
Source: https://forum.freecadweb.org/viewtopic.php?p=314796#p314617

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:
There are two source files required to implement a new Python binding. Assuming we wanted to expose some methods from .../Mod/Part/TopoShape.cpp, we would need to make:
# <tt>xxxxxPyImp</tt> routines return a <tt>PyObject*</tt> pointer (see <tt>TopoShapePyImp.cpp</tt>)
* TopoShapePy.xml - definitions of the functions for be exposed in XML format. This file is used to generate header files for our next file...
# <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>]).
* 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 .../Mod/Part/App/CMakeLists.txt for an example.


=== Related Links ===
You can extend the Python version of your module by adding to ../Mod/myModule/App/AppmyModulePy.cpp (see ../Mod/Part/AppPartPy.cpp). The additions are accessed in Python by "import myModule".


* Source: https://forum.freecadweb.org/viewtopic.php?p=314796#p314617
Note: xxxxxPyImp routines return a PyObject* pointer (see TopoShapePyImp.cpp) and AppmyModulePy.cpp routines return a Py::Object (see ../Mod/Part/AppPartPy.cpp).
* [https://forum.freecadweb.org/viewtopic.php?p=560639#p560639 Forum discussion: Adding Commands in Python to C++ Workbench]
* Another forum thread: https://forum.freecadweb.org/viewtopic.php?f=10&t=70750
* [[Workbench creation]]


[[Category:Developer Documentation]]
[[Category:Developer Documentation]]

Latest revision as of 09:12, 24 September 2022

This documentation is not finished. Please help and contribute documentation.

GuiCommand model explains how commands should be documented. Browse Category:UnfinishedDocu to see more incomplete pages like this one. See Category:Command Reference for all commands.

See WikiPages to learn about editing the wiki pages, and go to Help FreeCAD to learn about other ways in which you can contribute.

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

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:

  1. xxxxxPyImp routines return a PyObject* pointer (see TopoShapePyImp.cpp)
  2. AppmyModulePy.cpp routines return a Py::Object (see FreeCAD/src/Mod/Part/AppPartPy.cpp).

Related Links