Writing Python modules in Rust - PyO3 101

In this workshop, we will cover the very basic of using PyO3 - rust library that package rust crates into Python modules. This is the most popular tool in terms of creating Python libraries with Rust.

In recent years, Rust has been getting more and more popular over other similar programming languages like C and C++ due to its robust compiler checking and ownership rules to make sure memory is safe. Hence there are more and more Python libraries that have been written in Rust natively with a Python API interface. One of the tools that have been driving this movement is PyO3, a toolset that proves Rust bindings for Python and tools for creating native Python extension modules.

In this interactive workshop, we will cover the very basics of using PyO3. There will be hands-on exercises to go from how to set up the project environment to writing a "toy" Python library written in Rust using PyO3. We will cover a lot of expectations of the API provided by PyO3 to create Python functions, modules, handling errors and converting types.

Goal

To give developers who are not familiar with PyO3 an introduction to PyO3 so they can consider building their Python libraries with Rust to make use of Rust's memory-safe property and parallelism ability.

Target audiences

Any developers who are interested in developing Python libraries using Rust. It will be an advantage if the attendees are comfortable writing in Rust. However, attendees are not required to be familiar with Rust as all the Rust codes will be provided. Basic knowledge of Python will be assumed from the attendees.

Preflight checklist

• Install/ Update Rust
• Make sure having Python 3.9 or above (recommend 3.12)
• Make sure using virtual environment (recommend using uv)

Windows checklist

In this workshop we recommend using Unix OS (Mac or Linux). If you use Windows, you may encounter problems with Rust and Maturin. To minimise issues that you may encounter, please go through the extra checklist below:

• Install the c++ build tools
• Check the dll files are linked correctly

Setting up

1. Create a new working directory

mkdir pyo3_101
cd pyo3_101

2. Set up virtual environment and install maturin

uv venv .venv
source .venv/bin/activate
uv pip install maturin
python -m ensurepip --default-pip

Note: the last command is needed as maturin develop cannot find pip otherwise

2. Start a project

If you want to start from scratch and write your own module, you can start a new project by

maturin init

Outline

Part 1 - introduction and getting started (40 mins)

• What's the difference between Rust and Python (5 mins)
• Why using PyO3 (5 mins)
• Setting up the environment (exercises) (15 mins)
• Starting a new project (exercises) (15 mins)

Break (15 mins)

Part 2 - Creating a simple Python library (100 mins)

• Creating Python modules (exercises) (40 mins)
  • Generating documentation
• Creating Python functions (exercises) (60 mins)
  • How to create function signatures
  • How to deal wi