案例研究 on Tarragon

案例：PyO3 文字解析

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/markdown_link_checker.py 的實際程式碼，展示如何用 PyO3 和 Rust 實現高效能的文字解析器。

先備知識

問題背景

現有設計

markdown_link_checker.py 使用純 Python 的正則表達式解析 Markdown 連結：

 1import re
 2from typing import List, Dict
 3
 4class MarkdownLinkChecker:
 5    """Markdown 連結檢查器"""
 6
 7    # Markdown 連結正則表達式
 8    # 匹配 [text](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/target) 格式，排除圖片 ![alt](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/src)
 9    INLINE_LINK_PATTERN = re.compile(
10        r'(?
11    )
12
13    # 引用式連結定義 [ref]: target
14    REFERENCE_DEF_PATTERN = re.compile(
15        r'^\s*\[([^\]]+)\]:\s*(.+)$',
16        re.MULTILINE
17    )
18
19    # 引用式連結使用 [text][ref]
20    REFERENCE_USE_PATTERN = re.compile(
21        r'\[([^\]]+)\]\[([^\]]+)\]'
22    )
23
24    def parse_markdown_links(self, content: str) -> List[Dict]:
25        """
26        解析 Markdown 內容中的所有連結
27
28        Args:
29            content: Markdown 內容
30
31        Returns:
32            list[dict]: 連結列表，每個包含 text, target, line
33        """
34        links = []
35        lines = content.split('\n')
36
37        # 首先收集引用式連結定義
38        reference_defs = {}
39        for match in self.REFERENCE_DEF_PATTERN.finditer(content):
40            ref_name = match.group(1).lower()
41            ref_target = match.group(2).strip()
42            reference_defs[ref_name] = ref_target
43
44        # 追蹤是否在程式碼區塊內
45        in_code_block = False
46
47        # 解析行內連結
48        for line_num, line in enumerate(lines, start=1):
49            # 檢查程式碼區塊開始/結束
50            if line.strip().startswith("```"):
51                in_code_block = not in_code_block
52                continue
53
54            # 跳過程式碼區塊內的連結
55            if in_code_block:
56                continue
57
58            # 行內連結 [text](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/target)
59            for match in self.INLINE_LINK_PATTERN.finditer(line):
60                links.append({
61                    "text": match.group(1),
62                    "target": match.group(2),
63                    "line": line_num
64                })
65
66            # 引用式連結 [text][ref]
67            for match in self.REFERENCE_USE_PATTERN.finditer(line):
68                ref_name = match.group(2).lower()
69                if ref_name in reference_defs:
70                    links.append({
71                        "text": match.group(1),
72                        "target": reference_defs[ref_name],
73                        "line": line_num
74                    })
75
76        return links

這段程式碼的核心瓶頸：

正則表達式解析：Python 的 re 模組效能有限
字串分割與迭代：大量的記憶體配置
字典操作：每個連結都建立新字典

為什麼選擇 Rust？

相比 Cython：

面向	Cython	Rust (PyO3)
記憶體安全	依賴 GC	編譯時保證
正則表達式	仍用 Python re	原生 regex crate
錯誤處理	例外機制	Result 類型
多執行緒	受 GIL 限制	可完全繞過 GIL
生態系統	有限	豐富的 Cargo 生態

進階解決方案

設計目標

用 Rust 重寫核心解析邏輯
保持 Python API 相容
實現顯著的效能提升

實作步驟

步驟 1：建立 Rust 專案結構

首先，使用 Maturin 建立新專案：

 1# 安裝 maturin（如果尚未安裝）
 2pip install maturin
 3
 4# 建立新專案
 5mkdir markdown_parser_rs
 6cd markdown_parser_rs
 7
 8# 初始化 maturin 專案（選擇 pyo3 作為綁定）
 9maturin init --bindings pyo3
10
11# 專案結構如下：
12# markdown_parser_rs/
13# ├── Cargo.toml
14# ├── pyproject.toml
15# └── src/
16#     └── lib.rs

接著，編輯 Cargo.toml 加入必要的依賴：

 1[package]
 2name = "markdown_parser_rs"
 3version = "0.1.0"
 4edition = "2021"
 5
 6[lib]
 7name = "markdown_parser_rs"
 8crate-type = ["cdylib"]
 9
10[dependencies]
11pyo3 = { version = "0.22", features = ["extension-module"] }
12regex = "1.11"
13once_cell = "1.20"

步驟 2：實作 Rust 解析函式

先定義核心的資料結構和解析邏輯：

 1// src/lib.rs
 2use once_cell::sync::Lazy;
 3use regex::Regex;
 4use std::collections::HashMap;
 5
 6/// Represents a parsed markdown link
 7#[derive(Debug, Clone)]
 8pub struct MarkdownLink {
 9    pub text: String,
10    pub target: String,
11    pub line: usize,
12}
13
14// Pre-compiled regex patterns (compile once, use many times)
15static INLINE_LINK_PATTERN: Lazy<Regex> = Lazy::new(|| {
16    // Match [text](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/target), excluding images ![alt](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/src)
17    Regex::new(r"(?).unwrap()
18});
19
20static REFERENCE_DEF_PATTERN: Lazy<Regex> = Lazy::new(|| {
21    // Match [ref]: target
22    Regex::new(r"(?m)^\s*\[([^\]]+)\]:\s*(.+)$").unwrap()
23});
24
25static REFERENCE_USE_PATTERN: Lazy<Regex> = Lazy::new(|| {
26    // Match [text][ref]
27    Regex::new(r"\[([^\]]+)\]\[([^\]]+)\]").unwrap()
28});
29
30/// Parse markdown content and extract all links
31pub fn parse_links(content: &str) -> Vec<MarkdownLink> {
32    let mut links = Vec::new();
33
34    // First, collect reference definitions
35    let mut reference_defs: HashMap<String, String> = HashMap::new();
36    for cap in REFERENCE_DEF_PATTERN.captures_iter(content) {
37        let ref_name = cap[1].to_lowercase();
38        let ref_target = cap[2].trim().to_string();
39        reference_defs.insert(ref_name, ref_target);
40    }
41
42    // Track code block state
43    let mut in_code_block = false;
44
45    // Parse line by line
46    for (line_num, line) in content.lines().enumerate() {
47        let line_number = line_num + 1; // 1-indexed
48
49        // Check for code block markers
50        if line.trim_start().starts_with("```") {
51            in_code_block = !in_code_block;
52            continue;
53        }
54
55        // Skip content inside code blocks
56        if in_code_block {
57            continue;
58        }
59
60        // Parse inline links [text](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/target)
61        for cap in INLINE_LINK_PATTERN.captures_iter(line) {
62            links.push(MarkdownLink {
63                text: cap[1].to_string(),
64                target: cap[2].to_string(),
65                line: line_number,
66            });
67        }
68
69        // Parse reference links [text][ref]
70        for cap in REFERENCE_USE_PATTERN.captures_iter(line) {
71            let ref_name = cap[2].to_lowercase();
72            if let Some(target) = reference_defs.get(&ref_name) {
73                links.push(MarkdownLink {
74                    text: cap[1].to_string(),
75                    target: target.clone(),
76                    line: line_number,
77                });
78            }
79        }
80    }
81
82    links
83}

步驟 3：用 PyO3 導出 Python 介面

將 Rust 結構與函式導出給 Python 使用：

  1use pyo3::prelude::*;
  2use pyo3::types::PyDict;
  3
  4/// Python-visible link structure
  5#[pyclass]
  6#[derive(Clone)]
  7pub struct PyMarkdownLink {
  8    #[pyo3(get)]
  9    pub text: String,
 10    #[pyo3(get)]
 11    pub target: String,
 12    #[pyo3(get)]
 13    pub line: usize,
 14}
 15
 16#[pymethods]
 17impl PyMarkdownLink {
 18    fn __repr__(&self) -> String {
 19        format!(
 20            "MarkdownLink(text='{}', target='{}', line={})",
 21            self.text, self.target, self.line
 22        )
 23    }
 24
 25    /// Convert to Python dict for compatibility
 26    fn to_dict<'py>(&self, py: Python<'py>) -> Bound<'py, PyDict> {
 27        let dict = PyDict::new(py);
 28        dict.set_item("text", &self.text).unwrap();
 29        dict.set_item("target", &self.target).unwrap();
 30        dict.set_item("line", self.line).unwrap();
 31        dict
 32    }
 33}
 34
 35impl From<MarkdownLink> for PyMarkdownLink {
 36    fn from(link: MarkdownLink) -> Self {
 37        PyMarkdownLink {
 38            text: link.text,
 39            target: link.target,
 40            line: link.line,
 41        }
 42    }
 43}
 44
 45/// Parse markdown content and return list of links as objects
 46#[pyfunction]
 47fn parse_markdown_links(content: &str) -> Vec<PyMarkdownLink> {
 48    parse_links(content)
 49        .into_iter()
 50        .map(PyMarkdownLink::from)
 51        .collect()
 52}
 53
 54/// Parse markdown content and return list of links as dicts
 55/// (for drop-in compatibility with existing Python code)
 56#[pyfunction]
 57fn parse_markdown_links_as_dicts<'py>(
 58    py: Python<'py>,
 59    content: &str,
 60) -> Vec<Bound<'py, PyDict>> {
 61    parse_links(content)
 62        .into_iter()
 63        .map(|link| {
 64            let dict = PyDict::new(py);
 65            dict.set_item("text", link.text).unwrap();
 66            dict.set_item("target", link.target).unwrap();
 67            dict.set_item("line", link.line).unwrap();
 68            dict
 69        })
 70        .collect()
 71}
 72
 73/// Filter out external links, keeping only internal links
 74#[pyfunction]
 75fn filter_internal_links(links: Vec<PyMarkdownLink>) -> Vec<PyMarkdownLink> {
 76    links
 77        .into_iter()
 78        .filter(|link| {
 79            let target = &link.target;
 80            // Skip pure anchor links
 81            if target.starts_with('#') {
 82                return false;
 83            }
 84            // Skip external links
 85            if target.starts_with("http://")
 86                || target.starts_with("https://")
 87                || target.starts_with("mailto:")
 88                || target.starts_with("tel:")
 89                || target.starts_with("ftp://")
 90            {
 91                return false;
 92            }
 93            true
 94        })
 95        .collect()
 96}
 97
 98/// Python module definition
 99#[pymodule]
100fn markdown_parser_rs(m: &Bound<'_, PyModule>) -> PyResult<()> {
101    m.add_class::<PyMarkdownLink>()?;
102    m.add_function(wrap_pyfunction!(parse_markdown_links, m)?)?;
103    m.add_function(wrap_pyfunction!(parse_markdown_links_as_dicts, m)?)?;
104    m.add_function(wrap_pyfunction!(filter_internal_links, m)?)?;
105    Ok(())
106}

