fix: qualifies builtins types in TypeInfo::builtin (#139)

Builtin type identifiers like `int` or `string` can be shadowed with
local definitions. This PR avoids that by importing `builtins` module
and qualifies identifier with it. There is still the case where
`builtins` can accidentally redefined, but at least this change saves
corner cases.

Cargo.toml

@@ -38,3 +38,4 @@ quote = "1.0.38"
 serde = { version = "1.0.217", features = ["derive"] }
 syn = "2.0.96"
 toml = "0.8.19"
+test-case = "3.3.1"

examples/mixed/python/mixed/main_mod.pyi

@@ -1,6 +1,7 @@
 # This file is automatically generated by pyo3_stub_gen
 # ruff: noqa: E501, F401
 
+import builtins
 
 class A:
     def show_x(self) -> None:
@@ -12,9 +13,9 @@ class B:
         ...
 
 
-def create_a(x:int) -> A:
+def create_a(x:builtins.int) -> A:
     ...
 
-def create_b(x:int) -> B:
+def create_b(x:builtins.int) -> B:
     ...
 

examples/mixed_sub/python/mixed_sub/main_mod/__init__.pyi

@@ -1,6 +1,8 @@
 # This file is automatically generated by pyo3_stub_gen
 # ruff: noqa: E501, F401
 
+import builtins
+from . import int
 from . import sub_mod
 
 class A:
@@ -13,9 +15,9 @@ class B:
         ...
 
 
-def create_a(x:int) -> A:
+def create_a(x:builtins.int) -> A:
     ...
 
-def create_b(x:int) -> B:
+def create_b(x:builtins.int) -> B:
     ...
 

examples/mixed_sub/python/mixed_sub/main_mod/int.pyi

@@ -0,0 +1,8 @@
+# This file is automatically generated by pyo3_stub_gen
+# ruff: noqa: E501, F401
+
+import builtins
+
+def dummy_int_fun(x:builtins.int) -> builtins.int:
+    ...
+

examples/mixed_sub/python/mixed_sub/main_mod/sub_mod.pyi

@@ -1,12 +1,13 @@
 # This file is automatically generated by pyo3_stub_gen
 # ruff: noqa: E501, F401
 
+import builtins
 
 class C:
     def show_x(self) -> None:
         ...
 
 
-def create_c(x:int) -> C:
+def create_c(x:builtins.int) -> C:
     ...
 

examples/mixed_sub/src/lib.rs

@@ -68,13 +68,20 @@ fn create_c(x: usize) -> C {
     C { x }
 }
 
+#[gen_stub_pyfunction(module = "mixed_sub.main_mod.int")]
+#[pyfunction]
+fn dummy_int_fun(x: usize) -> usize {
+    x
+}
+
 #[pymodule]
 fn main_mod(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_class::<A>()?;
     m.add_class::<B>()?;
     m.add_function(wrap_pyfunction!(create_a, m)?)?;
     m.add_function(wrap_pyfunction!(create_b, m)?)?;
     sub_mod(m)?;
+    int_mod(m)?;
     Ok(())
 }
 
@@ -87,6 +94,15 @@ fn sub_mod(parent: &Bound<PyModule>) -> PyResult<()> {
     Ok(())
 }
 
+/// A dummy module to pollute namespace with unqualified `int`
+fn int_mod(parent: &Bound<PyModule>) -> PyResult<()> {
+    let py = parent.py();
+    let sub = PyModule::new(py, "int")?;
+    sub.add_function(wrap_pyfunction!(dummy_int_fun, &sub)?)?;
+    parent.add_submodule(&sub)?;
+    Ok(())
+}
+
 define_stub_info_gatherer!(stub_info);
 
 /// Test of unit test for testing link problem

examples/pure/pure.pyi

@@ -1,15 +1,16 @@
 # This file is automatically generated by pyo3_stub_gen
 # ruff: noqa: E501, F401
 
+import builtins
 import os
 import pathlib
 import typing
 from enum import Enum, auto
 
-MY_CONSTANT: int
+MY_CONSTANT: builtins.int
 class A:
-    x: int
-    def __new__(cls,x:int): ...
+    x: builtins.int
+    def __new__(cls,x:builtins.int): ...
     def show_x(self) -> None:
         ...
 
@@ -21,31 +22,31 @@ class Number(Enum):
     FLOAT = auto()
     INTEGER = auto()
 
-def ahash_dict() -> dict[str, int]:
+def ahash_dict() -> builtins.dict[builtins.str, builtins.int]:
     ...
 
-def create_a(x:int=2) -> A:
+def create_a(x:builtins.int=2) -> A:
     ...
 
-def create_dict(n:int) -> dict[int, list[int]]:
+def create_dict(n:builtins.int) -> builtins.dict[builtins.int, builtins.list[builtins.int]]:
     ...
 
 def default_value(num:Number=...) -> Number:
     ...
 
-def echo_path(path:str | os.PathLike | pathlib.Path) -> str:
+def echo_path(path:builtins.str | os.PathLike | pathlib.Path) -> builtins.str:
     ...
 
-def read_dict(dict:typing.Mapping[int, typing.Mapping[int, int]]) -> None:
+def read_dict(dict:typing.Mapping[builtins.int, typing.Mapping[builtins.int, builtins.int]]) -> None:
     ...
 
-def str_len(x:str) -> int:
+def str_len(x:builtins.str) -> builtins.int:
     r"""
     Returns the length of the string.
     """
     ...
 
-def sum(v:typing.Sequence[int]) -> int:
+def sum(v:typing.Sequence[builtins.int]) -> builtins.int:
     r"""
     Returns the sum of two numbers as a string.
     """

pyo3-stub-gen/Cargo.toml

@@ -25,6 +25,9 @@ toml.workspace = true
 version = "0.7.0"
 path = "../pyo3-stub-gen-derive"
 
+[dev-dependencies]
+test-case.workspace = true
+
 [features]
 default = ["numpy"]
 numpy = ["dep:numpy"]

pyo3-stub-gen/src/lib.rs

@@ -127,7 +127,7 @@
 //! assert_eq!(
 //!     method.to_string().trim(),
 //!     r#"
-//!     def foo(self, x:int) -> int:
+//!     def foo(self, x:builtins.int) -> builtins.int:
 //!         r"""
 //!         This is a foo method.
 //!         """

pyo3-stub-gen/src/stub_type.rs

@@ -61,6 +61,8 @@ impl fmt::Display for TypeInfo {
 impl TypeInfo {
     /// A `None` type annotation.
     pub fn none() -> Self {
+        // NOTE: since 3.10, NoneType is provided from types module,
+        // but there is no corresponding definitions prior to 3.10.
         Self {
             name: "None".to_string(),
             import: HashSet::new(),
@@ -75,11 +77,57 @@ impl TypeInfo {
         }
     }
 
-    /// A type annotation of a built-in type, such as `int`, `str`, or `float`. Generic builtin types are also possible, such as `dict[str, str]`.
+    /// A `list[Type]` type annotation.
+    pub fn list_of<T: PyStubType>() -> Self {
+        let TypeInfo { name, mut import } = T::type_output();
+        import.insert("builtins".into());
+        TypeInfo {
+            name: format!("builtins.list[{}]", name),
+            import,
+        }
+    }
+
+    /// A `set[Type]` type annotation.
+    pub fn set_of<T: PyStubType>() -> Self {
+        let TypeInfo { name, mut import } = T::type_output();
+        import.insert("builtins".into());
+        TypeInfo {
+            name: format!("builtins.set[{}]", name),
+            import,
+        }
+    }
+
+    /// A `dict[Type]` type annotation.
+    pub fn dict_of<K: PyStubType, V: PyStubType>() -> Self {
+        let TypeInfo {
+            name: name_k,
+            mut import,
+        } = K::type_output();
+        let TypeInfo {
+            name: name_v,
+            import: import_v,
+        } = V::type_output();
+        import.extend(import_v);
+        import.insert("builtins".into());
+        TypeInfo {
+            name: format!("builtins.set[{}, {}]", name_k, name_v),
+            import,
+        }
+    }
+
+    /// A type annotation of a built-in type provided from `builtins` module, such as `int`, `str`, or `float`. Generic builtin types are also possible, such as `dict[str, str]`.
     pub fn builtin(name: &str) -> Self {
+        Self {
+            name: format!("builtins.{name}"),
+            import: hashset! { "builtins".into() },
+        }
+    }
+
+    /// Unqualified type.
+    pub fn unqualified(name: &str) -> Self {
         Self {
             name: name.to_string(),
-            import: HashSet::new(),
+            import: hashset! {},
         }
     }
 
@@ -182,49 +230,23 @@ mod test {
     use super::*;
     use maplit::hashset;
     use std::collections::HashMap;
-
-    #[test]
-    fn test() {
-        assert_eq!(bool::type_input().name, "bool");
-        assert!(bool::type_input().import.is_empty());
-
-        assert_eq!(<&str>::type_input().name, "str");
-        assert!(<&str>::type_input().import.is_empty());
-
-        assert_eq!(Vec::<u32>::type_input().name, "typing.Sequence[int]");
-        assert_eq!(
-            Vec::<u32>::type_input().import,
-            hashset! { "typing".into() }
-        );
-
-        assert_eq!(Vec::<u32>::type_output().name, "list[int]");
-        assert!(Vec::<u32>::type_output().import.is_empty());
-
-        assert_eq!(
-            HashMap::<u32, String>::type_input().name,
-            "typing.Mapping[int, str]"
-        );
-        assert_eq!(
-            HashMap::<u32, String>::type_input().import,
-            hashset! { "typing".into() }
-        );
-
-        assert_eq!(HashMap::<u32, String>::type_output().name, "dict[int, str]");
-        assert!(HashMap::<u32, String>::type_output().import.is_empty());
-
-        assert_eq!(
-            HashMap::<u32, Vec<u32>>::type_input().name,
-            "typing.Mapping[int, typing.Sequence[int]]"
-        );
-        assert_eq!(
-            HashMap::<u32, Vec<u32>>::type_input().import,
-            hashset! { "typing".into() }
-        );
-
-        assert_eq!(
-            HashMap::<u32, Vec<u32>>::type_output().name,
-            "dict[int, list[int]]"
-        );
-        assert!(HashMap::<u32, Vec<u32>>::type_output().import.is_empty());
+    use test_case::test_case;
+
+    #[test_case(bool::type_input(), "builtins.bool", hashset! { "builtins".into() } ; "bool_input")]
+    #[test_case(<&str>::type_input(), "builtins.str", hashset! { "builtins".into() } ; "str_input")]
+    #[test_case(Vec::<u32>::type_input(), "typing.Sequence[builtins.int]", hashset! { "typing".into(), "builtins".into() } ; "Vec_u32_input")]
+    #[test_case(Vec::<u32>::type_output(), "builtins.list[builtins.int]", hashset! {  "builtins".into() } ; "Vec_u32_output")]
+    #[test_case(HashMap::<u32, String>::type_input(), "typing.Mapping[builtins.int, builtins.str]", hashset! { "typing".into(), "builtins".into() } ; "HashMap_u32_String_input")]
+    #[test_case(HashMap::<u32, String>::type_output(), "builtins.dict[builtins.int, builtins.str]", hashset! { "builtins".into() } ; "HashMap_u32_String_output")]
+    #[test_case(HashMap::<u32, Vec<u32>>::type_input(), "typing.Mapping[builtins.int, typing.Sequence[builtins.int]]", hashset! { "builtins".into(), "typing".into() } ; "HashMap_u32_Vec_u32_input")]
+    #[test_case(HashMap::<u32, Vec<u32>>::type_output(), "builtins.dict[builtins.int, builtins.list[builtins.int]]", hashset! { "builtins".into() } ; "HashMap_u32_Vec_u32_output")]
+    #[test_case(HashSet::<u32>::type_input(), "builtins.set[builtins.int]", hashset! { "builtins".into() } ; "HashSet_u32_input")]
+    fn test(tinfo: TypeInfo, name: &str, import: HashSet<ModuleRef>) {
+        assert_eq!(tinfo.name, name);
+        if import.is_empty() {
+            assert!(tinfo.import.is_empty());
+        } else {
+            assert_eq!(tinfo.import, import);
+        }
     }
 }

pyo3-stub-gen/src/stub_type/builtins.rs

@@ -14,10 +14,7 @@ macro_rules! impl_builtin {
     ($ty:ty, $pytype:expr) => {
         impl PyStubType for $ty {
             fn type_output() -> TypeInfo {
-                TypeInfo {
-                    name: $pytype.to_string(),
-                    import: HashSet::new(),
-                }
+                TypeInfo::builtin($pytype)
             }
         }
     };
@@ -33,7 +30,12 @@ macro_rules! impl_with_module {
     };
 }
 
-impl_builtin!((), "None");
+// NOTE:
+impl PyStubType for () {
+    fn type_output() -> TypeInfo {
+        TypeInfo::none()
+    }
+}
 impl_builtin!(bool, "bool");
 impl_builtin!(u8, "int");
 impl_builtin!(u16, "int");