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

tools/telemetry/telemetry/util/file_handle.py

Index: tools/telemetry/telemetry/util/file_handle.py
diff --git a/tools/telemetry/telemetry/util/file_handle.py b/tools/telemetry/telemetry/util/file_handle.py
new file mode 100644
index 0000000000000000000000000000000000000000..456d5b90b923a94f15a84dda567002d146753300
--- /dev/null
+++ b/tools/telemetry/telemetry/util/file_handle.py
@@ -0,0 +1,90 @@
+# 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.
+
+import os
+import shutil
+
+_next_file_id = 0
+
+class FileHandle(object):
+  def __init__(self, tf, absolute_path=None):
+    """Constructs a FileHandle object.
+
+    This constructor should not be used by the user; rather it is preferred to
+    use the module-level GetRelPath and FromTempFile functions.
+
+    Args:
+      tf: An instance of a temporary file object.
+      absolute_path: A path; should not be passed if tempfile is and vice-versa.
+    """
+    # We should never build a file handle from nothing.
+    assert (absolute_path is None) != (tf is None)
+    self._tf = tf
+    self._absolute_path = absolute_path
+
+    global _next_file_id
+    self._id = _next_file_id
+    _next_file_id += 1
+
+  @property
+  def id(self):
+    return self._id
+
+  def GetRelPath(self, start=os.curdir):
+    """Returns the path to the pointed-to file relative to the given start path.
+
+    Args:
+      start: A string representing a starting path.
+    Returns:
+      A string giving the relative path from path to this file.
+    """
+    if self._tf:
+      name = self._tf.name
+    else:
+      name = self._absolute_path
+
+    return os.path.relpath(name, start)
+
+def FromTempFile(tf):
+  """Constructs a FileHandle pointing to a temporary file.
+
+  Returns:
+    A FileHandle referring to a named temporary file.
+  """
+  return FileHandle(tf)
+
+def FromPath(path):
+  """Constructs a FileHandle from an absolute path.
+
+  Args:
+    path: A string giving the absolute path to a file.
+  Returns:
+    A FileHandle referring to the file at the specified path.
+  """
+  return FileHandle(None, os.path.abspath(path))
+
+def OutputFiles(file_handles, prefix, extension):
+  """Outputs a list of file_handles by ID with a given prefix and extension.
+
+  For the normal use case where we generate a collection of FileHandles
+  corresponding to temporary files, it is often necessary to collate the
+  represented files into a single place. This function copies each file
+  referenced by an element of file_handles to a standardized location indicated
+  by prefix.
+
+  Args:
+    file_handles: A list of file handles
+    prefix: A string, usually a path.
+    extension: Extension to append.
+  Returns:
+    A dict mapping IDs to output filenames.
+  """
+  files = dict()
+
+  for fh in file_handles:
+    name = prefix + str(fh.id) + extension
+    shutil.copy(fh.GetRelPath(), name)
+    files[fh.id] = os.path.abspath(name)
+
+  return files