[ty] Add builtins to completions derived from scope

Most of the work here was doing some light refactoring to facilitate
sensible testing. That is, we don't want to list every builtin included
in most tests, so we add some structure to the completion type returned.
Tests can now filter based on whether a completion is a builtin or not.

Otherwise, builtins are found using the existing infrastructure for
`object.attr` completions (where we hard-code the module name
`builtins`).

I did consider changing the sort order based on whether a completion
suggestion was a builtin or not. In particular, it seemed like it might
be a good idea to sort builtins after other scope based completions,
but before the dunder and sunder attributes. Namely, it seems likely
that there is an inverse correlation between the size of a scope and
the likelihood of an item in that scope being used at any given point.
So it *might* be a good idea to prioritize the likelier candidates in
the completions returned.

Additionally, the number of items introduced by adding builtins is quite
large. So I wondered whether mixing them in with everything else would
become too noisy.

However, it's not totally clear to me that this is the right thing to
do. Right now, I feel like there is a very obvious lexicographic
ordering that makes "finding" the right suggestion to activate
potentially easier than if the ranking mechanism is less clear.
(Technically, the dunder and sunder attributes are not sorted
lexicographically, but I'd put forward that most folks don't have an
intuitive understanding of where `_` ranks lexicographically with
respect to "regular" letters. Moreover, since dunder and sunder
attributes are all grouped together, I think the ordering here ends up
being very obvious after even a quick glance.)

Author: BurntSushi

crates/ty_ide/src/completion.rs

@@ -5,14 +5,11 @@ use ruff_db::parsed::{ParsedModuleRef, parsed_module};
 use ruff_python_ast as ast;
 use ruff_python_parser::{Token, TokenAt, TokenKind};
 use ruff_text_size::{Ranged, TextRange, TextSize};
+use ty_python_semantic::{Completion, SemanticModel};
 
 use crate::Db;
 use crate::find_node::covering_node;
 
-pub struct Completion {
-    pub label: String,
-}
-
 pub fn completion(db: &dyn Db, file: File, offset: TextSize) -> Vec<Completion> {
     let parsed = parsed_module(db.upcast(), file).load(db.upcast());
 
@@ -23,18 +20,15 @@ pub fn completion(db: &dyn Db, file: File, offset: TextSize) -> Vec<Completion>
         return vec![];
     };
 
-    let model = ty_python_semantic::SemanticModel::new(db.upcast(), file);
+    let model = SemanticModel::new(db.upcast(), file);
     let mut completions = match target {
         CompletionTargetAst::ObjectDot { expr } => model.attribute_completions(expr),
         CompletionTargetAst::ImportFrom { import, name } => model.import_completions(import, name),
         CompletionTargetAst::Scoped { node } => model.scoped_completions(node),
     };
-    completions.sort_by(|name1, name2| compare_suggestions(name1, name2));
-    completions.dedup();
+    completions.sort_by(compare_suggestions);
+    completions.dedup_by(|c1, c2| c1.name == c2.name);
     completions
-        .into_iter()
-        .map(|name| Completion { label: name.into() })
-        .collect()
 }
 
 /// The kind of tokens identified under the cursor.
