Deprecation for at and axis (#170)

* at and axis replaced by [] and axes

* Replace usages of axis

* Fix tests

Author: henryiii

boost_histogram/_hist.py

@@ -6,6 +6,7 @@
 
 from . import core as _core
 
+import warnings
 import numpy as np
 
 _histograms = (
@@ -93,27 +94,41 @@ def _compute_commonindex(self, index, expand):
     # Allow [bh.loc(...)] to work
     for i in range(len(indexes)):
         if hasattr(indexes[i], "value") and hasattr(indexes[i], "offset"):
-            indexes[i] = self.axis(i).index(indexes[i].value) + indexes[i].offset
+            indexes[i] = self._axis(i).index(indexes[i].value) + indexes[i].offset
         elif hasattr(indexes[i], "flow"):
             if indexes[i].flow == 1:
-                indexes[i] = self.axis(i).size
+                indexes[i] = self._axis(i).size
             elif indexes[i].flow == -1:
                 indexes[i] = -1
         elif isinstance(indexes[i], int):
-            if abs(indexes[i]) >= self.axis(i).size:
+            if abs(indexes[i]) >= self._axis(i).size:
                 raise IndexError("histogram index is out of range")
-            indexes[i] %= self.axis(i).size
+            indexes[i] %= self._axis(i).size
 
     return indexes
 
 
+def at(self, *ind):
+    warnings.warn(
+        ".at is deprecated, please use [] indexing instead", category=DeprecationWarning
+    )
+    return self._at(*ind)
+
+
+def axis(self, value):
+    warnings.warn(
+        ".axis() is deprecated, please use axes[] instead", category=DeprecationWarning
+    )
+    return self._axis(value)
+
+
 def _compute_getitem(self, index):
 
     indexes = _compute_commonindex(self, index, expand=True)
 
     # If this is (now) all integers, return the bin contents
     try:
-        return self.at(*indexes)
+        return self._at(*indexes)
     except RuntimeError:
         pass
 
@@ -149,10 +164,10 @@ def _compute_getitem(self, index):
             process_loc = (
                 lambda x, y: y
                 if x is None
-                else (self.axis(i).index(x.value) if hasattr(x, "value") else x)
+                else (self._axis(i).index(x.value) if hasattr(x, "value") else x)
             )
             begin = process_loc(ind.start, 0)
-            end = process_loc(ind.stop, len(self.axis(i)))
+            end = process_loc(ind.stop, len(self._axis(i)))
 
             slices.append(_core.algorithm.slice_and_rebin(i, begin, end, merge))
 
@@ -204,6 +219,8 @@ def widths(self):
 for h in _histograms:
     h.__getitem__ = _compute_getitem
     h.__setitem__ = _compute_setitem
-    h.axes = property(lambda self: AxesTuple(self.axis(i) for i in range(self.rank)))
+    h.at = at
+    h.axis = axis
+    h.axes = property(lambda self: AxesTuple(self._axis(i) for i in range(self.rank)))
 
 del h

include/boost/histogram/python/register_histogram.hpp

@@ -154,7 +154,7 @@ register_histogram(py::module &m, const char *name, const char *desc) {
             "Return a view into the data, optionally with overflow turned on")
 
         .def(
-            "axis",
+            "_axis",
             [](const histogram_t &self, int i) {
                 unsigned ii = i < 0 ? self.rank() - (unsigned)std::abs(i) : (unsigned)i;
                 if(ii < self.rank())
@@ -168,7 +168,7 @@ register_histogram(py::module &m, const char *name, const char *desc) {
             py::return_value_policy::move)
 
         .def(
-            "at",
+            "_at",
             [](const histogram_t &self, py::args &args) {
                 auto int_args = py::cast<std::vector<int>>(args);
                 return self.at(int_args);

tests/test_histogram_internal.py

@@ -34,8 +34,8 @@ def test_1D_fill_int(hist_func):
     assert_array_equal(hist.view(flow=False), H)
     assert_array_equal(hist.view(flow=True)[1:-1], H)
 
-    assert hist.axis(0).size == bins
-    assert hist.axis(0).extent == bins + 2
+    assert hist.axes[0].size == bins
+    assert hist.axes[0].extent == bins + 2
 
 
 @pytest.mark.parametrize("hist_func", methods)
@@ -56,11 +56,11 @@ def test_2D_fill_int(hist_func):
     assert_array_equal(hist.view(flow=True)[1:-1, 1:-1], H)
     assert_array_equal(hist.view(flow=False), H)
 
-    assert hist.axis(0).size == bins[0]
-    assert hist.axis(0).extent == bins[0] + 2
+    assert hist.axes[0].size == bins[0]
+    assert hist.axes[0].extent == bins[0] + 2
 
-    assert hist.axis(1).size == bins[1]
-    assert hist.axis(1).extent == bins[1] + 2
+    assert hist.axes[1].size == bins[1]
+    assert hist.axes[1].extent == bins[1] + 2
 
 
 def test_edges_histogram():
@@ -108,7 +108,7 @@ def test_numpy_flow():
 
     for i in range(10):
         for j in range(5):
-            x, y = h.axis(0).centers[i], h.axis(1).centers[j]
+            x, y = h.axes[0].centers[i], h.axes[1].centers[j]
             v = i + j * 10 + 1
             h.fill([x] * v, [y] * v)
 
@@ -132,7 +132,7 @@ def test_numpy_compare():
     ys = []
     for i in range(10):
         for j in range(5):
-            x, y = h.axis(0).centers[i], h.axis(1).centers[j]
+            x, y = h.axes[0].centers[i], h.axes[1].centers[j]
             v = i + j * 10 + 1
             xs += [x] * v
             ys += [y] * v

tests/test_make_histogram.py

@@ -11,18 +11,18 @@ def test_make_regular_1D(opt, extent):
     )
 
     assert hist.rank == 1
-    assert hist.axis(0).size == 3
-    assert hist.axis(0).extent == 3 + extent
-    assert hist.axis(0).bin(1) == (3, 4)
+    assert hist.axes[0].size == 3
+    assert hist.axes[0].extent == 3 + extent
+    assert hist.axes[0].bin(1) == (3, 4)
 
 
 def test_shortcuts():
     hist = bh.histogram((1, 2, 3), (10, 0, 1))
     assert hist.rank == 2
     for i in range(2):
-        assert isinstance(hist.axis(i), bh.axis.regular)
-        assert isinstance(hist.axis(i), bh.core.axis._regular_uoflow)
-        assert not isinstance(hist.axis(i), bh.axis.variable)
+        assert isinstance(hist.axes[i], bh.axis.regular)
+        assert isinstance(hist.axes[i], bh.core.axis._regular_uoflow)
+        assert not isinstance(hist.axes[i], bh.axis.variable)
 
 
 def test_shortcuts_with_metadata():
@@ -42,13 +42,13 @@ def test_make_regular_2D(opt, extent):
     )
 
     assert hist.rank == 2
-    assert hist.axis(0).size == 3
-    assert hist.axis(0).extent == 3 + extent
-    assert hist.axis(0).bin(1) == approx((3, 4))
+    assert hist.axes[0].size == 3
+    assert hist.axes[0].extent == 3 + extent
+    assert hist.axes[0].bin(1) == approx((3, 4))
 
-    assert hist.axis(1).size == 5
-    assert hist.axis(1).extent == 5 + extent
-    assert hist.axis(1).bin(1) == approx((2, 3))
+    assert hist.axes[1].size == 5
+    assert hist.axes[1].extent == 5 + extent
+    assert hist.axes[1].bin(1) == approx((2, 3))
 
 
 @pytest.mark.parametrize(
@@ -69,24 +69,24 @@ def test_make_any_hist(storage):
     )
 
     assert hist.rank == 3
-    assert hist.axis(0).size == 3
-    assert hist.axis(0).extent == 5
-    assert hist.axis(0).bin(1) == approx((2, 3))
-    assert hist.axis(1).size == 2
-    assert hist.axis(1).extent == 2
-    assert hist.axis(1).bin(1) == approx((3, 4))
-    assert hist.axis(2).size == 4
-    assert hist.axis(2).extent == 5
-    assert hist.axis(2).bin(1) == approx((2, 3))
+    assert hist.axes[0].size == 3
+    assert hist.axes[0].extent == 5
+    assert hist.axes[0].bin(1) == approx((2, 3))
+    assert hist.axes[1].size == 2
+    assert hist.axes[1].extent == 2
+    assert hist.axes[1].bin(1) == approx((3, 4))
+    assert hist.axes[2].size == 4
+    assert hist.axes[2].extent == 5
+    assert hist.axes[2].bin(1) == approx((2, 3))
 
 
 def test_make_any_hist_storage():
 
     assert float != type(
-        bh.histogram(bh.axis.regular(5, 1, 2), storage=bh.storage.int()).at(0)
+        bh.histogram(bh.axis.regular(5, 1, 2), storage=bh.storage.int())[0]
     )
     assert float == type(
-        bh.histogram(bh.axis.regular(5, 1, 2), storage=bh.storage.double()).at(0)
+        bh.histogram(bh.axis.regular(5, 1, 2), storage=bh.storage.double())[0]
     )
 
 
@@ -96,14 +96,14 @@ def test_issue_axis_bin_swan():
         bh.axis.circular(10, 0, 1, metadata="y"),
     )
 
-    b = hist.axis(1).bin(1)
+    b = hist.axes[1].bin(1)
     assert repr(b) == "(0.1, 0.2)"
     assert b[0] == approx(0.1)
     assert b[1] == approx(0.2)
 
-    assert hist.axis(0).bin(0)[0] == 0
-    assert hist.axis(0).bin(1)[0] == approx(0.1)
-    assert hist.axis(0).bin(2)[0] == approx(0.4)
+    assert hist.axes[0].bin(0)[0] == 0
+    assert hist.axes[0].bin(1)[0] == approx(0.1)
+    assert hist.axes[0].bin(2)[0] == approx(0.4)
 
 
 options = (

tests/test_pickle.py

@@ -108,9 +108,9 @@ def test_compare_copy_hist(metadata):
     new = copy.copy(orig)
     dnew = copy.deepcopy(orig)
 
-    assert orig.axis(0).metadata is new.axis(0).metadata
-    assert orig.axis(0).metadata == dnew.axis(0).metadata
-    assert orig.axis(0).metadata is not dnew.axis(0).metadata
+    assert orig.axes[0].metadata is new.axes[0].metadata
+    assert orig.axes[0].metadata == dnew.axes[0].metadata
+    assert orig.axes[0].metadata is not dnew.axes[0].metadata
 
 
 @pytest.mark.parametrize("axis,args", axes_creations)