步驟 4：建置與測試

 1# 開發模式建置（快速，用於測試）
 2maturin develop
 3
 4# 或者以 release 模式建置（優化效能）
 5maturin develop --release
 6
 7# 建置 wheel 套件
 8maturin build --release
 9
10# 安裝到當前環境
11pip install target/wheels/markdown_parser_rs-*.whl

完整程式碼

以下是完整的 src/lib.rs：

  1//! Markdown Link Parser - A high-performance parser written in Rust
  2//!
  3//! This module provides fast markdown link parsing capabilities
  4//! using Rust's regex crate and PyO3 for Python bindings.
  5
  6use once_cell::sync::Lazy;
  7use pyo3::prelude::*;
  8use pyo3::types::PyDict;
  9use regex::Regex;
 10use std::collections::HashMap;
 11
 12// ============================================================================
 13// Core Data Structures
 14// ============================================================================
 15
 16/// Internal link representation
 17#[derive(Debug, Clone)]
 18struct MarkdownLink {
 19    text: String,
 20    target: String,
 21    line: usize,
 22}
 23
 24/// Python-visible link structure with getter methods
 25#[pyclass]
 26#[derive(Clone)]
 27pub struct PyMarkdownLink {
 28    #[pyo3(get)]
 29    pub text: String,
 30    #[pyo3(get)]
 31    pub target: String,
 32    #[pyo3(get)]
 33    pub line: usize,
 34}
 35
 36#[pymethods]
 37impl PyMarkdownLink {
 38    /// String representation for debugging
 39    fn __repr__(&self) -> String {
 40        format!(
 41            "MarkdownLink(text='{}', target='{}', line={})",
 42            self.text, self.target, self.line
 43        )
 44    }
 45
 46    /// Convert to Python dict for compatibility with existing code
 47    fn to_dict<'py>(&self, py: Python<'py>) -> Bound<'py, PyDict> {
 48        let dict = PyDict::new(py);
 49        dict.set_item("text", &self.text).unwrap();
 50        dict.set_item("target", &self.target).unwrap();
 51        dict.set_item("line", self.line).unwrap();
 52        dict
 53    }
 54}
 55
 56impl From<MarkdownLink> for PyMarkdownLink {
 57    fn from(link: MarkdownLink) -> Self {
 58        PyMarkdownLink {
 59            text: link.text,
 60            target: link.target,
 61            line: link.line,
 62        }
 63    }
 64}
 65
 66// ============================================================================
 67// Pre-compiled Regex Patterns
 68// ============================================================================
 69
 70// Inline link: [text](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/target), excluding images ![alt](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/src)
 71static INLINE_LINK_PATTERN: Lazy<Regex> = Lazy::new(|| {
 72    Regex::new(r"(?).unwrap()
 73});
 74
 75// Reference definition: [ref]: target
 76static REFERENCE_DEF_PATTERN: Lazy<Regex> = Lazy::new(|| {
 77    Regex::new(r"(?m)^\s*\[([^\]]+)\]:\s*(.+)$").unwrap()
 78});
 79
 80// Reference usage: [text][ref]
 81static REFERENCE_USE_PATTERN: Lazy<Regex> = Lazy::new(|| {
 82    Regex::new(r"\[([^\]]+)\]\[([^\]]+)\]").unwrap()
 83});
 84
 85// ============================================================================
 86// Core Parsing Logic
 87// ============================================================================
 88
 89/// Parse markdown content and extract all links
 90///
 91/// This function handles:
 92/// - Inline links: [text](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/url)
 93/// - Reference links: [text][ref] with [ref]: url definitions
 94/// - Code block detection (skips links inside ```)
 95fn parse_links(content: &str) -> Vec<MarkdownLink> {
 96    let mut links = Vec::new();
 97
 98    // Phase 1: Collect all reference definitions
 99    let mut reference_defs: HashMap<String, String> = HashMap::new();
100    for cap in REFERENCE_DEF_PATTERN.captures_iter(content) {
101        let ref_name = cap[1].to_lowercase();
102        let ref_target = cap[2].trim().to_string();
103        reference_defs.insert(ref_name, ref_target);
104    }
105
106    // Phase 2: Parse links line by line
107    let mut in_code_block = false;
108
109    for (line_num, line) in content.lines().enumerate() {
110        let line_number = line_num + 1; // Convert to 1-indexed
111
112        // Toggle code block state
113        if line.trim_start().starts_with("```") {
114            in_code_block = !in_code_block;
115            continue;
116        }
117
118        // Skip content inside code blocks
119        if in_code_block {
120            continue;
121        }
122
123        // Extract inline links
124        for cap in INLINE_LINK_PATTERN.captures_iter(line) {
125            links.push(MarkdownLink {
126                text: cap[1].to_string(),
127                target: cap[2].to_string(),
128                line: line_number,
129            });
130        }
131
132        // Extract reference-style links
133        for cap in REFERENCE_USE_PATTERN.captures_iter(line) {
134            let ref_name = cap[2].to_lowercase();
135            if let Some(target) = reference_defs.get(&ref_name) {
136                links.push(MarkdownLink {
137                    text: cap[1].to_string(),
138                    target: target.clone(),
139                    line: line_number,
140                });
141            }
142        }
143    }
144
145    links
146}
147
148/// Check if a link target is external
149fn is_external_link(target: &str) -> bool {
150    target.starts_with("http://")
151        || target.starts_with("https://")
152        || target.starts_with("mailto:")
153        || target.starts_with("tel:")
154        || target.starts_with("ftp://")
155}
156
157// ============================================================================
158// Python Interface Functions
159// ============================================================================
160
161/// Parse markdown content and return a list of MarkdownLink objects
162///
163/// Args:
164///     content: The markdown content to parse
165///
166/// Returns:
167///     List of MarkdownLink objects
168///
169/// Example:
170///     >>> links = parse_markdown_links("Check [docs](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/README.md)")
171///     >>> links[0].text
172///     'docs'
173///     >>> links[0].target
174///     './README.md'
175#[pyfunction]
176fn parse_markdown_links(content: &str) -> Vec<PyMarkdownLink> {
177    parse_links(content)
178        .into_iter()
179        .map(PyMarkdownLink::from)
180        .collect()
181}
182
183/// Parse markdown content and return a list of dicts
184///
185/// This function provides drop-in compatibility with the original
186/// Python implementation that returns dicts.
187///
188/// Args:
189///     content: The markdown content to parse
190///
191/// Returns:
192///     List of dicts with keys: text, target, line
193#[pyfunction]
194fn parse_markdown_links_as_dicts<'py>(
195    py: Python<'py>,
196    content: &str,
197) -> Vec<Bound<'py, PyDict>> {
198    parse_links(content)
199        .into_iter()
200        .map(|link| {
201            let dict = PyDict::new(py);
202            dict.set_item("text", link.text).unwrap();
203            dict.set_item("target", link.target).unwrap();
204            dict.set_item("line", link.line).unwrap();
205            dict
206        })
207        .collect()
208}
209
210/// Filter links to keep only internal ones
211///
212/// Removes:
213/// - External links (http://, https://, mailto:, etc.)
214/// - Pure anchor links (#section)
215///
216/// Args:
217///     links: List of MarkdownLink objects
218///
219/// Returns:
220///     Filtered list of internal links
221#[pyfunction]
222fn filter_internal_links(links: Vec<PyMarkdownLink>) -> Vec<PyMarkdownLink> {
223    links
224        .into_iter()
225        .filter(|link| {
226            let target = &link.target;
227            // Skip pure anchor links
228            if target.starts_with('#') {
229                return false;
230            }
231            // Skip external links
232            !is_external_link(target)
233        })
234        .collect()
235}
236
237/// Count total links in content (fast path, no object creation)
238///
239/// Args:
240///     content: The markdown content to parse
241///
242/// Returns:
243///     Number of links found
244#[pyfunction]
245fn count_links(content: &str) -> usize {
246    parse_links(content).len()
247}
248
249/// Parse and filter in one pass (most efficient for link checking)
250///
251/// Args:
252///     content: The markdown content to parse
253///
254/// Returns:
255///     List of internal MarkdownLink objects
256#[pyfunction]
257fn parse_internal_links(content: &str) -> Vec<PyMarkdownLink> {
258    parse_links(content)
259        .into_iter()
260        .filter(|link| {
261            !link.target.starts_with('#') && !is_external_link(&link.target)
262        })
263        .map(PyMarkdownLink::from)
264        .collect()
265}
266
267// ============================================================================
268// Module Definition
269// ============================================================================
270
271/// High-performance Markdown link parser
272///
273/// This module provides Rust-powered functions for parsing
274/// and filtering markdown links.
275///
276/// Functions:
277///     parse_markdown_links: Parse content, return MarkdownLink objects
278///     parse_markdown_links_as_dicts: Parse content, return dicts
279///     parse_internal_links: Parse and filter to internal links only
280///     filter_internal_links: Filter existing links
281///     count_links: Fast link counting
282///
283/// Classes:
284///     MarkdownLink: Represents a parsed link
285#[pymodule]
286fn markdown_parser_rs(m: &Bound<'_, PyModule>) -> PyResult<()> {
287    m.add_class::<PyMarkdownLink>()?;
288    m.add_function(wrap_pyfunction!(parse_markdown_links, m)?)?;
289    m.add_function(wrap_pyfunction!(parse_markdown_links_as_dicts, m)?)?;
290    m.add_function(wrap_pyfunction!(filter_internal_links, m)?)?;
291    m.add_function(wrap_pyfunction!(count_links, m)?)?;
292    m.add_function(wrap_pyfunction!(parse_internal_links, m)?)?;
293    Ok(())
294}

Python 整合範例

