Converters

Default converters

The following types are convertible

Default converters

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.