Improve signature for doc and error messages

parcollet · parcollet · commit 91e85f7fcef5 · 2025-07-29T11:16:52.000-04:00
- In progress. py_converters for STL type to complete.
diff --git a/src/c2py/converters/basic_types.hpp b/src/c2py/converters/basic_types.hpp
@@ -40,6 +40,7 @@ namespace c2py {
 
   // --- bool
   template <> struct py_converter<bool> {
+    static constexpr const char *tp_name = "bool";
     static PyObject *c2py(bool b) {
       if (b)
         Py_RETURN_TRUE;
@@ -58,6 +59,9 @@ namespace c2py {
 
   namespace details {
     template <typename I> struct py_converter_impl {
+
+      static constexpr const char *tp_name = "int";
+
       static PyObject *c2py(I i) { return PyLong_FromLong(long(i)); }
       static I py2c(PyObject *ob) {
         if (PyLong_Check(ob)) { return I(PyLong_AsLong(ob)); }
@@ -97,6 +101,8 @@ namespace c2py {
   // --- byte
 
   template <> struct py_converter<std::byte> {
+    static constexpr const char *tp_name = "bytes";
+
     static PyObject *c2py(std::byte b) { return PyBytes_FromStringAndSize(reinterpret_cast<char *>(&b), 1); } //NOLINT
     static std::byte py2c(PyObject *ob) { return static_cast<std::byte>(PyBytes_AsString(ob)[0]); }           //NOLINT
     static bool is_convertible(PyObject *ob, bool raise_exception) {
@@ -109,6 +115,8 @@ namespace c2py {
   // --- double
 
   template <> struct py_converter<double> {
+    static constexpr const char *tp_name = "float";
+
     static PyObject *c2py(double x) { return PyFloat_FromDouble(x); }
     static double py2c(PyObject *ob) {
       if (PyFloat_Check(ob) || PyLong_Check(ob)) { return PyFloat_AsDouble(ob); }
diff --git a/src/c2py/converters/stl/complex.hpp b/src/c2py/converters/stl/complex.hpp
@@ -25,6 +25,8 @@ namespace c2py {
   // --- complex
 
   template <> struct py_converter<std::complex<double>> {
+
+    static constexpr const char *tp_name = "complex";
     static PyObject *c2py(std::complex<double> x) { return PyComplex_FromDoubles(x.real(), x.imag()); }
     static std::complex<double> py2c(PyObject *ob) {
       if (PyArray_CheckScalar(ob)) {
diff --git a/src/c2py/converters/stl/pair.hpp b/src/c2py/converters/stl/pair.hpp
@@ -23,6 +23,12 @@ namespace c2py {
 
   template <typename T1, typename T2> struct py_converter<std::pair<T1, T2>> {
 
+    static std::string tp_name() {
+      std::ostringstream out;
+      out << "tuple[" << python_typename<T1>() << ", " << python_typename<T2>() << "]";
+      return out.str();
+    }
+
     template <typename P> static PyObject *c2py(P &&p) {
       static_assert(is_instantiation_of_v<std::pair, std::decay_t<P>>, "Logic error");
       pyref x1 = cxx2py(std::get<0>(std::forward<P>(p)));
diff --git a/src/c2py/converters/stl/string.hpp b/src/c2py/converters/stl/string.hpp
@@ -22,6 +22,8 @@ namespace c2py {
 
   template <> struct py_converter<std::string> {
 
+    static constexpr const char *tp_name = "str";
+
     static PyObject *c2py(std::string const &x) { return PyUnicode_FromString(x.c_str()); }
 
     static std::string py2c(PyObject *ob) { return PyUnicode_AsUTF8(ob); }
diff --git a/src/c2py/converters/stl/tuple.hpp b/src/c2py/converters/stl/tuple.hpp
@@ -26,6 +26,15 @@ namespace c2py {
 
   template <typename... Types> struct py_converter<std::tuple<Types...>> {
 
+    static std::string tp_name() {
+      std::ostringstream out;
+      std::string sep;
+      out << "tuple[";
+      ((out << sep << python_typename<Types>(), sep = ", "), ...);
+      out << "]";
+      return out.str();
+    }
+
     private:
     using tuple_t = std::tuple<Types...>;
 
diff --git a/src/c2py/converters/stl/vector.hpp b/src/c2py/converters/stl/vector.hpp
@@ -17,14 +17,14 @@
 // Authors: Olivier Parcollet, Nils Wentzell
 
 #pragma once
+#include <sstream>
 #include <vector>
 #include <string>
 #include <cstddef>
 
 #include "./common.hpp"
 #include "../../py_converter.hpp"
 #include "../numpy_proxy.hpp"
-
 namespace c2py {
 
   // Convert vector to numpy_proxy, WARNING: Deep Copy
@@ -96,6 +96,12 @@ namespace c2py {
 
   template <typename T> struct py_converter<std::vector<T>> {
 
+    static std::string tp_name() {
+      std::ostringstream out;
+      out << "[" << python_typename<T>() << "]";
+      return out.str();
+    }
+
     template <typename V> static PyObject *c2py(V &&v) {
       static_assert(is_instantiation_of_v<std::vector, std::decay_t<V>>, "Logic error");
       using value_type = typename std::remove_reference_t<V>::value_type;
diff --git a/src/c2py/cpp_name.hpp b/src/c2py/cpp_name.hpp
@@ -14,6 +14,9 @@ namespace c2py {
   // FIXME : constexpr when implemented in clang 2b
   template <typename T> static inline const std::string cpp_name = trim(replacenl(std::string{util::type_name<T>()})); // typeid(T).name();
 
+  template <typename T> static constexpr char *tp_name = nullptr; //NOLINT
+
+  // cLEAN THIS
   // FIXME : if the first option is not ok, we have to enumerate all basic types , etc...
   // And specialize for all converters ?
   //template <> inline const std::string cpp_name<int>                      = "int";
diff --git a/src/c2py/dyn_dispatch/dispatcher.cpp b/src/c2py/dyn_dispatch/dispatcher.cpp
@@ -0,0 +1,48 @@
+#include "dispatcher.hpp"
+
+namespace c2py {
+  template <typename Eraser, bool Constructors>
+  PyObject *dispatcher_t<Eraser, Constructors>::call_impl(PyObject *self, PyObject *args, PyObject *kwargs) const {
+
+    for (auto const &ov : ov_list)
+      if (ov->is_callable(self, args, kwargs)) return ov->operator()(self, args, kwargs);
+
+    // The call has failed. We rerun, but raising the exception in each case, and report
+    std::stringstream err;
+    err << "[c2py] Can not call the function with the arguments\n";
+    //if (self) err << "  - " << PyUnicode_AsUTF8(pyref{PyObject_Str(self)}) << "\n";
+    if (args) err << "   " << PyUnicode_AsUTF8(pyref{PyObject_Str(args)}) << "\n";
+    if (kwargs) err << "   " << PyUnicode_AsUTF8(pyref{PyObject_Str(kwargs)}) << "\n";
+    err << "The dispatch to C++ failed with the following error(s):\n";
+    int c = 0;
+    for (auto const &ov : ov_list) {
+      ++c;
+      ov->is_callable(self, args, kwargs, true);
+      err << "[" << c << "] " << ov->signature() << "\n    -- " << c2py::get_python_error() << "\n\n";
+    }
+    PyErr_SetString(PyExc_TypeError, err.str().c_str());
+    return nullptr;
+  }
+
+  // overload doc (string) in case only one overload ...
+  // FIXME : to make generated code simpler in most cases.
+  template <typename Eraser, bool Constructors>
+  [[nodiscard]] std::string dispatcher_t<Eraser, Constructors>::doc(std::initializer_list<const char *> const &docs) const {
+    assert(docs.size() == ov_list.size()); // by construction for the automated tool
+    std::stringstream fs;
+    fs << "Dispatched C++ function\n";
+    // should use itertools ?
+    //for (auto &&[n, ov] : itertools::enumerate(ov_list)) { fs << "[" << n + 1 << "]  " << ov->signature() << "\n"; }
+    int n = 1;
+    for (auto const &ov : ov_list) fs << "[" << n++ << "]  " << ov->signature() << "\n";
+    fs << "\n";
+    for (auto const &x : docs) { fs << x << "\n"; }
+    return fs.str();
+  }
+
+  template struct dispatcher_t<pycfun_kw, false>;
+  template struct dispatcher_t<pycfun_kw, true>;
+  template struct dispatcher_t<pycfun23, false>;
+  template struct dispatcher_t<pycfun23, true>;
+
+} // namespace c2py
diff --git a/src/c2py/dyn_dispatch/dispatcher.hpp b/src/c2py/dyn_dispatch/dispatcher.hpp
@@ -13,28 +13,7 @@ namespace c2py {
     template <typename... U> dispatcher_t(U &&...u) { ((void)ov_list.push_back(std::forward<U>(u)), ...); }
 
     private:
-    // impl detail of ()
-    PyObject *call_impl(PyObject *self, PyObject *args, PyObject *kwargs) const {
-
-      for (auto const &ov : ov_list)
-        if (ov->is_callable(self, args, kwargs)) return ov->operator()(self, args, kwargs);
-
-      // The call has failed. We rerun, but raising the exception in each case, and report
-      std::stringstream err;
-      err << "[c2py] Can not call the function with the arguments\n";
-      //if (self) err << "  - " << PyUnicode_AsUTF8(pyref{PyObject_Str(self)}) << "\n";
-      if (args) err << "  - " << PyUnicode_AsUTF8(pyref{PyObject_Str(args)}) << "\n";
-      if (kwargs) err << "  - " << PyUnicode_AsUTF8(pyref{PyObject_Str(kwargs)}) << "\n";
-      err << "The dispatch to C++ failed with the following error(s):\n";
-      int c = 0;
-      for (auto const &ov : ov_list) {
-        ++c;
-        ov->is_callable(self, args, kwargs, true);
-        err << "[" << c << "] " << ov->signature() << "\n    " << c2py::get_python_error() << "\n";
-      }
-      PyErr_SetString(PyExc_TypeError, err.str().c_str());
-      return nullptr;
-    }
+    PyObject *call_impl(PyObject *self, PyObject *args, PyObject *kwargs) const;
 
     public:
     // Call each overload. The first available is used.
@@ -56,18 +35,7 @@ namespace c2py {
 
     // overload doc (string) in case only one overload ...
     // FIXME : to make generated code simpler in most cases.
-    [[nodiscard]] std::string doc(std::initializer_list<const char *> const &docs) const {
-      assert(docs.size() == ov_list.size()); // by construction for the automated tool
-      std::stringstream fs;
-      fs << "Dispatched C++ function\n";
-      int i = 0;
-      // FIXME : use format when in std
-      for (auto const &x : docs) {
-        fs << "[" << i + 1 << "]  " << ov_list[i]->signature() << "\n\n" << x << "\n\n";
-        ++i;
-      }
-      return fs.str();
-    }
+    [[nodiscard]] std::string doc(std::initializer_list<const char *> const &docs) const;
   };
 
   // ==============================
diff --git a/src/c2py/dyn_dispatch/pycfun_kw.cpp b/src/c2py/dyn_dispatch/pycfun_kw.cpp
@@ -85,10 +85,23 @@ bool c2py::pycfun_kw::is_callable(PyObject *, PyObject *args, PyObject *kwargs,
 // --------------------------------
 
 std::string c2py::pycfun_kw::signature() const {
-  auto res = "("
-     + join(
-                c_arguments, [](auto &&a) { return a.name + ": " + trim(*a.type_name); }, ", ");
-  return (this->rtype_name ? res + ") -> " + (*this->rtype_name) : res + ")");
+  // splitting strategy to be improved
+  auto sign = [&](bool split_lines) {
+    const char *sep = split_lines ? ",\n      " : ", ";
+    auto res        = join(
+       c_arguments,
+       [](argument_t const &a) {
+         return a.name + ": " + trim(a.python_typename()) + (a.default_value_printer ? " = " + a.default_value_printer(a.default_value) : "");
+       },
+       sep);
+    auto rtype_name = this->python_return_typename();
+    return "(" + (!rtype_name.empty() ? res + ")\n    -> " + rtype_name : res + ")");
+  };
+  auto res = sign(false);
+  if (res.size() > 100)
+    return sign(true);
+  else
+    return res;
 }
 
 // --------------------------------
diff --git a/src/c2py/dyn_dispatch/pycfun_kw.hpp b/src/c2py/dyn_dispatch/pycfun_kw.hpp
@@ -1,4 +1,7 @@
 #pragma once
+#include <optional>
+#include <ratio>
+#include <sstream>
 #include <type_traits>
 #include <vector>
 #include <any>
@@ -13,16 +16,32 @@ namespace c2py {
   // has raised an exception
   struct exception_raised_in_python {};
 
+  template <typename T> std::string default_value_repr(std::any const &v) {
+    std::ostringstream oss;
+    using U = std::decay_t<T>; // just in case
+    if constexpr (std::is_same_v<U, std::string>)
+      oss << '"' << std::any_cast<T>(v) << '"';
+    else if constexpr (std::is_same_v<U, bool>)
+      oss << (std::any_cast<T>(v) ? "True" : "False");
+    else if constexpr (std::is_same_v<U, std::nullopt_t> or std::is_same_v<U, std::nullptr_t>)
+      oss << "None";
+    else if constexpr (requires { oss << T{}; })
+      oss << std::any_cast<T>(v);
+    else
+      oss << "<unprintable>";
+    return oss.str();
+  }
   // =====================  argument_t ===========================
 
   // Handle one argument of a dynamically dispatched function pycfun_kw
   // Erase the C++ type and convertible call
   // We need a set of erased argument to determine which function to call
   struct argument_t {
     std::string name;                  // name of the argument. Can be empty
-    std::string const *type_name;      // Name of the C++ type for error. FIXME : Python AND C++ names?
+    std::string (*python_typename)();  // Name of the type in Python, for doc
     bool (*is_conv)(PyObject *, bool); // eraser of py_converter<T>::is_convertible
     std::any default_value;            // the value. Can be none.
+    std::string (*default_value_printer)(std::any const &) = nullptr;
 
     [[nodiscard]] bool has_default() const { return default_value.has_value(); }
 
@@ -36,26 +55,30 @@ namespace c2py {
   // First one for argument without a default value.
   template <typename A> auto make_argument(std::string const &name) {
     return argument_t{name,
-                      &cpp_name<A>,
+                      python_typename<std::decay_t<A>>,
                       [](PyObject *ob, bool re) -> bool { return py_converter<std::decay_t<A>>::is_convertible(ob, re); },
                       // &py_converter<std::decay_t<A>>::is_convertible, // I use a lambda as in some cases, is_convertible
                       // can have optional parameters (e.g. nda::array_view), so the cast of the pointer does not compile
+                      {},
                       {}};
   }
   // Second one with for an argument with a default value.
   template <typename A, typename T> auto make_argument(nv_pair<T> &&nvp) {
-    return argument_t{std::move(nvp).name, &cpp_name<A>,
-                      [](PyObject *ob, bool re) -> bool { return py_converter<std::decay_t<A>>::is_convertible(ob, re); },
-                      A{std::move(nvp).value}}; //ensure the default_value is an A, whatever T is.
+    return argument_t{std::move(nvp).name, //
+                      python_typename<std::decay_t<A>>,
+                      [](PyObject *ob, bool re) -> bool { return py_converter<std::decay_t<A>>::is_convertible(ob, re); }, //
+                      A{std::move(nvp).value}, //ensure the default_value is an A, whatever T is.
+                      default_value_repr<A>};
   }
 
   // =========================== pycfun_kw =====================
 
   // Abstract class for the eraser for a C++ function into a python function
   class pycfun_kw {
-    bool release_GIL = false;            // Not used
-    std::vector<argument_t> c_arguments; // arguments of the function, with erased type
-    std::string const *rtype_name;       // name of the return type for error messages
+    bool release_GIL = false;                // Not used
+    std::vector<argument_t> c_arguments;     // arguments of the function, with erased type
+                                             // std::string const *rtype_name;       // name of the return type for error messages
+    std::string (*python_return_typename)(); // Name of the return type in Python, for doc
 
     protected:
     // Call the function from args, kwargs
@@ -69,8 +92,8 @@ namespace c2py {
 
     protected:
     // Constructs by simply moving in the data
-    pycfun_kw(std::vector<argument_t> &&c_arguments, std::string const *rtype_name = {})
-       : c_arguments{std::move(c_arguments)}, rtype_name{rtype_name} {}
+    pycfun_kw(std::vector<argument_t> &&c_arguments, std::string (*python_return_typename)() = nullptr)
+       : c_arguments{std::move(c_arguments)}, python_return_typename{python_return_typename} {}
 
     pycfun_kw(pycfun_kw const &)            = default;
     pycfun_kw(pycfun_kw &&)                 = default;
@@ -143,7 +166,7 @@ namespace c2py {
     // Note that U can be some pair of a DIFFERENT type than A::type, e.g. double x = 0 ...
     // As long as we can construc the A, it is fine
     template <typename... U>
-    c_function_impl_t(fnt_ptr_t f, U &&...u) noexcept : pycfun_kw{{make_argument<T>(std::forward<U>(u))...}, &cpp_name<R>}, f{f} {}
+    c_function_impl_t(fnt_ptr_t f, U &&...u) noexcept : pycfun_kw{{make_argument<T>(std::forward<U>(u))...}, python_typename<R>}, f{f} {}
 
     // call it : simply convert all arguments and call f
     PyObject *call(PyObject * /*self*/, PyObject *args, PyObject *kwargs) const override {
@@ -166,7 +189,7 @@ namespace c2py {
     // Note that U can be some pair of a DIFFERENT type than A::type, e.g. double x = 0 ...
     // As long as we can construc the A, it is fine
     template <typename U0, typename... U>
-    c_methfun_impl_t(fnt_ptr_t f, U0, U &&...u) noexcept : pycfun_kw{{make_argument<T>(std::forward<U>(u))...}, &cpp_name<R>}, f{f} {}
+    c_methfun_impl_t(fnt_ptr_t f, U0, U &&...u) noexcept : pycfun_kw{{make_argument<T>(std::forward<U>(u))...}, python_typename<R>}, f{f} {}
 
     // call it : simply convert all arguments and call f
     PyObject *call(PyObject *self, PyObject *args, PyObject *kwargs) const override {
@@ -188,7 +211,7 @@ namespace c2py {
 
     public:
     template <typename... U>
-    c_method_impl_t(fnt_ptr_t f, U &&...u) noexcept : pycfun_kw{{make_argument<T>(std::forward<U>(u))...}, &cpp_name<R>}, f{f} {}
+    c_method_impl_t(fnt_ptr_t f, U &&...u) noexcept : pycfun_kw{{make_argument<T>(std::forward<U>(u))...}, python_typename<R>}, f{f} {}
 
     PyObject *call(PyObject *self, PyObject *args, PyObject *kwargs) const override {
       auto l = [&]<size_t... Is>(std::index_sequence<Is...>) {
diff --git a/src/c2py/py_converter.hpp b/src/c2py/py_converter.hpp
@@ -120,6 +120,26 @@ namespace c2py {
   // raise_exception. Cf py_converter::is_convertible
   template <typename T> static bool convertible(PyObject *ob, bool raise_exception) { return py_converter<T>::is_convertible(ob, raise_exception); }
 
+  // ------------------- Python type name --------------------
+  // For proper doc.
+  inline std::string remove_package_name(std::string const &name) {
+    auto pos = name.find_last_of('.');
+    if (pos != std::string::npos) return name.substr(pos + 1);
+    return name;
+  }
+
+  template <typename T> std::string python_typename() {
+    if constexpr (requires { py_converter<T>::tp_name(); })
+      return py_converter<T>::tp_name();
+    else if constexpr (requires { py_converter<T>::tp_name; }) // a simple string
+      return py_converter<T>::tp_name;
+    else {
+      if (tp_name<T>)
+        return remove_package_name(tp_name<T>);
+      else
+        return cpp_name<T>;
+    }
+  }
   // ---------------------  Backward compatibility layer with cpp2py ------------
   // If the converters already exists in cpp2py, use them
 
diff --git a/src/c2py/pytypes/wrap.hpp b/src/c2py/pytypes/wrap.hpp
diff --git a/test/basicfun.cpp b/test/basicfun.cpp
diff --git a/test/basicfun.wrap.cxx b/test/basicfun.wrap.cxx
diff --git a/test/cls_basic.cpp b/test/cls_basic.cpp
diff --git a/test/cls_basic.wrap.cxx b/test/cls_basic.wrap.cxx
