Make parameter a namedtuple (#176)

Author: timhoffm

numpydoc/docscrape.py

@@ -106,6 +106,9 @@ def __str__(self):
         return message
 
 
+Parameter = collections.namedtuple('Parameter', ['name', 'type', 'desc'])
+
+
 class NumpyDocString(collections.Mapping):
     """Parses a numpydoc string to an abstract representation
 
@@ -225,7 +228,7 @@ def _parse_param_list(self, content):
             desc = dedent_lines(desc)
             desc = strip_blank_lines(desc)
 
-            params.append((arg_name, arg_type, desc))
+            params.append(Parameter(arg_name, arg_type, desc))
 
         return params
 
@@ -409,13 +412,13 @@ def _str_param_list(self, name):
         out = []
         if self[name]:
             out += self._str_header(name)
-            for param, param_type, desc in self[name]:
-                if param_type:
-                    out += ['%s : %s' % (param, param_type)]
+            for param in self[name]:
+                if param.type:
+                    out += ['%s : %s' % (param.name, param.type)]
                 else:
-                    out += [param]
-                if desc and ''.join(desc).strip():
-                    out += self._str_indent(desc)
+                    out += [param.name]
+                if param.desc and ''.join(param.desc).strip():
+                    out += self._str_indent(param.desc)
             out += ['']
         return out
 
@@ -591,7 +594,8 @@ def splitlines_x(s):
                     for name in sorted(items):
                         try:
                             doc_item = pydoc.getdoc(getattr(self._cls, name))
-                            doc_list.append((name, '', splitlines_x(doc_item)))
+                            doc_list.append(
+                                Parameter(name, '', splitlines_x(doc_item)))
                         except AttributeError:
                             pass  # method doesn't exist
                     self[field] = doc_list

numpydoc/docscrape_sphinx.py

@@ -74,17 +74,18 @@ def _str_returns(self, name='Returns'):
         if self[name]:
             out += self._str_field_list(name)
             out += ['']
-            for param, param_type, desc in self[name]:
-                if param_type:
-                    out += self._str_indent([typed_fmt % (param.strip(),
-                                                          param_type)])
+            for param in self[name]:
+                if param.type:
+                    out += self._str_indent([typed_fmt % (param.name.strip(),
+                                                          param.type)])
                 else:
-                    out += self._str_indent([untyped_fmt % param.strip()])
-                if desc and self.use_blockquotes:
-                    out += ['']
-                elif not desc:
-                    desc = ['..']
-                out += self._str_indent(desc, 8)
+                    out += self._str_indent([untyped_fmt % param.name.strip()])
+                if not param.desc:
+                    out += self._str_indent(['..'], 8)
+                else:
+                    if self.use_blockquotes:
+                        out += ['']
+                    out += self._str_indent(param.desc, 8)
                 out += ['']
         return out
 
@@ -200,13 +201,14 @@ def _str_param_list(self, name, fake_autosummary=False):
         if self[name]:
             out += self._str_field_list(name)
             out += ['']
-            for param, param_type, desc in self[name]:
-                display_param, desc = self._process_param(param, desc,
+            for param in self[name]:
+                display_param, desc = self._process_param(param.name,
+                                                          param.desc,
                                                           fake_autosummary)
 
-                if param_type:
+                if param.type:
                     out += self._str_indent(['%s : %s' % (display_param,
-                                                          param_type)])
+                                                          param.type)])
                 else:
                     out += self._str_indent([display_param])
                 if desc and self.use_blockquotes:
@@ -243,21 +245,21 @@ def _str_member_list(self, name):
 
             autosum = []
             others = []
-            for param, param_type, desc in self[name]:
-                param = param.strip()
+            for param in self[name]:
+                param = param._replace(name=param.name.strip())
 
                 # Check if the referenced member can have a docstring or not
-                param_obj = getattr(self._obj, param, None)
+                param_obj = getattr(self._obj, param.name, None)
                 if not (callable(param_obj)
                         or isinstance(param_obj, property)
                         or inspect.isdatadescriptor(param_obj)):
                     param_obj = None
 
                 if param_obj and pydoc.getdoc(param_obj):
                     # Referenced object has a docstring
-                    autosum += ["   %s%s" % (prefix, param)]
+                    autosum += ["   %s%s" % (prefix, param.name)]
                 else:
-                    others.append((param, param_type, desc))
+                    others.append(param)
 
             if autosum:
                 out += ['.. autosummary::']
@@ -266,15 +268,17 @@ def _str_member_list(self, name):
                 out += [''] + autosum
 
             if others:
-                maxlen_0 = max(3, max([len(x[0]) + 4 for x in others]))
+                maxlen_0 = max(3, max([len(p.name) + 4 for p in others]))
                 hdr = sixu("=") * maxlen_0 + sixu("  ") + sixu("=") * 10
                 fmt = sixu('%%%ds  %%s  ') % (maxlen_0,)
                 out += ['', '', hdr]
-                for param, param_type, desc in others:
-                    desc = sixu(" ").join(x.strip() for x in desc).strip()
-                    if param_type:
-                        desc = "(%s) %s" % (param_type, desc)
-                    out += [fmt % ("**" + param.strip() + "**", desc)]
+                for param in others:
+                    name = "**" + param.name.strip() + "**"
+                    desc = sixu(" ").join(x.strip()
+                                          for x in param.desc).strip()
+                    if param.type:
+                        desc = "(%s) %s" % (param.type, desc)
+                    out += [fmt % (name, desc)]
                 out += [hdr]
             out += ['']
         return out