Skip to content

Commit 6beea68

Browse files
github-actions[bot]github-actions[bot]
committed
Update changelog to v1.8.0 [skip ci]
1 parent e64dd32 commit 6beea68

1 file changed

Lines changed: 149 additions & 1 deletion

File tree

‎CHANGELOG.md‎

Lines changed: 149 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,157 @@
99
.md-nav--secondary .md-nav__list .md-nav__list { display: none; }
1010
</style>
1111

12+
!!! info "v1.8.0"
13+
14+
## **v1.8.0 - Support All Python Function Parameter Types**
15+
16+
<!-- md:tag v1.8.0 --><br>
17+
<!-- md:date 2025-12-20 --><br>
18+
<!-- md:link [data-science-extensions/docstring-format-checker/releases/v1.8.0](https://github.com/data-science-extensions/docstring-format-checker/releases/tag/v1.8.0) -->
19+
20+
??? note "Release Notes"
21+
22+
### Summary
23+
24+
This release introduces comprehensive support for all Python function parameter types, ensuring accurate docstring validation for complex function signatures. It adds recognition for positional-only parameters (before `/`), keyword-only parameters (after `*`), variable positional arguments (`*args`), and variable keyword arguments (`**kwargs`). Additionally, this release fixes default value detection for positional-only arguments and updates the package configuration. These enhancements ensure that the docstring format checker correctly identifies and validates parameters across all modern Python function definitions.
25+
26+
27+
### Release Statistics
28+
29+
| Attribute | Note |
30+
| ------------------------- | --------------------------------------------- |
31+
| **Version:** | [`v1.8.0`] |
32+
| **Python Support:** | `3.9`, `3.10`, `3.11`, `3.12`, `3.13`, `3.14` |
33+
| **Test Coverage:** | 100% (1022 statements, +23 from v1.7.0) |
34+
| **Pylint Score:** | 10.00/10 |
35+
| **Complexity:** | All functions ≤13 threshold |
36+
| **Functions:** | 106 (-3 from v1.7.0) |
37+
| **Tests Passing:** | 248/248 (+7 from v1.7.0) |
38+
| **Files Changed:** | 3 |
39+
| **Lines Added:** | 2520 |
40+
| **Lines Removed:** | 2168 |
41+
| **Commits:** | 4 |
42+
| **Pull Requests Merged:** | 1 (PR #26) |
43+
44+
45+
### 🎯 Enhance Parameter Extraction
46+
47+
48+
#### Overview
49+
50+
Introduce comprehensive parameter extraction logic to support all five Python parameter types: positional-only, positional-or-keyword, variable positional, keyword-only, and variable keyword arguments. This ensures that the docstring format checker correctly identifies and validates parameters in complex function signatures, including those using `/` and `*` separators.
51+
52+
53+
#### Problem Statement
54+
55+
56+
##### Incomplete Parameter Extraction
57+
58+
The docstring format checker previously only extracted standard positional parameters (`args.args`) from function signatures. It failed to recognise:
59+
60+
1. **Positional-Only Parameters** (before `/`): Parameters that must be passed by position.
61+
2. **Keyword-Only Parameters** (after `*`): Parameters that must be passed by name.
62+
3. **Variable Positional Arguments** (`*args`): Arbitrary positional arguments.
63+
4. **Variable Keyword Arguments** (`**kwargs`): Arbitrary keyword arguments.
64+
65+
This limitation caused validation errors or false positives when checking functions that utilised these modern Python features.
66+
67+
**Real-World Example:**
68+
69+
Consider this function using keyword-only parameters:
70+
71+
```python
72+
@overload
73+
def print_or_log_output(message: str, print_or_log: Literal["print"]) -> None: ...
74+
@overload
75+
def print_or_log_output(
76+
message: str,
77+
print_or_log: Literal["log"],
78+
*,
79+
log: Logger,
80+
log_level: log_levels = "info",
81+
) -> None: ...
82+
def print_or_log_output(
83+
message: str,
84+
print_or_log: Literal["print", "log"] = "print",
85+
*,
86+
log: Optional[Logger] = None,
87+
log_level: log_levels = "info",
88+
) -> None:
89+
"""
90+
Print or log the output.
91+
92+
Params:
93+
message (str): The message to print or log.
94+
print_or_log (Literal["print", "log"]): The action to perform.
95+
log (Optional[Logger]): The logger to use.
96+
log_level (log_levels): The log level to use.
97+
"""
98+
...
99+
```
100+
101+
Previously, the checker would fail to find `log` and `log_level` in the function signature, reporting them as undocumented parameters or extra parameters in the docstring.
102+
103+
104+
#### Solution
105+
106+
107+
##### Comprehensive Parameter Extraction
108+
109+
Implement a new `._extract_all_params()` method in the `DocstringChecker` class that iterates through all parameter categories in the AST `arguments` node:
110+
111+
- `posonlyargs`: Positional-only arguments.
112+
- `args`: Positional-or-keyword arguments.
113+
- `vararg`: Variable positional arguments (`*args`).
114+
- `kwonlyargs`: Keyword-only arguments.
115+
- `kwarg`: Variable keyword arguments (`**kwargs`).
116+
117+
118+
##### Enhanced Type Annotation Capture
119+
120+
Update the `._extract_param_types()` method to utilise `._extract_all_params()`, ensuring that type annotations are captured for every parameter found. This allows the validator to correctly match docstring types with signature types for all parameter kinds.
121+
122+
123+
##### Improved Validation Logic
124+
125+
Refactor `._is_params_section_required()` and `._validate_param_types()` to account for the presence of any parameter type, ensuring that docstrings are required and validated whenever any parameters exist in the signature.
126+
127+
128+
### 💪 Pull Requests
129+
130+
* Enhance Parameter Extraction to Support All Python Function Parameter Types by @chrimaho in https://github.com/data-science-extensions/docstring-format-checker/pull/26
131+
132+
133+
**Full Changelog**: https://github.com/data-science-extensions/docstring-format-checker/compare/v1.7.0...v1.8.0
134+
135+
136+
[`v1.7.0`]: https://github.com/data-science-extensions/docstring-format-checker/releases/tag/v1.7.0
137+
[`v1.8.0`]: https://github.com/data-science-extensions/docstring-format-checker/releases/tag/v1.8.0
138+
139+
140+
??? abstract "Updates"
141+
142+
* [`4b38e17`](https://github.com/data-science-extensions/docstring-format-checker/commit/4b38e176e6355674bd8d01047a732222f1185842): Update package config
143+
(by [chrimaho](https://github.com/chrimaho))
144+
* [`795bb4d`](https://github.com/data-science-extensions/docstring-format-checker/commit/795bb4dd33ed927fe658e0e48d5102f6ff3b6b80): Fix duplicated unit test
145+
(by [chrimaho](https://github.com/chrimaho))
146+
* [`eea2ba2`](https://github.com/data-science-extensions/docstring-format-checker/commit/eea2ba2e7d5ccf04987c142126fba11f70bae7da): Fix default value detection for positional-only arguments<br>
147+
- Update `._get_params_with_defaults()` method in `DocstringChecker` class to correctly handle defaults for combined positional-only and regular arguments<br>
148+
- Ensure positional-only parameters are recognised as having defaults when iterating over the AST<br>
149+
- Add `.test_posonly_args_with_defaults()` method and `.test_mixed_args_with_defaults()` method to verify the fix<br>
150+
- Reorganise existing test methods in `src/tests/test_core.py` file to group default value tests
151+
(by [chrimaho](https://github.com/chrimaho))
152+
* [`85a49f1`](https://github.com/data-science-extensions/docstring-format-checker/commit/85a49f17fd5808e14ff213ba1cca628a5f99aca3): Support comprehensive parameter validation for all argument types (args, kwargs, kwonlyargs, posonlyargs, vararg)<br>
153+
- Introduce `._extract_all_params()` method to gather positional-only, keyword-only, and variable arguments from the AST<br>
154+
- Update `._extract_param_types()` method to capture type annotations from all argument categories using the new `._add_arg_types_to_dict()` method<br>
155+
- Ensure `._is_params_section_required()` method correctly identifies requirements for complex function signatures<br>
156+
- Fix validation logic to recognise parameters defined after `*` or before `/` in the `DocstringChecker` class
157+
(by [chrimaho](https://github.com/chrimaho))
158+
159+
12160
!!! info "v1.7.0"
13161

14-
## **# v1.7.0 - Add Configurable Optional Suffix Validation**
162+
## **v1.7.0 - Add Configurable Optional Suffix Validation**
15163

16164
<!-- md:tag v1.7.0 --><br>
17165
<!-- md:date 2025-12-19 --><br>

0 commit comments

Comments
 (0)