@@ -330,7 +324,7 @@ fn import_from_tokens(tokens: &[Token]) -> Option<&Token> {
 ///
 /// This has the effect of putting all dunder attributes after "normal"
 /// attributes, and all single-underscore attributes after dunder attributes.
-fn compare_suggestions(name1: &str, name2: &str) -> Ordering {
+fn compare_suggestions(c1: &Completion, c2: &Completion) -> Ordering {
     /// A helper type for sorting completions based only on name.
     ///
     /// This sorts "normal" names first, then dunder names and finally
@@ -345,31 +339,32 @@ fn compare_suggestions(name1: &str, name2: &str) -> Ordering {
     }
 
     impl Kind {
-        fn classify(name: &str) -> Kind {
+        fn classify(c: &Completion) -> Kind {
             // Dunder needs a prefix and suffix double underscore.
             // When there's only a prefix double underscore, this
             // results in explicit name mangling. We let that be
             // classified as-if they were single underscore names.
             //
             // Ref: <https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers>
-            if name.starts_with("__") && name.ends_with("__") {
+            if c.name.starts_with("__") && c.name.ends_with("__") {
                 Kind::Dunder
-            } else if name.starts_with('_') {
+            } else if c.name.starts_with('_') {
                 Kind::Sunder
             } else {
                 Kind::Normal
             }
         }
     }
 
-    let (kind1, kind2) = (Kind::classify(name1), Kind::classify(name2));
-    kind1.cmp(&kind2).then_with(|| name1.cmp(name2))
+    let (kind1, kind2) = (Kind::classify(c1), Kind::classify(c2));
+    kind1.cmp(&kind2).then_with(|| c1.name.cmp(&c2.name))
 }
 
 #[cfg(test)]
 mod tests {
     use insta::assert_snapshot;
     use ruff_python_parser::{Mode, ParseOptions, TokenKind, Tokens};
+    use ty_python_semantic::Completion;
 
     use crate::completion;
     use crate::tests::{CursorTest, cursor_test};
@@ -463,7 +458,39 @@ mod tests {
 ",
         );
 
-        assert_snapshot!(test.completions(), @"<No completions found>");
+        assert_snapshot!(test.completions(), @"<No completions found after filtering out 230 completions>");
+    }
+
+    #[test]
+    fn builtins() {
+        let test = cursor_test(
+            "\
+<CURSOR>
+",
+        );
+        test.assert_completions_include("filter");
+    }
+
+    #[test]
+    fn builtins_not_included_object_attr() {
+        let test = cursor_test(
+            "\
+import re
+
+re.<CURSOR>
+",
+        );
+        test.assert_completions_do_not_include("filter");
+    }
+
+    #[test]
+    fn builtins_not_included_import() {
+        let test = cursor_test(
+            "\
+from re import <CURSOR>
+",
+        );
+        test.assert_completions_do_not_include("filter");
     }
 
     #[test]
@@ -828,7 +855,7 @@ def frob(): ...
         // TODO: it would be good if `bar` was included here, but
         // the list comprehension is not yet valid and so we do not
         // detect this as a definition of `bar`.
-        assert_snapshot!(test.completions(), @"<No completions found>");
+        assert_snapshot!(test.completions(), @"<No completions found after filtering out 230 completions>");
     }
 
     #[test]
@@ -916,7 +943,7 @@ def frob(): ...
         //
         // The `lambda_blank1` test works because there are expressions
         // on either side of <CURSOR>.
-        assert_snapshot!(test.completions(), @"<No completions found>");
+        assert_snapshot!(test.completions(), @"<No completions found after filtering out 230 completions>");
     }
 
     #[test]
@@ -928,7 +955,7 @@ def frob(): ...
         );
 
         // FIXME: Should include `foo`.
-        assert_snapshot!(test.completions(), @"<No completions found>");
+        assert_snapshot!(test.completions(), @"<No completions found after filtering out 230 completions>");
     }
 
     #[test]
@@ -940,7 +967,7 @@ def frob(): ...
         );
 
         // FIXME: Should include `foo`.
-        assert_snapshot!(test.completions(), @"<No completions found>");
+        assert_snapshot!(test.completions(), @"<No completions found after filtering out 230 completions>");
     }
 
     #[test]
@@ -1330,7 +1357,7 @@ hidden_<CURSOR>
 ",
         );
 
-        assert_snapshot!(test.completions(), @"<No completions found>");
+        assert_snapshot!(test.completions(), @"<No completions found after filtering out 230 completions>");
     }
 
     #[test]
