Added AsyncFunctionDef visitor to make compatible with async functions (HunterMcGushion#116)

Allows the tool to properly detect async functions and factor in their docstrings in coverage/missing reports

Author: caffeinatedMike

docstr_coverage/visitor.py

@@ -1,7 +1,14 @@
 """This module handles traversing abstract syntax trees to check for docstrings"""
 import re
 import tokenize
-from ast import ClassDef, FunctionDef, Module, NodeVisitor, get_docstring
+from ast import (
+    AsyncFunctionDef,
+    ClassDef,
+    FunctionDef,
+    Module,
+    NodeVisitor,
+    get_docstring,
+)
 from typing import Optional
 
 ACCEPTED_EXCUSE_PATTERNS = (
@@ -37,6 +44,10 @@ def visit_FunctionDef(self, node: FunctionDef):
         """Collect information regarding function/method declaration nodes"""
         self._visit_helper(node)
 
+    def visit_AsyncFunctionDef(self, node: AsyncFunctionDef):
+        """Collect information regarding async function/method declaration nodes"""
+        self._visit_helper(node)
+
     def _visit_helper(self, node):
         """Helper method to update :attr:`DocStringCoverageVisitor.tree` with pertinent
         documentation information for `node`, then ensure all child nodes are

tests/excused_samples/fully_excused.py

@@ -19,12 +19,21 @@ def function(self):
     def prop(self):
         pass
 
+    # docstr-coverage:excuse `...almost as lazy as async functions...`
+    async def async_function(self):
+        pass
+
 
 # docstr-coverage:excuse `... besides: who's checking anyways`
 def bar():
     pass
 
 
+# docstr-coverage:excuse `... also: setting up async tests suck in general`
+async def baz():
+    pass
+
+
 # docstr-coverage:excuse `no one is reading this anyways`
 class FooBarChild(FooBar):
 

tests/extra_samples/private_undocumented.py

@@ -7,3 +7,11 @@ def _foo():
 
 def __dunder():
     pass
+
+
+async def _afoo():
+    pass
+
+
+async def __adunder():
+    pass

tests/sample_files/subdir_a/documented_file.py

@@ -13,6 +13,9 @@ def function(self):
     def another_function(self):
         """This is a second regular method docstring"""
 
+    async def an_async_function(self):
+        """This is an async method docstring"""
+
     @property
     def prop(self):
         """This is a wrapped method docstring"""
@@ -32,3 +35,7 @@ def _foo():
 
 def bar():
     """This is another function"""
+
+
+async def baz():
+    """This is an async function"""

tests/test_cli.py

@@ -230,11 +230,11 @@ def test_parse_ignore_names_file(path: str, expected: tuple):
 @pytest.mark.parametrize(
     ["paths", "expected_output"],
     [
-        [[SAMPLES_A.dirpath], "62.5"],
+        [[SAMPLES_A.dirpath], "66.66666666666667"],
         [[SAMPLES_A.partial], "20.0"],
         [[SAMPLES_A.documented], "100.0"],
         [[SAMPLES_A.undocumented], "0.0"],
-        [[SAMPLES_A.undocumented, SAMPLES_A.documented], "81.81818181818181"],
+        [[SAMPLES_A.undocumented, SAMPLES_A.documented], "84.61538461538461"],
     ],
 )
 @pytest.mark.parametrize("verbose_flag", [["-v", "0"], ["-v", "1"], ["-v", "2"], ["-v", "3"]])

tests/test_coverage.py

@@ -41,7 +41,7 @@ def test_should_report_for_an_empty_file():
 
 
 @pytest.mark.parametrize(
-    ["file_path", "needed_count"], [(DOCUMENTED_FILE_PATH, 9), (FULLY_EXCUSED_FILE_PATH, 8)]
+    ["file_path", "needed_count"], [(DOCUMENTED_FILE_PATH, 11), (FULLY_EXCUSED_FILE_PATH, 10)]
 )
 def test_should_report_full_coverage(file_path, needed_count):
     result = analyze([file_path])
@@ -105,7 +105,7 @@ def test_should_report_for_multiple_files():
             "missing": [],
             "module_doc": True,
             "missing_count": 0,
-            "needed_count": 9,
+            "needed_count": 11,
             "coverage": 100.0,
             "empty": False,
         },
@@ -118,7 +118,7 @@ def test_should_report_for_multiple_files():
             "empty": True,
         },
     }
-    assert total_results == {"missing_count": 4, "needed_count": 14, "coverage": 71.42857142857143}
+    assert total_results == {"missing_count": 4, "needed_count": 16, "coverage": 75.0}
 
 
 def test_should_report_when_no_docs_in_a_file():
@@ -255,14 +255,14 @@ def test_skip_private():
     result = analyze([PRIVATE_NO_DOCS_PATH], ignore_config=ignore_config)
     file_results, total_results = result.to_legacy()
     assert file_results[PRIVATE_NO_DOCS_PATH] == {
-        "missing": ["__dunder"],
+        "missing": ["__dunder", "__adunder"],
         "module_doc": True,
-        "missing_count": 1,
-        "needed_count": 2,
-        "coverage": 50.0,
+        "missing_count": 2,
+        "needed_count": 3,
+        "coverage": 33.333333333333336,
         "empty": False,
     }
-    assert total_results == {"missing_count": 1, "needed_count": 2, "coverage": 50.0}
+    assert total_results == {"missing_count": 2, "needed_count": 3, "coverage": 33.333333333333336}
 
 
 def test_long_doc():