{"id":9695,"library":"docstr-coverage","title":"Docstr-coverage","description":"docstr-coverage is a Python utility that scans source files to ensure proper documentation. It identifies missing docstrings, provides a detailed report, and calculates an overall docstring coverage percentage. The current version is 2.3.2, and it follows an infrequent but active release cadence, typically releasing minor versions a few times a year.","status":"active","version":"2.3.2","language":"en","source_language":"en","source_url":"https://github.com/HunterMcGushion/docstr_coverage","tags":["documentation","code quality","linter","testing","cli"],"install":[{"cmd":"pip install docstr-coverage","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for parsing TOML configuration files (e.g., pyproject.toml).","package":"toml","optional":false}],"imports":[{"symbol":"get_docstr_coverage","correct":"from docstr_coverage import get_docstr_coverage"}],"quickstart":{"code":"import os\nfrom docstr_coverage import get_docstr_coverage\n\n# Create a dummy file for demonstration\nwith open('example_module.py', 'w') as f:\n    f.write(\"\"\"\"\"\"\"Module docstring.\"\"\"\\n\nclass MyClass:\\n    \"\"\"Class docstring.\"\"\"\\n    def __init__(self):\\n        # No docstring here - this will be reported\\n        pass\\n\\n    def my_method(self, arg):\\n        \"\"\"Method docstring.\"\"\"\\n        return arg * 2\\n\"\"\")\n\n# Run docstr-coverage programmatically\nreport = get_docstr_coverage(\n    paths=['example_module.py'],\n    skip_init=False,\n    skip_magic=True,\n    skip_private=False,\n    skip_class_innards=False,\n    verbose=2\n)\n\nprint(f\"\\nOverall coverage: {report['overall_coverage']:.2f}%\")\n\nif report['missing_docstrings']:\n    print(\"\\nMissing docstrings found:\")\n    for item in report['missing_docstrings']:\n        print(f\"  - {item['file']}:{item['line']} ({item['name']}) -> {item['type']}\")\n\n# Clean up dummy file\nos.remove('example_module.py')","lang":"python","description":"The primary usage of docstr-coverage is via the command line, but it also exposes a programmatic API. This example demonstrates how to use `get_docstr_coverage` to analyze a Python file and print the results. For CLI usage, simply run `docstr-coverage your_project/`."},"warnings":[{"fix":"Update all configuration options in your project's configuration files (e.g., `pyproject.toml`) to use `snake_case`. For example, `failUnder` becomes `fail_under`.","message":"Configuration options (e.g., in `pyproject.toml` or `setup.cfg`) changed from `camelCase` to `snake_case`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"In CI/CD scripts, be aware of the exit codes. Configure your CI system to expect specific exit codes or wrap the command with `|| true` if you only want to log warnings without failing the build based on docstring coverage.","message":"The `docstr-coverage` CLI returns non-zero exit codes (e.g., 1 for failing `--fail-under`, 2 for argument errors). This can cause CI/CD pipelines to fail unexpectedly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully review the documentation for `--skip` (for individual docstring types) and `--exclude` (for file paths). Use glob patterns for `--exclude` paths, and test your configuration thoroughly to ensure the correct files and docstring types are being evaluated.","message":"Incorrect usage of exclusion flags like `--skip` or `--exclude` can lead to either files being unexpectedly included or crucial files being ignored.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install docstr-coverage`","cause":"The `docstr-coverage` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'docstr_coverage'"},{"fix":"Update your command-line arguments or configuration file (e.g., `pyproject.toml`) to use `snake_case`. Change `--failUnder` to `--fail-under`.","cause":"Using `camelCase` configuration options or command-line arguments in `docstr-coverage` version 2.0.0 or later. Options now require `snake_case`.","error":"docstr-coverage: error: unrecognized arguments: --failUnder=90"},{"fix":"Ensure your virtual environment is activated. Alternatively, run it as a Python module: `python -m docstr_coverage your_project/`.","cause":"The `docstr-coverage` executable is not in your system's PATH, usually because a virtual environment is not activated or pip's script directory is not included.","error":"Command 'docstr-coverage' not found"}]}