Fix TrialResult deprecation (#3381) (#3382)

Fix TrialResult deprecation to cater for JSON parsing of old JSON formats.

It adds back the TrialResult json and repr files for the json repr testing, adds extra tests for the old, TrialResult based JSON parsing. It also adds the ability to deprecate classes properly via `@deprecate_class`.

Fixes #3380.

Author: balopat

cirq/_compat.py

@@ -15,7 +15,7 @@
 """Workarounds for compatibility issues between versions and libraries."""
 import functools
 import warnings
-from typing import Any, Callable, Optional, Dict, Tuple
+from typing import Any, Callable, Optional, Dict, Tuple, Type
 from types import ModuleType
 
 import numpy as np
@@ -122,6 +122,47 @@ def decorated_func(*args, **kwargs) -> Any:
     return decorator
 
 
+def deprecated_class(*, deadline: str, fix: str,
+                     name: Optional[str] = None) -> Callable[[Type], Type]:
+    """Marks a class as deprecated.
+
+    Args:
+        deadline: The version where the function will be deleted (e.g. "v0.7").
+        fix: A complete sentence describing what the user should be using
+            instead of this particular function (e.g. "Use cos instead.")
+        name: How to refer to the class.
+            Defaults to `class.__qualname__`.
+
+    Returns:
+        A decorator that decorates classes with a deprecation warning.
+    """
+
+    def decorator(clazz: Type) -> Type:
+        clazz_new = clazz.__new__
+
+        def patched_new(cls, *args, **kwargs):
+            qualname = (clazz.__qualname__ if name is None else name)
+            print(f"HELLO {qualname}")
+            warnings.warn(
+                f'{qualname} was used but is deprecated.\n'
+                f'It will be removed in cirq {deadline}.\n'
+                f'{fix}\n',
+                DeprecationWarning,
+                stacklevel=2)
+
+            return clazz_new(cls)
+
+        setattr(clazz, '__new__', patched_new)
+        clazz.__doc__ = (f'THIS CLASS IS DEPRECATED.\n\n'
+                         f'IT WILL BE REMOVED IN `cirq {deadline}`.\n\n'
+                         f'{fix}\n\n'
+                         f'{clazz.__doc__ or ""}')
+
+        return clazz
+
+    return decorator
+
+
 def deprecated_parameter(
         *,
         deadline: str,

cirq/_compat_test.py

@@ -20,7 +20,7 @@
 
 import cirq.testing
 from cirq._compat import (proper_repr, deprecated, deprecated_parameter,
-                          proper_eq, wrap_module)
+                          proper_eq, wrap_module, deprecated_class)
 
 
 def test_proper_repr():
@@ -152,3 +152,35 @@ def test_wrap_module():
 
     with cirq.testing.assert_logs(count=0):
         _ = wrapped.bar
+
+
+def test_deprecated_class():
+
+    class NewClass:
+
+        def __init__(self, a):
+            self._a = a
+
+        @property
+        def a(self):
+            return self._a
+
+        def __repr__(self):
+            return f"NewClass: {self.a}"
+
+        @classmethod
+        def hello(cls):
+            return f"hello {cls}"
+
+    @deprecated_class(deadline="deadline", fix="theFix", name="foo")
+    class OldClass(NewClass):
+        """The OldClass docs"""
+
+    assert OldClass.__doc__.startswith("THIS CLASS IS DEPRECATED")
+    assert "OldClass docs" in OldClass.__doc__
+
+    with cirq.testing.assert_logs('foo was used but is deprecated',
+                                  'will be removed in cirq deadline', 'theFix'):
+        old_obj = OldClass("1")
+        assert repr(old_obj) == "NewClass: 1"
+        assert "OldClass" in old_obj.hello()

cirq/protocols/json_serialization.py

@@ -160,6 +160,7 @@ def two_qubit_matrix_gate(matrix):
                 'TaggedOperation': cirq.TaggedOperation,
                 'ThreeDQubit': cirq.pasqal.ThreeDQubit,
                 'Result': cirq.Result,
+                'TrialResult': cirq.TrialResult,
                 'TwoDQubit': cirq.pasqal.TwoDQubit,
                 'TwoQubitMatrixGate': two_qubit_matrix_gate,
                 'TwoQubitDiagonalGate': cirq.TwoQubitDiagonalGate,