@@ -1738,7 +1765,7 @@ A.<CURSOR>
         );
 
         assert_snapshot!(
-            test.completions_if(|name| name.contains("FOO") || name.contains("foo")),
+            test.completions_if(|c| c.name.contains("FOO") || c.name.contains("foo")),
             @r"
         FOO
         foo
@@ -1887,7 +1914,7 @@ except Type<CURSOR>:
 ",
         );
 
-        assert_snapshot!(test.completions(), @"<No completions found>");
+        assert_snapshot!(test.completions(), @"<No completions found after filtering out 230 completions>");
     }
 
     // Ref: https://github.com/astral-sh/ty/issues/572
@@ -2226,25 +2253,32 @@ importlib.<CURSOR>
             "#,
         );
 
-        assert_snapshot!(test.completions(), @r"<No completions found>");
+        assert_snapshot!(test.completions(), @"<No completions found after filtering out 230 completions>");
     }
 
     impl CursorTest {
+        /// Returns all completions except for builtins.
         fn completions(&self) -> String {
-            self.completions_if(|_| true)
+            self.completions_if(|c| !c.builtin)
         }
 
-        fn completions_if(&self, predicate: impl Fn(&str) -> bool) -> String {
+        fn completions_if(&self, predicate: impl Fn(&Completion) -> bool) -> String {
             let completions = completion(&self.db, self.cursor.file, self.cursor.offset);
             if completions.is_empty() {
                 return "<No completions found>".to_string();
             }
-            completions
-                .into_iter()
-                .map(|completion| completion.label)
+            let included = completions
+                .iter()
                 .filter(|label| predicate(label))
-                .collect::<Vec<String>>()
-                .join("\n")
+                .map(|completion| completion.name.as_str().to_string())
+                .collect::<Vec<String>>();
+            if included.is_empty() {
+                return format!(
+                    "<No completions found after filtering out {} completions>",
+                    completions.len(),
+                );
+            }
+            included.join("\n")
         }
 
         #[track_caller]
@@ -2254,7 +2288,7 @@ importlib.<CURSOR>
             assert!(
                 completions
                     .iter()
-                    .any(|completion| completion.label == expected),
+                    .any(|completion| completion.name == expected),
                 "Expected completions to include `{expected}`"
             );
         }
@@ -2266,7 +2300,7 @@ importlib.<CURSOR>
             assert!(
                 completions
                     .iter()
-                    .all(|completion| completion.label != unexpected),
+                    .all(|completion| completion.name != unexpected),
                 "Expected completions to not include `{unexpected}`",
             );
         }

crates/ty_python_semantic/src/lib.rs

@@ -15,7 +15,7 @@ pub use program::{
     PythonVersionWithSource, SearchPathSettings,
 };
 pub use python_platform::PythonPlatform;
-pub use semantic_model::{HasType, SemanticModel};
+pub use semantic_model::{Completion, HasType, SemanticModel};
 pub use site_packages::{PythonEnvironment, SitePackagesPaths, SysPrefixPathOrigin};
 pub use util::diagnostics::add_inferred_python_version_hint_to_diagnostic;
 

crates/ty_python_semantic/src/semantic_model.rs

