Allow binding factory functions as constructors

This allows you to use:

    cls.def(py::init(&factory_function));

where `factory_function` returns a pointer, holder, or value of the
class type (or a derived type).  Various compile-time checks
(static_asserts) are performed to ensure the function is valid, and
various run-time type checks where necessary.

The feature is optional, and requires including the <pybind11/factory.h>
header.

Some other details of this feature:
- The `py::init` name doesn't conflict with the templated no-argument
  `py::init<...>()`, but keeps the naming consistent (especially if we
  decide to roll this into the core, documented approach replacing raw
  placement-new `__init__`s).
- If returning a CppClass (whether by value or pointer) when an CppAlias
  is required (i.e. python-side inheritance and a declared alias), a
  dynamic_cast to the alias is attempted (for the pointer version); if
  it fails, or if returned by value, an Alias(Class &&) constructor
  is invoked.  If this constructor doesn't exist, a runtime error occurs.
- for holder returns when an alias is required, we try a dynamic_cast of
  the wrapped pointer to the alias to see if it is already an alias
  instance; if it isn't, we raise an error.
- `py::init(class_factory, alias_factory)` is also available that takes
  two factories: the first is called when an alias is not needed, the
  second when it is.
- It also allows using a factory init to workaround binding a type
  without placement new support (issue pybind#948), which is basically
  impossible with this approach.

Author: jagerman

CMakeLists.txt

@@ -48,6 +48,7 @@ set(PYBIND11_HEADERS
   include/pybind11/eigen.h
   include/pybind11/embed.h
   include/pybind11/eval.h
+  include/pybind11/factory.h
   include/pybind11/functional.h
   include/pybind11/numpy.h
   include/pybind11/operators.h

docs/advanced/classes.rst

@@ -322,6 +322,8 @@ can now create a python class that inherits from ``Dog``:
     See the file :file:`tests/test_virtual_functions.cpp` for complete examples
     using both the duplication and templated trampoline approaches.
 
+.. _extended_aliases:
+
 Extended trampoline class functionality
 =======================================
 
@@ -382,6 +384,76 @@ In other words, :func:`init` creates an anonymous function that invokes an
 in-place constructor. Memory allocation etc. is already take care of beforehand
 within pybind11.
 
+Factory function constructors
+=============================
+
+When binding a C++ type that creates new instances through a factory function
+or static method, it is sometimes desirable to bind C++ factory function as a
+Python constructor rather than a Python factory function.  This is possible
+when including the extra header ``pybind11/factory.h``:
+
+.. code-block:: cpp
+
+    #include <pybind11/factory.h>
+    class Example {
+        // ...
+        static Example *create(int a) { return new Example(a); }
+    };
+    py::class_<Example>(m, "Example")
+        // Bind an existing pointer-returning factory function:
+        .def(py::init(&Example::create))
+        // Similar, but returns the pointer wrapped in a holder:
+        .def(py::init([](std::string arg) {
+            return std::unique_ptr<Example>(new Example(arg, "another arg"));
+        }))
+        // Can overload these with bound C++ constructors, too:
+        .def(py::init<double>())
+        ;
+
+When the constructor is invoked from Python, pybind11 will call the factory
+function and store the resulting C++ instance in the Python instance.  Factory
+functions that return an object by value are also supported as long as the type
+is moveable or copyable.
+
+When combining factory functions constructors with :ref:`_overriding_virtuals`
+there are two approaches.  The first is to add a constructor to the alias class
+that takes a base value by rvalue-reference.  If such a constructor is
+available, it will be used to construct an alias instance from the value
+returned by the factory function.  The second option is to provide two factory
+functions to ``py::init()``: the first will be invoked when no alias class is
+required (i.e. when the class is being used but not inherited from in Python),
+and the second will be invoked when an alias is required.
+
+You can also specify a single factory function that always returns an Alias
+instance: this will result in behaviour similar to ``py::init_alias<...>()``,
+as described in :ref:`_extended_aliases`.
+
+The following example shows the different factory approaches for a class with an alias:
+
+..code-block:: cpp
+
+    #include <pybind11/factory.h>
+    class Example {
+    public:
+        // ...
+        virtual ~Example() = default;
+    };
+    class PyExample : public Example {
+    public:
+        using Example::Example;
+        PyExample(Example &&base) : Example(std::move(base)) {}
+    };
+    py::class_<Example, PyExample>(m, "Example")
+        // Returns an Example pointer.  If a PyExample is needed, it uses the
+        // extra constructor added to PyExample, above.
+        .def(py::init([]() { return new Example(); }))
+        // Two callbacks: a no-alias-needed, and an alias-needed:
+        .def(py::init([]() { return new Example(); },
+                      []() { return new PyExample(); }))
+        // Always return an alias instance, like py::init_alias<>()
+        .def(py::init([]() { return new PyExample(); }))
+        ;
+
 .. _classes_with_non_public_destructors:
 
 Non-public destructors

include/pybind11/attr.h

@@ -118,6 +118,7 @@ struct undefined_t;
 template <op_id id, op_type ot, typename L = undefined_t, typename R = undefined_t> struct op_;
 template <typename... Args> struct init;
 template <typename... Args> struct init_alias;
+template <typename, typename, typename, typename, typename...> struct init_factory;
 inline void keep_alive_impl(size_t Nurse, size_t Patient, function_call &call, handle ret);
 
 /// Internal data structure which holds metadata about a keyword argument

include/pybind11/factory.h

@@ -0,0 +1,276 @@
+/*
+    pybind11/factory.h: Helper class for binding C++ factory functions
+                        as Python constructors.
+
+    Copyright (c) 2017 Jason Rhinelander <[email protected]>
+
+    All rights reserved. Use of this source code is governed by a
+    BSD-style license that can be found in the LICENSE file.
+*/
+
+#pragma once
+#include "pybind11.h"
+
+#if defined(_MSC_VER)
+#  pragma warning(push)
+#  pragma warning(disable: 4100) // warning C4100: Unreferenced formal parameter
+#  pragma warning(disable: 4127) // warning C4127: Conditional expression is constant
+#endif
+
+NAMESPACE_BEGIN(pybind11)
+
+template <typename type, typename... options>
+template <typename... Args, typename... Extra>
+class_<type, options...> &class_<type, options...>::def(detail::init_factory<Args...> &&init, const Extra&... extra) {
+    std::move(init).execute(*this, extra...);
+    return *this;
+}
+
+NAMESPACE_BEGIN(detail)
+
+inline void init_factory_no_nullptr(void *ptr) {
+    if (!ptr) throw type_error("pybind11::init(): factory function returned nullptr");
+}
+
+inline void init_factory_reset(instance *self) {
+    // Reallocate the instance if there are any existing values
+    bool need_reset = false;
+    for (auto &v_h : values_and_holders(self))
+        if (v_h) { need_reset = true; break; }
+
+    if (need_reset) {
+        clear_instance((PyObject *) self);
+        self->allocate_layout();
+    }
+}
+
+
+template <typename CFunc, typename CReturn, typename AFuncIn, typename AReturn, typename... Args> struct init_factory {
+private:
+    using CFuncType = typename std::remove_reference<CFunc>::type;
+    using AFunc = conditional_t<std::is_void<AFuncIn>::value, void_type, AFuncIn>;
+    using AFuncType = typename std::remove_reference<AFunc>::type;
+
+    template <typename Class> using Cpp = typename Class::type;
+    template <typename Class> using Alias = typename Class::type_alias;
+    template <typename Class> using Holder = typename Class::holder_type;
+
+public:
+    // Constructor with a single function/lambda to call
+    init_factory(CFunc &&f) : class_factory(std::forward<CFunc>(f)) {}
+
+    // Constructor with two functions/lambdas, for a class with distinct class/alias factories: the
+    // first is called when an alias is not needed, the second when the alias is needed.  Requires
+    // non-void AFunc.
+    init_factory(CFunc &&c, AFunc &&a) :
+        class_factory(std::forward<CFunc>(c)), alias_factory(std::forward<AFunc>(a)) {}
+
+    // Add __init__ definition for a class that has no alias or has no separate alias factory
+    template <typename Class, typename... Extra,
+              enable_if_t<!Class::has_alias || std::is_void<AFuncIn>::value, int> = 0>
+    void execute(Class &cl, const Extra&... extra) && {
+        auto *cl_type = (PyTypeObject *) cl.ptr();
+        #if defined(PYBIND11_CPP14)
+        cl.def("__init__", [cl_type, func = std::move(class_factory)]
+        #else
+        CFuncType func(std::move(class_factory));
+        cl.def("__init__", [cl_type, func]
+        #endif
+        (handle self, Args... args) {
+            auto *inst = reinterpret_cast<instance *>(self.ptr());
+            construct<Class>(inst, func(std::forward<Args>(args)...), cl_type);
+        }, extra...);
+    }
+
+    // Add __init__ definition for a class with an alias *and* distinct alias factory:
+    template <typename Class, typename... Extra,
+              enable_if_t<Class::has_alias && !std::is_void<AFuncIn>::value, int> = 0>
+    void execute(Class &cl, const Extra&... extra) && {
+        auto *cl_type = (PyTypeObject *) cl.ptr();
+        #if defined(PYBIND11_CPP14)
+        cl.def("__init__", [cl_type, class_func = std::move(class_factory), alias_func = std::move(alias_factory)]
+        #else
+        CFuncType class_func(std::move(class_factory));
+        AFuncType alias_func(std::move(alias_factory));
+        cl.def("__init__", [cl_type, class_func, alias_func]
+        #endif
+        (handle self, Args... args) {
+            auto *inst = reinterpret_cast<instance *>(self.ptr());
+            if (Py_TYPE(inst) == cl_type)
+                construct<Class>(inst, class_func(std::forward<Args>(args)...), cl_type);
+            else
+                construct<Class>(inst, alias_func(std::forward<Args>(args)...), cl_type);
+        }, extra...);
+    }
+
+private:
+    // Pointer assignment implementation:
+    template <typename Class>
+    static void construct_impl(instance *self, Cpp<Class> *ptr) {
+        init_factory_reset(self);
+        auto v_h = self->get_value_and_holder(get_type_info(Py_TYPE(self)));
+        v_h.value_ptr() = ptr;
+    }
+
+    // Takes a cpp class pointer and returns true if it actually a polymorphic alias instance.
+    template <typename Class, enable_if_t<Class::has_alias, int> = 0>
+    static bool is_alias(Cpp<Class> *ptr) {
+        return dynamic_cast<Alias<Class> *>(ptr) != nullptr;
+    }
+    // Failing fallback version for a no-alias class (always returns false)
+    template <typename Class>
+    constexpr static bool is_alias(void *) { return false; }
+
+    // Attempts to constructs an alias using a `Alias(Cpp &&)` constructor.  Returns true if the
+    // constructor existed, false is the alias cannot be constructed that way.
+    template <typename Class, enable_if_t<std::is_constructible<Alias<Class>, Cpp<Class> &&>::value, int> = 0>
+    static bool construct_alias_from_cpp(instance *self, Cpp<Class> &&base) {
+        new (self->get_value_and_holder().value_ptr()) Alias<Class>(std::move(base));
+        return true;
+    }
+    // Base version for aliases without an appropriate constructor; does nothing and returns false.
+    template <typename Class, enable_if_t<!std::is_constructible<Alias<Class>, Cpp<Class> &&>::value, int> = 0>
+    static bool construct_alias_from_cpp(instance *, Cpp<Class> &&) { return false; }
+
+    // Error-generating fallback
+    template <typename Class>
+    static void construct(...) {
+        static_assert(!std::is_same<Class, Class>::value /* always false */,
+                "pybind11::init(): wrapped factory function must return a compatible pointer, "
+                "holder, or value");
+    }
+
+    // Pointer return v1: a factory function that returns a class pointer for a registered class
+    // without an alias
+    template <typename Class, enable_if_t<!Class::has_alias, int> = 0>
+    static void construct(instance *self, Cpp<Class> *ptr, PyTypeObject *) {
+        init_factory_no_nullptr(ptr);
+        construct_impl<Class>(self, ptr);
+    }
+
+    // Pointer return v2: a factory that always returns an alias instance ptr (like py::init_alias)
+    template <typename Class, enable_if_t<Class::has_alias, int> = 0>
+    static void construct(instance *self, Alias<Class> *alias_ptr, PyTypeObject *) {
+        construct_impl<Class>(self, static_cast<Cpp<Class> *>(alias_ptr));
+    }
+
+    // Pointer return v3: returning a cpp class for a registered class with an alias.  If we don't
+    // need an alias, we simply use the cpp pointer.  Otherwise, we try a dynamic_cast to see if the
+    // cpp pointer is actually a polymorphic alias instance.  If it isn't, but we can construct the
+    // alias via an `Alias(Cpp &&)` constructor, we do.  Otherwise we throw a type error.
+    template <typename Class, enable_if_t<Class::has_alias, int> = 0>
+    static void construct(instance *self, Cpp<Class> *ptr, PyTypeObject *cl_type) {
+        init_factory_no_nullptr(ptr);
+        if (Py_TYPE(self) != cl_type) {
+            // Inherited from on the Python side: an alias instance is required
+            if (!is_alias<Class>(ptr)) {
+                if (construct_alias_from_cpp<Class>(self, std::move(*ptr))) {
+                    delete ptr;
+                    return;
+                }
+
+                delete ptr;
+                throw type_error("pybind11::init(): factory function pointer could not be cast or "
+                                 "converted to an alias instance");
+            }
+        }
+        construct_impl<Class>(self, ptr);
+    }
+
+    // Holder return: copy its pointer, and move or copy the returned holder into the new instance's
+    // holder.  This also handles types like std::shared_ptr<T> and std::unique_ptr<T> where T is a
+    // derived type (through those holder's implicit conversion from derived class holder constructors).
+    template <typename Class>
+    static void construct(instance *self, Holder<Class> holder, PyTypeObject *cl_type) {
+        auto *ptr = holder_helper<Holder<Class>>::get(holder);
+        // If we need an alias, check that the held pointer is actually an alias instance
+        if (Class::has_alias && Py_TYPE(self) != cl_type && !is_alias<Class>(ptr))
+            throw type_error("pybind11::init(): construction failed: returned holder-wrapped instance "
+                             "is not an alias instance");
+
+        construct_impl<Class>(self, ptr);
+        Class::init_instance(self, &holder);
+    }
+
+    // return-by-value version 1: returning a cpp class by value when there is no alias
+    template <typename Class, enable_if_t<!Class::has_alias, int> = 0>
+    static void construct(instance *self, Cpp<Class> &&result, PyTypeObject *) {
+        static_assert(std::is_move_constructible<Cpp<Class>>::value,
+            "pybind11::init() return-by-value factory function requires a movable class");
+        new (self->get_value_and_holder().value_ptr()) Cpp<Class>(std::move(result));
+    }
+
+    // return-by-value version 2: returning a cpp class by value when there is an alias: the alias
+    // must have an `Alias(Base &&)` constructor so that we can construct the alias from the base
+    // when needed.
+    template <typename Class, enable_if_t<Class::has_alias, int> = 0>
+    static void construct(instance *self, Cpp<Class> &&result, PyTypeObject *cl_type) {
+        static_assert(std::is_move_constructible<Cpp<Class>>::value,
+            "pybind11::init() return-by-value factory function requires a movable class");
+        if (Py_TYPE(self) != cl_type) {
+            if (!construct_alias_from_cpp<Class>(self, std::move(result)))
+                throw type_error("pybind11::init(): unable to convert returned instance to "
+                                 "required alias class: no `Alias(Class &&)` constructor available");
+        }
+        else
+            new (self->get_value_and_holder().value_ptr()) Cpp<Class>(std::move(result));
+    }
+
+    // return-by-value version 3: the alias type itself--always initialize via the alias type (this
+    // is the factory equivalent of py::init_alias<...>()).
+    template <typename Class>
+    static void construct(instance *self, Alias<Class> &&result, PyTypeObject *) {
+        static_assert(std::is_move_constructible<Alias<Class>>::value,
+            "pybind11::init() return-by-alias-value factory function requires a movable alias class");
+        new (self->get_value_and_holder().value_ptr()) Alias<Class>(std::move(result));
+    }
+
+    CFuncType class_factory;
+    AFuncType alias_factory;
+};
+
+template <typename Func> using init_factory_functype =
+    conditional_t<std::is_function<remove_reference_t<Func>>::value, remove_reference_t<Func> *,
+    conditional_t<is_function_pointer<remove_reference_t<Func>>::value, remove_reference_t<Func>,
+    Func>>;
+
+// Helper definition to infer the detail::init_factory template type from a callable object
+template <typename Func, typename Return, typename... Args>
+init_factory<init_factory_functype<Func>, Return, void, void, Args...> init_factory_decltype(Return (*)(Args...));
+
+template <typename Return1, typename Return2, typename... Args1, typename... Args2>
+inline constexpr bool init_factory_require_matching_arguments(Return1 (*)(Args1...), Return2 (*)(Args2...)) {
+    static_assert(sizeof...(Args1) == sizeof...(Args2),
+        "pybind11::init(class_factory, alias_factory): class and alias factories must have identical argument signatures");
+    static_assert(all_of<std::is_same<Args1, Args2>...>::value,
+        "pybind11::init(class_factory, alias_factory): class and alias factories must have identical argument signatures");
+    return true;
+}
+
+template <typename CFunc, typename AFunc,
+          typename CReturn, typename... CArgs, typename AReturn, typename... AArgs,
+          bool = init_factory_require_matching_arguments((CReturn (*)(CArgs...)) nullptr, (AReturn (*)(AArgs...)) nullptr)>
+init_factory<init_factory_functype<CFunc>, CReturn, init_factory_functype<AFunc>, AReturn, CArgs...> init_factory_decltype(
+    CReturn (*)(CArgs...), AReturn (*)(AArgs...));
+
+template <typename... Func> using init_factory_t = decltype(init_factory_decltype<Func...>(
+    (function_signature_t<Func> *) nullptr...));
+
+NAMESPACE_END(detail)
+
+/// Single-argument factory function constructor wrapper
+template <typename Func, typename Ret = detail::init_factory_t<Func>>
+Ret init(Func &&f) { return {std::forward<Func>(f)}; }
+
+/// Dual-argument factory function: the first function is called when no alias is needed, the second
+/// when an alias is needed (i.e. due to python-side inheritance).  Arguments must be identical.
+template <typename CFunc, typename AFunc, typename Ret = detail::init_factory_t<CFunc, AFunc>>
+Ret init(CFunc &&c, AFunc &&a) {
+    return {std::forward<CFunc>(c), std::forward<AFunc>(a)};
+}
+
+NAMESPACE_END(pybind11)
+
+#if defined(_MSC_VER)
+#  pragma warning(pop)
+#endif