rod.hpp

Go to the documentation of this file.

#pragma once
#include <array>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <meta>
#include <optional> // lazy NSDMI defaults (Optional[F] = None; caster: <pybind11/stl.h>)
#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)
#include <pybind11/stl_bind.h>    // py::bind_vector / py::bind_map (opaque containers)
 
#include <welder/containers.hpp>  // container_kind_of (bind_vector vs bind_map)
#include <welder/rods/python/array_interface.hpp> // numpy __array_interface__ for POD vectors

#ifndef WELDER_OPAQUE
#define WELDER_OPAQUE(...) PYBIND11_MAKE_OPAQUE(__VA_ARGS__)
#endif
 
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 Self, class Def, std::size_t... I>
    static void _def_truncated(const char* name, Def def_into,
                               std::index_sequence<I...>) {
        // maybe_unused: a zero-arity truncation has an empty I pack, so the
        // splices below never reference params and gcc flags it set-but-unused.
        [[maybe_unused]] static constexpr auto params{
            ::welder::detail::param_types<Fn>()};
        static constexpr auto names{::welder::detail::param_names<Fn>()};
        constexpr py::return_value_policy rvp{
            _return_value_policy(::welder::return_policy_of(Fn, language))};
        if constexpr (std::is_void_v<Self>) {
            auto wrapper = [](typename [:params[I]:]... a) -> decltype(auto) {
                return [:Fn:](std::forward<typename [:params[I]:]>(a)...);
            };
            if constexpr (::welder::detail::all_params_named<Fn>())
                def_into(name, wrapper, py::arg(names[I])..., rvp);
            else
                def_into(name, wrapper, rvp);
        } else {
            auto wrapper = [](Self& self,
                              typename [:params[I]:]... a) -> decltype(auto) {
                return self.[:Fn:](std::forward<typename [:params[I]:]>(a)...);
            };
            if constexpr (::welder::detail::all_params_named<Fn>())
                def_into(name, wrapper, py::arg(names[I])..., rvp);
            else
                def_into(name, wrapper, rvp);
        }
    }

    template <std::meta::info Fn, class Self, class Def, std::size_t... K>
    static void _def_default_truncations(const char* name, Def def_into,
                                         std::index_sequence<K...>) {
        constexpr std::size_t P{std::meta::parameters_of(Fn).size()};
        constexpr std::size_t D{sizeof...(K)};
        (_def_truncated<Fn, Self>(name, def_into,
                                  std::make_index_sequence<P - D + K>{}),
         ...);
    }

    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 D, std::size_t... K>
    static void _def_init_truncations(auto& cls, std::index_sequence<K...>) {
        constexpr std::size_t P{std::meta::parameters_of(Ctor).size()};
        (_def_init<Ctor>(cls, std::make_index_sequence<P - D + K>{}), ...);
    }
 
    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>
    static py::object _copy_instance(py::handle self, py::object* memo) {
        py::object cls{py::type::of(self)};
        py::object out{cls.attr("__new__")(cls)};
        if (memo)
            (*memo)[py::int_(reinterpret_cast<std::uintptr_t>(self.ptr()))] =
                out;
        // Copy-construct the C++ payload into the fresh shell in place — the
        // alias-aware work `py::init<const T&>` would do, done here so the copy
        // needs no Python-visible `T(other)` constructor. A subclass shell
        // (`Py_TYPE(out) != tinfo->type`) gets the trampoline so C++ virtual
        // calls keep dispatching into the Python override; a plain instance
        // gets T. init_instance then constructs the owning holder and registers
        // the instance, exactly as pybind11's own constructor path finalizes.
        namespace pd = py::detail;
        const pd::type_info* tinfo{pd::get_type_info(typeid(T))};
        auto* inst{reinterpret_cast<pd::instance*>(out.ptr())};
        pd::value_and_holder v_h{inst->get_value_and_holder(tinfo)};
        const T& src{py::cast<const T&>(self)};
        v_h.value_ptr() = Py_TYPE(out.ptr()) != tinfo->type
                              ? static_cast<T*>(new construction_type<T>(src))
                              : new T(src);
        tinfo->init_instance(inst, nullptr);
        if (py::hasattr(self, "__dict__")) {
            py::object d{self.attr("__dict__")};
            if (memo)
                d = py::module_::import("copy").attr("deepcopy")(d, *memo);
            out.attr("__dict__").attr("update")(d);
        }
        for (py::handle name :
             py::module_::import("copyreg").attr("_slotnames")(cls)) {
            if (!py::hasattr(self, name))
                continue; // an unassigned slot stays unassigned on the copy
            py::object v{py::getattr(self, name)};
            if (memo)
                v = py::module_::import("copy").attr("deepcopy")(v, *memo);
            py::setattr(out, name, v);
        }
        return out;
    }

    template <class T, std::size_t I>
    static consteval bool _lazy_default() {
        if constexpr (I >= ::welder::detail::aggregate_defaults_from<T>()) {
            using field_type = std::remove_const_t<
                typename [:std::meta::type_of(::welder::detail::aggregate_fields<T>()[I]):]>;
            return !has_native_caster<field_type>;
        } else {
            return false;
        }
    }

    template <class T, std::size_t I>
    using _init_param = std::conditional_t<
        _lazy_default<T, I>(),
        std::optional<std::remove_const_t<
            typename [:std::meta::type_of(::welder::detail::aggregate_fields<T>()[I]):]>>,
        std::remove_const_t<
            typename [:std::meta::type_of(::welder::detail::aggregate_fields<T>()[I]):]>>;

    template <class T, std::size_t I>
    static auto _init_value(_init_param<T, I>&& arg) {
        if constexpr (_lazy_default<T, I>()) {
            constexpr auto field =
                ::welder::detail::aggregate_fields<T>()[I];
            if (arg)
                return typename _init_param<T, I>::value_type{std::move(*arg)};
            return typename _init_param<T, I>::value_type{T{}.[:field:]};
        } else {
            return std::move(arg);
        }
    }

    template <class T, std::size_t I>
    static auto _aggregate_arg([[maybe_unused]] const T& probe) {
        static constexpr auto fields{::welder::detail::aggregate_fields<T>()};
        constexpr const char* name{
            std::define_static_string(std::meta::identifier_of(fields[I]))};
        if constexpr (_lazy_default<T, I>()) {
            // A registration-needed default has no expression-shaped repr
            // anyway — the signature spells it `...`; None (or omission)
            // selects the NSDMI value in C++.
            return py::arg_v(name, py::none(), "...");
        } else if constexpr (I >= ::welder::detail::aggregate_defaults_from<T>()) {
            return py::arg(name) = probe.[:fields[I]:];
        } else {
            return py::arg(name);
        }
    }

    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>()};
        // The probe exists only when a default is extractable
        // (aggregate_defaults_from guarantees T{} is well-formed then) —
        // and T{} in the init lambda reuses the same guarantee.
        if constexpr (::welder::detail::aggregate_defaults_from<T>() <
                      fields.size()) {
            const T probe{};
            cls.def(py::init([](_init_param<T, I>... args) {
                        return T{_init_value<T, I>(std::move(args))...};
                    }),
                    _aggregate_arg<T, I>(probe)...);
        } else {
            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 (::welder::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(
                    ::welder::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::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, bool Copyable,
              class Style = ::welder::naming::none>
    static void add_constructors(auto& cls) {
        if constexpr (HasDefault)
            cls.def(py::init<>());
        if constexpr (Copyable) {
            // A trampolined type must keep the copy faithful for Python
            // subclasses: _copy_instance constructs the ALIAS payload on a
            // subclass shell only if it is constructible from const T&.
            static_assert(
                std::is_constructible_v<construction_type<T>, const T&>,
                "welder: this type's trampoline lacks a copy-from-base "
                "constructor, so a copied Python-subclass instance would hold a "
                "plain base payload and silently stop dispatching virtuals into "
                "Python. The WELDER_PY_TRAMPOLINE(TRAMP, BASE) macro declares "
                "it; a hand-rolled trampoline needs 'Tramp(const Base&)' — or "
                "mark::exclude the copy constructor.");
            // The copy constructor is exposed ONLY as Python's copy protocol —
            // `copy.copy`/`copy.deepcopy` — never as a `T(other)` init overload
            // (that C++-ism is unidiomatic in Python, and would collide with a
            // one-arg user constructor). _copy_instance owns the in-place copy.
            cls.def("__copy__", [](py::handle self) {
                return _copy_instance<T>(self, nullptr);
            });
            cls.def(
                "__deepcopy__",
                [](py::handle self, py::object memo) {
                    return _copy_instance<T>(self, &memo);
                },
                py::arg("memo"));
        }
        template for (constexpr auto ctor : std::define_static_array(Ctors)) {
            _def_init<ctor>(cls, std::make_index_sequence<
                                     std::meta::parameters_of(ctor).size()>{});
            constexpr std::size_t d{::welder::detail::trailing_default_count<ctor>()};
            if constexpr (d > 0)
                _def_init_truncations<ctor, d>(cls,
                                               std::make_index_sequence<d>{});
        }
        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>()};
        // Read-only either because the member's type is const (def_readwrite's
        // setter would not compile) or because a `no_reassign` mark forces it on
        // an otherwise-mutable member (a whole-object rebind is rejected; in-place
        // mutation still writes through the reference_internal getter).
        constexpr bool read_only{std::meta::is_const_type(std::meta::type_of(Mem)) ||
                                 ::welder::member_no_reassign(Mem, language)};
        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 (read_only) {
                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 (read_only) {
            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 <class T, std::meta::info Getter, std::meta::info Setter>
    static void add_property(auto& cls, const char* name) {
        ::welder::validate_return_policy<Getter, language>();
        constexpr ::welder::rv_kind rvk{::welder::return_policy_of(Getter, language)};
        static_assert(rvk != ::welder::rv_kind::none,
                      "welder: return_policy 'none' has no pybind11 equivalent "
                      "(it is nanobind-only) — choose another policy");
        constexpr const char* doc{::welder::doc_of<Getter>()};
        auto def{[&](auto&&... extra) {
            if constexpr (Setter == std::meta::info{}) {
                cls.def_property_readonly(name, &[:Getter:],
                                          std::forward<decltype(extra)>(extra)...);
            } else if constexpr (std::is_void_v<
                                     typename [:std::meta::return_type_of(Setter):]>) {
                cls.def_property(name, &[:Getter:], &[:Setter:],
                                 std::forward<decltype(extra)>(extra)...);
            } else {
                // A value-returning setter (a fluent T& set_x(…)): the property
                // protocol has no slot for the return, so discard it — binding
                // the member pointer directly would make pybind11 convert a
                // value the gate deliberately never checked.
                using Arg = typename
                    [:std::meta::type_of(std::meta::parameters_of(Setter)[0]):];
                static constexpr auto sp{&[:Setter:]};
                cls.def_property(
                    name, &[:Getter:],
                    [](T& self, Arg v) { (self.*sp)(std::forward<Arg>(v)); },
                    std::forward<decltype(extra)>(extra)...);
            }
        }};
        if constexpr (rvk == ::welder::rv_kind::automatic) {
            if constexpr (doc)
                def(doc);
            else
                def();
        } else {
            constexpr py::return_value_policy rvp{_return_value_policy(rvk)};
            if constexpr (doc)
                def(rvp, doc);
            else
                def(rvp);
        }
    }

    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)...);
            });
            constexpr std::size_t d{::welder::detail::trailing_default_count<fn>()};
            if constexpr (d > 0)
                _def_default_truncations<
                    fn, typename std::remove_reference_t<decltype(cls)>::type>(
                    name,
                    [&cls](auto&&... a) {
                        cls.def(std::forward<decltype(a)>(a)...);
                    },
                    std::make_index_sequence<d>{});
        }
    }

    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)...);
            });
            constexpr std::size_t d{::welder::detail::trailing_default_count<fn>()};
            if constexpr (d > 0)
                _def_default_truncations<fn, void>(
                    name,
                    [&cls](auto&&... a) {
                        cls.def_static(std::forward<decltype(a)>(a)...);
                    },
                    std::make_index_sequence<d>{});
        }
    }

    template <class T, auto Fns>
    static void add_operator(auto& cls) {
        template for (constexpr auto fn : std::define_static_array(Fns)) {
            if constexpr (::welder::detail::free_operator_reflected(fn, ^^T)) {
                _def_reflected_operator<T, fn>(cls);
            } else {
                _def_operator<fn, ::welder::rods::python::
                                      dunder_uses_not_implemented(fn)>(
                    ::welder::rods::python::operator_dunder(fn), cls,
                    std::make_index_sequence<
                        ::welder::detail::keep_alive_pairs<fn>().size()>{});
            }
        }
    }

    template <class T, auto Fns, auto Covered>
    static void add_comparisons(auto& cls) {
        ::welder::rods::python::synthesize_comparisons<T, Fns, Covered>(
            [&cls](const char* name, auto fp) {
                cls.def(name, fp, py::is_operator{});
            });
    }

    template <class T, std::meta::info Fn>
    static void add_stringifier(auto& cls) {
        cls.def("__str__", &::welder::detail::stringify<T, Fn>);
    }
 
  private:
    template <std::meta::info Fn, bool NotImpl, class Cls, std::size_t... K>
    static void _def_operator(const char* name, Cls& cls,
                              std::index_sequence<K...>) {
        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>()};
        auto def{[&](auto&&... extra) {
            if (doc.empty())
                cls.def(name, &[:Fn:], rvp,
                        py::keep_alive<ka[K].nurse, ka[K].patient>()...,
                        std::forward<decltype(extra)>(extra)...);
            else
                cls.def(name, &[:Fn:], doc.c_str(), rvp,
                        py::keep_alive<ka[K].nurse, ka[K].patient>()...,
                        std::forward<decltype(extra)>(extra)...);
        }};
        if constexpr (NotImpl)
            def(py::is_operator{});
        else
            def();
    }

    template <class T, std::meta::info Fn>
    static void _def_reflected_operator(auto& cls) {
        constexpr const char* name{::welder::rods::python::reflected_dunder(Fn)};
        if constexpr (name != nullptr) {
            ::welder::validate_return_policy<Fn, language>();
            using Lhs = typename
                [:std::meta::type_of(std::meta::parameters_of(Fn)[0]):];
            cls.def(
                name,
                [](const T& self, Lhs lhs) {
                    return [:Fn:](static_cast<Lhs&&>(lhs), self);
                },
                py::is_operator{});
        }
    }
 
  public:
 
    // --- 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 T>
    static class_handle_type<T> reopen_class(module_type& scope, const char* name) {
        return py::reinterpret_borrow<class_handle_type<T>>(scope.attr(name));
    }

    template <class T>
    static class_handle_type<T> reopen_nested_class(module_type&, auto& outer,
                                                    const char* name) {
        return py::reinterpret_borrow<class_handle_type<T>>(outer.attr(name));
    }

    static std::string _enum_docstring(const ::welder::detail::enum_doc& ed) {
        return DocStyle::format_enum(ed);
    }

    template <class E>
    static consteval const char* _enum_base() {
        return ::welder::flags_enum(^^E) ? "enum.IntFlag" : "enum.IntEnum";
    }

    template <class E>
    static enum_handle<E> make_enum(module_type& m, const char* name,
                                    const ::welder::detail::enum_doc& ed) {
        // native_enum copies class_doc into a std::string (so the transient doc here
        // is safe) and treats "" as "leave __doc__ untouched" — matching the prior
        // nullptr behaviour when the enum carries no documentation.
        const std::string doc{_enum_docstring(ed)};
        return {m, name,
                std::make_unique<py::native_enum<E>>(m, name, _enum_base<E>(),
                                                     doc.c_str())};
    }

    template <class E>
    static enum_handle<E> make_nested_enum(module_type&, auto& outer_cls,
                                           const char* name,
                                           const ::welder::detail::enum_doc& ed) {
        const std::string doc{_enum_docstring(ed)};
        return {outer_cls, name,
                std::make_unique<py::native_enum<E>>(outer_cls, name,
                                                     _enum_base<E>(),
                                                     doc.c_str())};
    }

    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)...);
            });
            constexpr std::size_t d{::welder::detail::trailing_default_count<fn>()};
            if constexpr (d > 0)
                _def_default_truncations<fn, void>(
                    fn_name,
                    [&m](auto&&... a) { m.def(std::forward<decltype(a)>(a)...); },
                    std::make_index_sequence<d>{});
        }
        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);
    }

    template <class Container, class Style = ::welder::naming::none>
    static void bind_container(module_type& m, const char* name) {
        constexpr ::welder::container_kind kind{
            ::welder::container_kind_of(^^Container)};
        if constexpr (kind == ::welder::container_kind::sequence) {
            using Elem = typename Container::value_type;
            if constexpr (::welder::container_is_contiguous(^^Container) &&
                          std::is_arithmetic_v<Elem> && !std::is_same_v<Elem, bool>) {
                // Contiguous scalar buffer: expose the buffer protocol so
                // numpy/memoryview/ctypes view data() zero-copy.
                auto cls{py::bind_vector<Container>(m, name, py::buffer_protocol())};
                _def_sizing<Container, Elem>(cls);
                _def_new<Container, Elem>(cls);
            } else if constexpr (::welder::container_is_contiguous(^^Container) &&
                                 ::welder::rods::python::pod_array_eligible<Elem>()) {
                // Contiguous POD-struct buffer: no scalar dtype, so expose the numpy
                // array-interface protocol (a structured, zero-copy, numpy-free view).
                auto cls{py::bind_vector<Container>(m, name)};
                _array_interface<Container, Elem>(cls);
                _def_sizing<Container, Elem>(cls);
                _def_new<Container, Elem>(cls);
            } else {
                auto cls{py::bind_vector<Container>(m, name)};
                _def_sizing<Container, Elem>(cls);
                _def_new<Container, Elem>(cls);
            }
        } else if constexpr (kind == ::welder::container_kind::fixed_sequence) {
            // std::array has no py::bind_array; hand-write the vector protocol minus
            // the size-changing ops.
            _bind_array<Container>(m, name);
        } else {
            py::bind_map<Container>(m, name);
        }
    }

    template <class Container>
    static void _bind_array(module_type& m, const char* name) {
        using Elem = typename Container::value_type;
        constexpr std::size_t N{std::tuple_size_v<Container>};
        constexpr bool scalar{std::is_arithmetic_v<Elem> &&
                              !std::is_same_v<Elem, bool>};
        auto cls{[&] {
            if constexpr (scalar)
                return py::class_<Container>(m, name, py::buffer_protocol());
            else
                return py::class_<Container>(m, name);
        }()};
        cls.def(py::init<>());
        cls.def(py::init<const Container&>());
        // Construct from a length-N sequence, registered as an implicit conversion so
        // `def_readwrite`'s setter accepts a plain list/tuple (`obj.arr = [...]`).
        cls.def(py::init([](const py::sequence& seq) {
            if (py::len(seq) != N)
                throw py::value_error(
                    "expected a sequence of the array's fixed length");
            Container a{};
            std::size_t i{0};
            for (py::handle h : seq)
                a[i++] = h.cast<Elem>();
            return a;
        }));
        py::implicitly_convertible<py::sequence, Container>();
        cls.def("__len__", [](const Container&) { return N; });
        cls.def(
            "__getitem__",
            [](Container& a, py::ssize_t i) -> Elem& {
                return a[_wrap_index(i, N)];
            },
            py::return_value_policy::reference_internal);
        cls.def("__setitem__", [](Container& a, py::ssize_t i, const Elem& v) {
            a[_wrap_index(i, N)] = v;
        });
        cls.def(
            "__iter__",
            [](Container& a) { return py::make_iterator(a.begin(), a.end()); },
            py::keep_alive<0, 1>());
        if constexpr (scalar) {
            // The buffer protocol: a 1-D contiguous view of data() (numpy/memoryview).
            cls.def_buffer([](Container& a) -> py::buffer_info {
                return py::buffer_info(a.data(),
                                       static_cast<py::ssize_t>(sizeof(Elem)),
                                       py::format_descriptor<Elem>::format(), 1,
                                       {a.size()}, {sizeof(Elem)});
            });
        } else if constexpr (::welder::rods::python::pod_array_eligible<Elem>()) {
            // Contiguous POD-struct element: structured, zero-copy numpy view.
            _array_interface<Container, Elem>(cls);
        }
    }

    static std::size_t _wrap_index(py::ssize_t i, std::size_t n) {
        if (i < 0)
            i += static_cast<py::ssize_t>(n);
        if (i < 0 || static_cast<std::size_t>(i) >= n)
            throw py::index_error("array index out of range");
        return static_cast<std::size_t>(i);
    }
 
  protected:
    template <class Container, class Elem, class Cls>
    static void _def_sizing(Cls& cls) {
        using Size = typename Container::size_type;
        if constexpr (requires(Container& c, Size n) { c.reserve(n); })
            cls.def(
                "reserve", [](Container& v, Size n) { v.reserve(n); }, py::arg("n"),
                "Pre-allocate capacity for at least n elements (no-op if capacity "
                "already exceeds n). Prevents reallocation — and reference "
                "invalidation — across a following run of append()/new().");
        if constexpr (requires(Container& c, Size n) { c.resize(n); })
            cls.def(
                "resize", [](Container& v, Size n) { v.resize(n); }, py::arg("n"),
                "Resize to exactly n elements, value-initializing any new tail "
                "elements. Shrinking or reallocating invalidates references.");
    }

    template <class Container, class Elem, class Cls>
    static void _def_new(Cls& cls) {
        if constexpr (std::is_class_v<Elem> &&
                      std::is_default_constructible_v<Elem>)
            cls.def(
                "new", [](Container& v) -> Elem& { return v.emplace_back(); },
                py::return_value_policy::reference_internal,
                "Default-construct a new element in place at the end and return a "
                "live reference to it.");
    }

    template <class Container, class Elem, class Cls>
    static void _array_interface(Cls& cls) {
        namespace pyai = ::welder::rods::python;
        cls.def_property_readonly("__array_interface__", [](Container& v) {
            static constexpr auto d{pyai::ai_descr<^^Elem>()};
            py::list descr{};
            for (auto [nm, ts] : d)
                descr.append(py::make_tuple(nm, ts));
            py::dict out{};
            out["shape"] = py::make_tuple(v.size());
            out["typestr"] = pyai::ai_typestr<Elem>();
            out["descr"] = descr;
            out["data"] = py::make_tuple(
                reinterpret_cast<std::uintptr_t>(v.data()), false);
            out["version"] = 3;
            return out;
        });
    }
 
  public:

    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