@@ -46,7 +46,7 @@ impl<'db> SemanticModel<'db> {
         &self,
         import: &ast::StmtImportFrom,
         _name: Option<usize>,
-    ) -> Vec<Name> {
+    ) -> Vec<Completion> {
         let module_name = match ModuleName::from_import_statement(self.db, self.file, import) {
             Ok(module_name) => module_name,
             Err(err) => {
@@ -58,26 +58,44 @@ impl<'db> SemanticModel<'db> {
                 return vec![];
             }
         };
-        let Some(module) = resolve_module(self.db, &module_name) else {
+        self.module_completions(&module_name)
+    }
+
+    /// Returns completions for symbols available in the given module as if
+    /// it were imported by this model's `File`.
+    fn module_completions(&self, module_name: &ModuleName) -> Vec<Completion> {
+        let Some(module) = resolve_module(self.db, module_name) else {
             tracing::debug!("Could not resolve module from `{module_name:?}`");
             return vec![];
         };
         let ty = Type::module_literal(self.db, self.file, &module);
-        crate::types::all_members(self.db, ty).into_iter().collect()
+        crate::types::all_members(self.db, ty)
+            .into_iter()
+            .map(|name| Completion {
+                name,
+                builtin: module_name.as_str() == "builtins",
+            })
+            .collect()
     }
 
     /// Returns completions for symbols available in a `object.<CURSOR>` context.
-    pub fn attribute_completions(&self, node: &ast::ExprAttribute) -> Vec<Name> {
+    pub fn attribute_completions(&self, node: &ast::ExprAttribute) -> Vec<Completion> {
         let ty = node.value.inferred_type(self);
-        crate::types::all_members(self.db, ty).into_iter().collect()
+        crate::types::all_members(self.db, ty)
+            .into_iter()
+            .map(|name| Completion {
+                name,
+                builtin: false,
+            })
+            .collect()
     }
 
     /// Returns completions for symbols available in the scope containing the
     /// given expression.
     ///
     /// If a scope could not be determined, then completions for the global
     /// scope of this model's `File` are returned.
-    pub fn scoped_completions(&self, node: ast::AnyNodeRef<'_>) -> Vec<Name> {
+    pub fn scoped_completions(&self, node: ast::AnyNodeRef<'_>) -> Vec<Completion> {
         let index = semantic_index(self.db, self.file);
 
         // TODO: We currently use `try_expression_scope_id` here as a hotfix for [1].
@@ -96,17 +114,37 @@ impl<'db> SemanticModel<'db> {
         }) else {
             return vec![];
         };
-        let mut symbols = vec![];
+        let mut completions = vec![];
         for (file_scope, _) in index.ancestor_scopes(file_scope) {
-            symbols.extend(all_declarations_and_bindings(
-                self.db,
-                file_scope.to_scope_id(self.db, self.file),
-            ));
+            completions.extend(
+                all_declarations_and_bindings(self.db, file_scope.to_scope_id(self.db, self.file))
+                    .map(|name| Completion {
+                        name,
+                        builtin: false,
+                    }),
+            );
         }
-        symbols
+        // Builtins are available in all scopes.
+        let builtins = ModuleName::new("builtins").expect("valid module name");
+        completions.extend(self.module_completions(&builtins));
+        completions
     }
 }
 
+/// A suggestion for code completion.
+#[derive(Clone, Debug)]
+pub struct Completion {
+    /// The label shown to the user for this suggestion.
+    pub name: Name,
+    /// Whether this suggestion came from builtins or not.
+    ///
+    /// At time of writing (2025-06-26), this information
+    /// doesn't make it into the LSP response. Instead, we
+    /// use it mainly in tests so that we can write less
+    /// noisy tests.
+    pub builtin: bool,
+}
+
 pub trait HasType {
     /// Returns the inferred type of `self`.
     ///

crates/ty_server/src/server/api/requests/completion.rs

@@ -56,7 +56,7 @@ impl BackgroundDocumentRequestHandler for CompletionRequestHandler {
             .into_iter()
             .enumerate()
             .map(|(i, comp)| CompletionItem {
-                label: comp.label,
+                label: comp.name.into(),
                 sort_text: Some(format!("{i:-max_index_len$}")),
                 ..Default::default()
             })

crates/ty_wasm/src/lib.rs

@@ -309,7 +309,7 @@ impl Workspace {
         Ok(completions
             .into_iter()
             .map(|completion| Completion {
-                label: completion.label,
+                name: completion.name.into(),
             })
             .collect())
     }
@@ -619,7 +619,7 @@ pub struct Hover {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Completion {
     #[wasm_bindgen(getter_with_clone)]
-    pub label: String,
+    pub name: String,
 }
 
 #[wasm_bindgen]