rod.hpp

Go to the documentation of this file.

#pragma once
#include <array>
#include <cstddef>
#include <memory>
#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 <pybind11/pybind11.h>
#include <pybind11/native_enum.h> // py::native_enum (stdlib enum binding)
 
namespace welder::inline v0::rods::pybind11 {
 
// Inside `welder::rods::pybind11`, the unqualified name `pybind11` resolves to *this*
// namespace, not the library. Alias the real one once — the way pybind11's own
// docs spell it — and use `py::` for every library reference below.
namespace py = ::pybind11;

template <::welder::doc_style DocStyle = ::welder::rods::python::google_style>
struct rod {
    static constexpr lang language{lang::py}; 
    using module_type = py::module_;          
 
  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>> ||
        std::is_base_of_v<py::detail::type_caster_base<py::detail::intrinsic_t<T>>,
                          py::detail::make_caster<T>>;

    static consteval py::return_value_policy _return_value_policy(::welder::rv_kind k) {
        switch (k) {
        case ::welder::rv_kind::automatic:           return py::return_value_policy::automatic;
        case ::welder::rv_kind::automatic_reference: return py::return_value_policy::automatic_reference;
        case ::welder::rv_kind::take_ownership:      return py::return_value_policy::take_ownership;
        case ::welder::rv_kind::copy:                return py::return_value_policy::copy;
        case ::welder::rv_kind::move:                return py::return_value_policy::move;
        case ::welder::rv_kind::reference:           return py::return_value_policy::reference;
        case ::welder::rv_kind::reference_internal:  return py::return_value_policy::reference_internal;
        case ::welder::rv_kind::none:                break; // no pybind11 equivalent
        }
        return py::return_value_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 ::welder::rv_kind rvk{::welder::return_policy_of(Fn, language)};
        static_assert(rvk != ::welder::rv_kind::none,
                      "welder: return_policy 'none' has no pybind11 equivalent "
                      "(it is nanobind-only) — choose another policy");
        constexpr py::return_value_policy rvp{_return_value_policy(rvk)};
        const std::string doc{::welder::function_docstring<Fn, DocStyle>()};
        if constexpr (::welder::detail::all_params_named<Fn>()) {
            if (doc.empty())
                def_into(name, &[:Fn:], py::arg(names[I])..., rvp,
                         py::keep_alive<ka[K].nurse, ka[K].patient>()...);
            else
                def_into(name, &[:Fn:], doc.c_str(), py::arg(names[I])..., rvp,
                         py::keep_alive<ka[K].nurse, ka[K].patient>()...);
        } else {
            if (doc.empty())
                def_into(name, &[:Fn:], rvp,
                         py::keep_alive<ka[K].nurse, ka[K].patient>()...);
            else
                def_into(name, &[:Fn:], doc.c_str(), rvp,
                         py::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(py::init<typename [:params[I]:]...>(), py::arg(names[I])...);
        else
            cls.def(py::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(py::init([](typename [:std::meta::type_of(fields[I]):]... args) {
                    return T{std::move(args)...};
                }),
                py::arg(std::define_static_string(
                    std::meta::identifier_of(fields[I])))...);
    }

    static void _install_live_properties(py::module_& m, py::dict props) {
        auto builtins{py::module_::import("builtins")};
        auto subclass{builtins.attr("type")(
            py::str("welder_live_module"),
            py::make_tuple(m.attr("__class__")), props)};
        // The dynamically-created class would otherwise carry
        // `__module__ == "_frozen_importlib"` (the frame that ran module init).
        // pybind11 copies a module *scope*'s `__module__` onto every function later
        // defined on it, so any function welded onto `m` after this swap — e.g. a
        // `weld_function` following a mutable `weld_variable` on the same handle —
        // would be misattributed in generated stubs. Stamp the module's own name so
        // those functions keep the right `__module__`.
        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(py::handle scope, const char* name, const char* doc,
                            std::index_sequence<I...>) {
        if constexpr (std::is_void_v<Trampoline>) {
            if (doc)
                return py::class_<T, typename [:Bases[I]:]...>(scope, name, doc);
            return py::class_<T, typename [:Bases[I]:]...>(scope, name);
        } else {
            // The trampoline is an extra `py::class_` template argument; Python
            // subclasses instantiate it, so their overrides capture C++ virtual calls.
            if (doc)
                return py::class_<T, Trampoline, typename [:Bases[I]:]...>(scope, name, doc);
            return py::class_<T, Trampoline, typename [:Bases[I]:]...>(scope, name);
        }
    }

    template <class T, auto Bases, std::size_t... I>
    static auto _make_class_at(py::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, auto Ctors, bool HasDefault, bool Aggregate>
    static void add_constructors(auto& cls) {
        if constexpr (HasDefault)
            cls.def(py::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_readwrite: 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_property_readonly(
                        name, &fa::get, py::return_value_policy::reference_internal,
                        doc);
                else
                    cls.def_property_readonly(
                        name, &fa::get,
                        py::return_value_policy::reference_internal);
            } else {
                if constexpr (doc)
                    cls.def_property(name, &fa::get, &fa::set,
                                     py::return_value_policy::reference_internal,
                                     doc);
                else
                    cls.def_property(name, &fa::get, &fa::set,
                                     py::return_value_policy::reference_internal);
            }
        } else if constexpr (std::meta::is_const_type(std::meta::type_of(Mem))) {
            // const member: read-only (def_readwrite's setter would not compile).
            if constexpr (doc)
                cls.def_readonly(name, &[:Mem:], doc);
            else
                cls.def_readonly(name, &[:Mem:]);
        } else {
            if constexpr (doc)
                cls.def_readwrite(name, &[:Mem:], doc);
            else
                cls.def_readwrite(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>
    struct enum_handle {
        py::object scope; 
        const char* name;                         
        std::unique_ptr<py::native_enum<E>> impl; 

        void value(const char* n, E v) { impl->value(n, v); }
        void export_values() { impl->export_values(); }

        void finalize() {
            impl->finalize(); // commits the enum onto `scope` as `name`
            // pybind11 3.0.1 does not yet stamp the `__pybind11_native_enum__`
            // marker that pybind11-stubgen keys on to recognize a stdlib-enum (and
            // strip its `enum` internals from the generated .pyi); a later pybind11
            // sets it. Set it ourselves so welded enums produce clean stubs — both
            // welder's own and any run by a consumer. Harmless once pybind11 sets it
            // too; drop when the conan pybind11 package carries it.
            scope.attr(name).attr("__pybind11_native_enum__") = true;
        }
    };

    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 E> using enum_handle_type = enum_handle<E>;

    template <class E>
    static enum_handle<E> make_enum(module_type& m, const char* name,
                                    const char* doc) {
        // native_enum's class_doc "" means "leave __doc__ untouched"; a non-null doc
        // is the enum docstring, applied at finalize().
        return {m, name,
                std::make_unique<py::native_enum<E>>(m, name, "enum.IntEnum",
                                                     doc ? doc : "")};
    }

    template <class E>
    static enum_handle<E> make_nested_enum(module_type&, auto& outer_cls,
                                           const char* name, const char* doc) {
        return {outer_cls, name,
                std::make_unique<py::native_enum<E>>(outer_cls, name,
                                                     "enum.IntEnum",
                                                     doc ? doc : "")};
    }

    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();
        e.finalize(); // native_enum requires an explicit finalize()
    }
 
    // --- namespace / module binding -----------------------------------------

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

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

    template <auto Fns, class Style = ::welder::naming::none>
    static py::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, py::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{py::module_::import("builtins").attr("property")};
            live[name] = property(
                py::cpp_function([](py::object) { return [:Var:]; }),
                py::cpp_function([](py::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, py::dict& live) {
        if (live.size() != 0)
            _install_live_properties(m, live);
    }
};
 
static_assert(::welder::rod<rod<>>,
              "welder::rods::pybind11::rod<> must satisfy welder::rod");
 
} // namespace welder::rods::pybind11