lsst::utils::python Namespace Reference

Classes
class	PySharedPtr
	A shared pointer that tracks both a C++ object and its associated PyObject. More...
class	TemplateInvoker
	A helper class for wrapping C++ template functions as Python functions with dtype arguments. More...
class	WrapperCollection
	A helper class for subdividing pybind11 module across multiple translation units (i.e. More...

Functions
template<typename Key , typename Value , typename KeyHash = boost::hash<Key>, typename KeyPred = std::equal_to<Key>>
void	declareCache (py::module &mod, std::string const &name)
template<typename T , typename PyClass >
void	addSharedPtrEquality (PyClass &cls)
	Add __eq__ and __ne__ methods based on two std::shared_ptr<T> pointing to the same address. More...
template<class PyClass >
void	addOutputOp (PyClass &cls, std::string const &method)
	Add __str__ or __repr__ method implemented by operator<<. More...
template<class PyClass >
void	addHash (PyClass &cls)
	Add __hash__ method implemented by std::hash. More...
std::size_t	cppIndex (std::ptrdiff_t size, std::ptrdiff_t i)
	Compute a C++ index from a Python index (negative values count from the end) and range-check. More...
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)
	Compute a pair of C++ indices from a pair of Python indices (negative values count from the end) and range-check. More...

Function Documentation

addHash()

template<class PyClass >

void lsst::utils::python::addHash

(

PyClass &

cls

)

Add __hash__ method implemented by std::hash.

Template Parameters

PyClass

The pybind11 class_ type. The wrapped class must have an enabled specialization of std::hash.

Parameters

cls	The PyClass object to which to add a wrapper.

Definition at line 104 of file python.h.

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

addOutputOp()

template<class PyClass >

void lsst::utils::python::addOutputOp	(	PyClass &	cls,
		std::string const &	method
	)

Add __str__ or __repr__ method implemented by operator<<.

For flexibility, this method can be used to define one or both of __str__ and __repr__. It can also be used to define any Python method that takes no arguments and returns a string, regardless of name.

Template Parameters

PyClass

The pybind11 class_ type. The wrapped class must support << as a stream output operator.

Parameters

cls	The PyClass object to which to add a wrapper.
method	The name of the method to implement. Should be "__str__" or "__repr__".

Definition at line 87 of file python.h.

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

addSharedPtrEquality()

template<typename T , typename PyClass >

void lsst::utils::python::addSharedPtrEquality ( PyClass &  cls )

inline

Add __eq__ and __ne__ methods based on two std::shared_ptr<T> pointing to the same address.

Template Parameters

T	The type to which the std::shared_ptr points.
PyClass	The pybind11 class_ type; this can be automatically deduced.

Example:

lsst::afw::table records are considered equal if two std::shared_ptr<record> point to the same record. This is wrapped as follows for lsst::afw::table::BaseRecord, where cls is an instance of pybind11::class_<BaseRecord, std::shared_ptr<BaseRecord>>):

utils::addSharedPtrEquality<BaseRecord>(cls);

Note that all record subclasses inherit this behavior without needing to call this function.

Definition at line 63 of file python.h.

                                                {
    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());
}

cppIndex() [1/2]

std::size_t lsst::utils::python::cppIndex ( std::ptrdiff_t  size, std::ptrdiff_t  i  )

inline

Compute a C++ index from a Python index (negative values count from the end) and range-check.

Parameters

[in]	size	Number of elements in the collection.
[in]	i	Index into the collection; negative values count from the end

Returns

index in the range [0, size - 1]

Note

the size argument has type std::ptrdiff_t instead of std::size_t in order to to match the allowed range for the i argument.

Exceptions

Python

IndexError if i not in range [-size, size - 1]

Definition at line 124 of file python.h.

                                                             {
    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);
}

cppIndex() [2/2]

std::pair<std::size_t, std::size_t> lsst::utils::python::cppIndex ( std::ptrdiff_t  size_i, std::ptrdiff_t  size_j, std::ptrdiff_t  i, std::ptrdiff_t  j  )

inline

Compute a pair of C++ indices from a pair of Python indices (negative values count from the end) and range-check.

Parameters

[in]	size_i	Number of elements along the first axis.
[in]	size_j	Number of elements along the second axis.
[in]	i	Index along first axis; negative values count from the end
[in]	j	Index along second axis; negative values count from the end

Returns

a std::pair of indices, each in the range [0, size - 1]

Exceptions

Python

IndexError if either input index not in range [-size, size - 1]

Definition at line 150 of file python.h.

                                                                                    {
    try {
        return {cppIndex(size_i, i), cppIndex(size_j, j)};
    } catch (lsst::pex::exceptions::OutOfRangeError const&) {
        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());
    }
}

declareCache()

template<typename Key , typename Value , typename KeyHash = boost::hash<Key>, typename KeyPred = std::equal_to<Key>>

void lsst::utils::python::declareCache	(	py::module &	mod,
		std::string const &	name
	)

Definition at line 41 of file Cache.h.

                                                         {
    typedef lsst::utils::Cache<Key, Value, KeyHash, KeyPred> Class;
    py::class_<Class> cls(mod, name.c_str());
 
    cls.def(py::init<std::size_t>(), "maxElements"_a=0);
    cls.def("__call__",
            [](Class & self, Key const& key, std::function<Value(Key const& key)> func) {
                py::gil_scoped_release release;
                return self(key, func);
            }, "key"_a, "func"_a);
    cls.def("__getitem__", &Class::operator[]);
    cls.def("add", &Class::add, "key"_a, "value"_a);
    cls.def("size", &Class::size);
    cls.def("__len__", &Class::size);
    cls.def("keys", &Class::keys);
    cls.def("contains", &Class::contains);
    cls.def("__contains__", &Class::contains);
    cls.def("capacity", &Class::capacity);
    cls.def("reserve", &Class::reserve);
    cls.def("flush", &Class::flush);
}