Debian Codegraph @

guide/src/tutorial.md

raw
1 # Tutorial
2
3 In this tutorial we will wrap a version of [the guessing game from The Rust
4 Book](https://doc.rust-lang.org/book/ch02-00-guessing-game-tutorial.html) to
5 run in Python using pyo3.
6
7 ## Create a new Rust project
8
9 First, create a new Rust library project using `cargo new --lib --edition 2021
10 guessing-game`. This will create a directory with the following structure.
11
12 ```ignore
13 guessing-game/
14 ├── Cargo.toml
15 └── src
16 └── lib.rs
17 ```
18
19 Edit `Cargo.toml` to configure the project and module name, and add the
20 dependencies (`rand` and `pyo3`). Configure `pyo3` with additional features to
21 make an extension module compatible with multiple Python versions using the
22 stable ABI (`abi3`).
23
24 ```toml
25 [package]
26 name = "guessing-game"
27 version = "0.1.0"
28 edition = "2021"
29
30 [lib]
31 name = "guessing_game"
32 # "cdylib" is necessary to produce a shared library for Python to import from.
33 crate-type = ["cdylib"]
34
35 [dependencies]
36 rand = "0.9.0"
37
38 [dependencies.pyo3]
39 version = "0.24.0"
40 # "abi3-py38" tells pyo3 (and maturin) to build using the stable ABI with minimum Python version 3.8
41 features = ["abi3-py38"]
42 ```
43
44 Add a `pyproject.toml` to configure [PEP 518](https://peps.python.org/pep-0518/) build system requirements
45 and enable the `extension-module` feature of pyo3.
46
47 ```toml
48 [build-system]
49 requires = ["maturin>=1.0,<2.0"]
50 build-backend = "maturin"
51
52 [tool.maturin]
53 # "extension-module" tells pyo3 we want to build an extension module (skips linking against libpython.so)
54 features = ["pyo3/extension-module"]
55 ```
56
57 ### Use `maturin new`
58
59 New projects can also be quickly created using the `maturin new` command:
60
61 ```bash
62 maturin new --help
63 Create a new cargo project
64
65 Usage: maturin new [OPTIONS] <PATH>
66
67 Arguments:
68 <PATH> Project path
69
70 Options:
71 --name <NAME> Set the resulting package name, defaults to the directory name
72 --mixed Use mixed Rust/Python project layout
73 --src Use Python first src layout for mixed Rust/Python project
74 -b, --bindings <BINDINGS> Which kind of bindings to use [possible values: pyo3, cffi, uniffi, bin]
75 -h, --help Print help information
76 ```
77
78 The above process can be achieved by running `maturin new -b pyo3 guessing_game`
79 then edit `Cargo.toml` to add `abi3-py38` feature.
80
81 ## Install and configure maturin (in a virtual environment)
82
83 Create a virtual environment and install maturin. Note maturin has minimal
84 dependencies!
85
86 ```shell
87 ferris@rustbox [~/src/rust/guessing-game] % python3 -m venv .venv
88 ferris@rustbox [~/src/rust/guessing-game] % source .venv/bin/activate
89 (.venv) ferris@rustbox [~/src/rust/guessing-game] % pip install -U pip maturin
90 (.venv) ferris@rustbox [~/src/rust/guessing-game] % pip freeze
91 maturin==1.3.0
92 tomli==2.0.1
93 ```
94
95 maturin is configured in `pyproject.toml` as introduced by [PEP
96 518](https://www.python.org/dev/peps/pep-0518/). This file lives in the root
97 of your project tree:
98
99 ```ignore
100 guessing-game/
101 ├── Cargo.toml
102 ├── pyproject.toml # <<< add this file
103 └── src
104 └── lib.rs
105 ```
106
107 Configuration in this file is quite simple for most projects. You just need to
108 indicate maturin as a requirement (and restrict the version) and as the
109 build-backend (Python supports a number of build-backends since [PEP
110 517](https://www.python.org/dev/peps/pep-0517/)).
111
112 ```toml
113 [build-system]
114 requires = ["maturin>=1.0,<2.0"]
115 build-backend = "maturin"
116 ```
117
118 Various other tools may also be configured in `pyproject.toml` and the Python
119 community seems to be consolidating declarative configuration in this file.
120
121 ## Program the guessing game in Rust
122
123 When you create a `lib` project with `cargo new` it creates a file
124 `src/lib.rs` with some default code. Edit that file and replace the default
125 code with the code below. As mentioned, we will implement a slightly
126 modified version of [the guessing game from The Rust
127 Book](https://doc.rust-lang.org/book/ch02-00-guessing-game-tutorial.html).
128 Instead of implementing as a `bin` crate, we're using a `lib` and will expose
129 the main logic as a Python function.
130
131 ```rust,no_run
132 use pyo3::prelude::*;
133 use rand::Rng;
134 use std::cmp::Ordering;
135 use std::io;
136
137 #[pyfunction]
138 fn guess_the_number() {
139 println!("Guess the number!");
140
141 let secret_number = rand::rng().random_range(1..101);
142
143 loop {
144 println!("Please input your guess.");
145
146 let mut guess = String::new();
147
148 io::stdin()
149 .read_line(&mut guess)
150 .expect("Failed to read line");
151
152 let guess: u32 = match guess.trim().parse() {
153 Ok(num) => num,
154 Err(_) => continue,
155 };
156
157 println!("You guessed: {}", guess);
158
159 match guess.cmp(&secret_number) {
160 Ordering::Less => println!("Too small!"),
161 Ordering::Greater => println!("Too big!"),
162 Ordering::Equal => {
163 println!("You win!");
164 break;
165 }
166 }
167 }
168 }
169
170 /// A Python module implemented in Rust. The name of this function must match
171 /// the `lib.name` setting in the `Cargo.toml`, else Python will not be able to
172 /// import the module.
173 #[pymodule]
174 fn guessing_game(m: &Bound<'_, PyModule>) -> PyResult<()> {
175 m.add_function(wrap_pyfunction!(guess_the_number, m)?)?;
176
177 Ok(())
178 }
179 ```
180
181 Thanks to pyo3, there's very little difference between this and the example in
182 The Rust Book. All we had to do was:
183
184 1. Include the pyo3 prelude
185 2. Add `#[pyfunction]` to our function
186 3. Add the `#[pymodule]` block to expose the function as part of a Python module
187
188 Refer to the [pyo3 User Guide](https://pyo3.rs/) for more information on using
189 pyo3. It can do a lot more!
190
191 ## Build and install the module with `maturin develop`
192
193 Note that _this is just a Rust project_ at this point, and with few exceptions
194 you can build it as you'd expect using `cargo build`. maturin helps with this,
195 however, adding some platform-specific build configuration and ultimately
196 packaging the binary results as a wheel (a `.whl` file, which is an archive of
197 compiled components suitable for installation with `pip`, the Python package
198 manager).
199
200 So let's use maturin to build and install in our current environment.
201
202 You can also compile a performance-optimized program by adding the `-r` or `--release` flag for speed testing.
203
204 ```shell
205 (.venv) ferris@rustbox [~/src/rust/guessing-game] % maturin develop
206 🔗 Found pyo3 bindings with abi3 support for Python ≥ 3.8
207 🐍 Not using a specific python interpreter (With abi3, an interpreter is only required on windows)
208 Compiling pyo3-build-config v0.23.1
209 Compiling libc v0.2.119
210 Compiling once_cell v1.10.0
211 Compiling cfg-if v1.0.0
212 Compiling proc-macro2 v1.0.36
213 Compiling unicode-xid v0.2.2
214 Compiling syn v1.0.86
215 Compiling parking_lot_core v0.8.5
216 Compiling smallvec v1.8.0
217 Compiling scopeguard v1.1.0
218 Compiling unindent v0.1.8
219 Compiling ppv-lite86 v0.2.16
220 Compiling instant v0.1.12
221 Compiling lock_api v0.4.6
222 Compiling indoc v1.0.4
223 Compiling getrandom v0.2.5
224 Compiling rand_core v0.6.3
225 Compiling parking_lot v0.11.2
226 Compiling rand_chacha v0.3.1
227 Compiling rand v0.8.5
228 Compiling quote v1.0.15
229 Compiling pyo3-ffi v0.23.1
230 Compiling pyo3 v0.23.1
231 Compiling pyo3-macros-backend v0.23.1
232 Compiling pyo3-macros v0.23.1
233 Compiling guessing-game v0.1.0 (/Users/ferris/src/rust/guessing-game)
234 Finished dev [unoptimized + debuginfo] target(s) in 13.31s
235 ```
236
237 Your `guessing_game` module should now be available in your current virtual
238 environment. Go ahead and play a few games!
239
240 ```shell
241 (.venv) ferris@rustbox [~/src/rust/guessing-game] % python
242 Python 3.9.6 (default, Aug 25 2021, 16:04:27)
243 [Clang 12.0.5 (clang-1205.0.22.9)] on darwin
244 Type "help", "copyright", "credits" or "license" for more information.
245 >>> import guessing_game
246 >>> guessing_game.guess_the_number()
247 Guess the number!
248 Please input your guess.
249 42
250 You guessed: 42
251 Too small!
252 Please input your guess.
253 80
254 You guessed: 80
255 Too big!
256 Please input your guess.
257 50
258 You guessed: 50
259 Too small!
260 Please input your guess.
261 60
262 You guessed: 60
263 Too big!
264 Please input your guess.
265 55
266 You guessed: 55
267 You win!
268 ```
269
270 ## Create a wheel for distribution
271
272 `maturin develop` actually skips the wheel generation part and installs
273 directly in the current environment. `maturin build` on the other hand will
274 produce a wheel you can distribute. Note the wheel contains "tags" in its
275 filename that correspond to supported Python versions, platforms, and/or
276 architectures, so yours might look a little different. If you want to
277 distribute broadly, you may need to build on multiple platforms and use a
278 [`manylinux`](https://github.com/pypa/manylinux) Docker container to build
279 wheels compatible with a wide range of Linux distros.
280
281 ```shell
282 (.venv) ferris@rustbox [~/src/rust/guessing-game] % maturin build
283 🔗 Found pyo3 bindings with abi3 support for Python ≥ 3.8
284 🐍 Not using a specific python interpreter (With abi3, an interpreter is only required on windows)
285 Finished dev [unoptimized + debuginfo] target(s) in 7.32s
286 📦 Built wheel for abi3 Python ≥ 3.8 to /Users/ferris/src/rust/guessing-game/target/wheels/guessing_game-0.1.0-cp37-abi3-macosx_10_7_x86_64.whl
287 ```
288
289 maturin can even publish wheels directly to [PyPI](https://pypi.org) with
290 `maturin publish`!
291
292 ## Summary
293
294 Congratulations! You successfully created a Python module implemented entirely
295 in Rust thanks to pyo3 and maturin.
296
297 This demonstrates how easy it is to get started with maturin, but keep reading
298 to learn more about all the additional features.