docs: document the exceptions

... and make some of them private.

10 files changed, 38 insertions, 26 deletions

diff --git a/Makefile b/Makefile
index 909ca4d6..681e6bf1 100644
--- a/Makefile
+++ b/Makefile
@@ -110,7 +110,7 @@ build_ext:
 DOCBIN = .tox/doc/bin
 SPHINXOPTS = -aE
 SPHINXBUILD = $(DOCBIN)/sphinx-build $(SPHINXOPTS)
-SPHINXAUTOBUILD = $(DOCBIN)/sphinx-autobuild -p 9876 --ignore '.git/**' --open-browser
+SPHINXAUTOBUILD = $(DOCBIN)/sphinx-autobuild --port 9876 --ignore '.git/**' --open-browser
 WEBHOME = ~/web/stellated
 WEBSAMPLE = $(WEBHOME)/files/sample_coverage_html
 WEBSAMPLEBETA = $(WEBHOME)/files/sample_coverage_html_beta
diff --git a/coverage/cmdline.py b/coverage/cmdline.py
index 13783d76..d0cd4625 100644
--- a/coverage/cmdline.py
+++ b/coverage/cmdline.py
@@ -19,7 +19,7 @@ from coverage import env
 from coverage.collector import CTracer
 from coverage.data import CoverageData, combinable_files, line_counts
 from coverage.debug import info_formatter, info_header, short_stack
-from coverage.exceptions import BaseCoverageException, ExceptionDuringRun, NoSource
+from coverage.exceptions import _BaseCoverageException, _ExceptionDuringRun, NoSource
 from coverage.execfile import PyRunner
 from coverage.misc import human_sorted, plural
 from coverage.results import Numbers, should_fail_under
@@ -899,13 +899,13 @@ def main(argv=None):
         argv = sys.argv[1:]
     try:
         status = CoverageScript().command_line(argv)
-    except ExceptionDuringRun as err:
+    except _ExceptionDuringRun as err:
         # An exception was caught while running the product code.  The
-        # sys.exc_info() return tuple is packed into an ExceptionDuringRun
+        # sys.exc_info() return tuple is packed into an _ExceptionDuringRun
         # exception.
         traceback.print_exception(*err.args)    # pylint: disable=no-value-for-parameter
         status = ERR
-    except BaseCoverageException as err:
+    except _BaseCoverageException as err:
         # A controlled error inside coverage.py: print the message to the user.
         msg = err.args[0]
         print(msg)
diff --git a/coverage/exceptions.py b/coverage/exceptions.py
index 6631e1ad..de2257a1 100644
--- a/coverage/exceptions.py
+++ b/coverage/exceptions.py
@@ -4,12 +4,12 @@
 """Exceptions coverage.py can raise."""
 
 
-class BaseCoverageException(Exception):
+class _BaseCoverageException(Exception):
     """The base of all Coverage exceptions."""
     pass
 
 
-class CoverageException(BaseCoverageException):
+class CoverageException(_BaseCoverageException):
     """An exception raised by a coverage.py function."""
     pass
 
@@ -29,7 +29,7 @@ class NotPython(CoverageException):
     pass
 
 
-class ExceptionDuringRun(CoverageException):
+class _ExceptionDuringRun(CoverageException):
     """An exception happened while running customer code.
 
     Construct it with three arguments, the values from `sys.exc_info`.
@@ -38,7 +38,7 @@ class ExceptionDuringRun(CoverageException):
     pass
 
 
-class StopEverything(BaseCoverageException):
+class _StopEverything(_BaseCoverageException):
     """An exception that means everything should stop.
 
     The CoverageTest class converts these to SkipTest, so that when running
diff --git a/coverage/execfile.py b/coverage/execfile.py
index 38dc1d07..2ee2f725 100644
--- a/coverage/execfile.py
+++ b/coverage/execfile.py
@@ -13,7 +13,7 @@ import sys
 import types
 
 from coverage import env
-from coverage.exceptions import CoverageException, ExceptionDuringRun, NoCode, NoSource
+from coverage.exceptions import CoverageException, _ExceptionDuringRun, NoCode, NoSource
 from coverage.files import canonical_filename, python_reported_file
 from coverage.misc import isolate_module
 from coverage.phystokens import compile_unicode
@@ -233,7 +233,7 @@ class PyRunner:
                 err2.__traceback__ = err2.__traceback__.tb_next
                 sys.__excepthook__(typ2, err2, tb2.tb_next)
                 sys.stderr.write("\nOriginal exception was:\n")
-                raise ExceptionDuringRun(typ, err, tb.tb_next) from exc
+                raise _ExceptionDuringRun(typ, err, tb.tb_next) from exc
             else:
                 sys.exit(1)
         finally:
diff --git a/coverage/parser.py b/coverage/parser.py
index d17d7c9b..665360fa 100644
--- a/coverage/parser.py
+++ b/coverage/parser.py
@@ -13,7 +13,7 @@ import tokenize
 from coverage import env
 from coverage.bytecode import code_objects
 from coverage.debug import short_stack
