template for a FreeCAD workbench / module
As python imports seems not that easy to understand, this template should show the way how extensions work in future versions of FreeCAD.
Due to the fact we are now using the pktutil-module to find extension of freecad, it's possible to use standart-paths of pyton to place the extension. This is any location which is included in the sys.path. To get a list of all the locations simple run this code in the FreeCAD-console:
ìmport sys sys.path
- init.py: optional, is called at startup. With gui and without gui.
- init_gui.py: mandatory for modules adding new functionality to the gui
minimal structure of a freecad-workbench/module for python2 and 3
freecad/ ├── __init__.py └── template_extension/ ├── __init__.py ├── init_gui.py └── (init.py)
minimal structure of a freecad-workbench/module for python3 (only)
freecad/ └── template_extension/ ├── __init__.py ├── init_gui.py └── (init.py)
Do not place code into
freecad/__init__.py. These files are only used to let pkgutil find your extension with python2.
init_gui.py get called at startup of FreeCAD. Do not put very time-intensive code in these files to reduce the start-up time.
the "freecad" namespace is not allowed to be used directly. this means it is not allowed to set any variables in the
__init__.py of freecad. (But as with python3 this
__init__.py should not exist anyway, this isn't a problem.)
Further it's not allowed to add variables to the freecad-namespace directly. This can introduce name-clashes (although the chance it really is a problem is quite small)
freecad.myVariable = 10
freecad.app.myVariable = 10
test your module/ workbench
If you want to work on your extension you have the following options:
- start FreeCAD from the root-directory you are working in (eg. TemplateExtension)
- simple link the extension to a location where python can find it.
- pip install -e . adds the root-directory to easy_install.path.
using pip (setuptool or distutlis)
Currently freecad has several ways to install packages , . With pip and pypi a third option is introduced. Using pip will give advanced possebilities to install dependencies.
setup.py file located in the main directory is a minimal example to get a extension installed. There we are using setuptools. If you need advanced options to install your package, please have a look at the documentation of [setuptools](here: https://setuptools.readthedocs.io/en/latest/).
Additional to the
setup.py there is often the need for a
MANIFEST.in With this file it's possible to install data like icons, documentation files, ... (everything not directly connected to python).
To tell setuptools to use the
MANIFEST.in add this line to the setup function in the setup.py:
you can specify required packages by setting the
install_requires in the setup-function of the
setup(..., install_requires=['required_package'], ...)
To install your extension locally with pip, do the following from a cmd (windows) or terminal (unix):
cd <path_to_your_package> pip install .
uploading your package to pypi
Please have a look at this tutorial
Be carfully with version-numbering. It seems pypi doesn't allow to upload a package with a version smaller then the biggest version of the package uploaded. This seems to be true also for deleted packages and deleted verions.
Once uploaded the package can be installed with:
pip install <package-name>