Issue 199: Sort text report.

Allows sorting of the text report based on:
 Name, Stmts, Miss, Cover

Tested on Mac with Python 2.7.11 and Python 3.5

Help message for the new option is:
python -m coverage report -h
  ...
  --sort=SORT           Sort report by a column. Valid values are: Name,
                        Stmts, Miss, Cover.
  ...

5 files changed, 49 insertions, 5 deletions

diff --git a/coverage/cmdline.py b/coverage/cmdline.py
index e2b79fe..b2803c5 100644
--- a/coverage/cmdline.py
+++ b/coverage/cmdline.py
@@ -82,6 +82,14 @@ class Opts(object):
         '--skip-covered', action='store_true',
         help="Skip files with 100% coverage.",
     )
+    SORT_CHOICES = ('Name', 'Stmts', 'Miss', 'Cover')
+    sort = optparse.make_option(
+        '--sort', action='store', choices=SORT_CHOICES,
+        help=(
+              "Sort report by a column. "
+              "Valid values are: %s."
+        ) % ", ".join(SORT_CHOICES)
+    )
     omit = optparse.make_option(
         '', '--omit', action='store',
         metavar="PAT1,PAT2,...",
@@ -335,6 +343,7 @@ CMDS = {
             Opts.include,
             Opts.omit,
             Opts.show_missing,
+            Opts.sort,
             Opts.skip_covered,
             ] + GLOBAL_ARGS,
         usage="[options] [modules]",
@@ -504,7 +513,8 @@ class CoverageScript(object):
         if options.action == "report":
             total = self.coverage.report(
                 show_missing=options.show_missing,
-                skip_covered=options.skip_covered, **report_args)
+                skip_covered=options.skip_covered, sort_name=options.sort,
+                **report_args)
         elif options.action == "annotate":
             self.coverage.annotate(
                 directory=options.directory, **report_args)
diff --git a/coverage/control.py b/coverage/control.py
index 97d4625..d41181e 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -943,7 +943,7 @@ class Coverage(object):
     def report(
         self, morfs=None, show_missing=None, ignore_errors=None,
         file=None,                  # pylint: disable=redefined-builtin
-        omit=None, include=None, skip_covered=None,
+        omit=None, include=None, skip_covered=None, sort_name=None
     ):
         """Write a summary report to `file`.
 
@@ -961,6 +961,7 @@ class Coverage(object):
         self.config.from_args(
             ignore_errors=ignore_errors, omit=omit, include=include,
             show_missing=show_missing, skip_covered=skip_covered,
+            sort=sort_name,
             )
         reporter = SummaryReporter(self, self.config)
         return reporter.report(morfs, outfile=file)
diff --git a/coverage/summary.py b/coverage/summary.py
index 81844b5..c5b393d 100644
--- a/coverage/summary.py
+++ b/coverage/summary.py
@@ -62,6 +62,7 @@ class SummaryReporter(Reporter):
 
         total = Numbers()
         skipped_count = 0
+        lines = []
 
         for fr in file_reporters:
             try:
@@ -90,7 +91,10 @@ class SummaryReporter(Reporter):
                                 missing_fmtd += ", "
                             missing_fmtd += branches_fmtd
                     args += (missing_fmtd,)
-                writeout(fmt_coverage % args)
+                text = fmt_coverage % args
+                # Add numeric percent coverage so that sorting makes sense
+                args += (nums.pc_covered,)
+                lines.append((text, args))
             except Exception:
                 report_it = not self.config.ignore_errors
                 if report_it:
@@ -100,7 +104,19 @@ class SummaryReporter(Reporter):
                     if typ is NotPython and not fr.should_be_python():
                         report_it = False
                 if report_it:
-                    writeout(fmt_err % (fr.relative_filename(), typ.__name__, msg))
+                    args = (fr.relative_filename(), typ.__name__, msg)
+                    lines.append((fmt_err % args, (fr.relative_filename(), 0, 0, 0, 0)))
+
+        if getattr(self.config, 'sort', None):
+            column_order = dict(Name=0,
+                                Stmts=1,
+                                Miss=2,
+                                Cover=-1,
+                                Missing=4)
+            position = column_order.get(self.config.sort)
+            lines.sort(key=lambda l: (l[1][position], l[0]))
+        for line in lines:
+            writeout(line[0])
 
         if total.n_files > 1:
             writeout(rule)
diff --git a/tests/test_cmdline.py b/tests/test_cmdline.py
index 8e2840b..1fefb02 100644
--- a/tests/test_cmdline.py
+++ b/tests/test_cmdline.py
@@ -43,7 +43,7 @@ class BaseCmdLineTest(CoverageTest):
     )
     defaults.report(
         ignore_errors=None, include=None, omit=None, morfs=[],
-        show_missing=None, skip_covered=None
+        show_missing=None, skip_covered=None, sort_name=None
     )
     defaults.xml_report(
         ignore_errors=None, include=None, omit=None, morfs=[], outfile=None,
@@ -341,6 +341,11 @@ class CmdLineTest(BaseCmdLineTest):
             .load()
             .report(skip_covered=True)
             """)
+        self.cmd_executes("report --sort Stmts", """\
+            .coverage()
+            .load()
+            .report(sort_name='Stmts')
+            """)
 
     def test_run(self):
         # coverage run [-p] [-L] [--timid] MODULE.py [ARG1 ARG2 ...]
diff --git a/tests/test_summary_class.py b/tests/test_summary_class.py
index 93e025c..2a8cd7c 100644
--- a/tests/test_summary_class.py
+++ b/tests/test_summary_class.py
@@ -51,3 +51,15 @@ class TestSummaryReporterConfiguration(unittest.TestCase):
         report = self.get_summary_text(data, opts)
         self.assertIn('Missing', report)
         self.assertNotIn('Branch', report)
+
+    def test_sort_report(self):
+        """Sort the text report."""
+        data = self.get_coverage_data()
+        opts = config.CoverageConfig()
+        opts.from_args(sort='Stmts')
+        report = self.get_summary_text(data, opts)
+        # just the basename, to avoid pyc and directory name complexities
+        filename = os.path.splitext(os.path.basename(__file__))[0]
+        location1 = report.find('helpers')
+        location2 = report.find(filename)
+        self.assertLess(location1, location2)