rod.hpp

Go to the documentation of this file.

#pragma once
#include <array>
#include <cstddef>
#include <meta>
#include <string>
#include <type_traits>
#include <utility>
 
#include <welder/welder.hpp>     // welder::welder + the rod contract + driver
#include <welder/rods/python/doc_style.hpp> // welder::rods::python::google_style
#include <welder/rods/python/operators.hpp> // welder::rods::python::operator_dunder
#include <welder/rods/python/trampoline.hpp> // trampoline_for / gate / coverage
#include <welder/bind_traits.hpp>// param_types / param_names / aggregate_fields
#include <welder/doc.hpp>        // function_docstring
 
#include <nanobind/nanobind.h>
 
namespace welder::inline v0::rods::nanobind {
 
// Inside `welder::rods::nanobind`, the unqualified name `nanobind` resolves to *this*
// namespace, not the library. Alias the real one once — the way nanobind's own
// docs spell it — and use `nb::` for every library reference below.
namespace nb = ::nanobind;

template <::welder::doc_style DocStyle = ::welder::rods::python::google_style>
struct rod {
    static constexpr lang language{lang::py}; 
    using module_type = nb::module_;          

    template <class E> using enum_handle_type = nb::enum_<E>;
 
  protected:
    // --- implementation helpers (not part of the welder::rod contract) --

    template <class T>
    static constexpr bool _needs_registration =
        std::is_enum_v<std::remove_cvref_t<T>> ||
        nb::detail::is_base_caster_v<nb::detail::make_caster<T>>;

    static consteval nb::rv_policy _rv_policy(::welder::rv_kind k) {
        switch (k) {
        case ::welder::rv_kind::automatic:           return nb::rv_policy::automatic;
        case ::welder::rv_kind::automatic_reference: return nb::rv_policy::automatic_reference;
        case ::welder::rv_kind::take_ownership:      return nb::rv_policy::take_ownership;
        case ::welder::rv_kind::copy:                return nb::rv_policy::copy;
        case ::welder::rv_kind::move:                return nb::rv_policy::move;
        case ::welder::rv_kind::reference:           return nb::rv_policy::reference;
        case ::welder::rv_kind::reference_internal:  return nb::rv_policy::reference_internal;
        case ::welder::rv_kind::none:                return nb::rv_policy::none;
        }
        return nb::rv_policy::automatic;
    }

    template <std::meta::info Fn, class Def, std::size_t... I, std::size_t... K>
    static void _def_function(const char* name, Def def_into,
                              std::index_sequence<I...>, std::index_sequence<K...>) {
        static constexpr auto names{::welder::detail::param_names<Fn>()};
        static constexpr auto ka{::welder::detail::keep_alive_pairs<Fn>()};
        ::welder::validate_return_policy<Fn, language>();
        constexpr nb::rv_policy rvp{_rv_policy(::welder::return_policy_of(Fn, language))};
        const std::string doc{::welder::function_docstring<Fn, DocStyle>()};
        if constexpr (::welder::detail::all_params_named<Fn>()) {
            if (doc.empty())
                def_into(name, &[:Fn:], nb::arg(names[I])..., rvp,
                         nb::keep_alive<ka[K].nurse, ka[K].patient>()...);
            else
                def_into(name, &[:Fn:], doc.c_str(), nb::arg(names[I])..., rvp,
                         nb::keep_alive<ka[K].nurse, ka[K].patient>()...);
        } else {
            if (doc.empty())
                def_into(name, &[:Fn:], rvp,
                         nb::keep_alive<ka[K].nurse, ka[K].patient>()...);
            else
                def_into(name, &[:Fn:], doc.c_str(), rvp,
                         nb::keep_alive<ka[K].nurse, ka[K].patient>()...);
        }
    }

    template <std::meta::info Fn, class Def>
    static void _def_function(const char* name, Def def_into) {
        _def_function<Fn>(
            name, def_into,
            std::make_index_sequence<std::meta::parameters_of(Fn).size()>{},
            std::make_index_sequence<
                ::welder::detail::keep_alive_pairs<Fn>().size()>{});
    }

