python.h

Go to the documentation of this file.

// -*- lsst-c++ -*-
/*
 * LSST Data Management System
 * See COPYRIGHT file at the top of the source tree.
 *
 * This product includes software developed by the
 * LSST Project (http://www.lsst.org/).
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the LSST License Statement and
 * the GNU General Public License along with this program.  If not,
 * see <http://www.lsstcorp.org/LegalNotices/>.
 */

#ifndef LSST_UTILS_PYTHON_H
#define LSST_UTILS_PYTHON_H

#include "pybind11/pybind11.h"

#include <cstddef>
#include <memory>
#include <string>
#include <sstream>
#include <utility>
#include <list>
#include <functional>

#include <iostream>

#include "lsst/pex/exceptions.h"
#include "lsst/pex/exceptions/python/Exception.h"

namespace lsst {
namespace utils {
namespace python {

template<typename T, typename PyClass>
inline void addSharedPtrEquality(PyClass & cls) {
    cls.def("__eq__",
            [](std::shared_ptr<T> self, std::shared_ptr<T> other) { return self.get() == other.get(); },
            pybind11::is_operator());
    cls.def("__ne__",
            [](std::shared_ptr<T> self, std::shared_ptr<T> other) { return self.get() != other.get(); },
            pybind11::is_operator());
}

template <class PyClass>
void addOutputOp(PyClass &cls, std::string const &method) {
    cls.def(method.c_str(), [](typename PyClass::type const &self) {
        std::ostringstream os;
        os << self;
        return os.str();
    });
}

template <class PyClass>
void addHash(PyClass &cls) {
    using Class = typename PyClass::type;
    cls.def("__hash__", [](Class const &self) {
        static auto const hash = std::hash<Class>();
        return hash(self);
    });
}

inline std::size_t cppIndex(std::ptrdiff_t size, std::ptrdiff_t i) {
    auto const i_orig = i;
    if (i < 0) {
        // index backwards from the end
        i += size;
    }
    if (i < 0 || i >= size) {
        std::ostringstream os;
        os << "Index " << i_orig << " not in range [" << -size << ", " << size - 1 << "]";
        throw pybind11::index_error(os.str());
    }
    return static_cast<std::size_t>(i);
}

inline std::pair<std::size_t, std::size_t> cppIndex(std::ptrdiff_t size_i, std::ptrdiff_t size_j,
                                                    std::ptrdiff_t i, std::ptrdiff_t j) {
    try {
        return {cppIndex(size_i, i), cppIndex(size_j, j)};
    } catch (lsst::pex::exceptions::OutOfRangeError) {
        std::ostringstream os;
        os << "Index (" << i << ", " << j << ") not in range ["
           << -size_i << ", " << size_i - 1 << "], ["
           << -size_j << ", " << size_j - 1 << "]";
        throw pybind11::index_error(os.str());
    }
}

class LSST_PRIVATE WrapperCollection final {
    // LSST_PRIVATE above: don't export symbols used only in pybind11 wrappers
public:

    using WrapperCallback = std::function<void(pybind11::module &)>;

    explicit WrapperCollection(pybind11::module module_, std::string const & package) :
        module(module_),
        _package(package)
    {}

    // WrapperCollection is move-contructable.
    WrapperCollection(WrapperCollection && other) noexcept :
        module(std::move(other.module)),
        _package(std::move(other._package)),
        _dependencies(std::move(other._dependencies)),
        _definitions(std::move(other._definitions))
    {}

    // WrapperCollection is not copyable or assignable.
    WrapperCollection(WrapperCollection const &) = delete;
    WrapperCollection & operator=(WrapperCollection const &) = delete;
    WrapperCollection & operator=(WrapperCollection &&) = delete;

    ~WrapperCollection() noexcept {
        if (!std::uncaught_exception() && !_definitions.empty()) {
            PyErr_SetString(PyExc_ImportError,
                            "WrapperCollection::finish() not called; module definition incomplete.");
            PyErr_WriteUnraisable(module.ptr());
        }
    }

    WrapperCollection makeSubmodule(std::string const & name) {
        return WrapperCollection(module.def_submodule(("_" + name).c_str()), _package + "." + name);
    }

    void collectSubmodule(WrapperCollection && submodule) {
        _dependencies.splice(_dependencies.end(), submodule._dependencies);
        _definitions.splice(_definitions.end(), submodule._definitions);
    }

    void addInheritanceDependency(std::string const & name) {
        pybind11::module::import(name.c_str());
    }

    void addSignatureDependency(std::string const & name) {
        _dependencies.push_back(name);
    }

    void wrap(WrapperCallback function) {
        _definitions.emplace_back(std::make_pair(module, function));
    }

    template <typename PyType, typename ClassWrapperCallback>
    PyType wrapType(PyType cls, ClassWrapperCallback function, bool setModuleName=true) {
        if (setModuleName) {
            cls.attr("__module__") = _package;
        }
        // lambda below is mutable so it can modify the captured `cls` variable
        wrap(
            [cls=cls, function=std::move(function)] (pybind11::module & mod) mutable -> void {
                function(mod, cls);
            }
        );
        return cls;
    }

    template <typename CxxException, typename CxxBase>
    auto wrapException(std::string const & pyName, std::string const & pyBase, bool setModuleName=true) {
        auto cls = pex::exceptions::python::declareException<CxxException, CxxBase>(module, pyName, pyBase);
        if (setModuleName) {
            cls.attr("__module__") = _package;
        }
        return cls;
    }

    void finish() {
        for (auto dep = _dependencies.begin(); dep != _dependencies.end(); dep = _dependencies.erase(dep)) {
            pybind11::module::import(dep->c_str());
        }
        for (auto def = _definitions.begin(); def != _definitions.end(); def = _definitions.erase(def)) {
            (def->second)(def->first);  // WrapperCallback(module)
        }
    }

    pybind11::module module;

private:
    std::string _package;
    std::list<std::string> _dependencies;
    std::list<std::pair<pybind11::module, WrapperCallback>> _definitions;
};


}}}  // namespace lsst::utils::python

#endif