Add ability to skip private functions (#32)

* Add ability to skip private functions

Closes #31

* Make sure skip_private doesn't also skip magic functions

* Change flag

* Update coverage.py

* Add test for skipping private

* Add logging

* Update test

trunder and quadrunder should both also fall under the magic/mangling category

* Update coverage.py

* Update cli.py

* Update private_undocumented.py

* Reorganize test files

* Reorganize part 2

* Update README.md

Author: cthoyt

README.md

@@ -58,6 +58,7 @@ docstr-coverage some_project/src
 
 - _--skipmagic, -m_ - Ignore all magic methods (like `__init__`, and `__str__`)
 - _--skipfiledoc, -f_ - Ignore module docstrings (at the top of files)
+- _--skip-private, -P_ - Ignore private functions (starting with a single underscore)
 - _--exclude=\<regex\>, -e \<regex\>_ - Filepath pattern to exclude from analysis
   _ To exclude the contents of a virtual environment `env` and your `tests` directory, run:
   <br>```\$ docstr-coverage some_project/ -e "env/_|tests/\*"```
@@ -91,7 +92,7 @@ my_coverage = get_docstring_coverage(['some_dir/file_0.py', 'some_dir/file_1.py'
 ##### Arguments
 
 - Required arg: `filenames` \<list of string filenames\>
-- Optional kwargs: `skip_magic` \<bool\>, `skip_file_docstring` \<bool\>, `verbose` \<int (0-3)\> \* For more info on `get_docstring_coverage` and its parameters, please see its [documentation](https://docstr-coverage.readthedocs.io/en/latest/api_essentials.html#get-docstring-coverage)
+- Optional kwargs: `skip_magic` \<bool\>, `skip_file_docstring` \<bool\>, `skip_private` \<bool\>, `verbose` \<int (0-3)\> \* For more info on `get_docstring_coverage` and its parameters, please see its [documentation](https://docstr-coverage.readthedocs.io/en/latest/api_essentials.html#get-docstring-coverage)
 
 ##### Results
 

docstr_coverage/cli.py

@@ -148,6 +148,15 @@ def parse_ignore_names_file(ignore_names_file: str) -> tuple:
     help="Ignore docstrings of class definitions",
     show_default=True,
 )
+@click.option(
+    "-P",
+    "--skip-private",
+    type=bool,
+    is_flag=True,
+    default=False,
+    help="Ignore docstrings of functions starting with a single underscore",
+    show_default=True,
+)
 @click.option(
     "-l",
     "--followlinks",
@@ -225,6 +234,7 @@ def execute(paths, **kwargs):
         skip_file_docstring=kwargs["skip_file_docstring"],
         skip_init=kwargs["skip_init"],
         skip_class_def=kwargs["skip_class_def"],
+        skip_private=kwargs["skip_private"],
         verbose=kwargs["verbose"],
         ignore_names=ignore_names,
     )

docstr_coverage/coverage.py

@@ -86,6 +86,7 @@ def get_docstring_coverage(
     skip_file_docstring: bool = False,
     skip_init: bool = False,
     skip_class_def: bool = False,
+    skip_private: bool = False,
     verbose: int = 0,
     ignore_names: Tuple[List[str], ...] = (),
 ):
@@ -107,6 +108,9 @@ def get_docstring_coverage(
     skip_class_def: Boolean, default=False
         If True, skips class definitions and does not include them in the report.
         If this is True, the class's methods will still be checked
+    skip_private: Boolean, default=False
+        If True, skips function definitions beginning with a single underscore and does
+        not include them in the report.
     verbose: Int in [0, 1, 2, 3], default=0
         0) No printing.
         1) Print total stats only.
@@ -211,6 +215,8 @@ def print_docstring(base, node, filename, ignore_names=()):
                 docs_needed -= 1
             elif skip_class_def and "_" not in name and (name[0] == name[0].upper()):
                 docs_needed -= 1
+            elif skip_private and name.startswith("_") and not name.startswith("__"):
+                docs_needed -= 1
             elif ignore_names and do_ignore_node(filename, base, name, ignore_names):
                 docs_needed -= 1
             else:
@@ -318,6 +324,8 @@ def print_docstring(base, node, filename, ignore_names=()):
         postfix += " (skipped __init__ methods)"
     if skip_class_def:
         postfix += " (skipped class definitions)"
+    if skip_private:
+        postfix += " (skipped private methods)"
 
     log("\n", 2)
 

tests/extra_samples/private_undocumented.py

@@ -0,0 +1,9 @@
+"""Test file for undocumented private methods."""
+
+
+def _foo():
+    pass
+
+
+def __dunder():
+    pass

tests/test_coverage.py

@@ -11,6 +11,9 @@
 PARTLY_DOCUMENTED_FILE_PATH = os.path.join(SAMPLES_DIRECTORY, "partly_documented_file.py")
 SOME_CODE_NO_DOCS_FILE_PATH = os.path.join(SAMPLES_DIRECTORY, "some_code_no_docs.py")
 
+SAMPLES_C_DIRECTORY = os.path.join("tests", "extra_samples")
+PRIVATE_NO_DOCS_PATH = os.path.join(SAMPLES_C_DIRECTORY, "private_undocumented.py")
+
 
 def test_should_report_for_an_empty_file():
     file_results, total_results = get_docstring_coverage([EMPTY_FILE_PATH])
@@ -205,3 +208,16 @@ def test_logging_partially_documented_file(caplog, expected, verbose, ignore_nam
         )
 
     assert caplog.messages == expected
+
+
+def test_skip_private():
+    file_results, total_results = get_docstring_coverage([PRIVATE_NO_DOCS_PATH], skip_private=True)
+    assert file_results[PRIVATE_NO_DOCS_PATH] == {
+        "missing": ["__dunder"],
+        "module_doc": True,
+        "missing_count": 1,
+        "needed_count": 2,
+        "coverage": 50.0,
+        "empty": False,
+    }
+    assert total_results == {"missing_count": 1, "needed_count": 2, "coverage": 50.0}