-from coverage.exceptions import NoSource, NotPython, StopEverything
+from coverage.exceptions import NoSource, NotPython, _StopEverything
 from coverage.misc import contract, join_regex, new_contract, nice_pair, one_of
 from coverage.phystokens import compile_unicode, generate_tokens, neuter_encoding_declaration
 
@@ -356,7 +356,7 @@ class ByteParser:
         # attributes on code objects that we need to do the analysis.
         for attr in ['co_lnotab', 'co_firstlineno']:
             if not hasattr(self.code, attr):
-                raise StopEverything(                   # pragma: only jython
+                raise _StopEverything(                  # pragma: only jython
                     "This implementation of Python doesn't support code analysis.\n" +
                     "Run coverage.py under another Python for this command."
                 )
diff --git a/doc/api.rst b/doc/api.rst
index 855e3ec6..f5112165 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -9,10 +9,10 @@ Coverage.py API
 
 There are a few different ways to use coverage.py programmatically.
 
-The API to coverage.py is in a module called `coverage`.
-Most of the interface is in the :class:`coverage.Coverage` class.  Methods on
-the Coverage object correspond roughly to operations available in the command
-line interface. For example, a simple use would be::
+The API to coverage.py is in a module called :mod:`coverage`.  Most of the
+interface is in the :class:`coverage.Coverage` class.  Methods on the Coverage
+object correspond roughly to operations available in the command line
+interface. For example, a simple use would be::
 
     import coverage
 
@@ -48,6 +48,7 @@ only.  :ref:`dbschema` explains more.
     :maxdepth: 1
 
     api_coverage
+    api_exceptions
     api_module
     api_plugin
     api_coveragedata
diff --git a/doc/api_exceptions.rst b/doc/api_exceptions.rst
new file mode 100644
index 00000000..38109657
--- /dev/null
+++ b/doc/api_exceptions.rst
@@ -0,0 +1,11 @@
+.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
+
+.. _api_exceptions:
+
+Coverage exceptions
+-------------------
+
+.. automodule:: coverage.exceptions
+    :noindex:
+    :members:
diff --git a/tests/conftest.py b/tests/conftest.py
index 16c2c162..6ef42fc1 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -15,7 +15,7 @@ import warnings
 import pytest
 
 from coverage import env
-from coverage.exceptions import StopEverything
+from coverage.exceptions import _StopEverything
 
 
 # Pytest will rewrite assertions in test modules, but not elsewhere.
@@ -96,10 +96,10 @@ def pytest_runtest_call(item):
     """Run once for each test."""
     write_test_name(">")
 
-    # Convert StopEverything into skipped tests.
+    # Convert _StopEverything into skipped tests.
     outcome = yield
-    if outcome.excinfo and issubclass(outcome.excinfo[0], StopEverything):  # pragma: only jython
-        pytest.skip(f"Skipping {item.nodeid} for StopEverything: {outcome.excinfo[1]}")
+    if outcome.excinfo and issubclass(outcome.excinfo[0], _StopEverything):  # pragma: only jython
+        pytest.skip(f"Skipping {item.nodeid} for _StopEverything: {outcome.excinfo[1]}")
 
     write_test_name("<")
 
diff --git a/tests/test_cmdline.py b/tests/test_cmdline.py
index 4e4f65b0..952dc47b 100644
--- a/tests/test_cmdline.py
+++ b/tests/test_cmdline.py
@@ -16,7 +16,7 @@ import coverage.cmdline
 from coverage import env
 from coverage.config import CoverageConfig
 from coverage.data import CoverageData
-from coverage.exceptions import ExceptionDuringRun
+from coverage.exceptions import _ExceptionDuringRun
 from coverage.version import __url__
 
 from tests.coveragetest import CoverageTest, OK, ERR, command_line
@@ -972,7 +972,7 @@ class CmdMainTest(CoverageTest):
                 try:
                     raise Exception("oh noes!")
                 except:
-                    raise ExceptionDuringRun(*sys.exc_info())
+                    raise _ExceptionDuringRun(*sys.exc_info())
             elif argv[0] == 'internalraise':
                 raise ValueError("coverage is broken")
             elif argv[0] == 'exit':
diff --git a/tests/test_execfile.py b/tests/test_execfile.py
index d211eba9..9c8b9233 100644
--- a/tests/test_execfile.py
+++ b/tests/test_execfile.py
@@ -15,7 +15,7 @@ import sys
 import pytest
 
 from coverage import env
-from coverage.exceptions import NoCode, NoSource, ExceptionDuringRun
+from coverage.exceptions import NoCode, NoSource, _ExceptionDuringRun
 from coverage.execfile import run_python_file, run_python_module
 from coverage.files import python_reported_file
 
@@ -185,9 +185,9 @@ class RunFileTest(CoverageTest):
 
             raise RuntimeError('Error Outside')
             """)
-        with pytest.raises(ExceptionDuringRun) as exc_info:
+        with pytest.raises(_ExceptionDuringRun) as exc_info:
             run_python_file(["excepthook_throw.py"])
-        # The ExceptionDuringRun exception has the RuntimeError as its argument.
+        # The _ExceptionDuringRun exception has the RuntimeError as its argument.
         assert exc_info.value.args[1].args[0] == "Error Outside"
         stderr = self.stderr()
         assert "in excepthook\n" in stderr