Converters
Default converters
The following types are convertible
C++ type |
Python type |
Bidirectional |
Note |
---|---|---|---|
int/long |
int |
yes |
|
double |
float |
yes |
|
std::complex<double> |
complex |
yes |
|
std::string |
str |
yes |
|
std::vector<T> |
list |
yes |
if T is convertible |
std::tuple<T…> |
tuple |
yes |
if T… are convertible |
std::pair<T1, T2> |
tuple |
yes |
if T1, T2 are convertible |
std::function<R(T…)> |
lambda |
yes |
if R, T… are convertible |
std::variant<T…> |
tuple |
yes |
if T… are convertible |
std::map<K, V> |
dict |
yes |
if K, V are convertible |
std::array<T, N> |
list |
yes |
if T is convertible |
std::optional<T> |
Convertion of T or None |
yes |
If T is convertible |
std::span<std::byte> |
bytes |
Python -> C++ only |
Note that convertibility is composable: std::vector<T>
is convertible is T
is,
so std::vector<std::tuple<T, U , W>>
is if T,U,W
are.
py_converter
In order to define a custom converter, specialize the c2py::py_converter
struct.
template <typename T> struct py_converter {
// C++ to python.
static PyObject *c2py(auto &&x);
// Python to C++
// Return true iif the object can A PRIORI be converted.
// It is a normally type check.
// An error may still occurr in the conversion, e.g. int overflow.
// raise_exception : in case of failure, sets an error message as a python exception.
static bool is_convertible(PyObject *ob, bool raise_exception) noexcept;
// Python to C++
// Convert, assuming that is_convertible is true
// Can still throw C++ exception.
// Returns a T or a T & (for wrapped types).
static [T & | T] py2c(PyObject *ob);
};
Third party library [developer corner]
In order for a third party library to provide converters
Write the specialization of the converters for the types provided by the library in e.g. converters.hpp
In the library includer e.g. my_library/my_library.hpp, include the converters conditionally
// my_library/my_library.hpp file
// ...
//
#ifdef C2PY_INCLUDED
#include <my_library/converters.hpp>
#endif
The c2py library defines the C2PY_INCLUDED macro, so including the library like
#include <c2py/c2py.hpp>
#include <my_library/my_library.hpp>
will automatically include the converters when c2py is included. For a concrete example, cf e.g. the TRIQS nda library.