[cppyy] Auto-downcast objects returned through smart pointers

[guitargeek]

Returning an object by raw pointer already triggers an automatic downcast to its actual (most derived) class, but returning it through a smart pointer (std::unique_ptr, std::shared_ptr) did not: the object was bound as the declared underlying type, so derived-class members were not accessible.

This became more and more of a nuisance as smart pointers become more common in C++ interface.

Therefore, this commit implements automatic downcasting also for returned smart pointers.

Closes #16210.

[github-actions]

Test Results

    21 files      21 suites   3d 10h 44m 38s ⏱️
 3 866 tests  3 791 ✅   0 💤 75 ❌
72 615 runs  72 383 ✅ 157 💤 75 ❌

For more details on these failures, see this check.

Results for commit 3a4918e.

♻️ This comment has been updated with latest results.

[guitargeek]

Updated! This is how it looks now:

[guitargeek]

Automatic downcasting pythonization

In C++, it is possible to use a base-class pointer to refer to an instance of a
derived type.

class Base {
public:
   virtual ~Base() = default;
};
class Derived : public Base {};

Base *foo() {
    static Derived obj;
    return &obj;
}

The same is also possible for smart pointers, like std::unique_ptr or
std::shared_ptr. For example:

std::unique_ptr<Base> foo_unique() {
    return std::unique_ptr<Base>{new Derived};
}

Using the Derived interface on the return value is not possible in C++ without
type casting (e.g. a dynamic_cast). Since explicit type casting is not natural
in Python, ROOT attempts to automatically downcast raw pointer or smart pointer
return values to their actual type. Demonstrating this with the types above:

p1 = ROOT.foo()
p2 = ROOT.foo_unique()

# if you absolutely need a base class proxy, there is a way:
p3 = ROOT.bind_object(p1, "Base")

print(p1)
print(p2)
print(p3)

will give you something like:

<cppyy.gbl.Derived object>
<cppyy.gbl.Derived object held by std::unique_ptr<Base>>
<cppyy.gbl.Base object>

Note 1: keep in mind that the auto downcasting also affects overload
resolution. For example, consider these two overloads:

void consume(Base *) {}    // overload 1
void consume(Derived *) {} // overload 2

In C++, consume(foo()) will hit overload 1. In Python,
ROOT.consume(ROOT.foo()) resolves to the second overload because the pointee
was automatically downcast. If you really need to hit the first Base overload, you'll have to explicitly cast back to the base class type with ROOT.bind_object, as shown before.

Note 2: while the type of the pointee gets downcast, smart pointer types
remain unchanged. That's because std::unique_ptr<Base> and
std::unique_ptr<Derived> are distinct, unrelated types. Template
instantiations don't inherit from one another even when their type arguments do.

Note 3: automatic downcasting is not enabled
unconditionally. It is only available for polymorphic base
classes, which is why the Base class in the example has a virtual destructor.

[vepadulano]

Really nice, thanks! Make sure the CI has no related failures before merging 👍