From b21839f6662808ab5e28b8cbc8c73373880cca21 Mon Sep 17 00:00:00 2001 From: Kyle Into Date: Mon, 16 Nov 2026 15:49:34 -0800 Subject: [PATCH 1/6] Add `SpecialExport::from_syntax` for matching before bindings exist Summary: Stack context: match annotated-doc `Doc` and `Annotated` with `SpecialExport` instead of by name (plan: https://artifacts.internalmeta.com/a/1087635754250361). Plan step: 1, NFC precursor. - What: add `SpecialExport::from_syntax`, which returns the special export that an expression names without resolving imports: a bare name such as `Final`, or an attribute of a module that defines it, such as `typing.Final`. The `Final`-annotation and `deprecated` checks in exports now use it instead of two copies of the same logic. - Why: a later diff matches `Annotated` and `Doc` the same way when it records `Doc` parameter ranges, which also happens before bindings exist. ___ landed-with-radar-review Differential Revision: D132395232 --- pyrefly/lib/export/definitions.rs | 12 +----------- pyrefly/lib/export/deprecation.rs | 18 +----------------- pyrefly/lib/export/special.rs | 18 ++++++++++++++++++ 3 files changed, 20 insertions(+), 28 deletions(-) diff --git a/pyrefly/lib/export/definitions.rs b/pyrefly/lib/export/definitions.rs index 6e4367340b..51cf89ac03 100644 --- a/pyrefly/lib/export/definitions.rs +++ b/pyrefly/lib/export/definitions.rs @@ -395,17 +395,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 { diff --git a/pyrefly/lib/export/deprecation.rs b/pyrefly/lib/export/deprecation.rs index c26f886eae..2f0ab21f8d 100644 --- a/pyrefly/lib/export/deprecation.rs +++ b/pyrefly/lib/export/deprecation.rs @@ -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 { if let Some(arg) = call.arguments.args.first() && let Expr::StringLiteral(ExprStringLiteral { value, .. }) = arg @@ -41,7 +25,7 @@ fn extract_message(call: &ExprCall) -> Option { /// Parse a decorator and return its deprecation metadata if it represents `@deprecated`. pub fn parse_deprecation(e: &Expr) -> Option { 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))) diff --git a/pyrefly/lib/export/special.rs b/pyrefly/lib/export/special.rs index 99eca899f6..30820514e8 100644 --- a/pyrefly/lib/export/special.rs +++ b/pyrefly/lib/export/special.rs @@ -7,6 +7,8 @@ use dupe::Dupe; use pyrefly_python::module_name::ModuleName; +use ruff_python_ast::Expr; +use ruff_python_ast::ExprAttribute; use ruff_python_ast::name::Name; /// These are names that are exported from the stdlib, but which take on @@ -197,6 +199,22 @@ impl SpecialExport { } } + /// The special export that `e` names without resolving imports: a bare name such as `Final`, + /// or an attribute of a module that defines it, such as `typing.Final`. For code that runs + /// before bindings exist, such as computing exports. + pub fn from_syntax(e: &Expr) -> Option { + match e { + Expr::Name(x) => Self::new(&x.id), + Expr::Attribute(ExprAttribute { value, attr, .. }) + if let Expr::Name(base) = &**value => + { + Self::new(&attr.id) + .filter(|special| special.defined_in(ModuleName::from_name(&base.id))) + } + _ => None, + } + } + pub fn defined_in(self, m: ModuleName) -> bool { match self { Self::IntVar | Self::Flag | Self::Index | Self::MapIntTuples | Self::NamedInts => { From 8db37555dd7cfe7b145940cb05f62078e4bd93bf Mon Sep 17 00:00:00 2001 From: Kyle Into Date: Mon, 16 Nov 2026 15:49:34 -0800 Subject: [PATCH 2/6] Build `DocRanges` from the AST in the pyrefly library Summary: Stack context: match annotated-doc `Doc` and `Annotated` with `SpecialExport` instead of by name (plan: https://artifacts.internalmeta.com/a/1087635754250361). Plan step: 2, NFC precursor. - What: the code that builds a definition's `DocRanges` from its AST, including the `Annotated[..., Doc("...")]` matcher, moves from `pyrefly_python::docstring` to the new `export::doc_ranges` module as `function_doc_ranges`, `class_doc_ranges`, and `doc_ranges_from_parts`. `DocRanges` keeps its representation and accessors, and `DocRanges::new` takes the parameter ranges directly. - Why: the next diffs match `Annotated` and `Doc` with `SpecialExport`, which lives in the pyrefly library. `pyrefly_python` cannot depend on it. ___ landed-with-radar-review Differential Revision: D132395233 --- crates/pyrefly_python/src/docstring.rs | 129 +-------------------- pyrefly/lib/binding/class.rs | 8 +- pyrefly/lib/export.rs | 1 + pyrefly/lib/export/definitions.rs | 6 +- pyrefly/lib/export/doc_ranges.rs | 152 +++++++++++++++++++++++++ pyrefly/lib/lsp/wasm/hover.rs | 4 +- pyrefly/lib/state/ide.rs | 6 +- pyrefly/lib/state/lsp.rs | 8 +- pyrefly/lib/state/lsp_attributes.rs | 7 +- 9 files changed, 182 insertions(+), 139 deletions(-) create mode 100644 pyrefly/lib/export/doc_ranges.rs diff --git a/crates/pyrefly_python/src/docstring.rs b/crates/pyrefly_python/src/docstring.rs index bd42c86de1..d89934b866 100644 --- a/crates/pyrefly_python/src/docstring.rs +++ b/crates/pyrefly_python/src/docstring.rs @@ -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] = [ @@ -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, 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, parameters: Box<[(Name, TextRange)]>) -> Self { if parameters.is_empty() { Self::of_docstring(docstring) } else { @@ -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 { - 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 { @@ -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; @@ -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#"""" diff --git a/pyrefly/lib/binding/class.rs b/pyrefly/lib/binding/class.rs index b924c3b990..811ed7fb77 100644 --- a/pyrefly/lib/binding/class.rs +++ b/pyrefly/lib/binding/class.rs @@ -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; @@ -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); @@ -729,7 +731,7 @@ 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, @@ -737,7 +739,7 @@ impl<'a> BindingsBuilder<'a> { 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); } diff --git a/pyrefly/lib/export.rs b/pyrefly/lib/export.rs index 8990d3959b..d04367f43b 100644 --- a/pyrefly/lib/export.rs +++ b/pyrefly/lib/export.rs @@ -7,6 +7,7 @@ pub mod definitions; pub mod deprecation; +pub mod doc_ranges; pub mod exports; pub mod special; pub mod symbols; diff --git a/pyrefly/lib/export/definitions.rs b/pyrefly/lib/export/definitions.rs index 51cf89ac03..c68a1aba68 100644 --- a/pyrefly/lib/export/definitions.rs +++ b/pyrefly/lib/export/definitions.rs @@ -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; @@ -763,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 } @@ -1025,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 } diff --git a/pyrefly/lib/export/doc_ranges.rs b/pyrefly/lib/export/doc_ranges.rs new file mode 100644 index 0000000000..237bc61790 --- /dev/null +++ b/pyrefly/lib/export/doc_ranges.rs @@ -0,0 +1,152 @@ +/* + * Copyright (c) Meta Platforms, Inc. and affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +//! Building the `DocRanges` of a definition from its AST. + +use pyrefly_python::ast::Ast; +use pyrefly_python::docstring::DocRanges; +use pyrefly_python::docstring::Docstring; +use pyrefly_python::dunder; +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_text_size::TextRange; + +pub fn function_doc_ranges(x: &StmtFunctionDef) -> DocRanges { + doc_ranges_from_parts(Docstring::range_from_stmts(&x.body), &x.parameters) +} + +/// A class's parameters are those of its `__init__`. +pub fn class_doc_ranges(x: &StmtClassDef) -> DocRanges { + 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) => doc_ranges_from_parts(docstring, &init.parameters), + None => DocRanges::of_docstring(docstring), + } +} + +/// The documentation of a function with the given docstring and parameters. +pub fn doc_ranges_from_parts(docstring: Option, parameters: &Parameters) -> DocRanges { + DocRanges::new( + docstring, + parameters + .iter() + .filter_map(|param| { + Some((param.name().id.clone(), annotated_doc(param.annotation()?)?)) + }) + .collect(), + ) +} + +/// 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 { + 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, + }) +} + +#[cfg(test)] +mod tests { + use pyrefly_python::ast::Ast; + use pyrefly_python::docstring::clean_annotated_doc; + use ruff_python_ast::PySourceType; + use ruff_python_ast::Stmt; + + use crate::export::doc_ranges::class_doc_ranges; + use crate::export::doc_ranges::function_doc_ranges; + + /// 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)) => function_doc_ranges(x), + Some(Stmt::ClassDef(x)) => class_doc_ranges(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())] + ); + } +} diff --git a/pyrefly/lib/lsp/wasm/hover.rs b/pyrefly/lib/lsp/wasm/hover.rs index 648fb6a5fc..cfe39cc2d2 100644 --- a/pyrefly/lib/lsp/wasm/hover.rs +++ b/pyrefly/lib/lsp/wasm/hover.rs @@ -19,7 +19,6 @@ use lsp_types::Range; use lsp_types::Uri; use pyrefly_build::handle::Handle; use pyrefly_python::ast::Ast; -use pyrefly_python::docstring::DocRanges; use pyrefly_python::docstring::Docstring; use pyrefly_python::docstring::parse_parameter_documentation; use pyrefly_python::dunder; @@ -62,6 +61,7 @@ use crate::alt::answers_solver::AnswersSolver; use crate::binding::binding::Key; use crate::binding::bindings::BindingsBuilder; use crate::error::error::Error; +use crate::export::doc_ranges::function_doc_ranges; use crate::export::exports::ExportLocation; use crate::lsp::module_helpers::collect_symbol_def_paths; use crate::lsp::module_helpers::to_real_path; @@ -764,7 +764,7 @@ fn parameter_definition_documentation( let mut docs = Docstring::range_from_stmts(func.body.as_slice()) .map(|range| parse_parameter_documentation(module.code_at(range))) .unwrap_or_default(); - docs.extend(DocRanges::of_function(func).parameter_docs(&module)); + docs.extend(function_doc_ranges(func).parameter_docs(&module)); let key = name.as_str(); docs.remove(key).map(|doc| (key.to_owned(), doc)) } diff --git a/pyrefly/lib/state/ide.rs b/pyrefly/lib/state/ide.rs index 75d13763d2..903abb73f2 100644 --- a/pyrefly/lib/state/ide.rs +++ b/pyrefly/lib/state/ide.rs @@ -36,6 +36,7 @@ use crate::binding::binding::Key; use crate::binding::bindings::Bindings; use crate::binding::narrow::identifier_and_chain_for_expr; use crate::binding::narrow::identifier_and_chain_prefix_for_expr; +use crate::export::doc_ranges::doc_ranges_from_parts; use crate::export::exports::Export; use crate::state::lsp::ImportFormat; @@ -201,7 +202,10 @@ fn create_intermediate_definition_from( return Some(IntermediateDefinition::Local(Export { location: undecorated.def.name.range, symbol_kind: Some(symbol_kind), - doc_ranges: DocRanges::new(func.docstring_range, &undecorated.def.parameters), + doc_ranges: doc_ranges_from_parts( + func.docstring_range, + &undecorated.def.parameters, + ), deprecation: None, is_final: false, special_export: None, diff --git a/pyrefly/lib/state/lsp.rs b/pyrefly/lib/state/lsp.rs index aaec80f67b..beeba275a0 100644 --- a/pyrefly/lib/state/lsp.rs +++ b/pyrefly/lib/state/lsp.rs @@ -88,6 +88,8 @@ use crate::binding::metadata::BindingsMetadata; use crate::config::error_kind::ErrorKind; use crate::error::error::ErrorQuickFix; use crate::error::suppress::detect_line_ending; +use crate::export::doc_ranges::class_doc_ranges; +use crate::export::doc_ranges::function_doc_ranges; use crate::export::exports::Export; use crate::export::exports::ExportLocation; use crate::export::exports::Exports; @@ -1193,21 +1195,21 @@ impl<'a> Transaction<'a> { // def id(...): ... Some(IdentifierWithContext::from_stmt_method_def( id, - DocRanges::of_function(stmt), + function_doc_ranges(stmt), )) } (Some(AnyNodeRef::Identifier(id)), Some(AnyNodeRef::StmtFunctionDef(stmt)), _, _) => { // def id(...): ... Some(IdentifierWithContext::from_stmt_function_def( id, - DocRanges::of_function(stmt), + function_doc_ranges(stmt), )) } (Some(AnyNodeRef::Identifier(id)), Some(AnyNodeRef::StmtClassDef(stmt)), _, _) => { // class id(...): ... Some(IdentifierWithContext::from_stmt_class_def( id, - DocRanges::of_class(stmt), + class_doc_ranges(stmt), )) } (Some(AnyNodeRef::Identifier(id)), Some(AnyNodeRef::Parameter(_)), _, _) => { diff --git a/pyrefly/lib/state/lsp_attributes.rs b/pyrefly/lib/state/lsp_attributes.rs index 286e795925..b7ee5530d5 100644 --- a/pyrefly/lib/state/lsp_attributes.rs +++ b/pyrefly/lib/state/lsp_attributes.rs @@ -16,6 +16,9 @@ use ruff_python_ast::Stmt; use ruff_text_size::Ranged; use ruff_text_size::TextRange; +use crate::export::doc_ranges::class_doc_ranges; +use crate::export::doc_ranges::function_doc_ranges; + #[derive(Debug, Clone)] pub(crate) enum AttributeKind { Function, @@ -177,7 +180,7 @@ fn definition_from_function( if let Stmt::FunctionDef(func_def) = stmt && &func_def.name.id == attr_name { - return Some((func_def.name.range, DocRanges::of_function(func_def))); + return Some((func_def.name.range, function_doc_ranges(func_def))); } } None @@ -191,7 +194,7 @@ fn definition_from_class( if let Stmt::ClassDef(class_def) = stmt && &class_def.name.id == attr_name { - return Some((class_def.name.range, DocRanges::of_class(class_def))); + return Some((class_def.name.range, class_doc_ranges(class_def))); } } None From 6598a5fd87c48dc8eed1e85d8b9c2b690b6d571f Mon Sep 17 00:00:00 2001 From: Kyle Into Date: Mon, 16 Nov 2026 15:49:34 -0800 Subject: [PATCH 3/6] Test that `Doc` parameter docs match `Annotated` and `Doc` from any module Summary: Stack context: match annotated-doc `Doc` and `Annotated` with `SpecialExport` instead of by name (plan: https://artifacts.internalmeta.com/a/1087635754250361). Plan step: 3, test of current behavior. - What: add a `DocRanges` test where `Annotated` and `Doc` are attributes of an unrelated module, `other.Annotated` and `other.Doc`. - Why: both are matched by name today, so they are wrongly treated as annotated-doc. The next diff fixes this. ___ landed-with-radar-review Differential Revision: D132395235 --- pyrefly/lib/export/doc_ranges.rs | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/pyrefly/lib/export/doc_ranges.rs b/pyrefly/lib/export/doc_ranges.rs index 237bc61790..186474a9e2 100644 --- a/pyrefly/lib/export/doc_ranges.rs +++ b/pyrefly/lib/export/doc_ranges.rs @@ -149,4 +149,24 @@ class C: vec![("a".to_owned(), "from init".to_owned())] ); } + + // Bug: `Annotated` and `Doc` are matched by name, so an attribute of any module matches. + #[test] + fn test_doc_ranges_parameters_from_other_modules() { + let source = r#" +def f( + a: other.Annotated[int, Doc("other Annotated")], + b: Annotated[int, other.Doc("other Doc")], + c: typing_extensions.Annotated[int, typing_extensions.Doc("typing_extensions")], +): ... +"#; + assert_eq!( + annotated_docs(source), + vec![ + ("a".to_owned(), "other Annotated".to_owned()), + ("b".to_owned(), "other Doc".to_owned()), + ("c".to_owned(), "typing_extensions".to_owned()), + ] + ); + } } From bd8c91cee43a1767dcfdf865604786592acd7195 Mon Sep 17 00:00:00 2001 From: Kyle Into Date: Mon, 16 Nov 2026 15:49:34 -0800 Subject: [PATCH 4/6] Match annotated-doc `Annotated` and `Doc` with `SpecialExport` Summary: Stack context: match annotated-doc `Doc` and `Annotated` with `SpecialExport` instead of by name (plan: https://artifacts.internalmeta.com/a/1087635754250361). Plan step: 4, fix. - Problem: `Doc` parameter docs matched `Annotated` and `Doc` by name, so an attribute of any module counted, for example `name: other.Annotated[str, other.Doc("...")]`. - Fix: add `SpecialExport::Doc`, defined in `typing_extensions` and `annotated_doc`, and match both names with `SpecialExport::from_syntax`, the same rule that exports use for `Final` and `deprecated`. A bare name or an attribute of a module that defines it matches. Imports are not resolved, because `DocRanges` are built before bindings exist. ___ landed-with-radar-review Reviewed By: samwgoldman Differential Revision: D132395237 --- pyrefly/lib/export/doc_ranges.rs | 26 ++++++++------------------ pyrefly/lib/export/special.rs | 4 ++++ 2 files changed, 12 insertions(+), 18 deletions(-) diff --git a/pyrefly/lib/export/doc_ranges.rs b/pyrefly/lib/export/doc_ranges.rs index 186474a9e2..10fdd8aec7 100644 --- a/pyrefly/lib/export/doc_ranges.rs +++ b/pyrefly/lib/export/doc_ranges.rs @@ -18,6 +18,8 @@ use ruff_python_ast::StmtClassDef; use ruff_python_ast::StmtFunctionDef; use ruff_text_size::TextRange; +use crate::export::special::SpecialExport; + pub fn function_doc_ranges(x: &StmtFunctionDef) -> DocRanges { doc_ranges_from_parts(Docstring::range_from_stmts(&x.body), &x.parameters) } @@ -50,21 +52,14 @@ pub fn doc_ranges_from_parts(docstring: Option, parameters: &Paramete /// 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. +/// `Annotated` and `Doc` are matched with `SpecialExport::from_syntax`, because this runs before +/// bindings exist. When there is more than one `Doc`, 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 { - 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") { + if SpecialExport::from_syntax(&annotated.value) != Some(SpecialExport::Annotated) { return None; } Ast::unpack_slice(&annotated.slice) @@ -73,7 +68,7 @@ fn annotated_doc(annotation: &Expr) -> Option { .rev() .find_map(|metadata| match metadata { Expr::Call(call) - if is_named(&call.func, "Doc") + if SpecialExport::from_syntax(&call.func) == Some(SpecialExport::Doc) && let [Expr::StringLiteral(text)] = &*call.arguments.args => { (!text.value.is_implicit_concatenated()).then_some(text.range) @@ -150,7 +145,6 @@ class C: ); } - // Bug: `Annotated` and `Doc` are matched by name, so an attribute of any module matches. #[test] fn test_doc_ranges_parameters_from_other_modules() { let source = r#" @@ -162,11 +156,7 @@ def f( "#; assert_eq!( annotated_docs(source), - vec![ - ("a".to_owned(), "other Annotated".to_owned()), - ("b".to_owned(), "other Doc".to_owned()), - ("c".to_owned(), "typing_extensions".to_owned()), - ] + vec![("c".to_owned(), "typing_extensions".to_owned())] ); } } diff --git a/pyrefly/lib/export/special.rs b/pyrefly/lib/export/special.rs index 30820514e8..8f81824763 100644 --- a/pyrefly/lib/export/special.rs +++ b/pyrefly/lib/export/special.rs @@ -28,6 +28,8 @@ pub enum SpecialExport { ParamSpec, TypeVarTuple, Annotated, + /// `Doc` from annotated-doc, formerly PEP 727. + Doc, Literal, Enum, StrEnum, @@ -119,6 +121,7 @@ impl SpecialExport { "ParamSpec" => Some(Self::ParamSpec), "TypeVarTuple" => Some(Self::TypeVarTuple), "Annotated" => Some(Self::Annotated), + "Doc" => Some(Self::Doc), "Shaped" => Some(Self::Shaped), "shape_vars" => Some(Self::ShapeVars), "Literal" => Some(Self::Literal), @@ -255,6 +258,7 @@ impl SpecialExport { | Self::TypeForm => { matches!(m.as_str(), "typing" | "typing_extensions") } + Self::Doc => matches!(m.as_str(), "typing_extensions" | "annotated_doc"), Self::CollectionsNamedTuple => matches!(m.as_str(), "collections"), Self::FunctoolsWraps | Self::FunctoolsUpdateWrapper => m == ModuleName::functools(), Self::Enum | Self::StrEnum | Self::IntEnum => matches!(m.as_str(), "enum"), From 8e460ffe347cd3d1217dd3f962a4efef2f7f2cc2 Mon Sep 17 00:00:00 2001 From: Kyle Into Date: Mon, 16 Nov 2026 15:49:34 -0800 Subject: [PATCH 5/6] Test that function hover shows no annotated-doc parameter docs Summary: Stack context: show the annotated-doc `Doc` text of every parameter in function hover (plan: https://artifacts.internalmeta.com/a/2314372522479036). Plan step: 1, test of current behavior. - What: a hover test on a function with `Doc` parameter docs, at its definition and at a call in another module. - Why: function hover shows the signature and docstring, but no `Doc` text. The next diff fixes this. Differential Revision: D132412471 --- pyrefly/lib/test/lsp/hover.rs | 64 +++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/pyrefly/lib/test/lsp/hover.rs b/pyrefly/lib/test/lsp/hover.rs index a7dbe381fe..080cddcb1f 100644 --- a/pyrefly/lib/test/lsp/hover.rs +++ b/pyrefly/lib/test/lsp/hover.rs @@ -4538,6 +4538,70 @@ C().method(x=1) ); } +// Bug: hover on a function does not show the `Doc` text of its parameters. +#[test] +fn hover_on_function_shows_annotated_doc_parameter_documentation() { + let lib = r#" +from typing import Annotated +from typing_extensions import Doc + +def greet( +# ^ + name: Annotated[str, Doc("The user's name.")], + greeting: Annotated[str, Doc("How to greet the user.")] = "Hello", + loud: bool = False, +) -> None: + """Greet a user.""" +"#; + let main = r#" +from lib import greet +greet("Ada") +# ^ +"#; + let report = get_batched_lsp_operations_report( + &[("lib", lib), ("main", main)], + |state, handle, position| match get_hover(&state.transaction(), handle, position, false) { + Some(Hover { + contents: Contents::MarkupContent(markup), + .. + }) => markup.value, + _ => "None".to_owned(), + }, + ); + assert_eq!( + r#" +# lib.py +5 | def greet( + ^ +```python +(function) greet: def greet( + name : str, + greeting: str = 'Hello', + loud : bool = False +) -> None: ... +``` +--- +Greet a user. + + +# main.py +3 | greet("Ada") + ^ +```python +(function) greet: def greet( + name : str, + greeting: str = 'Hello', + loud : bool = False +) -> None: ... +``` +--- +Greet a user. +"# + .trim(), + report.trim(), + ); +} + #[test] fn hover_shows_annotated_doc_parameter_documentation() { let code = r#" From 51526eea9f3c80de1dc5e695a893a2166bcb3033 Mon Sep 17 00:00:00 2001 From: Kyle Into Date: Mon, 16 Nov 2026 15:49:34 -0800 Subject: [PATCH 6/6] Show annotated-doc parameter docs in function hover Summary: Stack context: show the annotated-doc `Doc` text of every parameter in function hover (plan: https://artifacts.internalmeta.com/a/2314372522479036). Plan step: 2, fix. - What: hover on a function shows the `Doc` text of each documented parameter, after the docstring, in definition order. Each entry uses the existing `**Parameter `name`**` format. - Why: the `Doc` text showed only in a parameter hover and in signature help. Docstring parameter sections already show in function hover, because they are part of the docstring. - How: the definition that hover finds already carries the `Doc` ranges, which signature help reads with `DocRanges::parameter_docs`. `HoverValue::parameter_doc` becomes a list, which a parameter hover fills with one entry, as before. Differential Revision: D132412472 --- pyrefly/lib/lsp/wasm/hover.rs | 86 +++++++++++++++++++++-------------- pyrefly/lib/test/lsp/hover.rs | 15 +++++- 2 files changed, 65 insertions(+), 36 deletions(-) diff --git a/pyrefly/lib/lsp/wasm/hover.rs b/pyrefly/lib/lsp/wasm/hover.rs index cfe39cc2d2..c1e58f1818 100644 --- a/pyrefly/lib/lsp/wasm/hover.rs +++ b/pyrefly/lib/lsp/wasm/hover.rs @@ -91,7 +91,7 @@ pub struct HoverValue { pub type_: Type, pub range: Option, pub docstring: Option, - pub parameter_doc: Option<(String, String)>, + pub parameter_docs: Vec<(String, String)>, pub type_sources: Vec, pub display: Option, pub show_go_to_links: bool, @@ -262,18 +262,27 @@ impl HoverValue { } None => String::new(), }; - let parameter_doc_formatted = - self.parameter_doc - .as_ref() - .map_or(String::new(), |(name, doc)| { - let prefix = if self.docstring.is_some() { - "\n\n---\n" - } else { - "\n---\n" - }; - let cleaned = doc.trim().replace('\n', " \n"); - format!("{prefix}**Parameter `{}`**\n{}", name, cleaned) - }); + let parameter_docs_formatted = if self.parameter_docs.is_empty() { + String::new() + } else { + let prefix = if self.docstring.is_some() { + "\n\n---\n" + } else { + "\n---\n" + }; + let docs = self + .parameter_docs + .iter() + .map(|(name, doc)| { + format!( + "**Parameter `{name}`**\n{}", + doc.trim().replace('\n', " \n") + ) + }) + .collect::>() + .join("\n\n"); + format!("{prefix}{docs}") + }; let kind_formatted = self .resolve_symbol_kind() .map(|kind| format!("{} ", kind.display_for_hover())) @@ -326,7 +335,7 @@ impl HoverValue { type_display, type_source_formatted, docstring_formatted, - parameter_doc_formatted, + parameter_docs_formatted, symbol_def_formatted ), }), @@ -1651,25 +1660,27 @@ pub fn get_hover_with_verbosity( let hover_constructor_dunder = definition .as_ref() .is_some_and(|item| is_constructor_dunder(item.display_name.as_deref())); - let (kind, name, fallback_docstring) = if let Some(FindDefinitionItemWithDocstring { - metadata, - definition_range: definition_location, - module, - doc_ranges, - display_name, - }) = definition - { - let kind = metadata.symbol_kind(); - let name = hover_name_from_definition_snippet( - module.code_at(definition_location), - display_name.as_deref(), - fallback_name_from_type, - ); - let docstring = doc_ranges.docstring().map(|range| Docstring(range, module)); - (kind, name, docstring) - } else { - (None, fallback_name_from_type, None) - }; + let (kind, name, fallback_docstring, definition_parameter_docs) = + if let Some(FindDefinitionItemWithDocstring { + metadata, + definition_range: definition_location, + module, + doc_ranges, + display_name, + }) = definition + { + let kind = metadata.symbol_kind(); + let name = hover_name_from_definition_snippet( + module.code_at(definition_location), + display_name.as_deref(), + fallback_name_from_type, + ); + let parameter_docs = doc_ranges.parameter_docs(&module).collect::>(); + let docstring = doc_ranges.docstring().map(|range| Docstring(range, module)); + (kind, name, docstring, parameter_docs) + } else { + (None, fallback_name_from_type, None, Vec::new()) + }; let docstring = interface_definition .and_then(|item| { item.doc_ranges @@ -1745,7 +1756,12 @@ pub fn get_hover_with_verbosity( None => (None, false), }; - let parameter_doc = resolve_hover_parameter_doc(transaction, handle, position); + // A function's own `Doc` texts, or the docs of the parameter under the cursor. At most one + // is nonempty, because a parameter's definition documents no parameters of its own. + let parameter_docs = resolve_hover_parameter_doc(transaction, handle, position) + .into_iter() + .chain(definition_parameter_docs) + .collect(); let mut hover = HoverValue { kind, @@ -1753,7 +1769,7 @@ pub fn get_hover_with_verbosity( type_, range, docstring, - parameter_doc, + parameter_docs, type_sources: type_sources_for_hover(transaction, handle, position), display: type_display, show_go_to_links: options.show_go_to_links, diff --git a/pyrefly/lib/test/lsp/hover.rs b/pyrefly/lib/test/lsp/hover.rs index 080cddcb1f..ee70b7b756 100644 --- a/pyrefly/lib/test/lsp/hover.rs +++ b/pyrefly/lib/test/lsp/hover.rs @@ -4538,7 +4538,6 @@ C().method(x=1) ); } -// Bug: hover on a function does not show the `Doc` text of its parameters. #[test] fn hover_on_function_shows_annotated_doc_parameter_documentation() { let lib = r#" @@ -4583,6 +4582,13 @@ greet("Ada") --- Greet a user. +--- +**Parameter `name`** +The user's name. + +**Parameter `greeting`** +How to greet the user. + # main.py 3 | greet("Ada") @@ -4596,6 +4602,13 @@ Greet a user. ``` --- Greet a user. + +--- +**Parameter `name`** +The user's name. + +**Parameter `greeting`** +How to greet the user. "# .trim(), report.trim(),