def handle(self, *args, **options):
""" If fisrt arg for docstr-coverage (directory or filename to measure docstr coverage) is not set -
the command will collect all registered django apps (according to `settings.INSTALLED_APPS`)
placed in `settings.BASE_DIR'.
Extra settings:
settings.DOCSTR_EXTRA_DIRS (list): list of extra dirs (not included to `settings.INSTALLED_APPS`)
to include them to the docstr-coverage measure
settings.DOCSTR_EXCLUDE (str): regex identifying filepaths to exclude used as default `exclude` parameter
"""
if len(args) > 1:
print("Expected a single path argument. Received invalid argument(s): {}".format(args[1:]))
sys.exit()
verbose = options.get('verbose')
if not args:
base = self.collect_dirs()
filenames = []
for directory in base:
found_files = self.collect_filenames(directory, options)
if found_files:
if verbose > 1:
print("Included {}".format(directory))
filenames.extend(found_files)
else:
base = args[0]
if base.endswith(".py"):
filenames = [base]
else:
filenames = self.collect_filenames(directory, options)
if len(filenames) < 1:
sys.exit("No Python files found")
if verbose > 0:
print("-" * 81)
print("\n DOCSTR-COVERAGE: \n")
code_excludes = getattr(settings, 'DOCSTR_CODE_EXCLUDES', None)
get_docstring_coverage(
filenames,
skip_magic=options.get('skip_magic'),
skip_file_docstring=options.get('skip_file_docstring'),
skip_init=options.get('skip_init'),
skip_class_def=options.get('skip_class_def'),
verbose=options.get('verbose'),
code_excludes=code_excludes,
)
if verbose > 0:
print("-" * 81)
print("\n")
def test_should_report_for_multiple_files():
file_results, total_results = get_docstring_coverage(
[PARTLY_DOCUMENTED_FILE_PATH, DOCUMENTED_FILE_PATH, EMPTY_FILE_PATH])
assert file_results == {
PARTLY_DOCUMENTED_FILE_PATH: {
"missing": ["FooBar.__init__", "foo", "bar"],
"module_doc": False,
"missing_count": 4,
"needed_count": 5,
"coverage": 20.0,
"empty": False,
},
DOCUMENTED_FILE_PATH: {
"missing": [],
"module_doc": True,
"missing_count": 0,
"needed_count": 9,
"coverage": 100.0,
"empty": False,
},
EMPTY_FILE_PATH: {
"missing": [],
"module_doc": False,
"missing_count": 0,
"needed_count": 0,
"coverage": 0,
"empty": True,
},
}
assert total_results == {
"missing_count": 4,
"needed_count": 14,
"coverage": 71.42857142857143
}
def test_logging_partially_documented_file(caplog, expected, verbose,
ignore_names):
with caplog.at_level(logging.DEBUG):
_file_results, _total_results = get_docstring_coverage(
[PARTLY_DOCUMENTED_FILE_PATH],
verbose=verbose,
ignore_names=ignore_names)
assert caplog.messages == expected
def test_logging_empty_file(caplog, expected):
with caplog.at_level(logging.DEBUG):
_file_results, _total_results = get_docstring_coverage(
[EMPTY_FILE_PATH], verbose=3)
if platform.system() == "Windows":
assert [m.replace("\\", "/") for m in caplog.messages] == expected
else:
assert caplog.messages == expected
def test_logging_partially_documented_file(caplog, expected, verbose,
ignore_names):
with caplog.at_level(logging.DEBUG):
_file_results, _total_results = get_docstring_coverage(
[PARTLY_DOCUMENTED_FILE_PATH],
verbose=verbose,
ignore_names=ignore_names)
if platform.system() == "Windows":
assert [m.replace("\\", "/") for m in caplog.messages] == expected
else:
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
}
def test_should_report_for_an_empty_file():
file_results, total_results = get_docstring_coverage([EMPTY_FILE_PATH])
assert file_results == {
EMPTY_FILE_PATH: {
"missing": [],
"module_doc": False,
"missing_count": 0,
"needed_count": 0,
"coverage": 0,
"empty": True,
}
}
assert total_results == {
"missing_count": 0,
"needed_count": 0,
"coverage": 100
}
def test_should_report_full_coverage(file_path, needed_count):
file_results, total_results = get_docstring_coverage([file_path])
assert file_results == {
file_path: {
"missing": [],
"module_doc": True,
"missing_count": 0,
"needed_count": needed_count,
"coverage": 100.0,
"empty": False,
}
}
assert total_results == {
"missing_count": 0,
"needed_count": needed_count,
"coverage": 100.0
}
def test_should_report_partial_coverage():
file_results, total_results = get_docstring_coverage(
[PARTLY_DOCUMENTED_FILE_PATH])
assert file_results == {
PARTLY_DOCUMENTED_FILE_PATH: {
"missing": ["FooBar.__init__", "foo", "bar"],
"module_doc": False,
"missing_count": 4,
"needed_count": 5,
"coverage": 20.0,
"empty": False,
}
}
assert total_results == {
"missing_count": 4,
"needed_count": 5,
"coverage": 20.0
}
def test_should_report_full_coverage():
file_results, total_results = get_docstring_coverage(
[DOCUMENTED_FILE_PATH])
assert file_results == {
DOCUMENTED_FILE_PATH: {
"missing": [],
"module_doc": True,
"missing_count": 0,
"needed_count": 9,
"coverage": 100.0,
"empty": False,
}
}
assert total_results == {
"missing_count": 0,
"needed_count": 9,
"coverage": 100.0
}
def test_should_report_when_no_docs_in_a_file():
file_results, total_results = get_docstring_coverage(
[SOME_CODE_NO_DOCS_FILE_PATH])
assert file_results == {
SOME_CODE_NO_DOCS_FILE_PATH: {
"missing": ["foo"],
"module_doc": False,
"missing_count": 2,
"needed_count": 2,
"coverage": 0.0,
"empty": False,
}
}
assert total_results == {
"missing_count": 2,
"needed_count": 2,
"coverage": 0.0
}
def test_should_report_partial_coverage(file_path, missing, module_doc,
missing_count, needed_count, coverage):
file_results, total_results = get_docstring_coverage([file_path])
assert file_results == {
file_path: {
"missing": missing,
"module_doc": module_doc,
"missing_count": missing_count,
"needed_count": needed_count,
"coverage": coverage,
"empty": False,
}
}
assert total_results == {
"missing_count": missing_count,
"needed_count": needed_count,
"coverage": coverage,
}
def get_modinfo(modules, docname):
modinfo = {}
modinfo['files'] = {m: [] for m in modules}
modinfo['dirs'] = {m: find_module(m) for m in modules}
modinfo['doc'] = {m: '{}-{}.md'.format(docname, m) for m in modules}
modinfo['topdoc'] = '{}.md'.format(docname)
for mod in modules:
for root, dirs, files in os.walk(modinfo['dirs'][mod]):
for file in (f for f in files if f.endswith(".py")):
modinfo['files'][mod].append(os.path.join(root, file))
modinfo['coverage'] = {
m: get_docstring_coverage(filenames=modinfo['files'][m],
skip_magic=True)
for m in modules
}
return modinfo
def test_logging_empty_file(caplog, expected):
with caplog.at_level(logging.DEBUG):
_file_results, _total_results = get_docstring_coverage(
[EMPTY_FILE_PATH], verbose=3)
assert caplog.messages == expected
from docstr_coverage import get_docstring_coverage
from typing import List, Union
import os
if __name__ == "__main__":
# collect files
files: List[Union[os.PathLike, str]] = []
for dirpath, _, filenames in os.walk('training_scheduler'):
files.extend(
os.path.join(dirpath, name) for name in filenames
if name.endswith('.py'))
get_docstring_coverage(files, verbose=3)