Does order of defining classes matter?

[pk1234pk1234dva-a11y]

Suppose you are declaring classes. Sometimes a method of one class returns another class. I wonder, is it needed for the class that is e.g. returned, to be defined before the method that uses it, or is the order irrelevant?

As an example:

PYBIND11_EMBEDDED_MODULE(some_module, m) {
    auto library = py::class_<Library>(m, "Library");
    library.def("FindBook", &Library::FindBook, py::return_value_policy::reference); // signature is say Book* FindBook(int ID)
    // ! declared after FindBook!
    auto obj = py::class_<Book>(m, "Book");
}

This seems to work fine, despite Book being declared after FindBook, where FindBook returns Book*. So it seems that things are resolved in some deferred/lazy way. Still, I couldn't find documentation about this, and perhaps things are only working by chance.

Can I rely on the order of class definitions being irrelevant, as far as return types and argument types go?

[gistrec]

The order is irrelevant as long as all classes are registered before any of the bound methods is actually invoked from Python — which, for the pattern in your snippet (everything inside one PYBIND11_EMBEDDED_MODULE / PYBIND11_MODULE), is automatically the case.

The mechanism:

• py::class_<T>(m, "T") registers T in pybind11's internal type registry (a hash map keyed by std::type_index).
• library.def("FindBook", &Library::FindBook, ...) does not resolve Book at registration time. It only stores enough type info to convert the return value later, at call time.
• When Python actually calls library.FindBook(123) and pybind11 needs to hand back a Book*, it looks up typeid(Book) in the registry. If Book is there, the cast succeeds; if not, you get a runtime error like "Unable to convert function return value of type Book* to a Python type".

Inside a single PYBIND11_EMBEDDED_MODULE / PYBIND11_MODULE block, all py::class_<...> calls execute before the module's init returns — so by the time Python code can call any bound method, every class registered in the same block is already in the registry. Order within the block is safe by design, not by chance.

Where it does start to matter:

• Split modules. If module A's bound function returns a type registered in module B, module B must be imported before that call.
• Init-time invocation. If init code itself invokes bound methods (rare), classes touched there must already be registered.
• Inheritance. py::class_<Derived, Base>(m, "Derived") does require Base to already be registered — that relationship is resolved at registration time, not call time.

For your Library / Book example, the order is safe.