[Checkins] SVN: zc.buildout/branches/help-api/src/zc/buildout/ added a 'describe' command that displays an egg docstring

[Tarek Ziade]

Log message for revision 83112:
  added a 'describe' command that displays an egg docstring

Changed:
  U   zc.buildout/branches/help-api/src/zc/buildout/buildout.py
  U   zc.buildout/branches/help-api/src/zc/buildout/tests.py

-=-
Modified: zc.buildout/branches/help-api/src/zc/buildout/buildout.py
===================================================================
--- zc.buildout/branches/help-api/src/zc/buildout/buildout.py	2008-01-23 15:38:10 UTC (rev 83111)
+++ zc.buildout/branches/help-api/src/zc/buildout/buildout.py	2008-01-23 15:46:46 UTC (rev 83112)
@@ -801,7 +801,30 @@
     def __iter__(self):
         return iter(self._raw)
 
+    def describe(self, recipes):
+        for recipe_spec in recipes:
+            recipe_class = self._get_recipe_class(recipe_spec)
+            if recipe_class is not None:
+                self._describe_recipe(recipe_spec, recipe_class)
 
+    def _get_recipe_class(self, name):
+        # XXX no version specified yet
+        try:
+            reqs, entry = _recipe({'recipe': name})
+            return  _install_and_load(reqs, 'zc.buildout', entry, self)
+        except pkg_resources.DistributionNotFound:
+            return None
+
+    def _describe_recipe(self, name, recipe_class):
+        docstring = recipe_class.__doc__
+        if docstring is not None:
+            print name
+            for line in docstring.splitlines():
+                print '    %s' % line
+        else:
+            print name
+            print '    Help not available'
+
 def _install_and_load(spec, group, entry, buildout):
     __doing__ = 'Loading recipe %r.', spec
     try:
@@ -1369,7 +1392,7 @@
     if args:
         command = args.pop(0)
         if command not in (
-            'install', 'bootstrap', 'runsetup', 'setup', 'init',
+            'install', 'bootstrap', 'runsetup', 'setup', 'init', 'describe'
             ):
             _error('invalid command:', command)
     else:

Modified: zc.buildout/branches/help-api/src/zc/buildout/tests.py
===================================================================
--- zc.buildout/branches/help-api/src/zc/buildout/tests.py	2008-01-23 15:38:10 UTC (rev 83111)
+++ zc.buildout/branches/help-api/src/zc/buildout/tests.py	2008-01-23 15:46:46 UTC (rev 83112)
@@ -633,6 +633,137 @@
     ...
     """
 
+def test_describe():
+    """
+    If help is followed by recipe names, it shows the 
+    recipe's class docstring.
+   
+    >>> mkdir(sample_buildout, 'my.recipes')
+    >>> write(sample_buildout, 'my.recipes', 'recipe.py', 
+    ... '''
+    ... class MyRecipe:
+    ...     def __init__(self, buildout, name, options):
+    ...         pass
+    ...
+    ...     def install(self):
+    ...         return tuple()
+    ...
+    ...     update = install
+    ... ''')
+
+
+    >>> write(sample_buildout, 'my.recipes', 'setup.py',
+    ... '''
+    ... from setuptools import setup
+    ... setup(
+    ...     name = "my.recipes",
+    ...     entry_points = {'zc.buildout': 
+    ...                      ['default = recipe:MyRecipe']},
+    ...     )
+    ... ''')
+
+    >>> write(sample_buildout, 'my.recipes', 'README.txt', " ")
+
+    >>> write(sample_buildout, 'buildout.cfg',
+    ... '''
+    ... [buildout]
+    ... develop = my.recipes
+    ... parts = my-recipe
+    ... [my-recipe]
+    ... recipe = my.recipes
+    ... ''')
+
+    >>> buildout = os.path.join(sample_buildout, 'bin', 'buildout')
+
+    >>> print system(buildout),
+    Develop: '/sample-buildout/my.recipes'
+    Installing my-recipe.
+
+    >>> print system('%s describe my.recipes' % buildout) 
+    my.recipes
+        Help not available
+    <BLANKLINE>
+
+    Let's add a docstring now:
+
+    >>> write(sample_buildout, 'my.recipes', 'recipe.py', 
+    ... '''
+    ... class MyRecipe:
+    ...     "The coolest recipe on Earth."
+    ...     def __init__(self, buildout, name, options):
+    ...         pass
+    ...
+    ...     def install(self):
+    ...         return tuple()
+    ...
+    ...     update = install
+    ... ''')
+
+    >>> print system('%s describe my.recipes' % buildout) 
+    my.recipes
+        The coolest recipe on Earth.
+    <BLANKLINE>
+
+    Let's add a second recipe in the egg:
+
+    >>> write(sample_buildout, 'my.recipes', 'setup.py',
+    ... '''
+    ... from setuptools import setup
+    ... setup(
+    ...     name = "my.recipes",
+    ...     entry_points = {'zc.buildout': 
+    ...                      ['default = recipe:MyRecipe',
+    ...                       'second = second:OtherRecipe']},
+    ...     )
+    ... ''')
+
+
+    >>> write(sample_buildout, 'my.recipes', 'second.py', 
+    ... '''
+    ... class OtherRecipe:
+    ...     def __init__(self, buildout, name, options):
+    ...         pass
+    ...
+    ...     def install(self):
+    ...         return tuple()
+    ...
+    ...     update = install
+    ... ''')
+
+    Let's test that the second recipe is installable:
+
+    >>> write(sample_buildout, 'buildout.cfg',
+    ... '''
+    ... [buildout]
+    ... develop = my.recipes
+    ... parts = my-recipe
+    ... [my-recipe]
+    ... recipe = my.recipes:second
+    ... ''')
+
+    We have to run the buildout again, because the recipe
+    here is a develop, to be able to test the egg itself:
+
+    >>> print system(buildout) 
+    Develop: '/sample-buildout/my.recipes'
+    Uninstalling my-recipe.
+    Installing my-recipe.
+    <BLANKLINE>
+
+    >>> print system('%s describe my.recipes' % buildout) 
+    my.recipes
+        The coolest recipe on Earth.
+    <BLANKLINE>
+
+    >>> print system('%s describe my.recipes:second' % buildout) 
+    my.recipes:second
+        Help not available
+    <BLANKLINE>
+
+
+
+    """
+
 def test_bootstrap_with_extension():
     """
 We had a problem running a bootstrap with an extension.  Let's make