    template <std::meta::info Ctor, std::size_t... I>
    static void _def_init(auto& cls, std::index_sequence<I...>) {
        static constexpr auto params{::welder::detail::param_types<Ctor>()};
        static constexpr auto names{::welder::detail::param_names<Ctor>()};
        if constexpr (::welder::detail::all_params_named<Ctor>())
            cls.def(nb::init<typename [:params[I]:]...>(), nb::arg(names[I])...);
        else
            cls.def(nb::init<typename [:params[I]:]...>());
    }

    template <class T, std::size_t... I>
    static void _def_aggregate_init(auto& cls, std::index_sequence<I...>) {
        static constexpr auto fields{::welder::detail::aggregate_fields<T>()};
        cls.def(
            "__init__",
            [](T* self, typename [:std::meta::type_of(fields[I]):]... args) {
                new (self) T{std::move(args)...};
            },
            nb::arg(std::define_static_string(
                std::meta::identifier_of(fields[I])))...);
    }

    static void _install_live_properties(nb::module_& m, nb::dict props) {
        auto builtins{nb::module_::import_("builtins")};
        auto subclass{builtins.attr("type")(
            nb::str("welder_live_module"),
            nb::make_tuple(m.attr("__class__")), props)};
        // Stamp the module's own name onto the dynamically-created class, which would
        // otherwise carry `__module__ == "_frozen_importlib"` (the module-init frame).
        // Keeps functions welded onto `m` after this swap (e.g. a `weld_function`
        // following a mutable `weld_variable`) correctly attributed in stubs.
        subclass.attr("__module__") = m.attr("__name__");
        m.attr("__class__") = subclass;
    }

    template <class T, class Trampoline, auto Bases, std::size_t... I>
    static auto _make_class(nb::handle scope, const char* name, const char* doc,
                            std::index_sequence<I...>) {
        if constexpr (std::is_void_v<Trampoline>) {
            if (doc)
                return nb::class_<T, typename [:Bases[I]:]...>(scope, name, doc);
            return nb::class_<T, typename [:Bases[I]:]...>(scope, name);
        } else {
            // The trampoline is an extra `nb::class_` template argument (nanobind
            // accepts base and trampoline in either order); Python subclasses then
            // instantiate it, so their overrides capture C++ virtual calls.
            if (doc)
                return nb::class_<T, Trampoline, typename [:Bases[I]:]...>(scope, name, doc);
            return nb::class_<T, Trampoline, typename [:Bases[I]:]...>(scope, name);
        }
    }

    template <class T, auto Bases, std::size_t... I>
    static auto _make_class_at(nb::handle scope, const char* name,
                               const char* doc, std::index_sequence<I...> seq) {
        namespace py = ::welder::rods::python;
        if constexpr (py::has_virtual_methods(^^T)) {
            // Resolve the trampoline: an explicit `trampoline_for<T>` wins; otherwise
            // scan T's namespace for a `[[=trampoline]]`-annotated subclass.
            constexpr auto scanned{py::scanned_trampoline_of(^^T)};
            static_assert(
                py::trampoline_for<T> != std::meta::info{} || !scanned.ambiguous,
                "welder: more than one [[=welder::rods::python::trampoline]] class in "
                "this namespace derives from T; disambiguate by specializing "
                "welder::rods::python::trampoline_for<T>.");
            constexpr std::meta::info tramp{py::trampoline_for<T> != std::meta::info{}
                                                ? py::trampoline_for<T>
                                                : scanned.type};
            if constexpr (tramp != std::meta::info{}) {
                using Trampoline = [:tramp:];
                static_assert(
                    py::trampoline_covers(^^T, ^^Trampoline),
                    "welder: the trampoline registered for this type does not "
                    "override all of its virtual methods; every virtual needs an "
                    "override forwarding to Python (see WELDER_PY_OVERRIDE).");
                return _make_class<T, Trampoline, Bases>(scope, name, doc, seq);
            } else {
                static_assert(
                    py::bound_flat(^^T),
                    "welder: this welded type has virtual methods but no trampoline "
                    "is registered, so a Python subclass could not override them. "
                    "Register one — a [[=welder::rods::python::trampoline]] subclass "
                    "in T's namespace, or a welder::rods::python::trampoline_for<T> "
                    "specialization — or annotate T with "
                    "[[=welder::rods::python::bind_flat]] to bind it non-overridably.");
                return _make_class<T, void, Bases>(scope, name, doc, seq);
            }
        } else {
            return _make_class<T, void, Bases>(scope, name, doc, seq);
        }
    }
 
