Move actual library code into use_desc_gen.py and make use_desc_gen the drive. This enables us to import and test functions out of use_desc_gen.py

2 files changed, 185 insertions, 148 deletions

diff --git a/users/antarus/projects/infra/use_desc_gen b/users/antarus/projects/infra/use_desc_gen
index b7fe1eb081..2ee39f6a38 100644
--- a/users/antarus/projects/infra/use_desc_gen
+++ b/users/antarus/projects/infra/use_desc_gen
@@ -1,155 +1,12 @@
 #!/usr/bin/env python
-# Written by Alec Warner for the Gentoo Foundation 2008
-# This code is hereby placed into the public domain.
+# Written by Alec Warner <antarus@gentoo.org>
+# This code is hereby placed in the public domain.
 
-"""Craws an ebuild repository for local use flags and generates documentation.
+"""A simple driver file for use_desc_gen."""
 
-This module attempts to read metadata.xml files in an ebuild repository and
-uses the <flag> xml tags to generate a set of documentation for local USE
-flags.
-
-It is a non-goal of this script to validate XML contents.
-
-CAVEATS:
-TEXT, <pkg>, <pkg>, TEXT. is difficult to parse into text and requires icky
-rules; see _GetTextFromNode for the nasty details.
-
-TODO(antarus): Some XML entries have weird blobs of whitespace that strip() does
-not want to remove.
-"""
-
-__author__ = "Alec Warner <antarus@gentoo.org>"
-
-import logging
 import optparse
-import os
-import sys
-
-from xml.dom import minidom
-
-METADATA_XML = 'metadata.xml'
-
-
-class RepositoryError(Exception):
-  """Basic Exception for repository problems."""
-  pass
-
-
-def FindMetadataFiles(repo_path, category_path, output=sys.stdout):
-  """Locate metadata files in repo_path.
-  
-  Args:
-    repo_path: path to repository.
-    category_path: path to a category file (None is ok).
-    output: file-like object to write output to.
-  Returns:
-    Nothing.
-  Raises; RepositoryError.
-  """
-
-  profile_path = os.path.join(repo_path, 'profiles')
-  logging.info('path to profile is: %s' % profile_path)
-  categories = GetCategories(profile_path, category_path)
-  packages = []
-  for cat in categories:
-    cat_path = os.path.join(repo_path, cat)
-    logging.debug('path to category %s is %s' % (cat, cat_path))
-    tmp_pkgs = GetPackages(cat_path)
-    pkg_paths = [os.path.join(cat_path, pkg) for pkg in tmp_pkgs]
-    packages.extend(pkg_paths)
-
-  total = len(packages)
-  for num, pkg_path in enumerate(packages):
-    metadata_path = os.path.join(pkg_path, METADATA_XML)
-    logging.info('processing %s (%s/%s)' % (metadata_path, num, total))
-    f = open(metadata_path, 'rb')
-    metadata = GetLocalFlagInfoFromMetadataXml(f)
-    pkg_split = pkg_path.split('/')
-    for k, v in metadata.iteritems():
-      output.write('%s/%s:%s - %s\n' % (pkg_split[-2] ,pkg_split[-1], k, v))
-
-
-def _GetTextFromNode(node):
-  """Given an XML node, try to turn all it's children into text.
-
-  Args:
-    node: a Node instance.
-  Returns:
-    some text.
+import use_desc_gen
 
-  This function has a few tweaks 'children' and 'base_children' which attempt
-  to aid the parser in determining where to insert spaces.  Nodes that have
-  no children are 'raw text' nodes that do not need spaces.  Nodes that have
-  children are 'complex' nodes (often <pkg> nodes) that usually require a
-  trailing space to ensure sane output.
-  """
-
-  if node.nodeValue:
-    children = 0
-    return (node.nodeValue.strip(), children)
-  else:
-    desc = ''
-    base_children = 1
-    for child in node.childNodes:
-      child_desc, children = _GetTextFromNode(child)
-      child_desc.strip()
-      logging.error('Children: %s' % children)
-      if children:
-        desc += ' ' + child_desc
-      else:
-        desc += child_desc
-    return (desc, base_children)
-
-
-def GetLocalFlagInfoFromMetadataXml(metadata_file):
-  """Determine use.local.desc information from metadata files.
-  
-  Args:
-    metadata_file: a file-like object holding metadata.xml
-  """
-
-  d = {}
-
-  dom_tree = minidom.parseString(metadata_file.read())
-  flag_tags = dom_tree.getElementsByTagName('flag')
-  for flag in flag_tags:
-    use_flag = flag.getAttribute('name')
-    desc, unused_children = _GetTextFromNode(flag)
-    desc.strip()
-    d[use_flag] = desc
-
-  return d
-
-
-def GetPackages(cat_path):
-  """Return a list of packages for a given category."""
-
-  files = os.listdir(cat_path)
-  if METADATA_XML in files:
-    files.remove(METADATA_XML)
-
-  return files
-
-def GetCategories(profile_path, categories_path):
-  """Return a set of categories for a given repository.
-
-  Args:
-    profile_path: path to profiles/ dir of a repository.
-  Returns:
-    a list of categories.
-  Raises: RepositoryError.
-  """
-
-  if not categories_path:
-    categories_path = os.path.join(profile_path, 'categories')
-  try:
-    f = open(categories_path, 'rb')
-  except (IOError, OSError), e:
-    raise RepositoryError('Problem while opening %s: %s' % (
-        categories_path, e))
-  categories = [cat.strip() for cat in f.readlines()]
-  return categories
-  
 
 def GetOpts():
   """Simple Option Parsing."""
