Docs and cleanup for source_pkgs

Author: nedbat

CHANGES.rst

@@ -25,6 +25,14 @@ want to know what's different in 5.0 since 4.5.x, see :ref:`whatsnew5x`.
 Unreleased
 ----------
 
+- The ``source`` setting has always been interpreted as either a file path or a
+  module, depending on which existed.  If both interpretations were valid, it
+  was assumed to be a file path.  The new ``source_pkgs`` setting can be used
+  to name a package to disambiguate this case.  Thanks, Thomas Grainger. Fixes
+  `issue 268`_.
+
+.. _issue 268: https://github.com/nedbat/coveragepy/issues/268
+
 
 .. _changes_521:
 

coverage/control.py

@@ -101,7 +101,7 @@ def __init__(
         auto_data=False, timid=None, branch=None, config_file=True,
         source=None, source_pkgs=None, omit=None, include=None, debug=None,
         concurrency=None, check_preimported=False, context=None,
-    ):
+    ):  # pylint: disable=too-many-arguments
         """
         Many of these arguments duplicate and override values that can be
         provided in a configuration file.  Parameters that are missing here
@@ -146,6 +146,10 @@ def __init__(
         in the trees indicated by the file paths or package names will be
         measured.
 
+        `source_pkgs` is a list of package names. It works the same as
+        `source`, but can be used to name packages where the name can also be
+        interpreted as a file path.
+
         `include` and `omit` are lists of file name patterns. Files that match
         `include` will be measured, files that match `omit` will not.  Each
         will also accept a single string argument.
@@ -176,6 +180,9 @@ def __init__(
         .. versionadded:: 5.0
             The `check_preimported` and `context` parameters.
 
+        .. versionadded:: 5.3
+            The `source_pkgs` parameter.
+
         """
         # data_file=None means no disk file at all. data_file missing means
         # use the value from the config file.

coverage/version.py

@@ -5,7 +5,7 @@
 # This file is exec'ed in setup.py, don't import anything!
 
 # Same semantics as sys.version_info.
-version_info = (5, 2, 2, "alpha", 0)
+version_info = (5, 3, 0, "alpha", 0)
 
 
 def _make_version(major, minor, micro, releaselevel, serial):

doc/config.rst

@@ -208,6 +208,14 @@ for details.
 measure during execution.  If set, ``include`` is ignored. See :ref:`source`
 for details.
 
+.. _config_run_source_pkgs:
+
+``source_pkgs`` (multi-string): a list of packages, the source to measure
+during execution.  Operates the same as ``source``, but only names packages,
+for resolving ambiguities between packages and directories.
+
+.. versionadded:: 5.3
+
 .. _config_run_timid:
 
 ``timid`` (boolean, default False): use a simpler but slower trace method.

tests/modules/ambigious/pkg1/__init__.py

@@ -0,0 +1 @@
+print("Ambiguous pkg1")

tests/modules/ambigious/pkg1/ambigious.py

@@ -0,0 +1,2 @@
+amb = 1
+amb = 2

tests/modules/usepkgs.py

@@ -5,3 +5,4 @@
 import pkg2.p2a, pkg2.p2b
 import othermods.othera, othermods.otherb
 import othermods.sub.osa, othermods.sub.osb
+import ambigious, ambigious.pkg1.ambigious

tests/test_api.py

@@ -940,13 +940,8 @@ def test_ambigious_source_package_as_dir(self):
         self.chdir(self.nice_file(TESTS_DIR, 'modules', "ambigious"))
         # pkg1 defaults to directory because tests/modules/ambigious/pkg1 exists
         lines = self.coverage_usepkgs(source=["pkg1"])
-        self.assertEqual(
-            self.coverage_usepkgs(source=["pkg1"]),
-            {
-                u"__init__.py": 0, u"__init__": 0,
-                u"ambigious.py": 0, u"ambigious": 0,
-            },
-        )
+        self.filenames_in(lines, "ambigious")
+        self.filenames_not_in(lines, "p1a p1b p1c")
 
     def test_ambigious_source_package_as_package(self):
         # pkg1 is a directory and a pkg, since we cd into tests/modules/ambigious