C-Bibliothek in Python mit ctypes

In diesem Beitrag werde ich beschreiben, wie man eine C-Bibliothek in Python verwenden kann. Dazu werde ich ein Projekt erstellen, die Abhängigkeiten mit Conan verwalten, das Projekt mit CMake bauen und abschließend die generierte Bibliothek in Python verwenden. Als Beispiel wird das Skalarprodukt zweier Vektoren berechnet. Außerdem wird die Korrektheit mit Unit Tests von Boost überprüft. Die Projektstruktur ist wie folgt aufgebaut:

conanfile.txt
CMakeLists.txt
dot_product.py
src/
    DotProduct.cpp
    DotProduct.hpp
test/
    main.cpp
    DotProduct.cpp
build/

Conan

Mit Conan können die Abhängigkeiten in C/C++ Projekten  verwalten werden. In simplen Projekten wie diesem werden die Abhängigkeiten in die Datei conanfile.txt eingetragen und konfiguriert. Die Datei sieht so aus:

[requires] 
boost/1.68.0@conan/stable 

[generators] 
cmake 

[options] 
boost:shared=True

Im Bereich requires wird die Abhängigkeit eingetragen. In diesem Projekt wird Boost in Version 1.68.0 verwendet. Im Bereich generators wird die Art des Projektes und die benötigten Dateien eingetragen. Durch den Eintrag cmake werden Dateien erzeugt, die man mit CMake einbinden kann. Damit werden u. A. die Include- und Library-Pfade gesetzt. Im Bereich options wird festgelegt, dass dynamisch gegen die shared objects von Boost gelinkt werden soll.

CMake

Mit CMake wird das Projekt konfiguriert. CMake ist ein Buildsystem, dass man plattformübergreifend einsetzen kann. Die Konfiguration wird in die Datei CMakeLists.txt eingetragen und sieht wie folgt aus:

cmake_minimum_required (VERSION 3.5.1) 
project (DotProduct) enable_testing() 
set(CMAKE_CXX_STANDARD 14) 
set(CMAKE_BUILD_TYPE Debug) include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) 
conan_basic_setup() 
add_library(DotProduct SHARED src/DotProduct.cpp src/DotProduct.hpp) 
add_executable(tests test/main.cpp test/DotProduct.cpp src/DotProduct.hpp) 
target_include_directories(tests PRIVATE src ${CONAN_INCLUDE_DIRS}) target_link_libraries(tests DotProduct ${CONAN_LIBS}) 
add_test(NAME tests COMMAND tests)

In der ersten Zeile wird die kleinstmögliche Version von CMake eingetragen. In der zweiten Zeile wird der Name des Projekts festgelegt. In der dritten Zeile wird das Testing aktiviert. Dadurch kann man nach dem Build mit ctest die Unit Tests ausführen. In den nächsten beiden Zeilen wird die C++ Version auf C++14 und der Build Type auf Debug gesetzt, damit u. A. Debug-Informationen geschrieben werden.

Die nächsten beiden Zeilen binden von Conan erstellte Datei ein und konfigurieren CMake mit den Einträgen aus der Datei.

Mit add_library wird nun der Build der C-Bibliothek beschrieben, die später in Python verwendet werden soll.

Abschließend wird mit ein add_executable ein Build für die Unit Tests erzeugt, die Include- und Linker-Einstellungen werden angepasst und die Tests werden zu CMake hinzugefügt.

Tests

Im Ordner test werden nun die Dateien für die Tests erstellt. Die Datei test/main.cpp enthält nur einen Rahmen:

#define BOOST_TEST_MODULE Dot_Product 
#define BOOST_TEST_DYN_LINK 
#include <boost/test/unit_test.hpp>

Die eigentlichen Tests befinden sich in der Datei test/DotProduct.cpp:

#define BOOST_TEST_DYN_LINK 
#include <boost/test/unit_test.hpp> 
#include "DotProduct.hpp" 

