pbp_include.h

Go to the documentation of this file.

/** @file pbp_include.h Includes all luabindings plug-in headers */
 
/*
 **************************************************** 
 Convenience header file that includes all headers
 relevant to the pybindings plug-in. 
 
 (c) Thomas Moor 2023 - 2026
 ****************************************************
 */
 
 
#ifndef FAUDES_PBP_INCLUDE_H
#define FAUDES_PBP_INCLUDE_H
 
// include all headers for this plugin
#include "pbp_addons.h"
 
 
/**
 
@defgroup PybindingsPlugin Python Bindings Plug-In
 
 
@ingroup AllPlugins
 
<p>
This plug-in implements libFAUDES bindings for the scripting language
<a href="https://www.python.org">Python</a>. 
Relevant libFAUDES data types and functions as documented via the <a href="https://fgdes.tf.fau.de/faudes/reference">libFAUDES User Reference</a>
can be accessed from within the Python interpreter.
For user documentation/introduction specifically for the faudes Python module,
see the
<a href="https://fgdes.tf.fau.de/faudes/pythonmod">libFAUDES Python API</a>.
<p>
 
 
</p>
The most convenient method
to make the faudes Python module available is to install it via <tt>pip</tt>; i.e., for
Linux and macOS
</p>
 
@code{.unparsed}
$ pip install faudes
$ python3 -c "import faudes; print(faudes.Version())"
@endcode
 
or, for native Windows
 
@code{.unparsed}
> py -m pip install faudes
> py -c "import faudes; print(faudes.Version())"
@endcode
 
<p>
This will search the index <a href="https://pypi.org/project/faudes/">PyPI</a>
for a binary distribution that fits your platform/archirectur. In the case
no such matching binary is present, please let us know. Instructions on how
to compile your own binary are below.
</p>
 
 
 
 
@subsection SecPybindingsIntro1 Example Script
 
@code{.unparsed}
# load libFAUDES bindings
from faudes import *
 
# test
Version()
Build()
 
# instantiate generator from Python lists                                                
g = Generator.NewFromLists(
  delta=[
    ['idle', 'alpha', 'busy'],
    ['busy', 'beta',  'idle']],
  Q0 =[ 'idle' ],
  Qm =[ 'idle' ]
)
 
# show on console
g.Write()
 
# show graphically, i.e., in Jupyter notebook
g.GraphShow()
@endcode
 
<p>
Note: for graphics output you must have installed <tt>dot</tt> from the GraphViz package.
If <tt>dot</tt> is not in the systems path, you may direct libFAUDES via
</p>
 
@code{.unparsed}
DocPath("/wherever_dot_is/dot").
@endcode
 
 
 
@subsection SecPybindingsIntro3 Building the libFAUDES Python Modeul
 
<p>
The faudes Python module consists of the glue code <tt>faudes.py</tt> and a suitably
extended libFAUDES shrared object <tt>_faudes.so</tt> (or <tt>_faudes.pyd</tt> for Windows).
Both files are generated by the libFAUDES build system; see
<a href="../faudes_build.html">build-system documentation</a> for details.
Manualy copying/renaming both files to a project folder enables the import of the
faudes module from Python scripts in that folder.
</p>
 
<p>
Example for the overall build process incl. copy/rename:
<p>
 
@code{.unparsed}
./libFAUDES$ make dist-clean
./libFAUDES$ make -j configure
./libFAUDES$ make -j 
./libFAUDES$ cp plugings/pybindings/obj/faudes.py whereever/
./libFAUDES$ cp plugings/pybindings/obj/_faudes.so whereever/
./libFAUDES$ cd whereever
./whereever$ python3 -c "import faudes; print(faudes.Version())"
@endcode
 
<p>
The above method is specifically recommended for MSYS environments where pip install
from PyPI.org will fail.
</p>
 
 
@subsection SecPybindingsIntro4 Building the Module as Python Wheel
 
<p>
A <i>Python wheel</i> is an archive in a clearly defined format/layout which
among others facilitates binary distribution of Python extenstions e.g. via PyPI.org.
The libFAUDES build system has the dedicated target <tt>pybindings-wheel</tt>
that utilises the Python module <tt>build</tt> to generate a Python wheel
<tt>faudes-*.whl</tt>. The latter can be installed via <tt>pip</tt>.
The benefit of this approach is that Python <tt>build</tt> takes care of matching
toolchains etc. and that after installing the the module files do not need
to be copied to each relevant project folder.
The downside is that Python <tt>build</tt> wont use parallel jobs and therefore
can take quite some time. 
</p>
 
<p>
Example for the overall build process incl. installation:
<p>
 
@code{.unparsed}
./libFAUDES$ make dist-clean
./libFAUDES$ make -j configure
./libFAUDES$ make pybindings-wheel
./libFAUDES$ pip install faudes-2.34.0-cp314-cp314-macosx_10_15_universal2.whl
@endcode
 
<p>
Alternatively, you may download the configured source from PyPI and invoke <tt>build</tt>
directly; e.g. for Windows with official Python distribution and MSVC installed
</p>
@code{.unparsed}
./faudes-2.34> py -m build --wheel --outdir=./
@endcode
 
 
<p>
Again, this method is of specific interest for MSYS environments where pip install
from PyPI.org will fail. You will need to install the matching Python module <tt>build</tt>
via the MSYS package manager <tt>pacman</tt>.
</p>
 
 
@subsection PyLicense License
 
The Python bindings plug-in is distributed with libFAUDES. 
All code is  provided under terms of the LGPL. 
 
 
Copyright (c) 2023 - 2026 Thomas Moor.
 
 
 
*/
 
 
 
#endif