DEP: Deprecate random_integers

doc/release/1.11.0-notes.rst

@@ -184,15 +184,23 @@ that will not be backward compatible.
 
 Invalid arguments for array ordering
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-It is currently possible to pass in arguments for the ```order```
-parameter in methods like ```array.flatten``` or ```array.ravel```
+It is currently possible to pass in arguments for the ``order``
+parameter in methods like ``array.flatten`` or ``array.ravel``
 that were not one of the following: 'C', 'F', 'A', 'K' (note that
 all of these possible values are unicode- and case-insensitive).
 Such behaviour will not be allowed in future releases.
 
 Random number generator in the ``testing`` namespace
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Python standard library random number generator was previously exposed in the
 ``testing`` namespace as ``testing.rand``. Using this generator is not
 recommended and it will be removed in a future release. Use generators from
 ``numpy.random`` namespace instead.
+
+Random integer generation on a closed interval
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In accordance with the Python C API, which gives preference to the half-open
+interval over the closed one, ``np.random.random_integers`` is being
+deprecated in favor of calling ``np.random.randint``, which has been
+enhanced with the ``dtype`` parameter as described under "New Features".
+However, ``np.random.random_integers`` will not be removed anytime soon.

numpy/random/mtrand/mtrand.pyx

@@ -1683,6 +1683,10 @@ cdef class RandomState:
         type translates to the C long type used by Python 2 for "short"
         integers and its precision is platform dependent.
 
+        This function has been deprecated. Use randint instead.
+
+        .. deprecated:: 1.11.0
+
         Parameters
         ----------
         low : int
@@ -1748,9 +1752,17 @@ cdef class RandomState:
 
         """
         if high is None:
+            warnings.warn(("This function is deprecated. Please call "
+                           "randint(1, {low} + 1) instead".format(low=low)),
+                          DeprecationWarning)
             high = low
             low = 1
 
+        else:
+            warnings.warn(("This function is deprecated. Please call "
+                           "randint({low}, {high} + 1) instead".format(
+                    low=low, high=high)), DeprecationWarning)
+
         return self.randint(low, high + 1, size=size, dtype='l')
 
 

numpy/random/tests/test_random.py

@@ -7,6 +7,8 @@
 from numpy import random
 from numpy.compat import asbytes
 import sys
+import warnings
+
 
 class TestSeed(TestCase):
     def test_scalar(self):
@@ -255,6 +257,20 @@ def test_random_integers_max_int(self):
         desired = np.iinfo('l').max
         np.testing.assert_equal(actual, desired)
 
+    def test_random_integers_deprecated(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", DeprecationWarning)
+
+            # DeprecationWarning raised with high == None
+            assert_raises(DeprecationWarning,
+                          np.random.random_integers,
+                          np.iinfo('l').max)
+
+            # DeprecationWarning raised with high != None
+            assert_raises(DeprecationWarning,
+                          np.random.random_integers,
+                          np.iinfo('l').max, np.iinfo('l').max)
+
     def test_random_sample(self):
         np.random.seed(self.seed)
         actual = np.random.random_sample((3, 2))