BOOST_AUTO_TEST_CASE(test_case1) { 
    double vec1[] = {2, 2}, vec2[] = {2, 3}; 
    BOOST_TEST(dotProduct(vec1, vec2, 2) == 10); 
} 

BOOST_AUTO_TEST_CASE(test_case2) { 
    double vec1[] = {-1, 0}, vec2[] = {0, 1}; 
    BOOST_TEST(dotProduct(vec1, vec2, 2) == 0); 
} 

BOOST_AUTO_TEST_CASE(test_case3) { 
    double vec1[] = {1, 1, 1}, vec2[] = {2, -3, 4};
    BOOST_TEST(dotProduct(vec1, vec2, 3) == 3); 
}

Die Bibliothek

Der Quellcode für die eigentliche Bibliothek befindet sich im Ordner src. In der Datei src/DotProduct.hpp wird die Funktion dotProduct deklariert, die das Skalarprodukt berechnet und das Ergebnis als double zurückgibt:

extern "C" double dotProduct(double* l, double* r, unsigned int len);

In der Datei src/DotProduct.cpp wird diese Funktion definiert:

#include "DotProduct.hpp" 

double dotProduct(double *l, double *r, unsigned int len) { 
    double sum(0); 
    
    while (len--) { 
        sum += l[len] * r[len]; 
    } 
    return sum; 
}

Build

Der Build des Projekts erfolgt im Verzeichnis build. Dazu wird das aktuelle Arbeitsverzeichnis mit cd auf build gesetzt. Nun werden zunächst die Abhängigkeiten mit Conan installiert:

conan install .. --build missing

Anschließend wird das CMake Projekt generiert und konfiguriert:

cmake ..

Mit

cmake --build .

werden die Bibliothek und die Unit Tests gebaut. Als letztes sollte die Bibliothek mit den Tests überprüft werden:

ctest

Python

Abschließend soll die Bibliothek in Python verwendet werden. Dazu wird ein Skript in dot_product.py erstellt:

import ctypes

def dot_product(v1, v2):    
    l = len(v1)    
    if l != len(v2):        
        return 0    
    vec1 = (ctypes.c_double * l)(*v1)    
    vec2 = (ctypes.c_double * l)(*v2)    
    Dot_Product = ctypes.CDLL("build/lib/libDotProduct.so")      
    Dot_Product.dotProduct.argtypes = [ctypes.POINTER(ctypes.c_double), ctypes.POINTER(ctypes.c_double), ctypes.c_int]    
    Dot_Product.dotProduct.restype = ctypes.c_double
    return Dot_Product.dotProduct(vec1, vec2, l)

vec1 = [2, 2]
vec2 = [2, 3]
print("{} * {} = {}".format(vec1, vec2, dot_product(vec1, vec2)))

Das Modul ctypes wird verwendet, um shared objects zu laden. Zuerst wird eine Funktion erzeugt, der zwei Listen übergeben werden. Am Anfang der Funktion wird überprüft, ob beide Listen die gleiche Länge haben. An dieser Stelle wird der Wert 0 zurückgegeben, wenn sich die Längen unterscheiden. Dies lässt sich durch eine Fehlerbehandlung mit Exceptions verbessern.

Im nächsten Schritt werden die Listen in ctypes-Arrays vom Typ c_double umgewandelt. Danach wird das shared object geladen. Anschließend werden die Typen der Funktionsparameter und des Rückgabewertes festgelegt. Abschließend wird die Funktion aus der C-Bibliothek aufgerufen und das berechnete Skalarprodukt wird zurückgegeben.

Um die neue Python-Funktion zu testen, werden zwei Listen erstellt und als Parameter an diese Funktion übergeben. Natürlich empfehlen sich auch an dieser Stelle automatische Unit Tests.

Fazit

Es wurde ein CMake-Projekt erstellt, in dem die Abhängigkeiten mit Conan verwaltet werden. Im Projekt wurden eine C-Bibliothek und Unit Tests erzeugt. Die Korrektheit der C-Bibliothek wurde getestet und abschließend wurde die Bibliothek in Python verwendet.

Schreibe einen Kommentar