v1.9.0 - Improve Parameter Mismatch Reporting and Test Robustness
📝 Summary
The focus of this release is on improving the clarity of parameter mismatch error messages and enhancing the robustness of the test suite. Introduce targeted detection for variadic parameters (*args, **kwargs) documented with leading asterisks in docstrings, and provide actionable guidance to remove them. Refactor test assertions to use native Python assert statements, standardise return type annotations in tests, and fix various formatting issues in test data generation. Ensure a more user-friendly experience and a more maintainable codebase through these enhancements.
📊 Release Statistics
| Attribute | Note |
|---|---|
| Version: | v1.9.0 |
| Python Support: | 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 |
| Test Coverage: | 100% (1033 statements, +11 from v1.8.0) |
| Pylint Score: | 10.00/10 |
| Complexity: | All functions ≤13 threshold |
| Functions: | 106 (unchanged from v1.8.0) |
| Tests Passing: | 250/250 (+2 from v1.8.0) |
| Files Changed: | 6 |
| Lines Added: | 119 |
| Lines Removed: | 20 |
| Commits: | 12 |
| Pull Requests Merged: | 1 (PR #27) |
🎯 Improve Parameter Mismatch Reporting
🔍 Overview
Enhance the parameter mismatch error output to provide clearer, more actionable feedback when variadic parameters are documented with leading asterisks. Reduce confusion by identifying that the parameter names match once the asterisks are ignored, rather than reporting them as entirely separate missing and extra parameters.
❓ Problem Statement
When validating functions with *args or **kwargs, the tool previously reported a mismatch if the docstring included the asterisks (e.g., *args (Any):). This resulted in a confusing error message that listed the parameter as both missing from the docstring (without asterisks) and extra in the docstring (with asterisks).
Example of previous confusing output:
Params section mismatch:
- In signature but not in docstring: 'args', 'kwargs'
- In docstring but not in signature: '*args', '**kwargs'
💡 Solution
Update the mismatch detection logic to recognise when a parameter name in the docstring matches a signature parameter after stripping leading asterisks.
Targeted Asterisk Detection
Update ._build_param_mismatch_error() to detect asterisk-only mismatches. When found, the tool now emits a specific message:
Parameter mismatch:
- Parameter 'args' found in docstring as '*args'. Please remove the asterisk.
- Parameter 'kwargs' found in docstring as '**kwargs'. Please remove the asterisks.
Robust Parameter Extraction
Strengthen the regex pattern in ._extract_documented_params() to correctly capture parameters with exactly zero, one, or two leading asterisks using \*{0,2}. Ensure that only valid Python parameter prefix patterns are matched.
🧪 Enhance Test Suite Robustness
🔍 Overview
Refactor the test suite to improve readability, maintainability, and alignment with modern Python testing standards. Standardise assertions, improve type safety, and fix formatting issues in test data.
🛠️ Key Improvements
Standardise Assertions
Replace unittest style assertions (e.g., .assertIn(), .assertFalse()) with native Python assert statements across the test suite. Align the codebase with pytest conventions and improve the readability of test failures.
Improve Type Safety
Add explicit None return type annotations to various test methods in src/tests/test_core.py. Ensure better type checking and consistency across the test suite.
Fix Test Data Formatting
Utilise dedent() for all dynamically generated Python file content in tests. Ensure that leading whitespace is correctly handled, preventing potential parsing issues or incorrect indentation in temporary test files.
Resolve Syntax Conflicts
Fix nested docstring syntax in test cases by replacing inner triple double quotes with triple single quotes. Prevent syntax errors when parsing code blocks that contain their own docstrings.
⚙️ Internal Refactorings
🛡️ Avoid Input Mutation
Refactor ._build_param_mismatch_error() to work with local copies of the missing_in_docstring and extra_in_docstring lists. Prevent unintended side effects on caller functions that might rely on the original lists remaining unchanged.
📏 Improve Test Output Visibility
Increase the default diff width for test output to 120 characters in pyproject.toml. Ensure that long error messages and diffs are clearly visible in the terminal without being prematurely wrapped.
💪 Pull Requests
Full Changelog: v1.8.0...v1.9.0
