refactor, docs: clean-up for #1387

Author: nedbat

CHANGES.rst

@@ -34,6 +34,14 @@ Unreleased
   time needed.  For coverage.py's own test suite, combining was about 17%
   faster.
 
+- When searching for completely unexecuted files, coverage.py uses the presence
+  of ``__init__.py`` files to determine which directories have source that
+  could have been imported.  However, `implicit namespace packages`_ don't
+  require ``__init__.py``.  A new setting ``[report]
+  include_namespace_packages`` tells coverage.py to consider these directories
+  during reporting.  Thanks to `Felix Horvat <pull 1387_>`_ for the
+  contribution.  Closes `issue 1383`_.
+
 - An empty file has a coverage total of 100%, but used to fail with
   ``--fail-under``.  This has been fixed, closing `issue 1470`_.
 
@@ -45,9 +53,12 @@ Unreleased
 
 - The ``[run] note`` setting has been completely removed.
 
+.. _implicit namespace packages: https://peps.python.org/pep-0420/
+.. _issue 1383: https://github.com/nedbat/coveragepy/issues/1383
 .. _issue 1418: https://github.com/nedbat/coveragepy/issues/1418
 .. _issue 1421: https://github.com/nedbat/coveragepy/issues/1421
 .. _issue 1470: https://github.com/nedbat/coveragepy/issues/1470
+.. _pull 1387: https://github.com/nedbat/coveragepy/pull/1387
 .. _pull 1479: https://github.com/nedbat/coveragepy/pull/1479
 
 

CONTRIBUTORS.txt

@@ -68,6 +68,7 @@ Eli Skeggs
 Emil Madsen
 Éric Larivière
 Federico Bond
+Felix Horvat
 Frazer McLean
 Geoff Bache
 George Paci

coverage/control.py

@@ -530,7 +530,7 @@ def _init_for_start(self):
         self._inorout = InOrOut(
             warn=self._warn,
             debug=(self._debug if self._debug.should('trace') else None),
-            include_namespace_packages=self.config.include_namespace_packages
+            include_namespace_packages=self.config.include_namespace_packages,
         )
         self._inorout.configure(self.config)
         self._inorout.plugins = self._plugins

coverage/files.py

@@ -470,14 +470,20 @@ def find_python_files(dirname, include_namespace_packages):
     best, but sub-directories are checked for a __init__.py to be sure we only
     find the importable files.
 
+    If `include_namespace_packages` is True, then the check for __init__.py
+    files is skipped.
+
+    Files with strange characters are skipped, since they couldn't have been
+    imported, and are probably editor side-files.
+
     """
     for i, (dirpath, dirnames, filenames) in enumerate(os.walk(dirname)):
-        if (i > 0 and '__init__.py' not in filenames
-            and not include_namespace_packages):
-            # If a directory doesn't have __init__.py, then it isn't
-            # importable and neither are its files
-            del dirnames[:]
-            continue
+        if not include_namespace_packages:
+            if i > 0 and "__init__.py" not in filenames:
+                # If a directory doesn't have __init__.py, then it isn't
+                # importable and neither are its files
+                del dirnames[:]
+                continue
         for filename in filenames:
             # We're only interested in files that look like reasonable Python
             # files: Must end with .py or .pyw, and must not have certain funny

doc/config.rst

@@ -415,8 +415,14 @@ See :ref:`source` for details.
 [report] include_namespace_packages
 ...................................
 
-(boolean, default False) Include folders without an ``__init__.py`` in the
-coverage.
+(boolean, default False) When searching for completely unexecuted files,
+include directories without ``__init__.py`` files.  These are `implicit
+namespace packages`_, and are ususally skipped.
+
+.. _implicit namespace packages: https://peps.python.org/pep-0420/
+
+.. versionadded:: 6.6
+
 
 .. _config_report_omit: