LSSTApplications  17.0+124,17.0+14,17.0+73,18.0.0+37,18.0.0+80,18.0.0-4-g68ffd23+4,18.1.0-1-g0001055+12,18.1.0-1-g03d53ef+5,18.1.0-1-g1349e88+55,18.1.0-1-g2505f39+44,18.1.0-1-g5315e5e+4,18.1.0-1-g5e4b7ea+14,18.1.0-1-g7e8fceb+4,18.1.0-1-g85f8cd4+48,18.1.0-1-g8ff0b9f+4,18.1.0-1-ga2c679d+1,18.1.0-1-gd55f500+35,18.1.0-10-gb58edde+2,18.1.0-11-g0997b02+4,18.1.0-13-gfe4edf0b+12,18.1.0-14-g259bd21+21,18.1.0-19-gdb69f3f+2,18.1.0-2-g5f9922c+24,18.1.0-2-gd3b74e5+11,18.1.0-2-gfbf3545+32,18.1.0-26-g728bddb4+5,18.1.0-27-g6ff7ca9+2,18.1.0-3-g52aa583+25,18.1.0-3-g8ea57af+9,18.1.0-3-gb69f684+42,18.1.0-3-gfcaddf3+6,18.1.0-32-gd8786685a,18.1.0-4-gf3f9b77+6,18.1.0-5-g1dd662b+2,18.1.0-5-g6dbcb01+41,18.1.0-6-gae77429+3,18.1.0-7-g9d75d83+9,18.1.0-7-gae09a6d+30,18.1.0-9-gc381ef5+4,w.2019.45
LSSTDataManagementBasePackage
Classes | Functions
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_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. More...
 

Function Documentation

◆ addHash()

template<class PyClass >
void lsst::utils::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 }
table::Key< int > type
Definition: Detector.cc:163

◆ 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
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) {
90  os << self;
91  return os.str();
92  });
93 }
table::Key< int > type
Definition: Detector.cc:163
T str(T... args)
std::ostream * os
Definition: Schema.cc:746

◆ 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
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 }
ItemVariant const * other
Definition: Schema.cc:56
T get(T... args)

◆ 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]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 }
T str(T... args)
std::ostream * os
Definition: Schema.cc:746

◆ 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_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)};
154  } catch (lsst::pex::exceptions::OutOfRangeError const&) {
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 }
T str(T... args)
Reports attempts to access elements outside a valid range of indices.
Definition: Runtime.h:89
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 ...
Definition: python.h:150
std::ostream * os
Definition: Schema.cc:746

◆ 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.

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("add", &Class::add, "key"_a, "value"_a);
53  cls.def("size", &Class::size);
54  cls.def("__len__", &Class::size);
55  cls.def("keys", &Class::keys);
56  cls.def("contains", &Class::contains);
57  cls.def("__contains__", &Class::contains);
58  cls.def("capacity", &Class::capacity);
59  cls.def("reserve", &Class::reserve);
60  cls.def("flush", &Class::flush);
61 }
Key< U > key
Definition: Schema.cc:281
Cache of most recently used values.
Definition: Cache.h:74