Source Code for Module epydoc.test.util

  1  # 
  2  # epydoc -- Utility functions used by regression tests (*.doctest) 
  3  # Edward Loper 
  4  # 
  5  # Created [01/30/01 05:18 PM] 
  6  # $Id: html.py 1420 2007-01-28 14:19:30Z dvarrazzo $ 
  7  # 
  8   
  9  """ 
 10  Utility functions used by the regression tests (C{*.doctest}). 
 11  """ 
 12  __docformat__ = 'epytext en' 
 13   
 14  import tempfile, re, os, os.path, textwrap, sys 
 15  from epydoc.docbuilder import build_doc, build_doc_index 
 16  from epydoc.docparser import parse_docs 
 17  from epydoc.docintrospecter import introspect_docs 
 18  from epydoc.apidoc import ClassDoc, RoutineDoc 
 19  from epydoc.markup import ParsedDocstring 
 20  from epydoc.docwriter.html import HTMLWriter 
 21   
 22  ###################################################################### 
 23  #{ Test Functions 
 24  ###################################################################### 
 25   
 26 -def buildvaluedoc(s): 
 27      """ 
 28      This test function takes a string containing the contents of a 
 29      module.  It writes the string contents to a file, imports the file 
 30      as a module, and uses build_doc to build documentation, and 
 31      returns it as a C{ValueDoc} object. 
 32      """ 
 33      tmp_dir = write_pystring_to_tmp_dir(s) 
 34      val_doc = build_doc(os.path.join(tmp_dir, 'epydoc_test.py')) 
 35      cleanup_tmp_dir(tmp_dir) 
 36      return val_doc 
 37   
 38 -def runbuilder(s, attribs='', build=None, exclude=''): 
 39      """ 
 40      This test function takes a string containing the contents of a 
 41      module.  It writes the string contents to a file, imports the file 
 42      as a module, and uses build_doc to build documentation, and pretty 
 43      prints the resulting ModuleDoc object.  The C{attribs} argument 
 44      specifies which attributes of the C{APIDoc}s should be displayed. 
 45      The C{build} argument gives the name of a variable in the module 
 46      whose documentation should be built, instead of bilding docs for 
 47      the whole module. 
 48      """ 
 49      # Write it to a temp file. 
 50      tmp_dir = write_pystring_to_tmp_dir(s) 
 51      # Build it. 
 52      val_doc = build_doc(os.path.join(tmp_dir, 'epydoc_test.py')) 
 53      if build: val_doc = val_doc.variables[build].value 
 54      # Display it. 
 55      if isinstance(val_doc, ClassDoc): 
 56          for val in val_doc.variables.values(): 
 57              if isinstance(val.value, RoutineDoc): 
 58                  fun_to_plain(val.value) 
 59      s = val_doc.pp(include=attribs.split(),exclude=exclude.split()) 
 60      s = re.sub(r"(filename = ).*", r"\1...", s) 
 61      s = re.sub(r"(<module 'epydoc_test' from ).*", r'\1...', s) 
 62      s = re.sub(r"(<function \w+ at )0x\w+>", r"\1...>", s) 
 63      s = re.sub(r"(<\w+ object at )0x\w+>", r"\1...>", s) 
 64      print s 
 65      # Clean up. 
 66      cleanup_tmp_dir(tmp_dir) 
 67   
 68 -def runparser(s, attribs='', show=None, exclude=''): 
 69      """ 
 70      This test function takes a string containing the contents of a 
 71      module, and writes it to a file, uses `parse_docs` to parse it, 
 72      and pretty prints the resulting ModuleDoc object.  The `attribs` 
 73      argument specifies which attributes of the `APIDoc`s should be 
 74      displayed.  The `show` argument, if specifies, gives the name of 
 75      the object in the module that should be displayed (but the whole 
 76      module will always be inspected; this just selects what to 
 77      display). 
 78      """ 
 79      # Write it to a temp file. 
 80      tmp_dir = write_pystring_to_tmp_dir(s) 
 81      # Parse it. 
 82      val_doc = parse_docs(os.path.join(tmp_dir, 'epydoc_test.py')) 
 83      if show is not None: 
 84          for name in show.split('.'): 
 85              if isinstance(val_doc, ClassDoc): 
 86                  val_doc = val_doc.local_variables[name].value 
 87              else: 
 88                  val_doc = val_doc.variables[name].value 
 89      # Display it. 
 90      s = val_doc.pp(include=attribs.split(), exclude=exclude.split()) 
 91      s = re.sub(r"filename = .*", "filename = ...", s) 
 92      print s 
 93      # Clean up. 
 94      cleanup_tmp_dir(tmp_dir) 
 95   
 96 -def runintrospecter(s, attribs='', introspect=None, exclude=''): 
 97      """ 
 98      This test function takes a string containing the contents of a 
 99      module.  It writes the string contents to a file, imports the file 
100      as a module, and uses C{introspect_docs} to introspect it, and 
101      pretty prints the resulting ModuleDoc object.  The C{attribs} 
102      argument specifies which attributes of the C{APIDoc}s should be 
103      displayed.  The C{introspect} argument gives the name of a variable 
104      in the module whose value should be introspected, instead of 
105      introspecting the whole module. 
106      """ 
107      # Write it to a temp file. 
108      tmp_dir = write_pystring_to_tmp_dir(s) 
109      # Import it. 
110      sys.path.insert(0, tmp_dir) 
111      if introspect is None: 
112          import epydoc_test as val 
113      else: 
114          exec("from epydoc_test import %s as val" % introspect) 
115      del sys.path[0] 
116      # Introspect it. 
117      val_doc = introspect_docs(val) 
118      # Display it. 
119      s = val_doc.pp(include=attribs.split(),exclude=exclude.split()) 
120      s = re.sub(r"(filename = ).*", r"\1...", s) 
121      s = re.sub(r"(<module 'epydoc_test' from ).*", r'\1...', s) 
122      s = re.sub(r"(<function \w+ at )0x\w+>", r"\1...>", s) 
123      s = re.sub(r"(<\w+ object at )0x\w+>", r"\1...>", s) 
124      print s 
125      # Clean up. 
126      cleanup_tmp_dir(tmp_dir) 
127   
128 -def print_warnings(): 
129      """ 
130      Register a logger that will print warnings & errors. 
131      """ 
132      from epydoc import log 
133      del log._loggers[:] 
134      log.register_logger(log.SimpleLogger(log.DOCSTRING_WARNING)) 
135   
136 -def testencoding(s, introspect=True, parse=True, debug=False): 
137      """ 
138      An end-to-end test for unicode encodings.  This function takes a 
139      given string, writes it to a python file, and processes that 
140      file's documentation.  It then generates HTML output from the 
141      documentation, extracts all docstrings from the generated HTML 
142      output, and displays them.  (In order to extract & display all 
143      docstrings, it monkey-patches the HMTLwriter.docstring_to_html() 
144      method.)""" 
145      # Monkey-patch docstring_to_html 
146      original_docstring_to_html = HTMLWriter.docstring_to_html 
147      HTMLWriter.docstring_to_html = print_docstring_as_html 
148       
149      # Write s to a temporary file. 
150      tmp_dir = tempfile.mkdtemp() 
151      path = os.path.join(tmp_dir, 'enc_test.py') 
152      out = open(path, 'w') 
153      out.write(textwrap.dedent(s)) 
154      out.close() 
155      # Build docs for it 
156      docindex = build_doc_index([path], introspect, parse) 
157      if docindex is None: return 
158      sys.modules.pop('enc_test', None) 
159      # Write html output. 
160      writer = HTMLWriter(docindex, mark_docstrings=True) 
161      writer.write(tmp_dir) 
162      for file in os.listdir(tmp_dir): 
163          os.unlink(os.path.join(tmp_dir,file)) 
164      os.rmdir(tmp_dir) 
165   
166      # Restore the HTMLWriter class to its original state. 
167      HTMLWriter.docstring_to_html = original_docstring_to_html 
168   
169  ###################################################################### 
170  #{ Helper Functions 
171  ###################################################################### 
172   
173 -def write_pystring_to_tmp_dir(s): 
174      tmp_dir = tempfile.mkdtemp() 
175      out = open(os.path.join(tmp_dir, 'epydoc_test.py'), 'w') 
176      out.write(textwrap.dedent(s)) 
177      out.close() 
178      return tmp_dir 
179   
180 -def cleanup_tmp_dir(tmp_dir): 
181      os.unlink(os.path.join(tmp_dir, 'epydoc_test.py')) 
182      try: os.unlink(os.path.join(tmp_dir, 'epydoc_test.pyc')) 
183      except OSError: pass 
184      os.rmdir(tmp_dir) 
185      sys.modules.pop('epydoc_test', None) 
186   
187 -def to_plain(docstring): 
188      """Conver a parsed docstring into plain text""" 
189      if isinstance(docstring, ParsedDocstring): 
190          docstring = docstring.to_plaintext(None) 
191      return docstring.rstrip() 
192   
193 -def fun_to_plain(val_doc): 
194      """Convert parsed docstrings in text from a RoutineDoc""" 
195      for k, v in val_doc.arg_types.items(): 
196          val_doc.arg_types[k] = to_plain(v) 
197      for i, (k, v) in enumerate(val_doc.arg_descrs): 
198          val_doc.arg_descrs[i] = (k, to_plain(v)) 
199   
200 -def print_docstring_as_html(self, parsed_docstring, *varargs, **kwargs): 
201      """ 
202      Convert the given parsed_docstring to HTML and print it.  Ignore 
203      any other arguments.  This function is used by L{testencoding} to 
204      monkey-patch the HTMLWriter class's docstring_to_html() method. 
205      """ 
206      s = parsed_docstring.to_html(None).strip() 
207      s = s.encode('ascii', 'xmlcharrefreplace') 
208      s = remove_surrogates(s) 
209      print s 
210      return '' 
211   
212 -def remove_surrogates(s): 
213      """ 
214      The following is a helper function, used to convert two-character 
215      surrogate sequences into single characters.  This is needed 
216      because some systems create surrogates but others don't. 
217      """ 
218      pieces = re.split('(&#\d+;)', s) 
219      for i in range(3, len(pieces)-1, 2): 
220          if pieces[i-1] != '': continue 
221          high,low = int(pieces[i-2][2:-1]), int(pieces[i][2:-1]) 
222          if 0xd800 <= high <= 0xdbff and 0xdc00 <= low <= 0xdfff: 
223              pieces[i-2] = '&#%d;' % (((high&0x3ff)<<10) + 
224                                       (low&0x3ff) + 0x10000) 
225              pieces[i] = '' 
226      return ''.join(pieces) 
227