[Scipy-svn] r5262 - in trunk/scipy/ndimage: . tests

[scipy-svn at scipy.org]

Author: matthew.brett at gmail.com
Date: 2008-12-14 22:45:00 -0600 (Sun, 14 Dec 2008)
New Revision: 5262

Modified:
   trunk/scipy/ndimage/doccer.py
   trunk/scipy/ndimage/tests/test_doccer.py
   trunk/scipy/ndimage/tests/test_filters.py
Log:
Better support for more arbitrary indentation in parameter strings, with tests

Modified: trunk/scipy/ndimage/doccer.py
===================================================================
--- trunk/scipy/ndimage/doccer.py	2008-12-14 22:42:33 UTC (rev 5261)
+++ trunk/scipy/ndimage/doccer.py	2008-12-15 04:45:00 UTC (rev 5262)
@@ -29,14 +29,15 @@
         return docstring
     if docdict is None:
         docdict = {}
+    if not docdict:
+        return docstring
     lines = docstring.expandtabs().splitlines()
-    # Find the minimum indent of the main docstring, after last line
-    indentno = sys.maxint
-    for line in lines[1:]:
-        stripped = line.lstrip()
-        if stripped:
-            indentno = min(indentno, len(line) - len(stripped))
-    indent = ' ' * indentno
+    # Find the minimum indent of the main docstring, after first line
+    if len(lines) < 2:
+        icount = 0
+    else:
+        icount = indentcount_lines(lines[1:])
+    indent = ' ' * icount
     # Insert this indent to dictionary docstrings
     indented = {}
     for name, dstr in docdict.items():
@@ -48,21 +49,54 @@
     return docstring % indented
 
 
-def filldoc(docdict):
+def indentcount_lines(lines):
+    ''' Minumum indent for all lines in line list '''
+    indentno = sys.maxint
+    for line in lines:
+        stripped = line.lstrip()
+        if stripped:
+            indentno = min(indentno, len(line) - len(stripped))
+    if indentno == sys.maxint:
+        return 0
+    return indentno
+
+
+def filldoc(docdict, unindent_params=True):
     ''' Return docstring decorator using docdict variable dictionary
 
     Parameters
     ----------
     docdict : dictionary
         dictionary containing name, docstring fragment pairs
-
+    unindent_params : {False, True}, boolean, optional
+        If True, strip common indentation from all parameters in
+        docdict
+    
     Returns
     -------
     decfunc : function
         decorator that applies dictionary to input function docstring
     '''
+    if unindent_params:
+        docdict = unindent_dict(docdict)
     def decorate(f):
         f.__doc__ = docformat(f.__doc__, docdict)
         return f
     return decorate
 
+
+def unindent_dict(docdict):
+    ''' Unindent all strings in a docdict '''
+    can_dict = {}
+    for name, dstr in docdict.items():
+        can_dict[name] = unindent_string(dstr)
+    return can_dict
+
+
+def unindent_string(docstring):
+    ''' Set docstring to minimum indent for all lines, including first '''
+    lines = docstring.expandtabs().splitlines()
+    icount = indentcount_lines(lines)
+    if icount == 0:
+        return docstring
+    return '\n'.join([line[icount:] for line in lines])

Modified: trunk/scipy/ndimage/tests/test_doccer.py
===================================================================
--- trunk/scipy/ndimage/tests/test_doccer.py	2008-12-14 22:42:33 UTC (rev 5261)
+++ trunk/scipy/ndimage/tests/test_doccer.py	2008-12-15 04:45:00 UTC (rev 5262)
@@ -1,4 +1,4 @@
-''' Some tests for the documenting decorator '''
+''' Some tests for the documenting decorator and support functions '''
 
 import numpy as np
 
@@ -6,20 +6,84 @@
 
 from nose.tools import assert_true
 
-from scipy.ndimage.doccer import docformat, filldoc
+import scipy.ndimage.doccer as sndd
 
-def test_docformat():
-    docstring = \
-    """Docstring
-    %(strtest)s
-    """
-    param_doc = \
+docstring = \
+"""Docstring
+    %(strtest1)s
+        %(strtest2)s
+     %(strtest3)s
+"""
+param_doc1 = \
 """Another test
    with some indent"""
-    formatted = docformat(docstring, {'strtest':param_doc})
-    expected = \
+
+param_doc2 = \
+"""Another test, one line"""
+
+param_doc3 = \
+"""    Another test
+       with some indent"""
+
+doc_dict = {'strtest1':param_doc1,
+            'strtest2':param_doc2,
+            'strtest3':param_doc3}
+
+filled_docstring = \
 """Docstring
     Another test
        with some indent
-    """
-    assert_equal(formatted, expected)
+        Another test, one line
+     Another test
+       with some indent
+"""
+
+
+def test_unindent():
+    yield assert_equal, sndd.unindent_string(param_doc1), param_doc1
+    yield assert_equal, sndd.unindent_string(param_doc2), param_doc2
+    yield assert_equal, sndd.unindent_string(param_doc3), param_doc1
+
+
+def test_unindent_dict():
+    d2 = sndd.unindent_dict(doc_dict)
+    yield assert_equal, d2['strtest1'], doc_dict['strtest1']
+    yield assert_equal, d2['strtest2'], doc_dict['strtest2']
+    yield assert_equal, d2['strtest3'], doc_dict['strtest1']
+
+
+def test_docformat():
+    udd = sndd.unindent_dict(doc_dict)
+    formatted = sndd.docformat(docstring, udd)
+    yield assert_equal, formatted, filled_docstring
+    single_doc = 'Single line doc %(strtest1)s'
+    formatted = sndd.docformat(single_doc, doc_dict)
+    # Note - initial indent of format string does not
+    # affect subsequent indent of inserted parameter
+    yield assert_equal, formatted, """Single line doc Another test
+   with some indent"""
+    
+
+def test_decorator():
+    # with unindentation of parameters
+    decorator = sndd.filldoc(doc_dict, True)
+    @decorator
+    def func():
+        """ Docstring
+        %(strtest3)s
+        """
+    yield assert_equal, func.__doc__, """ Docstring
+        Another test
+           with some indent
+        """
+    # without unindentation of parameters
+    decorator = sndd.filldoc(doc_dict, False)
+    @decorator
+    def func():
+        """ Docstring
+        %(strtest3)s
+        """
+    yield assert_equal, func.__doc__, """ Docstring
+            Another test
+               with some indent
+        """

Modified: trunk/scipy/ndimage/tests/test_filters.py
===================================================================
--- trunk/scipy/ndimage/tests/test_filters.py	2008-12-14 22:42:33 UTC (rev 5261)
+++ trunk/scipy/ndimage/tests/test_filters.py	2008-12-15 04:45:00 UTC (rev 5262)
@@ -8,6 +8,7 @@
 
 import scipy.ndimage as sndi
 
+
 def test_ticket_701():
     # Test generic filter sizes
     arr = np.arange(4).reshape((2,2))
@@ -17,6 +18,7 @@
     res2 = sndi.generic_filter(arr, func, size=1)
     assert_equal(res, res2)
 
+
 def test_orders_gauss():
     # Check order inputs to Gaussians
     arr = np.zeros((1,))