Method dispatcher

include/pybind11/pybind11.h:940–1383

Main dispatch logic for calls to functions bound using pybind11

    /// Main dispatch logic for calls to functions bound using pybind11
    static PyObject *
    dispatcher(PyObject *self, PyObject *const *args_in_arr, size_t nargsf, PyObject *kwnames_in) {
        using namespace detail;
        const function_record *overloads = function_record_ptr_from_PyObject(self);
        assert(overloads != nullptr);

        /* Iterator over the list of potentially admissible overloads */
        const function_record *current_overload = overloads;

        /* Need to know how many arguments + keyword arguments there are to pick the right
           overload */
        const auto n_args_in = static_cast<size_t>(PyVectorcall_NARGS(nargsf));

        handle parent = n_args_in > 0 ? args_in_arr[0] : nullptr,
               result = PYBIND11_TRY_NEXT_OVERLOAD;

        auto self_value_and_holder = value_and_holder();
        if (overloads->is_constructor) {
            if (!parent
                || !PyObject_TypeCheck(parent.ptr(), (PyTypeObject *) overloads->scope.ptr())) {
                set_error(PyExc_TypeError,
                          "__init__(self, ...) called with invalid or missing `self` argument");
                return nullptr;
            }

            auto *const tinfo
                = get_type_info(reinterpret_cast<PyTypeObject *>(overloads->scope.ptr()));
            auto *const pi = reinterpret_cast<instance *>(parent.ptr());
            self_value_and_holder = pi->get_value_and_holder(tinfo, true);

            // If this value is already registered it must mean __init__ is invoked multiple times;
            // we really can't support that in C++, so just ignore the second __init__.
            if (self_value_and_holder.instance_registered()) {
                return none().release().ptr();
            }
        }

        try {
            // We do this in two passes: in the first pass, we load arguments with `convert=false`;
            // in the second, we allow conversion (except for arguments with an explicit
            // py::arg().noconvert()).  This lets us prefer calls without conversion, with
            // conversion as a fallback.
            std::vector<function_call> second_pass;

            // However, if there are no overloads, we can just skip the no-convert pass entirely
            const bool overloaded
                = current_overload != nullptr && current_overload->next != nullptr;

            for (; current_overload != nullptr; current_overload = current_overload->next) {

                /* For each overload:
                   1. Copy all positional arguments we were given, also checking to make sure that
                      named positional arguments weren't *also* specified via kwarg.
                   2. If we weren't given enough, try to make up the omitted ones by checking
                      whether they were provided by a kwarg matching the `py::arg("name")` name. If
                      so, use it (and remove it from kwargs); if not, see if the function binding
                      provided a default that we can use.
                   3. Ensure that either all keyword arguments were "consumed", or that the