LSST Applications  21.0.0+04719a4bac,21.0.0-1-ga51b5d4+f5e6047307,21.0.0-11-g2b59f77+a9c1acf22d,21.0.0-11-ga42c5b2+86977b0b17,21.0.0-12-gf4ce030+76814010d2,21.0.0-13-g1721dae+760e7a6536,21.0.0-13-g3a573fe+768d78a30a,21.0.0-15-g5a7caf0+f21cbc5713,21.0.0-16-g0fb55c1+b60e2d390c,21.0.0-19-g4cded4ca+71a93a33c0,21.0.0-2-g103fe59+bb20972958,21.0.0-2-g45278ab+04719a4bac,21.0.0-2-g5242d73+3ad5d60fb1,21.0.0-2-g7f82c8f+8babb168e8,21.0.0-2-g8f08a60+06509c8b61,21.0.0-2-g8faa9b5+616205b9df,21.0.0-2-ga326454+8babb168e8,21.0.0-2-gde069b7+5e4aea9c2f,21.0.0-2-gecfae73+1d3a86e577,21.0.0-2-gfc62afb+3ad5d60fb1,21.0.0-25-g1d57be3cd+e73869a214,21.0.0-3-g357aad2+ed88757d29,21.0.0-3-g4a4ce7f+3ad5d60fb1,21.0.0-3-g4be5c26+3ad5d60fb1,21.0.0-3-g65f322c+e0b24896a3,21.0.0-3-g7d9da8d+616205b9df,21.0.0-3-ge02ed75+a9c1acf22d,21.0.0-4-g591bb35+a9c1acf22d,21.0.0-4-g65b4814+b60e2d390c,21.0.0-4-gccdca77+0de219a2bc,21.0.0-4-ge8a399c+6c55c39e83,21.0.0-5-gd00fb1e+05fce91b99,21.0.0-6-gc675373+3ad5d60fb1,21.0.0-64-g1122c245+4fb2b8f86e,21.0.0-7-g04766d7+cd19d05db2,21.0.0-7-gdf92d54+04719a4bac,21.0.0-8-g5674e7b+d1bd76f71f,master-gac4afde19b+a9c1acf22d,w.2021.13
LSST Data Management Base Package
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) {
89  std::ostringstream os;
90  os << self;
91  return os.str();
92  });
93 }

◆ 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

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

◆ 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 }
table::Key< std::string > name
Definition: Amplifier.cc:116
Key< U > key
Definition: Schema.cc:281
Cache of most recently used values.
Definition: Cache.h:74