Add --accept-empty to avoid exit code 1 (#48)

* Draft

* black

* Flake & Typo

* Make descriptions for `--accept-empty` in README/Click match

Co-authored-by: Hunter McGushion <hunter@mcgushion.com>

Author: MiWeiss

README.md

@@ -61,6 +61,7 @@ docstr-coverage some_project/src
 - _--skip-file-doc, -f_ - Ignore module docstrings (at the top of files)
 - _--skip-private, -P_ - Ignore private functions (starting with a single underscore)
 - _--skip-class-def, -c_ - Ignore docstrings of class definitions
+- _--accept-empty, -a_ - Exit with code 0 if no Python files are found (default: exit code 1)
 - _--exclude=\<regex\>, -e \<regex\>_ - Filepath pattern to exclude from analysis
   - To exclude the contents of a virtual environment `env` and your `tests` directory, run:
   ```docstr-coverage some_project/ -e ".*/(env|tests)"```
@@ -103,6 +104,7 @@ skip_init: True # Boolean
 skip_class_def: True # Boolean
 skip_private: True # Boolean
 follow_links: True # Boolean
+accept_empty: True # Boolean
 ignore_names_file: .*/test # regex
 fail_under: 90 # int 
 percentage_only: True # Boolean

docstr_coverage/cli.py

@@ -4,6 +4,7 @@
 import platform
 import re
 import sys
+import warnings
 from typing import List, Optional
 
 import click
@@ -217,6 +218,12 @@ def _assert_valid_key_value(k, v):
     is_flag=True,
     help="Output only the overall coverage percentage as a float, silencing all other logging",
 )
+@click.option(
+    "-a",
+    "--accept-empty",
+    is_flag=True,
+    help="Exit with code 0 if no Python files are found (default: exit code 1)",
+)
 @click.help_option("-h", "--help")
 @click.argument(
     "paths",
@@ -279,7 +286,14 @@ def execute(paths, **kwargs):
     )
 
     if len(all_paths) < 1:
-        sys.exit("No Python files found")
+        if kwargs["accept_empty"] is True:
+            warnings.warn("No Python files found in specified paths. Processing aborted")
+            sys.exit(0)
+        else:
+            sys.exit(
+                "No Python files found "
+                "(use `--accept-empty` to exit with code 0 if you expect this case)"
+            )
 
     # Parse ignore names file
     has_ignore_patterns_in_config = "ignore_patterns" in kwargs

tests/test_cli.py

@@ -444,3 +444,62 @@ def test_ignore_patterns_files(
     else:
         parse_ig_from_dict.assert_not_called()
         mock_parse_ig_f.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    ["paths", "path_contains_py"],
+    [
+        pytest.param([SAMPLES_DIR], True, id="samples_dir_x1"),
+        pytest.param([SAMPLES_A.documented], True, id="files_x1"),
+        pytest.param([SAMPLES_A.empty, SAMPLES_A.partial], True, id="files_x2"),
+        pytest.param([SAMPLES_A.dirpath, SAMPLES_B.dirpath], True, id="dirs_x2"),
+        pytest.param(
+            [SAMPLES_A.empty, SAMPLES_A.partial, SAMPLES_B.dirpath], True, id="files_x2+dir_x1"
+        ),
+        pytest.param([os.path.join("sample_files", "subdir_a")], True, id="rel_dir_x1"),
+        pytest.param(
+            [os.path.join("config_files", "docstr_ignore.txt")], False, id="file_with_no_python"
+        ),
+        pytest.param([os.path.join(CWD, "config_files")], False, id="folder_with_no_python"),
+    ],
+)
+@pytest.mark.parametrize(
+    ["accept_empty_flag", "accept_empty_value"],
+    [
+        pytest.param([], False, id="no_accept_empty"),
+        pytest.param(["-a"], True, id="short_accept_empty"),
+        pytest.param(["--accept-empty"], True, id="long_accept_empty"),
+    ],
+)
+@pytest.mark.usefixtures("cd_tests_dir_fixture")
+def test_accept_empty(
+    paths: List[str],
+    path_contains_py: bool,
+    accept_empty_flag: List[str],
+    accept_empty_value: bool,
+    runner: CliRunner,
+):
+    """Test that the `--accept-empty`/`-a` flag leads to the correct exit codes
+
+    Parameters
+    ----------
+    paths: List[str]
+        Path arguments provided to CLI. These should be made absolute before they are passed to
+        :func:`docstr_coverage.cli.collect_filepaths`
+    path_contains_py: bool
+        True iff the passed paths point (directly or indirectly via dir) to at least one .py file
+    accept_empty_flag: List[str]
+        Flag under test
+    accept_empty_value: bool
+        True iff the flag under test specifies to return exit code 0 if no .py file was found
+    runner: CliRunner
+        Click utility to invoke command line scripts"""
+
+    dont_fail_due_to_coverage = ["--fail-under=5"]
+
+    run_result = runner.invoke(execute, paths + accept_empty_flag + dont_fail_due_to_coverage)
+
+    if accept_empty_flag or path_contains_py:
+        assert run_result.exit_code == 0
+    else:
+        assert run_result.exit_code == 1