Skip to content

Commit f3c5f08

Browse files
github-actions[bot]github-actions[bot]
committed
Update changelog to v1.9.0 [skip ci]
1 parent fae623b commit f3c5f08

1 file changed

Lines changed: 178 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,184 @@
99
.md-nav--secondary .md-nav__list .md-nav__list { display: none; }
1010
</style>
1111

12+
!!! info "v1.9.0"
13+
14+
## **v1.9.0 - Improve Parameter Mismatch Reporting and Test Robustness**
15+
16+
<!-- md:tag v1.9.0 --><br>
17+
<!-- md:date 2025-12-28 --><br>
18+
<!-- md:link [data-science-extensions/docstring-format-checker/releases/v1.9.0](https://github.com/data-science-extensions/docstring-format-checker/releases/tag/v1.9.0) -->
19+
20+
??? note "Release Notes"
21+
22+
### 📝 Summary
23+
24+
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.
25+
26+
27+
### 📊 Release Statistics
28+
29+
| Attribute | Note |
30+
| ------------------------- | --------------------------------------------- |
31+
| **Version:** | [`v1.9.0`] |
32+
| **Python Support:** | `3.9`, `3.10`, `3.11`, `3.12`, `3.13`, `3.14` |
33+
| **Test Coverage:** | 100% (1033 statements, +11 from v1.8.0) |
34+
| **Pylint Score:** | 10.00/10 |
35+
| **Complexity:** | All functions ≤13 threshold |
36+
| **Functions:** | 106 (unchanged from v1.8.0) |
37+
| **Tests Passing:** | 250/250 (+2 from v1.8.0) |
38+
| **Files Changed:** | 6 |
39+
| **Lines Added:** | 119 |
40+
| **Lines Removed:** | 20 |
41+
| **Commits:** | 12 |
42+
| **Pull Requests Merged:** | 1 (PR #27) |
43+
44+
45+
### 🎯 Improve Parameter Mismatch Reporting
46+
47+
48+
#### 🔍 Overview
49+
50+
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.
51+
52+
53+
#### ❓ Problem Statement
54+
55+
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).
56+
57+
**Example of previous confusing output:**
58+
59+
```
60+
Params section mismatch:
61+
- In signature but not in docstring: 'args', 'kwargs'
62+
- In docstring but not in signature: '*args', '**kwargs'
63+
```
64+
65+
66+
#### 💡 Solution
67+
68+
Update the mismatch detection logic to recognise when a parameter name in the docstring matches a signature parameter after stripping leading asterisks.
69+
70+
71+
##### Targeted Asterisk Detection
72+
73+
Update `._build_param_mismatch_error()` to detect asterisk-only mismatches. When found, the tool now emits a specific message:
74+
75+
```
76+
Parameter mismatch:
77+
- Parameter 'args' found in docstring as '*args'. Please remove the asterisk.
78+
- Parameter 'kwargs' found in docstring as '**kwargs'. Please remove the asterisks.
79+
```
80+
81+
82+
##### Robust Parameter Extraction
83+
84+
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.
85+
86+
87+
### 🧪 Enhance Test Suite Robustness
88+
89+
90+
#### 🔍 Overview
91+
92+
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.
93+
94+
95+
#### 🛠️ Key Improvements
96+
97+
98+
##### Standardise Assertions
99+
100+
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.
101+
102+
103+
##### Improve Type Safety
104+
105+
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.
106+
107+
108+
##### Fix Test Data Formatting
109+
110+
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.
111+
112+
113+
##### Resolve Syntax Conflicts
114+
115+
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.
116+
117+
118+
### ⚙️ Internal Refactorings
119+
120+
121+
#### 🛡️ Avoid Input Mutation
122+
123+
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.
124+
125+
126+
#### 📏 Improve Test Output Visibility
127+
128+
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.
129+
130+
131+
### 💪 Pull Requests
132+
133+
* Improve Error Messages for Asterisk Parameter Mismatches by @chrimaho in https://github.com/data-science-extensions/docstring-format-checker/pull/27
134+
135+
136+
**Full Changelog**: https://github.com/data-science-extensions/docstring-format-checker/compare/v1.8.0...v1.9.0
137+
138+
139+
[`v1.9.0`]: https://github.com/data-science-extensions/docstring-format-checker/releases/tag/v1.9.0
140+
[`unittest`]: https://docs.python.org/3/library/unittest.html
141+
[`pytest`]: https://docs.pytest.org/
142+
143+
??? abstract "Updates"
144+
145+
* [`ebda57e`](https://github.com/data-science-extensions/docstring-format-checker/commit/ebda57e6dfbe7832768e8595681e845b83543b24): Update test output width and fix grammar<br>
146+
- Increase the diff width for test output to improve visibility of failures.<br>
147+
- Correct the pluralisation in error messages for double-starred parameters.
148+
(by [chrimaho](https://github.com/chrimaho))
149+
* [`b0645de`](https://github.com/data-science-extensions/docstring-format-checker/commit/b0645de98d1f63cf65ffd568a95b9f366d7f3100): Make error messages more robust and readable<br>
150+
The error message uses the singular "asterisk" but should handle both single (`*args`) and double (`**kwargs`) asterisks. Consider making the message more accurate by using "asterisk(s)" or detecting the number of asterisks and adjusting the message accordingly.
151+
(by [chrimaho](https://github.com/chrimaho))
152+
* [`0654455`](https://github.com/data-science-extensions/docstring-format-checker/commit/0654455353fd6d9fcb067a7b697537d4e4f981ba): Fix exception attribute access in unit tests<br>
153+
- Correct the attribute used to access exceptions by switching to the `value` attribute.<br>
154+
- Standardise verification of exception messages within the `TestGlobalConfigFeatures()` class.
155+
(by [chrimaho](https://github.com/chrimaho))
156+
* [`0240a3d`](https://github.com/data-science-extensions/docstring-format-checker/commit/0240a3dace818743f68fe3f0b88591b401bc315b): Avoid mutating inputs in parameter mismatch logic<br>
157+
- Create local copies of the `missing_in_docstring` list and `extra_in_docstring` list to prevent unintended side effects on caller functions.<br>
158+
- Update the matching logic to remove items from these local copies when identifying asterisk mismatches.<br>
159+
- Use these local copies instead of the original parameters when constructing the final error message string.
160+
(by [chrimaho](https://github.com/chrimaho))
161+
* [`4c3dee6`](https://github.com/data-science-extensions/docstring-format-checker/commit/4c3dee68d2580b0bc3309790d590b5e330087b54): Strengthen regex syntax<br>
162+
The regex pattern uses `\**` which matches zero or more asterisks. This could incorrectly match invalid cases like `***args` (three asterisks) or edge cases with many asterisks. Consider using `\*{0,2}` to match exactly 0, 1, or 2 asterisks, which are the only valid Python parameter prefix patterns.
163+
(by [chrimaho](https://github.com/chrimaho))
164+
* [`e5844b1`](https://github.com/data-science-extensions/docstring-format-checker/commit/e5844b1dc60e3b11ec1618ebd7cae9a2f3229b68): Refactor test assertions to use native assert statements<br>
165+
- Replace `unittest` style assertions like `.assertFalse()` and `.assertIn()` with native Python `assert` statements in `src/tests/test_core.py`<br>
166+
- Simplify test logic within the `TestParameterMismatch` class to improve readability and align with pytest style conventions
167+
(by [chrimaho](https://github.com/chrimaho))
168+
* [`76b0165`](https://github.com/data-science-extensions/docstring-format-checker/commit/76b0165952603e09bdefeef296a16ea0763d4bad): Add return type annotations to core test methods<br>
169+
- Update various test methods in `src/tests/test_core.py` to explicitly return `None` to improve type safety<br>
170+
- Modify the `TestDocstringChecker` class and the `TestParameterMismatch` class to align with strict typing standards<br>
171+
- Apply changes to the `.test_83_malformed_type_after_valid_type()` method, the `.test_param_mismatch_with_asterisks()` method, and others
172+
(by [chrimaho](https://github.com/chrimaho))
173+
* [`34af423`](https://github.com/data-science-extensions/docstring-format-checker/commit/34af42382c79fcf23e09f866c24d5042d70e6ca7): Use `dedent()` for test file content creation<br>
174+
- Ensure proper formatting of generated Python files in `TestCLI` by removing leading whitespace from the multiline string.<br>
175+
- Prevent potential parsing issues or incorrect indentation in the temporary test files created during execution.
176+
(by [chrimaho](https://github.com/chrimaho))
177+
* [`a4a168f`](https://github.com/data-science-extensions/docstring-format-checker/commit/a4a168fe78096a2b6d335f6cc0d5651a6e908913): Fix nested docstring syntax in test cases<br>
178+
- Utilise `dedent()` to ensure correct indentation for dynamically parsed code blocks within tests<br>
179+
- Replace inner triple double quotes with triple single quotes to avoid syntax conflicts in the `.test_param_mismatch_with_asterisks()` method<br>
180+
- Apply similar quoting and indentation fixes to the `.test_normal_param_mismatch()` method to prevent parsing errors
181+
(by [chrimaho](https://github.com/chrimaho))
182+
* [`1d8a827`](https://github.com/data-science-extensions/docstring-format-checker/commit/1d8a82756c5c66c7f788e4f0c022035a02184579): Detect asterisk mismatch in docstring parameters<br>
183+
- Update parameter parsing regex to capture names with leading asterisks in `_check_params_section_detailed()` method<br>
184+
- Detect when variadic arguments are documented with asterisks in `_format_missing_extra_error()` method<br>
185+
- Return specific error message advising users to remove asterisks from parameter names in the docstring<br>
186+
- Add `TestParameterMismatch` class to verify asterisk mismatch detection works as expected
187+
(by [chrimaho](https://github.com/chrimaho))
188+
189+
12190
!!! info "v1.8.0"
13191

14192
## **v1.8.0 - Support All Python Function Parameter Types**

0 commit comments

Comments
 (0)