  public:
    // --- caster oracle + emission primitives (the welder::rod contract) --

    template <class T>
    static constexpr bool has_native_caster = !_needs_registration<T>;

    static consteval const char* special_method_name(std::meta::info op_fn) {
        return ::welder::rods::python::operator_dunder(op_fn);
    }
 
    // --- class binding ------------------------------------------------------

    template <class T>
    using construction_type =
        [: ::welder::rods::python::construction_type_of<T>() :];

    template <class T, auto Bases, std::size_t... I>
    static auto make_class(module_type& m, const char* name, const char* doc,
                           std::index_sequence<I...> seq) {
        return _make_class_at<T, Bases>(m, name, doc, seq);
    }

    template <class T, auto Bases, std::size_t... I>
    static auto make_nested_class(module_type&, auto& outer_cls, const char* name,
                                  const char* doc, std::index_sequence<I...> seq) {
        return _make_class_at<T, Bases>(outer_cls, name, doc, seq);
    }

    template <class T>
    using class_handle_type = decltype(make_class<T, std::array<std::meta::info, 0>{}>(
        std::declval<module_type&>(), nullptr, nullptr, std::index_sequence<>{}));

    template <class T, auto Ctors, bool HasDefault, bool Aggregate>
    static void add_constructors(auto& cls) {
        if constexpr (HasDefault)
            cls.def(nb::init<>());
        template for (constexpr auto ctor : std::define_static_array(Ctors)) {
            _def_init<ctor>(cls, std::make_index_sequence<
                                     std::meta::parameters_of(ctor).size()>{});
        }
        if constexpr (Aggregate) {
            constexpr auto fields{::welder::detail::aggregate_fields<T>()};
            _def_aggregate_init<T>(cls, std::make_index_sequence<fields.size()>{});
        }
    }

    template <std::meta::info Mem, class Style = ::welder::naming::none>
    static void add_field(auto& cls) {
        constexpr const char* name{
            ::welder::name_of<Mem, language, Style, ::welder::ent_kind::field>()};
        constexpr const char* doc{::welder::doc_of<Mem>()};
        if constexpr (!std::meta::is_public(Mem)) {
            // A protected member (admitted under policy::weld_protected) binds
            // as a property over welder::detail::field_access — gcc-16 rejects
            // the dependent `&[:Mem:]` for protected data (see field_access).
            // Same semantics as def_rw: reference_internal getter.
            using fa = ::welder::detail::field_access<Mem>;
            if constexpr (std::meta::is_const_type(std::meta::type_of(Mem))) {
                if constexpr (doc)
                    cls.def_prop_ro(name, &fa::get,
                                    nb::rv_policy::reference_internal, doc);
                else
                    cls.def_prop_ro(name, &fa::get,
                                    nb::rv_policy::reference_internal);
            } else {
                if constexpr (doc)
                    cls.def_prop_rw(name, &fa::get, &fa::set,
                                    nb::rv_policy::reference_internal, doc);
                else
                    cls.def_prop_rw(name, &fa::get, &fa::set,
                                    nb::rv_policy::reference_internal);
            }
        } else if constexpr (std::meta::is_const_type(std::meta::type_of(Mem))) {
            // const member: read-only (def_rw's setter would not compile).
            if constexpr (doc)
                cls.def_ro(name, &[:Mem:], doc);
            else
                cls.def_ro(name, &[:Mem:]);
        } else {
            if constexpr (doc)
                cls.def_rw(name, &[:Mem:], doc);
            else
                cls.def_rw(name, &[:Mem:]);
        }
    }

    template <auto Fns, class Style = ::welder::naming::none>
    static void add_method(auto& cls) {
        constexpr const char* name{
            ::welder::name_of<Fns[0], language, Style, ::welder::ent_kind::method>()};
        template for (constexpr auto fn : std::define_static_array(Fns)) {
            _def_function<fn>(name, [&cls](auto&&... a) {
                cls.def(std::forward<decltype(a)>(a)...);
            });
        }
    }

