案例研究 on Tarragon

案例：Cython 加速 Markdown 解析

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

本案例基於 .claude/lib/markdown_link_checker.py 的實際程式碼，展示如何用 Cython 加速文字解析。

先備知識

問題背景

現有設計

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/05-c-extensions/case-studies/cython-markdown/target) 格式，排除圖片 ![alt](/python-advanced/05-c-extensions/case-studies/cython-markdown/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/05-c-extensions/case-studies/cython-markdown/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 的限制：

正則表達式呼叫開銷：每次 finditer() 都有 Python 層級的迭代器開銷
迴圈效率不如 C：Python 的 for 迴圈涉及迭代器協議和物件建立
字串處理有額外開銷：split()、strip()、startswith() 都會建立新物件
字典存取開銷：reference_defs[ref_name] 涉及雜湊計算和物件比較

當處理大量 Markdown 文件（例如整個文件專案）時，這些開銷會累積成可觀的效能損失。

進階解決方案

優化目標

保持相同的 API：不改變 parse_markdown_links() 的輸入輸出格式
顯著提升解析速度：目標 2-5x 加速
容易整合到現有專案：編譯後可直接替換原模組

實作步驟

步驟 1：建立 .pyx 檔案

首先，建立基本的 Cython 檔案結構：

 1# markdown_parser.pyx
 2"""
 3Cython accelerated Markdown link parser.
 4
 5This module provides fast parsing of Markdown links,
 6compatible with the original Python implementation.
 7"""
 8
 9import re
10from typing import List, Dict
11
12# Compile regex patterns at module level for reuse
13cdef object INLINE_LINK_PATTERN = re.compile(
14    r'(?
15)
16
17cdef object REFERENCE_DEF_PATTERN = re.compile(
18    r'^\s*\[([^\]]+)\]:\s*(.+)$',
19    re.MULTILINE
20)
21
22cdef object REFERENCE_USE_PATTERN = re.compile(
23    r'\[([^\]]+)\]\[([^\]]+)\]'
24)

重點說明：

使用 cdef object 宣告正則表達式物件，讓 Cython 知道這些是 Python 物件
將正則表達式編譯放在模組層級，避免重複編譯
保留 docstring 和 type hints 以維護可讀性

步驟 2：添加型別宣告

為關鍵變數添加 C 型別宣告：

 1# markdown_parser.pyx (continued)
 2
 3cdef class LinkInfo:
 4    """
 5    C-level struct to hold link information.
 6    Faster than Python dict for internal operations.
 7    """
 8    cdef public str text
 9    cdef public str target
10    cdef public int line
11
12    def __init__(self, str text, str target, int line):
13        self.text = text
14        self.target = target
15        self.line = line
16
17    def to_dict(self) -> dict:
18        """Convert to dictionary for API compatibility."""
19        return {
20            "text": self.text,
21            "target": self.target,
22            "line": self.line
23        }
24
25cdef bint is_code_fence(str line):
26    """
27    Check if line is a code fence marker.
28
29    cdef function: only callable from Cython, fastest.
30    """
31    cdef str stripped = line.strip()
32    return stripped.startswith("```") or stripped.startswith("~~~")

重點說明：

cdef class LinkInfo：使用 Cython 的擴展類別，內部存取比 Python dict 快
cdef public：讓屬性可以從 Python 存取，同時保持 C 層級效率
cdef bint：使用 C 的布林型別（0 或 1），比 Python 的 bool 快
cdef 函式：只能從 Cython 呼叫，沒有 Python 呼叫開銷

步驟 3：優化迴圈

使用 Cython 優化主要的解析迴圈：

 1# markdown_parser.pyx (continued)
 2
 3cdef list _parse_inline_links(list lines, dict reference_defs):
 4    """
 5    Parse inline and reference links from lines.
 6
 7    Internal function with optimized loop.
 8    """
 9    cdef:
10        list links = []
11        int line_num
12        int total_lines = len(lines)
13        bint in_code_block = False
14        str line
15        str ref_name
16        object match
17
18    for line_num in range(total_lines):
19        line = lines[line_num]
20
21        # Check code fence
22        if is_code_fence(line):
23            in_code_block = not in_code_block
24            continue
25
26        if in_code_block:
27            continue
28
29        # Parse inline links [text](/python-advanced/05-c-extensions/case-studies/cython-markdown/target)
30        for match in INLINE_LINK_PATTERN.finditer(line):
31            links.append(LinkInfo(
32                match.group(1),
33                match.group(2),
34                line_num + 1  # 1-indexed
35            ))
36
37        # Parse reference links [text][ref]
38        for match in REFERENCE_USE_PATTERN.finditer(line):
39            ref_name = match.group(2).lower()
40            if ref_name in reference_defs:
41                links.append(LinkInfo(
42                    match.group(1),
43                    reference_defs[ref_name],
44                    line_num + 1
45                ))
46
47    return links
48
49cdef dict _collect_reference_defs(str content):
50    """
51    Collect reference link definitions from content.
52
53    Returns dict mapping ref_name -> target.
54    """
55    cdef:
56        dict reference_defs = {}
57        object match
58        str ref_name
59        str ref_target
60
61    for match in REFERENCE_DEF_PATTERN.finditer(content):
62        ref_name = match.group(1).lower()
63        ref_target = match.group(2).strip()
64        reference_defs[ref_name] = ref_target
65
66    return reference_defs

重點說明：

cdef list、cdef dict：明確宣告容器型別，減少型別檢查開銷
cdef int line_num：使用 C 整數進行迴圈計數
cdef bint in_code_block：使用 C 布林型別追蹤狀態
將功能分解成多個 cdef 函式，每個函式專注單一職責

步驟 4：建立公開 API

使用 cpdef 或 def 建立可從 Python 呼叫的公開介面：

 1# markdown_parser.pyx (continued)
 2
 3cpdef list parse_markdown_links(str content):
 4    """
 5    Parse all links from Markdown content.
 6
 7    This is the main public API, compatible with the original
 8    Python implementation.
 9
10    Args:
11        content: Markdown content string
12
13    Returns:
14        List of dicts with 'text', 'target', 'line' keys
15    """
16    cdef:
17        list lines
18        dict reference_defs
19        list link_infos
20        list result
21        LinkInfo info
22
23    # Split content into lines
24    lines = content.split('\n')
25
26    # Collect reference definitions
27    reference_defs = _collect_reference_defs(content)
28
29    # Parse all links
30    link_infos = _parse_inline_links(lines, reference_defs)
31
32    # Convert to dict format for API compatibility
33    result = [info.to_dict() for info in link_infos]
34
35    return result
36
37def parse_markdown_links_py(content: str) -> List[Dict]:
38    """
39    Python-compatible wrapper with type hints.
40
41    Identical to parse_markdown_links but with explicit
42    Python type annotations for better IDE support.
43    """
44    return parse_markdown_links(content)

重點說明：

cpdef：同時產生 Python 和 C 版本，從 Python 呼叫時用 Python 版本，從 Cython 呼叫時用 C 版本
保持 API 相容性：回傳格式與原始 Python 版本完全相同
提供 _py 版本：帶有完整型別提示，改善 IDE 支援

步驟 5：建立 setup.py

 1# setup.py
 2"""
 3Build script for Cython markdown parser.
 4
 5Usage:
 6    python setup.py build_ext --inplace
 7
 8Or for development with automatic rebuild:
 9    pip install -e .
10"""
11
12from setuptools import setup, Extension
13from Cython.Build import cythonize
14
15extensions = [
16    Extension(
17        "markdown_parser",
18        sources=["markdown_parser.pyx"],
19        # Optional: add compiler directives for optimization
20        # extra_compile_args=["-O3"],
21    )
22]
23
24setup(
25    name="markdown_parser",
26    version="0.1.0",
27    description="Cython accelerated Markdown link parser",
28    ext_modules=cythonize(
29        extensions,
30        compiler_directives={
31            "language_level": "3",      # Python 3 syntax
32            "boundscheck": False,       # Disable bounds checking
33            "wraparound": False,        # Disable negative indexing
34            "cdivision": True,          # Use C division semantics
35        },
36        annotate=True,  # Generate HTML annotation file
37    ),
38    zip_safe=False,
39)

編譯指令說明：

指令	說明	效能影響
`language_level=3`	使用 Python 3 語法	無
`boundscheck=False`	停用陣列邊界檢查	加速 5-10%
`wraparound=False`	停用負數索引支援	加速 2-5%
`cdivision=True`	使用 C 的除法（不檢查除以零）	加速除法運算
`annotate=True`	產生 HTML 註解報告	僅開發時使用

完整程式碼

將以上所有部分整合成完整的 .pyx 檔案：

  1# markdown_parser.pyx
  2"""
  3Cython accelerated Markdown link parser.
  4
  5This module provides fast parsing of Markdown links,
  6compatible with the original Python implementation.
  7
  8Build:
  9    python setup.py build_ext --inplace
 10
 11Usage:
 12    from markdown_parser import parse_markdown_links
 13    links = parse_markdown_links(markdown_content)
 14"""
 15
 16import re
 17from typing import List, Dict
 18
 19# ============================================================
 20# Compiled regex patterns (module level for reuse)
 21# ============================================================
 22
 23cdef object INLINE_LINK_PATTERN = re.compile(
 24    r'(?
 25)
 26
 27cdef object REFERENCE_DEF_PATTERN = re.compile(
 28    r'^\s*\[([^\]]+)\]:\s*(.+)$',
 29    re.MULTILINE
 30)
 31
 32cdef object REFERENCE_USE_PATTERN = re.compile(
 33    r'\[([^\]]+)\]\[([^\]]+)\]'
 34)
 35
 36# ============================================================
 37# C-level data structures
 38# ============================================================
 39
 40cdef class LinkInfo:
 41    """
 42    C-level struct to hold link information.
 43    Faster than Python dict for internal operations.
 44    """
 45    cdef public str text
 46    cdef public str target
 47    cdef public int line
 48
 49    def __init__(self, str text, str target, int line):
 50        self.text = text
 51        self.target = target
 52        self.line = line
 53
 54    def to_dict(self) -> dict:
 55        """Convert to dictionary for API compatibility."""
 56        return {
 57            "text": self.text,
 58            "target": self.target,
 59            "line": self.line
 60        }
 61
 62    def __repr__(self):
 63        return f"LinkInfo(text={self.text!r}, target={self.target!r}, line={self.line})"
 64
 65# ============================================================
 66# Internal helper functions (cdef = C-only, fastest)
 67# ============================================================
 68
 69cdef bint is_code_fence(str line):
 70    """
 71    Check if line is a code fence marker.
 72    """
 73    cdef str stripped = line.strip()
 74    return stripped.startswith("```") or stripped.startswith("~~~")
 75
 76cdef dict _collect_reference_defs(str content):
 77    """
 78    Collect reference link definitions from content.
 79    """
 80    cdef:
 81        dict reference_defs = {}
 82        object match
 83        str ref_name
 84        str ref_target
 85
 86    for match in REFERENCE_DEF_PATTERN.finditer(content):
 87        ref_name = match.group(1).lower()
 88        ref_target = match.group(2).strip()
 89        reference_defs[ref_name] = ref_target
 90
 91    return reference_defs
 92
 93cdef list _parse_inline_links(list lines, dict reference_defs):
 94    """
 95    Parse inline and reference links from lines.
 96    """
 97    cdef:
 98        list links = []
 99        int line_num
100        int total_lines = len(lines)
101        bint in_code_block = False
102        str line
103        str ref_name
104        object match
105
106    for line_num in range(total_lines):
107        line = lines[line_num]
108
109        # Check code fence
110        if is_code_fence(line):
111            in_code_block = not in_code_block
112            continue
113
114        if in_code_block:
115            continue
116
117        # Parse inline links [text](/python-advanced/05-c-extensions/case-studies/cython-markdown/target)
118        for match in INLINE_LINK_PATTERN.finditer(line):
119            links.append(LinkInfo(
120                match.group(1),
121                match.group(2),
122                line_num + 1
123            ))
124
125        # Parse reference links [text][ref]
126        for match in REFERENCE_USE_PATTERN.finditer(line):
127            ref_name = match.group(2).lower()
128            if ref_name in reference_defs:
129                links.append(LinkInfo(
130                    match.group(1),
131                    reference_defs[ref_name],
132                    line_num + 1
133                ))
134
135    return links
136
137# ============================================================
138# Public API (cpdef = callable from both Python and Cython)
139# ============================================================
140
141cpdef list parse_markdown_links(str content):
142    """
143    Parse all links from Markdown content.
144
145    Args:
146        content: Markdown content string
147
148    Returns:
149        List of dicts with 'text', 'target', 'line' keys
150
151    Example:
152        >>> content = "[Click here](https://example.com)"
153        >>> links = parse_markdown_links(content)
154        >>> links[0]['target']
155        'https://example.com'
156    """
157    cdef:
158        list lines
159        dict reference_defs
160        list link_infos
161        list result
162        LinkInfo info
163
164    lines = content.split('\n')
165    reference_defs = _collect_reference_defs(content)
166    link_infos = _parse_inline_links(lines, reference_defs)
167    result = [info.to_dict() for info in link_infos]
168
169    return result
170
171# Python-compatible wrapper with full type hints
172def parse_markdown_links_py(content: str) -> List[Dict]:
173    """
174    Python-compatible wrapper with type hints.
175
176    Identical to parse_markdown_links but with explicit
177    Python type annotations for better IDE support.
178    """
179    return parse_markdown_links(content)
180
181# ============================================================
182# Optional: Expose LinkInfo class for advanced usage
183# ============================================================
184
185def parse_markdown_links_fast(str content) -> list:
186    """
187    Parse links and return LinkInfo objects directly.
188
189    Faster than parse_markdown_links() as it skips
190    the dict conversion step.
191
192    Returns:
193        List of LinkInfo objects
194    """
195    cdef:
196        list lines
197        dict reference_defs
198
199    lines = content.split('\n')
200    reference_defs = _collect_reference_defs(content)
201    return _parse_inline_links(lines, reference_defs)

效能比較

建立效能測試腳本來比較純 Python 和 Cython 版本：

  1# benchmark.py
  2"""
  3Performance comparison between Python and Cython implementations.
  4
  5Usage:
  6    # First, build the Cython module
  7    python setup.py build_ext --inplace
  8
  9    # Then run benchmark
 10    python benchmark.py
 11"""
 12
 13import time
 14import statistics
 15from typing import Callable, List
 16
 17# Pure Python implementation (inline for comparison)
 18import re
 19
 20class PythonMarkdownParser:
 21    """Original pure Python implementation."""
 22
 23    INLINE_LINK_PATTERN = re.compile(r'(?)
 24    REFERENCE_DEF_PATTERN = re.compile(r'^\s*\[([^\]]+)\]:\s*(.+)$', re.MULTILINE)
 25    REFERENCE_USE_PATTERN = re.compile(r'\[([^\]]+)\]\[([^\]]+)\]')
 26
 27    def parse_markdown_links(self, content: str) -> list:
 28        links = []
 29        lines = content.split('\n')
 30
 31        reference_defs = {}
 32        for match in self.REFERENCE_DEF_PATTERN.finditer(content):
 33            ref_name = match.group(1).lower()
 34            ref_target = match.group(2).strip()
 35            reference_defs[ref_name] = ref_target
 36
 37        in_code_block = False
 38
 39        for line_num, line in enumerate(lines, start=1):
 40            if line.strip().startswith("```"):
 41                in_code_block = not in_code_block
 42                continue
 43
 44            if in_code_block:
 45                continue
 46
 47            for match in self.INLINE_LINK_PATTERN.finditer(line):
 48                links.append({
 49                    "text": match.group(1),
 50                    "target": match.group(2),
 51                    "line": line_num
 52                })
 53
 54            for match in self.REFERENCE_USE_PATTERN.finditer(line):
 55                ref_name = match.group(2).lower()
 56                if ref_name in reference_defs:
 57                    links.append({
 58                        "text": match.group(1),
 59                        "target": reference_defs[ref_name],
 60                        "line": line_num
 61                    })
 62
 63        return links
 64
 65def generate_test_content(num_lines: int, links_per_100_lines: int = 10) -> str:
 66    """Generate test Markdown content with specified characteristics."""
 67    lines = []
 68    for i in range(num_lines):
 69        if i % (100 // links_per_100_lines) == 0:
 70            # Add an inline link
 71            lines.append(f"Check out [Link {i}](https://example.com/page{i}) for details.")
 72        elif i % 50 == 0:
 73            # Add a code block
 74            lines.append("```python")
 75            lines.append(f"# This is code, links here [should](/python-advanced/05-c-extensions/case-studies/cython-markdown/be/ignored)")
 76            lines.append("```")
 77        else:
 78            # Regular text
 79            lines.append(f"This is line {i} with some regular text content.")
 80
 81    return '\n'.join(lines)
 82
 83def benchmark(func: Callable, content: str, iterations: int = 100) -> dict:
 84    """Run benchmark and return statistics."""
 85    times = []
 86
 87    # Warmup
 88    for _ in range(5):
 89        func(content)
 90
 91    # Actual benchmark
 92    for _ in range(iterations):
 93        start = time.perf_counter()
 94        result = func(content)
 95        end = time.perf_counter()
 96        times.append(end - start)
 97
 98    return {
 99        "mean": statistics.mean(times) * 1000,  # Convert to ms
100        "stdev": statistics.stdev(times) * 1000,
101        "min": min(times) * 1000,
102        "max": max(times) * 1000,
103        "links_found": len(result),
104    }
105
106def main():
107    print("=" * 60)
108    print("Markdown Link Parser Benchmark")
109    print("=" * 60)
110
111    # Test different content sizes
112    sizes = [1000, 5000, 10000, 50000]
113
114    python_parser = PythonMarkdownParser()
115
116    # Try to import Cython version
117    try:
118        from markdown_parser import parse_markdown_links as cython_parse
119        has_cython = True
120    except ImportError:
121        print("\nWarning: Cython module not found.")
122        print("Run 'python setup.py build_ext --inplace' first.\n")
123        has_cython = False
124
125    for size in sizes:
126        print(f"\n--- Content size: {size} lines ---")
127        content = generate_test_content(size)
128
129        # Python benchmark
130        py_result = benchmark(python_parser.parse_markdown_links, content)
131        print(f"Python:  {py_result['mean']:.3f} ms (+/- {py_result['stdev']:.3f} ms)")
132        print(f"         Found {py_result['links_found']} links")
133
134        # Cython benchmark (if available)
135        if has_cython:
136            cy_result = benchmark(cython_parse, content)
137            speedup = py_result['mean'] / cy_result['mean']
138            print(f"Cython:  {cy_result['mean']:.3f} ms (+/- {cy_result['stdev']:.3f} ms)")
139            print(f"         Speedup: {speedup:.2f}x")
140
141    print("\n" + "=" * 60)
142
143if __name__ == "__main__":
144    main()

預期結果

執行效能測試後，預期會看到類似以下的結果：

 1============================================================
 2Markdown Link Parser Benchmark
 3============================================================
 4
 5--- Content size: 1000 lines ---
 6Python:  0.523 ms (+/- 0.031 ms)
 7         Found 100 links
 8Cython:  0.198 ms (+/- 0.012 ms)
 9         Speedup: 2.64x
10
11--- Content size: 5000 lines ---
12Python:  2.617 ms (+/- 0.089 ms)
13         Found 500 links
14Cython:  0.892 ms (+/- 0.045 ms)
15         Speedup: 2.93x
16
17--- Content size: 10000 lines ---
18Python:  5.234 ms (+/- 0.156 ms)
19         Found 1000 links
20Cython:  1.712 ms (+/- 0.078 ms)
21         Speedup: 3.06x
22
23--- Content size: 50000 lines ---
24Python:  26.18 ms (+/- 0.823 ms)
25         Found 5000 links
26Cython:  7.89 ms (+/- 0.312 ms)
27         Speedup: 3.32x
28
29============================================================

結果分析：

內容大小	Python	Cython	加速比
1,000 行	0.52 ms	0.20 ms	2.6x
5,000 行	2.62 ms	0.89 ms	2.9x
10,000 行	5.23 ms	1.71 ms	3.1x
50,000 行	26.2 ms	7.89 ms	3.3x

觀察：

加速比隨著資料量增加而提高
主要效能提升來自迴圈優化和型別化變數
正則表達式仍然是瓶頸（Cython 無法加速 re 模組本身）

設計權衡

面向	純 Python	Cython
開發速度	快，即寫即用	中，需要編譯步驟
執行速度	基準	2-5x 加速
除錯難度	低，標準 Python 工具	中，需要看生成的 C 碼
部署複雜度	簡單，純 Python	需要編譯環境或預編譯 wheel
可維護性	高	中，需要了解 Cython 語法
IDE 支援	完整	部分（.pyx 支援有限）
跨平台	天生跨平台	需要為每個平台編譯

進階優化：使用 C 正則表達式

如果需要更高的效能，可以考慮使用 C 語言的正則表達式庫。以下是使用 PCRE2 的範例：

 1# advanced_parser.pyx
 2"""
 3Advanced parser using PCRE2 C library for maximum performance.
 4
 5Requires: libpcre2-dev (Ubuntu) or pcre2 (macOS Homebrew)
 6"""
 7
 8cdef extern from "pcre2.h":
 9    # PCRE2 declarations...
10    pass
11
12# This is an advanced topic, see PCRE2 documentation for details

不過，對於大多數使用情境，Python 的 re 模組配合 Cython 優化的迴圈已經足夠。

什麼時候該用 Cython？

適合使用

熱點程式碼已經用 profiler 確認
需要 2x 以上的效能提升
程式碼相對穩定，不常變動
團隊有能力維護 Cython 程式碼
可以接受編譯步驟

不建議使用

效能瓶頸在 I/O（網路、磁碟）
程式碼還在頻繁迭代中
跨平台部署且沒有 CI/CD 支援
團隊對 C 語言不熟悉
效能提升不到 2x

替代方案考量

 1如果 Cython 不適合你的情境，考慮：
 2
 31. PyPy
 4   - 無需修改程式碼
 5   - JIT 編譯帶來 5-10x 加速
 6   - 但相容性問題較多
 7
 82. Numba
 9   - 針對數值計算優化
10   - 使用裝飾器即可加速
11   - 但僅支援部分 Python 語法
12
133. 演算法優化
14   - 先檢查是否有更好的演算法
15   - 減少不必要的記憶體分配
16   - 使用更高效的資料結構

練習

基礎練習

將以下純 Python 函式轉換為 Cython：

 1# exercise_1.py
 2def count_words(text: str) -> dict:
 3    """Count word frequencies in text."""
 4    words = text.lower().split()
 5    counts = {}
 6    for word in words:
 7        word = word.strip('.,!?;:')
 8        if word:
 9            counts[word] = counts.get(word, 0) + 1
10    return counts

提示：

建立 exercise_1.pyx
為 counts 變數添加 cdef dict 宣告
為迴圈變數添加適當的型別宣告
考慮使用 cdef 輔助函式處理字串清理

進階練習

使用 cProfile 驗證 Cython 加速效果：

 1# exercise_2.py
 2import cProfile
 3import pstats
 4
 5def profile_parsers(content: str):
 6    """Profile both Python and Cython parsers."""
 7    from markdown_parser import parse_markdown_links as cython_parse
 8
 9    python_parser = PythonMarkdownParser()
10
11    # Profile Python version
12    print("=== Python Version ===")
13    cProfile.runctx(
14        'for _ in range(100): python_parser.parse_markdown_links(content)',
15        globals(), locals(),
16        'python_stats'
17    )
18    stats = pstats.Stats('python_stats')
19    stats.strip_dirs().sort_stats('cumulative').print_stats(10)
20
21    # Profile Cython version
22    print("\n=== Cython Version ===")
23    cProfile.runctx(
24        'for _ in range(100): cython_parse(content)',
25        globals(), locals(),
26        'cython_stats'
27    )
28    stats = pstats.Stats('cython_stats')
29    stats.strip_dirs().sort_stats('cumulative').print_stats(10)

挑戰題

比較不同型別宣告策略的效能影響：

無型別宣告：將 .pyx 當作純 Python 編譯
部分型別宣告：只為迴圈變數添加型別
完整型別宣告：為所有變數添加型別
使用 LinkInfo 類別 vs 使用 dict

記錄每種策略的效能，並分析哪些優化帶來最大效益。

延伸閱讀

返回：案例研究 返回：模組四：用 C 擴展 Python

案例：使用 ctypes 呼叫系統 API

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

本案例展示如何使用 ctypes 直接呼叫系統 API，處理 Python 標準庫未提供的底層功能。

先備知識

問題背景

為什麼需要直接呼叫系統 API？

Python 標準庫涵蓋了大多數常見需求，但有時我們需要：

存取特定系統功能：某些底層功能沒有 Python 封裝
避免 subprocess 開銷：執行外部命令有進程建立的成本
即時取得系統資訊：某些資訊需要直接從核心取得
與 C 函式庫互動：使用第三方 C 函式庫的功能

常見場景

1需要直接呼叫系統 API 的情況：
2├── 取得主機名稱（gethostname）
3├── 取得使用者 ID（getuid, geteuid）
4├── 系統時間操作（time, gettimeofday）
5├── 檔案系統操作（sync, fsync）
6├── 記憶體資訊（sysinfo - Linux 限定）
7└── 其他未封裝的 POSIX/Windows API

雖然許多功能有 Python 對應（如 os.getpid()、socket.gethostname()），但理解如何直接呼叫系統 API 是重要的技能：

學習 ctypes 的實際應用
處理 Python 未封裝的功能
理解 Python 標準庫的實作原理

實作方案

基礎設置：跨平台載入 libc

 1# system_api.py
 2"""
 3使用 ctypes 呼叫系統 API 的範例模組。
 4
 5跨平台支援 Linux、macOS 和 Windows。
 6"""
 7
 8import ctypes
 9import ctypes.util
10import sys
11from typing import Optional
12
13def load_libc() -> ctypes.CDLL:
14 """
15 跨平台載入 C 函式庫。
16
17 Returns:
18 ctypes.CDLL: 載入的 C 函式庫物件
19
20 Raises:
21 OSError: 無法載入 C 函式庫
22 """
23 if sys.platform == 'win32':
24 # Windows 使用 msvcrt
25 return ctypes.CDLL('msvcrt')
26 else:
27 # Unix-like 系統使用 find_library
28 libc_name = ctypes.util.find_library('c')
29 if libc_name is None:
30 # 嘗試常見路徑
31 if sys.platform == 'darwin':
32 libc_name = 'libc.dylib'
33 else:
34 libc_name = 'libc.so.6'
35 return ctypes.CDLL(libc_name)
36
37# 全域 libc 實例
38_libc: Optional[ctypes.CDLL] = None
39
40def get_libc() -> ctypes.CDLL:
41 """取得 libc 的單例實例。"""
42 global _libc
43 if _libc is None:
44 _libc = load_libc()
45 return _libc

範例 1：取得主機名稱

 1import ctypes
 2import socket
 3
 4def gethostname_ctypes(max_len: int = 256) -> str:
 5 """
 6 使用 ctypes 呼叫 gethostname() 取得主機名稱。
 7
 8 Args:
 9 max_len: 主機名稱緩衝區大小
10
11 Returns:
12 主機名稱字串
13
14 Raises:
15 OSError: 系統呼叫失敗
16 """
17 libc = get_libc()
18
19 # int gethostname(char *name, size_t len)
20 libc.gethostname.argtypes = [ctypes.c_char_p, ctypes.c_size_t]
21 libc.gethostname.restype = ctypes.c_int
22
23 # 建立緩衝區
24 buffer = ctypes.create_string_buffer(max_len)
25
26 # 呼叫系統函式
27 result = libc.gethostname(buffer, max_len)
28
29 if result != 0:
30 raise OSError(f"gethostname failed with code {result}")
31
32 return buffer.value.decode('utf-8')
33
34# 比較 ctypes 與 Python 標準庫
35if __name__ == "__main__":
36 print(f"ctypes gethostname: {gethostname_ctypes()}")
37 print(f"socket.gethostname: {socket.gethostname()}")

範例 2：取得 Process ID

 1import ctypes
 2import os
 3
 4def getpid_ctypes() -> int:
 5 """
 6 使用 ctypes 呼叫 getpid() 取得當前 process ID。
 7
 8 Returns:
 9 當前 process 的 PID
10 """
11 libc = get_libc()
12
13 # pid_t getpid(void)
14 libc.getpid.argtypes = []
15 libc.getpid.restype = ctypes.c_int
16
17 return libc.getpid()
18
19def getppid_ctypes() -> int:
20 """
21 使用 ctypes 呼叫 getppid() 取得父 process ID。
22
23 Returns:
24 父 process 的 PID
25 """
26 libc = get_libc()
27
28 # pid_t getppid(void)
29 libc.getppid.argtypes = []
30 libc.getppid.restype = ctypes.c_int
31
32 return libc.getppid()
33
34# 驗證結果
35if __name__ == "__main__":
36 print(f"ctypes getpid: {getpid_ctypes()}")
37 print(f"os.getpid: {os.getpid()}")
38 print(f"ctypes getppid: {getppid_ctypes()}")
39 print(f"os.getppid: {os.getppid()}")

範例 3：Unix 時間戳記

 1import ctypes
 2import time as time_module
 3
 4def time_ctypes() -> int:
 5 """
 6 使用 ctypes 呼叫 time() 取得 Unix 時間戳記。
 7
 8 Returns:
 9 當前 Unix 時間戳記（秒）
10 """
11 libc = get_libc()
12
13 # time_t time(time_t *tloc)
14 libc.time.argtypes = [ctypes.c_void_p]
15 libc.time.restype = ctypes.c_long
16
17 # 傳入 NULL，直接取得回傳值
18 return libc.time(None)
19
20# timeval 結構體（用於 gettimeofday）
21class Timeval(ctypes.Structure):
22 """
23 struct timeval {
24 time_t tv_sec; // 秒
25 suseconds_t tv_usec; // 微秒
26 };
27 """
28 _fields_ = [
29 ("tv_sec", ctypes.c_long),
30 ("tv_usec", ctypes.c_long),
31 ]
32
33def gettimeofday_ctypes() -> tuple[int, int]:
34 """
35 使用 ctypes 呼叫 gettimeofday() 取得高精度時間。
36
37 Returns:
38 (秒, 微秒) 的 tuple
39
40 Note:
41 gettimeofday 在 POSIX.1-2008 中已標記為過時，
42 建議使用 clock_gettime。此處僅作為教學範例。
43 """
44 import sys
45 if sys.platform == 'win32':
46 raise NotImplementedError("gettimeofday not available on Windows")
47
48 libc = get_libc()
49
50 # int gettimeofday(struct timeval *tv, struct timezone *tz)
51 libc.gettimeofday.argtypes = [
52 ctypes.POINTER(Timeval),
53 ctypes.c_void_p # timezone 已過時，傳 NULL
54 ]
55 libc.gettimeofday.restype = ctypes.c_int
56
57 tv = Timeval()
58 result = libc.gettimeofday(ctypes.byref(tv), None)
59
60 if result != 0:
61 raise OSError(f"gettimeofday failed with code {result}")
62
63 return (tv.tv_sec, tv.tv_usec)
64
65# 驗證結果
66if __name__ == "__main__":
67 print(f"ctypes time: {time_ctypes()}")
68 print(f"time.time: {int(time_module.time())}")
69
70 import sys
71 if sys.platform != 'win32':
72 sec, usec = gettimeofday_ctypes()
73 print(f"gettimeofday: {sec}.{usec:06d}")

範例 4：使用者與群組 ID（Unix 限定）

 1import ctypes
 2import os
 3import sys
 4
 5def get_user_ids() -> dict:
 6 """
 7 取得當前 process 的使用者和群組 ID。
 8
 9 Returns:
10 包含 uid, euid, gid, egid 的字典
11
12 Note:
13 僅支援 Unix-like 系統。
14 """
15 if sys.platform == 'win32':
16 raise NotImplementedError("User IDs not applicable on Windows")
17
18 libc = get_libc()
19
20 # 設定函式簽名
21 # uid_t getuid(void)
22 libc.getuid.argtypes = []
23 libc.getuid.restype = ctypes.c_uint
24
25 # uid_t geteuid(void)
26 libc.geteuid.argtypes = []
27 libc.geteuid.restype = ctypes.c_uint
28
29 # gid_t getgid(void)
30 libc.getgid.argtypes = []
31 libc.getgid.restype = ctypes.c_uint
32
33 # gid_t getegid(void)
34 libc.getegid.argtypes = []
35 libc.getegid.restype = ctypes.c_uint
36
37 return {
38 'uid': libc.getuid(),
39 'euid': libc.geteuid(),
40 'gid': libc.getgid(),
41 'egid': libc.getegid(),
42 }
43
44# 驗證結果
45if __name__ == "__main__":
46 if sys.platform != 'win32':
47 ids = get_user_ids()
48 print(f"ctypes: uid={ids['uid']}, euid={ids['euid']}, "
49 f"gid={ids['gid']}, egid={ids['egid']}")
50 print(f"os: uid={os.getuid()}, euid={os.geteuid()}, "
51 f"gid={os.getgid()}, egid={os.getegid()}")

跨平台考量

平台差異對照表

功能	Linux	macOS	Windows
libc 名稱	`libc.so.6`	`libc.dylib`	`msvcrt`
`gethostname`	libc	libc	`kernel32.GetComputerNameA`
`getpid`	libc	libc	`kernel32.GetCurrentProcessId`
`time`	libc	libc	`msvcrt.time`
`getuid/geteuid`	libc	libc	不適用

Windows 特定實作

 1import ctypes
 2import sys
 3
 4def gethostname_windows(max_len: int = 256) -> str:
 5 """
 6 Windows 版本的 gethostname。
 7
 8 使用 kernel32.GetComputerNameA。
 9 """
10 if sys.platform != 'win32':
11 raise NotImplementedError("This function is Windows-only")
12
13 kernel32 = ctypes.windll.kernel32
14
15 # BOOL GetComputerNameA(LPSTR lpBuffer, LPDWORD nSize)
16 buffer = ctypes.create_string_buffer(max_len)
17 size = ctypes.c_ulong(max_len)
18
19 result = kernel32.GetComputerNameA(buffer, ctypes.byref(size))
20
21 if not result:
22 raise OSError(f"GetComputerNameA failed")
23
24 return buffer.value.decode('utf-8')
25
26def getpid_windows() -> int:
27 """
28 Windows 版本的 getpid。
29
30 使用 kernel32.GetCurrentProcessId。
31 """
32 if sys.platform != 'win32':
33 raise NotImplementedError("This function is Windows-only")
34
35 kernel32 = ctypes.windll.kernel32
36
37 # DWORD GetCurrentProcessId(void)
38 kernel32.GetCurrentProcessId.argtypes = []
39 kernel32.GetCurrentProcessId.restype = ctypes.c_ulong
40
41 return kernel32.GetCurrentProcessId()

跨平台封裝

 1import sys
 2
 3def get_hostname() -> str:
 4 """跨平台取得主機名稱。"""
 5 if sys.platform == 'win32':
 6 return gethostname_windows()
 7 else:
 8 return gethostname_ctypes()
 9
10def get_process_id() -> int:
11 """跨平台取得 process ID。"""
12 if sys.platform == 'win32':
13 return getpid_windows()
14 else:
15 return getpid_ctypes()

錯誤處理與安全性

常見錯誤類型

 1import ctypes
 2import errno
 3
 4def safe_gethostname(max_len: int = 256) -> str:
 5 """
 6 安全版本的 gethostname，包含完整的錯誤處理。
 7 """
 8 libc = get_libc()
 9
10 # 設定函式簽名
11 libc.gethostname.argtypes = [ctypes.c_char_p, ctypes.c_size_t]
12 libc.gethostname.restype = ctypes.c_int
13
14 # 驗證參數
15 if max_len <= 0:
16 raise ValueError("max_len must be positive")
17
18 if max_len > 1024:
19 raise ValueError("max_len too large (max 1024)")
20
21 # 建立緩衝區
22 buffer = ctypes.create_string_buffer(max_len)
23
24 # 呼叫系統函式
25 result = libc.gethostname(buffer, max_len)
26
27 if result != 0:
28 # 取得錯誤碼
29 err = ctypes.get_errno()
30 if err == errno.ENAMETOOLONG:
31 raise OSError(errno.ENAMETOOLONG,
32 "Hostname too long for buffer")
33 elif err == errno.EFAULT:
34 raise OSError(errno.EFAULT,
35 "Invalid buffer address")
36 else:
37 raise OSError(err, f"gethostname failed: {errno.errorcode.get(err, 'Unknown')}")
38
39 # 解碼並處理可能的編碼錯誤
40 try:
41 return buffer.value.decode('utf-8')
42 except UnicodeDecodeError:
43 return buffer.value.decode('latin-1')

安全性考量

 1"""
 2使用 ctypes 時的安全性注意事項：
 3
 41. 緩衝區溢位
 5 - 永遠確保緩衝區大小足夠
 6 - 使用 create_string_buffer() 而非直接操作指標
 7
 82. 型別安全
 9 - 務必設定 argtypes 和 restype
10 - 錯誤的型別可能導致程式崩潰或安全漏洞
11
123. 記憶體管理
13 - ctypes 物件由 Python GC 管理
14 - 小心回呼函式的生命週期
15
164. 輸入驗證
17 - 永遠驗證使用者輸入
18 - 不要直接將未驗證的資料傳給 C 函式
19"""
20
21def secure_strlen(s: str) -> int:
22 """
23 安全的 strlen 範例，包含輸入驗證。
24 """
25 # 輸入驗證
26 if not isinstance(s, str):
27 raise TypeError("Expected str, got {type(s).__name__}")
28
29 # 限制長度避免 DoS
30 MAX_LENGTH = 10_000_000 # 10 MB
31 if len(s) > MAX_LENGTH:
32 raise ValueError(f"String too long (max {MAX_LENGTH} bytes)")
33
34 libc = get_libc()
35 libc.strlen.argtypes = [ctypes.c_char_p]
36 libc.strlen.restype = ctypes.c_size_t
37
38 # 轉換為 bytes
39 encoded = s.encode('utf-8')
40
41 return libc.strlen(encoded)

錯誤碼處理

 1import ctypes
 2import errno
 3
 4def get_errno_message(err: int) -> str:
 5 """取得錯誤碼對應的訊息。"""
 6 libc = get_libc()
 7
 8 # char *strerror(int errnum)
 9 libc.strerror.argtypes = [ctypes.c_int]
10 libc.strerror.restype = ctypes.c_char_p
11
12 result = libc.strerror(err)
13 if result:
14 return result.decode('utf-8')
15 return f"Unknown error {err}"
16
17# 使用範例
18if __name__ == "__main__":
19 print(f"ENOENT ({errno.ENOENT}): {get_errno_message(errno.ENOENT)}")
20 print(f"EACCES ({errno.EACCES}): {get_errno_message(errno.EACCES)}")
21 print(f"EINVAL ({errno.EINVAL}): {get_errno_message(errno.EINVAL)}")

效能比較：ctypes vs subprocess

測試腳本

 1import subprocess
 2import time
 3import statistics
 4from typing import Callable
 5
 6def benchmark(func: Callable, iterations: int = 1000) -> dict:
 7 """執行效能測試並回傳統計資料。"""
 8 times = []
 9
10 # 暖機
11 for _ in range(10):
12 func()
13
14 # 實際測試
15 for _ in range(iterations):
16 start = time.perf_counter()
17 func()
18 end = time.perf_counter()
19 times.append(end - start)
20
21 return {
22 'mean': statistics.mean(times) * 1_000_000, # 轉換為微秒
23 'stdev': statistics.stdev(times) * 1_000_000,
24 'min': min(times) * 1_000_000,
25 'max': max(times) * 1_000_000,
26 }
27
28# 方法 1：ctypes
29def hostname_ctypes():
30 return gethostname_ctypes()
31
32# 方法 2：subprocess
33def hostname_subprocess():
34 result = subprocess.run(
35 ['hostname'],
36 capture_output=True,
37 text=True
38 )
39 return result.stdout.strip()
40
41# 方法 3：Python 標準庫
42def hostname_stdlib():
43 import socket
44 return socket.gethostname()
45
46# 執行測試
47if __name__ == "__main__":
48 print("=" * 60)
49 print("取得主機名稱效能比較")
50 print("=" * 60)
51
52 methods = [
53 ("ctypes", hostname_ctypes),
54 ("subprocess", hostname_subprocess),
55 ("socket (stdlib)", hostname_stdlib),
56 ]
57
58 for name, func in methods:
59 result = benchmark(func)
60 print(f"\n{name}:")
61 print(f" 平均: {result['mean']:.2f} us")
62 print(f" 標準差: {result['stdev']:.2f} us")
63 print(f" 最小: {result['min']:.2f} us")
64 print(f" 最大: {result['max']:.2f} us")

效能測試結果

 1============================================================
 2取得主機名稱效能比較
 3============================================================
 4
 5ctypes:
 6 平均: 1.52 us
 7 標準差: 0.31 us
 8 最小: 1.21 us
 9 最大: 8.45 us
10
11subprocess:
12 平均: 4523.67 us
13 標準差: 892.34 us
14 最小: 3128.45 us
15 最大: 12456.78 us
16
17socket (stdlib):
18 平均: 0.89 us
19 標準差: 0.18 us
20 最小: 0.72 us
21 最大: 4.23 us

結果分析

方法	平均時間	相對 ctypes	適用場景
socket (stdlib)	~0.9 us	0.6x (最快)	首選，已有封裝
ctypes	~1.5 us	1x (基準)	無標準庫支援時
subprocess	~4500 us	~3000x (最慢)	需要執行外部命令時

結論：

案例：pybind11 綁定 C++ 類別

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

本案例展示如何使用 pybind11 將 C++ 類別完整綁定到 Python，包含建構子、方法、屬性、運算子重載，以及記憶體管理與生命週期控制。

先備知識

問題背景

使用情境

在以下情境中，你可能需要在 Python 中使用 C++ 類別：

複用現有 C++ 程式庫：公司有成熟的 C++ 資料結構或演算法，想在 Python 專案中使用
效能敏感的資料處理：需要高效的記憶體管理和計算效能
自訂資料結構：標準 Python 容器無法滿足特定需求

設計目標

本案例將建立一個 StringProcessor 類別，展示：

1StringProcessor 功能：
2├── 建構子：支援預設和參數化初始化
3├── 方法：字串處理（大小寫轉換、統計、搜尋）
4├── 屬性：可讀寫的狀態屬性
5├── 運算子重載：+ 運算子串接、[] 索引存取
6├── 記憶體管理：正確處理物件生命週期
7└── 效能優化：避免不必要的記憶體複製

實作步驟

步驟 1：專案結構

 1pybind11_string_processor/
 2├── CMakeLists.txt
 3├── setup.py
 4├── src/
 5│   ├── string_processor.hpp    # C++ 標頭檔
 6│   ├── string_processor.cpp    # C++ 實作
 7│   └── bindings.cpp            # pybind11 綁定
 8├── tests/
 9│   └── test_string_processor.py
10└── benchmark.py

步驟 2：C++ 類別定義

首先，建立 C++ 類別的標頭檔：

  1// src/string_processor.hpp
  2#ifndef STRING_PROCESSOR_HPP
  3#define STRING_PROCESSOR_HPP
  4
  5#include 
  6#include 
  7#include 
  8#include 
  9#include 
 10
 11/**
 12 * StringProcessor: 高效能字串處理類別
 13 *
 14 * 提供字串操作、統計分析和搜尋功能。
 15 * 設計用於展示 pybind11 的類別綁定特性。
 16 */
 17class StringProcessor {
 18public:
 19    // ========================================
 20    // 建構子與解構子
 21    // ========================================
 22
 23    // 預設建構子
 24    StringProcessor();
 25
 26    // 參數化建構子
 27    explicit StringProcessor(const std::string& content);
 28
 29    // 複製建構子
 30    StringProcessor(const StringProcessor& other);
 31
 32    // 移動建構子
 33    StringProcessor(StringProcessor&& other) noexcept;
 34
 35    // 解構子
 36    ~StringProcessor();
 37
 38    // ========================================
 39    // 基本方法
 40    // ========================================
 41
 42    // 取得內容
 43    const std::string& content() const { return content_; }
 44
 45    // 設定內容
 46    void set_content(const std::string& content);
 47
 48    // 取得長度
 49    size_t length() const { return content_.length(); }
 50
 51    // 是否為空
 52    bool empty() const { return content_.empty(); }
 53
 54    // ========================================
 55    // 字串處理方法
 56    // ========================================
 57
 58    // 轉換為大寫
 59    std::string to_upper() const;
 60
 61    // 轉換為小寫
 62    std::string to_lower() const;
 63
 64    // 反轉字串
 65    std::string reverse() const;
 66
 67    // 移除前後空白
 68    std::string trim() const;
 69
 70    // 分割字串
 71    std::vector<std::string> split(const std::string& delimiter = " ") const;
 72
 73    // 取代子字串
 74    std::string replace(const std::string& old_str,
 75                        const std::string& new_str) const;
 76
 77    // ========================================
 78    // 統計分析方法
 79    // ========================================
 80
 81    // 字元頻率統計
 82    std::unordered_map<char, int> char_frequency() const;
 83
 84    // 單字計數
 85    size_t word_count() const;
 86
 87    // 子字串出現次數
 88    size_t count_occurrences(const std::string& substring) const;
 89
 90    // ========================================
 91    // 搜尋方法
 92    // ========================================
 93
 94    // 搜尋子字串位置（找不到回傳 -1）
 95    int find(const std::string& substring, size_t start = 0) const;
 96
 97    // 搜尋所有出現位置
 98    std::vector<size_t> find_all(const std::string& substring) const;
 99
100    // 是否包含子字串
101    bool contains(const std::string& substring) const;
102
103    // 是否以指定字串開頭
104    bool starts_with(const std::string& prefix) const;
105
106    // 是否以指定字串結尾
107    bool ends_with(const std::string& suffix) const;
108
109    // ========================================
110    // 運算子重載
111    // ========================================
112
113    // + 運算子：串接
114    StringProcessor operator+(const StringProcessor& other) const;
115
116    // += 運算子：原地串接
117    StringProcessor& operator+=(const StringProcessor& other);
118
119    // [] 運算子：索引存取
120    char operator[](size_t index) const;
121
122    // == 運算子：相等比較
123    bool operator==(const StringProcessor& other) const;
124
125    // != 運算子：不等比較
126    bool operator!=(const StringProcessor& other) const;
127
128    // ========================================
129    // 指派運算子
130    // ========================================
131
132    StringProcessor& operator=(const StringProcessor& other);
133    StringProcessor& operator=(StringProcessor&& other) noexcept;
134
135private:
136    std::string content_;
137
138    // 處理計數器（用於展示狀態追蹤）
139    mutable size_t operation_count_ = 0;
140
141    // 輔助方法
142    void increment_operation_count() const { ++operation_count_; }
143
144public:
145    // 取得操作計數（用於效能分析）
146    size_t operation_count() const { return operation_count_; }
147    void reset_operation_count() { operation_count_ = 0; }
148};
149
150#endif // STRING_PROCESSOR_HPP

步驟 3：C++ 實作

  1// src/string_processor.cpp
  2#include "string_processor.hpp"
  3#include 
  4#include 
  5#include 
  6
  7// ========================================
  8// 建構子與解構子
  9// ========================================
 10
 11StringProcessor::StringProcessor() : content_("") {}
 12
 13StringProcessor::StringProcessor(const std::string& content)
 14    : content_(content) {}
 15
 16StringProcessor::StringProcessor(const StringProcessor& other)
 17    : content_(other.content_), operation_count_(0) {}
 18
 19StringProcessor::StringProcessor(StringProcessor&& other) noexcept
 20    : content_(std::move(other.content_)), operation_count_(0) {
 21    other.content_.clear();
 22}
 23
 24StringProcessor::~StringProcessor() = default;
 25
 26// ========================================
 27// 基本方法
 28// ========================================
 29
 30void StringProcessor::set_content(const std::string& content) {
 31    content_ = content;
 32    increment_operation_count();
 33}
 34
 35// ========================================
 36// 字串處理方法
 37// ========================================
 38
 39std::string StringProcessor::to_upper() const {
 40    increment_operation_count();
 41    std::string result = content_;
 42    std::transform(result.begin(), result.end(), result.begin(),
 43                   [](unsigned char c) { return std::toupper(c); });
 44    return result;
 45}
 46
 47std::string StringProcessor::to_lower() const {
 48    increment_operation_count();
 49    std::string result = content_;
 50    std::transform(result.begin(), result.end(), result.begin(),
 51                   [](unsigned char c) { return std::tolower(c); });
 52    return result;
 53}
 54
 55std::string StringProcessor::reverse() const {
 56    increment_operation_count();
 57    std::string result = content_;
 58    std::reverse(result.begin(), result.end());
 59    return result;
 60}
 61
 62std::string StringProcessor::trim() const {
 63    increment_operation_count();
 64    size_t start = content_.find_first_not_of(" \t\n\r\f\v");
 65    if (start == std::string::npos) {
 66        return "";
 67    }
 68    size_t end = content_.find_last_not_of(" \t\n\r\f\v");
 69    return content_.substr(start, end - start + 1);
 70}
 71
 72std::vector<std::string> StringProcessor::split(const std::string& delimiter) const {
 73    increment_operation_count();
 74    std::vector<std::string> result;
 75
 76    if (delimiter.empty()) {
 77        // 空分隔符：按字元分割
 78        for (char c : content_) {
 79            result.push_back(std::string(1, c));
 80        }
 81        return result;
 82    }
 83
 84    size_t start = 0;
 85    size_t end = content_.find(delimiter);
 86
 87    while (end != std::string::npos) {
 88        result.push_back(content_.substr(start, end - start));
 89        start = end + delimiter.length();
 90        end = content_.find(delimiter, start);
 91    }
 92
 93    result.push_back(content_.substr(start));
 94    return result;
 95}
 96
 97std::string StringProcessor::replace(const std::string& old_str,
 98                                     const std::string& new_str) const {
 99    increment_operation_count();
100    if (old_str.empty()) {
101        return content_;
102    }
103
104    std::string result = content_;
105    size_t pos = 0;
106    while ((pos = result.find(old_str, pos)) != std::string::npos) {
107        result.replace(pos, old_str.length(), new_str);
108        pos += new_str.length();
109    }
110    return result;
111}
112
113// ========================================
114// 統計分析方法
115// ========================================
116
117std::unordered_map<char, int> StringProcessor::char_frequency() const {
118    increment_operation_count();
119    std::unordered_map<char, int> freq;
120    for (char c : content_) {
121        freq[c]++;
122    }
123    return freq;
124}
125
126size_t StringProcessor::word_count() const {
127    increment_operation_count();
128    if (content_.empty()) {
129        return 0;
130    }
131
132    std::istringstream iss(content_);
133    size_t count = 0;
134    std::string word;
135    while (iss >> word) {
136        count++;
137    }
138    return count;
139}
140
141size_t StringProcessor::count_occurrences(const std::string& substring) const {
142    increment_operation_count();
143    if (substring.empty()) {
144        return 0;
145    }
146
147    size_t count = 0;
148    size_t pos = 0;
149    while ((pos = content_.find(substring, pos)) != std::string::npos) {
150        count++;
151        pos += substring.length();
152    }
153    return count;
154}
155
156// ========================================
157// 搜尋方法
158// ========================================
159
160int StringProcessor::find(const std::string& substring, size_t start) const {
161    increment_operation_count();
162    size_t pos = content_.find(substring, start);
163    return (pos == std::string::npos) ? -1 : static_cast<int>(pos);
164}
165
166std::vector<size_t> StringProcessor::find_all(const std::string& substring) const {
167    increment_operation_count();
168    std::vector<size_t> positions;
169    if (substring.empty()) {
170        return positions;
171    }
172
173    size_t pos = 0;
174    while ((pos = content_.find(substring, pos)) != std::string::npos) {
175        positions.push_back(pos);
176        pos += substring.length();
177    }
178    return positions;
179}
180
181bool StringProcessor::contains(const std::string& substring) const {
182    increment_operation_count();
183    return content_.find(substring) != std::string::npos;
184}
185
186bool StringProcessor::starts_with(const std::string& prefix) const {
187    increment_operation_count();
188    if (prefix.length() > content_.length()) {
189        return false;
190    }
191    return content_.compare(0, prefix.length(), prefix) == 0;
192}
193
194bool StringProcessor::ends_with(const std::string& suffix) const {
195    increment_operation_count();
196    if (suffix.length() > content_.length()) {
197        return false;
198    }
199    return content_.compare(content_.length() - suffix.length(),
200                            suffix.length(), suffix) == 0;
201}
202
203// ========================================
204// 運算子重載
205// ========================================
206
207StringProcessor StringProcessor::operator+(const StringProcessor& other) const {
208    increment_operation_count();
209    return StringProcessor(content_ + other.content_);
210}
211
212StringProcessor& StringProcessor::operator+=(const StringProcessor& other) {
213    increment_operation_count();
214    content_ += other.content_;
215    return *this;
216}
217
218char StringProcessor::operator[](size_t index) const {
219    increment_operation_count();
220    if (index >= content_.length()) {
221        throw std::out_of_range("Index out of range: " + std::to_string(index));
222    }
223    return content_[index];
224}
225
226bool StringProcessor::operator==(const StringProcessor& other) const {
227    return content_ == other.content_;
228}
229
230bool StringProcessor::operator!=(const StringProcessor& other) const {
231    return content_ != other.content_;
232}
233
234// ========================================
235// 指派運算子
236// ========================================
237
238StringProcessor& StringProcessor::operator=(const StringProcessor& other) {
239    if (this != &other) {
240        content_ = other.content_;
241        operation_count_ = 0;
242    }
243    return *this;
244}
245
246StringProcessor& StringProcessor::operator=(StringProcessor&& other) noexcept {
247    if (this != &other) {
248        content_ = std::move(other.content_);
249        operation_count_ = 0;
250        other.content_.clear();
251    }
252    return *this;
253}

步驟 4：pybind11 綁定

這是最關鍵的部分，將 C++ 類別暴露給 Python：

  1// src/bindings.cpp
  2#include 
  3#include   // 支援 STL 容器自動轉換
  4#include   // 支援運算子重載
  5
  6#include "string_processor.hpp"
  7
  8namespace py = pybind11;
  9
 10PYBIND11_MODULE(string_processor, m) {
 11    m.doc() = "StringProcessor: 高效能字串處理模組";
 12
 13    // ========================================
 14    // 類別綁定
 15    // ========================================
 16    py::class_<StringProcessor>(m, "StringProcessor")
 17        // ----------------------------------------
 18        // 建構子
 19        // ----------------------------------------
 20        .def(py::init<>(), "建立空的 StringProcessor")
 21        .def(py::init<const std::string&>(),
 22             py::arg("content"),
 23             "使用指定內容建立 StringProcessor")
 24
 25        // 複製建構（Python 的 copy 模組會使用）
 26        .def(py::init<const StringProcessor&>())
 27
 28        // ----------------------------------------
 29        // 屬性
 30        // ----------------------------------------
 31        // content 屬性：可讀寫
 32        .def_property("content",
 33                      &StringProcessor::content,
 34                      &StringProcessor::set_content,
 35                      "字串內容")
 36
 37        // 唯讀屬性
 38        .def_property_readonly("length",
 39                               &StringProcessor::length,
 40                               "字串長度")
 41        .def_property_readonly("empty",
 42                               &StringProcessor::empty,
 43                               "是否為空")
 44        .def_property_readonly("operation_count",
 45                               &StringProcessor::operation_count,
 46                               "操作計數器")
 47
 48        // ----------------------------------------
 49        // 基本方法
 50        // ----------------------------------------
 51        .def("reset_operation_count",
 52             &StringProcessor::reset_operation_count,
 53             "重置操作計數器")
 54
 55        // ----------------------------------------
 56        // 字串處理方法
 57        // ----------------------------------------
 58        .def("to_upper",
 59             &StringProcessor::to_upper,
 60             "轉換為大寫")
 61        .def("to_lower",
 62             &StringProcessor::to_lower,
 63             "轉換為小寫")
 64        .def("reverse",
 65             &StringProcessor::reverse,
 66             "反轉字串")
 67        .def("trim",
 68             &StringProcessor::trim,
 69             "移除前後空白")
 70        .def("split",
 71             &StringProcessor::split,
 72             py::arg("delimiter") = " ",
 73             "以分隔符分割字串")
 74        .def("replace",
 75             &StringProcessor::replace,
 76             py::arg("old_str"),
 77             py::arg("new_str"),
 78             "取代子字串")
 79
 80        // ----------------------------------------
 81        // 統計分析方法
 82        // ----------------------------------------
 83        .def("char_frequency",
 84             &StringProcessor::char_frequency,
 85             "統計字元頻率")
 86        .def("word_count",
 87             &StringProcessor::word_count,
 88             "計算單字數量")
 89        .def("count_occurrences",
 90             &StringProcessor::count_occurrences,
 91             py::arg("substring"),
 92             "計算子字串出現次數")
 93
 94        // ----------------------------------------
 95        // 搜尋方法
 96        // ----------------------------------------
 97        .def("find",
 98             &StringProcessor::find,
 99             py::arg("substring"),
100             py::arg("start") = 0,
101             "搜尋子字串位置（找不到回傳 -1）")
102        .def("find_all",
103             &StringProcessor::find_all,
104             py::arg("substring"),
105             "搜尋所有出現位置")
106        .def("contains",
107             &StringProcessor::contains,
108             py::arg("substring"),
109             "是否包含子字串")
110        .def("starts_with",
111             &StringProcessor::starts_with,
112             py::arg("prefix"),
113             "是否以指定字串開頭")
114        .def("ends_with",
115             &StringProcessor::ends_with,
116             py::arg("suffix"),
117             "是否以指定字串結尾")
118
119        // ----------------------------------------
120        // 運算子重載
121        // ----------------------------------------
122
123        // + 運算子：StringProcessor + StringProcessor
124        .def(py::self + py::self)
125
126        // += 運算子
127        .def(py::self += py::self)
128
129        // == 和 != 運算子
130        .def(py::self == py::self)
131        .def(py::self != py::self)
132
133        // [] 運算子：索引存取
134        .def("__getitem__",
135             &StringProcessor::operator[],
136             py::arg("index"),
137             "取得指定位置的字元")
138
139        // ----------------------------------------
140        // Python 特殊方法
141        // ----------------------------------------
142
143        // __repr__：物件表示
144        .def("__repr__",
145             [](const StringProcessor& sp) {
146                 std::string repr = " + std::to_string(sp.length()) + ">";
153                 return repr;
154             })
155
156        // __str__：字串轉換
157        .def("__str__",
158             [](const StringProcessor& sp) {
159                 return sp.content();
160             })
161
162        // __len__：長度
163        .def("__len__",
164             &StringProcessor::length)
165
166        // __bool__：布林轉換
167        .def("__bool__",
168             [](const StringProcessor& sp) {
169                 return !sp.empty();
170             })
171
172        // __contains__：in 運算子
173        .def("__contains__",
174             &StringProcessor::contains,
175             py::arg("substring"))
176
177        // __iter__：迭代支援
178        .def("__iter__",
179             [](const StringProcessor& sp) {
180                 return py::make_iterator(sp.content().begin(),
181                                          sp.content().end());
182             },
183             py::keep_alive<0, 1>())  // 保持物件存活
184
185        // __hash__：雜湊支援（讓物件可作為 dict key）
186        .def("__hash__",
187             [](const StringProcessor& sp) {
188                 return std::hash<std::string>{}(sp.content());
189             })
190
191        // 支援 pickle
192        .def(py::pickle(
193            // __getstate__
194            [](const StringProcessor& sp) {
195                return py::make_tuple(sp.content());
196            },
197            // __setstate__
198            [](py::tuple t) {
199                if (t.size() != 1) {
200                    throw std::runtime_error("Invalid state");
201                }
202                return StringProcessor(t[0].cast<std::string>());
203            }
204        ));
205
206    // ========================================
207    // 模組層級函式
208    // ========================================
209    m.def("concatenate",
210          [](const std::vector<StringProcessor>& processors,
211             const std::string& separator) {
212              if (processors.empty()) {
213                  return StringProcessor();
214              }
215              std::string result = processors[0].content();
216              for (size_t i = 1; i < processors.size(); i++) {
217                  result += separator + processors[i].content();
218              }
219              return StringProcessor(result);
220          },
221          py::arg("processors"),
222          py::arg("separator") = "",
223          "串接多個 StringProcessor");
224
225    // 版本資訊
226    m.attr("__version__") = "0.1.0";
227}

步驟 5：建構檔案

CMakeLists.txt：

 1cmake_minimum_required(VERSION 3.15)
 2project(string_processor LANGUAGES CXX)
 3
 4set(CMAKE_CXX_STANDARD 17)
 5set(CMAKE_CXX_STANDARD_REQUIRED ON)
 6
 7# 找到 pybind11
 8find_package(pybind11 REQUIRED)
 9
10# 建立 Python 模組
11pybind11_add_module(string_processor
12    src/string_processor.cpp
13    src/bindings.cpp
14)
15
16# 包含標頭檔目錄
17target_include_directories(string_processor PRIVATE src)
18
19# 優化設定
20target_compile_options(string_processor PRIVATE
21    $<$>:-O3 -march=native>
22    $<$>:/O2>
23)

setup.py：

 1# setup.py
 2from setuptools import setup
 3from pybind11.setup_helpers import Pybind11Extension, build_ext
 4
 5ext_modules = [
 6    Pybind11Extension(
 7        "string_processor",
 8        sources=[
 9            "src/string_processor.cpp",
10            "src/bindings.cpp",
11        ],
12        include_dirs=["src"],
13        cxx_std=17,
14        extra_compile_args=["-O3"],
15    ),
16]
17
18setup(
19    name="string_processor",
20    version="0.1.0",
21    description="High-performance string processor using pybind11",
22    ext_modules=ext_modules,
23    cmdclass={"build_ext": build_ext},
24    python_requires=">=3.8",
25)

記憶體管理與物件生命週期

pybind11 的記憶體管理策略

pybind11 提供多種方式控制物件的所有權：

 1// 1. return_value_policy::automatic（預設）
 2// pybind11 自動決定最佳策略
 3.def("get_content", &StringProcessor::content)
 4
 5// 2. return_value_policy::copy
 6// 總是建立副本，Python 擁有副本
 7.def("get_content_copy", &StringProcessor::content,
 8     py::return_value_policy::copy)
 9
10// 3. return_value_policy::reference
11// 回傳參考，不轉移所有權（危險：可能產生懸空指標）
12.def("get_content_ref", &StringProcessor::content,
13     py::return_value_policy::reference)
14
15// 4. return_value_policy::reference_internal
16// 回傳參考，並保持父物件存活
17.def("get_content_internal", &StringProcessor::content,
18     py::return_value_policy::reference_internal)

keep_alive 策略

當物件間有依賴關係時，使用 keep_alive 確保生命週期正確：

 1// keep_alive
 2// Nurse: 需要被保持存活的物件的引數索引
 3// Patient: 依賴 Nurse 的物件的引數索引
 4// 0 = 回傳值, 1 = self, 2+ = 其他引數
 5
 6// 範例：迭代器需要保持原物件存活
 7.def("__iter__",
 8     [](const StringProcessor& sp) {
 9         return py::make_iterator(sp.content().begin(),
10                                  sp.content().end());
11     },
12     py::keep_alive<0, 1>())  // 回傳值(0)存活期間，self(1)必須存活

智慧指標支援

pybind11 自動支援 std::shared_ptr 和 std::unique_ptr：

1// 使用 shared_ptr 管理物件
2py::class_<StringProcessor, std::shared_ptr<StringProcessor>>(m, "StringProcessor")
3    // ...
4
5// 工廠函式回傳 shared_ptr
6m.def("create_processor", []() {
7    return std::make_shared<StringProcessor>("factory created");
8});

Python 使用範例

基本使用

 1from string_processor import StringProcessor, concatenate
 2
 3# 建立物件
 4sp = StringProcessor("Hello, World!")
 5print(sp)           # Hello, World!
 6print(repr(sp))     # 
 7print(len(sp))      # 13
 8
 9# 屬性存取
10print(sp.content)   # Hello, World!
11print(sp.length)    # 13
12print(sp.empty)     # False
13
14# 修改內容
15sp.content = "New content"
16print(sp.content)   # New content

字串處理

 1sp = StringProcessor("  Hello, Python World!  ")
 2
 3# 大小寫轉換
 4print(sp.to_upper())  # "  HELLO, PYTHON WORLD!  "
 5print(sp.to_lower())  # "  hello, python world!  "
 6
 7# 修剪空白
 8print(sp.trim())      # "Hello, Python World!"
 9
10# 反轉
11print(sp.reverse())   # "  !dlroW nohtyP ,olleH  "
12
13# 分割
14sp = StringProcessor("apple,banana,cherry")
15print(sp.split(","))  # ['apple', 'banana', 'cherry']
16
17# 取代
18print(sp.replace(",", " | "))  # "apple | banana | cherry"

統計與搜尋

 1sp = StringProcessor("hello hello world")
 2
 3# 統計
 4print(sp.word_count())              # 3
 5print(sp.count_occurrences("hello")) # 2
 6print(sp.char_frequency())          # {'h': 2, 'e': 2, 'l': 5, ...}
 7
 8# 搜尋
 9print(sp.find("world"))             # 12
10print(sp.find_all("hello"))         # [0, 6]
11print(sp.contains("world"))         # True
12print(sp.starts_with("hello"))      # True
13print(sp.ends_with("world"))        # True

運算子使用

 1sp1 = StringProcessor("Hello")
 2sp2 = StringProcessor(" World")
 3
 4# + 運算子
 5sp3 = sp1 + sp2
 6print(sp3.content)   # "Hello World"
 7
 8# += 運算子
 9sp1 += sp2
10print(sp1.content)   # "Hello World"
11
12# [] 索引
13print(sp3[0])        # 'H'
14print(sp3[6])        # 'W'
15
16# in 運算子
17print("World" in sp3)  # True
18
19# 比較運算子
20print(sp1 == sp3)    # True
21print(sp1 != sp2)    # True

Python 特殊功能

 1import copy
 2import pickle
 3
 4sp = StringProcessor("test data")
 5
 6# 迭代
 7for char in sp:
 8    print(char, end="")  # t e s t   d a t a
 9
10# 複製
11sp_copy = copy.copy(sp)
12
13# 序列化
14data = pickle.dumps(sp)
15sp_restored = pickle.loads(data)
16print(sp_restored.content)  # "test data"
17
18# 作為 dict key
19cache = {sp: "cached value"}
20print(cache[sp])  # "cached value"

效能測試

建立效能測試腳本，比較 C++ 綁定與純 Python 實作：

  1# benchmark.py
  2"""
  3效能比較：pybind11 StringProcessor vs 純 Python
  4"""
  5
  6import time
  7import statistics
  8from typing import Callable, Any
  9
 10# pybind11 版本
 11from string_processor import StringProcessor
 12
 13# 純 Python 版本
 14class PyStringProcessor:
 15    """純 Python 實作作為效能基準"""
 16
 17    def __init__(self, content: str = ""):
 18        self._content = content
 19
 20    @property
 21    def content(self) -> str:
 22        return self._content
 23
 24    @content.setter
 25    def content(self, value: str):
 26        self._content = value
 27
 28    def to_upper(self) -> str:
 29        return self._content.upper()
 30
 31    def to_lower(self) -> str:
 32        return self._content.lower()
 33
 34    def reverse(self) -> str:
 35        return self._content[::-1]
 36
 37    def split(self, delimiter: str = " ") -> list:
 38        return self._content.split(delimiter)
 39
 40    def char_frequency(self) -> dict:
 41        freq = {}
 42        for c in self._content:
 43            freq[c] = freq.get(c, 0) + 1
 44        return freq
 45
 46    def word_count(self) -> int:
 47        return len(self._content.split())
 48
 49    def count_occurrences(self, substring: str) -> int:
 50        count = 0
 51        start = 0
 52        while True:
 53            pos = self._content.find(substring, start)
 54            if pos == -1:
 55                break
 56            count += 1
 57            start = pos + len(substring)
 58        return count
 59
 60    def find_all(self, substring: str) -> list:
 61        positions = []
 62        start = 0
 63        while True:
 64            pos = self._content.find(substring, start)
 65            if pos == -1:
 66                break
 67            positions.append(pos)
 68            start = pos + len(substring)
 69        return positions
 70
 71def benchmark(func: Callable[[], Any],
 72              iterations: int = 1000,
 73              warmup: int = 100) -> dict:
 74    """執行效能測試並回傳統計資料"""
 75    # 預熱
 76    for _ in range(warmup):
 77        func()
 78
 79    # 正式測試
 80    times = []
 81    for _ in range(iterations):
 82        start = time.perf_counter()
 83        func()
 84        end = time.perf_counter()
 85        times.append((end - start) * 1000)  # 轉換為毫秒
 86
 87    return {
 88        "mean": statistics.mean(times),
 89        "stdev": statistics.stdev(times),
 90        "min": min(times),
 91        "max": max(times),
 92        "median": statistics.median(times),
 93    }
 94
 95def generate_test_content(size: int) -> str:
 96    """產生測試用字串"""
 97    base = "Hello World! This is a test string for benchmarking. "
 98    return (base * (size // len(base) + 1))[:size]
 99
100def run_benchmarks():
101    """執行所有效能測試"""
102    print("=" * 70)
103    print("StringProcessor 效能測試：pybind11 vs 純 Python")
104    print("=" * 70)
105
106    sizes = [1_000, 10_000, 100_000, 1_000_000]
107
108    for size in sizes:
109        content = generate_test_content(size)
110        cpp_sp = StringProcessor(content)
111        py_sp = PyStringProcessor(content)
112
113        print(f"\n--- 字串長度：{size:,} 字元 ---\n")
114
115        # 測試項目
116        tests = [
117            ("to_upper", lambda: cpp_sp.to_upper(), lambda: py_sp.to_upper()),
118            ("to_lower", lambda: cpp_sp.to_lower(), lambda: py_sp.to_lower()),
119            ("reverse", lambda: cpp_sp.reverse(), lambda: py_sp.reverse()),
120            ("char_frequency", lambda: cpp_sp.char_frequency(), lambda: py_sp.char_frequency()),
121            ("word_count", lambda: cpp_sp.word_count(), lambda: py_sp.word_count()),
122            ("count_occurrences", lambda: cpp_sp.count_occurrences("test"), lambda: py_sp.count_occurrences("test")),
123            ("find_all", lambda: cpp_sp.find_all("Hello"), lambda: py_sp.find_all("Hello")),
124        ]
125
126        for name, cpp_func, py_func in tests:
127            cpp_result = benchmark(cpp_func, iterations=500)
128            py_result = benchmark(py_func, iterations=500)
129
130            speedup = py_result["mean"] / cpp_result["mean"]
131
132            print(f"{name:20s}")
133            print(f"  C++:    {cpp_result['mean']:8.4f} ms (stdev: {cpp_result['stdev']:.4f})")
134            print(f"  Python: {py_result['mean']:8.4f} ms (stdev: {py_result['stdev']:.4f})")
135            print(f"  加速比: {speedup:.2f}x")
136            print()
137
138    print("=" * 70)
139
140if __name__ == "__main__":
141    run_benchmarks()

預期效能結果

 1======================================================================
 2StringProcessor 效能測試：pybind11 vs 純 Python
 3======================================================================
 4
 5--- 字串長度：1,000 字元 ---
 6
 7to_upper
 8  C++:      0.0012 ms (stdev: 0.0003)
 9  Python:   0.0008 ms (stdev: 0.0002)
10  加速比: 0.67x
11
12char_frequency
13  C++:      0.0089 ms (stdev: 0.0012)
14  Python:   0.0423 ms (stdev: 0.0045)
15  加速比: 4.75x
16
17word_count
18  C++:      0.0034 ms (stdev: 0.0008)
19  Python:   0.0028 ms (stdev: 0.0006)
20  加速比: 0.82x
21
22--- 字串長度：100,000 字元 ---
23
24to_upper
25  C++:      0.0892 ms (stdev: 0.0089)
26  Python:   0.0634 ms (stdev: 0.0067)
27  加速比: 0.71x
28
29char_frequency
30  C++:      0.7823 ms (stdev: 0.0456)
31  Python:   4.2341 ms (stdev: 0.2134)
32  加速比: 5.41x
33
34count_occurrences
35  C++:      0.0234 ms (stdev: 0.0034)
36  Python:   0.0567 ms (stdev: 0.0078)
37  加速比: 2.42x
38
39find_all
40  C++:      0.0312 ms (stdev: 0.0045)
41  Python:   0.0823 ms (stdev: 0.0098)
42  加速比: 2.64x
43
44======================================================================

效能分析

操作類型	C++ 優勢	說明
字元頻率統計	4-6x	C++ unordered_map 比 Python dict 更快
搜尋操作	2-3x	C++ string::find 效率高
大小寫轉換	0.7x	Python 內建函式已高度優化
單字計數	0.8-1x	Python split() 非常高效

重點觀察：

不是所有操作都能加速：Python 的內建字串方法（如 upper()、split()）已經用 C 實作，pybind11 包裝反而增加呼叫開銷
複雜操作效益明顯：需要多次迴圈或資料結構操作的方法（如字元頻率統計）獲益最大
資料量影響顯著：資料量越大，C++ 的優勢越明顯

設計權衡

面向	純 Python	pybind11 C++ 綁定
開發速度	快	中（需要 C++ 開發經驗）
效能	基準	特定操作 2-6x 加速
記憶體使用	較高	較低（C++ 記憶體管理）
除錯難度	低	中高（需要 C++ 除錯工具）
部署複雜度	簡單	需要編譯環境
可維護性	高	中（需要維護兩種語言）

何時使用 pybind11 綁定 C++ 類別？

適合使用：

已有成熟的 C++ 程式庫需要在 Python 中使用
需要精細的記憶體管理
效能瓶頸在資料結構操作而非 I/O
需要與其他 C++ 系統整合

不建議使用：

純字串處理（Python 內建已很快）
簡單的資料容器（用 Python dataclass 更簡潔）
快速原型開發
團隊沒有 C++ 經驗

練習

基礎練習

擴展 StringProcessor，新增以下方法：

join(separator: str, strings: list[str]) - 用分隔符串接字串列表
pad_left(width: int, char: str) - 左側填充字元
pad_right(width: int, char: str) - 右側填充字元

進階練習

建立一個 DataBuffer 類別，展示：

使用 std::vector 儲存二進位資料
支援 Python buffer protocol（可與 NumPy 互通）
實作切片操作（__getitem__ 支援 slice）

挑戰題

比較三種綁定方式的效能：

pybind11 直接綁定
pybind11 + 釋放 GIL
使用 NumPy 陣列避免資料複製

延伸閱讀

返回：案例研究 返回：模組五：用 C 擴展 Python