@@ -169,10 +26,12 @@ def GetOpts():
 
   return (opts, unused_args)
 
+
 def Main():
   """Main."""
   opts, unused_args = GetOpts()
-  FindMetadataFiles(opts.repo_path, opts.category_path)
+  use_desc_gen.FindMetadataFiles(opts.repo_path, opts.category_path)
+
 
 if __name__ == '__main__':
   Main()
diff --git a/users/antarus/projects/infra/use_desc_gen.py b/users/antarus/projects/infra/use_desc_gen.py
new file mode 100644
index 0000000000..b7fe1eb081
--- /dev/null
+++ b/users/antarus/projects/infra/use_desc_gen.py
@@ -0,0 +1,178 @@
+#!/usr/bin/env python
+# Written by Alec Warner for the Gentoo Foundation 2008
+# This code is hereby placed into the public domain.
+
+"""Craws an ebuild repository for local use flags and generates documentation.
+
+This module attempts to read metadata.xml files in an ebuild repository and
+uses the <flag> xml tags to generate a set of documentation for local USE
+flags.
+
+It is a non-goal of this script to validate XML contents.
+
+CAVEATS:
+TEXT, <pkg>, <pkg>, TEXT. is difficult to parse into text and requires icky
+rules; see _GetTextFromNode for the nasty details.
+
+TODO(antarus): Some XML entries have weird blobs of whitespace that strip() does
+not want to remove.
+"""
+
+__author__ = "Alec Warner <antarus@gentoo.org>"
+
+import logging
+import optparse
+import os
+import sys
+
+from xml.dom import minidom
+
+METADATA_XML = 'metadata.xml'
+
+
+class RepositoryError(Exception):
+  """Basic Exception for repository problems."""
+  pass
+
+
+def FindMetadataFiles(repo_path, category_path, output=sys.stdout):
+  """Locate metadata files in repo_path.
+  
+  Args:
+    repo_path: path to repository.
+    category_path: path to a category file (None is ok).
+    output: file-like object to write output to.
+  Returns:
+    Nothing.
+  Raises; RepositoryError.
+  """
+
+  profile_path = os.path.join(repo_path, 'profiles')
+  logging.info('path to profile is: %s' % profile_path)
+  categories = GetCategories(profile_path, category_path)
+  packages = []
+  for cat in categories:
+    cat_path = os.path.join(repo_path, cat)
+    logging.debug('path to category %s is %s' % (cat, cat_path))
+    tmp_pkgs = GetPackages(cat_path)
+    pkg_paths = [os.path.join(cat_path, pkg) for pkg in tmp_pkgs]
+    packages.extend(pkg_paths)
+
+  total = len(packages)
+  for num, pkg_path in enumerate(packages):
+    metadata_path = os.path.join(pkg_path, METADATA_XML)
+    logging.info('processing %s (%s/%s)' % (metadata_path, num, total))
+    f = open(metadata_path, 'rb')
+    metadata = GetLocalFlagInfoFromMetadataXml(f)
+    pkg_split = pkg_path.split('/')
+    for k, v in metadata.iteritems():
+      output.write('%s/%s:%s - %s\n' % (pkg_split[-2] ,pkg_split[-1], k, v))
+
+
+def _GetTextFromNode(node):
+  """Given an XML node, try to turn all it's children into text.
+
+  Args:
+    node: a Node instance.
+  Returns:
+    some text.
+
+  This function has a few tweaks 'children' and 'base_children' which attempt
+  to aid the parser in determining where to insert spaces.  Nodes that have
+  no children are 'raw text' nodes that do not need spaces.  Nodes that have
+  children are 'complex' nodes (often <pkg> nodes) that usually require a
+  trailing space to ensure sane output.
+  """
+
+  if node.nodeValue:
+    children = 0
+    return (node.nodeValue.strip(), children)
+  else:
+    desc = ''
+    base_children = 1
+    for child in node.childNodes:
+      child_desc, children = _GetTextFromNode(child)
+      child_desc.strip()
+      logging.error('Children: %s' % children)
+      if children:
+        desc += ' ' + child_desc
+      else:
+        desc += child_desc
+    return (desc, base_children)
+
+
+def GetLocalFlagInfoFromMetadataXml(metadata_file):
+  """Determine use.local.desc information from metadata files.
+  
+  Args:
+    metadata_file: a file-like object holding metadata.xml
+  """
+
+  d = {}
+
+  dom_tree = minidom.parseString(metadata_file.read())
+  flag_tags = dom_tree.getElementsByTagName('flag')
+  for flag in flag_tags:
+    use_flag = flag.getAttribute('name')
+    desc, unused_children = _GetTextFromNode(flag)
+    desc.strip()
+    d[use_flag] = desc
+
+  return d
+
+
+def GetPackages(cat_path):
+  """Return a list of packages for a given category."""
+
+  files = os.listdir(cat_path)
+  if METADATA_XML in files:
+    files.remove(METADATA_XML)
+
+  return files
+
+def GetCategories(profile_path, categories_path):
+  """Return a set of categories for a given repository.
+
+  Args:
+    profile_path: path to profiles/ dir of a repository.
+  Returns:
+    a list of categories.
+  Raises: RepositoryError.
+  """
+
+  if not categories_path:
+    categories_path = os.path.join(profile_path, 'categories')
+  try:
+    f = open(categories_path, 'rb')
+  except (IOError, OSError), e:
+    raise RepositoryError('Problem while opening %s: %s' % (
+        categories_path, e))
+  categories = [cat.strip() for cat in f.readlines()]
+  return categories
+  
+
+def GetOpts():
+  """Simple Option Parsing."""
+
+  parser = optparse.OptionParser()
+  parser.add_option('-r', '--repo_path', help=('path to repository from '
+                    'which the documentation will be generated.'))
+  parser.add_option('-c', '--category_path', help=('path to a category',
+                    'file if repo_path lacks a profile/category file'))
+
+  opts, unused_args = parser.parse_args()
+
+  if not opts.repo_path:
+    parser.error('--repo_path is a required option')
+
+  logging.error('REPO_PATH is %s' % opts.repo_path)
+
+  return (opts, unused_args)
+
+def Main():
+  """Main."""
+  opts, unused_args = GetOpts()
+  FindMetadataFiles(opts.repo_path, opts.category_path)
+
+if __name__ == '__main__':
+  Main()