LSSTApplications  19.0.0-10-g4a5fae6+3,19.0.0-10-g920eed2,19.0.0-11-g48a0200+2,19.0.0-18-gfc4e62b+16,19.0.0-2-g3b2f90d+2,19.0.0-2-gd671419+6,19.0.0-20-g5a5a17ab+14,19.0.0-21-g2644856+17,19.0.0-24-g0913cb1,19.0.0-24-g878c510+4,19.0.0-25-g6c8df7140+1,19.0.0-25-gb330496+4,19.0.0-3-g2b32d65+6,19.0.0-3-g8227491+15,19.0.0-3-g9c54d0d+15,19.0.0-3-gca68e65+11,19.0.0-3-gcfc5f51+6,19.0.0-3-ge110943+14,19.0.0-3-ge74d124,19.0.0-30-g9c3fd16+5,19.0.0-4-g06f5963+6,19.0.0-4-g10df615,19.0.0-4-g3d16501+17,19.0.0-4-g4a9c019+6,19.0.0-4-g5a8b323,19.0.0-4-g66397f0+1,19.0.0-4-g8557e14,19.0.0-4-g8964aba+16,19.0.0-4-ge404a01+15,19.0.0-5-g40f3a5a,19.0.0-5-g4db63b3,19.0.0-5-gb9eeb60,19.0.0-5-gfb03ce7+16,19.0.0-6-gbaebbfb+15,19.0.0-61-gec4c6e08+5,19.0.0-7-g039c0b5+15,19.0.0-7-gbea9075+4,19.0.0-7-gc567de5+16,19.0.0-72-g37abf38+2,19.0.0-9-g463f923+15,v20.0.0.rc1
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