language-servers/ruff
1
0
Fork 0
mirror of https://github.com/astral-sh/ruff.git synced 2025-11-19 11:45:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

[pydocstyle] Handle arguments with the same names as sections (D417) (#16011)

Browse source 
## Summary

Fixes #16007. The logic from the last fix for this (#9427) was
sufficient, it just wasn't being applied because `Attributes` sections
aren't expected to have nested sections. I just deleted the outer
conditional, which should hopefully fix this for all section types.

## Test Plan

New regression test, plus the existing D417 tests.
This commit is contained in:
Brent Westbrook 2025-02-11 12:05:29 -05:00 • committed by GitHub
parent df1d430294
commit 7b487d853a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 150 additions and 77 deletions
Download patch file Download diff file Expand all files Collapse all files

147
crates/ruff_linter/src/docstrings/sections.rs
View file

@ -2,6 +2,7 @@ use std::fmt::{Debug, Formatter};
use std::iter::FusedIterator;
use ruff_python_ast::docstrings::{leading_space, leading_words};
use ruff_python_semantic::Definition;
use ruff_text_size::{Ranged, TextLen, TextRange, TextSize};
use strum_macros::EnumIter;
@ -130,34 +131,6 @@ impl SectionKind {
Self::Yields => "Yields",
}
}
/// Returns `true` if a section can contain subsections, as in:
/// ```python
/// Yields
/// ------
/// int
/// Description of the anonymous integer return value.
/// ```
///
/// For NumPy, see: <https://numpydoc.readthedocs.io/en/latest/format.html>
///
/// For Google, see: <https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings>
pub(crate) fn has_subsections(self) -> bool {
matches!(
self,
Self::Args
| Self::Arguments
| Self::OtherArgs
| Self::OtherParameters
| Self::OtherParams
| Self::Parameters
| Self::Raises
| Self::Returns
| Self::SeeAlso
| Self::Warns
| Self::Yields
)
}
}
pub(crate) struct SectionContexts<'a> {
@ -195,6 +168,7 @@ impl<'a> SectionContexts<'a> {
last.as_ref(),
previous_line.as_ref(),
lines.peek(),
docstring.definition,
) {
if let Some(mut last) = last.take() {
last.range = TextRange::new(last.start(), line.start());
@ -444,6 +418,7 @@ fn suspected_as_section(line: &str, style: SectionStyle) -> Option<SectionKind>
}
/// Check if the suspected context is really a section header.
#[allow(clippy::too_many_arguments)]
fn is_docstring_section(
line: &Line,
indent_size: TextSize,
@ -452,7 +427,9 @@ fn is_docstring_section(
previous_section: Option<&SectionContextData>,
previous_line: Option<&Line>,
next_line: Option<&Line>,
definition: &Definition<'_>,
) -> bool {
// for function definitions, track the known argument names for more accurate section detection.
// Determine whether the current line looks like a section header, e.g., "Args:".
let section_name_suffix = line[usize::from(indent_size + section_name_size)..].trim();
let this_looks_like_a_section_name =
@ -509,60 +486,80 @@ fn is_docstring_section(
// ```
// However, if the header is an _exact_ match (like `Returns:`, as opposed to `returns:`), then
// continue to treat it as a section header.
if section_kind.has_subsections() {
if let Some(previous_section) = previous_section {
let verbatim = &line[TextRange::at(indent_size, section_name_size)];
if let Some(previous_section) = previous_section {
let verbatim = &line[TextRange::at(indent_size, section_name_size)];
// If the section is more deeply indented, assume it's a subsection, as in:
// ```python
// def func(args: tuple[int]):
// """Toggle the gizmo.
//
// Args:
// args: The arguments to the function.
// """
// ```
if previous_section.indent_size < indent_size {
if section_kind.as_str() != verbatim {
return false;
}
// If the section is more deeply indented, assume it's a subsection, as in:
// ```python
// def func(args: tuple[int]):
// """Toggle the gizmo.
//
// Args:
// args: The arguments to the function.
// """
// ```
// As noted above, an exact match for a section name (like the inner `Args:` below) is
// treated as a section header, unless the enclosing `Definition` is a function and contains
// a parameter with the same name, as in:
// ```python
// def func(Args: tuple[int]):
// """Toggle the gizmo.
//
// Args:
// Args: The arguments to the function.
// """
// ```
if previous_section.indent_size < indent_size {
let section_name = section_kind.as_str();
if section_name != verbatim || has_parameter(definition, section_name) {
return false;
}
}
// If the section has a preceding empty line, assume it's _not_ a subsection, as in:
// ```python
// def func(args: tuple[int]):
// """Toggle the gizmo.
//
// Args:
// args: The arguments to the function.
//
// returns:
// The return value of the function.
// """
// ```
if previous_line.is_some_and(|line| line.trim().is_empty()) {
return true;
}
// If the section has a preceding empty line, assume it's _not_ a subsection, as in:
// ```python
// def func(args: tuple[int]):
// """Toggle the gizmo.
//
// Args:
// args: The arguments to the function.
//
// returns:
// The return value of the function.
// """
// ```
if previous_line.is_some_and(|line| line.trim().is_empty()) {
return true;
}
// If the section isn't underlined, and isn't title-cased, assume it's a subsection,
// as in:
// ```python
// def func(parameters: tuple[int]):
// """Toggle the gizmo.
//
// Parameters:
// -----
// parameters:
// The arguments to the function.
// """
// ```
if !next_line_is_underline && verbatim.chars().next().is_some_and(char::is_lowercase) {
if section_kind.as_str() != verbatim {
return false;
}
// If the section isn't underlined, and isn't title-cased, assume it's a subsection,
// as in:
// ```python
// def func(parameters: tuple[int]):
// """Toggle the gizmo.
//
// Parameters:
// -----
// parameters:
// The arguments to the function.
// """
// ```
if !next_line_is_underline && verbatim.chars().next().is_some_and(char::is_lowercase) {
if section_kind.as_str() != verbatim {
return false;
}
}
}
true
}
/// Returns whether or not `definition` is a function definition and contains a parameter with the
/// same name as `section_name`.
fn has_parameter(definition: &Definition, section_name: &str) -> bool {
definition.as_function_def().is_some_and(|func| {
func.parameters
.iter()
.any(|param| param.name() == section_name)
})
}