LSST Applications g0265f82a02+c6dfa2ddaf,g1162b98a3f+b2075782a9,g2079a07aa2+1b2e822518,g2bbee38e9b+c6dfa2ddaf,g337abbeb29+c6dfa2ddaf,g3ddfee87b4+a60788ef87,g50ff169b8f+2eb0e556e8,g52b1c1532d+90ebb246c7,g555ede804d+a60788ef87,g591dd9f2cf+ba8caea58f,g5ec818987f+864ee9cddb,g858d7b2824+9ee1ab4172,g876c692160+a40945ebb7,g8a8a8dda67+90ebb246c7,g8cdfe0ae6a+4fd9e222a8,g99cad8db69+5e309b7bc6,g9ddcbc5298+a1346535a5,ga1e77700b3+df8f93165b,ga8c6da7877+aa12a14d27,gae46bcf261+c6dfa2ddaf,gb0e22166c9+8634eb87fb,gb3f2274832+d0da15e3be,gba4ed39666+1ac82b564f,gbb8dafda3b+5dfd9c994b,gbeb006f7da+97157f9740,gc28159a63d+c6dfa2ddaf,gc86a011abf+9ee1ab4172,gcf0d15dbbd+a60788ef87,gdaeeff99f8+1cafcb7cd4,gdc0c513512+9ee1ab4172,ge79ae78c31+c6dfa2ddaf,geb67518f79+ba1859f325,geb961e4c1e+f9439d1e6f,gee10cc3b42+90ebb246c7,gf1cff7945b+9ee1ab4172,w.2024.12
LSST Data Management Base Package
Loading...
Searching...
No Matches
Classes | Functions
lsst::cpputils::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 T , typename PyClass >
void addSharedPtrEquality (PyClass &cls)
 Add __eq__ and __ne__ methods based on two std::shared_ptr<T> pointing to the same address.
 
template<class PyClass >
void addOutputOp (PyClass &cls, std::string const &method)
 Add __str__ or __repr__ method implemented by operator<<.
 
template<class PyClass >
void addHash (PyClass &cls)
 Add __hash__ method implemented by std::hash.
 
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.
 
std::pair< std::size_t, std::size_tcppIndex (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.
 
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)
 

Function Documentation

◆ addHash()

template<class PyClass >
void lsst::cpputils::python::addHash ( PyClass & cls)

Add __hash__ method implemented by std::hash.

Template Parameters
PyClassThe pybind11 class_ type. The wrapped class must have an enabled specialization of std::hash.
Parameters
clsThe PyClass object to which to add a wrapper.

Definition at line 104 of file python.h.

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

◆ addOutputOp()

template<class PyClass >
void lsst::cpputils::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
PyClassThe pybind11 class_ type. The wrapped class must support << as a stream output operator.
Parameters
clsThe PyClass object to which to add a wrapper.
methodThe name of the method to implement. Should be "__str__" or "__repr__".

Definition at line 87 of file python.h.

87 {
88 cls.def(method.c_str(), [](typename PyClass::type const &self) {
89 std::ostringstream os;
90 os << self;
91 return os.str();
92 });
93}

◆ addSharedPtrEquality()

template<typename T , typename PyClass >
void lsst::cpputils::python::addSharedPtrEquality ( PyClass & cls)
inline

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

Template Parameters
TThe type to which the std::shared_ptr points.
PyClassThe 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.

63 {
64 cls.def("__eq__",
65 [](std::shared_ptr<T> self, std::shared_ptr<T> other) { return self.get() == other.get(); },
66 pybind11::is_operator());
67 cls.def("__ne__",
68 [](std::shared_ptr<T> self, std::shared_ptr<T> other) { return self.get() != other.get(); },
69 pybind11::is_operator());
70}
T get(T... args)

◆ cppIndex() [1/2]

std::size_t lsst::cpputils::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]sizeNumber of elements in the collection.
[in]iIndex 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
PythonIndexError if i not in range [-size, size - 1]

Definition at line 124 of file python.h.

124 {
125 auto const i_orig = i;
126 if (i < 0) {
127 // index backwards from the end
128 i += size;
129 }
130 if (i < 0 || i >= size) {
132 os << "Index " << i_orig << " not in range [" << -size << ", " << size - 1 << "]";
133 throw pybind11::index_error(os.str());
134 }
135 return static_cast<std::size_t>(i);
136}
std::ostream * os
Definition Schema.cc:557

◆ cppIndex() [2/2]

std::pair< std::size_t, std::size_t > lsst::cpputils::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_iNumber of elements along the first axis.
[in]size_jNumber of elements along the second axis.
[in]iIndex along first axis; negative values count from the end
[in]jIndex along second axis; negative values count from the end
Returns
a std::pair of indices, each in the range [0, size - 1]
Exceptions
PythonIndexError if either input index not in range [-size, size - 1]

Definition at line 150 of file python.h.

151 {
152 try {
153 return {cppIndex(size_i, i), cppIndex(size_j, j)};
156 os << "Index (" << i << ", " << j << ") not in range ["
157 << -size_i << ", " << size_i - 1 << "], ["
158 << -size_j << ", " << size_j - 1 << "]";
159 throw pybind11::index_error(os.str());
160 }
161}
Reports attempts to access elements outside a valid range of indices.
Definition Runtime.h:89
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.
Definition python.h:124

◆ declareCache()

template<typename Key , typename Value , typename KeyHash = boost::hash<Key>, typename KeyPred = std::equal_to<Key>>
void lsst::cpputils::python::declareCache ( py::module & mod,
std::string const & name )

Definition at line 41 of file Cache.h.

41 {
43 py::class_<Class> cls(mod, name.c_str());
44
45 cls.def(py::init<std::size_t>(), "maxElements"_a=0);
46 cls.def("__call__",
47 [](Class & self, Key const& key, std::function<Value(Key const& key)> func) {
48 py::gil_scoped_release release;
49 return self(key, func);
50 }, "key"_a, "func"_a);
51 cls.def("__getitem__", &Class::operator[]);
52 cls.def("get", &Class::get);
53 cls.def("add", &Class::add, "key"_a, "value"_a);
54 cls.def("size", &Class::size);
55 cls.def("__len__", &Class::size);
56 cls.def("keys", &Class::keys);
57 cls.def("contains", &Class::contains);
58 cls.def("__contains__", &Class::contains);
59 cls.def("capacity", &Class::capacity);
60 cls.def("reserve", &Class::reserve);
61 cls.def("flush", &Class::flush);
62}
Cache of most recently used values.
Definition Cache.h:75