create a PL-specific deprecation warning (#4814)

**Context:**
When we deprecate features, it's hard to identify that we've done it.

**Description of the Change:**
Replace all deprecation warning categories with the new
`PennyLaneDeprecationWarning`

**Benefits:**
We can add a pytest.ini filter to make this into failures on plugins!

```
[pytest]
filterwarnings =
    error::pennylane.PennyLaneDeprecationWarning
```

(I ran a test locally with a plugin that was setting
`Observable.return_type` and saw that it raised the error)

**Possible Drawbacks:**
N/A

doc/development/deprecations.rst

@@ -3,6 +3,9 @@
 Deprecations
 ============
 
+All PennyLane deprecations will raise a ``qml.PennyLaneDeprecationWarning``. Pending and completed
+deprecations are listed below.
+
 Pending deprecations
 --------------------
 

doc/releases/changelog-dev.md

@@ -48,6 +48,9 @@
 
 <h3>Deprecations 👋</h3>
 
+* All deprecations now raise a `qml.PennyLaneDeprecationWarning` instead of a `UserWarning`.
+  [(#4814)](https://github.com/PennyLaneAI/pennylane/pull/4814)
+
 * `QuantumScript.is_sampled` and `QuantumScript.all_sampled` are deprecated.
   Users should now validate these properties manually.
   [(#4773)](https://github.com/PennyLaneAI/pennylane/pull/4773)

pennylane/__init__.py

@@ -139,6 +139,10 @@ class QuantumFunctionError(Exception):
     """Exception raised when an illegal operation is defined in a quantum function."""
 
 
+class PennyLaneDeprecationWarning(UserWarning):
+    """Warning raised when a PennyLane feature is being deprecated."""
+
+
 def _get_device_entrypoints():
     """Returns a dictionary mapping the device short name to the
     loadable entrypoint"""

pennylane/operation.py

@@ -1883,7 +1883,7 @@ def return_type(self):
         warnings.warn(
             "`Observable.return_type` is deprecated. Instead, you should "
             "inspect the type of the surrounding measurement process.",
-            UserWarning,
+            qml.PennyLaneDeprecationWarning,
         )
         return self._return_type
 
@@ -1893,7 +1893,7 @@ def return_type(self, value):
         warnings.warn(
             "`Observable.return_type` is deprecated. Instead, you should "
             "create a measurement process containing this Observable.",
-            UserWarning,
+            qml.PennyLaneDeprecationWarning,
         )
         self._return_type = value
 

pennylane/ops/functions/generator.py

@@ -88,7 +88,7 @@ def _generator_backcompatibility(op):
         "The Operator.generator property is deprecated. Please update the operator so that "
         "\n\t1. Operator.generator() is a method, and"
         "\n\t2. Operator.generator() returns an Operator instance representing the operator.",
-        UserWarning,
+        qml.PennyLaneDeprecationWarning,
     )
     gen = op.generator
 

pennylane/ops/op_math/controlled.py

@@ -268,7 +268,7 @@ def __init__(self, base, control_wires, control_values=None, work_wires=None, id
             if isinstance(control_values, str):
                 warnings.warn(
                     "Specifying control values as a string is deprecated. Please use Sequence[Bool]",
-                    UserWarning,
+                    qml.PennyLaneDeprecationWarning,
                 )
                 # All values not 0 are cast as true. Assumes a string of 1s and 0s.
                 control_values = [(x != "0") for x in control_values]

pennylane/tape/qscript.py

@@ -405,7 +405,7 @@ def is_sampled(self) -> bool:
             ">>> from pennylane.measurements import *\n"
             ">>> sample_types = (SampleMP, CountsMP, ClassicalShadowMP, ShadowExpvalMP)\n"
             ">>> is_sampled = any(isinstance(m, sample_types) for m in tape.measurements)\n",
-            UserWarning,
+            qml.PennyLaneDeprecationWarning,
         )
         sample_type = (SampleMP, CountsMP, ClassicalShadowMP, ShadowExpvalMP)
         return any(isinstance(m, sample_type) for m in self.measurements)
@@ -419,7 +419,7 @@ def all_sampled(self) -> bool:
             ">>> from pennylane.measurements import *\n"
             ">>> sample_types = (SampleMP, CountsMP, ClassicalShadowMP, ShadowExpvalMP)\n"
             ">>> all_sampled = all(isinstance(m, sample_types) for m in tape.measurements)\n",
-            UserWarning,
+            qml.PennyLaneDeprecationWarning,
         )
         sample_type = (SampleMP, CountsMP, ClassicalShadowMP, ShadowExpvalMP)
         return all(isinstance(m, sample_type) for m in self.measurements)

pennylane/transforms/__init__.py

@@ -215,9 +215,9 @@
 Old transforms framework
 ------------------------
 
-These utility functions were previously used to create transforms in PennyLane and will be
-deprecated soon. It is now recommended to use :class:`qml.transform <pennylane.transform>`
-for creation of custom transforms.
+These utility functions were previously used to create transforms in PennyLane and are now
+deprecated. It is now recommended to use :class:`qml.transform <pennylane.transform>`
+for the creation of custom transforms.
 
 .. autosummary::
     :toctree: api

pennylane/transforms/batch_transform.py

@@ -224,7 +224,7 @@ def __init__(self, transform_fn, expand_fn=None, differentiable=True):
             "Use of `batch_transform` to create a custom transform is deprecated. Instead "
             "switch to using the new qml.transform function. Follow the instructions here for "
             "further details: https://docs.pennylane.ai/en/stable/code/qml_transforms.html#custom-transforms.",
-            UserWarning,
+            qml.PennyLaneDeprecationWarning,
         )
         self.transform_fn = transform_fn
         self.expand_fn = expand_fn

pennylane/transforms/core/transform_dispatcher.py

@@ -134,7 +134,7 @@ def processing_fn(results):
             "or call the transform directly using qnode = transform_fn(qnode, "
             "**transform_kwargs). Visit the deprecations page for more details: "
             "https://docs.pennylane.ai/en/stable/development/deprecations.html",
-            UserWarning,
+            qml.PennyLaneDeprecationWarning,
         )
 
         if obj is not None:

pennylane/transforms/op_transforms.py

@@ -203,7 +203,7 @@ def __init__(self, fn):
             "Use of `op_transform` to create a custom transform is deprecated. Instead "
             "switch to using the new qml.transform function. Follow the instructions here for "
             "further details: https://docs.pennylane.ai/en/stable/code/qml_transforms.html#custom-transforms.",
-            UserWarning,
+            qml.PennyLaneDeprecationWarning,
         )
         self._fn = fn
         self._sig = inspect.signature(fn).parameters

