rod.hpp

Go to the documentation of this file.

#pragma once
#include <array>
#include <cstddef>
#include <cstdint>
#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>
#include <nanobind/ndarray.h>            // nb::ndarray (zero-copy numpy views)
#include <nanobind/stl/bind_vector.h>    // nb::bind_vector (opaque sequences)
#include <nanobind/stl/optional.h>       // lazy NSDMI defaults (Optional[F] = None)
#include <nanobind/stl/bind_map.h>       // nb::bind_map (opaque maps)
 
#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(...) NB_MAKE_OPAQUE(__VA_ARGS__)
#endif
 
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 Style>
    static consteval auto _styled_param_names() {
        constexpr std::size_t n{std::meta::parameters_of(Fn).size()};
        std::array<const char*, n> names{};
        std::size_t i{0};
        for (auto p : std::meta::parameters_of(Fn))
            names[i++] = std::meta::has_identifier(p)
                             ? std::define_static_string(Style::transform_field(p))
                             : nullptr;
        return names;
    }
 
    template <std::meta::info Fn, class Style, 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{_styled_param_names<Fn, Style>()};
        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 Self, class Style, 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{_styled_param_names<Fn, Style>()};
        constexpr nb::rv_policy rvp{
            _rv_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, nb::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, nb::arg(names[I])..., rvp);
            else
                def_into(name, wrapper, rvp);
        }
    }

    template <std::meta::info Fn, class Self, class Style, 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, Style>(name, def_into,
                                  std::make_index_sequence<P - D + K>{}),
         ...);
    }

    template <std::meta::info Fn, class Style, class Def>
    static void _def_function(const char* name, Def def_into) {
        _def_function<Fn, Style>(
            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, class Style, 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, Style>(cls, std::make_index_sequence<P - D + K>{}), ...);
    }
 
    template <std::meta::info Ctor, class Style, 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{_styled_param_names<Ctor, Style>()};
        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>
    static nb::object _copy_instance(nb::handle self, nb::object* memo) {
        nb::object cls{
            nb::borrow(reinterpret_cast<PyObject*>(Py_TYPE(self.ptr())))};
        nb::object out{cls.attr("__new__")(cls)};
        if (memo)
            (*memo)[nb::int_(reinterpret_cast<std::uintptr_t>(self.ptr()))] =
                out;
        // Copy-construct the C++ payload into the fresh shell in place — the
        // alias-aware work `nb::init<const T&>` would do, done here so the copy
        // needs no Python-visible `T(other)` constructor. A Python-derived shell
        // gets the trampoline so C++ virtual calls keep dispatching into the
        // Python override; a plain instance gets T. nanobind sizes every
        // instance for the alias, so either payload fits; inst_mark_ready then
        // flags it constructed and owned, as nanobind's own init path does.
        const T& src{nb::cast<const T&>(self)};
        if (nb::detail::nb_inst_python_derived(out.ptr()))
            new (nb::inst_ptr<void>(out)) construction_type<T>(src);
        else
            new (nb::inst_ptr<void>(out)) T(src);
        nb::inst_mark_ready(out);
        if (nb::hasattr(self, "__dict__")) {
            nb::object d{self.attr("__dict__")};
            if (memo)
                d = nb::module_::import_("copy").attr("deepcopy")(d, *memo);
            out.attr("__dict__").attr("update")(d);
        }
        for (nb::handle name :
             nb::module_::import_("copyreg").attr("_slotnames")(cls)) {
            if (!nb::hasattr(self, name))
                continue; // an unassigned slot stays unassigned on the copy
            nb::object v{nb::getattr(self, name)};
            if (memo)
                v = nb::module_::import_("copy").attr("deepcopy")(v, *memo);
            nb::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, class Style>
    static auto _aggregate_arg([[maybe_unused]] const T& probe) {
        static constexpr auto fields{::welder::detail::aggregate_fields<T>()};
        constexpr const char* name{::welder::name_of<fields[I], language, Style,
                                                      ::welder::ent_kind::field>()};
        if constexpr (_lazy_default<T, I>()) {
            // A registration-needed default (a welded class/enum instance)
            // has no expression-shaped repr anyway — the signature spells it
            // `...`; None (or omission) selects the NSDMI value in C++.
            return (nb::arg(name).sig("...") = nb::none());
        } else if constexpr (I >= ::welder::detail::aggregate_defaults_from<T>()) {
            return nb::arg(name) = probe.[:fields[I]:];
        } else {
            return nb::arg(name);
        }
    }

    template <class T, class Style, std::size_t... I>
    static void _def_aggregate_init(auto& cls, std::index_sequence<I...>) {
        static constexpr auto fields{::welder::detail::aggregate_fields<T>()};
        if constexpr (::welder::detail::aggregate_defaults_from<T>() <
                      fields.size()) {
            // The probe exists only when a default is extractable
            // (aggregate_defaults_from guarantees T{} is well-formed then) —
            // and T{} in the lambda body reuses the same guarantee.
            const T probe{};
            cls.def(
                "__init__",
                [](T* self, _init_param<T, I>... args) {
                    new (self) T{_init_value<T, I>(std::move(args))...};
                },
                _aggregate_arg<T, I, Style>(probe)...);
        } else {
            cls.def(
                "__init__",
                [](T* self, typename [:std::meta::type_of(fields[I]):]... args) {
                    new (self) T{std::move(args)...};
                },
                nb::arg(::welder::name_of<fields[I], language, Style,
                                          ::welder::ent_kind::field>())...);
        }
    }

    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 (::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>
    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>
    static class_handle_type<T> reopen_class(module_type& scope, const char* name) {
        return nb::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 nb::borrow<class_handle_type<T>>(outer.attr(name));
    }

    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(nb::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__", [](nb::handle self) {
                return _copy_instance<T>(self, nullptr);
            });
            cls.def(
                "__deepcopy__",
                [](nb::handle self, nb::object memo) {
                    return _copy_instance<T>(self, &memo);
                },
                nb::arg("memo"));
        }
        template for (constexpr auto ctor : std::define_static_array(Ctors)) {
            _def_init<ctor, Style>(cls, std::make_index_sequence<
                                     std::meta::parameters_of(ctor).size()>{});
            // C++ default arguments on constructors: _def_init already takes
            // the parameter index sequence, so each omissible arity is just a
            // shorter sequence — nb::init<first-N> calls the constructor with
            // N arguments and the language applies the real defaults.
            constexpr std::size_t d{::welder::detail::trailing_default_count<ctor>()};
            if constexpr (d > 0)
                _def_init_truncations<ctor, d, Style>(cls,
                                               std::make_index_sequence<d>{});
        }
        if constexpr (Aggregate) {
            constexpr auto fields{::welder::detail::aggregate_fields<T>()};
            _def_aggregate_init<T, Style>(cls, std::make_index_sequence<fields.size()>{});
        }
    }

    template <std::meta::info Mem, class Bound>
    static constexpr bool _erasable_field{[] {
        if (!std::meta::is_public(Mem) || std::meta::is_bit_field(Mem))
            return false;
        if (std::meta::parent_of(Mem) != ^^Bound)
            return false;
        using F = [:std::meta::remove_cv(std::meta::type_of(Mem)):];
        if (std::meta::is_volatile_type(std::meta::type_of(Mem)))
            return false;
        return std::is_arithmetic_v<F> || std::is_enum_v<F> ||
               std::is_same_v<F, std::string>;
    }()};

    template <class D>
    static void _def_erased_field(nb::handle cls, const char* name,
                                  std::size_t offset, bool read_only,
                                  const char* doc) {
        auto get = [offset](nb::handle self) -> D {
            return *reinterpret_cast<const D*>(
                static_cast<const char*>(nb::inst_ptr<void>(self)) + offset);
        };
        nb::object get_p{doc ? nb::cpp_function(get, nb::is_method(),
                                                nb::is_getter(), doc)
                             : nb::cpp_function(get, nb::is_method(),
                                                nb::is_getter())};
        nb::object set_p{};
        if (!read_only) {
            auto set = [offset](nb::handle self, D value) {
                *reinterpret_cast<D*>(
                    static_cast<char*>(nb::inst_ptr<void>(self)) + offset) =
                    std::move(value);
            };
            set_p = nb::cpp_function(set, nb::is_method());
        }
        nb::detail::property_install(cls.ptr(), name, get_p.ptr(), set_p.ptr());
    }

    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_rw'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_rw: reference_internal getter.
            using fa = ::welder::detail::field_access<Mem>;
            if constexpr (read_only) {
                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 (_erasable_field<
                                 Mem, typename std::remove_reference_t<
                                          decltype(cls)>::Type>) {
            using F = [:std::meta::remove_cv(std::meta::type_of(Mem)):];
            // .bytes is ptrdiff_t (P2996's member_offset); a real member's
            // offset is never negative, so the cast is value-preserving.
            _def_erased_field<F>(
                cls, name,
                static_cast<std::size_t>(std::meta::offset_of(Mem).bytes),
                read_only, doc);
        } else if constexpr (read_only) {
            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 <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)};
        constexpr const char* doc{::welder::doc_of<Getter>()};
        auto def{[&](auto&&... extra) {
            if constexpr (Setter == std::meta::info{}) {
                cls.def_prop_ro(name, &[:Getter:],
                                std::forward<decltype(extra)>(extra)...);
            } else if constexpr (std::is_void_v<
                                     typename [:std::meta::return_type_of(Setter):]>) {
                cls.def_prop_rw(name, &[:Getter:], &[:Setter:],
                                std::forward<decltype(extra)>(extra)...);
            } else {
                // A value-returning setter (a fluent T& set_x(…)): discard the
                // return — the property protocol has no slot for it, and the
                // gate deliberately never checked it.
                using Arg = typename
                    [:std::meta::type_of(std::meta::parameters_of(Setter)[0]):];
                static constexpr auto sp{&[:Setter:]};
                cls.def_prop_rw(
                    name, &[:Getter:],
                    [](T& self, Arg v) { (self.*sp)(std::forward<Arg>(v)); },
                    std::forward<decltype(extra)>(extra)...);
            }
        }};
        constexpr nb::rv_policy rvp{[] {
            if constexpr (rvk != ::welder::rv_kind::automatic) {
                return _rv_policy(rvk);
            } else {
                constexpr auto rt{std::meta::return_type_of(Getter)};
                return std::meta::is_pointer_type(rt) ||
                               std::meta::is_lvalue_reference_type(rt)
                           ? nb::rv_policy::reference_internal
                           : nb::rv_policy::automatic;
            }
        }()};
        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, Style>(name, [&cls](auto&&... a) {
                cls.def(std::forward<decltype(a)>(a)...);
            });
            // C++ default arguments: one truncated overload per omissible
            // arity (see _def_truncated for why the value cannot be restated).
            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,
                    Style>(
                    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, Style>(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, Style>(
                    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, nb::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 nb::rv_policy rvp{
            _rv_policy(::welder::return_policy_of(Fn, language))};
        const std::string doc{::welder::function_docstring<Fn, DocStyle>()};
        auto def{[&](auto&&... extra) {
            if (doc.empty())
                cls.def(name, &[:Fn:], rvp,
                        nb::keep_alive<ka[K].nurse, ka[K].patient>()...,
                        std::forward<decltype(extra)>(extra)...);
            else
                cls.def(name, &[:Fn:], doc.c_str(), rvp,
                        nb::keep_alive<ka[K].nurse, ka[K].patient>()...,
                        std::forward<decltype(extra)>(extra)...);
        }};
        if constexpr (NotImpl)
            def(nb::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);
                },
                nb::is_operator{});
        }
    }
 
  public:
 
    // --- enum binding -------------------------------------------------------

    template <class E>
    static auto make_enum(module_type& m, const char* name,
                          const ::welder::detail::enum_doc& ed) {
        // ed's summary + documented enumerators fold into the class docstring under
        // DocStyle (an Attributes section) — the one place nanobind's stub generator
        // carries an enumerator's doc into the .pyi. Empty (wholly undocumented) is
        // branched out rather than passed. nb::enum_ builds the type in its ctor and
        // copies the doc, so the transient string here is safe.
        const std::string doc{DocStyle::format_enum(ed)};
        if (!doc.empty())
            return nb::enum_<E>(m, name, doc.c_str(), 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 ::welder::detail::enum_doc& ed) {
        const std::string doc{DocStyle::format_enum(ed)};
        if (!doc.empty())
            return nb::enum_<E>(outer_cls, name, doc.c_str(), 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, Style>(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, Style>(
                    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, 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);
    }

    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) {
            // reference_internal (not nanobind's automatic_reference default,
            // which downgrades an lvalue-reference return to a *copy*) so
            // __getitem__/__iter__ hand out a live reference aliasing the C++
            // element — v[i].field = x writes through, matching pybind11's own
            // bind_vector default. A scalar element ignores the policy and casts
            // by value (a copy, as intended).
            auto cls{
                nb::bind_vector<Container, nb::rv_policy::reference_internal>(
                    m, name)};
            using Elem = typename Container::value_type;
            using Size = typename Container::size_type;
            // `reserve(n)`: pre-grow capacity so a following run of append()/new()
            // does not reallocate — the efficient way to bulk-populate, and the way
            // to keep element references valid across that run (no reallocation ⇒ no
            // move). Only where the container actually has reserve (std::vector;
            // std::deque has none).
            if constexpr (requires(Container& c, Size n) { c.reserve(n); })
                cls.def(
                    "reserve", [](Container& v, Size n) { v.reserve(n); },
                    nb::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().");
            // `resize(n)`: grow/shrink to exactly n elements, value-initializing any
            // new tail elements — allocate-then-fill-by-index bulk population. Needs a
            // default-constructible element (the requires-expression gates it).
            if constexpr (requires(Container& c, Size n) { c.resize(n); })
                cls.def(
                    "resize", [](Container& v, Size n) { v.resize(n); },
                    nb::arg("n"),
                    "Resize to exactly n elements, value-initializing any new tail "
                    "elements. Shrinking or reallocating invalidates references.");
            // `new()`: default-construct an element in place at the back and hand
            // back a **live reference** to it (reference_internal, kept alive to the
            // container) — so generic Python code can grow a container of welded
            // structs without importing the element type just to construct one
            // (`e = v.new(); e.field = x`). Class elements only: a scalar would be
            // returned by value (a dead copy, mutations lost), which is a footgun, so
            // it's omitted there — use `append(value)`. Standard bind_vector caveat:
            // a later append/clear may reallocate and invalidate the reference.
            if constexpr (std::is_class_v<Elem> &&
                          std::is_default_constructible_v<Elem>) {
                cls.def(
                    "new",
                    [](Container& v) -> Elem& { return v.emplace_back(); },
                    nb::rv_policy::reference_internal,
                    "Default-construct a new element in place at the end and return "
                    "a live reference to it.");
            }
            _numpy_view<Container>(cls);
        } else if constexpr (kind == ::welder::container_kind::fixed_sequence) {
            // std::array has no nb::bind_array; hand-write the vector protocol
            // minus the size-changing ops.
            _bind_array<Container>(m, name);
        } else {
            // reference_internal for __getitem__ (see the sequence branch): the
            // mapped value is handed out as a live reference, so m[k].field = x
            // writes through — a copy for a scalar value type.
            nb::bind_map<Container, nb::rv_policy::reference_internal>(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 nb::rv_policy P{nb::rv_policy::reference_internal};
        auto cls{nb::class_<Container>(m, name)};
        cls.def(nb::init<>(), "Default constructor")
            .def(nb::init<const Container&>(), "Copy constructor")
            .def("__len__", [](const Container&) { return N; })
            .def("__bool__", [](const Container&) { return N != 0; })
            .def(
                "__iter__",
                [](Container& a) {
                    return nb::make_iterator<P>(nb::type<Container>(), "Iterator",
                                                a.begin(), a.end());
                },
                nb::keep_alive<0, 1>())
            .def(
                "__getitem__",
                [](Container& a, Py_ssize_t i) -> Elem& {
                    return a[_wrap_index(i, N)];
                },
                P)
            .def("__setitem__", [](Container& a, Py_ssize_t i, const Elem& v) {
                a[_wrap_index(i, N)] = v;
            });
        // Whole-attribute assignment: construct from a length-N iterable, registered
        // as an implicit conversion so `def_rw`'s setter accepts a plain list/tuple.
        cls.def(
            "__init__",
            [](Container* self, nb::typed<nb::iterable, Elem> seq) {
                // Mirror bind_vector's exception safety: destruct the in-place object
                // if the fill fails (a wrong length, an element that won't cast), so a
                // welded-class element leaves no default-constructed leftovers behind.
                Container* a{new (self) Container{}};
                try {
                    std::size_t i{0};
                    for (nb::handle h : seq) {
                        if (i >= N)
                            throw nb::value_error(
                                "expected a sequence of the array's fixed length");
                        (*a)[i++] = nb::cast<Elem>(h);
                    }
                    if (i != N)
                        throw nb::value_error(
                            "expected a sequence of the array's fixed length");
                } catch (...) {
                    a->~Container();
                    throw;
                }
            },
            "Construct from a length-N iterable");
        nb::implicitly_convertible<nb::iterable, Container>();
        _numpy_view<Container>(cls);
    }

    template <class Container, class Cls>
    static void _numpy_view(Cls& cls) {
        using Elem = typename Container::value_type;
        if constexpr (::welder::container_is_contiguous(^^Container) &&
                      std::is_arithmetic_v<Elem> && !std::is_same_v<Elem, bool>) {
            // numpy's __array__ protocol: numpy 2.x calls it with dtype/copy
            // (positional or keyword); accept and ignore both and always hand
            // back a live view — copy=True is honored by numpy copying the view.
            cls.def(
                "__array__",
                [](Container& v, nb::handle, nb::handle) {
                    return nb::ndarray<nb::numpy, Elem, nb::ndim<1>, nb::c_contig>(
                        v.data(), {v.size()}, nb::find(&v));
                },
                nb::arg("dtype") = nb::none(), nb::arg("copy") = nb::none());
        } else if constexpr (::welder::container_is_contiguous(^^Container) &&
                             ::welder::rods::python::pod_array_eligible<Elem>()) {
            // Contiguous POD-struct element: expose the numpy array-interface
            // protocol (structured, zero-copy, numpy-free view of data()).
            _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 nb::index_error("array index out of range");
        return static_cast<std::size_t>(i);
    }

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

    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