POC: deprecation with strict removal version

pandas/core/generic.py

@@ -30,7 +30,12 @@
 from pandas.compat._optional import import_optional_dependency
 from pandas.compat.numpy import function as nv
 from pandas.errors import AbstractMethodError
-from pandas.util._decorators import Appender, Substitution, rewrite_axis_style_signature
+from pandas.util._decorators import (
+    Appender,
+    Substitution,
+    rewrite_axis_style_signature,
+    strict_deprecation,
+)
 from pandas.util._validators import validate_bool_kwarg, validate_fillna_kwargs
 
 from pandas.core.dtypes.cast import maybe_promote, maybe_upcast_putmask
@@ -5334,6 +5339,7 @@ def _get_bool_data(self):
     # ----------------------------------------------------------------------
     # Internal Interface Methods
 
+    @strict_deprecation("Example usage", deprecated_in="0.23.0", remove_in="0.26.0")
     def as_matrix(self, columns=None):
         """
         Convert the frame to its Numpy-array representation.

pandas/tests/api/test_api.py

@@ -1,3 +1,5 @@
+from pandas.util._decorators import check_deprecations
+
 import pandas as pd
 from pandas import api, compat
 from pandas.util import testing as tm
@@ -232,3 +234,7 @@ def test_testing(self):
         from pandas import testing
 
         self.check(testing, self.funcs)
+
+
+def test_deprecations_removed():
+    check_deprecations(pd.__version__)

pandas/util/_decorators.py

@@ -347,3 +347,34 @@ def indent(text: Optional[str], indents: int = 1) -> str:
         return ""
     jointext = "".join(["\n"] + ["    "] * indents)
     return jointext.join(text.split("\n"))
+
+
+_deprecation_registry = {}
+
+
+def strict_deprecation(msg, deprecated_in, remove_in):
+    def deprecator(arg):
+        if isinstance(arg, str):
+            key = arg
+        else:
+            key = arg.__name__
+
+        _deprecation_registry[key] = (msg, deprecated_in, remove_in)
+
+        return arg
+
+    return deprecator
+
+
+def check_deprecations(version):
+    from distutils.version import LooseVersion
+
+    version = LooseVersion(version)
+
+    for key in _deprecation_registry:
+        value = _deprecation_registry[key]
+        remove_in = _deprecation_registry[key][-1]
+        remove_in = LooseVersion(remove_in)
+
+        if remove_in <= version:
+            raise AssertionError(key, value)