Add Python bindings

CMakeLists.txt

@@ -152,4 +152,4 @@ install(DIRECTORY ${PROJECT_SOURCE_DIR}/include/
 include(cpack_config)
 include(CPack)
 
-message(STATUS "Components to pack: ${CPACK_COMPONENTS_ALL}")
+message(STATUS "Components to pack: ${CPACK_COMPONENTS_ALL}")

Dockerfile

@@ -14,7 +14,11 @@ RUN apt-get update && \
       cmake \
       libgoogle-glog-dev \
       libgtest-dev \
-      libyaml-cpp-dev && \
+      libyaml-cpp-dev \
+      pybind11-dev \
+      python3-dev \
+      python3-pybind11 \
+      python3-yaml && \
     apt-get clean
 
 # Install Crow dependencies

README.md

@@ -26,6 +26,8 @@
   Your behavior is unreliable or unsafe? Arbitrators will gracefully fall back to the next-best option.
 - 📦 **Header-Only**  
   Simple integration – just include this header-only C++ library!
+- 🐍 **Python Bindings**  
+  For easy prototyping, testing, and integration of machine learning algorithms, all the functionality is available via Python bindings.
 - 📜 **Permissive License**  
   Published under MIT license to ensure maximum flexibility for your projects.
 
@@ -94,6 +96,7 @@ First make sure all dependencies are installed:
 - [yaml-cpp](https://github.com/jbeder/yaml-cpp)
 - [Googletest](https://github.com/google/googletest) (optional, if you want to build unit tests)
 - [Crow](https://crowcpp.org) (optional, needed for GUI only)
+- [pybind11](https://pybind11.readthedocs.io/en/stable/) (optional, if you want to build Python bindings and Python unit tests)
 
 See also the [`Dockerfile`](./Dockerfile) for how to install these packages under Debian or Ubuntu.
 </details>
@@ -169,6 +172,31 @@ In order to skip compiling the GUI, use `cmake -DBUILD_GUI=false ..` instead.
 
 </details>
 
+## Python Bindings
+
+The library can be used in Python via pybind11 bindings.
+Since `arbitration_graphs` is a templated C++ library,
+  you need to explicitly instantiate the template for the types you want to use in Python.
+For this, we provide convenience functions to bind the library for the desired types.
+Simply call them in a pybind11 module definition, e.g.:
+
+```cpp
+PYBIND11_MODULE(arbitration_graphs, m) {
+    python_api::bindArbitrationGraphs<MyCommand>(m);
+}
+```
+and use them in Python.
+For example, you could implement a custom behavior that inherits from the abstract `Behavior` class.
+
+```python
+from arbitration_graphs import Behavior
+
+class MyBehavior(Behavior):
+    def __init__(self, "my_behavior"):
+        super().__init__(name)
+```
+We re-implemented all of the C++ unit tests in Python, so take a closer look at those for more advanced usage examples.
+
 
 ## Development
 
@@ -193,6 +221,9 @@ There, you can edit the source code, compile and run the tests etc.
 <details>
 <summary>Compiling unit tests</summary>
 
+To compile and run the C++ unit tests, make sure Googletest is available.
+For the Python tests, make sure pybind11 is installed.
+
 In order to compile with tests define `BUILD_TESTS=true`
 ```bash
 mkdir -p arbitration_graphs/build
@@ -201,15 +232,13 @@ cmake -DBUILD_TESTS=true ..
 cmake --build . -j9
 ```
 
-Run all unit tests with CTest:
+Run all unit tests (C++ and Python) with CTest:
 
 ```bash
 cmake --build . --target test
 ```
-
 </details>
 
-
 <details>
 <summary>Serving the WebApp GUI</summary>
 
@@ -287,6 +316,7 @@ This library and repo has been crafted with ❤️ by
 Christoph and Piotr coded the core in a pair-programming session.
 Piotr also contributed the GUI and GitHub Page.
 Nick implemented the awesome PacMan demo and tutorial, with drafting support by Christoph, reviews and finetuning by Piotr.
+The Python bindings have been contributed by Nick and reviewed py Piotr.
 
 The repository is maintained by Piotr Spieker&nbsp;
 <a href="https://github.com/orzechow" aria-label="View GitHub profile">
@@ -381,4 +411,4 @@ _Martin Lauer, Roland Hafner, Sascha Lange, and Martin Riedmiller, “Cognitive
 }
 ```
 
-</details>
+</details>

include/arbitration_graphs/internal/arbitrator_py.hpp

@@ -0,0 +1,114 @@
+#pragma once
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+#include <yaml-cpp/yaml.h>
+
+#include "../arbitrator.hpp"
+#include "../behavior.hpp"
+
+namespace arbitration_graphs::python_api {
+
+namespace py = pybind11;
+
+template <typename CommandT, typename SubCommandT, typename VerifierT, typename VerificationResultT>
+class PyArbitratorOption : public Arbitrator<CommandT, SubCommandT, VerifierT, VerificationResultT>::Option {
+public:
+    using BaseT = typename Arbitrator<CommandT, SubCommandT, VerifierT, VerificationResultT>::Option;
+    using FlagsT = typename BaseT::FlagsT;
+
+    explicit PyArbitratorOption(const typename Behavior<SubCommandT>::Ptr& behavior, const FlagsT& flags)
+            : BaseT(behavior, flags) {
+    }
+
+    std::string toYamlAsString(const Time& time) const {
+        YAML::Emitter out;
+        out << BaseT::toYaml(time);
+        return out.c_str();
+    }
+};
+
+template <typename CommandT, typename SubCommandT, typename VerifierT, typename VerificationResultT>
+class PyArbitrator : public Arbitrator<CommandT, SubCommandT, VerifierT, VerificationResultT> {
+public:
+    using BaseT = Arbitrator<CommandT, SubCommandT, VerifierT, VerificationResultT>;
+
+    explicit PyArbitrator(const std::string& name = "Arbitrator", const VerifierT& verifier = VerifierT())
+            : BaseT(name, verifier) {
+    }
+
+    // NOLINTBEGIN(readability-function-size)
+    CommandT getCommand(const Time& time) override {
+        PYBIND11_OVERRIDE_PURE_NAME(CommandT, BaseT, "get_command", getCommand, time);
+    }
+
+    void addOption(const typename BaseT::Option::Ptr& behavior, const typename BaseT::Option::FlagsT& flags) {
+        PYBIND11_OVERRIDE_NAME(void, BaseT, "add_option", addOption, behavior, flags);
+    }
+
+    bool checkInvocationCondition(const Time& time) const override {
+        PYBIND11_OVERRIDE_NAME(bool, BaseT, "check_invocation_condition", checkInvocationCondition, time);
+    }
+
+    bool checkCommitmentCondition(const Time& time) const override {
+        PYBIND11_OVERRIDE_NAME(bool, BaseT, "check_commitment_condition", checkCommitmentCondition, time);
+    }
+
+    void gainControl(const Time& time) override {
+        PYBIND11_OVERRIDE_NAME(void, BaseT, "gain_control", gainControl, time);
+    }
+
+    void loseControl(const Time& time) override {
+        PYBIND11_OVERRIDE_NAME(void, BaseT, "lose_control", loseControl, time);
+    }
+    // NOLINTEND(readability-function-size)
+};
+
+template <typename CommandT,
+          typename SubCommandT = CommandT,
+          typename VerifierT = verification::PlaceboVerifier<SubCommandT>,
+          typename VerificationResultT = typename decltype(std::function{VerifierT::analyze})::result_type>
+void bindArbitrator(py::module& module) {
+    using ArbitratorT = Arbitrator<CommandT, SubCommandT, VerifierT, VerificationResultT>;
+    using PyArbitratorT = PyArbitrator<CommandT, SubCommandT, VerifierT, VerificationResultT>;
+
+    using OptionT = typename ArbitratorT::Option;
+    using PyOptionT = PyArbitratorOption<CommandT, SubCommandT, VerifierT, VerificationResultT>;
+
+    using FlagsT = typename OptionT::FlagsT;
+
+    py::class_<ArbitratorT, PyArbitratorT, Behavior<CommandT>, std::shared_ptr<ArbitratorT>> arbitrator(module,
+                                                                                                        "Arbitrator");
+    arbitrator.def("add_option", &ArbitratorT::addOption, py::arg("behavior"), py::arg("flags"))
+        .def("options", &ArbitratorT::options)
+        .def("get_command", &ArbitratorT::getCommand, py::arg("time"))
+        .def("check_invocation_condition", &ArbitratorT::checkInvocationCondition, py::arg("time"))
+        .def("check_commitment_condition", &ArbitratorT::checkCommitmentCondition, py::arg("time"))
+        .def("gain_control", &ArbitratorT::gainControl, py::arg("time"))
+        .def("lose_control", &ArbitratorT::loseControl, py::arg("time"))
+        .def("__repr__", [](const ArbitratorT& self) { return "<Arbitrator '" + self.name_ + "'>"; });
+
+    py::class_<OptionT, PyOptionT, std::shared_ptr<OptionT>> option(arbitrator, "Option");
+    option
+        .def(py::init<const typename Behavior<SubCommandT>::Ptr&, const FlagsT&>(),
+             py::arg("behavior"),
+             py::arg("flags"))
+        .def("has_flags", &OptionT::hasFlag, py::arg("flags_to_check"))
+        .def(
+            "to_yaml_as_str",
+            [](const OptionT& self, const Time& time) {
+                return static_cast<const PyOptionT&>(self).toYamlAsString(time);
+            },
+            py::arg("time"))
+        .def_readwrite("behavior", &OptionT::behavior_)
+        .def_readwrite("flags", &OptionT::flags_)
+        .def_readwrite("verification_result", &OptionT::verificationResult_);
+
+    py::enum_<typename OptionT::Flags>(option, "Flags")
+        .value("NO_FLAGS", OptionT::NO_FLAGS)
+        .value("INTERRUPTABLE", OptionT::INTERRUPTABLE)
+        .value("FALLBACK", OptionT::FALLBACK)
+        .export_values();
+}
+
+} // namespace arbitration_graphs::python_api

include/arbitration_graphs/internal/behavior_py.hpp

@@ -0,0 +1,78 @@
+#pragma once
+
+#include <pybind11/pybind11.h>
+#include <yaml-cpp/yaml.h>
+
+#include "../behavior.hpp"
+
+namespace arbitration_graphs::python_api {
+
+namespace py = pybind11;
+
+template <typename CommandT>
+class PyBehavior : public Behavior<CommandT> {
+public:
+    using BaseT = Behavior<CommandT>;
+
+    explicit PyBehavior(const std::string& name) : BaseT(name) {
+    }
+
+    // NOLINTBEGIN(readability-function-size)
+    CommandT getCommand(const Time& time) override {
+        PYBIND11_OVERRIDE_PURE_NAME(CommandT, BaseT, "get_command", getCommand, time);
+    }
+
+    bool checkInvocationCondition(const Time& time) const override {
+        PYBIND11_OVERRIDE_NAME(bool, BaseT, "check_invocation_condition", checkInvocationCondition, time);
+    }
+
+    bool checkCommitmentCondition(const Time& time) const override {
+        PYBIND11_OVERRIDE_NAME(bool, BaseT, "check_commitment_condition", checkCommitmentCondition, time);
+    }
+
+    void gainControl(const Time& time) override {
+        PYBIND11_OVERRIDE_NAME(void, BaseT, "gain_control", gainControl, time);
+    }
+
+    void loseControl(const Time& time) override {
+        PYBIND11_OVERRIDE_NAME(void, BaseT, "lose_control", loseControl, time);
+    }
+
+    std::string to_str(const Time& time,
+                       const std::string& prefix = "",
+                       const std::string& suffix = "") const override {
+        PYBIND11_OVERRIDE(std::string, BaseT, to_str, time, prefix, suffix);
+    }
+    // NOLINTEND(readability-function-size)
+
+    std::string toYamlAsString(const Time& time) const {
+        YAML::Emitter out;
+        out << BaseT::toYaml(time);
+        return out.c_str();
+    }
+};
+
+template <typename CommandT>
+void bindBehavior(py::module& module, const std::string& bindingName = "Behavior") {
+    using BehaviorT = Behavior<CommandT>;
+    using PyBehaviorT = PyBehavior<CommandT>;
+
+    py::class_<BehaviorT, PyBehaviorT, std::shared_ptr<BehaviorT>>(module, bindingName.c_str())
+        .def(py::init<const std::string&>(), py::arg("name") = "Behavior")
+        .def("get_command", &BehaviorT::getCommand, py::arg("time"))
+        .def("check_invocation_condition", &BehaviorT::checkInvocationCondition, py::arg("time"))
+        .def("check_commitment_condition", &BehaviorT::checkCommitmentCondition, py::arg("time"))
+        .def("gain_control", &BehaviorT::gainControl, py::arg("time"))
+        .def("lose_control", &BehaviorT::loseControl, py::arg("time"))
+        .def("to_str", &BehaviorT::to_str, py::arg("time"), py::arg("prefix") = "", py::arg("suffix") = "")
+        .def(
+            "to_yaml_as_str",
+            [](const BehaviorT& self, const Time& time) {
+                return static_cast<const PyBehaviorT&>(self).toYamlAsString(time);
+            },
+            py::arg("time"))
+        .def_readonly("name", &BehaviorT::name_)
+        .def("__repr__", [](const BehaviorT& self) { return "<Behavior '" + self.name_ + "'>"; });
+}
+
+} // namespace arbitration_graphs::python_api