LSSTApplications  19.0.0-14-gb0260a2+c4152221ba,20.0.0+428775a0ef,20.0.0+7c6b12c2f9,20.0.0+ae956f52c5,20.0.0+c388114e2c,20.0.0+e2e26847c2,20.0.0+e5529315c6,20.0.0-1-g04bee24+7c6b12c2f9,20.0.0-1-g10df615+cc9679e3e4,20.0.0-1-g253301a+7c6b12c2f9,20.0.0-1-g2b7511a+46a6078777,20.0.0-1-g4d801e7+9b3155b620,20.0.0-1-g5b95a8c+3d35cd64b7,20.0.0-1-gb058bd0+46a6078777,20.0.0-1-gb88604f+acecce4127,20.0.0-1-gc96f8cb+f5ea1f6730,20.0.0-1-gedffbd8+57e6df9186,20.0.0-10-g0891cd99+21712b8dc8,20.0.0-10-g9a20bd332+576ca7b471,20.0.0-17-gcdbda88+f8ebf1b2ab,20.0.0-2-g4dae9ad+f5ea1f6730,20.0.0-2-g61b8584+85c46248f3,20.0.0-2-gb780d76+f45b7d88f4,20.0.0-20-g7966b28+f5ea1f6730,20.0.0-21-g1f5da01+74cacf985d,20.0.0-23-g8900aa8+dfd6ff4ddf,20.0.0-3-g1653f94+85c46248f3,20.0.0-3-g4cc78c6+63636aeed8,20.0.0-3-g750bffe+3a91ba9410,20.0.0-3-gbd60e8c+ff10c6d78d,20.0.0-32-g15a0e07c+fb20712e7c,20.0.0-4-g97dc21a+dfd6ff4ddf,20.0.0-4-gfea843c+f45b7d88f4,20.0.0-5-g357b56b+f45b7d88f4,20.0.0-59-gb502cbb+701042a847,20.0.0-6-g9a5b7a1+3980549e0d,20.0.0-7-gcda7bf1+ddb9d7f898,w.2020.43
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 }

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

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

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

◆ 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 }
std::shared_ptr
STL class.
lsst::utils::python::cppIndex
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
astshim.keyMap.keyMapContinued.keys
def keys(self)
Definition: keyMapContinued.py:6
std::function
lsst::afw::geom.transform.transformContinued.name
string name
Definition: transformContinued.py:32
lsst::utils::Cache
Cache of most recently used values.
Definition: Cache.h:74
lsst::afw::geom.transform.transformContinued.cls
cls
Definition: transformContinued.py:33
astshim.fitsChanContinued.contains
def contains(self, name)
Definition: fitsChanContinued.py:127
other
ItemVariant const * other
Definition: Schema.cc:56
std::ostringstream
STL class.
os
std::ostream * os
Definition: Schema.cc:746
type
table::Key< int > type
Definition: Detector.cc:163
key
Key< U > key
Definition: Schema.cc:281
lsst.pex::exceptions::OutOfRangeError
Reports attempts to access elements outside a valid range of indices.
Definition: Runtime.h:89
std::size_t
std::hash