Add qpy deprecation warning class (#11260)

* Add qpy deprecation warning class

* Add docs, reno

* Fix docs

* Update qpy complex amp warning

qiskit/qpy/__init__.py

@@ -92,6 +92,12 @@
 0.29.0. However, loading that QPY file with 0.18.0 is not supported and may not
 work.
 
+If a feature being loaded is deprecated in the corresponding qiskit release, QPY will
+raise a :exc:`~.QPYLoadingDeprecatedFeatureWarning` informing of the deprecation period
+and how the feature will be internally handled.
+
+.. autoexception:: QPYLoadingDeprecatedFeatureWarning
+
 .. _qpy_format:
 
 **********
@@ -1335,7 +1341,7 @@ class if it's defined in Qiskit. Otherwise it falls back to the custom
 .. [#f3] https://docs.python.org/3/c-api/complex.html#c.Py_complex
 """
 
-from .exceptions import QpyError
+from .exceptions import QpyError, QPYLoadingDeprecatedFeatureWarning
 from .interface import dump, load
 
 # For backward compatibility. Provide, Runtime, Experiment call these private functions.

qiskit/qpy/binary_io/schedules.py

@@ -29,7 +29,7 @@
 from qiskit.pulse.schedule import ScheduleBlock
 from qiskit.qpy import formats, common, type_keys
 from qiskit.qpy.binary_io import value
-from qiskit.qpy.exceptions import QpyError
+from qiskit.qpy.exceptions import QpyError, QPYLoadingDeprecatedFeatureWarning
 from qiskit.pulse.configuration import Kernel, Discriminator
 
 
@@ -162,7 +162,7 @@ def _read_symbolic_pulse(file_obj, version):
             "Complex amp support for symbolic library pulses will be deprecated. "
             "Once deprecated, library pulses loaded from old QPY files (Terra version < 0.23),"
             " will be converted automatically to float (amp,angle) representation.",
-            PendingDeprecationWarning,
+            QPYLoadingDeprecatedFeatureWarning,
         )
         class_name = "ScalableSymbolicPulse"
 

qiskit/qpy/exceptions.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2022.
+# (C) Copyright IBM 2022, 2023.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -26,3 +26,8 @@ def __init__(self, *message):
     def __str__(self):
         """Return the message."""
         return repr(self.message)
+
+
+class QPYLoadingDeprecatedFeatureWarning(UserWarning):
+    """Visible deprecation warning for QPY loading functions without
+    a stable point in the call stack."""

releasenotes/notes/add-qpy-loading-depr-warning-8628b23ca63c3eb5.yaml

@@ -0,0 +1,7 @@
+---
+features:
+  - |
+    A new exception, :exc:`~.QPYLoadingDeprecatedFeatureWarning`, has been added to the QPY module.
+    This class allows for deprecation warnings to surface even if the depreacted feature
+    is in a variable point in the call stack, as is the case for many QPY loading functions that
+    are called recursively.