third_party/pycoverage/coverage/html.py

   1 """HTML reporting for Coverage."""
   2
   3 import os, re, shutil, sys
   4
   5 import coverage
   6 from coverage.backward import pickle
   7 from coverage.misc import CoverageException, Hasher
   8 from coverage.phystokens import source_token_lines, source_encoding
   9 from coverage.report import Reporter
  10 from coverage.results import Numbers
  11 from coverage.templite import Templite
  12
  13
  14 # Static files are looked for in a list of places.
  15 STATIC_PATH = [
  16     # The place Debian puts system Javascript libraries.
  17     "/usr/share/javascript",
  18
  19     # Our htmlfiles directory.
  20     os.path.join(os.path.dirname(__file__), "htmlfiles"),
  21 ]
  22
  23 def data_filename(fname, pkgdir=""):
  24     """Return the path to a data file of ours.
  25
  26     The file is searched for on `STATIC_PATH`, and the first place it's found,
  27     is returned.
  28
  29     Each directory in `STATIC_PATH` is searched as-is, and also, if `pkgdir`
  30     is provided, at that subdirectory.
  31
  32     """
  33     for static_dir in STATIC_PATH:
  34         static_filename = os.path.join(static_dir, fname)
  35         if os.path.exists(static_filename):
  36             return static_filename
  37         if pkgdir:
  38             static_filename = os.path.join(static_dir, pkgdir, fname)
  39             if os.path.exists(static_filename):
  40                 return static_filename
  41     raise CoverageException("Couldn't find static file %r" % fname)
  42
  43
  44 def data(fname):
  45     """Return the contents of a data file of ours."""
  46     data_file = open(data_filename(fname))
  47     try:
  48         return data_file.read()
  49     finally:
  50         data_file.close()
  51
  52
  53 class HtmlReporter(Reporter):
  54     """HTML reporting."""
  55
  56     # These files will be copied from the htmlfiles dir to the output dir.
  57     STATIC_FILES = [
  58             ("style.css", ""),
  59             ("jquery.min.js", "jquery"),
  60             ("jquery.hotkeys.js", "jquery-hotkeys"),
  61             ("jquery.isonscreen.js", "jquery-isonscreen"),
  62             ("jquery.tablesorter.min.js", "jquery-tablesorter"),
  63             ("coverage_html.js", ""),
  64             ("keybd_closed.png", ""),
  65             ("keybd_open.png", ""),
  66             ]
  67
  68     def __init__(self, cov, config):
  69         super(HtmlReporter, self).__init__(cov, config)
  70         self.directory = None
  71         self.template_globals = {
  72             'escape': escape,
  73             'title': self.config.html_title,
  74             '__url__': coverage.__url__,
  75             '__version__': coverage.__version__,
  76             }
  77         self.source_tmpl = Templite(
  78             data("pyfile.html"), self.template_globals
  79             )
  80
  81         self.coverage = cov
  82
  83         self.files = []
  84         self.arcs = self.coverage.data.has_arcs()
  85         self.status = HtmlStatus()
  86         self.extra_css = None
  87         self.totals = Numbers()
  88
  89     def report(self, morfs):
  90         """Generate an HTML report for `morfs`.
  91
  92         `morfs` is a list of modules or filenames.
  93
  94         """
  95         assert self.config.html_dir, "must give a directory for html reporting"
  96
  97         # Read the status data.
  98         self.status.read(self.config.html_dir)
  99
 100         # Check that this run used the same settings as the last run.
 101         m = Hasher()
 102         m.update(self.config)
 103         these_settings = m.digest()
 104         if self.status.settings_hash() != these_settings:
 105             self.status.reset()
 106             self.status.set_settings_hash(these_settings)
 107
 108         # The user may have extra CSS they want copied.
 109         if self.config.extra_css:
 110             self.extra_css = os.path.basename(self.config.extra_css)
 111
 112         # Process all the files.
 113         self.report_files(self.html_file, morfs, self.config.html_dir)
 114
 115         if not self.files:
 116             raise CoverageException("No data to report.")
 117
 118         # Write the index file.
 119         self.index_file()
 120
 121         self.make_local_static_report_files()
 122
 123         return self.totals.pc_covered
 124
 125     def make_local_static_report_files(self):
 126         """Make local instances of static files for HTML report."""
 127         # The files we provide must always be copied.
 128         for static, pkgdir in self.STATIC_FILES:
 129             shutil.copyfile(
 130                 data_filename(static, pkgdir),
 131                 os.path.join(self.directory, static)
 132                 )
 133
 134         # The user may have extra CSS they want copied.
 135         if self.extra_css:
 136             shutil.copyfile(
 137                 self.config.extra_css,
 138                 os.path.join(self.directory, self.extra_css)
 139                 )
 140
 141     def write_html(self, fname, html):
 142         """Write `html` to `fname`, properly encoded."""
 143         fout = open(fname, "wb")
 144         try:
 145             fout.write(html.encode('ascii', 'xmlcharrefreplace'))
 146         finally:
 147             fout.close()
 148
 149     def file_hash(self, source, cu):
 150         """Compute a hash that changes if the file needs to be re-reported."""
 151         m = Hasher()
 152         m.update(source)
 153         self.coverage.data.add_to_hash(cu.filename, m)
 154         return m.digest()
 155
 156     def html_file(self, cu, analysis):
 157         """Generate an HTML file for one source file."""
 158         source_file = cu.source_file()
 159         try:
 160             source = source_file.read()
 161         finally:
 162             source_file.close()
 163
 164         # Find out if the file on disk is already correct.
 165         flat_rootname = cu.flat_rootname()
 166         this_hash = self.file_hash(source, cu)
 167         that_hash = self.status.file_hash(flat_rootname)
 168         if this_hash == that_hash:
 169             # Nothing has changed to require the file to be reported again.
 170             self.files.append(self.status.index_info(flat_rootname))
 171             return
 172
 173         self.status.set_file_hash(flat_rootname, this_hash)
 174
 175         # If need be, determine the encoding of the source file. We use it
 176         # later to properly write the HTML.
 177         if sys.version_info < (3, 0):
 178             encoding = source_encoding(source)
 179             # Some UTF8 files have the dreaded UTF8 BOM. If so, junk it.
 180             if encoding.startswith("utf-8") and source[:3] == "\xef\xbb\xbf":
 181                 source = source[3:]
 182                 encoding = "utf-8"
 183
 184         # Get the numbers for this file.
 185         nums = analysis.numbers
 186
 187         if self.arcs:
 188             missing_branch_arcs = analysis.missing_branch_arcs()
 189
 190         # These classes determine which lines are highlighted by default.
 191         c_run = "run hide_run"
 192         c_exc = "exc"
 193         c_mis = "mis"
 194         c_par = "par " + c_run
 195
 196         lines = []
 197
 198         for lineno, line in enumerate(source_token_lines(source)):
 199             lineno += 1     # 1-based line numbers.
 200             # Figure out how to mark this line.
 201             line_class = []
 202             annotate_html = ""
 203             annotate_title = ""
 204             if lineno in analysis.statements:
 205                 line_class.append("stm")
 206             if lineno in analysis.excluded:
 207                 line_class.append(c_exc)
 208             elif lineno in analysis.missing:
 209                 line_class.append(c_mis)
 210             elif self.arcs and lineno in missing_branch_arcs:
 211                 line_class.append(c_par)
 212                 annlines = []
 213                 for b in missing_branch_arcs[lineno]:
 214                     if b < 0:
 215                         annlines.append("exit")
 216                     else:
 217                         annlines.append(str(b))
 218                 annotate_html = "&nbsp;&nbsp; ".join(annlines)
 219                 if len(annlines) > 1:
 220                     annotate_title = "no jumps to these line numbers"
 221                 elif len(annlines) == 1:
 222                     annotate_title = "no jump to this line number"
 223             elif lineno in analysis.statements:
 224                 line_class.append(c_run)
 225
 226             # Build the HTML for the line
 227             html = []
 228             for tok_type, tok_text in line:
 229                 if tok_type == "ws":
 230                     html.append(escape(tok_text))
 231                 else:
 232                     tok_html = escape(tok_text) or '&nbsp;'
 233                     html.append(
 234                         "<span class='%s'>%s</span>" % (tok_type, tok_html)
 235                         )
 236
 237             lines.append({
 238                 'html': ''.join(html),
 239                 'number': lineno,
 240                 'class': ' '.join(line_class) or "pln",
 241                 'annotate': annotate_html,
 242                 'annotate_title': annotate_title,
 243             })
 244
 245         # Write the HTML page for this file.
 246         html = spaceless(self.source_tmpl.render({
 247             'c_exc': c_exc, 'c_mis': c_mis, 'c_par': c_par, 'c_run': c_run,
 248             'arcs': self.arcs, 'extra_css': self.extra_css,
 249             'cu': cu, 'nums': nums, 'lines': lines,
 250         }))
 251
 252         if sys.version_info < (3, 0):
 253             html = html.decode(encoding)
 254
 255         html_filename = flat_rootname + ".html"
 256         html_path = os.path.join(self.directory, html_filename)
 257         self.write_html(html_path, html)
 258
 259         # Save this file's information for the index file.
 260         index_info = {
 261             'nums': nums,
 262             'html_filename': html_filename,
 263             'name': cu.name,
 264             }
 265         self.files.append(index_info)
 266         self.status.set_index_info(flat_rootname, index_info)
 267
 268     def index_file(self):
 269         """Write the index.html file for this report."""
 270         index_tmpl = Templite(
 271             data("index.html"), self.template_globals
 272             )
 273
 274         self.totals = sum([f['nums'] for f in self.files])
 275
 276         html = index_tmpl.render({
 277             'arcs': self.arcs,
 278             'extra_css': self.extra_css,
 279             'files': self.files,
 280             'totals': self.totals,
 281         })
 282
 283         if sys.version_info < (3, 0):
 284             html = html.decode("utf-8")
 285         self.write_html(
 286             os.path.join(self.directory, "index.html"),
 287             html
 288             )
 289
 290         # Write the latest hashes for next time.
 291         self.status.write(self.directory)
 292
 293
 294 class HtmlStatus(object):
 295     """The status information we keep to support incremental reporting."""
 296
 297     STATUS_FILE = "status.dat"
 298     STATUS_FORMAT = 1
 299
 300     def __init__(self):
 301         self.reset()
 302
 303     def reset(self):
 304         """Initialize to empty."""
 305         self.settings = ''
 306         self.files = {}
 307
 308     def read(self, directory):
 309         """Read the last status in `directory`."""
 310         usable = False
 311         try:
 312             status_file = os.path.join(directory, self.STATUS_FILE)
 313             fstatus = open(status_file, "rb")
 314             try:
 315                 status = pickle.load(fstatus)
 316             finally:
 317                 fstatus.close()
 318         except (IOError, ValueError):
 319             usable = False
 320         else:
 321             usable = True
 322             if status['format'] != self.STATUS_FORMAT:
 323                 usable = False
 324             elif status['version'] != coverage.__version__:
 325                 usable = False
 326
 327         if usable:
 328             self.files = status['files']
 329             self.settings = status['settings']
 330         else:
 331             self.reset()
 332
 333     def write(self, directory):
 334         """Write the current status to `directory`."""
 335         status_file = os.path.join(directory, self.STATUS_FILE)
 336         status = {
 337             'format': self.STATUS_FORMAT,
 338             'version': coverage.__version__,
 339             'settings': self.settings,
 340             'files': self.files,
 341             }
 342         fout = open(status_file, "wb")
 343         try:
 344             pickle.dump(status, fout)
 345         finally:
 346             fout.close()
 347
 348     def settings_hash(self):
 349         """Get the hash of the coverage.py settings."""
 350         return self.settings
 351
 352     def set_settings_hash(self, settings):
 353         """Set the hash of the coverage.py settings."""
 354         self.settings = settings
 355
 356     def file_hash(self, fname):
 357         """Get the hash of `fname`'s contents."""
 358         return self.files.get(fname, {}).get('hash', '')
 359
 360     def set_file_hash(self, fname, val):
 361         """Set the hash of `fname`'s contents."""
 362         self.files.setdefault(fname, {})['hash'] = val
 363
 364     def index_info(self, fname):
 365         """Get the information for index.html for `fname`."""
 366         return self.files.get(fname, {}).get('index', {})
 367
 368     def set_index_info(self, fname, info):
 369         """Set the information for index.html for `fname`."""
 370         self.files.setdefault(fname, {})['index'] = info
 371
 372
 373 # Helpers for templates and generating HTML
 374
 375 def escape(t):
 376     """HTML-escape the text in `t`."""
 377     return (t
 378             # Convert HTML special chars into HTML entities.
 379             .replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
 380             .replace("'", "&#39;").replace('"', "&quot;")
 381             # Convert runs of spaces: "......" -> "&nbsp;.&nbsp;.&nbsp;."
 382             .replace("  ", "&nbsp; ")
 383             # To deal with odd-length runs, convert the final pair of spaces
 384             # so that "....." -> "&nbsp;.&nbsp;&nbsp;."
 385             .replace("  ", "&nbsp; ")
 386         )
 387
 388 def spaceless(html):
 389     """Squeeze out some annoying extra space from an HTML string.
 390
 391     Nicely-formatted templates mean lots of extra space in the result.
 392     Get rid of some.
 393
 394     """
 395     html = re.sub(r">\s+<p ", ">\n<p ", html)
 396     return html