feat: Add internal API to warn of deprecation and future removal (#2012)

* Add internal API pyhf.exceptions._deprecated_api_warning to alert users to API deprecation
  by raising a subclass of DeprecationWarning and future removal.
* Add test for pyhf.exceptions._deprecated_api_warning to ensure it gets picked up as
  DeprecationWarning.

src/pyhf/exceptions/__init__.py

@@ -1,4 +1,5 @@
 import sys
+from warnings import warn
 
 __all__ = [
     "FailedMinimization",
@@ -175,3 +176,15 @@ def __init__(self, result):
             result, 'message', "Unknown failure. See fit result for more details."
         )
         super().__init__(message)
+
+
+# Deprecated APIs
+def _deprecated_api_warning(
+    deprecated_api, new_api, deprecated_release, remove_release
+):
+    warn(
+        f"{deprecated_api} is deprecated in favor of {new_api} as of pyhf v{deprecated_release} and will be removed in pyhf v{remove_release}."
+        + f" Please use {new_api}.",
+        DeprecationWarning,
+        stacklevel=3,  # Raise to user level
+    )

tests/test_regression.py

@@ -1,3 +1,5 @@
+import warnings
+
 import numpy as np
 import pytest
 from skhep_testdata import data_path
@@ -176,3 +178,19 @@ def test_sbottom_regionC_1600_850_60(get_json_from_tarfile):
             rtol=1e-5,
         )
     )
+
+
+def test_deprecated_api_warning():
+    with warnings.catch_warnings(record=True) as _warning:
+        # Cause all warnings to always be triggered
+        warnings.simplefilter("always")
+
+        pyhf.exceptions._deprecated_api_warning(
+            "deprecated_api", "new_api", "0.9.9", "1.0.0"
+        )
+        assert len(_warning) == 1
+        assert issubclass(_warning[-1].category, DeprecationWarning)
+        assert (
+            "deprecated_api is deprecated in favor of new_api as of pyhf v0.9.9 and will be removed in pyhf v1.0.0."
+            in str(_warning[-1].message)
+        )