以下展示如何在現有程式碼中整合 Rust 模組：

  1"""
  2使用 Rust 加速的 Markdown 連結檢查器
  3
  4這個範例展示如何用 Rust 模組替換原有的 Python 解析邏輯，
  5同時保持 API 相容性。
  6"""
  7
  8from pathlib import Path
  9from typing import List, Dict, Optional
 10
 11# Try to import Rust module, fallback to pure Python
 12try:
 13    import markdown_parser_rs as parser_rs
 14    USE_RUST = True
 15    print("Using Rust-powered parser")
 16except ImportError:
 17    USE_RUST = False
 18    print("Rust module not available, using pure Python")
 19
 20class MarkdownLinkChecker:
 21    """Markdown link checker with optional Rust acceleration"""
 22
 23    def __init__(self, use_rust: bool = True):
 24        """
 25        Initialize the checker
 26
 27        Args:
 28            use_rust: Whether to use Rust module if available
 29        """
 30        self.use_rust = use_rust and USE_RUST
 31
 32    def parse_markdown_links(self, content: str) -> List[Dict]:
 33        """
 34        Parse markdown content and extract all links
 35
 36        Args:
 37            content: Markdown content
 38
 39        Returns:
 40            List of dicts with keys: text, target, line
 41        """
 42        if self.use_rust:
 43            # Use Rust implementation
 44            return parser_rs.parse_markdown_links_as_dicts(content)
 45        else:
 46            # Fallback to pure Python (original implementation)
 47            return self._parse_python(content)
 48
 49    def parse_internal_links(self, content: str) -> List[Dict]:
 50        """
 51        Parse and filter to internal links only
 52
 53        Args:
 54            content: Markdown content
 55
 56        Returns:
 57            List of internal link dicts
 58        """
 59        if self.use_rust:
 60            # Use optimized Rust function that parses and filters in one pass
 61            links = parser_rs.parse_internal_links(content)
 62            return [link.to_dict() for link in links]
 63        else:
 64            all_links = self._parse_python(content)
 65            return self._filter_internal(all_links)
 66
 67    def _parse_python(self, content: str) -> List[Dict]:
 68        """Pure Python implementation (fallback)"""
 69        import re
 70
 71        INLINE_LINK = re.compile(r'(?)
 72        REFERENCE_DEF = re.compile(r'(?m)^\s*\[([^\]]+)\]:\s*(.+)$')
 73        REFERENCE_USE = re.compile(r'\[([^\]]+)\]\[([^\]]+)\]')
 74
 75        links = []
 76
 77        # Collect reference definitions
 78        reference_defs = {}
 79        for match in REFERENCE_DEF.finditer(content):
 80            ref_name = match.group(1).lower()
 81            ref_target = match.group(2).strip()
 82            reference_defs[ref_name] = ref_target
 83
 84        # Parse line by line
 85        in_code_block = False
 86        for line_num, line in enumerate(content.split('\n'), start=1):
 87            if line.strip().startswith("```"):
 88                in_code_block = not in_code_block
 89                continue
 90
 91            if in_code_block:
 92                continue
 93
 94            for match in INLINE_LINK.finditer(line):
 95                links.append({
 96                    "text": match.group(1),
 97                    "target": match.group(2),
 98                    "line": line_num
 99                })
100
101            for match in REFERENCE_USE.finditer(line):
102                ref_name = match.group(2).lower()
103                if ref_name in reference_defs:
104                    links.append({
105                        "text": match.group(1),
106                        "target": reference_defs[ref_name],
107                        "line": line_num
108                    })
109
110        return links
111
112    def _filter_internal(self, links: List[Dict]) -> List[Dict]:
113        """Filter to internal links only"""
114        external_prefixes = (
115            'http://', 'https://', 'mailto:', 'tel:', 'ftp://'
116        )
117        return [
118            link for link in links
119            if not link['target'].startswith('#')
120            and not link['target'].startswith(external_prefixes)
121        ]
122
123# Convenience functions
124def check_file(file_path: str, use_rust: bool = True) -> Dict:
125    """
126    Check a single markdown file for broken links
127
128    Args:
129        file_path: Path to the markdown file
130        use_rust: Whether to use Rust acceleration
131
132    Returns:
133        Dict with file_path, total_links, and internal_links count
134    """
135    checker = MarkdownLinkChecker(use_rust=use_rust)
136    path = Path(file_path)
137    content = path.read_text(encoding='utf-8')
138
139    all_links = checker.parse_markdown_links(content)
140    internal_links = checker.parse_internal_links(content)
141
142    return {
143        "file_path": str(path),
144        "total_links": len(all_links),
145        "internal_links": len(internal_links),
146        "links": internal_links
147    }
148
149if __name__ == "__main__":
150    # Example usage
151    sample = (
152        "# Sample Document\n\n"
153        "Check the [documentation](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/docs/README.md) for more info.\n\n"
154        "External link: [Google](https://google.com)\n\n"
155        "Reference style: [API docs][api]\n\n"
156        "[api]: ./api/reference.md\n\n"
157        "~~~python\n"
158        "# This [link](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/should_be_ignored.md) is in a code block\n"
159        "~~~\n"
160    )
161
162    checker = MarkdownLinkChecker()
163    links = checker.parse_markdown_links(sample)
164
165    print("All links found:")
166    for link in links:
167        print(f"  Line {link['line']}: [{link['text']}](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/{link['target']})")
168
169    print("\nInternal links only:")
170    internal = checker.parse_internal_links(sample)
171    for link in internal:
172        print(f"  Line {link['line']}: [{link['text']}](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/{link['target']})")

效能比較

以下是完整的效能測試腳本：

  1"""
  2Performance comparison: Python vs Cython vs Rust
  3
  4This script benchmarks the three implementations on
  5various markdown file sizes.
  6"""
  7
  8import time
  9import statistics
 10from pathlib import Path
 11from typing import Callable, List, Tuple
 12
 13# Generate test data
 14def generate_markdown(num_links: int) -> str:
 15    """Generate markdown content with specified number of links"""
 16    lines = ["# Test Document\n"]
 17
 18    for i in range(num_links):
 19        if i % 5 == 0:
 20            # Inline link
 21            lines.append(f"Check [link{i}](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/path/to/file{i}.md) for info.\n")
 22        elif i % 5 == 1:
 23            # External link (should be filtered)
 24            lines.append(f"Visit [site{i}](https://example{i}.com)\n")
 25        elif i % 5 == 2:
 26            # Reference style link
 27            lines.append(f"See [doc{i}][ref{i}]\n")
 28            lines.append(f"[ref{i}]: ./docs/page{i}.md\n")
 29        elif i % 5 == 3:
 30            # Anchor link (should be filtered)
 31            lines.append(f"Jump to [section{i}](#section-{i})\n")
 32        else:
 33            # Regular text
 34            lines.append(f"This is paragraph {i} with some text.\n")
 35
 36        # Add occasional code blocks (using ~~~ to avoid markdown parsing issues)
 37        if i % 20 == 0:
 38            lines.append("~~~python\n")
 39            lines.append(f"# [fake link](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/should_ignore_{i}.md)\n")
 40            lines.append("print('hello')\n")
 41            lines.append("~~~\n")
 42
 43    return "".join(lines)
 44
 45def benchmark(
 46    func: Callable[[str], List],
 47    content: str,
 48    iterations: int = 100
 49) -> Tuple[float, float, float]:
 50    """
 51    Benchmark a function
 52
 53    Returns:
 54        Tuple of (mean_time_ms, min_time_ms, max_time_ms)
 55    """
 56    times = []
 57
 58    # Warmup
 59    for _ in range(5):
 60        func(content)
 61
 62    # Actual benchmark
 63    for _ in range(iterations):
 64        start = time.perf_counter()
 65        func(content)
 66        end = time.perf_counter()
 67        times.append((end - start) * 1000)  # Convert to ms
 68
 69    return (
 70        statistics.mean(times),
 71        min(times),
 72        max(times)
 73    )
 74
 75def run_benchmarks():
 76    """Run benchmarks comparing all implementations"""
 77
 78    # Import implementations
 79    import re
 80
 81    # Pure Python implementation
 82    INLINE_LINK = re.compile(r'(?)
 83
 84    def parse_python(content: str) -> List:
 85        links = []
 86        in_code_block = False
 87        for line_num, line in enumerate(content.split('\n'), 1):
 88            if line.strip().startswith("```"):
 89                in_code_block = not in_code_block
 90                continue
 91            if in_code_block:
 92                continue
 93            for m in INLINE_LINK.finditer(line):
 94                links.append({"text": m.group(1), "target": m.group(2), "line": line_num})
 95        return links
 96
 97    # Try to import Rust implementation
 98    try:
 99        import markdown_parser_rs as rust_parser
100        has_rust = True
101    except ImportError:
102        has_rust = False
103        print("Rust module not available")
104
105    # Test sizes
106    sizes = [100, 500, 1000, 5000, 10000]
107
108    print("=" * 70)
109    print("Markdown Link Parser Benchmark")
110    print("=" * 70)
111    print()
112
113    results = []
114
115    for size in sizes:
116        content = generate_markdown(size)
117        content_kb = len(content.encode('utf-8')) / 1024
118
119        print(f"Test: {size} links (~{content_kb:.1f} KB)")
120        print("-" * 50)
121
122        # Python benchmark
123        py_mean, py_min, py_max = benchmark(parse_python, content)
124        print(f"  Python:  {py_mean:8.3f} ms (min: {py_min:.3f}, max: {py_max:.3f})")
125
126        # Rust benchmark
127        if has_rust:
128            rs_mean, rs_min, rs_max = benchmark(
129                rust_parser.parse_markdown_links,
130                content
131            )
132            speedup = py_mean / rs_mean
133            print(f"  Rust:    {rs_mean:8.3f} ms (min: {rs_min:.3f}, max: {rs_max:.3f})")
134            print(f"  Speedup: {speedup:.1f}x faster")
135
136        print()
137        results.append({
138            "size": size,
139            "python_ms": py_mean,
140            "rust_ms": rs_mean if has_rust else None,
141            "speedup": speedup if has_rust else None
142        })
143
144    # Summary table
145    print("=" * 70)
146    print("Summary")
147    print("=" * 70)
148    print(f"{'Links':<10} {'Python (ms)':<15} {'Rust (ms)':<15} {'Speedup':<10}")
149    print("-" * 50)
150    for r in results:
151        rust_str = f"{r['rust_ms']:.3f}" if r['rust_ms'] else "N/A"
152        speedup_str = f"{r['speedup']:.1f}x" if r['speedup'] else "N/A"
153        print(f"{r['size']:<10} {r['python_ms']:<15.3f} {rust_str:<15} {speedup_str:<10}")
154
155if __name__ == "__main__":
156    run_benchmarks()

典型效能結果：

連結數	Python (ms)	Rust (ms)	加速比
100	0.45	0.03	15x
500	2.10	0.12	18x
1000	4.25	0.22	19x
5000	21.50	1.05	20x
10000	43.80	2.10	21x

注意：實際效能取決於硬體和內容複雜度。Rust 的優勢在大型檔案上更加明顯。

設計權衡

面向	Python	Cython	Rust (PyO3)
開發速度	快（數小時）	中（數天）	慢（數天至週）
執行速度	1x	2-10x	10-100x
記憶體安全	GC 管理	GC 管理	編譯時保證
學習曲線	低	中	高
除錯難度	低	中	高
部署複雜度	低	中	中
跨平台支援	優秀	需編譯	需編譯
生態系統	豐富	有限	豐富（Cargo）

選擇決策樹

1需要加速 Python 程式碼？
2├── 否 → 保持純 Python
3└── 是 → 效能需求多高？
4    ├── 2-5x 足夠 → 考慮 Cython
5    └── 需要 10x+ → 團隊有 Rust 經驗？
6        ├── 是 → 使用 PyO3
7        └── 否 → 效能瓶頸明確嗎？
8            ├── 是 → 值得學習 Rust
9            └── 否 → 先用 Cython，後續再評估

什麼時候該用 Rust？

適合使用：

需要極致效能（10x+ 加速）
CPU 密集的核心邏輯
需要處理大量資料
團隊有 Rust 經驗
需要記憶體安全保證
可利用 Rust 生態系統（如 regex, rayon）

不建議使用：

效能需求不高
快速原型開發
團隊不熟悉 Rust
專案生命週期短
I/O 密集型任務（瓶頸不在 CPU）

練習

練習 1：基礎練習 - 字串處理函式

用 PyO3 實作一個字串處理函式，將 Markdown 標題轉換為 slug：

1// 目標：將 "Hello World! 你好" 轉換為 "hello-world-你好"
2#[pyfunction]
3fn slugify(title: &str) -> String {
4    // 你的實作
5    todo!()
6}

提示：

轉換為小寫
移除特殊字元
用連字號替換空白

參考解答：

 1#[pyfunction]
 2fn slugify(title: &str) -> String {
 3    title
 4        .chars()
 5        .map(|c| {
 6            if c.is_alphanumeric() {
 7                c.to_lowercase().next().unwrap_or(c)
 8            } else if c.is_whitespace() {
 9                '-'
10            } else {
11                // Keep non-ASCII chars (like CJK)
12                if c.is_ascii() { '\0' } else { c }
13            }
14        })
15        .filter(|&c| c != '\0')
16        .collect::<String>()
17        // Clean up multiple consecutive dashes
18        .split('-')
19        .filter(|s| !s.is_empty())
20        .collect::<Vec<_>>()
21        .join("-")
22}

練習 2：進階練習 - 模式匹配

用 regex crate 實作一個函式，提取 Markdown 文件中的所有標題：

 1// 目標：提取 # 標題，## 標題，### 標題 等
 2#[pyclass]
 3struct Heading {
 4    #[pyo3(get)]
 5    level: usize,
 6    #[pyo3(get)]
 7    text: String,
 8    #[pyo3(get)]
 9    line: usize,
10}
11
12#[pyfunction]
13fn extract_headings(content: &str) -> Vec<Heading> {
14    // 你的實作
15    todo!()
16}

提示：

使用 ^#{1,6}\s+(.+)$ 正則表達式
記得處理 multiline 模式

參考解答：

 1use once_cell::sync::Lazy;
 2use regex::Regex;
 3
 4static HEADING_PATTERN: Lazy<Regex> = Lazy::new(|| {
 5    Regex::new(r"(?m)^(#{1,6})\s+(.+)$").unwrap()
 6});
 7
 8#[pyfunction]
 9fn extract_headings(content: &str) -> Vec<Heading> {
10    let mut headings = Vec::new();
11    let mut current_line = 1;
12    let mut last_end = 0;
13
14    for cap in HEADING_PATTERN.captures_iter(content) {
15        let match_start = cap.get(0).unwrap().start();
16
17        // Count newlines to determine line number
18        current_line += content[last_end..match_start]
19            .chars()
20            .filter(|&c| c == '\n')
21            .count();
22        last_end = match_start;
23
24        let level = cap[1].len();
25        let text = cap[2].trim().to_string();
26
27        headings.push(Heading {
28            level,
29            text,
30            line: current_line,
31        });
32    }
33
34    headings
35}

練習 3：挑戰題 - 串流解析

實作一個可處理大型檔案的串流解析器：

 1use std::io::{BufRead, BufReader};
 2use std::fs::File;
 3
 4#[pyclass]
 5struct StreamingParser {
 6    // 你的實作
 7}
 8
 9#[pymethods]
10impl StreamingParser {
11    #[new]
12    fn new(file_path: &str) -> PyResult<Self> {
13        // 開啟檔案
14        todo!()
15    }
16
17    /// 迭代器協議
18    fn __iter__(slf: PyRef<Self>) -> PyRef<Self> {
19        slf
20    }
21
22    fn __next__(&mut self) -> Option<PyMarkdownLink> {
23        // 讀取下一個連結
24        todo!()
25    }
26}

提示：

使用 BufReader 逐行讀取
維護狀態（行號、程式碼區塊）
實作 Python 迭代器協議

參考解答思路：

 1use pyo3::prelude::*;
 2use std::fs::File;
 3use std::io::{BufRead, BufReader};
 4
 5#[pyclass]
 6struct StreamingParser {
 7    reader: BufReader<File>,
 8    line_number: usize,
 9    in_code_block: bool,
10    // Buffer for pending links found on current line
11    pending_links: Vec<PyMarkdownLink>,
12}
13
14#[pymethods]
15impl StreamingParser {
16    #[new]
17    fn new(file_path: &str) -> PyResult<Self> {
18        let file = File::open(file_path)
19            .map_err(|e| PyErr::new::<pyo3::exceptions::PyIOError, _>(
20                format!("Cannot open file: {}", e)
21            ))?;
22
23        Ok(StreamingParser {
24            reader: BufReader::new(file),
25            line_number: 0,
26            in_code_block: false,
27            pending_links: Vec::new(),
28        })
29    }
30
31    fn __iter__(slf: PyRef<Self>) -> PyRef<Self> {
32        slf
33    }
34
35    fn __next__(mut slf: PyRefMut<Self>) -> Option<PyMarkdownLink> {
36        // Return pending links first
37        if let Some(link) = slf.pending_links.pop() {
38            return Some(link);
39        }
40
41        // Read and parse lines until we find links
42        let mut line = String::new();
43        loop {
44            line.clear();
45            match slf.reader.read_line(&mut line) {
46                Ok(0) => return None, // EOF
47                Ok(_) => {
48                    slf.line_number += 1;
49
50                    // Handle code blocks
51                    if line.trim_start().starts_with("```") {
52                        slf.in_code_block = !slf.in_code_block;
53                        continue;
54                    }
55
56                    if slf.in_code_block {
57                        continue;
58                    }
59
60                    // Parse links from this line
61                    let links = parse_line_links(&line, slf.line_number);
62                    if !links.is_empty() {
63                        slf.pending_links = links;
64                        return slf.pending_links.pop();
65                    }
66                }
67                Err(_) => return None,
68            }
69        }
70    }
71}
72
73fn parse_line_links(line: &str, line_number: usize) -> Vec<PyMarkdownLink> {
74    let mut links = Vec::new();
75    for cap in INLINE_LINK_PATTERN.captures_iter(line) {
76        links.push(PyMarkdownLink {
77            text: cap[1].to_string(),
78            target: cap[2].to_string(),
79            line: line_number,
80        });
81    }
82    links
83}

案例：Rust 正則表達式

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/hook_validator.py 的實際程式碼，展示如何用 Rust 的 regex crate 加速模式匹配。

先備知識

問題背景

現有設計

hook_validator.py 使用 Python 的 re 模組進行多種模式匹配驗證：

 1import re
 2from typing import List, Optional
 3from pathlib import Path
 4
 5class HookValidator:
 6    """Hook 合規性驗證器"""
 7
 8    # Pattern definitions for various validation checks
 9    HOOK_IO_PATTERNS = [
10        r"from\s+hook_io\s+import",
11        r"from\s+lib\.hook_io\s+import",
12    ]
13
14    HOOK_LOGGING_PATTERNS = [
15        r"from\s+hook_logging\s+import",
16        r"from\s+lib\.hook_logging\s+import",
17    ]
18
19    CONFIG_LOADER_PATTERNS = [
20        r"from\s+config_loader\s+import",
21        r"from\s+lib\.config_loader\s+import",
22    ]
23
24    GIT_UTILS_PATTERNS = [
25        r"from\s+git_utils\s+import",
26        r"from\s+lib\.git_utils\s+import",
27    ]
28
29    OUTPUT_PATTERNS = [
30        r"write_hook_output\s*\(",
31        r"create_pretooluse_output\s*\(",
32        r"create_posttooluse_output\s*\(",
33    ]
34
35    BAD_OUTPUT_PATTERNS = [
36        r'print\s*\(\s*json\.dumps\s*\(',
37        r'sys\.stdout\.write\s*\(\s*json\.dumps\s*\(',
38    ]
39
40    VALID_NAME_PATTERNS = [
41        r"^[a-z0-9](/python-advanced/06-rust-extensions/case-studies/rust-regex/[a-z0-9\-_]*[a-z0-9])?\.py$",
42    ]
43
44    def _has_import(self, content: str, patterns: List[str]) -> bool:
45        """Check if content matches any of the import patterns"""
46        return any(
47            re.search(pattern, content)
48            for pattern in patterns
49        )
50
51    def _matches_pattern(self, content: str, patterns: List[str]) -> bool:
52        """Check if content matches any pattern"""
53        return any(
54            re.search(pattern, content)
55            for pattern in patterns
56        )
57
58    def check_naming_convention(self, hook_path: Path) -> List[dict]:
59        """Validate file naming convention"""
60        filename = hook_path.name
61        valid_name = any(
62            re.match(pattern, filename)
63            for pattern in self.VALID_NAME_PATTERNS
64        )
65        # ... validation logic

這段程式碼展示了幾個核心問題：

重複編譯：每次呼叫 re.search() 或 re.match() 都可能重新編譯正則表達式
多模式匹配：需要遍歷多個模式逐一檢查
混合使用場景：部分用於 match（從頭匹配），部分用於 search（任意位置）

效能限制

Python re 模組的限制：

限制	說明	影響
回溯型引擎	NFA with backtracking	某些模式可能導致指數級時間複雜度
解釋器開銷	每次匹配都經過 Python 呼叫	大量匹配時累積顯著延遲
無硬體加速	純軟體實作	無法利用 SIMD 等現代 CPU 特性
GIL 限制	受 Global Interpreter Lock 影響	多執行緒場景效能受限

病態輸入示例

 1import re
 2import time
 3
 4# Pathological pattern: catastrophic backtracking
 5pattern = r"(a+)+b"
 6text = "a" * 25 + "c"  # No match, triggers backtracking
 7
 8start = time.time()
 9re.search(pattern, text)
10elapsed = time.time() - start
11print(f"Python re: {elapsed:.2f}s")  # May take several seconds!

進階解決方案

設計目標

用 Rust regex crate 取代 Python re
利用 Rust regex 的 DFA 引擎確保線性時間複雜度
使用 RegexSet 實現高效批次驗證
預編譯正則表達式，避免重複編譯開銷

實作步驟

步驟 1：建立專案結構

 1# Create new maturin project
 2maturin new hook_validator_rs
 3cd hook_validator_rs
 4
 5# Project structure
 6hook_validator_rs/
 7├── Cargo.toml
 8├── pyproject.toml
 9└── src/
10    └── lib.rs

編輯 Cargo.toml：

 1[package]
 2name = "hook_validator_rs"
 3version = "0.1.0"
 4edition = "2021"
 5
 6[lib]
 7name = "hook_validator_rs"
 8crate-type = ["cdylib"]
 9
10[dependencies]
11pyo3 = { version = "0.22", features = ["extension-module"] }
12regex = "1.10"
13once_cell = "1.19"

步驟 2：定義預編譯正則表達式

使用 once_cell::sync::Lazy 實現執行緒安全的延遲初始化：

 1use once_cell::sync::Lazy;
 2use regex::{Regex, RegexSet};
 3
 4// Pre-compiled individual patterns
 5static HOOK_IO_REGEX: Lazy<RegexSet> = Lazy::new(|| {
 6    RegexSet::new([
 7        r"from\s+hook_io\s+import",
 8        r"from\s+lib\.hook_io\s+import",
 9    ]).expect("Invalid regex pattern")
10});
11
12static HOOK_LOGGING_REGEX: Lazy<RegexSet> = Lazy::new(|| {
13    RegexSet::new([
14        r"from\s+hook_logging\s+import",
15        r"from\s+lib\.hook_logging\s+import",
16    ]).expect("Invalid regex pattern")
17});
18
19static CONFIG_LOADER_REGEX: Lazy<RegexSet> = Lazy::new(|| {
20    RegexSet::new([
21        r"from\s+config_loader\s+import",
22        r"from\s+lib\.config_loader\s+import",
23    ]).expect("Invalid regex pattern")
24});
25
26static GIT_UTILS_REGEX: Lazy<RegexSet> = Lazy::new(|| {
27    RegexSet::new([
28        r"from\s+git_utils\s+import",
29        r"from\s+lib\.git_utils\s+import",
30    ]).expect("Invalid regex pattern")
31});
32
33static OUTPUT_REGEX: Lazy<RegexSet> = Lazy::new(|| {
34    RegexSet::new([
35        r"write_hook_output\s*\(",
36        r"create_pretooluse_output\s*\(",
37        r"create_posttooluse_output\s*\(",
38    ]).expect("Invalid regex pattern")
39});
40
41static BAD_OUTPUT_REGEX: Lazy<RegexSet> = Lazy::new(|| {
42    RegexSet::new([
43        r"print\s*\(\s*json\.dumps\s*\(",
44        r"sys\.stdout\.write\s*\(\s*json\.dumps\s*\(",
45    ]).expect("Invalid regex pattern")
46});
47
48// For filename validation (anchored match)
49static VALID_NAME_REGEX: Lazy<Regex> = Lazy::new(|| {
50    Regex::new(r"^[a-z0-9](/python-advanced/06-rust-extensions/case-studies/rust-regex/[a-z0-9\-_]*[a-z0-9])?\.py$")
51        .expect("Invalid regex pattern")
52});

為什麼用 `once_cell::sync::Lazy`？

執行緒安全：Lazy 確保初始化只執行一次，即使多執行緒同時存取
延遲初始化：只在第一次使用時編譯正則表達式
零執行時開銷：初始化後的存取是零成本的

步驟 3：實作批次匹配邏輯

 1use pyo3::prelude::*;
 2use std::collections::HashMap;
 3
 4/// Result of validating import patterns in source code
 5#[pyclass]
 6#[derive(Clone)]
 7pub struct ImportCheckResult {
 8    #[pyo3(get)]
 9    pub has_hook_io: bool,
10    #[pyo3(get)]
11    pub has_hook_logging: bool,
12    #[pyo3(get)]
13    pub has_config_loader: bool,
14    #[pyo3(get)]
15    pub has_git_utils: bool,
16    #[pyo3(get)]
17    pub has_good_output: bool,
18    #[pyo3(get)]
19    pub has_bad_output: bool,
20}
21
22#[pymethods]
23impl ImportCheckResult {
24    fn __repr__(&self) -> String {
25        format!(
26            "ImportCheckResult(hook_io={}, logging={}, config={}, git={}, good_out={}, bad_out={})",
27            self.has_hook_io, self.has_hook_logging,
28            self.has_config_loader, self.has_git_utils,
29            self.has_good_output, self.has_bad_output
30        )
31    }
32}
33
34/// Check all import patterns in a single pass through the content
35#[pyfunction]
36pub fn check_imports(content: &str) -> ImportCheckResult {
37    ImportCheckResult {
38        has_hook_io: HOOK_IO_REGEX.is_match(content),
39        has_hook_logging: HOOK_LOGGING_REGEX.is_match(content),
40        has_config_loader: CONFIG_LOADER_REGEX.is_match(content),
41        has_git_utils: GIT_UTILS_REGEX.is_match(content),
42        has_good_output: OUTPUT_REGEX.is_match(content),
43        has_bad_output: BAD_OUTPUT_REGEX.is_match(content),
44    }
45}
46
47/// Validate filename against naming convention
48#[pyfunction]
49pub fn is_valid_hook_name(filename: &str) -> bool {
50    VALID_NAME_REGEX.is_match(filename)
51}
52
53/// Check which specific patterns matched (for detailed reporting)
54#[pyfunction]
55pub fn get_matched_patterns(content: &str, pattern_group: &str) -> Vec<usize> {
56    let regex_set = match pattern_group {
57        "hook_io" => &*HOOK_IO_REGEX,
58        "hook_logging" => &*HOOK_LOGGING_REGEX,
59        "config_loader" => &*CONFIG_LOADER_REGEX,
60        "git_utils" => &*GIT_UTILS_REGEX,
61        "output" => &*OUTPUT_REGEX,
62        "bad_output" => &*BAD_OUTPUT_REGEX,
63        _ => return vec![],
64    };
65
66    regex_set.matches(content).iter().collect()
67}

步驟 4：進階批次驗證 API

對於需要一次驗證大量檔案的場景，提供更高效的批次 API：

 1/// Batch validation result for multiple files
 2#[pyclass]
 3#[derive(Clone)]
 4pub struct BatchValidationResult {
 5    #[pyo3(get)]
 6    pub results: HashMap<String, ImportCheckResult>,
 7    #[pyo3(get)]
 8    pub valid_names: HashMap<String, bool>,
 9}
10
11#[pymethods]
12impl BatchValidationResult {
13    fn __repr__(&self) -> String {
14        format!("BatchValidationResult({} files)", self.results.len())
15    }
16
17    /// Get files that are missing hook_io import
18    fn files_missing_hook_io(&self) -> Vec<String> {
19        self.results
20            .iter()
21            .filter(|(_, r)| !r.has_hook_io)
22            .map(|(path, _)| path.clone())
23            .collect()
24    }
25
26    /// Get files with bad output patterns
27    fn files_with_bad_output(&self) -> Vec<String> {
28        self.results
29            .iter()
30            .filter(|(_, r)| r.has_bad_output)
31            .map(|(path, _)| path.clone())
32            .collect()
33    }
34}
35
36/// Validate multiple files in batch
37///
38/// This is more efficient than calling check_imports for each file
39/// because it can potentially parallelize the work.
40#[pyfunction]
41pub fn validate_batch(files: HashMap<String, String>) -> BatchValidationResult {
42    let results: HashMap<String, ImportCheckResult> = files
43        .iter()
44        .map(|(path, content)| (path.clone(), check_imports(content)))
45        .collect();
46
47    let valid_names: HashMap<String, bool> = files
48        .keys()
49        .map(|path| {
50            let filename = path.rsplit('/').next().unwrap_or(path);
51            (path.clone(), is_valid_hook_name(filename))
52        })
53        .collect();
54
55    BatchValidationResult { results, valid_names }
56}

步驟 5：PyO3 模組導出

 1/// Rust-powered hook validator with pre-compiled regex patterns
 2#[pymodule]
 3fn hook_validator_rs(m: &Bound<'_, PyModule>) -> PyResult<()> {
 4    m.add_function(wrap_pyfunction!(check_imports, m)?)?;
 5    m.add_function(wrap_pyfunction!(is_valid_hook_name, m)?)?;
 6    m.add_function(wrap_pyfunction!(get_matched_patterns, m)?)?;
 7    m.add_function(wrap_pyfunction!(validate_batch, m)?)?;
 8    m.add_class::<ImportCheckResult>()?;
 9    m.add_class::<BatchValidationResult>()?;
10    Ok(())
11}

步驟 6：Python 端整合

在 Python 端無縫整合 Rust 模組：

  1"""
  2Hook 合規性驗證工具（Rust 加速版）
  3
  4This module provides a drop-in replacement for the pure Python
  5hook_validator, using Rust regex crate for pattern matching.
  6"""
  7
  8from pathlib import Path
  9from typing import List, Optional
 10from dataclasses import dataclass, field
 11
 12# Try to import Rust extension, fall back to pure Python
 13try:
 14    import hook_validator_rs as _rs
 15    _USE_RUST = True
 16except ImportError:
 17    import re
 18    _USE_RUST = False
 19    print("Warning: Rust extension not available, using pure Python")
 20
 21@dataclass
 22class ValidationIssue:
 23    """Validation issue description"""
 24    level: str  # "error" | "warning" | "info"
 25    message: str
 26    line: Optional[int] = None
 27    suggestion: Optional[str] = None
 28
 29@dataclass
 30class ValidationResult:
 31    """Validation result for a single hook"""
 32    hook_path: str
 33    issues: List[ValidationIssue] = field(default_factory=list)
 34    is_compliant: bool = True
 35
 36    def __post_init__(self):
 37        self.is_compliant = not any(
 38            issue.level == "error" for issue in self.issues
 39        )
 40
 41class HookValidator:
 42    """Hook compliance validator with optional Rust acceleration"""
 43
 44    def __init__(self, project_root: Optional[str] = None):
 45        if project_root is None:
 46            import os
 47            project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
 48        self.project_root = Path(project_root)
 49
 50    def check_lib_imports(
 51        self,
 52        content: str,
 53        hook_path: Optional[Path] = None
 54    ) -> List[ValidationIssue]:
 55        """Check shared module imports using Rust regex"""
 56        issues = []
 57
 58        if _USE_RUST:
 59            # Use Rust-accelerated pattern matching
 60            result = _rs.check_imports(content)
 61
 62            if not result.has_hook_io:
 63                issues.append(ValidationIssue(
 64                    level="warning",
 65                    message="Missing hook_io import",
 66                    suggestion="Add: from hook_io import read_hook_input, write_hook_output"
 67                ))
 68
 69            if not result.has_hook_logging:
 70                issues.append(ValidationIssue(
 71                    level="info",
 72                    message="Missing hook_logging import (recommended)",
 73                    suggestion="Add: from hook_logging import setup_hook_logging"
 74                ))
 75
 76            if result.has_bad_output:
 77                issues.append(ValidationIssue(
 78                    level="warning",
 79                    message="Using print(json.dumps(...)) instead of write_hook_output()",
 80                    suggestion="Replace with: write_hook_output(output_dict)"
 81                ))
 82        else:
 83            # Fallback to pure Python regex
 84            issues.extend(self._check_imports_python(content, hook_path))
 85
 86        return issues
 87
 88    def check_naming_convention(self, hook_path: Path) -> List[ValidationIssue]:
 89        """Validate filename against naming convention"""
 90        issues = []
 91        filename = hook_path.name
 92
 93        if _USE_RUST:
 94            valid = _rs.is_valid_hook_name(filename)
 95        else:
 96            import re
 97            valid = bool(re.match(
 98                r"^[a-z0-9](/python-advanced/06-rust-extensions/case-studies/rust-regex/[a-z0-9\-_]*[a-z0-9])?\.py$",
 99                filename
100            ))
101
102        if not valid:
103            issues.append(ValidationIssue(
104                level="warning",
105                message=f"Invalid filename: {filename}",
106                suggestion="Use snake-case or kebab-case: check_permissions.py"
107            ))
108
109        return issues
110
111    def validate_hook(self, hook_path: str) -> ValidationResult:
112        """Validate a single hook file"""
113        path = self._resolve_path(hook_path)
114
115        if not path.exists():
116            return ValidationResult(
117                hook_path=str(path),
118                issues=[ValidationIssue(
119                    level="error",
120                    message=f"Hook file not found: {path}"
121                )]
122            )
123
124        content = path.read_text(encoding="utf-8")
125        issues = []
126        issues.extend(self.check_naming_convention(path))
127        issues.extend(self.check_lib_imports(content, path))
128
129        return ValidationResult(hook_path=str(path), issues=issues)
130
131    def validate_all_hooks(
132        self,
133        hooks_dir: Optional[str] = None
134    ) -> List[ValidationResult]:
135        """Validate all hooks with batch optimization"""
136        if hooks_dir is None:
137            hooks_dir = str(self.project_root / ".claude" / "hooks")
138
139        hooks_path = self._resolve_path(hooks_dir)
140        hook_files = list(hooks_path.glob("*.py"))
141
142        if _USE_RUST and len(hook_files) > 1:
143            # Use batch validation for multiple files
144            files_content = {
145                str(f): f.read_text(encoding="utf-8")
146                for f in hook_files
147                if not f.name.startswith("_")
148            }
149
150            batch_result = _rs.validate_batch(files_content)
151
152            results = []
153            for path, content in files_content.items():
154                import_result = batch_result.results[path]
155                valid_name = batch_result.valid_names[path]
156
157                issues = self._import_result_to_issues(import_result, valid_name)
158                results.append(ValidationResult(hook_path=path, issues=issues))
159
160            return results
161        else:
162            # Single file or no Rust: use standard validation
163            return [
164                self.validate_hook(str(f))
165                for f in hook_files
166                if not f.name.startswith("_")
167            ]
168
169    def _resolve_path(self, path: str) -> Path:
170        p = Path(path)
171        return p if p.is_absolute() else self.project_root / p
172
173    def _import_result_to_issues(
174        self,
175        result,
176        valid_name: bool
177    ) -> List[ValidationIssue]:
178        """Convert Rust ImportCheckResult to list of issues"""
179        issues = []
180
181        if not valid_name:
182            issues.append(ValidationIssue(
183                level="warning",
184                message="Invalid filename format"
185            ))
186
187        if not result.has_hook_io:
188            issues.append(ValidationIssue(
189                level="warning",
190                message="Missing hook_io import"
191            ))
192
193        if result.has_bad_output:
194            issues.append(ValidationIssue(
195                level="warning",
196                message="Using deprecated output pattern"
197            ))
198
199        return issues
200
201    def _check_imports_python(
202        self,
203        content: str,
204        hook_path: Optional[Path]
205    ) -> List[ValidationIssue]:
206        """Pure Python fallback for import checking"""
207        import re
208        issues = []
209
210        hook_io_patterns = [
211            r"from\s+hook_io\s+import",
212            r"from\s+lib\.hook_io\s+import",
213        ]
214
215        if not any(re.search(p, content) for p in hook_io_patterns):
216            issues.append(ValidationIssue(
217                level="warning",
218                message="Missing hook_io import"
219            ))
220
221        return issues

完整程式碼

以下是完整的 src/lib.rs：

  1//! Hook Validator - Rust regex acceleration for Python hook validation
  2//!
  3//! This module provides pre-compiled regex patterns for validating
  4//! Claude Code hook files, with significant performance improvements
  5//! over pure Python regex.
  6
  7use once_cell::sync::Lazy;
  8use pyo3::prelude::*;
  9use regex::{Regex, RegexSet};
 10use std::collections::HashMap;
 11
 12// ============================================================================
 13// Pre-compiled Regex Patterns
 14// ============================================================================
 15
 16/// Import patterns for hook_io module
 17static HOOK_IO_REGEX: Lazy<RegexSet> = Lazy::new(|| {
 18    RegexSet::new([
 19        r"from\s+hook_io\s+import",
 20        r"from\s+lib\.hook_io\s+import",
 21    ])
 22    .expect("Invalid HOOK_IO_REGEX pattern")
 23});
 24
 25/// Import patterns for hook_logging module
 26static HOOK_LOGGING_REGEX: Lazy<RegexSet> = Lazy::new(|| {
 27    RegexSet::new([
 28        r"from\s+hook_logging\s+import",
 29        r"from\s+lib\.hook_logging\s+import",
 30    ])
 31    .expect("Invalid HOOK_LOGGING_REGEX pattern")
 32});
 33
 34/// Import patterns for config_loader module
 35static CONFIG_LOADER_REGEX: Lazy<RegexSet> = Lazy::new(|| {
 36    RegexSet::new([
 37        r"from\s+config_loader\s+import",
 38        r"from\s+lib\.config_loader\s+import",
 39    ])
 40    .expect("Invalid CONFIG_LOADER_REGEX pattern")
 41});
 42
 43/// Import patterns for git_utils module
 44static GIT_UTILS_REGEX: Lazy<RegexSet> = Lazy::new(|| {
 45    RegexSet::new([
 46        r"from\s+git_utils\s+import",
 47        r"from\s+lib\.git_utils\s+import",
 48    ])
 49    .expect("Invalid GIT_UTILS_REGEX pattern")
 50});
 51
 52/// Recommended output function patterns
 53static OUTPUT_REGEX: Lazy<RegexSet> = Lazy::new(|| {
 54    RegexSet::new([
 55        r"write_hook_output\s*\(",
 56        r"create_pretooluse_output\s*\(",
 57        r"create_posttooluse_output\s*\(",
 58    ])
 59    .expect("Invalid OUTPUT_REGEX pattern")
 60});
 61
 62/// Deprecated output patterns (should be avoided)
 63static BAD_OUTPUT_REGEX: Lazy<RegexSet> = Lazy::new(|| {
 64    RegexSet::new([
 65        r"print\s*\(\s*json\.dumps\s*\(",
 66        r"sys\.stdout\.write\s*\(\s*json\.dumps\s*\(",
 67    ])
 68    .expect("Invalid BAD_OUTPUT_REGEX pattern")
 69});
 70
 71/// Valid hook filename pattern (anchored)
 72static VALID_NAME_REGEX: Lazy<Regex> = Lazy::new(|| {
 73    Regex::new(r"^[a-z0-9](/python-advanced/06-rust-extensions/case-studies/rust-regex/[a-z0-9\-_]*[a-z0-9])?\.py$")
 74        .expect("Invalid VALID_NAME_REGEX pattern")
 75});
 76
 77/// JSON output detection patterns
 78static JSON_OUTPUT_REGEX: Lazy<RegexSet> = Lazy::new(|| {
 79    RegexSet::new([
 80        r"json\.dumps",
 81        r"write_hook_output",
 82        r"create_.*_output",
 83    ])
 84    .expect("Invalid JSON_OUTPUT_REGEX pattern")
 85});
 86
 87// ============================================================================
 88// Result Types
 89// ============================================================================
 90
 91/// Result of checking import patterns in source code
 92#[pyclass]
 93#[derive(Clone, Debug)]
 94pub struct ImportCheckResult {
 95    #[pyo3(get)]
 96    pub has_hook_io: bool,
 97    #[pyo3(get)]
 98    pub has_hook_logging: bool,
 99    #[pyo3(get)]
100    pub has_config_loader: bool,
101    #[pyo3(get)]
102    pub has_git_utils: bool,
103    #[pyo3(get)]
104    pub has_good_output: bool,
105    #[pyo3(get)]
106    pub has_bad_output: bool,
107    #[pyo3(get)]
108    pub has_json_output: bool,
109}
110
111#[pymethods]
112impl ImportCheckResult {
113    fn __repr__(&self) -> String {
114        format!(
115            "ImportCheckResult(hook_io={}, logging={}, config={}, git={}, \
116             good_out={}, bad_out={}, json_out={})",
117            self.has_hook_io,
118            self.has_hook_logging,
119            self.has_config_loader,
120            self.has_git_utils,
121            self.has_good_output,
122            self.has_bad_output,
123            self.has_json_output
124        )
125    }
126
127    /// Check if the hook uses recommended output patterns
128    fn uses_recommended_output(&self) -> bool {
129        self.has_good_output && !self.has_bad_output
130    }
131
132    /// Check if the hook has all required imports
133    fn has_required_imports(&self) -> bool {
134        self.has_hook_io
135    }
136}
137
138/// Batch validation result for multiple files
139#[pyclass]
140#[derive(Clone, Debug)]
141pub struct BatchValidationResult {
142    #[pyo3(get)]
143    pub results: HashMap<String, ImportCheckResult>,
144    #[pyo3(get)]
145    pub valid_names: HashMap<String, bool>,
146}
147
148#[pymethods]
149impl BatchValidationResult {
150    fn __repr__(&self) -> String {
151        format!("BatchValidationResult({} files)", self.results.len())
152    }
153
154    /// Get list of files missing hook_io import
155    fn files_missing_hook_io(&self) -> Vec<String> {
156        self.results
157            .iter()
158            .filter(|(_, r)| !r.has_hook_io)
159            .map(|(path, _)| path.clone())
160            .collect()
161    }
162
163    /// Get list of files using bad output patterns
164    fn files_with_bad_output(&self) -> Vec<String> {
165        self.results
166            .iter()
167            .filter(|(_, r)| r.has_bad_output)
168            .map(|(path, _)| path.clone())
169            .collect()
170    }
171
172    /// Get list of files with invalid names
173    fn files_with_invalid_names(&self) -> Vec<String> {
174        self.valid_names
175            .iter()
176            .filter(|(_, valid)| !*valid)
177            .map(|(path, _)| path.clone())
178            .collect()
179    }
180
181    /// Get summary statistics
182    fn summary(&self) -> HashMap<String, usize> {
183        let mut stats = HashMap::new();
184        stats.insert("total".to_string(), self.results.len());
185        stats.insert(
186            "missing_hook_io".to_string(),
187            self.files_missing_hook_io().len(),
188        );
189        stats.insert(
190            "bad_output".to_string(),
191            self.files_with_bad_output().len(),
192        );
193        stats.insert(
194            "invalid_names".to_string(),
195            self.files_with_invalid_names().len(),
196        );
197        stats
198    }
199}
200
201// ============================================================================
202// Public API Functions
203// ============================================================================
204
205/// Check all import patterns in source code
206///
207/// This function performs all pattern checks in a single pass through
208/// the content, making it much more efficient than individual checks.
209///
210/// # Arguments
211/// * `content` - The source code content to check
212///
213/// # Returns
214/// * `ImportCheckResult` - Results of all pattern checks
215#[pyfunction]
216pub fn check_imports(content: &str) -> ImportCheckResult {
217    ImportCheckResult {
218        has_hook_io: HOOK_IO_REGEX.is_match(content),
219        has_hook_logging: HOOK_LOGGING_REGEX.is_match(content),
220        has_config_loader: CONFIG_LOADER_REGEX.is_match(content),
221        has_git_utils: GIT_UTILS_REGEX.is_match(content),
222        has_good_output: OUTPUT_REGEX.is_match(content),
223        has_bad_output: BAD_OUTPUT_REGEX.is_match(content),
224        has_json_output: JSON_OUTPUT_REGEX.is_match(content),
225    }
226}
227
228/// Validate filename against naming convention
229///
230/// Valid names must:
231/// - Start and end with lowercase alphanumeric
232/// - Contain only lowercase letters, numbers, hyphens, underscores
233/// - Have .py extension
234///
235/// # Arguments
236/// * `filename` - The filename to validate (just the name, not full path)
237///
238/// # Returns
239/// * `bool` - True if the filename is valid
240#[pyfunction]
241pub fn is_valid_hook_name(filename: &str) -> bool {
242    VALID_NAME_REGEX.is_match(filename)
243}
244
245/// Get indices of matched patterns in a pattern group
246///
247/// Useful for detailed reporting of which specific patterns matched.
248///
249/// # Arguments
250/// * `content` - The source code content to check
251/// * `pattern_group` - One of: "hook_io", "hook_logging", "config_loader",
252///                     "git_utils", "output", "bad_output", "json_output"
253///
254/// # Returns
255/// * `Vec` - Indices of patterns that matched
256#[pyfunction]
257pub fn get_matched_patterns(content: &str, pattern_group: &str) -> Vec<usize> {
258    let regex_set: &RegexSet = match pattern_group {
259        "hook_io" => &HOOK_IO_REGEX,
260        "hook_logging" => &HOOK_LOGGING_REGEX,
261        "config_loader" => &CONFIG_LOADER_REGEX,
262        "git_utils" => &GIT_UTILS_REGEX,
263        "output" => &OUTPUT_REGEX,
264        "bad_output" => &BAD_OUTPUT_REGEX,
265        "json_output" => &JSON_OUTPUT_REGEX,
266        _ => return vec![],
267    };
268
269    regex_set.matches(content).iter().collect()
270}
271
272/// Validate multiple files in a single batch operation
273///
274/// This is significantly more efficient than validating files one by one,
275/// especially when dealing with many files.
276///
277/// # Arguments
278/// * `files` - HashMap of file paths to their contents
279///
280/// # Returns
281/// * `BatchValidationResult` - Combined results for all files
282#[pyfunction]
283pub fn validate_batch(files: HashMap<String, String>) -> BatchValidationResult {
284    let results: HashMap<String, ImportCheckResult> = files
285        .iter()
286        .map(|(path, content)| (path.clone(), check_imports(content)))
287        .collect();
288
289    let valid_names: HashMap<String, bool> = files
290        .keys()
291        .map(|path| {
292            // Extract filename from path
293            let filename = path.rsplit('/').next().unwrap_or(path);
294            (path.clone(), is_valid_hook_name(filename))
295        })
296        .collect();
297
298    BatchValidationResult {
299        results,
300        valid_names,
301    }
302}
303
304/// Check if content contains specific import pattern (simple check)
305///
306/// # Arguments
307/// * `content` - The source code to check
308/// * `module_name` - The module to check for: "hook_io", "hook_logging", etc.
309///
310/// # Returns
311/// * `bool` - True if the import pattern is found
312#[pyfunction]
313pub fn has_import(content: &str, module_name: &str) -> bool {
314    match module_name {
315        "hook_io" => HOOK_IO_REGEX.is_match(content),
316        "hook_logging" => HOOK_LOGGING_REGEX.is_match(content),
317        "config_loader" => CONFIG_LOADER_REGEX.is_match(content),
318        "git_utils" => GIT_UTILS_REGEX.is_match(content),
319        _ => false,
320    }
321}
322
323// ============================================================================
324// Python Module Definition
325// ============================================================================
326
327/// Rust-accelerated hook validator with pre-compiled regex patterns
328///
329/// This module provides significant performance improvements over pure Python
330/// regex for validating Claude Code hook files. Key features:
331///
332/// - Pre-compiled regex patterns using once_cell
333/// - RegexSet for efficient multi-pattern matching
334/// - Batch validation API for multiple files
335/// - Guaranteed linear time complexity (DFA engine)
336#[pymodule]
337fn hook_validator_rs(m: &Bound<'_, PyModule>) -> PyResult<()> {
338    m.add_function(wrap_pyfunction!(check_imports, m)?)?;
339    m.add_function(wrap_pyfunction!(is_valid_hook_name, m)?)?;
340    m.add_function(wrap_pyfunction!(get_matched_patterns, m)?)?;
341    m.add_function(wrap_pyfunction!(validate_batch, m)?)?;
342    m.add_function(wrap_pyfunction!(has_import, m)?)?;
343    m.add_class::<ImportCheckResult>()?;
344    m.add_class::<BatchValidationResult>()?;
345    Ok(())
346}

建置與測試

 1# Build the extension
 2maturin develop --release
 3
 4# Run tests
 5python -c "
 6import hook_validator_rs as rs
 7
 8# Test basic import checking
 9content = '''
10from hook_io import read_hook_input, write_hook_output
11from hook_logging import setup_hook_logging
12'''
13
14result = rs.check_imports(content)
15print(f'Import check: {result}')
16print(f'Has hook_io: {result.has_hook_io}')
17print(f'Uses recommended output: {result.uses_recommended_output()}')
18
19# Test filename validation
20print(f'Valid name \"check-permissions.py\": {rs.is_valid_hook_name(\"check-permissions.py\")}')
21print(f'Valid name \"BadName.py\": {rs.is_valid_hook_name(\"BadName.py\")}')
22"

效能比較

  1"""Performance comparison: Python re vs Rust regex"""
  2
  3import time
  4import re
  5from typing import Callable
  6
  7def benchmark(name: str, func: Callable, iterations: int = 10000) -> float:
  8    """Run benchmark and return average time in microseconds"""
  9    start = time.perf_counter()
 10    for _ in range(iterations):
 11        func()
 12    elapsed = time.perf_counter() - start
 13    avg_us = (elapsed / iterations) * 1_000_000
 14    print(f"{name}: {avg_us:.2f} us/iteration ({iterations} iterations)")
 15    return avg_us
 16
 17# Test content (typical hook file)
 18TEST_CONTENT = '''
 19#!/usr/bin/env python3
 20"""Example hook for testing performance"""
 21
 22import json
 23import sys
 24from pathlib import Path
 25
 26from hook_io import read_hook_input, write_hook_output
 27from hook_logging import setup_hook_logging
 28from config_loader import load_config
 29
 30def main():
 31    logger = setup_hook_logging("example-hook")
 32    hook_input = read_hook_input()
 33
 34    # Process input
 35    result = {"decision": "approve"}
 36
 37    write_hook_output(result)
 38
 39if __name__ == "__main__":
 40    main()
 41'''
 42
 43# Python patterns
 44HOOK_IO_PATTERNS_PY = [
 45    r"from\s+hook_io\s+import",
 46    r"from\s+lib\.hook_io\s+import",
 47]
 48HOOK_LOGGING_PATTERNS_PY = [
 49    r"from\s+hook_logging\s+import",
 50    r"from\s+lib\.hook_logging\s+import",
 51]
 52
 53def python_check():
 54    """Pure Python regex check"""
 55    has_hook_io = any(
 56        re.search(p, TEST_CONTENT) for p in HOOK_IO_PATTERNS_PY
 57    )
 58    has_logging = any(
 59        re.search(p, TEST_CONTENT) for p in HOOK_LOGGING_PATTERNS_PY
 60    )
 61    return has_hook_io, has_logging
 62
 63def python_check_compiled():
 64    """Python regex with pre-compiled patterns"""
 65    global _compiled_hook_io, _compiled_logging
 66    has_hook_io = any(p.search(TEST_CONTENT) for p in _compiled_hook_io)
 67    has_logging = any(p.search(TEST_CONTENT) for p in _compiled_logging)
 68    return has_hook_io, has_logging
 69
 70# Pre-compile Python patterns
 71_compiled_hook_io = [re.compile(p) for p in HOOK_IO_PATTERNS_PY]
 72_compiled_logging = [re.compile(p) for p in HOOK_LOGGING_PATTERNS_PY]
 73
 74def rust_check():
 75    """Rust regex check"""
 76    import hook_validator_rs as rs
 77    result = rs.check_imports(TEST_CONTENT)
 78    return result.has_hook_io, result.has_hook_logging
 79
 80if __name__ == "__main__":
 81    print("=" * 60)
 82    print("Performance Comparison: Python re vs Rust regex")
 83    print("=" * 60)
 84    print(f"Content size: {len(TEST_CONTENT)} bytes\n")
 85
 86    # Warm up
 87    python_check()
 88    python_check_compiled()
 89    rust_check()
 90
 91    # Benchmark
 92    py_time = benchmark("Python re (uncompiled)", python_check)
 93    py_compiled_time = benchmark("Python re (compiled)", python_check_compiled)
 94    rust_time = benchmark("Rust regex", rust_check)
 95
 96    print("\n" + "=" * 60)
 97    print("Results Summary")
 98    print("=" * 60)
 99    print(f"Python uncompiled: {py_time:.2f} us")
100    print(f"Python compiled:   {py_compiled_time:.2f} us")
101    print(f"Rust regex:        {rust_time:.2f} us")
102    print(f"\nSpeedup vs uncompiled: {py_time / rust_time:.1f}x")
103    print(f"Speedup vs compiled:   {py_compiled_time / rust_time:.1f}x")

典型結果：

 1============================================================
 2Performance Comparison: Python re vs Rust regex
 3============================================================
 4Content size: 512 bytes
 5
 6Python re (uncompiled): 12.45 us/iteration (10000 iterations)
 7Python re (compiled):    4.32 us/iteration (10000 iterations)
 8Rust regex:              0.89 us/iteration (10000 iterations)
 9
10============================================================
11Results Summary
12============================================================
13Python uncompiled: 12.45 us
14Python compiled:    4.32 us
15Rust regex:         0.89 us
16
17Speedup vs uncompiled: 14.0x
18Speedup vs compiled:   4.9x

病態輸入效能比較

 1"""Pathological input benchmark - demonstrating DFA vs backtracking"""
 2
 3import time
 4import re
 5
 6def test_catastrophic_backtracking():
 7    """
 8    Test pattern that causes catastrophic backtracking in NFA engines
 9
10    Pattern: (a+)+b
11    Input: "aaa...a" (no 'b' at end)
12
13    Python re: O(2^n) time complexity
14    Rust regex: O(n) time complexity (DFA engine)
15    """
16    pattern = r"(a+)+b"
17
18    print("Catastrophic Backtracking Test")
19    print("Pattern: (a+)+b")
20    print("-" * 50)
21
22    for n in [15, 20, 22, 24, 25]:
23        text = "a" * n + "c"  # No match - triggers backtracking
24
25        # Python test
26        start = time.perf_counter()
27        try:
28            re.search(pattern, text, timeout=5)
29        except TimeoutError:
30            py_time = ">5s (timeout)"
31        else:
32            py_time = f"{(time.perf_counter() - start)*1000:.2f}ms"
33
34        # Note: Rust regex doesn't support backreferences,
35        # so (a+)+b is rewritten as a+b internally
36        # This demonstrates why Rust regex is safe from this attack
37
38        print(f"n={n:2d}: Python={py_time}")
39
40def test_regex_dos():
41    """
42    Test ReDoS (Regular Expression Denial of Service) patterns
43    """
44    # Common ReDoS patterns
45    redos_patterns = [
46        (r"(a+)+$", "a" * 20 + "!"),          # Nested quantifiers
47        (r"(a|aa)+$", "a" * 20 + "!"),        # Overlapping alternatives
48        (r"(.*a){10}$", "a" * 10 + "!"),      # Repeated wildcards
49    ]
50
51    print("\nReDoS Pattern Tests")
52    print("-" * 50)
53
54    for pattern, text in redos_patterns:
55        start = time.perf_counter()
56        re.search(pattern, text)
57        elapsed = time.perf_counter() - start
58        print(f"Pattern: {pattern:20s} Time: {elapsed*1000:.2f}ms")
59
60if __name__ == "__main__":
61    test_catastrophic_backtracking()
62    test_regex_dos()
63
64    print("\n" + "=" * 50)
65    print("Note: Rust regex crate uses DFA/hybrid engine")
66    print("that guarantees O(n) time complexity for all inputs.")
67    print("It does NOT support backreferences, which prevents")
68    print("catastrophic backtracking by design.")

設計權衡

面向	Python re	Rust regex
引擎類型	NFA with backtracking	DFA/混合引擎
時間複雜度	最壞 O(2^n)	保證 O(n)
功能完整性	完整（lookahead、backreference）	部分限制（無 backreference）
整合難度	無（內建）	需要 FFI（PyO3 + Maturin）
除錯便利	Python 原生	需要 Rust 工具鏈
記憶體安全	GC 管理	編譯時保證
多執行緒	受 GIL 限制	完全平行化
SIMD 加速	無	自動啟用

Rust regex 不支援的功能

 1// These patterns will fail to compile in Rust regex:
 2
 3// 1. Backreferences
 4// r"(\w+)\s+\1"  // ERROR: backreference not supported
 5
 6// 2. Lookahead/Lookbehind
 7// r"(?=foo)"    // ERROR: lookahead not supported
 8// r"(?<=foo)"   // ERROR: lookbehind not supported
 9
10// 3. Atomic groups
11// r"(?>foo)"    // ERROR: atomic groups not supported
12
13// Workaround: Use regex-fancy crate for these features
14// (with performance trade-offs)

什麼時候該用 Rust regex？

適合使用

大量文字需要驗證：日誌分析、程式碼審查、批次處理
正則表達式可能有病態輸入：用戶提供的輸入、不可信來源
需要保證線性時間：安全性要求、SLA 保證
高併發場景：多執行緒處理、Web 服務
效能關鍵路徑：CI/CD pipeline、即時驗證

不建議使用

需要 lookahead/lookbehind：複雜的文字邊界檢查
需要 backreference：重複單詞檢測、HTML 標籤匹配
驗證次數很少：一次性腳本、開發階段
模式簡單：固定字串、簡單前綴/後綴檢查
團隊不熟悉 Rust：維護成本可能超過效能收益

練習

1. 基礎練習：Email 驗證

用 Rust regex 實作 email 地址驗證：

 1// Exercise: Implement email validation
 2use once_cell::sync::Lazy;
 3use regex::Regex;
 4use pyo3::prelude::*;
 5
 6static EMAIL_REGEX: Lazy<Regex> = Lazy::new(|| {
 7    // TODO: Implement email pattern
 8    // Requirements:
 9    // - Local part: alphanumeric + dots + underscores + hyphens
10    // - @ symbol
11    // - Domain: alphanumeric + dots + hyphens
12    // - TLD: 2-6 alphabetic characters
13    Regex::new(r"TODO").expect("Invalid email regex")
14});
15
16#[pyfunction]
17pub fn is_valid_email(email: &str) -> bool {
18    EMAIL_REGEX.is_match(email)
19}
20
21// Test cases:
22// is_valid_email("user@example.com") -> true
23// is_valid_email("user.name+tag@example.co.uk") -> true
24// is_valid_email("invalid@") -> false
25// is_valid_email("@example.com") -> false

2. 進階練習：RegexSet 批次匹配

實作一個程式語言檢測器，判斷程式碼片段是哪種語言：

 1// Exercise: Language detection using RegexSet
 2use once_cell::sync::Lazy;
 3use regex::RegexSet;
 4use pyo3::prelude::*;
 5use std::collections::HashMap;
 6
 7static LANGUAGE_PATTERNS: Lazy<RegexSet> = Lazy::new(|| {
 8    RegexSet::new([
 9        // TODO: Add patterns for different languages
10        // 0: Python (def, import, from ... import)
11        // 1: JavaScript (const, let, =>)
12        // 2: Rust (fn, let mut, impl)
13        // 3: Go (func, package, import)
14    ]).expect("Invalid language patterns")
15});
16
17static LANGUAGE_NAMES: [&str; 4] = ["Python", "JavaScript", "Rust", "Go"];
18
19#[pyfunction]
20pub fn detect_languages(code: &str) -> Vec<String> {
21    // TODO: Return list of detected languages
22    // Hint: Use LANGUAGE_PATTERNS.matches(code)
23    vec![]
24}
25
26// Test case:
27// detect_languages("def hello():\n    print('Hi')") -> ["Python"]
28// detect_languages("const x = () => {}") -> ["JavaScript"]

3. 挑戰題：病態輸入防護

設計一個安全的正則表達式驗證器，拒絕可能導致 ReDoS 的模式：

 1// Challenge: ReDoS-safe regex validator
 2use pyo3::prelude::*;
 3
 4/// Validate that a regex pattern is safe from ReDoS attacks
 5///
 6/// Unsafe patterns to detect:
 7/// 1. Nested quantifiers: (a+)+
 8/// 2. Overlapping alternatives: (a|a)+
 9/// 3. Long quantified groups with wildcards: (.*)+
10#[pyfunction]
11pub fn is_safe_pattern(pattern: &str) -> PyResult<bool> {
12    // Strategy 1: Try to compile with Rust regex
13    // Rust regex rejects inherently unsafe patterns
14    match regex::Regex::new(pattern) {
15        Ok(_) => Ok(true),
16        Err(e) => {
17            // Check if error is due to unsupported features
18            // vs actual syntax errors
19            let error_msg = e.to_string();
20            if error_msg.contains("backreference")
21                || error_msg.contains("look") {
22                // Potentially unsafe pattern
23                Ok(false)
24            } else {
25                // Syntax error
26                Err(pyo3::exceptions::PyValueError::new_err(error_msg))
27            }
28        }
29    }
30}
31
32/// Benchmark a pattern to detect slow execution
33#[pyfunction]
34pub fn benchmark_pattern(
35    pattern: &str,
36    test_input: &str,
37    max_ms: u64
38) -> PyResult<bool> {
39    // TODO: Implement timeout-based safety check
40    // 1. Compile the pattern
41    // 2. Run match with timeout
42    // 3. Return false if exceeds max_ms
43    Ok(true)
44}

案例研究 on Tarragon

案例：PyO3 文字解析

先備知識

問題背景

現有設計

為什麼選擇 Rust？

進階解決方案

設計目標

實作步驟

步驟 1：建立 Rust 專案結構

步驟 2：實作 Rust 解析函式

步驟 3：用 PyO3 導出 Python 介面

步驟 4：建置與測試

完整程式碼

Python 整合範例

效能比較

設計權衡

選擇決策樹

什麼時候該用 Rust？

練習

練習 1：基礎練習 - 字串處理函式

練習 2：進階練習 - 模式匹配

練習 3：挑戰題 - 串流解析

延伸閱讀

案例：Rust 正則表達式

先備知識

問題背景

現有設計

效能限制

病態輸入示例

進階解決方案

設計目標

實作步驟

步驟 1：建立專案結構

步驟 2：定義預編譯正則表達式

為什麼用 once_cell::sync::Lazy？

步驟 3：實作批次匹配邏輯

步驟 4：進階批次驗證 API

步驟 5：PyO3 模組導出

步驟 6：Python 端整合

完整程式碼

建置與測試

效能比較

病態輸入效能比較

設計權衡

Rust regex 不支援的功能

什麼時候該用 Rust regex？

適合使用

不建議使用

練習

1. 基礎練習：Email 驗證

2. 進階練習：RegexSet 批次匹配

3. 挑戰題：病態輸入防護

延伸閱讀

為什麼用 `once_cell::sync::Lazy`？