pennylane/transforms/qfunc_transforms.py

@@ -150,7 +150,7 @@ def __init__(self, transform_fn):
             "Use of `single_tape_transform` to create a custom transform is deprecated. Instead "
             "switch to using the new qml.transform function. Follow the instructions here for "
             "further details: https://docs.pennylane.ai/en/stable/code/qml_transforms.html#custom-transforms.",
-            UserWarning,
+            qml.PennyLaneDeprecationWarning,
         )
         self.transform_fn = transform_fn
         functools.update_wrapper(self, transform_fn)
@@ -405,11 +405,11 @@ def new_qfunc(*args, **kwargs):
         "Use of `qfunc_transform` to create a custom transform is deprecated. Instead "
         "switch to using the new qml.transform function. Follow the instructions here for "
         "further details: https://docs.pennylane.ai/en/stable/code/qml_transforms.html#custom-transforms.",
-        UserWarning,
+        qml.PennyLaneDeprecationWarning,
     )
     if not isinstance(tape_transform, single_tape_transform):
         with warnings.catch_warnings():
-            warnings.simplefilter("ignore", UserWarning)
+            warnings.simplefilter("ignore", qml.PennyLaneDeprecationWarning)
             tape_transform = single_tape_transform(tape_transform)
 
     sig = inspect.signature(tape_transform)

pennylane/vqe/vqe.py

@@ -156,7 +156,7 @@ def __init__(
             "ExpvalCost is deprecated, use qml.expval() instead. "
             "For optimizing Hamiltonian measurements with measuring commuting "
             "terms in parallel, use the grouping_type keyword in qml.Hamiltonian.",
-            UserWarning,
+            qml.PennyLaneDeprecationWarning,
         )
 
         if kwargs.get("measure", "expval") != "expval":