    template <auto Fns, class Style = ::welder::naming::none>
    static void add_static_method(auto& cls) {
        constexpr const char* name{
            ::welder::name_of<Fns[0], language, Style,
                              ::welder::ent_kind::static_method>()};
        template for (constexpr auto fn : std::define_static_array(Fns)) {
            _def_function<fn>(name, [&cls](auto&&... a) {
                cls.def_static(std::forward<decltype(a)>(a)...);
            });
        }
    }

    template <auto Fns>
    static void add_operator(auto& cls) {
        constexpr const char* name{::welder::rods::python::operator_dunder(Fns[0])};
        template for (constexpr auto fn : std::define_static_array(Fns)) {
            _def_function<fn>(name, [&cls](auto&&... a) {
                cls.def(std::forward<decltype(a)>(a)...);
            });
        }
    }
 
    // --- enum binding -------------------------------------------------------

    template <class E>
    static auto make_enum(module_type& m, const char* name, const char* doc) {
        // A non-null doc is the enum docstring (a bare const char* extra); nullptr
        // is branched out rather than passed.
        if (doc)
            return nb::enum_<E>(m, name, doc, nb::is_arithmetic());
        return nb::enum_<E>(m, name, nb::is_arithmetic());
    }

    template <class E>
    static auto make_nested_enum(module_type&, auto& outer_cls, const char* name,
                                 const char* doc) {
        if (doc)
            return nb::enum_<E>(outer_cls, name, doc, nb::is_arithmetic());
        return nb::enum_<E>(outer_cls, name, nb::is_arithmetic());
    }

    template <std::meta::info Enum, class Style = ::welder::naming::none>
    static void add_enumerator(auto& e) {
        e.value(
            ::welder::name_of<Enum, language, Style, ::welder::ent_kind::enumerator>(),
            [:Enum:]);
    }

    template <class E>
    static void finish_enum(auto& e) {
        // Mirror C++ scope semantics: an unscoped enum's enumerators are visible
        // unqualified, so export them into the enclosing scope; a scoped enum's
        // are reached as E.Value, so leave them scoped.
        if constexpr (!std::is_scoped_enum_v<E>)
            e.export_values();
    }
 
    // --- namespace / module binding -----------------------------------------

    static nb::dict open_module(module_type&) { return nb::dict{}; }

    static void set_module_doc(module_type& m, const char* doc) {
        m.attr("__doc__") = doc;
    }

    template <auto Fns, class Style = ::welder::naming::none>
    static nb::object add_function(module_type& m, const char* name = nullptr) {
        const char* fn_name{::welder::name_of_or<Fns[0], language, Style,
                                                 ::welder::ent_kind::function>(name)};
        template for (constexpr auto fn : std::define_static_array(Fns)) {
            _def_function<fn>(fn_name, [&m](auto&&... a) {
                m.def(std::forward<decltype(a)>(a)...);
            });
        }
        return m.attr(fn_name);
    }

    template <std::meta::info Var, class Style = ::welder::naming::none>
    static void add_variable(module_type& m, nb::dict& live,
                             const char* name_override = nullptr) {
        const char* name{
            ::welder::name_of_or<Var, language, Style, ::welder::ent_kind::variable>(
                name_override)};
        if constexpr (std::meta::is_const_type(std::meta::type_of(Var))) {
            m.attr(name) = [:Var:]; // immutable: a value snapshot at bind time
        } else {
            // Mutable: a live property over the C++ global. The descriptors take a
            // leading `self` (the module) and ignore it.
            auto property{nb::module_::import_("builtins").attr("property")};
            live[name] = property(
                nb::cpp_function([](nb::object) { return [:Var:]; }),
                nb::cpp_function([](nb::object,
                                    typename [:std::meta::type_of(Var):] v) {
                    [:Var:] = v;
                }));
        }
    }

    static module_type add_submodule(module_type& m, const char* name) {
        return m.def_submodule(name);
    }

    static void close_module(module_type& m, nb::dict& live) {
        if (live.size() != 0)
            _install_live_properties(m, live);
    }
};
 
static_assert(::welder::rod<rod<>>,
              "welder::rods::nanobind::rod<> must satisfy welder::rod");
 
} // namespace welder::rods::nanobind