[recipe_modules/file] add real file module to engine.

recipe_modules/file/test_api.py

+# Copyright 2017 The LUCI Authors. All rights reserved.
+# Use of this source code is governed under the Apache License, Version 2.0
+# that can be found in the LICENSE file.
+
+import os
+
+from recipe_engine import recipe_test_api
+
+
+class FileTestApi(recipe_test_api.RecipeTestApi):
+  def listdir(self, files=(), errno_name=0):
+    """Provides test mock for the `listdir` method.
+
+    Args:
+      files (iterable[str]) - The list of file names for this `listdir` step to
+        return.
+      errno_name (str|None) - The error name for this step to return, if any.
+
+    Example:
+      yield (api.test('my_test')
+        + api.file.listdir('list step name', ['some', 'file', 'names'])
+      )
+    """
+    return (self.m.raw_io.stream_output('\n'.join(files))
+            + self.errno(errno_name))
+
+  def read_text(self, text_content='', errno_name=0):
+    """Provides test mock for the `read_text` method.
+
+    Args:
+      text_content (str) - The text data for this read_text step to return.
+      errno_name (str|None) - The error name for this step to return, if any.
+
+    Example:
+      yield (api.test('my_test')
+        + api.file.read_text('read step name', 'some\nfile\ncontent')
+      )
+    """
+    return (self.m.raw_io.output_text(text_content)
+            + self.errno(errno_name))
+
+  def glob_paths(self, paths=(), errno_name=0):

[dnj, 2017/05/31 16:50:40]

errno_name=0 .. why not None? I like None as a more descriptive and less
committal default. Imagine you're someone wrapping this, now you have to
propagate the "0" default to the wrapper etc. etc. Here and elsewhere.

+    """Provides test mock for the `glob_paths` method.
+
+    Args:
+      paths (iterable[str|Path]) - The paths for the glob_paths step to return.
+      errno_name (str|None) - The error name for this step to return, if any.
+
+    Example:
+      yield (api.test('my_test')
+        + api.file.glob_paths('glob step name', [
+          '[BASE_PATH]/some/path',
+          '[BASE_PATH]/some/other_thing',
+        ])
+      )
+    """
+    return (self.m.raw_io.stream_output('\n'.join(map(str, paths)))
+            + self.errno(errno_name))
+
+  def errno(self, errno_name=None):
+    """Provides test mock for any file module method, causing the step to raise
+    a file.Error exception.
+
+    Args:
+      errno_name (None|str) - The errno error name that the step should raise.
+        This must be e.g. 'EPERM', 'EEXIST', etc.

[dnj, 2017/05/31 16:50:40]

'must be ... etc.' seems silly - either have some constants and must be one of
them, or "should be"

+    """
+    data = {'ok': True}
+    if errno_name:
+      data['ok'] = False
+      data['errno_name'] = errno_name
+      # in real operation, this message will come from the underlying OS and
+      # will potentially have descriptive detail.
+      data['message'] = 'file command encountered system error '+errno_name
+    return self.m.json.output(data, name='main')