Extending Python with Rust: a hands-on introduction to PyO3

This is an example project using PyO3. The goal of this project is to provide a practical example.

To see it in action:

The code exists to accompany the matching presentation. The slides are available here.

Structure

    .
    ├── 00_Example_Usage.ipynb             # Installs the extension from source and tests it
    ├── Cargo.toml                         # Defines the Rust manifest: crate name, deps, and more.
    ├── pyproject.toml                     # Configuration for Python: defines the build system and deps, and more.
    ├── Cargo.lock                         # Lockfile generated by Cargo. This is auto-generated.
    ├── src/                               # Rust implementation using PyO3 and jxl-oxide
    │   ├── lib.rs                         # Contains the functions and module exported to Python
    │   └── core.rs                        # Contains the implementation using jxl-oxide
    ├── slides                             # Slides source
    │   └── slides.pdf                     # Slides rendered as a PDF
    ├── .cargo                             # Config files to make this project compile for macOS
    └── README.md                          # This file!

Purpose

This example extension lets users load JPEG XL images into Python as NumPy arrays and Pillow Images.

We leverage jxl-oxide to read the JPEG XL images. This demo code wraps the Rust crate and makes it available for Python users.

Usage

To install from source, firstly ensure you have a Rust compiler available.

Then, simply run:

pip install .

Once that is done, the extension module should be available in Python:

import jxl_demo

The jxl_demo module has two functions: decode_jxl and decode_jxl_as_array.

Resources

• Maturin User Guide
• PyO3 User Guide
• Cargo Book