[Telemetry] Add capability for values to reference external files.

tools/telemetry/telemetry/value/__init__.py

 # Copyright 2014 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 """
 The Value hierarchy provides a way of representing the values measurements
 produce such that they can be merged across runs, grouped by page, and output
 to different targets.
 
 The core Value concept provides the basic functionality:
 - association with a page, may be none
@@ skipping 24 matching lines @@
 # value is being interpreted actually affects the conversion. This is insane,
 # but there you have it. There are three contexts in which Values are converted
 # for use by buildbot, represented by these output-intent values.
 PER_PAGE_RESULT_OUTPUT_CONTEXT = 'per-page-result-output-context'
 COMPUTED_PER_PAGE_SUMMARY_OUTPUT_CONTEXT = 'merged-pages-result-output-context'
 SUMMARY_RESULT_OUTPUT_CONTEXT = 'summary-result-output-context'
 
 class Value(object):
   """An abstract value produced by a telemetry page test.
   """
-  def __init__(self, page, name, units, important, description):
+  def __init__(self, page, name, units, important, description, paths):
     """A generic Value object.
 
     Args:
       page: A Page object, may be given as None to indicate that the value
           represents results for multiple pages.
       name: A value name string, may contain a dot. Values from the same test
           with the same prefix before the dot may be considered to belong to
           the same chart.
       units: A units string.
       important: Whether the value is "important". Causes the value to appear
           by default in downstream UIs.
       description: A string explaining in human-understandable terms what this
           value represents.
+      paths: A list of paths corresponding to files associated with this value.

[nednguyen, 2014/09/08 18:45:24]

What are paths? Are they strings, or are they instances of some classes? In
addition, what does it mean if some paths are relative? i.e: which file location
does ./foo.txt refers too? Do paths need to exist?

It seems to me that having a Path class like your previous patch that answers
these questions and raise corresponding exceptions in case of invalid values is
better the strings representation.

     """
     self.page = page
     self.name = name
     self.units = units
     self.important = important
     self.description = description
+    if paths is None:
+      self.paths = []
+    else:
+      self.paths = paths
 
   def IsMergableWith(self, that):
     return (self.units == that.units and
             type(self) == type(that) and
             self.important == that.important)
 
   @classmethod
   def MergeLikeValuesFromSamePage(cls, values):
     """Combines the provided list of values into a single compound value.
 
@@ skipping 103 matching lines @@
     d = {
       'name': self.name,
       'type': self.GetJSONTypeName(),
       'units': self.units,
     }
 
     if self.description:
       d['description'] = self.description
 
     if self.page:
       d['page_id'] = self.page.id

[nduca, 2014/09/08 18:53:02]

How about

   ""Returns file handle... or none."""
   def GetAssociatedFileHandle(self):
     return None

 
+    if self.paths:
+      # Assigning IDs to paths is a serialization detail, so we defer updating
+      # this to an ID until we actually intend on serializing this value.
+      d['paths'] = self.paths
+
     return d
 
   def AsDictWithoutBaseClassEntries(self):
     full_dict = self.AsDict()
     base_dict_keys = set(self._AsDictImpl().keys())
 
     # Extracts only entries added by the subclass.
     return dict([(k, v) for (k, v) in full_dict.iteritems()
                   if k not in base_dict_keys])
 
@@ skipping 97 matching lines @@
   whereas telemetry represents values with a chart_name.trace_name convention,
   where chart_name is optional. This convention is also used by chart_json.
 
   This converts from the telemetry convention to the buildbot convention,
   returning a 2-tuple (measurement_name, trace_name).
   """
   if '.' in value_name:
     return value_name.split('.', 1)
   else:
     return value_name, value_name