DEPR: Add deprecation warning for factorize() order keyword

pandas/core/algorithms.py

@@ -32,6 +32,7 @@
 from pandas.core import common as com
 from pandas._libs import algos, lib, hashtable as htable
 from pandas._libs.tslib import iNaT
+from pandas.util._decorators import deprecate_kwarg
 
 
 # --------------- #
@@ -436,6 +437,7 @@ def isin(comps, values):
     return f(comps, values)
 
 
+@deprecate_kwarg(old_arg_name='order', new_arg_name=None)
 def factorize(values, sort=False, order=None, na_sentinel=-1, size_hint=None):
     """
     Encode input values as an enumerated type or categorical variable

pandas/tests/util/test_util.py

@@ -34,9 +34,14 @@ def _f2(new=False):
         def _f3(new=0):
             return new
 
+        @deprecate_kwarg('old', None)
+        def _f4(old=True, unchanged=True):
+            return old
+
         self.f1 = _f1
         self.f2 = _f2
         self.f3 = _f3
+        self.f4 = _f4
 
     def test_deprecate_kwarg(self):
         x = 78
@@ -72,6 +77,15 @@ def test_bad_deprecate_kwarg(self):
             def f4(new=None):
                 pass
 
+    def test_deprecate_keyword(self):
+        x = 9
+        with tm.assert_produces_warning(FutureWarning):
+            result = self.f4(old=x)
+        assert result is x
+        with tm.assert_produces_warning(None):
+            result = self.f4(unchanged=x)
+        assert result is True
+
 
 def test_rands():
     r = tm.rands(10)

pandas/util/_decorators.py

@@ -65,8 +65,9 @@ def deprecate_kwarg(old_arg_name, new_arg_name, mapping=None, stacklevel=2):
     ----------
     old_arg_name : str
         Name of argument in function to deprecate
-    new_arg_name : str
-        Name of preferred argument in function
+    new_arg_name : str | None
+        Name of preferred argument in function. Use none to raise warning that
+        ``old_arg_name`` keyword is deprecated.
     mapping : dict or callable
         If mapping is present, use it to translate old arguments to
         new arguments. A callable must do its own value checking;
@@ -107,6 +108,16 @@ def _deprecate_kwarg(func):
         @wraps(func)
         def wrapper(*args, **kwargs):
             old_arg_value = kwargs.pop(old_arg_name, None)
+
+            if new_arg_name is None and old_arg_value is not None:
+                msg = (
+                    "the '{old_name}' keyword is no longer supported"
+                    "please takes steps to stop use of '{old_name}'"
+                ).format(old_name=old_arg_name)
+                warnings.warn(msg, FutureWarning, stacklevel=stacklevel)
+                kwargs[old_arg_name] = old_arg_value
+                return func(*args, **kwargs)
+
             if old_arg_value is not None:
                 if mapping is not None:
                     if hasattr(mapping, 'get'):