[Telemetry] Add Deprecated decorators and apply it for page_set

BUG=439512, 472215

TEST=./tools/perf/run_benchmark --browser=system smoothness.maps

Review URL: https://codereview.chromium.org/1171113002

Cr-Commit-Position: refs/heads/master@{#333647}

tools/telemetry/telemetry/decorators.py

@@ -3,9 +3,13 @@
 # found in the LICENSE file.
 # pylint: disable=W0212
 
+import datetime
 import functools
+import os
 import inspect
 import types
+import warnings
+
 
 def Cache(obj):
   """Decorator for caching read-only properties.
@@ -32,6 +36,66 @@ def Cache(obj):
   return Cacher
 
 
+class Deprecated(object):
+
+  def __init__(self, year, month, day, extra_guidance=''):
+    self._date_of_support_removal = datetime.date(year, month, day)
+    self._extra_guidance = extra_guidance
+
+  def _DisplayWarningMessage(self, target):
+    target_str = ''
+    if isinstance(target, types.FunctionType):
+      target_str = 'Function %s' % target.__name__
+    else:
+      target_str = 'Class %s' % target.__name__
+    warnings.warn('%s is deprecated. It will no longer be supported on %s. '
+                  'Please remove it or switch to an alternative before '
+                  'that time. %s\n'
+                  % (target_str,
+                     self._date_of_support_removal.strftime('%B %d, %Y'),
+                     self._extra_guidance),
+                  stacklevel=self._ComputeStackLevel())
+
+  def _ComputeStackLevel(self):
+    this_file, _ = os.path.splitext(__file__)
+    frame = inspect.currentframe()
+    i = 0
+    while True:
+      filename = frame.f_code.co_filename
+      if not filename.startswith(this_file):
+        return i
+      frame = frame.f_back
+      i += 1
+
+  def __call__(self, target):
+    if isinstance(target, types.FunctionType):
+      @functools.wraps(target)
+      def wrapper(*args, **kwargs):
+        self._DisplayWarningMessage(target)
+        target(*args, **kwargs)
+      return wrapper
+    elif inspect.isclass(target):
+      original_ctor = target.__init__
+
+      # We have to handle case original_ctor is object.__init__ seperately
+      # since object.__init__ does not have __module__ defined, which
+      # cause functools.wraps() to raise exception.
+      if original_ctor == object.__init__:
+        def new_ctor(*args, **kwargs):
+          self._DisplayWarningMessage(target)
+          return original_ctor(*args, **kwargs)
+      else:
+        @functools.wraps(original_ctor)
+        def new_ctor(*args, **kwargs):
+          self._DisplayWarningMessage(target)
+          return original_ctor(*args, **kwargs)
+
+      target.__init__ = new_ctor
+      return target
+    else:
+      raise TypeError('@Deprecated is only applicable to functions or classes')
+
+
 def Disabled(*args):
   """Decorator for disabling tests/benchmarks.
 

tools/telemetry/telemetry/decorators_unittest.py

@@ -5,6 +5,10 @@
 import unittest
 
 from telemetry import decorators
+from telemetry.core import util
+
+util.AddDirToPythonPath(util.GetTelemetryDir(), 'third_party', 'mock')
+import mock  # pylint:disable=import-error
 
 
 class FakePlatform(object):
@@ -82,3 +86,78 @@ class TestShouldSkip(unittest.TestCase):
 
     test.SetDisabledStrings(['another_os_name', 'another_os_version_name'])
     self.assertFalse(decorators.ShouldSkip(test, possible_browser)[0])
+
+class TestDeprecation(unittest.TestCase):
+
+  @mock.patch('warnings.warn')
+  def testFunctionDeprecation(self, warn_mock):
+    @decorators.Deprecated(2015, 12, 1)
+    def Foo(x):
+      return x
+    Foo(1)
+    warn_mock.assert_called_with(
+        'Function Foo is deprecated. It will no longer be supported on '
+        'December 01, 2015. Please remove it or switch to an alternative '
+        'before that time. \n', stacklevel=4)
+
+  @mock.patch('warnings.warn')
+  def testMethodDeprecated(self, warn_mock):
+
+    class Bar(object):
+      @decorators.Deprecated(2015, 12, 1, 'Testing only.')
+      def Foo(self, x):
+        return x
+
+    Bar().Foo(1)
+    warn_mock.assert_called_with(
+        'Function Foo is deprecated. It will no longer be supported on '
+        'December 01, 2015. Please remove it or switch to an alternative '
+        'before that time. Testing only.\n', stacklevel=4)
+
+  @mock.patch('warnings.warn')
+  def testClassWithoutInitDefinedDeprecated(self, warn_mock):
+    @decorators.Deprecated(2015, 12, 1)
+    class Bar(object):
+      def Foo(self, x):
+        return x
+
+    Bar().Foo(1)
+    warn_mock.assert_called_with(
+        'Class Bar is deprecated. It will no longer be supported on '
+        'December 01, 2015. Please remove it or switch to an alternative '
+        'before that time. \n', stacklevel=4)
+
+  @mock.patch('warnings.warn')
+  def testClassWithInitDefinedDeprecated(self, warn_mock):
+
+    @decorators.Deprecated(2015, 12, 1)
+    class Bar(object):
+      def __init__(self):
+        pass
+      def Foo(self, x):
+        return x
+
+    Bar().Foo(1)
+    warn_mock.assert_called_with(
+        'Class Bar is deprecated. It will no longer be supported on '
+        'December 01, 2015. Please remove it or switch to an alternative '
+        'before that time. \n', stacklevel=4)
+
+  @mock.patch('warnings.warn')
+  def testInheritedClassDeprecated(self, warn_mock):
+    class Ba(object):
+      pass
+
+    @decorators.Deprecated(2015, 12, 1)
+    class Bar(Ba):
+      def Foo(self, x):
+        return x
+
+    class Baz(Bar):
+      pass
+
+    Baz().Foo(1)
+    warn_mock.assert_called_with(
+        'Class Bar is deprecated. It will no longer be supported on '
+        'December 01, 2015. Please remove it or switch to an alternative '
+        'before that time. \n', stacklevel=4)

tools/telemetry/telemetry/page/page_set.py

@@ -5,13 +5,16 @@
 import os
 
 from telemetry.page import page as page_module
+from telemetry import decorators
 from telemetry import story
 
 PUBLIC_BUCKET = story.PUBLIC_BUCKET
 PARTNER_BUCKET = story.PARTNER_BUCKET
 INTERNAL_BUCKET = story.INTERNAL_BUCKET
 
-
+@decorators.Deprecated(
+    2015, 6, 25, 'Please use the UserStory class instead (crbug.com/439512). '
+    'Instructions for conversion can be found in: https://goo.gl/JsaEez')
 class PageSet(story.StorySet):
   def __init__(self, file_path=None, archive_data_file='', user_agent_type=None,
                serving_dirs=None, bucket=None):