| 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. |