Docserver: Generate a table of extension/app API owners

chrome/common/extensions/docs/server2/owners_data_source.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.
+
+from operator import itemgetter
+import posixpath
+
+from data_source import DataSource
+from docs_server_utils import MarkLast
+from extensions_paths import BROWSER_API_PATHS, BROWSER_CHROME_EXTENSIONS
+from file_system import FileNotFoundError
+from future import All
+
+
+_COMMENT_START_MARKER = '#'
+_OWNERS = 'OWNERS'
+
+
+def _ParseOwnersFile(content):
+  '''Returns a tuple (owners, notes), where
+  |owners| is a list of dicts formed from the owners in |content|,
+  |notes| is a string formed from the comments in |content|.
+  '''
+  if content is None:
+    return [], 'See core extensions owners.'

[not at google - send to devlin, 2014/08/15 15:45:51]

Let's share a string with 'Core Extensions/Apps Owners'. Like, 'Use one of the '
+ CORE_OWNERS for example.

Speaking of which - could you add a TODO for randomizing that list of core
OWNERS? We have a persistent problem where people at the top of the list get
more reviews. It'd be cool if they were randomised. Not really a priority, just
a neat idea :)

+  owners = []
+  notes = []
+  for line in content.splitlines():
+    if line == '':
+      continue
+    if line.startswith(_COMMENT_START_MARKER):
+      notes.append(line[len(_COMMENT_START_MARKER):].lstrip())
+    else:
+      # TODO(ahernandez): Mark owners no longer on the project.
+      owners.append({'email': line, 'username': line[:line.find('@')]})
+  MarkLast(owners)
+  return owners, ' '.join(notes)
+
+
+class OwnersDataSource(DataSource):
+  def __init__(self, server_instance, _):
+    self._host_fs = server_instance.host_file_system_provider.GetTrunk()
+    self._cache = server_instance.object_store_creator.Create(OwnersDataSource)
+    self._owners_fs = server_instance.compiled_fs_factory.Create(
+        self._host_fs, self._CreateAPIEntry, OwnersDataSource)
+
+  def _CreateAPIEntry(self, path, content):

[not at google - send to devlin, 2014/08/15 15:45:51]

content is optional, so content=None.

[not at google - send to devlin, 2014/08/21 21:39:57]

Oh, my bad. sorry.

+    '''Creates a dict with owners information for an API, specified
+    by |owners_file|.
+    '''
+    owners, notes = _ParseOwnersFile(content)
+    return {
+      'apiName': posixpath.basename(posixpath.dirname(path)),
+      'owners': owners,
+      'notes': notes
+    }
+
+  def _CollectOwnersData(self):
+    '''Walks through the file system, collecting owners data from
+    API directories.
+    '''
+    def collect(api_owners):
+      if api_owners is not None:
+        return api_owners
+      api_owners = []
+      for root in BROWSER_API_PATHS:
+        for base, dirs, _ in self._host_fs.Walk(root, depth=1):
+          for dir_ in dirs:
+            owners_file = posixpath.join(root, base, dir_, _OWNERS)

[not at google - send to devlin, 2014/08/15 15:45:51]

For all of these posixpath calls, prefer using the functions in path_util (Join,
etc). Mostly because they do path validation, but they're also more concise.
There might be an equivalent for basename?

+            if self._owners_fs.FileExists(owners_file).Get():

[not at google - send to devlin, 2014/08/15 15:45:51]

What happened to using .Then() everywhere?

I'm wondering if to simplify all of this the file system methods (both on
CompiledFileSystem and FileSystem) should respect a skip_not_found flag. Already
~half of the methods do. It would be so nice to be able to avoid calling
Exists() and/or deal with exceptions.

Actually this wouldn't be so hard.
- Make CompiledFileSystem.ReadFrom* take a skip_not_found flag.
- Same for CacheChainFileSystem.
- Make FileSystem.ReadSingle take a skip_not_found flag, easy, just passes
through to Read.

Then you'd be able to write this so much more simply *and* it would be able to
Then-ify. And we can likely simplify... other code... as we come across it.

+              api_owners.append(self._owners_fs.GetFromFile(owners_file).Get())
+            else:
+              api_owners.append(self._CreateAPIEntry(owners_file, None))
+      # Add an entry for the core extensions/apps owners.
+      owners_file = posixpath.join(BROWSER_CHROME_EXTENSIONS, _OWNERS)
+      entry = self._owners_fs.GetFromFile(owners_file).Get()

[not at google - send to devlin, 2014/08/15 15:45:51]

.Get() here as well.

+      entry['apiName'] = 'Core Extensions/Apps Owners'
+      api_owners.append(entry)
+      api_owners.sort(key=itemgetter('apiName'))
+      self._cache.Set('api_owners', api_owners)
+      return api_owners
+    return self._cache.Get('api_owners').Then(collect)
+
+  def get(self, key):
+    return {
+      'apis': self._CollectOwnersData()
+    }.get(key).Get()
+
+  def Cron(self):
+    return self._CollectOwnersData()