feat(check-docstrings): short description up to blank line, add max l… - #20
Merged
Merged
Conversation
…ength - Short description = first paragraph (up to first blank line), not first line - Multi-line first paragraph joined with spaces for meta description use - Add max_short_description_length (0 to disable, 160 recommended for SEO) - Add _extract_short_description helper, extensive parametrized tests - Update README, tools/README, google-docstring-format and python-pre-commit skills - Bump version to 0.0.11 Made-with: Cursor
Reviewer's GuideImplements configurable short-description handling for docstring checking: short description is now defined as the first paragraph (up to a blank line), supports an optional maximum length, wires both min/max length through CLI, config, and core checking pipeline, and updates documentation, skills, and tests accordingly. Sequence diagram for docstring short description length validationsequenceDiagram
actor User
participant CLI as check_docstrings_CLI
participant Main as main
participant Cfg as _get_config_values
participant Paths as _process_paths
participant Scan as scan_directory
participant File as check_file
participant Proc as _process_docstring
participant AddVal as _check_additional_validations
participant LenChk as check_short_description_length
participant Extract as _extract_short_description
User->>CLI: Invoke with paths and options
CLI->>Main: Parse args with argparse
Main->>Cfg: _get_config_values(args, config)
Cfg-->>Main: paths, flags, min_short_description_length, max_short_description_length
Main->>Paths: _process_paths(paths, flags, min_short_description_length, max_short_description_length)
alt Path is directory
Paths->>Scan: scan_directory(path, flags, min_short_description_length, max_short_description_length)
Scan->>File: check_file(file, flags, min_short_description_length, max_short_description_length)
else Path is single file
Paths->>File: check_file(path, flags, min_short_description_length, max_short_description_length)
end
loop For each docstring in file
File->>Proc: _process_docstring(DocstringContext(...))
Proc->>AddVal: _check_additional_validations(context, parsed_docstring)
alt Min or max short description length enabled
AddVal->>LenChk: check_short_description_length(parsed_docstring,
AddVal->>LenChk: min_short_description_length,
AddVal->>LenChk: max_short_description_length)
LenChk->>Extract: _extract_short_description(description)
Extract-->>LenChk: short_desc
LenChk-->>AddVal: errors for too short or too long
AddVal-->>Proc: errors
else No short description length checks
AddVal-->>Proc: no length errors
end
end
Paths-->>Main: Aggregate all_errors
Main-->>User: Print errors and exit status
Class diagram for DocstringContext and short description helpersclassDiagram
class DocstringContext {
+str filepath
+str name
+bool require_param_types
+bool check_references
+bool check_type_consistency
+int min_short_description_length
+int max_short_description_length
+ast_AST node
}
class main {
+main() void
}
class _get_config_values {
+_get_config_values(args, config) tuple
}
class _process_paths {
+_process_paths(paths, require_param_types, check_references, check_type_consistency, min_short_description_length, max_short_description_length) list~str~
}
class scan_directory {
+scan_directory(directory, require_param_types, check_references, check_type_consistency, min_short_description_length, max_short_description_length) list~str~
}
class check_file {
+check_file(filepath, require_param_types, check_references, check_type_consistency, min_short_description_length, max_short_description_length) list~str~
}
class _process_docstring {
+_process_docstring(context, docstring) list~str~
}
class _check_additional_validations {
+_check_additional_validations(context, parsed) list~str~
}
class check_short_description_length {
+check_short_description_length(parsed, min_length, max_length) list~str~
}
class _extract_short_description {
+_extract_short_description(description) str
}
main --> _get_config_values : calls
main --> _process_paths : calls
_get_config_values ..> DocstringContext : provides config values
_process_paths --> scan_directory : calls
_process_paths --> check_file : calls
scan_directory --> check_file : calls
check_file ..> DocstringContext : constructs
check_file --> _process_docstring : calls
_process_docstring --> _check_additional_validations : calls
_check_additional_validations --> check_short_description_length : calls
check_short_description_length --> _extract_short_description : calls
Flow diagram for resolving min and max short description length configurationflowchart TD
A[Start] --> B[Read pyproject config for docstring_checker]
B --> C[Parse CLI args with argparse]
C --> D[Set min_short_description_length = config.min_short_description_length or 0]
D --> E{CLI provides --min-short-description-length?}
E -- Yes --> F[Override min_short_description_length with CLI value]
E -- No --> G[Keep config-derived min_short_description_length]
C --> H[Set max_short_description_length = config.max_short_description_length or 0]
H --> I{CLI provides --max-short-description-length?}
I -- Yes --> J[Override max_short_description_length with CLI value]
I -- No --> K[Keep config-derived max_short_description_length]
F --> L[Return min_short_description_length]
G --> L
J --> M[Return max_short_description_length]
K --> M
L --> N[Pass min_short_description_length into _process_paths]
M --> N
N --> O[Propagate min and max lengths into scan_directory and check_file]
O --> P[Create DocstringContext with min and max lengths]
P --> Q[_check_additional_validations uses lengths in check_short_description_length]
Q --> R[End]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- In
test_check_short_description_length, theisinstance(parsed, str)branch and accompanying comment appear unused now that all parametrizedparsedvalues are dicts; consider removing this dead code for clarity. - In
_extract_short_description, consider documenting the behavior for leading/trailing blank lines (e.g., that leading blank lines are stripped before paragraph detection) directly in the docstring to make the regex-based splitting easier to understand for future maintainers.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In `test_check_short_description_length`, the `isinstance(parsed, str)` branch and accompanying comment appear unused now that all parametrized `parsed` values are dicts; consider removing this dead code for clarity.
- In `_extract_short_description`, consider documenting the behavior for leading/trailing blank lines (e.g., that leading blank lines are stripped before paragraph detection) directly in the docstring to make the regex-based splitting easier to understand for future maintainers.
## Individual Comments
### Comment 1
<location path="tests/test_docstring_checker/test_check_docstrings.py" line_range="671" />
<code_context>
+ 0,
+ [],
+ ),
+ # Max length
+ (
+ {"Description": "A" * 161},
</code_context>
<issue_to_address>
**suggestion (testing):** Consider adding a max-length test case where the first paragraph is multi-line and joined with spaces
The current max-length tests only cover a single-line description of repeated "A" characters, so they don’t verify how `_extract_short_description` handles multi-line first paragraphs. To cover the new behavior, consider adding a case where the first paragraph spans multiple lines and is joined with spaces before the length check, e.g.:
```python
(
{"Description": "Line one with some text.\nAnd another line that pushes length over max.\n\nNext paragraph."},
0,
80,
["Short description too long ..."],
),
```
Suggested implementation:
```python
# First paragraph = up to blank line (multi-line)
(
{"Description": "First line. More.\nSecond line of para.\n\nSecond para."},
0,
0,
[],
),
# Max length with multi-line first paragraph (joined with spaces)
(
{
"Description": (
"Line one with some text.\n"
"And another line that pushes length over max.\n\n"
"Next paragraph."
)
},
0,
80,
[
"Short description too long (93 chars, max 80): "
"'Line one with some text. And another line that pushes length over max.'"
],
),
# Max length (single-line)
(
{"Description": "A" * 161},
0,
160,
["Short description too long (161 chars, max 160): 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA...'"],
),
```
Depending on the exact implementation of `_extract_short_description` and the error formatting logic, you may need to:
1. Adjust the expected length value `93` if your join/strip logic counts characters differently (e.g., handling of trailing spaces).
2. Update the expected preview string if your error message truncates the description differently (for example, limiting to a fixed prefix length and appending `...`).
3. If your checker normalizes whitespace more aggressively (e.g. collapsing multiple spaces or stripping punctuation), mirror that behavior in the expected string so the test aligns with the actual output.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
There was a problem hiding this comment.
Pull request overview
This PR updates the docstring checker to treat the “short description” as the first paragraph (up to the first blank line), normalizes multi-line paragraphs into a single line for meta-description use, and adds an optional maximum-length constraint.
Changes:
- Add
_extract_short_description()and update short-description length validation to support both min and max bounds. - Wire
max_short_description_lengththrough config, CLI, runtime context, and verbose output. - Add/extend parametrized and integration tests; update documentation and bump version to 0.0.11.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| tools/check_docstrings.py | Implements paragraph-based short description extraction and adds max length enforcement + CLI/config plumbing. |
| tests/test_docstring_checker/test_check_docstrings.py | Adds unit tests for extraction/length checks and integration coverage for CLI behavior. |
| tools/README.md | Documents new short-description semantics and max_short_description_length option. |
| README.md | Adds user-facing explanation of short description usage for meta descriptions and config knobs. |
| pyproject.toml | Bumps project version to 0.0.11. |
| .cursor/skills/python-pre-commit/SKILL.md | Notes docstring checker config now includes min/max short description length. |
| .cursor/skills/google-docstring-format/SKILL.md | Documents short-description guidance and references new error cases. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…add multi-line max test - Remove unused isinstance(parsed, str) branch in test_check_short_description_length - Document leading/trailing blank line behavior in _extract_short_description - Add max-length test for multi-line first paragraph (joined with spaces) Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
Updates the docstring checker to treat the “short description” as the first paragraph (up to the first blank line), and adds an optional maximum length constraint to complement the existing minimum-length check.
Changes:
- Implement
_extract_short_description()(first paragraph extraction + whitespace normalization) and update length validation to support both min/max bounds. - Thread
max_short_description_lengththrough config defaults, CLI flags, and the checker pipeline (file/directory scanning + verbose config output). - Expand unit + integration tests and update documentation/examples; bump package version to
0.0.11.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| tools/check_docstrings.py | Adds paragraph-based short description extraction and min/max length checks; wires new config/CLI through execution flow. |
| tests/test_docstring_checker/test_check_docstrings.py | Adds focused unit tests for extraction plus min/max validation and end-to-end CLI integration coverage. |
| tools/README.md | Documents new short description semantics and max_short_description_length config/CLI usage. |
| README.md | Adds a dedicated “Short Description” section and updates example configuration to include min/max bounds. |
| pyproject.toml | Bumps project version to 0.0.11. |
| .cursor/skills/python-pre-commit/SKILL.md | Notes docstring checker supports min/max short description config. |
| .cursor/skills/google-docstring-format/SKILL.md | Documents short description paragraph rule and the min/max length knobs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
…ength
Made-with: Cursor
Summary by Sourcery
Introduce configurable short description extraction and length validation for docstring checking.
New Features:
Enhancements:
Build: