模組六：用 Rust 擴展 Python on Tarragon

5.1 為什麼選擇 Rust？

Tue, 20 Jan 2026 00:00:00 +0000

本章比較 Rust 與傳統 C/C++ 作為 Python 擴展語言的優缺點。

本章目標

學完本章後，你將能夠：

理解 Rust 的記憶體安全保證
評估 Rust vs C/C++ 的取捨
認識使用 Rust 的知名 Python 專案

【原理層】Rust 的核心優勢

記憶體安全

Rust 透過所有權（Ownership）系統在編譯時保證記憶體安全：

 1// Rust 的所有權規則
 2fn main() {
 3    let s1 = String::from("hello");
 4    let s2 = s1;  // s1 的所有權轉移給 s2
 5
 6    // println!("{}", s1);  // 編譯錯誤！s1 已經無效
 7    println!("{}", s2);     // OK
 8}
 9
10// 借用（Borrowing）
11fn calculate_length(s: &String) -> usize {
12    s.len()
13}  // s 離開作用域，但不會釋放記憶體（只是借用）
14
15fn main() {
16    let s = String::from("hello");
17    let len = calculate_length(&s);  // 借用 s
18    println!("長度: {}, 字串: {}", len, s);  // s 仍然有效
19}

與 C/C++ 的對比：

 1// C 語言：常見的記憶體錯誤
 2
 3// 1. Use After Free
 4char* ptr = malloc(100);
 5free(ptr);
 6printf("%s", ptr);  // 未定義行為！
 7
 8// 2. Double Free
 9char* ptr = malloc(100);
10free(ptr);
11free(ptr);  // 未定義行為！
12
13// 3. Buffer Overflow
14char buffer[10];
15strcpy(buffer, "This string is way too long!");  // 溢位！
16
17// 4. Null Pointer Dereference
18char* ptr = NULL;
19printf("%c", *ptr);  // Crash!

 1// Rust：上述錯誤在編譯時就會被捕捉
 2
 3// 1. Use After Free - 不可能
 4let s = String::from("hello");
 5drop(s);  // 明確釋放
 6// println!("{}", s);  // 編譯錯誤：value borrowed after move
 7
 8// 2. Double Free - 不可能
 9// 所有權系統確保每個值只會被釋放一次
10
11// 3. Buffer Overflow - 執行時檢查
12let v = vec![1, 2, 3];
13// v[10];  // 執行時 panic，不是未定義行為
14
15// 4. Null Pointer - 使用 Option 類型
16let maybe_value: Option<i32> = None;
17// 必須明確處理 None 的情況
18match maybe_value {
19    Some(v) => println!("值: {}", v),
20    None => println!("沒有值"),
21}

並行安全

Rust 的類型系統在編譯時防止資料競爭：

 1use std::thread;
 2
 3// 編譯錯誤：不能在多個執行緒中修改同一資料
 4fn wont_compile() {
 5    let mut data = vec![1, 2, 3];
 6
 7    thread::spawn(|| {
 8        data.push(4);  // 錯誤：無法借用
 9    });
10
11    data.push(5);
12}
13
14// 正確：使用 Arc 和 Mutex
15use std::sync::{Arc, Mutex};
16
17fn correct_approach() {
18    let data = Arc::new(Mutex::new(vec![1, 2, 3]));
19    let data_clone = Arc::clone(&data);
20
21    let handle = thread::spawn(move || {
22        let mut d = data_clone.lock().unwrap();
23        d.push(4);
24    });
25
26    {
27        let mut d = data.lock().unwrap();
28        d.push(5);
29    }
30
31    handle.join().unwrap();
32}

零成本抽象

高階語法不會帶來執行時開銷：

1// 迭代器鏈式操作
2let sum: i32 = (0..1000)
3    .filter(|x| x % 2 == 0)
4    .map(|x| x * x)
5    .sum();
6
7// 編譯後等同於手寫的迴圈
8// 沒有額外的函式呼叫或記憶體分配

【比較】Rust vs C/C++

效能比較

 1效能特性比較：
 2
 3                    Rust        C           C++
 4────────────────────────────────────────────────────
 5執行速度            5/5         5/5         5/5
 6編譯時間            2/5         4/5         3/5
 7二進位大小          3/5         5/5         4/5
 8記憶體使用          5/5         5/5         4/5
 9
10說明：
11- 執行速度三者相當（都編譯為原生機器碼）
12- Rust 編譯時間較長（複雜的類型檢查）
13- Rust 二進位可能較大（標準庫靜態連結）

開發體驗比較

 1開發體驗：
 2
 3                    Rust        C           C++
 4────────────────────────────────────────────────────
 5學習曲線            陡峭        中等         陡峭
 6除錯難度            較易        困難         困難
 7錯誤訊息            優秀        普通         差
 8套件管理 (Cargo)    5/5         無           2/5
 9IDE 支援            4/5         5/5         5/5
10
11說明：
12- Rust 的學習曲線主要來自所有權系統
13- Rust 的錯誤通常在編譯時發現，更容易修復
14- Cargo 提供了優秀的套件管理和建構系統

安全性比較

 1安全性：
 2
 3問題類型              Rust                C/C++
 4──────────────────────────────────────────────────────
 5記憶體洩漏            可能（較少見）      常見
 6Use After Free        編譯時防止          常見
 7Buffer Overflow       執行時 panic        未定義行為
 8Null Pointer          使用 Option         常見 crash
 9Data Race             編譯時防止          常見
10未初始化變數          編譯時防止          可能
11
12Rust 的 unsafe：
13- 可以繞過某些安全檢查
14- 明確標記，易於審查
15- 應該盡量減少使用

【案例】使用 Rust 的知名 Python 專案

tiktoken（OpenAI）

 1tiktoken - OpenAI 的 tokenizer
 2
 3用途：
 4- GPT 模型的 token 編碼/解碼
 5- 處理大量文字資料
 6
 7為什麼選擇 Rust：
 8- 效能要求高（處理大量請求）
 9- 需要處理各種邊界情況
10- 記憶體安全很重要
11
12效能數據：
13- 比純 Python 實現快 3-10x
14- 與 C++ 實現效能相當

tokenizers（Hugging Face）

 1tokenizers - Hugging Face 的 tokenizer 函式庫
 2
 3用途：
 4- NLP 模型的 token 處理
 5- 支援多種 tokenization 演算法
 6
 7特點：
 8- 純 Rust 核心
 9- PyO3 提供 Python 綁定
10- 支援多種語言綁定（Node.js、Ruby 等）
11
12為什麼選擇 Rust：
13- 需要高效能的字串處理
14- 需要安全地處理任意輸入
15- 跨平台支援

Polars

 1Polars - 高效能 DataFrame 函式庫
 2
 3用途：
 4- pandas 的替代方案
 5- 大規模資料處理
 6
 7特點：
 8- 比 pandas 快 10-100x（某些操作）
 9- 惰性求值
10- 多執行緒
11
12為什麼選擇 Rust：
13- 需要最佳效能
14- 需要安全的並行處理
15- Arrow 生態系統整合
16
17使用範例：
18import polars as pl
19
20df = pl.read_csv("large_file.csv")
21result = (
22    df.lazy()
23    .filter(pl.col("value") > 100)
24    .group_by("category")
25    .agg(pl.col("value").sum())
26    .collect()
27)

Ruff

 1Ruff - 超快的 Python linter
 2
 3用途：
 4- Python 程式碼檢查
 5- 取代 flake8、isort、pyupgrade 等
 6
 7特點：
 8- 比 flake8 快 10-100x
 9- 單一工具取代多個 linter
10
11為什麼選擇 Rust：
12- 需要處理大型程式碼庫
13- 需要快速的回饋（IDE 整合）
14- 字串處理效能關鍵
15
16效能數據：
17- CPython 程式碼庫（約 60 萬行）
18- Ruff: 0.29 秒
19- flake8: 22 秒

pydantic-core

 1pydantic-core - Pydantic v2 的核心
 2
 3用途：
 4- 資料驗證和序列化
 5- 廣泛用於 FastAPI
 6
 7特點：
 8- Pydantic v2 比 v1 快 5-50x
 9- 核心驗證邏輯用 Rust 重寫
10
11為什麼選擇 Rust：
12- 驗證邏輯被頻繁呼叫
13- 需要處理各種邊界情況
14- 需要安全地處理任意輸入

【評估】何時選擇 Rust

適合使用 Rust 的場景

 1應該考慮 Rust：
 2
 31. 效能關鍵的程式碼
 4   - 大量數值計算
 5   - 頻繁呼叫的函式
 6   - 處理大型資料集
 7
 82. 需要安全地處理任意輸入
 9   - 解析使用者提供的資料
10   - 網路協議處理
11   - 檔案格式解析
12
133. 需要並行處理
14   - 多執行緒計算
15   - 非同步 I/O
16   - 需要避免 GIL
17
184. 長期維護的核心函式庫
19   - 減少記憶體相關 bug
20   - 更容易重構
21   - 跨語言共享
22
235. 跨平台發布
24   - Rust 交叉編譯支援好
25   - 減少平台特定 bug

不太適合 Rust 的場景

 1可能不需要 Rust：
 2
 31. 快速原型開發
 4   - Python 本身就夠用
 5   - 學習成本高
 6
 72. 已有 C/C++ 程式碼
 8   - 直接用 pybind11 包裝
 9   - 除非需要大幅修改
10
113. 團隊不熟悉 Rust
12   - 學習曲線陡峭
13   - 維護成本考量
14
154. 效能不是瓶頸
16   - 先用 profiler 確認
17   - 可能 Python 優化就夠了
18
195. 只需要呼叫現有 C 函式庫
20   - ctypes/cffi 更簡單
21   - 不需要額外語言

決策流程

 1需要 Python 擴展？
 2│
 3├── 有現有 C/C++ 程式碼？
 4│   ├── 是 → pybind11/Cython
 5│   └── 否 ↓
 6│
 7├── 效能是主要考量？
 8│   ├── 否 → 純 Python 或 Cython
 9│   └── 是 ↓
10│
11├── 需要並行安全？
12│   ├── 是 → Rust (PyO3)
13│   └── 否 ↓
14│
15├── 團隊熟悉 Rust？
16│   ├── 是 → Rust (PyO3)
17│   └── 否 → Cython 或學習 Rust
18│
19└── 長期維護的核心程式碼？
20    ├── 是 → 考慮 Rust
21    └── 否 → Cython 可能更實際

【入門】Rust 基礎概念

給 Python 開發者的快速入門

 1// 變數與型別
 2fn basics() {
 3    // 不可變變數（預設）
 4    let x = 5;
 5    // x = 6;  // 錯誤！
 6
 7    // 可變變數
 8    let mut y = 5;
 9    y = 6;  // OK
10
11    // 型別推斷
12    let z = 10;       // i32
13    let pi = 3.14;    // f64
14
15    // 明確型別
16    let a: i64 = 100;
17    let b: f32 = 3.14;
18}
19
20// 函式
21fn add(a: i32, b: i32) -> i32 {
22    a + b  // 沒有分號 = 回傳值
23}
24
25// 結構體（類似 Python class）
26struct Point {
27    x: f64,
28    y: f64,
29}
30
31impl Point {
32    // 關聯函式（類似 classmethod）
33    fn new(x: f64, y: f64) -> Self {
34        Point { x, y }
35    }
36
37    // 方法
38    fn distance(&self, other: &Point) -> f64 {
39        let dx = self.x - other.x;
40        let dy = self.y - other.y;
41        (dx * dx + dy * dy).sqrt()
42    }
43}
44
45// 列舉（比 Python enum 更強大）
46enum Option<T> {
47    Some(T),
48    None,
49}
50
51enum Result<T, E> {
52    Ok(T),
53    Err(E),
54}
55
56// 模式匹配
57fn handle_option(opt: Option<i32>) {
58    match opt {
59        Some(value) => println!("有值: {}", value),
60        None => println!("沒有值"),
61    }
62}
63
64// 迭代器（類似 Python generator）
65fn iterators() {
66    let v = vec![1, 2, 3, 4, 5];
67
68    // 類似 Python 的 list comprehension
69    let doubled: Vec<i32> = v.iter().map(|x| x * 2).collect();
70
71    // 類似 Python 的 filter
72    let evens: Vec<&i32> = v.iter().filter(|x| *x % 2 == 0).collect();
73}

Python vs Rust 語法對照

 1Python                          Rust
 2──────────────────────────────────────────────────────
 3x = 5                           let x = 5;
 4x = 5  # mutable                let mut x = 5;
 5def foo(x):                     fn foo(x: i32) -> i32 {
 6    return x + 1                    x + 1
 7                                }
 8class Point:                    struct Point {
 9    def __init__(self, x, y):       x: f64,
10        self.x = x                  y: f64,
11        self.y = y              }
12[x*2 for x in lst]              lst.iter().map(|x| x*2).collect()
13if x is None:                   if x.is_none() {
14    ...                             ...
15for i in range(10):             for i in 0..10 {
16    ...                             ...
17try: ... except:                match result {
18    ...                             Ok(v) => ...,
19                                    Err(e) => ...,
20                                }

思考題

Rust 的所有權系統如何與 Python 的垃圾回收協調？PyO3 如何處理這個問題？
為什麼許多高效能 Python 函式庫選擇用 Rust 重寫而不是 C++？
學習 Rust 對 Python 開發者有什麼長期價值？

實作練習

安裝 Rust 並完成官方教學「rustlings」的前 20 個練習
比較用 Python、Cython 和 Rust 實現 Fibonacci 函式的效能
研究一個用 Rust 寫的 Python 函式庫（如 Polars），理解其專案結構

延伸閱讀

下一章：PyO3 基礎

5.2 PyO3 基礎

Tue, 20 Jan 2026 00:00:00 +0000

本章介紹 PyO3，Rust 的 Python 綁定函式庫。

本章目標

學完本章後，你將能夠：

理解 PyO3 的設計原理
使用 #[pyfunction] 和 #[pyclass] 建立綁定
處理型別轉換和錯誤

【原理層】PyO3 的設計

PyO3 是什麼？

PyO3 是 Rust 與 Python 之間的橋樑：

1PyO3 提供：
2├── Rust → Python：將 Rust 程式碼編譯為 Python 模組
3├── Python → Rust：在 Rust 中嵌入 Python 直譯器
4├── 型別轉換：自動處理 Rust ↔ Python 型別
5└── GIL 管理：安全地處理 Python 的全域直譯器鎖

版本要求

1# Cargo.toml（2025 年建議）
2[dependencies]
3pyo3 = { version = "0.23", features = ["extension-module"] }
4
5# 支援的版本：
6# - Rust: 1.63+（建議 1.75+）
7# - Python: 3.8+
8# - PyO3: 0.23+（支援 Free-threading）

與 Python 的互動模型

 1Python 程式
 2    │
 3    ↓ import
 4┌─────────────────────────────────┐
 5│  Rust 編譯的 .so/.pyd 模組      │
 6│  ┌─────────────────────────┐   │
 7│  │  PyO3 綁定層            │   │
 8│  │  - 型別轉換             │   │
 9│  │  - GIL 管理             │   │
10│  │  - 錯誤處理             │   │
11│  └─────────────────────────┘   │
12│  ┌─────────────────────────┐   │
13│  │  純 Rust 程式碼         │   │
14│  │  - 核心邏輯             │   │
15│  │  - 無 GIL 限制          │   │
16│  └─────────────────────────┘   │
17└─────────────────────────────────┘

【設計層】專案設定

Cargo.toml 設定

 1[package]
 2name = "my_rust_module"
 3version = "0.1.0"
 4edition = "2021"
 5
 6[lib]
 7name = "my_rust_module"
 8crate-type = ["cdylib"]  # 編譯為動態連結庫
 9
10[dependencies]
11pyo3 = { version = "0.23", features = ["extension-module"] }
12
13# 選用功能
14# pyo3 = { version = "0.23", features = [
15#     "extension-module",
16#     "abi3-py38",        # 穩定 ABI（支援 Python 3.8+）
17#     "multiple-pymethods",
18# ]}

基本模組結構

 1// src/lib.rs
 2use pyo3::prelude::*;
 3
 4/// 簡單的加法函式
 5#[pyfunction]
 6fn add(a: i64, b: i64) -> i64 {
 7    a + b
 8}
 9
10/// 建立 Python 模組
11#[pymodule]
12fn my_rust_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
13    m.add_function(wrap_pyfunction!(add, m)?)?;
14    Ok(())
15}

abi3：穩定 ABI

1# 啟用 abi3 的好處：
2# 1. 一次編譯，多版本 Python 使用
3# 2. 減少發布的 wheel 數量
4# 3. 更好的向前相容性
5
6[dependencies]
7pyo3 = { version = "0.23", features = ["extension-module", "abi3-py38"] }

1不使用 abi3：
2├── my_module-cp38-cp38-linux_x86_64.whl
3├── my_module-cp39-cp39-linux_x86_64.whl
4├── my_module-cp310-cp310-linux_x86_64.whl
5├── my_module-cp311-cp311-linux_x86_64.whl
6└── my_module-cp312-cp312-linux_x86_64.whl
7
8使用 abi3-py38：
9└── my_module-cp38-abi3-linux_x86_64.whl  # 支援 Python 3.8+

【實作層】函式綁定

#[pyfunction] 基礎

 1use pyo3::prelude::*;
 2
 3// 基本函式
 4#[pyfunction]
 5fn greet(name: &str) -> String {
 6    format!("Hello, {}!", name)
 7}
 8
 9// 帶預設參數
10#[pyfunction]
11#[pyo3(signature = (a, b=1.0))]
12fn divide(a: f64, b: f64) -> f64 {
13    a / b
14}
15
16// 可變參數
17#[pyfunction]
18#[pyo3(signature = (*args))]
19fn sum_all(args: Vec<i64>) -> i64 {
20    args.iter().sum()
21}
22
23// 關鍵字參數
24#[pyfunction]
25#[pyo3(signature = (**kwargs))]
26fn print_kwargs(kwargs: Option<&Bound<'_, PyDict>>) -> PyResult<()> {
27    if let Some(dict) = kwargs {
28        for (key, value) in dict.iter() {
29            println!("{}: {}", key, value);
30        }
31    }
32    Ok(())
33}
34
35// 文件字串
36/// 計算兩個數的最大公因數
37///
38/// Args:
39///     a: 第一個整數
40///     b: 第二個整數
41///
42/// Returns:
43///     最大公因數
44#[pyfunction]
45fn gcd(a: u64, b: u64) -> u64 {
46    if b == 0 { a } else { gcd(b, a % b) }
47}
48
49#[pymodule]
50fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
51    m.add_function(wrap_pyfunction!(greet, m)?)?;
52    m.add_function(wrap_pyfunction!(divide, m)?)?;
53    m.add_function(wrap_pyfunction!(sum_all, m)?)?;
54    m.add_function(wrap_pyfunction!(print_kwargs, m)?)?;
55    m.add_function(wrap_pyfunction!(gcd, m)?)?;
56    Ok(())
57}

型別轉換

 1use pyo3::prelude::*;
 2use pyo3::types::{PyList, PyDict, PyTuple};
 3
 4// 自動型別轉換
 5#[pyfunction]
 6fn process_list(items: Vec<i64>) -> Vec<i64> {
 7    // Python list 自動轉換為 Vec
 8    items.iter().map(|x| x * 2).collect()
 9}
10
11#[pyfunction]
12fn process_dict(data: HashMap<String, i64>) -> i64 {
13    // Python dict 自動轉換為 HashMap
14    data.values().sum()
15}
16
17// 手動處理 Python 物件
18#[pyfunction]
19fn manual_conversion(py: Python<'_>, obj: &Bound<'_, PyAny>) -> PyResult<String> {
20    // 檢查型別
21    if obj.is_instance_of::<PyList>() {
22        let list = obj.downcast::<PyList>()?;
23        Ok(format!("List with {} items", list.len()))
24    } else if obj.is_instance_of::<PyDict>() {
25        let dict = obj.downcast::<PyDict>()?;
26        Ok(format!("Dict with {} keys", dict.len()))
27    } else {
28        Ok(format!("Unknown type: {}", obj.get_type().name()?))
29    }
30}
31
32// 回傳多個值（使用 tuple）
33#[pyfunction]
34fn divmod(a: i64, b: i64) -> (i64, i64) {
35    (a / b, a % b)
36}
37
38// 回傳 Option（轉換為 None 或值）
39#[pyfunction]
40fn find_item(items: Vec<i64>, target: i64) -> Option<usize> {
41    items.iter().position(|&x| x == target)
42}

【實作層】類別綁定

#[pyclass] 基礎

 1use pyo3::prelude::*;
 2
 3#[pyclass]
 4struct Point {
 5    #[pyo3(get, set)]  // 自動產生 getter 和 setter
 6    x: f64,
 7    #[pyo3(get, set)]
 8    y: f64,
 9}
10
11#[pymethods]
12impl Point {
13    // 建構子
14    #[new]
15    fn new(x: f64, y: f64) -> Self {
16        Point { x, y }
17    }
18
19    // 方法
20    fn distance(&self, other: &Point) -> f64 {
21        let dx = self.x - other.x;
22        let dy = self.y - other.y;
23        (dx * dx + dy * dy).sqrt()
24    }
25
26    // 類別方法
27    #[classmethod]
28    fn origin(_cls: &Bound<'_, PyType>) -> Self {
29        Point { x: 0.0, y: 0.0 }
30    }
31
32    // 靜態方法
33    #[staticmethod]
34    fn from_polar(r: f64, theta: f64) -> Self {
35        Point {
36            x: r * theta.cos(),
37            y: r * theta.sin(),
38        }
39    }
40
41    // __repr__
42    fn __repr__(&self) -> String {
43        format!("Point({}, {})", self.x, self.y)
44    }
45
46    // __str__
47    fn __str__(&self) -> String {
48        format!("({}, {})", self.x, self.y)
49    }
50}
51
52#[pymodule]
53fn geometry(m: &Bound<'_, PyModule>) -> PyResult<()> {
54    m.add_class::<Point>()?;
55    Ok(())
56}

Python 使用：

 1from geometry import Point
 2
 3p1 = Point(3.0, 4.0)
 4p2 = Point.origin()  # 類別方法
 5p3 = Point.from_polar(5.0, 0.927)  # 靜態方法
 6
 7print(p1)  # (3.0, 4.0)
 8print(repr(p1))  # Point(3.0, 4.0)
 9print(p1.distance(p2))  # 5.0
10
11p1.x = 10.0  # setter
12print(p1.x)  # getter

運算子重載

 1use pyo3::prelude::*;
 2use std::ops::{Add, Sub, Mul};
 3
 4#[pyclass]
 5#[derive(Clone)]
 6struct Vector2D {
 7    x: f64,
 8    y: f64,
 9}
10
11#[pymethods]
12impl Vector2D {
13    #[new]
14    fn new(x: f64, y: f64) -> Self {
15        Vector2D { x, y }
16    }
17
18    // __add__
19    fn __add__(&self, other: &Vector2D) -> Vector2D {
20        Vector2D {
21            x: self.x + other.x,
22            y: self.y + other.y,
23        }
24    }
25
26    // __sub__
27    fn __sub__(&self, other: &Vector2D) -> Vector2D {
28        Vector2D {
29            x: self.x - other.x,
30            y: self.y - other.y,
31        }
32    }
33
34    // __mul__（標量乘法）
35    fn __mul__(&self, scalar: f64) -> Vector2D {
36        Vector2D {
37            x: self.x * scalar,
38            y: self.y * scalar,
39        }
40    }
41
42    // __rmul__（右乘）
43    fn __rmul__(&self, scalar: f64) -> Vector2D {
44        self.__mul__(scalar)
45    }
46
47    // __neg__
48    fn __neg__(&self) -> Vector2D {
49        Vector2D {
50            x: -self.x,
51            y: -self.y,
52        }
53    }
54
55    // __eq__
56    fn __eq__(&self, other: &Vector2D) -> bool {
57        (self.x - other.x).abs() < 1e-10 &&
58        (self.y - other.y).abs() < 1e-10
59    }
60
61    // __len__（向量維度）
62    fn __len__(&self) -> usize {
63        2
64    }
65
66    // __getitem__
67    fn __getitem__(&self, index: usize) -> PyResult<f64> {
68        match index {
69            0 => Ok(self.x),
70            1 => Ok(self.y),
71            _ => Err(PyIndexError::new_err("Index out of range")),
72        }
73    }
74
75    fn __repr__(&self) -> String {
76        format!("Vector2D({}, {})", self.x, self.y)
77    }
78}

繼承與多型

 1use pyo3::prelude::*;
 2
 3// 基礎類別
 4#[pyclass(subclass)]  // 允許被繼承
 5struct Animal {
 6    #[pyo3(get)]
 7    name: String,
 8}
 9
10#[pymethods]
11impl Animal {
12    #[new]
13    fn new(name: String) -> Self {
14        Animal { name }
15    }
16
17    // 可被覆寫的方法
18    fn speak(&self) -> String {
19        "...".to_string()
20    }
21}
22
23// 子類別
24#[pyclass(extends=Animal)]
25struct Dog {}
26
27#[pymethods]
28impl Dog {
29    #[new]
30    fn new(name: String) -> (Self, Animal) {
31        (Dog {}, Animal { name })
32    }
33
34    fn speak(&self) -> String {
35        "Woof!".to_string()
36    }
37}
38
39#[pyclass(extends=Animal)]
40struct Cat {}
41
42#[pymethods]
43impl Cat {
44    #[new]
45    fn new(name: String) -> (Self, Animal) {
46        (Cat {}, Animal { name })
47    }
48
49    fn speak(&self) -> String {
50        "Meow!".to_string()
51    }
52}

【實作層】錯誤處理

PyResult 與錯誤轉換

 1use pyo3::prelude::*;
 2use pyo3::exceptions::{PyValueError, PyTypeError, PyIOError};
 3
 4// 回傳 PyResult
 5#[pyfunction]
 6fn safe_divide(a: f64, b: f64) -> PyResult<f64> {
 7    if b == 0.0 {
 8        Err(PyValueError::new_err("除數不能為零"))
 9    } else {
10        Ok(a / b)
11    }
12}
13
14// 自訂錯誤類型
15use std::io;
16
17fn read_file_internal(path: &str) -> Result<String, io::Error> {
18    std::fs::read_to_string(path)
19}
20
21#[pyfunction]
22fn read_file(path: &str) -> PyResult<String> {
23    read_file_internal(path).map_err(|e| {
24        PyIOError::new_err(format!("無法讀取檔案: {}", e))
25    })
26}
27
28// 使用 ? 運算子
29#[pyfunction]
30fn parse_and_double(s: &str) -> PyResult<i64> {
31    let num: i64 = s.parse().map_err(|_| {
32        PyValueError::new_err(format!("無法解析為整數: {}", s))
33    })?;
34    Ok(num * 2)
35}
36
37// 自動轉換 Rust 錯誤
38use thiserror::Error;
39
40#[derive(Error, Debug)]
41enum MyError {
42    #[error("數值錯誤: {0}")]
43    ValueError(String),
44    #[error("IO 錯誤: {0}")]
45    IoError(#[from] io::Error),
46}
47
48impl From<MyError> for PyErr {
49    fn from(err: MyError) -> PyErr {
50        match err {
51            MyError::ValueError(msg) => PyValueError::new_err(msg),
52            MyError::IoError(e) => PyIOError::new_err(e.to_string()),
53        }
54    }
55}
56
57#[pyfunction]
58fn risky_operation(value: i64) -> Result<i64, MyError> {
59    if value < 0 {
60        Err(MyError::ValueError("負數不允許".to_string()))
61    } else {
62        Ok(value * 2)
63    }
64}

自訂異常

 1use pyo3::prelude::*;
 2use pyo3::create_exception;
 3
 4// 建立自訂異常
 5create_exception!(my_module, ValidationError, pyo3::exceptions::PyException);
 6create_exception!(my_module, ProcessingError, pyo3::exceptions::PyException);
 7
 8#[pyfunction]
 9fn validate_data(data: &str) -> PyResult<()> {
10    if data.is_empty() {
11        return Err(ValidationError::new_err("資料不能為空"));
12    }
13    if data.len() > 100 {
14        return Err(ValidationError::new_err("資料太長"));
15    }
16    Ok(())
17}
18
19#[pymodule]
20fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
21    m.add("ValidationError", m.py().get_type::<ValidationError>())?;
22    m.add("ProcessingError", m.py().get_type::<ProcessingError>())?;
23    m.add_function(wrap_pyfunction!(validate_data, m)?)?;
24    Ok(())
25}

【實作層】GIL 管理

釋放 GIL

 1use pyo3::prelude::*;
 2
 3// CPU 密集計算，應該釋放 GIL
 4#[pyfunction]
 5fn heavy_computation(n: u64) -> f64 {
 6    // 釋放 GIL，允許其他 Python 執行緒執行
 7    Python::with_gil(|py| {
 8        py.allow_threads(|| {
 9            // 這裡的程式碼不持有 GIL
10            let mut result = 0.0;
11            for i in 0..n {
12                result += (i as f64).sin() * (i as f64).cos();
13            }
14            result
15        })
16    })
17}
18
19// 或者使用 Python 參數
20#[pyfunction]
21fn parallel_sum(py: Python<'_>, data: Vec<f64>) -> f64 {
22    py.allow_threads(|| {
23        // 可以安全地使用多執行緒
24        use rayon::prelude::*;
25        data.par_iter().sum()
26    })
27}

需要 GIL 的操作

 1use pyo3::prelude::*;
 2
 3#[pyfunction]
 4fn callback_example(py: Python<'_>, callback: PyObject) -> PyResult<()> {
 5    // 模擬一些計算
 6    let results: Vec<i64> = py.allow_threads(|| {
 7        (0..10).map(|x| x * x).collect()
 8    });
 9
10    // 呼叫 Python 回呼需要 GIL
11    for result in results {
12        callback.call1(py, (result,))?;
13    }
14
15    Ok(())
16}
17
18#[pyfunction]
19fn mixed_workload(py: Python<'_>, n: u64) -> PyResult<Vec<f64>> {
20    let mut results = Vec::new();
21
22    for i in 0..n {
23        // 計算（釋放 GIL）
24        let value = py.allow_threads(|| {
25            (i as f64).sin()
26        });
27
28        // Python 互動（需要 GIL）
29        results.push(value);
30
31        // 定期檢查是否有 Python 訊號（如 Ctrl+C）
32        if i % 1000 == 0 {
33            py.check_signals()?;
34        }
35    }
36
37    Ok(results)
38}

【進階】與 NumPy 整合

numpy crate

1[dependencies]
2pyo3 = { version = "0.23", features = ["extension-module"] }
3numpy = "0.23"
4ndarray = "0.16"

 1use pyo3::prelude::*;
 2use numpy::{PyArray1, PyArray2, PyReadonlyArray1, PyReadonlyArray2};
 3use ndarray::{Array1, Array2};
 4
 5// 接受 NumPy 陣列
 6#[pyfunction]
 7fn array_sum(arr: PyReadonlyArray1<'_, f64>) -> f64 {
 8    arr.as_array().sum()
 9}
10
11// 回傳 NumPy 陣列
12#[pyfunction]
13fn create_range(py: Python<'_>, n: usize) -> Bound<'_, PyArray1<f64>> {
14    let arr: Array1<f64> = Array1::from_iter((0..n).map(|x| x as f64));
15    PyArray1::from_owned_array(py, arr)
16}
17
18// 處理 2D 陣列
19#[pyfunction]
20fn matrix_multiply<'py>(
21    py: Python<'py>,
22    a: PyReadonlyArray2<'py, f64>,
23    b: PyReadonlyArray2<'py, f64>,
24) -> PyResult<Bound<'py, PyArray2<f64>>> {
25    let a = a.as_array();
26    let b = b.as_array();
27
28    // 檢查維度
29    if a.ncols() != b.nrows() {
30        return Err(PyValueError::new_err("矩陣維度不匹配"));
31    }
32
33    // 計算（釋放 GIL）
34    let result = py.allow_threads(|| {
35        a.dot(&b)
36    });
37
38    Ok(PyArray2::from_owned_array(py, result))
39}
40
41// 原地修改
42#[pyfunction]
43fn normalize_inplace(mut arr: PyReadwriteArray1<'_, f64>) {
44    let mut arr = arr.as_array_mut();
45    let sum: f64 = arr.sum();
46    if sum != 0.0 {
47        arr.mapv_inplace(|x| x / sum);
48    }
49}

思考題

PyO3 如何處理 Rust 的所有權系統和 Python 的垃圾回收之間的衝突？
什麼時候應該使用 py.allow_threads()？有什麼風險？
為什麼 PyO3 使用 Bound<'_, T> 而不是直接傳遞 Python 物件？

實作練習

使用 PyO3 實現一個簡單的 Counter 類別，支援 +、-、+= 運算子
實現一個接受 Python 回呼的函式，用於處理大量資料
使用 numpy crate 實現一個高效能的向量運算函式

延伸閱讀

上一章：為什麼選擇 Rust？ 下一章：Maturin 開發流程

5.3 Maturin 開發流程

Tue, 20 Jan 2026 00:00:00 +0000

本章介紹 Maturin，Rust Python 套件的建構工具。

本章目標

學完本章後，你將能夠：

設定 Maturin 專案
使用 maturin develop 快速迭代
建構跨平台 wheel 並發布到 PyPI

【原理層】Maturin 是什麼？

建構工具的角色

 1傳統 Python 擴展建構：
 2├── setuptools + setup.py
 3├── 複雜的編譯器設定
 4├── 手動處理連結問題
 5└── 跨平台建構困難
 6
 7Maturin 提供：
 8├── 一鍵建構 Rust Python 套件
 9├── 自動處理 PyO3 設定
10├── 跨平台 wheel 生成
11├── 與 pyproject.toml 整合
12└── 開發模式快速迭代

支援的專案類型

1Maturin 支援：
2├── pyo3：純 Rust 擴展（最常用）
3├── cffi：生成 cffi 綁定
4├── uniffi：跨語言綁定
5└── bin：Rust 二進位程式打包

【設計層】專案設定

安裝 Maturin

 1# 使用 pip
 2pip install maturin
 3
 4# 使用 pipx（推薦，隔離環境）
 5pipx install maturin
 6
 7# 使用 cargo
 8cargo install maturin
 9
10# 驗證安裝
11maturin --version

建立新專案

 1# 互動式建立
 2maturin new my_rust_module
 3cd my_rust_module
 4
 5# 或者指定綁定類型
 6maturin new my_rust_module --bindings pyo3
 7
 8# 專案結構
 9my_rust_module/
10├── Cargo.toml
11├── pyproject.toml
12├── src/
13│ └── lib.rs
14└── python/
15 └── my_rust_module/
16 └── __init__.py # 選用

pyproject.toml 設定

 1[build-system]
 2requires = ["maturin>=1.5,<2.0"]
 3build-backend = "maturin"
 4
 5[project]
 6name = "my-rust-module"
 7version = "0.1.0"
 8description = "A Python module written in Rust"
 9requires-python = ">=3.8"
10classifiers = [
11 "Programming Language :: Rust",
12 "Programming Language :: Python :: Implementation :: CPython",
13 "Programming Language :: Python :: Implementation :: PyPy",
14]
15
16[project.optional-dependencies]
17dev = ["pytest", "hypothesis"]
18
19[tool.maturin]
20# 模組名稱（如果與 crate 名稱不同）
21module-name = "my_rust_module"
22
23# Python 原始碼目錄（如果有純 Python 程式碼）
24python-source = "python"
25
26# 功能標誌
27features = ["pyo3/extension-module"]
28
29# 啟用 abi3
30# features = ["pyo3/extension-module", "pyo3/abi3-py38"]
31
32# 排除不需要的檔案
33exclude = ["tests/*", "benches/*"]
34
35# 建構設定
36# strip = true # 移除除錯符號（減小檔案大小）

Cargo.toml 設定

 1[package]
 2name = "my_rust_module"
 3version = "0.1.0"
 4edition = "2021"
 5
 6[lib]
 7name = "my_rust_module"
 8crate-type = ["cdylib"]
 9
10[dependencies]
11pyo3 = { version = "0.23", features = ["extension-module"] }
12
13[profile.release]
14lto = true # Link-Time Optimization
15codegen-units = 1 # 更好的優化
16strip = true # 移除除錯符號
17
18[profile.dev]
19opt-level = 0 # 快速編譯

【實作層】開發流程

maturin develop

 1# 開發模式：編譯並安裝到當前虛擬環境
 2maturin develop
 3
 4# 使用 release 模式（較慢但更快的執行時效能）
 5maturin develop --release
 6
 7# 指定功能
 8maturin develop --features "some-feature"
 9
10# 在其他虛擬環境中安裝
11maturin develop --target-dir target -E /path/to/venv
12
13# 使用後立即測試
14maturin develop && python -c "import my_rust_module; print(my_rust_module.add(1, 2))"

完整開發循環

 1# 1. 建立虛擬環境
 2python -m venv .venv
 3source .venv/bin/activate # Linux/macOS
 4# .venv\Scripts\activate # Windows
 5
 6# 2. 安裝開發依賴
 7pip install maturin pytest
 8
 9# 3. 開發循環
10while editing:
11 # 編輯 Rust 程式碼
12 vim src/lib.rs
13
14 # 建構並安裝
15 maturin develop
16
17 # 執行測試
18 pytest tests/
19
20# 4. 準備發布
21maturin build --release

混合 Python/Rust 專案

 1專案結構：
 2my_package/
 3├── Cargo.toml
 4├── pyproject.toml
 5├── src/
 6│ └── lib.rs # Rust 程式碼
 7└── python/
 8 └── my_package/
 9 ├── __init__.py # 匯入 Rust 模組
10 ├── utils.py # 純 Python 程式碼
11 └── py.typed # 型別標記

1# python/my_package/__init__.py
2from .my_package import * # 從 Rust 模組匯入
3from .utils import helper_function # 純 Python
4
5__version__ = "0.1.0"

1# pyproject.toml
2[tool.maturin]
3python-source = "python"
4module-name = "my_package.my_package"

【實作層】建構與發布

maturin build

 1# 建構 wheel
 2maturin build
 3
 4# Release 模式
 5maturin build --release
 6
 7# 指定 Python 版本
 8maturin build --interpreter python3.11
 9
10# 多個 Python 版本
11maturin build --interpreter python3.10 python3.11 python3.12
12
13# 使用 abi3（穩定 ABI）
14maturin build --release --features pyo3/abi3-py38
15
16# 建構結果位置
17ls target/wheels/
18# my_rust_module-0.1.0-cp311-cp311-linux_x86_64.whl

跨平台建構

 1# 使用 Docker 建構 manylinux wheel
 2maturin build --release --manylinux 2014
 3
 4# 常用的 manylinux 版本
 5# manylinux1: CentOS 5 (非常老舊)
 6# manylinux2010: CentOS 6
 7# manylinux2014: CentOS 7 (推薦)
 8# manylinux_2_28: Debian 9 / Ubuntu 18.04
 9
10# 使用 zig 進行交叉編譯
11pip install ziglang
12maturin build --release --target x86_64-unknown-linux-gnu --zig
13
14# 常見目標平台
15# x86_64-unknown-linux-gnu
16# aarch64-unknown-linux-gnu
17# x86_64-apple-darwin
18# aarch64-apple-darwin
19# x86_64-pc-windows-msvc

發布到 PyPI

 1# 發布到 TestPyPI（測試）
 2maturin publish --repository testpypi
 3
 4# 發布到 PyPI
 5maturin publish
 6
 7# 使用 API token
 8maturin publish --username __token__ --password <your-pypi-token>
 9
10# 或者設定環境變數
11export MATURIN_PYPI_TOKEN=<your-pypi-token>
12maturin publish

【實作層】CI/CD 整合

GitHub Actions

 1# .github/workflows/build.yml
 2name: Build and Publish
 3
 4on:
 5 push:
 6 tags:
 7 - 'v*'
 8 pull_request:
 9 branches:
 10 - main
 11
 12jobs:
 13 # Linux
 14 linux:
 15 runs-on: ubuntu-latest
 16 strategy:
 17 matrix:
 18 target: [x86_64, aarch64]
 19 steps:
 20 - uses: actions/checkout@v4
 21
 22 - uses: actions/setup-python@v5
 23 with:
 24 python-version: '3.11'
 25
 26 - name: Build wheels
 27 uses: PyO3/maturin-action@v1
 28 with:
 29 target: ${{ matrix.target }}
 30 args: --release --out dist
 31 manylinux: auto
 32
 33 - name: Upload wheels
 34 uses: actions/upload-artifact@v4
 35 with:
 36 name: wheels-linux-${{ matrix.target }}
 37 path: dist
 38
 39 # macOS
 40 macos:
 41 runs-on: macos-latest
 42 strategy:
 43 matrix:
 44 target: [x86_64, aarch64]
 45 steps:
 46 - uses: actions/checkout@v4
 47
 48 - uses: actions/setup-python@v5
 49 with:
 50 python-version: '3.11'
 51
 52 - name: Build wheels
 53 uses: PyO3/maturin-action@v1
 54 with:
 55 target: ${{ matrix.target }}-apple-darwin
 56 args: --release --out dist
 57
 58 - name: Upload wheels
 59 uses: actions/upload-artifact@v4
 60 with:
 61 name: wheels-macos-${{ matrix.target }}
 62 path: dist
 63
 64 # Windows
 65 windows:
 66 runs-on: windows-latest
 67 steps:
 68 - uses: actions/checkout@v4
 69
 70 - uses: actions/setup-python@v5
 71 with:
 72 python-version: '3.11'
 73
 74 - name: Build wheels
 75 uses: PyO3/maturin-action@v1
 76 with:
 77 args: --release --out dist
 78
 79 - name: Upload wheels
 80 uses: actions/upload-artifact@v4
 81 with:
 82 name: wheels-windows
 83 path: dist
 84
 85 # 發布
 86 publish:
 87 needs: [linux, macos, windows]
 88 runs-on: ubuntu-latest
 89 if: startsWith(github.ref, 'refs/tags/')
 90 steps:
 91 - uses: actions/download-artifact@v4
 92 with:
 93 pattern: wheels-*
 94 merge-multiple: true
 95 path: dist
 96
 97 - name: Publish to PyPI
 98 uses: PyO3/maturin-action@v1
 99 env:
100 MATURIN_PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
101 with:
102 command: upload
103 args: --non-interactive --skip-existing dist/*

測試工作流程

 1# .github/workflows/test.yml
 2name: Test
 3
 4on:
 5 push:
 6 branches: [main]
 7 pull_request:
 8
 9jobs:
10 test:
11 runs-on: ${{ matrix.os }}
12 strategy:
13 matrix:
14 os: [ubuntu-latest, macos-latest, windows-latest]
15 python-version: ['3.9', '3.10', '3.11', '3.12']
16 steps:
17 - uses: actions/checkout@v4
18
19 - uses: actions/setup-python@v5
20 with:
21 python-version: ${{ matrix.python-version }}
22
23 - name: Install Rust
24 uses: dtolnay/rust-toolchain@stable
25
26 - name: Install maturin
27 run: pip install maturin pytest
28
29 - name: Build and install
30 run: maturin develop
31
32 - name: Run tests
33 run: pytest tests/

【進階】效能優化

編譯優化

1# Cargo.toml
2[profile.release]
3lto = "fat" # 最佳化連結（較慢編譯）
4codegen-units = 1 # 單一編譯單元（更好優化）
5panic = "abort" # 不展開 panic（較小二進位）
6strip = true # 移除符號
7
8# 針對特定 CPU 優化
9# RUSTFLAGS="-C target-cpu=native" maturin build --release

減小二進位大小

 1# Cargo.toml
 2[profile.release]
 3opt-level = "z" # 優化大小而非速度
 4lto = true
 5strip = true
 6panic = "abort"
 7
 8[dependencies]
 9# 使用 features 減少不需要的程式碼
10pyo3 = { version = "0.23", default-features = false, features = ["extension-module"] }

除錯技巧

1# 保留除錯符號
2maturin develop --profile dev
3
4# 啟用 Rust backtrace
5RUST_BACKTRACE=1 python -c "import my_module; my_module.buggy_function()"
6
7# 使用 lldb/gdb
8lldb python
9(lldb) run -c "import my_module; my_module.buggy_function()"

【常見問題】疑難排解

編譯錯誤

 1問題：找不到 Python
 2
 3解決：
 41. 確認 Python 在 PATH 中
 52. 使用 --interpreter 指定路徑
 6 maturin develop --interpreter /usr/bin/python3.11
 7
 8問題：連結錯誤（Linux）
 9
10解決：
111. 安裝 python3-dev
12 sudo apt install python3-dev
132. 安裝 build-essential
14 sudo apt install build-essential
15
16問題：找不到 PyO3
17
18解決：
191. 確認 Cargo.toml 中有正確的 pyo3 依賴
202. 執行 cargo update

執行時錯誤

 1問題：ImportError: undefined symbol
 2
 3原因：模組和 Python 版本不匹配
 4
 5解決：
 61. 重新建構
 7 maturin develop
 82. 確認使用正確的 Python
 9 which python
10
11問題：記憶體錯誤 / Segfault
12
13原因：通常是 unsafe 程式碼或 GIL 問題
14
15解決：
161. 檢查 unsafe 區塊
172. 確認正確使用 py.allow_threads()
183. 使用 RUST_BACKTRACE=1 獲取堆疊追蹤

完整範例專案

專案結構

 1fibonacci_rs/
 2├── Cargo.toml
 3├── pyproject.toml
 4├── src/
 5│ └── lib.rs
 6├── python/
 7│ └── fibonacci_rs/
 8│ ├── __init__.py
 9│ └── py.typed
10├── tests/
11│ └── test_fib.py
12└── README.md

完整程式碼

 1# Cargo.toml
 2[package]
 3name = "fibonacci_rs"
 4version = "0.1.0"
 5edition = "2021"
 6
 7[lib]
 8name = "fibonacci_rs"
 9crate-type = ["cdylib"]
10
11[dependencies]
12pyo3 = { version = "0.23", features = ["extension-module"] }
13
14[profile.release]
15lto = true
16codegen-units = 1

 1# pyproject.toml
 2[build-system]
 3requires = ["maturin>=1.5,<2.0"]
 4build-backend = "maturin"
 5
 6[project]
 7name = "fibonacci-rs"
 8version = "0.1.0"
 9description = "Fast Fibonacci implementation in Rust"
10requires-python = ">=3.8"
11
12[tool.maturin]
13python-source = "python"
14module-name = "fibonacci_rs._core"

 1// src/lib.rs
 2use pyo3::prelude::*;
 3
 4/// 計算 Fibonacci 數列第 n 項
 5#[pyfunction]
 6fn fib(n: u64) -> u64 {
 7 if n <= 1 {
 8 return n;
 9 }
10 let mut a = 0u64;
11 let mut b = 1u64;
12 for _ in 2..=n {
13 let tmp = a + b;
14 a = b;
15 b = tmp;
16 }
17 b
18}
19
20/// 計算 Fibonacci 數列前 n 項
21#[pyfunction]
22fn fib_sequence(py: Python<'_>, n: usize) -> Vec<u64> {
23 py.allow_threads(|| {
24 let mut seq = Vec::with_capacity(n);
25 let (mut a, mut b) = (0u64, 1u64);
26 for _ in 0..n {
27 seq.push(a);
28 let tmp = a + b;
29 a = b;
30 b = tmp;
31 }
32 seq
33 })
34}
35
36#[pymodule]
37fn _core(m: &Bound<'_, PyModule>) -> PyResult<()> {
38 m.add_function(wrap_pyfunction!(fib, m)?)?;
39 m.add_function(wrap_pyfunction!(fib_sequence, m)?)?;
40 Ok(())
41}

1# python/fibonacci_rs/__init__.py
2from ._core import fib, fib_sequence
3
4__all__ = ["fib", "fib_sequence"]
5__version__ = "0.1.0"

 1# tests/test_fib.py
 2import fibonacci_rs
 3
 4def test_fib_zero():
 5 assert fibonacci_rs.fib(0) == 0
 6
 7def test_fib_one():
 8 assert fibonacci_rs.fib(1) == 1
 9
10def test_fib_ten():
11 assert fibonacci_rs.fib(10) == 55
12
13def test_fib_sequence():
14 seq = fibonacci_rs.fib_sequence(10)
15 assert seq == [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

思考題

為什麼 Maturin 使用 cdylib crate type？與 rlib 有什麼差異？
abi3 功能如何減少需要建構的 wheel 數量？有什麼限制？
在 CI 中建構跨平台 wheel 時，最大的挑戰是什麼？

實作練習

建立一個新的 Maturin 專案，實現一個簡單的字串處理函式
設定 GitHub Actions 自動建構並發布到 TestPyPI
比較 maturin develop 和 maturin develop --release 的編譯時間和執行效能

延伸閱讀

上一章：PyO3 基礎 下一章：實戰案例分析

5.4 實戰案例分析

Tue, 20 Jan 2026 00:00:00 +0000

本章分析幾個使用 Rust 的知名 Python 專案，學習實際應用的模式。

本章目標

學完本章後，你將能夠：

理解 Rust 在數值計算的應用
理解 Rust 在文字處理的應用
評估自己的專案是否適合使用 Rust

【案例一】數值計算：實現快速排序

需求分析

1場景：需要對大量數值資料進行排序
2問題：Python 內建排序雖然是 C 實現，但有特殊需求時需要自訂
3
4實現目標：
5├── 支援自訂比較函式
6├── 支援並行排序（大資料集）
7├── 與 NumPy 整合
8└── 效能接近或超過 NumPy sort

Rust 實現

 1// src/lib.rs
 2use pyo3::prelude::*;
 3use numpy::{PyArray1, PyReadonlyArray1};
 4use rayon::prelude::*;
 5
 6/// 並行快速排序
 7#[pyfunction]
 8fn parallel_sort(py: Python<'_>, arr: PyReadonlyArray1<'_, f64>) -> Bound<'_, PyArray1<f64>> {
 9 let arr = arr.as_array();
10
11 // 釋放 GIL 進行並行排序
12 let mut data: Vec<f64> = py.allow_threads(|| {
13 let mut data: Vec<f64> = arr.to_vec();
14 data.par_sort_by(|a, b| a.partial_cmp(b).unwrap());
15 data
16 });
17
18 PyArray1::from_vec(py, data)
19}
20
21/// 部分排序（只排序前 k 個元素）
22#[pyfunction]
23fn partial_sort(py: Python<'_>, arr: PyReadonlyArray1<'_, f64>, k: usize) -> PyResult<Bound<'_, PyArray1<f64>>> {
24 let arr = arr.as_array();
25
26 if k > arr.len() {
27 return Err(PyValueError::new_err("k 大於陣列長度"));
28 }
29
30 let result = py.allow_threads(|| {
31 let mut data: Vec<f64> = arr.to_vec();
32 // 使用 select_nth_unstable 獲得前 k 個最小元素
33 data.select_nth_unstable_by(k, |a, b| a.partial_cmp(b).unwrap());
34 data[..k].to_vec()
35 });
36
37 Ok(PyArray1::from_vec(py, result))
38}
39
40/// 找出 top-k 元素（不完全排序，更快）
41#[pyfunction]
42fn top_k(py: Python<'_>, arr: PyReadonlyArray1<'_, f64>, k: usize) -> PyResult<Bound<'_, PyArray1<f64>>> {
43 use std::collections::BinaryHeap;
44 use std::cmp::Ordering;
45
46 // 包裝 f64 以支援 BinaryHeap
47 #[derive(PartialEq)]
48 struct MinFloat(f64);
49
50 impl Eq for MinFloat {}
51
52 impl PartialOrd for MinFloat {
53 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
54 // 反向比較，使 BinaryHeap 成為 min-heap
55 other.0.partial_cmp(&self.0)
56 }
57 }
58
59 impl Ord for MinFloat {
60 fn cmp(&self, other: &Self) -> Ordering {
61 self.partial_cmp(other).unwrap()
62 }
63 }
64
65 let arr = arr.as_array();
66
67 let result = py.allow_threads(|| {
68 let mut heap: BinaryHeap<MinFloat> = BinaryHeap::with_capacity(k + 1);
69
70 for &x in arr.iter() {
71 heap.push(MinFloat(x));
72 if heap.len() > k {
73 heap.pop();
74 }
75 }
76
77 heap.into_sorted_vec().into_iter().map(|x| x.0).collect::<Vec<_>>()
78 });
79
80 Ok(PyArray1::from_vec(py, result))
81}
82
83#[pymodule]
84fn fast_sort(m: &Bound<'_, PyModule>) -> PyResult<()> {
85 m.add_function(wrap_pyfunction!(parallel_sort, m)?)?;
86 m.add_function(wrap_pyfunction!(partial_sort, m)?)?;
87 m.add_function(wrap_pyfunction!(top_k, m)?)?;
88 Ok(())
89}

效能比較

 1import numpy as np
 2import fast_sort
 3import timeit
 4
 5# 測試資料
 6n = 1_000_000
 7data = np.random.rand(n)
 8
 9# NumPy sort
10t_numpy = timeit.timeit(lambda: np.sort(data.copy()), number=10)
11
12# Rust parallel sort
13t_rust = timeit.timeit(lambda: fast_sort.parallel_sort(data), number=10)
14
15# 找 top-1000（Rust）
16t_topk_rust = timeit.timeit(lambda: fast_sort.top_k(data, 1000), number=10)
17
18# 找 top-1000（NumPy: 完整排序後取前 k）
19t_topk_numpy = timeit.timeit(lambda: np.sort(data)[:1000], number=10)
20
21print(f"完整排序 - NumPy: {t_numpy:.3f}s, Rust: {t_rust:.3f}s")
22print(f"Top-1000 - NumPy: {t_topk_numpy:.3f}s, Rust: {t_topk_rust:.3f}s")
23
24# 預期結果（依硬體而異）：
25# 完整排序 - NumPy: 0.85s, Rust: 0.45s（使用多核心）
26# Top-1000 - NumPy: 0.85s, Rust: 0.02s（不需完整排序）

【案例二】文字處理：高效能 Tokenizer

需求分析

1場景：NLP 應用需要將文字切分為 tokens
2問題：純 Python 實現太慢，無法處理大量文字
3
4實現目標：
5├── 支援 Unicode
6├── 支援正規表達式模式
7├── 批次處理
8└── 與現有 NLP 工具整合

Rust 實現

 1// src/lib.rs
 2use pyo3::prelude::*;
 3use regex::Regex;
 4use rayon::prelude::*;
 5
 6#[pyclass]
 7struct Tokenizer {
 8 pattern: Regex,
 9 lowercase: bool,
 10}
 11
 12#[pymethods]
 13impl Tokenizer {
 14 #[new]
 15 #[pyo3(signature = (pattern=r"\w+", lowercase=true))]
 16 fn new(pattern: &str, lowercase: bool) -> PyResult<Self> {
 17 let pattern = Regex::new(pattern)
 18 .map_err(|e| PyValueError::new_err(format!("無效的正規表達式: {}", e)))?;
 19 Ok(Tokenizer { pattern, lowercase })
 20 }
 21
 22 /// 對單一字串進行 tokenization
 23 fn tokenize(&self, text: &str) -> Vec<String> {
 24 self.pattern
 25 .find_iter(text)
 26 .map(|m| {
 27 let s = m.as_str();
 28 if self.lowercase {
 29 s.to_lowercase()
 30 } else {
 31 s.to_string()
 32 }
 33 })
 34 .collect()
 35 }
 36
 37 /// 批次 tokenization（並行處理）
 38 fn tokenize_batch(&self, py: Python<'_>, texts: Vec<String>) -> Vec<Vec<String>> {
 39 py.allow_threads(|| {
 40 texts
 41 .par_iter()
 42 .map(|text| self.tokenize(text))
 43 .collect()
 44 })
 45 }
 46
 47 /// 計算詞頻
 48 fn count_tokens(&self, py: Python<'_>, text: &str) -> HashMap<String, usize> {
 49 use std::collections::HashMap;
 50
 51 py.allow_threads(|| {
 52 let mut counts = HashMap::new();
 53 for mat in self.pattern.find_iter(text) {
 54 let token = if self.lowercase {
 55 mat.as_str().to_lowercase()
 56 } else {
 57 mat.as_str().to_string()
 58 };
 59 *counts.entry(token).or_insert(0) += 1;
 60 }
 61 counts
 62 })
 63 }
 64}
 65
 66// 簡單的 BPE（Byte Pair Encoding）實現
 67#[pyclass]
 68struct SimpleBPE {
 69 vocab: HashMap<String, u32>,
 70 merges: Vec<(String, String)>,
 71}
 72
 73#[pymethods]
 74impl SimpleBPE {
 75 #[new]
 76 fn new() -> Self {
 77 SimpleBPE {
 78 vocab: HashMap::new(),
 79 merges: Vec::new(),
 80 }
 81 }
 82
 83 /// 訓練 BPE
 84 fn train(&mut self, py: Python<'_>, texts: Vec<String>, vocab_size: usize) {
 85 use std::collections::HashMap;
 86
 87 py.allow_threads(|| {
 88 // 初始化：每個字元是一個 token
 89 let mut word_freqs: HashMap<Vec<String>, usize> = HashMap::new();
 90
 91 for text in &texts {
 92 for word in text.split_whitespace() {
 93 let chars: Vec<String> = word.chars().map(|c| c.to_string()).collect();
 94 *word_freqs.entry(chars).or_insert(0) += 1;
 95 }
 96 }
 97
 98 // 迭代合併最頻繁的 pair
 99 while self.vocab.len() < vocab_size {
100 // 計算 pair 頻率
101 let mut pair_freqs: HashMap<(String, String), usize> = HashMap::new();
102
103 for (word, freq) in &word_freqs {
104 for i in 0..word.len().saturating_sub(1) {
105 let pair = (word[i].clone(), word[i + 1].clone());
106 *pair_freqs.entry(pair).or_insert(0) += freq;
107 }
108 }
109
110 // 找出最頻繁的 pair
111 if let Some((best_pair, _)) = pair_freqs.iter().max_by_key(|(_, &freq)| freq) {
112 let new_token = format!("{}{}", best_pair.0, best_pair.1);
113 self.merges.push(best_pair.clone());
114 self.vocab.insert(new_token.clone(), self.vocab.len() as u32);
115
116 // 更新 word_freqs
117 let mut new_word_freqs = HashMap::new();
118 for (word, freq) in word_freqs {
119 let mut new_word = Vec::new();
120 let mut i = 0;
121 while i < word.len() {
122 if i + 1 < word.len() && word[i] == best_pair.0 && word[i + 1] == best_pair.1 {
123 new_word.push(new_token.clone());
124 i += 2;
125 } else {
126 new_word.push(word[i].clone());
127 i += 1;
128 }
129 }
130 *new_word_freqs.entry(new_word).or_insert(0) += freq;
131 }
132 word_freqs = new_word_freqs;
133 } else {
134 break;
135 }
136 }
137 });
138 }
139
140 /// 編碼文字
141 fn encode(&self, text: &str) -> Vec<u32> {
142 let mut tokens: Vec<String> = text.chars().map(|c| c.to_string()).collect();
143
144 for (a, b) in &self.merges {
145 let merged = format!("{}{}", a, b);
146 let mut new_tokens = Vec::new();
147 let mut i = 0;
148 while i < tokens.len() {
149 if i + 1 < tokens.len() && &tokens[i] == a && &tokens[i + 1] == b {
150 new_tokens.push(merged.clone());
151 i += 2;
152 } else {
153 new_tokens.push(tokens[i].clone());
154 i += 1;
155 }
156 }
157 tokens = new_tokens;
158 }
159
160 tokens
161 .iter()
162 .filter_map(|t| self.vocab.get(t).copied())
163 .collect()
164 }
165}
166
167use std::collections::HashMap;
168
169#[pymodule]
170fn fast_tokenizer(m: &Bound<'_, PyModule>) -> PyResult<()> {
171 m.add_class::<Tokenizer>()?;
172 m.add_class::<SimpleBPE>()?;
173 Ok(())
174}

使用範例

 1from fast_tokenizer import Tokenizer, SimpleBPE
 2
 3# 基本 tokenization
 4tokenizer = Tokenizer(r"\w+", lowercase=True)
 5
 6text = "Hello, World! This is a test."
 7tokens = tokenizer.tokenize(text)
 8print(tokens) # ['hello', 'world', 'this', 'is', 'a', 'test']
 9
10# 批次處理
11texts = ["First sentence.", "Second sentence.", "Third one."]
12batch_tokens = tokenizer.tokenize_batch(texts)
13print(batch_tokens)
14
15# 詞頻統計
16counts = tokenizer.count_tokens("the cat sat on the mat")
17print(counts) # {'the': 2, 'cat': 1, 'sat': 1, 'on': 1, 'mat': 1}
18
19# BPE 訓練
20bpe = SimpleBPE()
21corpus = ["hello world", "hello there", "world peace"]
22bpe.train(corpus, vocab_size=100)
23encoded = bpe.encode("hello world")
24print(encoded)

【案例三】資料驗證：Pydantic 風格驗證器

需求分析

1場景：API 需要驗證大量輸入資料
2問題：純 Python 驗證太慢（Pydantic v1 的問題）
3
4實現目標：
5├── 型別檢查
6├── 範圍驗證
7├── 自訂驗證函式
8└── 清晰的錯誤訊息

Rust 實現

 1// src/lib.rs
 2use pyo3::prelude::*;
 3use pyo3::exceptions::PyValueError;
 4use std::collections::HashMap;
 5
 6// 驗證錯誤
 7#[pyclass]
 8#[derive(Clone)]
 9struct ValidationError {
 10 #[pyo3(get)]
 11 field: String,
 12 #[pyo3(get)]
 13 message: String,
 14}
 15
 16#[pymethods]
 17impl ValidationError {
 18 fn __repr__(&self) -> String {
 19 format!("ValidationError(field='{}', message='{}')", self.field, self.message)
 20 }
 21}
 22
 23// 欄位驗證器
 24#[pyclass]
 25struct Field {
 26 name: String,
 27 field_type: String,
 28 required: bool,
 29 min_value: Option<f64>,
 30 max_value: Option<f64>,
 31 min_length: Option<usize>,
 32 max_length: Option<usize>,
 33 pattern: Option<regex::Regex>,
 34}
 35
 36#[pymethods]
 37impl Field {
 38 #[new]
 39 #[pyo3(signature = (name, field_type, required=true, min_value=None, max_value=None, min_length=None, max_length=None, pattern=None))]
 40 fn new(
 41 name: String,
 42 field_type: String,
 43 required: bool,
 44 min_value: Option<f64>,
 45 max_value: Option<f64>,
 46 min_length: Option<usize>,
 47 max_length: Option<usize>,
 48 pattern: Option<String>,
 49 ) -> PyResult<Self> {
 50 let pattern = match pattern {
 51 Some(p) => Some(regex::Regex::new(&p)
 52 .map_err(|e| PyValueError::new_err(format!("無效的正規表達式: {}", e)))?),
 53 None => None,
 54 };
 55
 56 Ok(Field {
 57 name,
 58 field_type,
 59 required,
 60 min_value,
 61 max_value,
 62 min_length,
 63 max_length,
 64 pattern,
 65 })
 66 }
 67}
 68
 69// Schema 驗證器
 70#[pyclass]
 71struct Schema {
 72 fields: Vec<Field>,
 73}
 74
 75#[pymethods]
 76impl Schema {
 77 #[new]
 78 fn new(fields: Vec<Py<Field>>) -> PyResult<Self> {
 79 Python::with_gil(|py| {
 80 let fields: Vec<Field> = fields
 81 .iter()
 82 .map(|f| f.borrow(py).clone())
 83 .collect();
 84 Ok(Schema { fields })
 85 })
 86 }
 87
 88 /// 驗證單一物件
 89 fn validate(&self, py: Python<'_>, data: &Bound<'_, PyDict>) -> PyResult<Vec<ValidationError>> {
 90 let mut errors = Vec::new();
 91
 92 for field in &self.fields {
 93 let value = data.get_item(&field.name)?;
 94
 95 match value {
 96 None => {
 97 if field.required {
 98 errors.push(ValidationError {
 99 field: field.name.clone(),
100 message: "此欄位為必填".to_string(),
101 });
102 }
103 }
104 Some(v) => {
105 // 型別檢查
106 match field.field_type.as_str() {
107 "int" => {
108 if let Ok(num) = v.extract::<i64>() {
109 // 範圍檢查
110 if let Some(min) = field.min_value {
111 if (num as f64) < min {
112 errors.push(ValidationError {
113 field: field.name.clone(),
114 message: format!("值必須 >= {}", min),
115 });
116 }
117 }
118 if let Some(max) = field.max_value {
119 if (num as f64) > max {
120 errors.push(ValidationError {
121 field: field.name.clone(),
122 message: format!("值必須 <= {}", max),
123 });
124 }
125 }
126 } else {
127 errors.push(ValidationError {
128 field: field.name.clone(),
129 message: "必須是整數".to_string(),
130 });
131 }
132 }
133 "float" => {
134 if let Ok(num) = v.extract::<f64>() {
135 if let Some(min) = field.min_value {
136 if num < min {
137 errors.push(ValidationError {
138 field: field.name.clone(),
139 message: format!("值必須 >= {}", min),
140 });
141 }
142 }
143 if let Some(max) = field.max_value {
144 if num > max {
145 errors.push(ValidationError {
146 field: field.name.clone(),
147 message: format!("值必須 <= {}", max),
148 });
149 }
150 }
151 } else {
152 errors.push(ValidationError {
153 field: field.name.clone(),
154 message: "必須是浮點數".to_string(),
155 });
156 }
157 }
158 "str" => {
159 if let Ok(s) = v.extract::<String>() {
160 // 長度檢查
161 if let Some(min_len) = field.min_length {
162 if s.len() < min_len {
163 errors.push(ValidationError {
164 field: field.name.clone(),
165 message: format!("長度必須 >= {}", min_len),
166 });
167 }
168 }
169 if let Some(max_len) = field.max_length {
170 if s.len() > max_len {
171 errors.push(ValidationError {
172 field: field.name.clone(),
173 message: format!("長度必須 <= {}", max_len),
174 });
175 }
176 }
177 // 正規表達式檢查
178 if let Some(ref pattern) = field.pattern {
179 if !pattern.is_match(&s) {
180 errors.push(ValidationError {
181 field: field.name.clone(),
182 message: "格式不符合要求".to_string(),
183 });
184 }
185 }
186 } else {
187 errors.push(ValidationError {
188 field: field.name.clone(),
189 message: "必須是字串".to_string(),
190 });
191 }
192 }
193 _ => {}
194 }
195 }
196 }
197 }
198
199 Ok(errors)
200 }
201
202 /// 批次驗證
203 fn validate_batch(&self, py: Python<'_>, data_list: Vec<Bound<'_, PyDict>>) -> PyResult<Vec<Vec<ValidationError>>> {
204 let mut results = Vec::new();
205 for data in data_list {
206 results.push(self.validate(py, &data)?);
207 }
208 Ok(results)
209 }
210}
211
212use pyo3::types::PyDict;
213
214#[pymodule]
215fn fast_validator(m: &Bound<'_, PyModule>) -> PyResult<()> {
216 m.add_class::<Field>()?;
217 m.add_class::<Schema>()?;
218 m.add_class::<ValidationError>()?;
219 Ok(())
220}

使用範例

 1from fast_validator import Field, Schema
 2
 3# 定義 schema
 4schema = Schema([
 5 Field("name", "str", required=True, min_length=1, max_length=100),
 6 Field("age", "int", required=True, min_value=0, max_value=150),
 7 Field("email", "str", required=True, pattern=r"^[\w\.-]+@[\w\.-]+\.\w+$"),
 8 Field("score", "float", required=False, min_value=0, max_value=100),
 9])
10
11# 驗證資料
12data = {"name": "Alice", "age": 30, "email": "alice@example.com"}
13errors = schema.validate(data)
14if errors:
15 for e in errors:
16 print(f"{e.field}: {e.message}")
17else:
18 print("驗證通過")
19
20# 無效資料
21invalid_data = {"name": "", "age": -5, "email": "invalid"}
22errors = schema.validate(invalid_data)
23for e in errors:
24 print(f"{e.field}: {e.message}")
25# name: 長度必須 >= 1
26# age: 值必須 >= 0
27# email: 格式不符合要求

【總結】何時使用 Rust

決策清單

 1應該使用 Rust：
 2
 31. 效能瓶頸明確
 4 □ profiler 顯示特定函式占用大量時間
 5 □ 純 Python 優化已到極限
 6 □ 現有 C 擴展不滿足需求
 7
 82. 資料處理需求
 9 □ 大量數值計算
10 □ 頻繁的字串處理
11 □ 需要並行處理
12
133. 安全性要求
14 □ 處理不可信的輸入
15 □ 需要避免記憶體錯誤
16 □ 長期運行的服務
17
184. 跨平台需求
19 □ 需要支援多個作業系統
20 □ 需要支援多個 Python 版本
21
22可能不需要 Rust：
23
241. 效能不是主要瓶頸
252. 團隊沒有 Rust 經驗且時間緊迫
263. 專案規模小且不會長期維護
274. 可以用現有函式庫解決

最佳實踐

 11. 設計階段
 2 ├── 明確定義 Python/Rust 邊界
 3 ├── 最小化跨語言呼叫次數
 4 ├── 使用批次處理減少開銷
 5 └── 設計清晰的錯誤處理
 6
 72. 開發階段
 8 ├── 先用 Python 原型驗證邏輯
 9 ├── 逐步將瓶頸移到 Rust
10 ├── 完善的測試覆蓋
11 └── 使用 maturin develop 快速迭代
12
133. 發布階段
14 ├── 使用 CI/CD 自動建構 wheel
15 ├── 支援主流 Python 版本
16 ├── 提供 fallback 純 Python 實現
17 └── 清楚的安裝文件

思考題

在設計 Rust 擴展的 API 時，如何平衡效能和易用性？
如何處理 Rust 函式庫沒有 Python 綁定的情況？
在什麼情況下，應該用 Cython 而不是 Rust？

實作練習

選擇一個你常用的純 Python 函式，用 Rust 重寫並比較效能
分析 Polars 的原始碼結構，理解大型 Rust Python 專案的組織方式
實現一個簡單的 JSON parser，比較與 Python json 模組的效能差異

延伸閱讀

上一章：Maturin 開發流程 下一模組：模組六：打包與發布