pyo3_stub_gen/lib.rs
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//! getters: &[
40//! MemberInfo {
41//! name: "name",
42//! r#type: <String as ::pyo3_stub_gen::PyStubType>::type_output,
43//! doc: "Name docstring",
44//! default: None,
45//! deprecated: None,
46//! },
47//! MemberInfo {
48//! name: "description",
49//! r#type: <Option<String> as ::pyo3_stub_gen::PyStubType>::type_output,
50//! doc: "Description docstring",
51//! default: None,
52//! deprecated: None,
53//! },
54//! ],
55//!
56//! setters: &[],
57//!
58//! doc: "Docstring used in Python",
59//!
60//! // Base classes
61//! bases: &[],
62//!
63//! // Decorated with `#[pyclass(eq, ord)]`
64//! has_eq: false,
65//! has_ord: false,
66//! // Decorated with `#[pyclass(hash, str)]`
67//! has_hash: false,
68//! has_str: false,
69//! }
70//! }
71//! ```
72//!
73//! Roughly speaking, the above corresponds a following stub file `my_module.pyi`:
74//!
75//! ```python
76//! class MyClass:
77//! """
78//! Docstring used in Python
79//! """
80//! name: str
81//! """Name docstring"""
82//! description: Optional[str]
83//! """Description docstring"""
84//! ```
85//!
86//! We want to generate this [type_info::PyClassInfo] section automatically from `MyClass` Rust struct definition.
87//! This is done by using `#[gen_stub_pyclass]` proc-macro:
88//!
89//! ```
90//! use pyo3::*;
91//! use pyo3_stub_gen::{type_info::*, derive::gen_stub_pyclass};
92//!
93//! // Usual PyO3 class definition
94//! #[gen_stub_pyclass]
95//! #[pyclass(module = "my_module", name = "MyClass")]
96//! struct MyClass {
97//! #[pyo3(get)]
98//! name: String,
99//! #[pyo3(get)]
100//! description: Option<String>,
101//! }
102//! ```
103//!
104//! Since proc-macro is a converter from Rust code to Rust code, the output must be a Rust code.
105//! However, we need to gather these [type_info::PyClassInfo] definitions to generate stub files,
106//! and the above [inventory::submit] is for it.
107//!
108//! Gather type information into [StubInfo]
109//! ----------------------------------------
110//! [inventory] crate provides a mechanism to gather [inventory::submit]ted information when the library is loaded.
111//! To access these information through [inventory::iter], we need to define a gather function in the crate.
112//! Typically, this is done by following:
113//!
114//! ```rust
115//! use pyo3_stub_gen::{StubInfo, Result};
116//!
117//! pub fn stub_info() -> Result<StubInfo> {
118//! let manifest_dir: &::std::path::Path = env!("CARGO_MANIFEST_DIR").as_ref();
119//! StubInfo::from_pyproject_toml(manifest_dir.join("pyproject.toml"))
120//! }
121//! ```
122//!
123//! There is a helper macro to define it easily:
124//!
125//! ```rust
126//! pyo3_stub_gen::define_stub_info_gatherer!(sub_info);
127//! ```
128//!
129//! Generate stub file from [StubInfo]
130//! -----------------------------------
131//! [StubInfo] translates [type_info::PyClassInfo] and other information into a form helpful for generating stub files while gathering.
132//!
133//! [generate] module provides structs implementing [std::fmt::Display] to generate corresponding parts of stub file.
134//! For example, [generate::MethodDef] generates Python class method definition as follows:
135//!
136//! ```rust
137//! use pyo3_stub_gen::{TypeInfo, generate::*};
138//!
139//! let method = MethodDef {
140//! name: "foo",
141//! args: vec![Arg { name: "x", r#type: TypeInfo::builtin("int"), signature: None, }],
142//! r#return: TypeInfo::builtin("int"),
143//! doc: "This is a foo method.",
144//! r#type: MethodType::Instance,
145//! deprecated: None,
146//! is_async: false,
147//! type_ignored: None,
148//! };
149//!
150//! assert_eq!(
151//! method.to_string().trim(),
152//! r#"
153//! def foo(self, x:builtins.int) -> builtins.int:
154//! r"""
155//! This is a foo method.
156//! """
157//! "#.trim()
158//! );
159//! ```
160//!
161//! [generate::ClassDef] generates Python class definition using [generate::MethodDef] and others, and other `*Def` structs works as well.
162//!
163//! [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.
164//! [generate::Module]s are created as a part of [StubInfo], which merges [type_info::PyClassInfo]s and others submitted to [inventory] separately.
165//! [StubInfo] is instantiated with [pyproject::PyProject] to get where to generate the stub file,
166//! and [StubInfo::generate] generates the stub files for every modules.
167//!
168
169pub use inventory;
170pub use pyo3_stub_gen_derive as derive; // re-export to use in generated code
171
172pub mod exception;
173pub mod generate;
174pub mod pyproject;
175pub mod rule_name;
176mod stub_type;
177pub mod type_info;
178pub mod util;
179
180pub use generate::StubInfo;
181pub use stub_type::{PyStubType, TypeInfo};
182
183pub type Result<T> = anyhow::Result<T>;
184
185/// Create a function to initialize [StubInfo] from `pyproject.toml` in `CARGO_MANIFEST_DIR`.
186///
187/// If `pyproject.toml` is in another place, you need to create a function to call [StubInfo::from_pyproject_toml] manually.
188/// This must be placed in your PyO3 library crate, i.e. same crate where [inventory::submit]ted,
189/// not in `gen_stub` executables due to [inventory] mechanism.
190///
191#[macro_export]
192macro_rules! define_stub_info_gatherer {
193 ($function_name:ident) => {
194 /// Auto-generated function to gather information to generate stub files
195 pub fn $function_name() -> $crate::Result<$crate::StubInfo> {
196 let manifest_dir: &::std::path::Path = env!("CARGO_MANIFEST_DIR").as_ref();
197 $crate::StubInfo::from_pyproject_toml(manifest_dir.join("pyproject.toml"))
198 }
199 };
200}
201
202#[macro_export]
203macro_rules! module_variable {
204 ($module:expr, $name:expr, $ty:ty) => {
205 $crate::inventory::submit! {
206 $crate::type_info::PyVariableInfo{
207 name: $name,
208 module: $module,
209 r#type: <$ty as $crate::PyStubType>::type_output,
210 }
211 }
212 };
213}
214
215#[doc = include_str!("../README.md")]
216mod readme {}