pyo3_stub_gen/generate/
stub_info.rs

1use crate::{generate::*, pyproject::PyProject, type_info::*};
2use anyhow::{Context, Result};
3use std::{
4    collections::{BTreeMap, BTreeSet},
5    fs,
6    io::Write,
7    path::*,
8};
9
10#[derive(Debug, Clone, PartialEq)]
11pub struct StubInfo {
12    pub modules: BTreeMap<String, Module>,
13    pub python_root: PathBuf,
14}
15
16impl StubInfo {
17    /// Initialize [StubInfo] from a `pyproject.toml` file in `CARGO_MANIFEST_DIR`.
18    /// This is automatically set up by the [crate::define_stub_info_gatherer] macro.
19    pub fn from_pyproject_toml(path: impl AsRef<Path>) -> Result<Self> {
20        let pyproject = PyProject::parse_toml(path)?;
21        Ok(StubInfoBuilder::from_pyproject_toml(pyproject).build())
22    }
23
24    /// Initialize [StubInfo] with a specific module name and project root.
25    /// This must be placed in your PyO3 library crate, i.e. the same crate where [inventory::submit]ted,
26    /// not in the `gen_stub` executables due to [inventory]'s mechanism.
27    pub fn from_project_root(default_module_name: String, project_root: PathBuf) -> Result<Self> {
28        Ok(StubInfoBuilder::from_project_root(default_module_name, project_root).build())
29    }
30
31    pub fn generate(&self) -> Result<()> {
32        for (name, module) in self.modules.iter() {
33            // Convert dashes to underscores for Python compatibility
34            let normalized_name = name.replace("-", "_");
35            let path = normalized_name.replace(".", "/");
36            let dest = if module.submodules.is_empty() {
37                self.python_root.join(format!("{path}.pyi"))
38            } else {
39                self.python_root.join(path).join("__init__.pyi")
40            };
41
42            let dir = dest.parent().context("Cannot get parent directory")?;
43            if !dir.exists() {
44                fs::create_dir_all(dir)?;
45            }
46
47            let mut f = fs::File::create(&dest)?;
48            write!(f, "{module}")?;
49            log::info!(
50                "Generate stub file of a module `{name}` at {dest}",
51                dest = dest.display()
52            );
53        }
54        Ok(())
55    }
56}
57
58struct StubInfoBuilder {
59    modules: BTreeMap<String, Module>,
60    default_module_name: String,
61    python_root: PathBuf,
62}
63
64impl StubInfoBuilder {
65    fn from_pyproject_toml(pyproject: PyProject) -> Self {
66        StubInfoBuilder::from_project_root(
67            pyproject.module_name().to_string(),
68            pyproject
69                .python_source()
70                .unwrap_or(PathBuf::from(std::env::var("CARGO_MANIFEST_DIR").unwrap())),
71        )
72    }
73
74    fn from_project_root(default_module_name: String, project_root: PathBuf) -> Self {
75        Self {
76            modules: BTreeMap::new(),
77            default_module_name,
78            python_root: project_root,
79        }
80    }
81
82    fn get_module(&mut self, name: Option<&str>) -> &mut Module {
83        let name = name.unwrap_or(&self.default_module_name).to_string();
84        let module = self.modules.entry(name.clone()).or_default();
85        module.name = name;
86        module.default_module_name = self.default_module_name.clone();
87        module
88    }
89
90    fn register_submodules(&mut self) {
91        let mut map: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
92        for module in self.modules.keys() {
93            let path = module.split('.').collect::<Vec<_>>();
94            let n = path.len();
95            if n <= 1 {
96                continue;
97            }
98            map.entry(path[..n - 1].join("."))
99                .or_default()
100                .insert(path[n - 1].to_string());
101        }
102        for (parent, children) in map {
103            if let Some(module) = self.modules.get_mut(&parent) {
104                module.submodules.extend(children);
105            }
106        }
107    }
108
109    fn add_class(&mut self, info: &PyClassInfo) {
110        self.get_module(info.module)
111            .class
112            .insert((info.struct_id)(), ClassDef::from(info));
113    }
114
115    fn add_complex_enum(&mut self, info: &PyComplexEnumInfo) {
116        self.get_module(info.module)
117            .class
118            .insert((info.enum_id)(), ClassDef::from(info));
119    }
120
121    fn add_enum(&mut self, info: &PyEnumInfo) {
122        self.get_module(info.module)
123            .enum_
124            .insert((info.enum_id)(), EnumDef::from(info));
125    }
126
127    fn add_function(&mut self, info: &PyFunctionInfo) {
128        let target = self
129            .get_module(info.module)
130            .function
131            .entry(info.name)
132            .or_default();
133        target.push(FunctionDef::from(info));
134    }
135
136    fn add_variable(&mut self, info: &PyVariableInfo) {
137        self.get_module(Some(info.module))
138            .variables
139            .insert(info.name, VariableDef::from(info));
140    }
141
142    fn add_methods(&mut self, info: &PyMethodsInfo) {
143        let struct_id = (info.struct_id)();
144        for module in self.modules.values_mut() {
145            if let Some(entry) = module.class.get_mut(&struct_id) {
146                for attr in info.attrs {
147                    entry.attrs.push(MemberDef {
148                        name: attr.name,
149                        r#type: (attr.r#type)(),
150                        doc: attr.doc,
151                        default: attr.default.map(|s| s.as_str()),
152                        deprecated: attr.deprecated.clone(),
153                    });
154                }
155                for getter in info.getters {
156                    entry.getters.push(MemberDef {
157                        name: getter.name,
158                        r#type: (getter.r#type)(),
159                        doc: getter.doc,
160                        default: getter.default.map(|s| s.as_str()),
161                        deprecated: getter.deprecated.clone(),
162                    });
163                }
164                for setter in info.setters {
165                    entry.setters.push(MemberDef {
166                        name: setter.name,
167                        r#type: (setter.r#type)(),
168                        doc: setter.doc,
169                        default: setter.default.map(|s| s.as_str()),
170                        deprecated: setter.deprecated.clone(),
171                    });
172                }
173                for method in info.methods {
174                    let entries = entry.methods.entry(method.name.to_string()).or_default();
175                    entries.push(MethodDef::from(method));
176                }
177                return;
178            } else if let Some(entry) = module.enum_.get_mut(&struct_id) {
179                for attr in info.attrs {
180                    entry.attrs.push(MemberDef {
181                        name: attr.name,
182                        r#type: (attr.r#type)(),
183                        doc: attr.doc,
184                        default: attr.default.map(|s| s.as_str()),
185                        deprecated: attr.deprecated.clone(),
186                    });
187                }
188                for getter in info.getters {
189                    entry.getters.push(MemberDef {
190                        name: getter.name,
191                        r#type: (getter.r#type)(),
192                        doc: getter.doc,
193                        default: getter.default.map(|s| s.as_str()),
194                        deprecated: getter.deprecated.clone(),
195                    });
196                }
197                for setter in info.setters {
198                    entry.setters.push(MemberDef {
199                        name: setter.name,
200                        r#type: (setter.r#type)(),
201                        doc: setter.doc,
202                        default: setter.default.map(|s| s.as_str()),
203                        deprecated: setter.deprecated.clone(),
204                    });
205                }
206                for method in info.methods {
207                    entry.methods.push(MethodDef::from(method))
208                }
209                return;
210            }
211        }
212        unreachable!("Missing struct_id/enum_id = {:?}", struct_id);
213    }
214
215    fn build(mut self) -> StubInfo {
216        for info in inventory::iter::<PyClassInfo> {
217            self.add_class(info);
218        }
219        for info in inventory::iter::<PyComplexEnumInfo> {
220            self.add_complex_enum(info);
221        }
222        for info in inventory::iter::<PyEnumInfo> {
223            self.add_enum(info);
224        }
225        for info in inventory::iter::<PyFunctionInfo> {
226            self.add_function(info);
227        }
228        for info in inventory::iter::<PyVariableInfo> {
229            self.add_variable(info);
230        }
231        for info in inventory::iter::<PyMethodsInfo> {
232            self.add_methods(info);
233        }
234        self.register_submodules();
235        StubInfo {
236            modules: self.modules,
237            python_root: self.python_root,
238        }
239    }
240}
pyo3_stub_gen/generate/stub_info.rs

pyo3_stub_gen/generate/
stub_info.rs
