[Zope-Checkins] CVS: Zope3/lib/python/Interface - Document.py:1.1.2.2

[Jim Fulton]

Update of /cvs-repository/Zope3/lib/python/Interface
In directory cvs.zope.org:/tmp/cvs-serv29054

Modified Files:
      Tag: Zope-3x-branch
	Document.py 
Log Message:
- Added documentation to Document

- Cleaned up the interface.

- Made the output a bit nicer.

- Wrote a test.

:)



=== Zope3/lib/python/Interface/Document.py 1.1.2.1 => 1.1.2.2 ===
+##############################################################################
+#
+# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
+# All Rights Reserved.
+# 
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE
+# 
+##############################################################################
+""" Pretty-Print an Interface object as structured text (Yum)
+
+This module provides a function, asStructuredText, for rendering an
+interface as structured text.
+
+Revision information:
+$Id$
+"""
 
-""" Pretty-Print an Interface object as structured text (Yum) """
+from string import maketrans
 
+def asStructuredText(I, munge=0):
+    """ Output structured text format.  Note, this will wack any existing
+    'structured' format of the text.  """
+
+    
+    r = ["%s\n\n" % I.getName()]
+    outp = r.append
+    level = 1
+
+    if I.getDoc():
+        outp(_justify_and_indent(_trim_doc_string(I.getDoc()), level)+ "\n\n")
+
+    if I.getBases():
+        outp((" " * level) + "This interface extends:\n\n")
+        level = level + 1
+        for b in I.getBases():
+            item = "o %s" % b.getName()
+            outp(_justify_and_indent(_trim_doc_string(item), level, munge)
+                 + "\n\n")
+
+        level = level - 1
+
+    outp(_justify_and_indent("Attributes:", level, munge)+'\n\n')
+    level = level + 1
+    for name, desc in I.namesAndDescriptions():
+        if not hasattr(desc, 'getSignatureString'):   # ugh...
+            item = "%s -- %s" % (desc.getName(),
+                                 desc.getDoc() or 'no documentation')
+            outp(_justify_and_indent(_trim_doc_string(item), level, munge)
+                 + "\n\n")
+    level = level - 1
+
+    outp(_justify_and_indent("Methods:", level, munge)+'\n\n')
+    level = level + 1
+    for name, desc in I.namesAndDescriptions():
+        if hasattr(desc, 'getSignatureString'):   # ugh...
+            item = "%s%s -- %s" % (desc.getName(),
+                                   desc.getSignatureString(),
+                                   desc.getDoc() or 'no documentation')
+            outp(_justify_and_indent(_trim_doc_string(item), level, munge)
+                 + "\n\n")
+
+    return "".join(r)
 
-def trim_doc_string(text):
+def _trim_doc_string(text):
     """
     Trims a doc string to make it format
     correctly with structured text.
     """
-    text=string.strip(text)
-    text=string.replace(text, '\r\n', '\n')
-    lines=string.split(text, '\n')
-    nlines=[lines[0]]
+    text = text.strip().replace('\r\n', '\n')
+    lines = text.split('\n')
+    nlines = [lines[0]]
     if len(lines) > 1:
         min_indent=None
         for line in lines[1:]:
-            indent=len(line) - len(string.lstrip(line))
+            indent=len(line) - len(line.lstrip())
             if indent < min_indent or min_indent is None:
                 min_indent=indent   
         for line in lines[1:]:
             nlines.append(line[min_indent:])
-    return string.join(nlines, '\n')
+    return '\n'.join(nlines)
     
     
-    
-def justify_and_indent(text, level, munge=0, width=72):
+_trans = maketrans("\r\n", "  ")
+def _justify_and_indent(text, level, munge=0, width=72):
     """ indent and justify text, rejustify (munge) if specified """
 
     lines = []
 
     if munge:
         line = " " * level
-        text = string.split(
-                 string.strip(
-                   string.translate(text, string.maketrans("\r\n", "  "))))
+        text = text.translate(text, _trans).strip().split()
 
         for word in text:
-            line = string.join([line, word])
+            line = ' '.join([line, word])
             if len(line) > width:
                 lines.append(line)
                 line = " " * level
         else:
             lines.append(line)
 
-        return string.join(lines, "\n")
+        return "\n".join(lines)
 
     else:
-        text = string.split(string.replace(text,"\r\n", "\n"), "\n")
+        text = text.replace("\r\n", "\n").split("\n")
 
         for line in text:
             lines.append( (" " * level) + line)
 
-        return string.join(lines, "\n")
-            
-
-def interface_as_stx(I, munge=0):
-    """ Output structured text format.  Note, this will wack any existing
-    'structured' format of the text.  """
-
-    outp = "%s\n\n" % I.getName()
-    level = 1
-
-    if I.getDoc():
-        outp = ( outp
-               + justify_and_indent(trim_doc_string(I.getDoc()), level)
-               + "\n\n"
-               )
-
-    if I.getBases():
-        outp = outp + (" " * level) + "This interface extends:\n\n"
-        level = level + 1
-        for b in I.getBases():
-            item = "o %s" % b.getName()
-            outp = ( outp
-                   + justify_and_indent(trim_doc_string(item), level, munge)
-                   + "\n\n"
-                   )
-
-        level = level - 1
-
-    level = level + 1
-    for name, desc in I.namesAndDescriptions():
-        if hasattr(desc, 'getSignatureRepr'):   # ugh...
-            item = "%s%s -- %s" % (desc.getName(),
-                                   desc.getSignatureRepr(),
-                                   desc.getDoc())
-        else:
-            item = "%s -- %s" % (desc.getName(), desc.getDoc())
+        return '\n'.join(lines)
             
-        outp = ( outp
-               + justify_and_indent(trim_doc_string(item), level, munge)
-               + "\n\n"
-               )
-
-    return outp