Add cursor skills#19
Merged
Merged
Conversation
- google-docstring-format: project docstring rules and check-docstrings fixes - pytest-parametrize: test layout and parametrize patterns - python-pre-commit: hook config, run workflow, debugging - pypi-release: version bump and release workflow Made-with: Cursor
- Use astral-sh/setup-uv@v7 with enable-cache and activate-environment - Remove manual pip cache and Install uv steps - Simplify install: uv pip install wheel . -r requirements-dev.txt Made-with: Cursor
Pre-commit now fails when docstring short descriptions are below a configurable minimum (default 50 chars). Addresses Bing SEO feedback about meta descriptions derived from docstrings. Configurable via pyproject.toml or --min-short-description-length. Set to 0 to disable. Made-with: Cursor
Compare docstring types (Args, Returns) with Python function annotations. When they mismatch, report an error. Uses Python 3.10+ typing (list, dict, tuple, X|Y) - no List, Dict, Tuple, Union normalization. - Add check_type_consistency() with _annotation_to_str, _normalize_type - Wire config (pyproject.toml), CLI (--check-type-consistency, --no-check-type-consistency) - Pass AST node through pipeline for annotation extraction - Skip ClassDef, self/cls; skip when annotation missing in source - Add tests (param match/mismatch, return mismatch, missing annotation, self) - Update tools/README.md and README.md - Fix test_valid_docstrings to use Python 3.10+ typing Made-with: Cursor
- Add rule to python-pre-commit skill: do not disable refactor-forcing checks - Remove C901 from tools/*.py per-file-ignores - Extract _CONFIG_KEYS and _apply_tool_config to reduce load_pyproject_config complexity Made-with: Cursor
Reviewer's GuideExtends the custom docstring checker with type-consistency and short-description-length validations, wires them through CLI/config and tests, refreshes documentation and examples accordingly, adds Cursor skills docs, modernizes valid test docstrings to Python 3.10+ typing, bumps the package version, and updates CI to use uv with a wider Python matrix. Sequence diagram for CLI docstring check with new validationssequenceDiagram
actor Developer
participant CLI as main
participant Config as load_pyproject_config
participant Args as _parse_args
participant MergeCfg 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 Extra as _check_additional_validations
participant TypeCons as check_type_consistency
participant ShortDesc as check_short_description_length
Developer->>CLI: python -m tools.check_docstrings
CLI->>Config: load_pyproject_config()
Config-->>CLI: config dict
CLI->>Args: _parse_args()
Args-->>CLI: argparse.Namespace
CLI->>MergeCfg: _get_config_values(args, config)
MergeCfg-->>CLI: paths, flags, min_short_description_length
CLI->>Paths: _process_paths(paths, exclude_files, require_param_types, verbose, check_references, check_type_consistency, min_short_description_length)
alt path_is_directory
Paths->>Scan: scan_directory(path, exclude_files, require_param_types, verbose, check_references, check_type_consistency, min_short_description_length)
Scan->>File: check_file(py_file, require_param_types, verbose, check_references, check_type_consistency, min_short_description_length)
else path_is_file
Paths->>File: check_file(file_path, require_param_types, verbose, check_references, check_type_consistency, min_short_description_length)
end
loop for each docstring
File->>Proc: _process_docstring(DocstringContext)
Proc->>Extra: _check_additional_validations(context, parsed)
alt short_description_check_enabled
Extra->>ShortDesc: check_short_description_length(parsed, min_short_description_length)
ShortDesc-->>Extra: length_errors
end
alt type_consistency_enabled
Extra->>TypeCons: check_type_consistency(parsed, node)
TypeCons-->>Extra: consistency_errors
end
Extra-->>Proc: collected_errors
Proc-->>File: errors
end
File-->>Paths: file_errors
Paths-->>CLI: all_errors
CLI-->>Developer: print errors and exit code
Class diagram for updated docstring checker componentsclassDiagram
class DocstringContext {
Path file_path
int line_no
str name
bool verbose
bool require_param_types
bool check_references
bool check_type_consistency
int min_short_description_length
ast.AST node
}
class CheckDocstringsModule {
dict DEFAULT_CONFIG
dict _CONFIG_KEYS
load_pyproject_config() dict
_apply_tool_config(config, tool_config) void
get_docstrings(file_path) list
check_param_types(docstring_dict, require_types) list
check_references(docstring_dict) list
check_returns_type(docstring_dict) list
check_short_description_length(parsed, min_length) list
check_type_consistency(parsed, node) list
validate_docstring(docstring) list
check_returns_section_name(docstring) list
_format_error(context, error) str
safe_execute(context, func, arg1, arg2, arg3, error_prefix) tuple
_check_returns_section(context, docstring) list
_validate_docstring_format(context, docstring) list
_parse_and_check_returns(context, docstring) tuple
_check_additional_validations(context, parsed) list
_process_docstring(context, docstring) list
check_file(file_path, require_param_types, verbose, check_references, check_type_consistency, min_short_description_length) list
scan_directory(path, exclude_files, require_param_types, verbose, check_references, check_type_consistency, min_short_description_length) list
_parse_args() argparse.Namespace
_get_config_values(args, config) tuple
_process_paths(paths, exclude_files, require_param_types, verbose, check_references, check_type_consistency, min_short_description_length) list
main() void
}
class TypeConsistencyHelpers {
_normalize_type(type_str) str
_annotation_to_str(annotation) str
check_type_consistency(parsed, node) list
}
class ShortDescriptionHelpers {
check_short_description_length(parsed, min_length) list
}
DocstringContext <.. CheckDocstringsModule : used_by
TypeConsistencyHelpers <.. CheckDocstringsModule : used_by
ShortDescriptionHelpers <.. CheckDocstringsModule : used_by
TypeConsistencyHelpers ..> ast.FunctionDef : uses
TypeConsistencyHelpers ..> ast.AsyncFunctionDef : uses
CheckDocstringsModule ..> DocstringContext : constructs
CheckDocstringsModule ..> TypeConsistencyHelpers : calls
CheckDocstringsModule ..> ShortDescriptionHelpers : calls
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:
- The
--check-type-consistencyand--no-check-type-consistencyflags are both allowed simultaneously; consider putting them in a mutually exclusive argparse group so users can’t accidentally pass conflicting options. - The configuration keys are now split between
DEFAULT_CONFIGand_CONFIG_KEYS; consider adding a small guard (e.g., a test or assertion) to ensure these stay in sync when new options are added or renamed. - In
check_short_description_length, the preview length is hard-coded to 50; you might want to derive this frommin_length(or make it a named constant) so behavior is easier to adjust and reason about.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The `--check-type-consistency` and `--no-check-type-consistency` flags are both allowed simultaneously; consider putting them in a mutually exclusive argparse group so users can’t accidentally pass conflicting options.
- The configuration keys are now split between `DEFAULT_CONFIG` and `_CONFIG_KEYS`; consider adding a small guard (e.g., a test or assertion) to ensure these stay in sync when new options are added or renamed.
- In `check_short_description_length`, the preview length is hard-coded to 50; you might want to derive this from `min_length` (or make it a named constant) so behavior is easier to adjust and reason about.
## Individual Comments
### Comment 1
<location path="tools/check_docstrings.py" line_range="210-216" />
<code_context>
+ return ast.unparse(annotation)
+
+
+def check_type_consistency(
+ parsed: dict[str, Any],
+ node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[str]:
+ """Compare docstring types with function annotations.
+
+ Args:
+ parsed (dict[str, Any]): Parsed docstring dictionary
+ node (ast.FunctionDef | ast.AsyncFunctionDef): Function AST node
+
+ Returns:
+ list[str]: List of error messages for type mismatches
+ """
+ errors = []
+
+ # Build param dict from AST (skip self/cls)
+ ast_params: dict[str, str] = {}
+ for arg in node.args.args:
+ if arg.arg in ("self", "cls"):
+ continue
</code_context>
<issue_to_address>
**suggestion:** Type consistency check ignores pos-only, varargs, and kw-only parameters.
Because it only iterates over `node.args.args`, this logic ignores `posonlyargs`, `kwonlyargs`, `vararg` (`*args`), and `kwarg` (`**kwargs`), so type mismatches for those parameters won’t be reported. Please extend `ast_params` to also include annotations from these fields so all user-visible parameters are validated.
```suggestion
# Build param dict from AST (skip self/cls)
ast_params: dict[str, str] = {}
# Collect all user-visible parameters:
# - posonlyargs: positional-only params (Python 3.8+)
# - args: regular positional-or-keyword params
# - kwonlyargs: keyword-only params
# - vararg: *args
# - kwarg: **kwargs
all_args: list[ast.arg] = []
all_args.extend(node.args.posonlyargs)
all_args.extend(node.args.args)
all_args.extend(node.args.kwonlyargs)
if node.args.vararg is not None:
all_args.append(node.args.vararg)
if node.args.kwarg is not None:
all_args.append(node.args.kwarg)
for arg in all_args:
if arg.arg in ("self", "cls"):
continue
if ann_str := _annotation_to_str(arg.annotation):
ast_params[arg.arg] = ann_str
```
</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 extends the repo’s docstring-checking tooling by adding new validation capabilities (type-consistency vs annotations, and minimum short-description length), updates documentation and test fixtures accordingly, and modernizes CI to use uv.
Changes:
- Add
check_type_consistencyandmin_short_description_lengthconfiguration/CLI support totools/check_docstrings.py. - Add tests and update test fixtures to align with the new validation behavior.
- Update docs and CI (switch to
astral-sh/setup-uv, broaden Python matrix).
Reviewed changes
Copilot reviewed 14 out of 15 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/README.md | Documents new checker capabilities (but currently missing/incorrect details noted in comments). |
| tools/check_docstrings.py | Implements type-consistency checks, short-description-length validation, and config plumbing. |
| tests/test_docstring_checker/test_valid_docstrings.py | Updates fixture docstrings/annotations to match new typing expectations. |
| tests/test_docstring_checker/test_example_files.py | Updates tests to disable short-description-length checks where needed. |
| tests/test_docstring_checker/test_check_docstrings.py | Adds unit tests for short-description-length and type-consistency behavior. |
| README.md | Updates user-facing config example for type consistency (min length still undocumented). |
| pyproject.toml | Bumps version and enables the new checker settings in project config. |
| google_docstring_parser/type_validation.py | Docstring wording updates (no functional change). |
| google_docstring_parser/google_docstring_parser.py | Docstring wording updates (no functional change). |
| .gitignore | Ignores uv.lock. |
| .github/workflows/ci.yml | Switches CI install flow to uv and expands Python versions. |
| .cursor/skills/* | Adds project-specific skill docs for Cursor. |
Comments suppressed due to low confidence (1)
tools/README.md:55
- The new
min_short_description_lengthoption is implemented (and has a CLI flag), but it isn’t documented in this tools README (config snippet, feature list, or command-line options). Please document the setting and its default/disable behavior (0disables) so users can discover and configure it.
# Whether to compare docstring types with function annotations
check_type_consistency = true
# List of filenames to exclude from checks
# These can be just filenames (e.g., "conftest.py") or paths ending with the filename
exclude_files = ["conftest.py", "__init__.py", "tests/fixtures/bad_docstrings.py"]
# Whether to enable verbose output
verbose = false
</details>
---
💡 <a href="/ternaus/google-docstring-parser/new/main?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.
Comment on lines
26
to
30
| "require_param_types": False, | ||
| "check_references": True, | ||
| "check_type_consistency": False, | ||
| "min_short_description_length": 50, | ||
| "exclude_files": [], |
| check_references = true # Check references for proper format | ||
| check_type_consistency = true # Compare docstring types with annotations | ||
| exclude_files = ["conftest.py", "__init__.py"] # Files to exclude from checks | ||
| verbose = false # Enable verbose output |
- Add mutually exclusive argparse groups for --check/--no-check flags - Add _config_keys_match guard and test for DEFAULT_CONFIG/_CONFIG_KEYS sync - Use SHORT_DESC_PREVIEW_LENGTH constant for preview length - Extend type consistency to pos-only, kw-only, varargs, kwargs params - Use macos-latest in CI matrix Made-with: Cursor
- Default min_short_description_length to 0 for backward compatibility - Handle Returns string 'None' in type consistency check - Update type consistency docs to use list[str], dict[str, Any], etc - Document min_short_description_length in README and tools/README Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
This PR enhances the repository’s docstring-checking tooling by adding (1) docstring ↔ annotation type consistency validation and (2) configurable minimum short-description length checks, along with documentation, tests, and CI updates to support the new behavior.
Changes:
- Add
check_type_consistencyandmin_short_description_lengthoptions totools.check_docstrings(CLI + pyproject config) and wire them into validation. - Expand test suite to cover new configuration invariants and validations.
- Update docs/config, bump package version, and modernize CI to use
uv.
Reviewed changes
Copilot reviewed 14 out of 15 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/README.md | Documents new config keys and CLI flags for the docstring checker. |
| tools/check_docstrings.py | Implements type consistency + short-description-length checks; refactors config loading and CLI parsing. |
| tests/test_docstring_checker/test_valid_docstrings.py | Updates test fixtures to use PEP 585 built-in generics for type-consistency alignment. |
| tests/test_docstring_checker/test_example_files.py | Updates calls to check_file to include the new parameter. |
| tests/test_docstring_checker/test_check_docstrings.py | Adds tests for config key sync, new flags, short-description checking, and type-consistency behavior. |
| README.md | Updates user-facing example config to include new options. |
| pyproject.toml | Bumps version and adds new docstring-checker config; adjusts ruff ignores for updated tool signature. |
| google_docstring_parser/type_validation.py | Docstring wording-only clarifications. |
| google_docstring_parser/google_docstring_parser.py | Docstring wording-only clarifications. |
| .gitignore | Adds uv.lock. |
| .github/workflows/ci.yml | Switches CI to astral-sh/setup-uv and expands Python version matrix. |
| .cursor/skills/*/SKILL.md | Adds project workflow “skills” documentation for tooling/tests. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+172
to
+176
| def _normalize_type(type_str: str) -> str: | ||
| """Normalize type string for comparison (whitespace and quotes only). | ||
|
|
||
| Python 3.10+ typing uses list, dict, tuple, X|Y - no List, Dict, Tuple, Union. | ||
| We do not normalize those; mismatches will be reported. |
- Normalize internal whitespace in type comparison (tuple[int, str] vs tuple[int,str]) - Fix _get_config_values docstring return tuple order - Use min_short_description_length=10 in README example - Add test for whitespace normalization Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
This PR enhances the repository’s docstring-checking tooling by adding stricter, configurable validations (type consistency vs annotations and minimum short description length), updates documentation/tests accordingly, and refreshes CI/release metadata to align with the updated tooling.
Changes:
- Add
check_type_consistencyandmin_short_description_lengthoptions totools/check_docstrings.py, including CLI flags and pyproject config loading refactor. - Expand/adjust test coverage and example fixtures to validate the new checker behaviors.
- Update docs and project/CI metadata (version bump, CI moves to
uv, config docs).
Reviewed changes
Copilot reviewed 14 out of 15 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/README.md | Documents new docstring checker configuration and CLI flags. |
| tools/check_docstrings.py | Implements type-consistency checks, short-description length checks, and config loading refactor. |
| tests/test_docstring_checker/test_valid_docstrings.py | Updates fixture types to modern dict[str, Any] / list[Any] style to align with consistency rules. |
| tests/test_docstring_checker/test_example_files.py | Updates calls to check_file/scan_directory to pass the new option explicitly. |
| tests/test_docstring_checker/test_check_docstrings.py | Adds tests for config key sync, new CLI flag exclusivity, short-description validation, and type-consistency behavior. |
| README.md | Updates example [tool.docstring_checker] config with the new options. |
| pyproject.toml | Bumps version, adds ruff ignore for tools, and enables new checker config (incl. min_short_description_length). |
| google_docstring_parser/type_validation.py | Docstring wording improvements only. |
| google_docstring_parser/google_docstring_parser.py | Docstring wording improvements only. |
| .gitignore | Adds uv.lock to ignored files. |
| .github/workflows/ci.yml | Switches Python setup/install to uv and updates the test matrix. |
| .cursor/skills/python-pre-commit/SKILL.md | Adds repo-specific guidance for using pre-commit. |
| .cursor/skills/pytest-parametrize/SKILL.md | Adds repo-specific guidance for pytest parametrization. |
| .cursor/skills/pypi-release/SKILL.md | Adds repo-specific guidance for PyPI release workflow. |
| .cursor/skills/google-docstring-format/SKILL.md | Adds repo-specific docstring formatting guidance reflecting checker expectations. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+751
to
+756
| check_file( | ||
| py_file, | ||
| require_param_types, | ||
| verbose, | ||
| check_references, | ||
| check_type_consistency, |
|
|
||
| short_desc = (parsed.get("Description") or "").split("\n")[0].strip() | ||
| if not short_desc: | ||
| return [] |
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.
Summary by Sourcery
Enhance the custom docstring checker with stricter validation options, expand tests and documentation to cover the new behavior, modernize example code, update CI and project metadata, and add editor skills files for working with this project.
New Features:
Enhancements:
Build:
CI:
Documentation:
Tests:
Chores: