1//! This crate creates stub files in following three steps using [inventory] crate:
2//!
3//! Define type information in Rust code (or by proc-macro)
4//! ---------------------------------------------------------
5//! The first step is to define Python type information in Rust code. [type_info] module provides several structs, for example:
6//!
7//! - [type_info::PyFunctionInfo] stores information of Python function, i.e. the name of the function, arguments and its types, return type, etc.
8//! - [type_info::PyClassInfo] stores information for Python class definition, i.e. the name of the class, members and its types, methods, etc.
9//!
10//! For better understanding of what happens in the background, let's define these information manually:
11//!
12//! ```
13//! use pyo3::*;
14//! use pyo3_stub_gen::type_info::*;
15//!
16//! // Usual PyO3 class definition
17//! #[pyclass(module = "my_module", name = "MyClass")]
18//! struct MyClass {
19//! #[pyo3(get)]
20//! name: String,
21//! #[pyo3(get)]
22//! description: Option<String>,
23//! }
24//!
25//! // Submit type information for stub file generation to inventory
26//! inventory::submit!{
27//! // Send information about Python class
28//! PyClassInfo {
29//! // Type ID of Rust struct (used to gathering phase discussed later)
30//! struct_id: std::any::TypeId::of::<MyClass>,
31//!
32//! // Python module name. Since stub file is generated per modules,
33//! // this helps where the class definition should be placed.
34//! module: Some("my_module"),
35//!
36//! // Python class name
37//! pyclass_name: "MyClass",
38//!
39//! members: &[
40//! MemberInfo {
41//! name: "name",
42//! r#type: <String as ::pyo3_stub_gen::PyStubType>::type_output,
43//! },
44//! MemberInfo {
45//! name: "description",
46//! r#type: <Option<String> as ::pyo3_stub_gen::PyStubType>::type_output,
47//! },
48//! ],
49//! doc: "Docstring used in Python",
50//! }
51//! }
52//! ```
53//!
54//! Roughly speaking, the above corresponds a following stub file `my_module.pyi`:
55//!
56//! ```python
57//! class MyClass:
58//! """
59//! Docstring used in Python
60//! """
61//! name: str
62//! description: Optional[str]
63//! ```
64//!
65//! We want to generate this [type_info::PyClassInfo] section automatically from `MyClass` Rust struct definition.
66//! This is done by using `#[gen_stub_pyclass]` proc-macro:
67//!
68//! ```
69//! use pyo3::*;
70//! use pyo3_stub_gen::{type_info::*, derive::gen_stub_pyclass};
71//!
72//! // Usual PyO3 class definition
73//! #[gen_stub_pyclass]
74//! #[pyclass(module = "my_module", name = "MyClass")]
75//! struct MyClass {
76//! #[pyo3(get)]
77//! name: String,
78//! #[pyo3(get)]
79//! description: Option<String>,
80//! }
81//! ```
82//!
83//! Since proc-macro is a converter from Rust code to Rust code, the output must be a Rust code.
84//! However, we need to gather these [type_info::PyClassInfo] definitions to generate stub files,
85//! and the above [inventory::submit] is for it.
86//!
87//! Gather type information into [StubInfo]
88//! ----------------------------------------
89//! [inventory] crate provides a mechanism to gather [inventory::submit]ted information when the library is loaded.
90//! To access these information through [inventory::iter], we need to define a gather function in the crate.
91//! Typically, this is done by following:
92//!
93//! ```rust
94//! use pyo3_stub_gen::{StubInfo, Result};
95//!
96//! pub fn stub_info() -> Result<StubInfo> {
97//! let manifest_dir: &::std::path::Path = env!("CARGO_MANIFEST_DIR").as_ref();
98//! StubInfo::from_pyproject_toml(manifest_dir.join("pyproject.toml"))
99//! }
100//! ```
101//!
102//! There is a helper macro to define it easily:
103//!
104//! ```rust
105//! pyo3_stub_gen::define_stub_info_gatherer!(sub_info);
106//! ```
107//!
108//! Generate stub file from [StubInfo]
109//! -----------------------------------
110//! [StubInfo] translates [type_info::PyClassInfo] and other information into a form helpful for generating stub files while gathering.
111//!
112//! [generate] module provides structs implementing [std::fmt::Display] to generate corresponding parts of stub file.
113//! For example, [generate::MethodDef] generates Python class method definition as follows:
114//!
115//! ```rust
116//! use pyo3_stub_gen::{TypeInfo, generate::*};
117//!
118//! let method = MethodDef {
119//! name: "foo",
120//! args: vec![Arg { name: "x", r#type: TypeInfo::builtin("int"), signature: None, }],
121//! r#return: TypeInfo::builtin("int"),
122//! doc: "This is a foo method.",
123//! is_static: false,
124//! is_class: false,
125//! };
126//!
127//! assert_eq!(
128//! method.to_string().trim(),
129//! r#"
130//! def foo(self, x:builtins.int) -> builtins.int:
131//! r"""
132//! This is a foo method.
133//! """
134//! ...
135//! "#.trim()
136//! );
137//! ```
138//!
139//! [generate::ClassDef] generates Python class definition using [generate::MethodDef] and others, and other `*Def` structs works as well.
140//!
141//! [generate::Module] consists of `*Def` structs and yields an entire stub file `*.pyi` for a single Python (sub-)module, i.e. a shared library build by PyO3.
142//! [generate::Module]s are created as a part of [StubInfo], which merges [type_info::PyClassInfo]s and others submitted to [inventory] separately.
143//! [StubInfo] is instantiated with [pyproject::PyProject] to get where to generate the stub file,
144//! and [StubInfo::generate] generates the stub files for every modules.
145//!
146
147pub use inventory;
148pub use pyo3_stub_gen_derive as derive; // re-export to use in generated code
149
150pub mod exception;
151pub mod generate;
152pub mod pyproject;
153mod stub_type;
154pub mod type_info;
155pub mod util;
156
157pub use generate::StubInfo;
158pub use stub_type::{PyStubType, TypeInfo};
159
160pub type Result<T> = anyhow::Result<T>;
161
162/// Create a function to initialize [StubInfo] from `pyproject.toml` in `CARGO_MANIFEST_DIR`.
163///
164/// If `pyproject.toml` is in another place, you need to create a function to call [StubInfo::from_pyproject_toml] manually.
165/// This must be placed in your PyO3 library crate, i.e. same crate where [inventory::submit]ted,
166/// not in `gen_stub` executables due to [inventory] mechanism.
167///
168#[macro_export]
169macro_rules! define_stub_info_gatherer {
170 ($function_name:ident) => {
171 /// Auto-generated function to gather information to generate stub files
172 pub fn $function_name() -> $crate::Result<$crate::StubInfo> {
173 let manifest_dir: &::std::path::Path = env!("CARGO_MANIFEST_DIR").as_ref();
174 $crate::StubInfo::from_pyproject_toml(manifest_dir.join("pyproject.toml"))
175 }
176 };
177}
178
179#[macro_export]
180macro_rules! module_variable {
181 ($module:expr, $name:expr, $ty:ty) => {
182 $crate::inventory::submit! {
183 $crate::type_info::PyVariableInfo{
184 name: $name,
185 module: $module,
186 r#type: <$ty as $crate::PyStubType>::type_output,
187 }
188 }
189 };
190}
191