From 6ceb005d00728b22a33d0e6a8a392382a952db35 Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Mon, 21 Oct 2024 11:14:06 +0200 Subject: [PATCH] More documentation --- include/util_caching/python_bindings.hpp | 167 ++++++++++++++--------- 1 file changed, 104 insertions(+), 63 deletions(-) diff --git a/include/util_caching/python_bindings.hpp b/include/util_caching/python_bindings.hpp index 97990ec..5d779da 100644 --- a/include/util_caching/python_bindings.hpp +++ b/include/util_caching/python_bindings.hpp @@ -12,98 +12,139 @@ namespace py = pybind11; namespace number_based { namespace internal { + +/*! + * \brief Bind the comparison policies to the Cache class + * + * This function binds the comparison policies to the Cache class. The policies + * are passed as variadic template arguments. The function overloads the + * `cached` function for each policy. + */ template -void bindPolicies(py::class_>& cacheClass) { - (cacheClass.def( - "cached", - [](CacheT& self, const NumberT& key, const ComparisonPolicyTs& policy) { - return self.template cached(key, policy); - }, - py::arg("key"), - py::arg("policy")), - ...); +void bindPolicies(py::class_> &cacheClass) { + (cacheClass.def( + "cached", + [](CacheT &self, const NumberT &key, const ComparisonPolicyTs &policy) { + return self.template cached(key, policy); + }, + py::arg("key"), py::arg("policy")), + ...); } } // namespace internal +/*! + * \brief Bind the ApproximateNumber policy + * + * This function adds bindings for the ApproximateNumber policy to the given + * python module under the given name. + */ template -void bindApproximatePolicy(py::module& module, const std::string& name = "ApproximateNumber") { - using ApproximateNumberT = policies::ApproximateNumber; - py::class_>(module, name.c_str()) - .def(py::init(), py::arg("threshold")) - .def("__call__", &ApproximateNumberT::operator(), "Compare two numbers"); +void bindApproximatePolicy(py::module &module, + const std::string &name = "ApproximateNumber") { + using ApproximateNumberT = policies::ApproximateNumber; + py::class_>( + module, name.c_str()) + .def(py::init(), py::arg("threshold")) + .def("__call__", &ApproximateNumberT::operator(), "Compare two numbers"); } /*! * \brief Bindings for a Cache that is based on number comparisons * - * This function binds the Cache class for a specific number-based key type (NumberT) and value type (ValueT). - * Call this function once inside PYBIND11_MODULE macro to create a Python module with the bindings. + * This function binds the Cache class for a specific number-based key type + * (NumberT) and value type (ValueT). Optionally, add a list of comparison + * policies to the list of template parameters. The `cached` function will be + * overloaded for each one of them. Call this function once inside + * PYBIND11_MODULE macro to create the bindings for the Cache class. */ template -void bindCache(py::module& module) { - using CacheT = Cache; - py::class_> cache(module, "Cache"); - cache - .def(py::init<>()) - // We cannot pass template parameters to python functions, therefore we need to explicitly bind all - // instantiations to different python functions. - // We need to use the lambdas here to handle the seconds argument, defining the comparison policy. - .def( - "cached", - [](CacheT& self, const NumberT& key) { return self.template cached>(key); }, - py::arg("key")) - .def("cache", &CacheT::cache, py::arg("key"), py::arg("value")) - .def("reset", &CacheT::reset); - - internal::bindPolicies(cache); +void bindCache(py::module &module) { + using CacheT = Cache; + py::class_> cache(module, "Cache"); + cache + .def(py::init<>()) + // We cannot pass template parameters to python functions, therefore we + // need to explicitly bind all instantiations to different python + // functions. We need to use the lambdas here to handle the seconds + // argument, defining the comparison policy. + .def( + "cached", + [](CacheT &self, const NumberT &key) { + return self.template cached>(key); + }, + py::arg("key")) + .def("cache", &CacheT::cache, py::arg("key"), py::arg("value")) + .def("reset", &CacheT::reset); + + internal::bindPolicies(cache); } } // namespace number_based namespace time_based { - namespace internal { + +/*! + * \brief Bind the comparison policies to the Cache class + * + * This function binds the comparison policies to the Cache class. The policies + * are passed as variadic template arguments. The function overloads the + * `cached` function for each policy. + */ template -void bindPolicies(py::class_>& cache) { - (cache.def( - "cached", - [](CacheT& self, const TimeT& key, const ComparisonPolicyTs& policy) { - return self.template cached(key, policy); - }, - py::arg("key"), - py::arg("policy")), - ...); +void bindPolicies(py::class_> &cache) { + (cache.def( + "cached", + [](CacheT &self, const TimeT &key, const ComparisonPolicyTs &policy) { + return self.template cached(key, policy); + }, + py::arg("key"), py::arg("policy")), + ...); } } // namespace internal +/*! + * \brief Bind the ApproximateTime policy + * + * This function adds bindings for the ApproximateTime policy to the given + * python module under the given name. + */ template -void bindApproximatePolicy(py::module& module, const std::string& name = "ApproximateTime") { - using ApproximateTimeT = policies::ApproximateTime; - py::class_>(module, name.c_str()) - .def(py::init(), py::arg("threshold")) - .def("__call__", &ApproximateTimeT::operator(), "Compare two time points"); +void bindApproximatePolicy(py::module &module, + const std::string &name = "ApproximateTime") { + using ApproximateTimeT = policies::ApproximateTime; + py::class_>(module, + name.c_str()) + .def(py::init(), py::arg("threshold")) + .def("__call__", &ApproximateTimeT::operator(), + "Compare two time points"); } /*! - * \brief Bindings for a Cache that is based on time comparisons + * \brief Bindings for a Cache that is based on time comparisons. * - * This function binds the Cache class for a specific time-based key type (TimeT) and value type (ValueT). - * Call this function once inside PYBIND11_MODULE macro to create a Python module with the bindings. + * This function binds the Cache class for a specific time-based key type + * (TimeT) and value type (ValueT). Optionally, add a list of comparison + * policies to the list of template parameters. The `cached` function will be + * overloaded for each one of them. Call this function once inside + * PYBIND11_MODULE macro to create the bindings for the Cache class. */ template -void bindCache(py::module& module) { - using CacheT = Cache; - - py::class_> cache(module, "Cache"); - cache.def(py::init<>()) - .def( - "cached", - [](CacheT& self, const TimeT& key) { return self.template cached>(key); }, - py::arg("key")) - .def("cache", &CacheT::cache, py::arg("key"), py::arg("value")) - .def("reset", &CacheT::reset); - - internal::bindPolicies(cache); +void bindCache(py::module &module) { + using CacheT = Cache; + + py::class_> cache(module, "Cache"); + cache.def(py::init<>()) + .def( + "cached", + [](CacheT &self, const TimeT &key) { + return self.template cached>(key); + }, + py::arg("key")) + .def("cache", &CacheT::cache, py::arg("key"), py::arg("value")) + .def("reset", &CacheT::reset); + + internal::bindPolicies(cache); } } // namespace time_based