Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 3 additions & 126 deletions crates/pyrefly_python/src/docstring.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,11 @@
use std::collections::HashMap;

use ruff_python_ast::Expr;
use ruff_python_ast::Parameters;
use ruff_python_ast::Stmt;
use ruff_python_ast::StmtClassDef;
use ruff_python_ast::StmtFunctionDef;
use ruff_python_ast::name::Name;
use ruff_text_size::Ranged;
use ruff_text_size::TextRange;

use crate::ast::Ast;
use crate::dunder;
use crate::module::Module;

const STRING_LITERAL_PATTERNS: [(&str, &str); 8] = [
Expand Down Expand Up @@ -117,30 +112,9 @@ impl DocRanges {
Self(DocRangesRepr::Docstring(docstring))
}

pub fn of_function(x: &StmtFunctionDef) -> Self {
Self::new(Docstring::range_from_stmts(&x.body), &x.parameters)
}

/// A class's parameters are those of its `__init__`.
pub fn of_class(x: &StmtClassDef) -> Self {
let docstring = Docstring::range_from_stmts(&x.body);
match x.body.iter().rev().find_map(|stmt| match stmt {
Stmt::FunctionDef(init) if init.name.id == dunder::INIT => Some(init),
_ => None,
}) {
Some(init) => Self::new(docstring, &init.parameters),
None => Self::of_docstring(docstring),
}
}

/// The documentation of a function with the given docstring and parameters.
pub fn new(docstring: Option<TextRange>, parameters: &Parameters) -> Self {
let parameters: Box<[_]> = parameters
.iter()
.filter_map(|param| {
Some((param.name().id.clone(), annotated_doc(param.annotation()?)?))
})
.collect();
/// The documentation of a function with the given docstring and the `Doc` string range of
/// each documented parameter.
pub fn new(docstring: Option<TextRange>, parameters: Box<[(Name, TextRange)]>) -> Self {
if parameters.is_empty() {
Self::of_docstring(docstring)
} else {
Expand Down Expand Up @@ -186,41 +160,6 @@ impl DocRanges {
}
}

/// The range of the string literal in the `Doc("...")` metadata of an `Annotated[...]`
/// annotation, as in `name: Annotated[str, Doc("The user's name")]`. This is the
/// [annotated-doc](https://github.com/fastapi/annotated-doc) convention that FastAPI uses.
/// `Doc` is matched by name, and when there is more than one, the last applies, as PEP 727
/// specifies. An implicitly concatenated string is skipped, because it has no single literal to
/// read back.
fn annotated_doc(annotation: &Expr) -> Option<TextRange> {
fn is_named(x: &Expr, name: &str) -> bool {
match x {
Expr::Name(x) => x.id == name,
Expr::Attribute(x) => x.attr.id == name,
_ => false,
}
}
let Expr::Subscript(annotated) = annotation else {
return None;
};
if !is_named(&annotated.value, "Annotated") {
return None;
}
Ast::unpack_slice(&annotated.slice)
.iter()
.skip(1)
.rev()
.find_map(|metadata| match metadata {
Expr::Call(call)
if is_named(&call.func, "Doc")
&& let [Expr::StringLiteral(text)] = &*call.arguments.args =>
{
(!text.value.is_implicit_concatenated()).then_some(text.range)
}
_ => None,
})
}

/// The documentation text of a `Doc("...")` string literal, given its source: the string
/// without its quotes, dedented, without surrounding blank lines. `None` if the text is blank.
pub fn clean_annotated_doc(literal: &str) -> Option<String> {
Expand Down Expand Up @@ -984,10 +923,6 @@ pub fn parse_sphinx_param_types(docstring: &str) -> HashMap<&str, DocstringParam
mod tests {
use std::ops::Range;

use ruff_python_ast::PySourceType;
use ruff_python_ast::Stmt;

use crate::ast::Ast;
use crate::docstring::CodeBlockKind;
use crate::docstring::DocRanges;
use crate::docstring::Docstring;
Expand Down Expand Up @@ -1857,64 +1792,6 @@ result : str
assert_eq!(param_types(doc), expected(&[]));
}

/// The `Doc` text of each documented parameter of the first statement of `source`.
fn annotated_docs(source: &str) -> Vec<(String, String)> {
let (module, _, _) = Ast::parse(source, PySourceType::Python);
let doc_ranges = match module.body.first() {
Some(Stmt::FunctionDef(x)) => DocRanges::of_function(x),
Some(Stmt::ClassDef(x)) => DocRanges::of_class(x),
_ => panic!("expected a function or class definition"),
};
doc_ranges
.parameters()
.iter()
.map(|(name, range)| {
let doc = clean_annotated_doc(&source[*range]).expect("non-blank `Doc` text");
(name.to_string(), doc)
})
.collect()
}

#[test]
fn test_doc_ranges_parameters() {
let source = r#"
def f(
a: Annotated[int, Doc("plain name")],
b: typing.Annotated[int, annotated_doc.Doc('attribute name')],
c: Annotated[int, Doc("first"), Doc("last")],
*args: Annotated[int, Doc("varargs")],
d: Annotated[int, "not a Doc"],
e: int,
f: Annotated[int, Doc(f"not a literal")],
g: list[Doc("not Annotated")],
h: Annotated[int, Doc("implicitly " "concatenated")],
): ...
"#;
assert_eq!(
annotated_docs(source),
vec![
("a".to_owned(), "plain name".to_owned()),
("b".to_owned(), "attribute name".to_owned()),
("c".to_owned(), "last".to_owned()),
("args".to_owned(), "varargs".to_owned()),
]
);
}

#[test]
fn test_doc_ranges_class_parameters_come_from_init() {
let source = r#"
class C:
"""Docstring."""
def __init__(self, a: Annotated[int, Doc("from init")]) -> None: ...
def other(self, b: Annotated[int, Doc("not from init")]) -> None: ...
"#;
assert_eq!(
annotated_docs(source),
vec![("a".to_owned(), "from init".to_owned())]
);
}

#[test]
fn test_clean_annotated_doc_dedents_multiline_text() {
let literal = r#""""
Expand Down
8 changes: 5 additions & 3 deletions pyrefly/lib/binding/class.rs
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,8 @@ use crate::binding::scope::Scope;
use crate::binding::shape_type::ShapeDeclarationOwner;
use crate::config::error_kind::ErrorKind;
use crate::export::deprecation::parse_deprecation;
use crate::export::doc_ranges::class_doc_ranges;
use crate::export::doc_ranges::function_doc_ranges;
use crate::export::special::SpecialExport;
use crate::types::class::ClassDefIndex;
use crate::types::class::ClassFieldProperties;
Expand Down Expand Up @@ -263,7 +265,7 @@ impl<'a> BindingsBuilder<'a> {
.find_map(|decorator| parse_deprecation(&decorator.expression))
.map(Box::new);
let mut pydantic_config_dict = PydanticConfigDict::default();
let doc_ranges = DocRanges::of_class(&x);
let doc_ranges = class_doc_ranges(&x);
let body = mem::take(&mut x.body);
let field_docstrings = Self::extract_field_docstrings(&body);
let pydantic_before_validator_fields = self.extract_field_validator_fields(&body);
Expand Down Expand Up @@ -729,15 +731,15 @@ impl<'a> BindingsBuilder<'a> {
let first_range = *first_function_ranges
.entry(func_def.name.id.clone())
.or_insert(func_def.name.range);
let doc_ranges = DocRanges::of_function(func_def);
let doc_ranges = function_doc_ranges(func_def);
if !doc_ranges.is_empty() {
field_docstrings.insert(func_def.name.range, doc_ranges.clone());
// Class field metadata points at the first declaration in an overload chain,
// while its documentation belongs to the implementation.
field_docstrings.insert(first_range, doc_ranges);
}
} else if let Stmt::ClassDef(class_def) = stmt {
let doc_ranges = DocRanges::of_class(class_def);
let doc_ranges = class_doc_ranges(class_def);
if !doc_ranges.is_empty() {
field_docstrings.insert(class_def.name.range, doc_ranges);
}
Expand Down
1 change: 1 addition & 0 deletions pyrefly/lib/export.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@

pub mod definitions;
pub mod deprecation;
pub mod doc_ranges;
pub mod exports;
pub mod special;
pub mod symbols;
18 changes: 5 additions & 13 deletions pyrefly/lib/export/definitions.rs
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ use crate::binding::stmt::is_special_import_function;
use crate::binding::stmt::special_import_form;
use crate::binding::stmt::special_import_module;
use crate::export::deprecation::parse_deprecation;
use crate::export::doc_ranges::class_doc_ranges;
use crate::export::doc_ranges::function_doc_ranges;
use crate::export::special::SpecialExport;
use crate::types::globals::ImplicitGlobal;

Expand Down Expand Up @@ -395,17 +397,7 @@ fn is_final_annotation(annotation: &Expr) -> bool {
Expr::Subscript(sub) => &*sub.value,
other => other,
};
let (base, value) = match target {
Expr::Name(x) => (None, &x.id),
Expr::Attribute(ExprAttribute { value, attr, .. }) if let Expr::Name(base) = &**value => {
(Some(&base.id), &attr.id)
}
_ => return false,
};
SpecialExport::new(value).is_some_and(|special| {
special == SpecialExport::Final
&& base.is_none_or(|base| special.defined_in(ModuleName::from_name(base)))
})
SpecialExport::from_syntax(target) == Some(SpecialExport::Final)
}

fn is_overload_decorator(decorator: &Decorator) -> bool {
Expand Down Expand Up @@ -773,7 +765,7 @@ impl DefinitionsBuilder {
self.add_identifier_with_docs(
name,
DefinitionStyle::Unannotated(SymbolKind::Class),
DocRanges::of_class(class_def),
class_doc_ranges(class_def),
);
return; // These things are inside a scope
}
Expand Down Expand Up @@ -1035,7 +1027,7 @@ impl DefinitionsBuilder {
self.add_identifier_with_docs(
name,
DefinitionStyle::Unannotated(SymbolKind::Function),
DocRanges::of_function(func_def),
function_doc_ranges(func_def),
);
return; // don't recurse because a separate scope
}
Expand Down
18 changes: 1 addition & 17 deletions pyrefly/lib/export/deprecation.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,29 +5,13 @@
* LICENSE file in the root directory of this source tree.
*/

use pyrefly_python::module_name::ModuleName;
use pyrefly_types::function::Deprecation;
use ruff_python_ast::Expr;
use ruff_python_ast::ExprAttribute;
use ruff_python_ast::ExprCall;
use ruff_python_ast::ExprStringLiteral;

use crate::export::special::SpecialExport;

fn is_deprecated_target(e: &Expr) -> bool {
let (base, value) = match e {
Expr::Name(x) => (None, &x.id),
Expr::Attribute(ExprAttribute { value, attr, .. }) if let Expr::Name(base) = &**value => {
(Some(&base.id), &attr.id)
}
_ => return false,
};
SpecialExport::new(value).is_some_and(|special| {
special == SpecialExport::Deprecated
&& base.is_none_or(|base| special.defined_in(ModuleName::from_name(base)))
})
}

fn extract_message(call: &ExprCall) -> Option<String> {
if let Some(arg) = call.arguments.args.first()
&& let Expr::StringLiteral(ExprStringLiteral { value, .. }) = arg
Expand All @@ -41,7 +25,7 @@ fn extract_message(call: &ExprCall) -> Option<String> {
/// Parse a decorator and return its deprecation metadata if it represents `@deprecated`.
pub fn parse_deprecation(e: &Expr) -> Option<Deprecation> {
let call = e.as_call_expr()?;
if !is_deprecated_target(&call.func) {
if SpecialExport::from_syntax(&call.func) != Some(SpecialExport::Deprecated) {
return None;
}
Some(Deprecation::new(extract_message(call)))
Expand Down
Loading
Loading