Add examples of how to deprecate a keyword, and fix spacing.

Author: eric

pandas/tests/test_algos.py

@@ -249,6 +249,8 @@ def test_uint64_factorize(self):
         tm.assert_numpy_array_equal(uniques, exp_uniques)
 
     def test_deprecate_order(self):
+        # gh 19727 - check warning is raised for deprecated keyword, order.
+        # Test not valid once order keyword is removed.
         data = np.array([2**63, 1, 2**63], dtype=np.uint64)
         with tm.assert_produces_warning(expected_warning=FutureWarning):
             algos.factorize(data, order=True)

pandas/util/_decorators.py

@@ -97,6 +97,24 @@ def deprecate_kwarg(old_arg_name, new_arg_name, mapping=None, stacklevel=2):
     FutureWarning: old='yes' is deprecated, use new=True instead
       warnings.warn(msg, FutureWarning)
     yes!
+
+
+    To raise a warning that a keyword will be removed entirely in the future
+
+    >>> @deprecate_kwarg(old_arg_name='cols', new_arg_name=None)
+    ... def f(cols='', another_param=''):
+    ...     print(cols)
+    ...
+    >>> f(cols='should raise warning')
+    FutureWarning: the 'cols' keyword is deprecated and will be removed in a
+    future version please takes steps to stop use of 'cols'
+    should raise warning
+    >>> f(another_param='should not raise warning')
+    should not raise warning
+    >>> f(cols='should raise warning', another_param='')
+    FutureWarning: the 'cols' keyword is deprecated and will be removed in a
+    future version please takes steps to stop use of 'cols'
+    should raise warning
     """
 
     if mapping is not None and not hasattr(mapping, 'get') and \
@@ -111,8 +129,8 @@ def wrapper(*args, **kwargs):
 
             if new_arg_name is None and old_arg_value is not None:
                 msg = (
-                    "the '{old_name}' keyword is deprecated and will be"
-                    "removed in a future version"
+                    "the '{old_name}' keyword is deprecated and will be "
+                    "removed in a future version "
                     "please takes steps to stop use of '{old_name}'"
                 ).format(old_name=old_arg_name)
                 warnings.warn(msg, FutureWarning, stacklevel=stacklevel)