Fix returns

[ternaus]

Summary by Sourcery

Improve docstring parsing and validation with enhanced type checking and error handling

Bug Fixes:

• Fixed issues with handling of nested type annotations
• Corrected type validation for collection types
• Improved handling of Returns section in docstrings

Enhancements:

• Refactored type validation logic to be more robust and precise
• Improved error handling in docstring parsing
• Updated parsing of Returns section to be more strict

Tests:

• Expanded test cases for type validation
• Added more comprehensive tests for docstring parsing edge cases
• Updated test suite to reflect new parsing behavior

[sourcery-ai]

Reviewer's Guide by Sourcery

This pull request refactors tests to use pytest.mark.parametrize, implements checks for incorrect 'Returns' section names and missing return type annotations in the docstring checker tool, improves the parsing and validation of the Returns section in Google-style docstrings, updates ruff pre-commit hook to v0.11.2, and enhances type validation and bracket checking in type annotations.

Sequence diagram for _process_docstring function

sequenceDiagram
    participant Context as DocstringContext
    participant _process_docstring
    participant check_returns_section_name
    participant validate_docstring
    participant parse_google_docstring
    participant check_param_types
    participant check_references

    _process_docstring->>Context: Get context
    _process_docstring->>check_returns_section_name: Check Returns section name
    check_returns_section_name-->>_process_docstring: Return errors
    _process_docstring->>validate_docstring: Validate docstring
    validate_docstring-->>_process_docstring: Return errors
    _process_docstring->>parse_google_docstring: Parse docstring
    parse_google_docstring-->>_process_docstring: Return parsed docstring
    alt context.require_param_types
        _process_docstring->>check_param_types: Check parameter types
        check_param_types-->>_process_docstring: Return errors
    end
    alt context.check_references
        _process_docstring->>check_references: Check references
        check_references-->>_process_docstring: Return errors
    end

Loading

Updated class diagram for DocstringContext

classDiagram
    class DocstringContext {
        file_path: Path
        verbose: bool
        require_param_types: bool
        check_references: bool
    }
    note for DocstringContext "A named tuple containing docstring processing context"

Loading

File-Level Changes

Change	Details	Files
Refactor tests to use pytest.mark.parametrize to reduce code duplication and improve readability.	Replace individual test functions with parameterized tests for invalid nested types. Replace individual test functions with parameterized tests for mixed valid and invalid types. Replace individual test functions with parameterized tests for case sensitivity. Add parameterized tests for string literal handling. Add parameterized tests for union type handling.	tests/test_type_validation_edge_cases.py
Implement checks for incorrect 'Returns' section names and missing return type annotations in the docstring checker tool.	Add check_returns_section_name function to identify incorrect 'Returns' section names. Add check_returns_type function to identify missing return type annotations. Integrate the new checks into the _process_docstring function. Update _process_docstring to validate docstring format. Update _process_docstring to parse docstring and check returns type. Update _process_docstring to run additional validations on parsed docstring.	tools/check_docstrings.py
Improve the parsing and validation of the Returns section in Google-style docstrings.	Update _process_returns_section to correctly extract return type and description. Update _process_returns_section to handle missing return type or description. Update _process_returns_section to return a dictionary instead of a list. Remove bare collection check from _process_args_section. Remove bare collection check from _process_returns_section.	google_docstring_parser/google_docstring_parser.py
Update ruff pre-commit hook to v0.11.2.	Update ruff pre-commit hook to v0.11.2.	.pre-commit-config.yaml
Enhance type validation and bracket checking in type annotations.	Add more test cases for invalid nested bare collections. Remove special cases for test examples in _validate_type_declaration.	tests/test_brackets_validation.py google_docstring_parser/type_validation.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!
• Generate a plan of action for an issue: Comment @sourcery-ai plan on
  an issue to generate a plan of action for it.

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[Copilot]

Pull Request Overview

This PR fixes returns handling in docstrings and enhances type annotations and docstring validations across various modules. Key changes include updated and more descriptive return type annotations in functions and classes, refactored docstring processing functions, and improvements to related tests and configuration files.

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tools/check_docstrings.py	Updated function docstrings and refactored returns and validations.
tools/init.py	Minor changes to module docstrings.
tests/test_type_validation_edge_cases.py	Adjusted parameterizations for testing invalid and mixed types.
tests/test_parser.py	Updated expected return structures in parsing tests.
tests/test_docstring_checker/*.py	Refined expected docstring outputs and type hints in test cases.
tests/test_brackets_validation.py	Expanded tests for bare collection detection.
google_docstring_parser/type_validation.py	Added return annotations in error constructors and helper functions.
google_docstring_parser/google_docstring_parser.py	Updated returns section processing and overall docstring parsing logic.
google_docstring_parser/init.py	Minimal docstring updates.
README.md	Updated example content to reflect new returns information.
.pre-commit-config.yaml	Upgraded ruff version.

Comments suppressed due to low confidence (1)

README.md:83

• There is an extra double quote in the 'Returns' key which makes the syntax invalid. Please remove the extra quote so the key is formatted correctly as 'Returns':.

    'Returns':"

[sourcery-ai]

Hey @ternaus - I've reviewed your changes - here's some feedback:

Overall Comments:

• The changes look good overall, but consider adding a brief explanation of the changes in the description.
• The use of parametrize is great for these tests, but consider renaming test_invalid_case_sensitivity to test_case_sensitivity_invalid and test_valid_case_sensitivity to test_case_sensitivity_valid for clarity.

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟡 Complexity: 1 issue found
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}