C-Extension 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

4.1 ctypes 與 cffi：動態綁定

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

本章介紹如何使用 ctypes 和 cffi 動態載入和呼叫 C 函式庫。

本章目標

學完本章後，你將能夠：

理解 FFI（Foreign Function Interface）的概念
使用 ctypes 呼叫系統函式庫
使用 cffi 的 ABI 和 API 模式

【原理層】什麼是 FFI？

動態連結庫

現代作業系統使用動態連結庫（Shared Library）來共享程式碼：

1不同平台的動態連結庫：
2├── Linux:   .so  (Shared Object)
3├── macOS:   .dylib (Dynamic Library)
4└── Windows: .dll (Dynamic Link Library)
5
6優點：
7- 節省記憶體（多個程式共享同一份）
8- 更新方便（不需重新編譯主程式）
9- 模組化設計

FFI 的概念

FFI（Foreign Function Interface）是一種讓程式語言呼叫其他語言函式的機制：

1Python 程式
2    │
3    ↓ FFI
4┌───────────────┐
5│  C 函式庫     │
6│  - libc.so    │
7│  - libm.so    │
8│  - 自訂 .so   │
9└───────────────┘

ctypes vs cffi

特性	ctypes	cffi
來源	標準庫	第三方
設計	物件導向 API	C 語法描述
效能	較慢	較快（API 模式）
學習曲線	較平緩	需要 C 語法知識
PyPy 支援	有限	完整

【設計層】ctypes 基礎

載入動態連結庫

 1import ctypes
 2import ctypes.util
 3
 4# 方法 1：直接載入
 5# Linux/macOS
 6libc = ctypes.CDLL("libc.so.6")  # Linux
 7libc = ctypes.CDLL("libc.dylib")  # macOS
 8
 9# Windows
10msvcrt = ctypes.CDLL("msvcrt")
11
12# 方法 2：使用 find_library（推薦，跨平台）
13from ctypes.util import find_library
14
15libc_path = find_library("c")
16print(f"libc 路徑: {libc_path}")
17libc = ctypes.CDLL(libc_path)
18
19# 方法 3：載入自訂函式庫
20mylib = ctypes.CDLL("./mylib.so")

C 型別對應

 1import ctypes
 2
 3# 基本型別對應
 4"""
 5C 型別           ctypes 型別        Python 型別
 6─────────────────────────────────────────────────
 7char             c_char            bytes (長度 1)
 8wchar_t          c_wchar           str (長度 1)
 9char *           c_char_p          bytes 或 None
10wchar_t *        c_wchar_p         str 或 None
11int              c_int             int
12unsigned int     c_uint            int
13long             c_long            int
14unsigned long    c_ulong           int
15long long        c_longlong        int
16float            c_float           float
17double           c_double          float
18void *           c_void_p          int 或 None
19"""
20
21# 範例：設定函式的參數和回傳型別
22libc = ctypes.CDLL(ctypes.util.find_library("c"))
23
24# strlen 函式：size_t strlen(const char *s)
25libc.strlen.argtypes = [ctypes.c_char_p]
26libc.strlen.restype = ctypes.c_size_t
27
28result = libc.strlen(b"Hello, World!")
29print(f"字串長度: {result}")  # 13

指標操作

 1import ctypes
 2
 3# 建立指標
 4x = ctypes.c_int(42)
 5ptr = ctypes.pointer(x)  # 指向 x 的指標
 6
 7print(f"值: {ptr.contents.value}")  # 42
 8
 9# 修改值
10ptr.contents.value = 100
11print(f"新值: {x.value}")  # 100
12
13# 指標型別
14IntPtr = ctypes.POINTER(ctypes.c_int)
15
16# 空指標
17null_ptr = IntPtr()
18print(f"是否為空: {not null_ptr}")  # True
19
20# byref：輕量級的指標傳遞（不建立完整指標物件）
21def example_with_byref():
22    value = ctypes.c_int(0)
23    # 假設某函式需要 int* 參數
24    # some_func(ctypes.byref(value))
25    return value.value

結構體與聯合

 1import ctypes
 2
 3# 定義結構體
 4class Point(ctypes.Structure):
 5    _fields_ = [
 6        ("x", ctypes.c_double),
 7        ("y", ctypes.c_double),
 8    ]
 9
10# 使用結構體
11p = Point(3.0, 4.0)
12print(f"Point: ({p.x}, {p.y})")
13
14# 巢狀結構體
15class Rectangle(ctypes.Structure):
16    _fields_ = [
17        ("top_left", Point),
18        ("bottom_right", Point),
19    ]
20
21rect = Rectangle(Point(0, 0), Point(10, 10))
22print(f"矩形: ({rect.top_left.x}, {rect.top_left.y}) -> "
23      f"({rect.bottom_right.x}, {rect.bottom_right.y})")
24
25# 陣列
26IntArray5 = ctypes.c_int * 5
27arr = IntArray5(1, 2, 3, 4, 5)
28print(f"陣列: {list(arr)}")
29
30# 聯合（Union）
31class IntOrFloat(ctypes.Union):
32    _fields_ = [
33        ("i", ctypes.c_int),
34        ("f", ctypes.c_float),
35    ]
36
37u = IntOrFloat()
38u.f = 3.14
39print(f"作為 float: {u.f}")
40print(f"作為 int: {u.i}")  # 記憶體的整數解釋

【實作層】ctypes 實戰

呼叫系統 API

 1import ctypes
 2import ctypes.util
 3import os
 4
 5# 取得 process ID（跨平台範例）
 6if os.name == 'posix':
 7    libc = ctypes.CDLL(ctypes.util.find_library("c"))
 8
 9    # pid_t getpid(void)
10    libc.getpid.restype = ctypes.c_int
11    pid = libc.getpid()
12    print(f"PID (ctypes): {pid}")
13    print(f"PID (os): {os.getpid()}")
14
15# 呼叫數學函式
16libm = ctypes.CDLL(ctypes.util.find_library("m"))
17
18# double sqrt(double x)
19libm.sqrt.argtypes = [ctypes.c_double]
20libm.sqrt.restype = ctypes.c_double
21
22result = libm.sqrt(2.0)
23print(f"sqrt(2) = {result}")

回呼函式

 1import ctypes
 2
 3# 定義回呼函式型別
 4# qsort 的比較函式：int (*compar)(const void *, const void *)
 5CMPFUNC = ctypes.CFUNCTYPE(
 6    ctypes.c_int,      # 回傳型別
 7    ctypes.c_void_p,   # 參數 1
 8    ctypes.c_void_p    # 參數 2
 9)
10
11def py_compare(a, b):
12    """Python 比較函式"""
13    # 將 void* 轉換為 int*
14    a_val = ctypes.cast(a, ctypes.POINTER(ctypes.c_int)).contents.value
15    b_val = ctypes.cast(b, ctypes.POINTER(ctypes.c_int)).contents.value
16    return a_val - b_val
17
18# 包裝為 C 回呼
19c_compare = CMPFUNC(py_compare)
20
21# 使用 qsort
22libc = ctypes.CDLL(ctypes.util.find_library("c"))
23
24# void qsort(void *base, size_t nmemb, size_t size,
25#            int (*compar)(const void *, const void *))
26IntArray = ctypes.c_int * 5
27arr = IntArray(5, 2, 8, 1, 9)
28
29print(f"排序前: {list(arr)}")
30
31libc.qsort(
32    arr,                          # base
33    len(arr),                     # nmemb
34    ctypes.sizeof(ctypes.c_int),  # size
35    c_compare                     # compar
36)
37
38print(f"排序後: {list(arr)}")

處理字串

 1import ctypes
 2
 3libc = ctypes.CDLL(ctypes.util.find_library("c"))
 4
 5# 注意：Python 3 的字串是 unicode
 6# ctypes 的 c_char_p 需要 bytes
 7
 8# 錯誤示範
 9# libc.strlen("Hello")  # TypeError
10
11# 正確做法
12result = libc.strlen(b"Hello")
13print(f"長度: {result}")
14
15# 建立可修改的字串緩衝區
16buffer = ctypes.create_string_buffer(b"Hello", 20)
17print(f"原始: {buffer.value}")
18
19# strcpy：複製字串
20libc.strcpy(buffer, b"World")
21print(f"複製後: {buffer.value}")
22
23# 處理 wchar_t（寬字元）
24# wchar_t *wcscat(wchar_t *dest, const wchar_t *src)
25if hasattr(libc, 'wcscat'):
26    wbuffer = ctypes.create_unicode_buffer("Hello, ", 50)
27    libc.wcscat(wbuffer, "World!")
28    print(f"寬字串: {wbuffer.value}")

【設計層】cffi 基礎

安裝與基本使用

1pip install cffi

 1from cffi import FFI
 2
 3ffi = FFI()
 4
 5# ABI 模式：動態載入，不需編譯
 6ffi.cdef("""
 7    int strlen(const char *s);
 8    double sqrt(double x);
 9""")
10
11# 載入函式庫
12libc = ffi.dlopen(None)  # None = 載入預設 C 函式庫
13
14# 呼叫函式
15result = libc.strlen(b"Hello, cffi!")
16print(f"strlen: {result}")

ABI 模式 vs API 模式

 1from cffi import FFI
 2
 3# ========== ABI 模式 ==========
 4# 優點：簡單，不需編譯器
 5# 缺點：效能較差，型別檢查較弱
 6
 7ffi_abi = FFI()
 8ffi_abi.cdef("""
 9    double sin(double x);
10    double cos(double x);
11""")
12libm = ffi_abi.dlopen("m")  # 或 None 使用預設
13
14import math
15print(f"sin(π/2) = {libm.sin(math.pi / 2)}")
16
17# ========== API 模式 ==========
18# 優點：效能好，完整型別檢查
19# 缺點：需要編譯器
20
21ffi_api = FFI()
22ffi_api.cdef("""
23    double compute_something(double x, double y);
24""")
25
26# 設定原始碼（會編譯成擴展模組）
27ffi_api.set_source("_example",
28    """
29    double compute_something(double x, double y) {
30        return x * x + y * y;
31    }
32    """,
33)
34
35# 編譯（通常在 setup.py 中執行）
36# ffi_api.compile()

cffi 的型別系統

 1from cffi import FFI
 2
 3ffi = FFI()
 4
 5# 定義結構體
 6ffi.cdef("""
 7    typedef struct {
 8        double x;
 9        double y;
10    } Point;
11
12    typedef struct {
13        Point center;
14        double radius;
15    } Circle;
16""")
17
18# 建立結構體實例
19point = ffi.new("Point *")
20point.x = 3.0
21point.y = 4.0
22
23# 或者一次初始化
24point2 = ffi.new("Point *", {'x': 1.0, 'y': 2.0})
25
26# 巢狀結構體
27circle = ffi.new("Circle *", {
28    'center': {'x': 0.0, 'y': 0.0},
29    'radius': 5.0
30})
31
32print(f"圓心: ({circle.center.x}, {circle.center.y})")
33print(f"半徑: {circle.radius}")
34
35# 陣列
36arr = ffi.new("int[5]", [1, 2, 3, 4, 5])
37print(f"陣列: {list(arr)}")
38
39# 動態大小陣列
40n = 10
41dynamic_arr = ffi.new(f"double[{n}]")
42for i in range(n):
43    dynamic_arr[i] = i * 0.5

【實作層】cffi 實戰

包裝簡單的 C 函式庫

假設我們有一個簡單的 C 函式庫 mathutil.c：

 1// mathutil.c
 2#include 
 3
 4double vector_length(double x, double y, double z) {
 5    return sqrt(x*x + y*y + z*z);
 6}
 7
 8int fibonacci(int n) {
 9    if (n <= 1) return n;
10    int a = 0, b = 1;
11    for (int i = 2; i <= n; i++) {
12        int tmp = a + b;
13        a = b;
14        b = tmp;
15    }
16    return b;
17}

使用 cffi 包裝：

 1# build_mathutil.py
 2from cffi import FFI
 3
 4ffi = FFI()
 5
 6# 宣告要使用的函式
 7ffi.cdef("""
 8    double vector_length(double x, double y, double z);
 9    int fibonacci(int n);
10""")
11
12# 設定原始碼
13ffi.set_source(
14    "_mathutil",  # 模組名稱
15    """
16    #include 
17
18    double vector_length(double x, double y, double z) {
19        return sqrt(x*x + y*y + z*z);
20    }
21
22    int fibonacci(int n) {
23        if (n <= 1) return n;
24        int a = 0, b = 1;
25        for (int i = 2; i <= n; i++) {
26            int tmp = a + b;
27            a = b;
28            b = tmp;
29        }
30        return b;
31    }
32    """,
33    libraries=['m'],  # 連結數學函式庫
34)
35
36if __name__ == "__main__":
37    ffi.compile(verbose=True)

1# 使用編譯後的模組
2from _mathutil import ffi, lib
3
4length = lib.vector_length(1.0, 2.0, 2.0)
5print(f"向量長度: {length}")  # 3.0
6
7fib_10 = lib.fibonacci(10)
8print(f"fibonacci(10): {fib_10}")  # 55

回呼函式

 1from cffi import FFI
 2
 3ffi = FFI()
 4
 5ffi.cdef("""
 6    typedef int (*compare_func)(int, int);
 7    void custom_sort(int *arr, int size, compare_func cmp);
 8""")
 9
10ffi.set_source("_sort_example",
11    """
12    typedef int (*compare_func)(int, int);
13
14    void custom_sort(int *arr, int size, compare_func cmp) {
15        // 簡單的冒泡排序
16        for (int i = 0; i < size - 1; i++) {
17            for (int j = 0; j < size - i - 1; j++) {
18                if (cmp(arr[j], arr[j+1]) > 0) {
19                    int tmp = arr[j];
20                    arr[j] = arr[j+1];
21                    arr[j+1] = tmp;
22                }
23            }
24        }
25    }
26    """
27)
28
29# 編譯後使用
30# from _sort_example import ffi, lib
31
32# @ffi.callback("int(int, int)")
33# def py_compare(a, b):
34#     return a - b
35
36# arr = ffi.new("int[5]", [5, 2, 8, 1, 9])
37# lib.custom_sort(arr, 5, py_compare)
38# print(list(arr))  # [1, 2, 5, 8, 9]

記憶體管理

 1from cffi import FFI
 2
 3ffi = FFI()
 4
 5# ffi.new() 分配的記憶體會自動管理
 6data = ffi.new("int[100]")  # 自動回收
 7
 8# 需要手動管理的情況
 9ffi.cdef("""
10    void *malloc(size_t size);
11    void free(void *ptr);
12""")
13
14libc = ffi.dlopen(None)
15
16# 手動分配
17ptr = libc.malloc(100)
18if ptr != ffi.NULL:
19    # 使用記憶體...
20
21    # 必須手動釋放
22    libc.free(ptr)
23
24# 使用 ffi.gc() 自動管理外部分配的記憶體
25def auto_managed_alloc(size):
26    ptr = libc.malloc(size)
27    if ptr == ffi.NULL:
28        raise MemoryError()
29    # 設定 finalizer，當 Python 物件被回收時自動呼叫
30    return ffi.gc(ptr, libc.free)
31
32managed_ptr = auto_managed_alloc(100)
33# 不需要手動 free，Python GC 會處理

【選擇指南】ctypes vs cffi

決策流程

 1需要呼叫 C 函式庫？
 2│
 3├── 只需要簡單呼叫系統 API
 4│   └── ctypes（標準庫，不需額外安裝）
 5│
 6├── 需要包裝複雜的 C 函式庫
 7│   └── cffi API 模式（更好的型別檢查）
 8│
 9├── 在 PyPy 上執行
10│   └── cffi（PyPy 原生支援）
11│
12└── 效能要求高
13    └── cffi API 模式 或 考慮 Cython/pybind11

效能比較

 1import timeit
 2
 3# 測試函式呼叫開銷
 4setup_ctypes = """
 5import ctypes
 6import ctypes.util
 7libm = ctypes.CDLL(ctypes.util.find_library("m"))
 8libm.sqrt.argtypes = [ctypes.c_double]
 9libm.sqrt.restype = ctypes.c_double
10"""
11
12setup_cffi = """
13from cffi import FFI
14ffi = FFI()
15ffi.cdef("double sqrt(double x);")
16libm = ffi.dlopen("m")
17"""
18
19# 結果（僅供參考，實際數據取決於環境）
20# ctypes: ~0.3 μs per call
21# cffi ABI: ~0.2 μs per call
22# cffi API: ~0.05 μs per call
23# 原生 Python math.sqrt: ~0.02 μs per call

常見錯誤與除錯

 1import ctypes
 2
 3# 錯誤 1：忘記設定 argtypes/restype
 4libc = ctypes.CDLL(ctypes.util.find_library("c"))
 5# result = libc.strlen("hello")  # 可能 crash 或回傳錯誤值
 6
 7# 正確做法
 8libc.strlen.argtypes = [ctypes.c_char_p]
 9libc.strlen.restype = ctypes.c_size_t
10result = libc.strlen(b"hello")
11
12# 錯誤 2：傳遞 Python str 而非 bytes
13# libc.strlen("hello")  # TypeError
14
15# 錯誤 3：回呼函式被垃圾回收
16CALLBACK = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_int)
17
18def bad_example():
19    def callback(x):
20        return x * 2
21
22    c_callback = CALLBACK(callback)
23    # 如果這裡把 c_callback 傳給 C，然後函式結束
24    # c_callback 可能被回收，C 呼叫時會 crash
25    return c_callback  # 必須保持參考
26
27# 正確做法：保持回呼的參考
28_callbacks = []  # 全域列表保持參考
29
30def safe_example():
31    def callback(x):
32        return x * 2
33
34    c_callback = CALLBACK(callback)
35    _callbacks.append(c_callback)  # 保持參考
36    return c_callback

思考題

為什麼 cffi 的 API 模式比 ABI 模式快？這與 Python 的執行模型有什麼關係？
在什麼情況下，使用 ctypes/cffi 會比重新用 Python 實現更好？
如何安全地處理 C 函式庫中的記憶體分配？

實作練習

使用 ctypes 包裝 time.h 中的 time() 和 localtime() 函式
使用 cffi 包裝一個簡單的數學函式庫，提供矩陣乘法功能
比較 ctypes、cffi ABI 模式、cffi API 模式在大量函式呼叫時的效能差異

延伸閱讀

下一章：Cython

案例：使用 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 (最慢)	需要執行外部命令時

結論：

4.2 Cython：Python 語法的 C 速度

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

本章介紹 Cython，一種 Python 的超集語言，可以編譯成 C 程式碼。

本章目標

學完本章後，你將能夠：

理解 Cython 的編譯流程
使用型別宣告加速程式碼
使用 Cython 包裝 C 函式庫

【原理層】Cython 是什麼？

Python 的超集

Cython 是一種程式語言，它是 Python 的超集：

1合法的 Python 程式碼 → 合法的 Cython 程式碼
2                    → 但 Cython 可以加入更多語法
3
4Cython 特有語法：
5- cdef：宣告 C 變數或函式
6- cpdef：同時暴露給 Python 和 C
7- cimport：匯入 .pxd 檔案
8- nogil：標記不需要 GIL 的區塊

編譯流程

 1.pyx (Cython 原始碼)
 2    │
 3    ↓ Cython 編譯器
 4.c (C 原始碼)
 5    │
 6    ↓ C 編譯器 (gcc, clang, MSVC)
 7.so / .pyd (Python 擴展模組)
 8    │
 9    ↓ import
10Python 程式

為什麼 Cython 比 Python 快？

 1# 純 Python：每次操作都是物件操作
 2def python_sum(n):
 3    total = 0           # 建立 int 物件
 4    for i in range(n):  # 建立 range 物件，迭代器
 5        total += i      # 呼叫 __add__，建立新物件
 6    return total
 7
 8# Cython：可以使用原生 C 型別
 9def cython_sum(int n):
10    cdef int total = 0  # C 的 int，不是 Python 物件
11    cdef int i
12    for i in range(n):  # 編譯成 C 的 for 迴圈
13        total += i      # 單一 CPU 指令
14    return total

效能差異的來源：

操作	Python	Cython (有型別)
變數存取	dict 查找	直接記憶體存取
整數加法	物件方法呼叫	CPU 指令
迴圈	迭代器協議	C for 迴圈
函式呼叫	建立 frame 物件	C 函式呼叫

【設計層】Cython 基礎語法

安裝與設定

1pip install cython
2
3# 檢查版本
4python -c "import cython; print(cython.__version__)"

第一個 Cython 模組

建立 example.pyx：

 1# example.pyx
 2
 3def say_hello(name):
 4    """純 Python 函式，也是合法的 Cython"""
 5    print(f"Hello, {name}!")
 6
 7def compute_sum(int n):
 8    """加入型別宣告的函式"""
 9    cdef int i
10    cdef long total = 0
11
12    for i in range(n):
13        total += i
14
15    return total

建立 setup.py：

1# setup.py
2from setuptools import setup
3from Cython.Build import cythonize
4
5setup(
6    ext_modules=cythonize("example.pyx"),
7)

編譯與使用：

1# 編譯
2python setup.py build_ext --inplace
3
4# 使用
5python -c "import example; example.say_hello('Cython')"

變數宣告

 1# 型別宣告語法
 2
 3# cdef：宣告 C 變數（只在 Cython 內部可見）
 4cdef int x = 10
 5cdef double y = 3.14
 6cdef char* s = "hello"
 7
 8# 多個變數
 9cdef:
10    int a, b, c
11    double d = 0.0
12    list my_list = []
13
14# 型別推斷（Python 3 風格）
15cdef int x = 10      # 明確宣告
16x: cython.int = 10   # 註解風格（Pure Python 模式）

函式類型

 1# def：Python 函式，可從 Python 呼叫
 2def python_func(x, y):
 3    return x + y
 4
 5# cdef：C 函式，只能從 Cython 呼叫，最快
 6cdef int c_func(int x, int y):
 7    return x + y
 8
 9# cpdef：同時產生 Python 和 C 版本
10cpdef int hybrid_func(int x, int y):
11    return x + y
12
13# 使用情境
14def api_func(int n):
15    """公開 API"""
16    cdef int i
17    cdef int total = 0
18    for i in range(n):
19        total = _helper(total, i)  # 呼叫 cdef 函式
20    return total
21
22cdef int _helper(int a, int b):
23    """內部輔助函式，不暴露給 Python"""
24    return a + b

型別轉換

 1# 隱式轉換
 2cdef int i = 10
 3cdef double d = i  # int → double，自動轉換
 4
 5# 明確轉換
 6cdef double x = 3.14
 7cdef int y = <int>x  # 截斷為 3
 8
 9# Python 物件與 C 型別
10def convert_example(obj):
11    cdef int c_int
12
13    # Python int → C int
14    c_int = <int>obj  # 可能 overflow
15
16    # 安全轉換
17    if isinstance(obj, int) and -2147483648 <= obj <= 2147483647:
18        c_int = obj
19
20    return c_int

【實作層】Cython 優化技巧

使用 cython -a 分析

1# 產生帶註解的 HTML 報告
2cython -a example.pyx

1HTML 報告的顏色含義：
2├── 白色：純 C 程式碼，最快
3├── 淺黃色：少量 Python API 呼叫
4├── 深黃色：較多 Python 互動
5└── 橙色/紅色：大量 Python 操作，需要優化

常見優化模式

 1# 優化前：大量黃色
 2def slow_function(data):
 3    total = 0
 4    for item in data:
 5        total += item * item
 6    return total
 7
 8# 優化後：大部分白色
 9def fast_function(double[:] data):  # 型別化記憶體視圖
10    cdef:
11        int i
12        int n = data.shape[0]
13        double total = 0.0
14
15    for i in range(n):
16        total += data[i] * data[i]
17
18    return total

停用邊界檢查

 1# 預設：有邊界檢查（安全但較慢）
 2cdef double[:] arr = some_array
 3
 4# 停用檢查（確定安全時使用）
 5cimport cython
 6
 7@cython.boundscheck(False)  # 停用邊界檢查
 8@cython.wraparound(False)   # 停用負數索引
 9def optimized_sum(double[:] arr):
10    cdef int i
11    cdef int n = arr.shape[0]
12    cdef double total = 0.0
13
14    for i in range(n):
15        total += arr[i]
16
17    return total
18
19# 或者使用全域設定
20# cython: boundscheck=False
21# cython: wraparound=False

釋放 GIL

 1from cython.parallel import prange
 2
 3# nogil：標記不需要 GIL 的區塊
 4cdef double compute_heavy(double x) nogil:
 5    """純 C 計算，不涉及 Python 物件"""
 6    cdef double result = 0.0
 7    cdef int i
 8    for i in range(1000):
 9        result += x * i
10    return result
11
12def parallel_compute(double[:] data):
13    cdef int i
14    cdef int n = data.shape[0]
15    cdef double[:] results = np.zeros(n)
16
17    # 使用 OpenMP 平行化
18    with nogil:
19        for i in prange(n):
20            results[i] = compute_heavy(data[i])
21
22    return np.asarray(results)

【實作層】與 NumPy 整合

記憶體視圖

 1import numpy as np
 2cimport numpy as cnp
 3
 4# 型別化記憶體視圖（推薦）
 5def process_array(double[:, :] arr):
 6    """處理 2D double 陣列"""
 7    cdef int i, j
 8    cdef int rows = arr.shape[0]
 9    cdef int cols = arr.shape[1]
10    cdef double total = 0.0
11
12    for i in range(rows):
13        for j in range(cols):
14            total += arr[i, j]
15
16    return total
17
18# 使用
19# import numpy as np
20# data = np.random.rand(100, 100)
21# result = process_array(data)

矩陣運算範例

 1# matrix_ops.pyx
 2import numpy as np
 3cimport numpy as cnp
 4cimport cython
 5
 6@cython.boundscheck(False)
 7@cython.wraparound(False)
 8def matrix_multiply(double[:, :] A, double[:, :] B):
 9    """矩陣乘法 C = A @ B"""
10    cdef int i, j, k
11    cdef int m = A.shape[0]
12    cdef int n = A.shape[1]
13    cdef int p = B.shape[1]
14
15    if B.shape[0] != n:
16        raise ValueError("矩陣維度不匹配")
17
18    cdef double[:, :] C = np.zeros((m, p), dtype=np.float64)
19
20    for i in range(m):
21        for j in range(p):
22            for k in range(n):
23                C[i, j] += A[i, k] * B[k, j]
24
25    return np.asarray(C)
26
27# 注意：這只是教學範例
28# 實際應用應使用 numpy.dot 或 BLAS

效能比較

 1import numpy as np
 2import timeit
 3
 4# 假設已編譯 matrix_ops
 5# from matrix_ops import matrix_multiply
 6
 7def benchmark():
 8    A = np.random.rand(100, 100)
 9    B = np.random.rand(100, 100)
10
11    # NumPy（使用 BLAS）
12    t1 = timeit.timeit(lambda: A @ B, number=100)
13
14    # Cython（我們的實現）
15    # t2 = timeit.timeit(lambda: matrix_multiply(A, B), number=100)
16
17    # 純 Python
18    def py_matmul(A, B):
19        m, n = A.shape
20        p = B.shape[1]
21        C = [[0.0] * p for _ in range(m)]
22        for i in range(m):
23            for j in range(p):
24                for k in range(n):
25                    C[i][j] += A[i, k] * B[k, j]
26        return C
27
28    t3 = timeit.timeit(lambda: py_matmul(A, B), number=1)
29
30    print(f"NumPy (BLAS):  {t1:.4f}s")
31    # print(f"Cython:        {t2:.4f}s")
32    print(f"Pure Python:   {t3:.4f}s (x1)")

【實作層】包裝 C 函式庫

宣告外部函式

 1# 宣告 C 標準函式庫函式
 2from libc.math cimport sqrt, sin, cos, pow
 3from libc.stdlib cimport malloc, free
 4from libc.string cimport memcpy, strlen
 5
 6def compute_distance(double x1, double y1, double x2, double y2):
 7    """使用 C 的 sqrt"""
 8    cdef double dx = x2 - x1
 9    cdef double dy = y2 - y1
10    return sqrt(dx * dx + dy * dy)

宣告自訂 C 函式庫

假設有 C 標頭檔 mylib.h：

1// mylib.h
2typedef struct {
3    double x, y, z;
4} Vector3D;
5
6double vector_length(Vector3D* v);
7Vector3D vector_add(Vector3D* a, Vector3D* b);

建立 Cython 宣告檔 mylib.pxd：

1# mylib.pxd
2cdef extern from "mylib.h":
3    ctypedef struct Vector3D:
4        double x
5        double y
6        double z
7
8    double vector_length(Vector3D* v)
9    Vector3D vector_add(Vector3D* a, Vector3D* b)

使用宣告：

 1# mylib_wrapper.pyx
 2from mylib cimport Vector3D, vector_length, vector_add
 3
 4cdef class PyVector3D:
 5    """Python 包裝類別"""
 6    cdef Vector3D _vec
 7
 8    def __init__(self, double x, double y, double z):
 9        self._vec.x = x
10        self._vec.y = y
11        self._vec.z = z
12
13    @property
14    def x(self):
15        return self._vec.x
16
17    @property
18    def y(self):
19        return self._vec.y
20
21    @property
22    def z(self):
23        return self._vec.z
24
25    def length(self):
26        return vector_length(&self._vec)
27
28    def __add__(self, PyVector3D other):
29        cdef Vector3D result = vector_add(&self._vec, &other._vec)
30        return PyVector3D(result.x, result.y, result.z)
31
32    def __repr__(self):
33        return f"Vector3D({self.x}, {self.y}, {self.z})"

記憶體管理

 1from libc.stdlib cimport malloc, free
 2
 3cdef class DynamicArray:
 4    """管理動態分配記憶體的範例"""
 5    cdef double* data
 6    cdef int size
 7
 8    def __cinit__(self, int size):
 9        """C 層級初始化，保證在 __init__ 之前執行"""
10        self.size = size
11        self.data = <double*>malloc(size * sizeof(double))
12        if self.data == NULL:
13            raise MemoryError("無法分配記憶體")
14
15    def __dealloc__(self):
16        """C 層級解構，保證釋放記憶體"""
17        if self.data != NULL:
18            free(self.data)
19
20    def __init__(self, int size):
21        """Python 層級初始化"""
22        cdef int i
23        for i in range(self.size):
24            self.data[i] = 0.0
25
26    def __getitem__(self, int index):
27        if index < 0 or index >= self.size:
28            raise IndexError("索引超出範圍")
29        return self.data[index]
30
31    def __setitem__(self, int index, double value):
32        if index < 0 or index >= self.size:
33            raise IndexError("索引超出範圍")
34        self.data[index] = value
35
36    def __len__(self):
37        return self.size

【進階】Pure Python 模式

使用型別註解

從 Cython 3.0 開始，支援純 Python 語法：

 1# pure_example.py（純 Python 檔案）
 2import cython
 3
 4@cython.cfunc
 5def c_function(x: cython.int, y: cython.int) -> cython.int:
 6    """等同於 cdef int c_function(int x, int y)"""
 7    return x + y
 8
 9@cython.ccall
10def hybrid_function(x: cython.int) -> cython.int:
11    """等同於 cpdef int hybrid_function(int x)"""
12    return c_function(x, x)
13
14def public_api(n: cython.int) -> cython.long:
15    """普通 Python 函式，但有型別最佳化"""
16    total: cython.long = 0
17    i: cython.int
18
19    for i in range(n):
20        total += hybrid_function(i)
21
22    return total

優點

1Pure Python 模式的好處：
21. 不需要 .pyx 檔案，直接用 .py
32. IDE 支援更好（型別提示）
43. 可以同時作為 Python 和 Cython 使用
54. 測試更容易（不需編譯就能跑 Python）

【建構】現代化建構方式

使用 pyproject.toml

 1# pyproject.toml
 2[build-system]
 3requires = ["setuptools>=61.0", "cython>=3.0"]
 4build-backend = "setuptools.build_meta"
 5
 6[project]
 7name = "my-cython-package"
 8version = "0.1.0"
 9
10[tool.setuptools]
11ext-modules = [
12    {name = "my_module", sources = ["src/my_module.pyx"]}
13]

使用 meson-python

1# pyproject.toml
2[build-system]
3requires = ["meson-python", "cython"]
4build-backend = "mesonpy"
5
6[project]
7name = "my-cython-package"
8version = "0.1.0"

 1# meson.build
 2project('my-cython-package', 'cython')
 3
 4py = import('python').find_installation()
 5
 6py.extension_module(
 7    'my_module',
 8    'src/my_module.pyx',
 9    install: true
10)

思考題

為什麼 cdef 函式比 def 函式快？從呼叫協議的角度解釋。
在什麼情況下，Cython 的效能提升最明顯？什麼情況下提升有限？
如何決定哪些函式應該用 cdef、cpdef 還是 def？

實作練習

將入門系列效能章節的 is_prime 函式用 Cython 改寫，比較效能差異
使用 Cython 實現一個簡單的 LRU Cache，與 functools.lru_cache 比較效能
包裝一個簡單的 C 函式庫（如 zlib）並在 Python 中使用

延伸閱讀

上一章：ctypes 與 cffi 下一章：pybind11

案例：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

4.3 pybind11：現代 C++ 綁定

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

本章介紹 pybind11，一個輕量級的 header-only C++ 函式庫，用於建立 Python 綁定。

本章目標

學完本章後，你將能夠：

理解 pybind11 的設計哲學
建立函式和類別綁定
處理 NumPy 陣列

【原理層】pybind11 的設計哲學

為什麼需要 pybind11？

傳統的 Python C API 非常繁瑣：

 1// 傳統 Python C API
 2static PyObject* add(PyObject* self, PyObject* args) {
 3    int a, b;
 4    if (!PyArg_ParseTuple(args, "ii", &a, &b)) {
 5        return NULL;
 6    }
 7    return PyLong_FromLong(a + b);
 8}
 9
10static PyMethodDef methods[] = {
11    {"add", add, METH_VARARGS, "Add two integers"},
12    {NULL, NULL, 0, NULL}
13};
14
15static struct PyModuleDef module = {
16    PyModuleDef_HEAD_INIT,
17    "example",
18    NULL,
19    -1,
20    methods
21};
22
23PyMODINIT_FUNC PyInit_example(void) {
24    return PyModule_Create(&module);
25}

pybind11 讓這變得簡單：

 1// pybind11
 2#include 
 3
 4int add(int a, int b) {
 5    return a + b;
 6}
 7
 8PYBIND11_MODULE(example, m) {
 9    m.def("add", &add, "Add two integers");
10}

Header-only 設計

1pybind11 的特點：
2├── Header-only：不需要編譯函式庫
3├── C++11：使用現代 C++ 特性
4├── 自動型別轉換：Python ↔ C++ 型別
5├── 最小化模板程式碼
6└── 與 NumPy 無縫整合

型別轉換原理

1Python 呼叫 C++ 函式時：
2
3Python int  ──→  pybind11 type_caster  ──→  C++ int
4Python str  ──→  pybind11 type_caster  ──→  std::string
5Python list ──→  pybind11 type_caster  ──→  std::vector
6
7回傳時反向轉換

【設計層】開發環境設定

安裝 pybind11

 1# 方法 1：pip 安裝
 2pip install pybind11
 3
 4# 方法 2：conda 安裝
 5conda install -c conda-forge pybind11
 6
 7# 方法 3：系統套件管理器
 8# Ubuntu/Debian
 9sudo apt install pybind11-dev
10
11# macOS
12brew install pybind11

專案結構

1my_project/
2├── CMakeLists.txt        # CMake 建構檔
3├── pyproject.toml        # Python 打包設定
4├── src/
5│   └── example.cpp       # C++ 原始碼
6└── tests/
7    └── test_example.py   # 測試

最小 CMakeLists.txt

1cmake_minimum_required(VERSION 3.15)
2project(example)
3
4# 找到 pybind11
5find_package(pybind11 REQUIRED)
6
7# 建立 Python 模組
8pybind11_add_module(example src/example.cpp)

使用 setup.py（簡單專案）

 1# setup.py
 2from setuptools import setup
 3from pybind11.setup_helpers import Pybind11Extension, build_ext
 4
 5ext_modules = [
 6    Pybind11Extension(
 7        "example",
 8        ["src/example.cpp"],
 9    ),
10]
11
12setup(
13    name="example",
14    ext_modules=ext_modules,
15    cmdclass={"build_ext": build_ext},
16)

【實作層】基礎綁定

函式綁定

 1#include 
 2#include 
 3
 4namespace py = pybind11;
 5
 6// 簡單函式
 7int add(int a, int b) {
 8    return a + b;
 9}
10
11// 帶預設參數
12double divide(double a, double b = 1.0) {
13    return a / b;
14}
15
16// 多載函式
17int multiply(int a, int b) { return a * b; }
18double multiply(double a, double b) { return a * b; }
19
20// 接受字串
21std::string greet(const std::string& name) {
22    return "Hello, " + name + "!";
23}
24
25PYBIND11_MODULE(example, m) {
26    m.doc() = "Example module";
27
28    // 基本綁定
29    m.def("add", &add, "Add two integers");
30
31    // 帶預設參數
32    m.def("divide", &divide, "Divide two numbers",
33          py::arg("a"), py::arg("b") = 1.0);
34
35    // 處理多載：需要明確指定簽名
36    m.def("multiply", py::overload_cast<int, int>(&multiply));
37    m.def("multiply", py::overload_cast<double, double>(&multiply));
38
39    // 字串函式
40    m.def("greet", &greet, "Greet someone");
41}

Python 使用：

1import example
2
3print(example.add(1, 2))           # 3
4print(example.divide(10, 2))       # 5.0
5print(example.divide(10))          # 10.0（使用預設值）
6print(example.multiply(3, 4))      # 12
7print(example.multiply(1.5, 2.0))  # 3.0
8print(example.greet("pybind11"))   # Hello, pybind11!

類別綁定

 1#include 
 2#include 
 3
 4namespace py = pybind11;
 5
 6class Pet {
 7public:
 8    Pet(const std::string& name, int age)
 9        : name_(name), age_(age) {}
10
11    // getter/setter
12    const std::string& get_name() const { return name_; }
13    void set_name(const std::string& name) { name_ = name; }
14
15    int get_age() const { return age_; }
16    void set_age(int age) { age_ = age; }
17
18    // 方法
19    std::string describe() const {
20        return name_ + " is " + std::to_string(age_) + " years old";
21    }
22
23private:
24    std::string name_;
25    int age_;
26};
27
28PYBIND11_MODULE(example, m) {
29    py::class_<Pet>(m, "Pet")
30        // 建構子
31        .def(py::init<const std::string&, int>())
32
33        // 屬性（getter/setter）
34        .def_property("name", &Pet::get_name, &Pet::set_name)
35        .def_property("age", &Pet::get_age, &Pet::set_age)
36
37        // 唯讀屬性
38        // .def_property_readonly("name", &Pet::get_name)
39
40        // 方法
41        .def("describe", &Pet::describe)
42
43        // __repr__
44        .def("__repr__", [](const Pet& p) {
45            return " + p.get_name() + "'>";
46        });
47}

繼承

 1#include 
 2#include 
 3
 4namespace py = pybind11;
 5
 6class Animal {
 7public:
 8    Animal(const std::string& name) : name_(name) {}
 9    virtual ~Animal() = default;
10
11    virtual std::string speak() const = 0;  // 純虛函式
12    const std::string& name() const { return name_; }
13
14protected:
15    std::string name_;
16};
17
18class Dog : public Animal {
19public:
20    Dog(const std::string& name) : Animal(name) {}
21    std::string speak() const override { return "Woof!"; }
22};
23
24class Cat : public Animal {
25public:
26    Cat(const std::string& name) : Animal(name) {}
27    std::string speak() const override { return "Meow!"; }
28};
29
30// 用於在 Python 中繼承 C++ 類別
31class PyAnimal : public Animal {
32public:
33    using Animal::Animal;
34
35    std::string speak() const override {
36        PYBIND11_OVERRIDE_PURE(std::string, Animal, speak);
37    }
38};
39
40PYBIND11_MODULE(example, m) {
41    py::class_<Animal, PyAnimal>(m, "Animal")
42        .def(py::init<const std::string&>())
43        .def("speak", &Animal::speak)
44        .def_property_readonly("name", &Animal::name);
45
46    py::class_<Dog, Animal>(m, "Dog")
47        .def(py::init<const std::string&>());
48
49    py::class_<Cat, Animal>(m, "Cat")
50        .def(py::init<const std::string&>());
51}

【實作層】進階功能

STL 容器轉換

 1#include 
 2#include   // 必須包含！
 3#include 
 4#include 
 5#include 
 6
 7namespace py = pybind11;
 8
 9// 自動轉換 std::vector ↔ Python list
10std::vector<int> double_values(const std::vector<int>& input) {
11    std::vector<int> result;
12    result.reserve(input.size());
13    for (int x : input) {
14        result.push_back(x * 2);
15    }
16    return result;
17}
18
19// std::map ↔ Python dict
20std::map<std::string, int> count_chars(const std::string& s) {
21    std::map<std::string, int> counts;
22    for (char c : s) {
23        counts[std::string(1, c)]++;
24    }
25    return counts;
26}
27
28PYBIND11_MODULE(example, m) {
29    m.def("double_values", &double_values);
30    m.def("count_chars", &count_chars);
31}

NumPy 整合

 1#include 
 2#include   // NumPy 支援
 3#include 
 4
 5namespace py = pybind11;
 6
 7// 處理 NumPy 陣列
 8py::array_t<double> compute_sin(py::array_t<double> input) {
 9    // 取得輸入資訊
10    auto buf = input.request();
11
12    if (buf.ndim != 1) {
13        throw std::runtime_error("輸入必須是一維陣列");
14    }
15
16    // 建立輸出陣列
17    py::array_t<double> result(buf.size);
18    auto result_buf = result.request();
19
20    // 取得原始指標
21    double* in_ptr = static_cast<double*>(buf.ptr);
22    double* out_ptr = static_cast<double*>(result_buf.ptr);
23
24    // 計算
25    for (size_t i = 0; i < buf.size; i++) {
26        out_ptr[i] = std::sin(in_ptr[i]);
27    }
28
29    return result;
30}
31
32// 多維陣列
33py::array_t<double> matrix_add(
34    py::array_t<double, py::array::c_style | py::array::forcecast> a,
35    py::array_t<double, py::array::c_style | py::array::forcecast> b
36) {
37    auto buf_a = a.request();
38    auto buf_b = b.request();
39
40    if (buf_a.ndim != 2 || buf_b.ndim != 2) {
41        throw std::runtime_error("需要二維陣列");
42    }
43
44    if (buf_a.shape[0] != buf_b.shape[0] ||
45        buf_a.shape[1] != buf_b.shape[1]) {
46        throw std::runtime_error("陣列形狀必須相同");
47    }
48
49    size_t rows = buf_a.shape[0];
50    size_t cols = buf_a.shape[1];
51
52    py::array_t<double> result({rows, cols});
53    auto buf_r = result.request();
54
55    double* ptr_a = static_cast<double*>(buf_a.ptr);
56    double* ptr_b = static_cast<double*>(buf_b.ptr);
57    double* ptr_r = static_cast<double*>(buf_r.ptr);
58
59    for (size_t i = 0; i < rows * cols; i++) {
60        ptr_r[i] = ptr_a[i] + ptr_b[i];
61    }
62
63    return result;
64}
65
66PYBIND11_MODULE(example, m) {
67    m.def("compute_sin", &compute_sin, "Compute sin for each element");
68    m.def("matrix_add", &matrix_add, "Add two matrices");
69}

GIL 管理

 1#include 
 2#include 
 3#include 
 4
 5namespace py = pybind11;
 6
 7// 長時間 CPU 計算，應該釋放 GIL
 8double heavy_computation(int iterations) {
 9    // 釋放 GIL
10    py::gil_scoped_release release;
11
12    double result = 0.0;
13    for (int i = 0; i < iterations; i++) {
14        result += std::sin(i) * std::cos(i);
15    }
16
17    return result;
18    // GIL 自動重新獲取
19}
20
21// 回呼 Python 函式，需要 GIL
22void process_with_callback(py::function callback) {
23    for (int i = 0; i < 10; i++) {
24        // 如果在無 GIL 的上下文中，需要獲取
25        // py::gil_scoped_acquire acquire;
26
27        callback(i);
28    }
29}
30
31// 多執行緒範例
32std::vector<double> parallel_compute(int n_threads, int iterations) {
33    std::vector<double> results(n_threads);
34    std::vector<std::thread> threads;
35
36    {
37        // 釋放 GIL 讓執行緒可以並行
38        py::gil_scoped_release release;
39
40        for (int t = 0; t < n_threads; t++) {
41            threads.emplace_back([&results, t, iterations]() {
42                double sum = 0.0;
43                for (int i = 0; i < iterations; i++) {
44                    sum += std::sin(t + i);
45                }
46                results[t] = sum;
47            });
48        }
49
50        for (auto& thread : threads) {
51            thread.join();
52        }
53    }
54
55    return results;
56}
57
58PYBIND11_MODULE(example, m) {
59    m.def("heavy_computation", &heavy_computation);
60    m.def("process_with_callback", &process_with_callback);
61    m.def("parallel_compute", &parallel_compute);
62}

異常處理

 1#include 
 2#include 
 3
 4namespace py = pybind11;
 5
 6double safe_divide(double a, double b) {
 7    if (b == 0.0) {
 8        throw std::invalid_argument("除數不能為零");
 9    }
10    return a / b;
11}
12
13void custom_exception_example() {
14    // 拋出特定的 Python 異常
15    throw py::value_error("這是一個 ValueError");
16}
17
18PYBIND11_MODULE(example, m) {
19    // std::invalid_argument 自動轉換為 ValueError
20    m.def("safe_divide", &safe_divide);
21
22    m.def("custom_exception", &custom_exception_example);
23
24    // 註冊自訂異常
25    static py::exception<std::runtime_error> exc(m, "CustomError");
26    py::register_exception_translator([](std::exception_ptr p) {
27        try {
28            if (p) std::rethrow_exception(p);
29        } catch (const std::runtime_error& e) {
30            exc(e.what());
31        }
32    });
33}

【建構】現代化建構方式

scikit-build-core（推薦）

 1# pyproject.toml
 2[build-system]
 3requires = ["scikit-build-core>=0.5", "pybind11"]
 4build-backend = "scikit_build_core.build"
 5
 6[project]
 7name = "my-cpp-extension"
 8version = "0.1.0"
 9requires-python = ">=3.8"
10
11[tool.scikit-build]
12wheel.packages = ["src/my_package"]

1# CMakeLists.txt
2cmake_minimum_required(VERSION 3.15)
3project(my_cpp_extension LANGUAGES CXX)
4
5find_package(pybind11 CONFIG REQUIRED)
6
7pybind11_add_module(_core src/core.cpp)
8
9install(TARGETS _core DESTINATION .)

meson-python

1# pyproject.toml
2[build-system]
3requires = ["meson-python", "pybind11"]
4build-backend = "mesonpy"
5
6[project]
7name = "my-cpp-extension"
8version = "0.1.0"

 1# meson.build
 2project('my-cpp-extension', 'cpp',
 3  version: '0.1.0',
 4  default_options: ['cpp_std=c++17']
 5)
 6
 7pybind11 = dependency('pybind11')
 8py = import('python').find_installation(pure: false)
 9
10py.extension_module(
11  '_core',
12  'src/core.cpp',
13  dependencies: pybind11,
14  install: true
15)

【比較】pybind11 vs nanobind

nanobind 簡介

nanobind 是 pybind11 作者開發的下一代工具：

 1nanobind vs pybind11：
 2
 3nanobind:
 4├── 更小的二進位檔案（~3-5x 減少）
 5├── 更快的編譯時間
 6├── 需要 C++17
 7├── 更嚴格的型別檢查
 8└── 更好的 Free-threading 支援
 9
10pybind11:
11├── 更成熟、更多文件
12├── C++11 即可
13├── 更廣泛的社群支援
14└── 更多現有專案使用

選擇建議

 1選擇 pybind11：
 2- 需要支援舊編譯器（C++11）
 3- 需要豐富的文件和範例
 4- 現有專案已使用 pybind11
 5
 6選擇 nanobind：
 7- 新專案
 8- 追求最小二進位大小
 9- 需要更好的 Free-threading 支援
10- 可以使用 C++17

思考題

pybind11 如何實現 Python 和 C++ 之間的自動型別轉換？
什麼時候應該在 C++ 程式碼中釋放 GIL？有什麼風險？
為什麼 pybind11 使用 header-only 設計？這有什麼優缺點？

實作練習

使用 pybind11 包裝一個簡單的 C++ 類別（如二維向量），支援運算子重載
實現一個接受 NumPy 陣列的 C++ 函式，計算陣列的移動平均
比較 pybind11 和 Cython 在相同任務上的效能和程式碼複雜度

延伸閱讀

上一章：Cython 下一章：選擇指南

4.4 選擇指南與效能比較

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

本章比較各種 C 擴展工具，幫助你在不同場景下做出正確選擇。

本章目標

學完本章後，你將能夠：

根據專案需求選擇適合的工具
理解各工具的效能差異
評估維護成本與學習曲線

【總覽】C 擴展工具比較

工具定位

 1┌─────────────────────────────────────────────────────────────────┐
 2│                        C/C++ 擴展工具選擇                        │
 3├─────────────────────────────────────────────────────────────────┤
 4│                                                                 │
 5│   動態綁定（不需編譯）          靜態編譯                         │
 6│   ├── ctypes                   ├── Cython                      │
 7│   └── cffi (ABI)               ├── cffi (API)                  │
 8│                                ├── pybind11                    │
 9│                                └── nanobind                    │
10│                                                                 │
11├─────────────────────────────────────────────────────────────────┤
12│   適合 Python 背景              適合 C/C++ 背景                  │
13│   ├── ctypes                   ├── pybind11                    │
14│   ├── cffi                     ├── nanobind                    │
15│   └── Cython                   └── Python C API                │
16│                                                                 │
17└─────────────────────────────────────────────────────────────────┘

快速比較表

特性	ctypes	cffi	Cython	pybind11
標準庫	是	否	否	否
不需編譯器	是	是 (ABI)	否	否
C++ 支援	否	否	有限	是
效能	2/5	3/5	4/5	4/5
學習曲線	低	低	中	中高
PyPy 支援	有限	是	有限	否

【決策】選擇流程圖

主要決策點

 1開始
 2│
 3├── Q1: 有 C/C++ 原始碼嗎？
 4│   │
 5│   ├── 沒有（只有 .so/.dll）
 6│   │   └── → ctypes 或 cffi (ABI 模式)
 7│   │
 8│   └── 有原始碼
 9│       │
10│       ├── Q2: 是 C++ 嗎？
11│       │   │
12│       │   ├── 是 C++
13│       │   │   └── → pybind11 或 nanobind
14│       │   │
15│       │   └── 是純 C
16│       │       │
17│       │       ├── Q3: 想用 Python 語法寫？
18│       │       │   ├── 是 → Cython
19│       │       │   └── 否 → cffi (API 模式)
20│       │       │
21│       │       └── Q4: 需要優化現有 Python 程式碼？
22│       │           └── 是 → Cython
23│
24├── Q5: 需要在 PyPy 上執行？
25│   └── 是 → cffi
26│
27└── Q6: 需要最小依賴？
28    └── 是 → ctypes（標準庫）

場景決策表

場景	推薦工具	原因
呼叫系統 API (libc, Win32)	ctypes	標準庫，無需額外安裝
包裝現有 C 函式庫（無原始碼）	cffi (ABI)	較好的型別支援
包裝現有 C 函式庫（有原始碼）	cffi (API) 或 Cython	效能更好
包裝 C++ 函式庫	pybind11	C++ 原生支援
優化 Python 程式碼瓶頸	Cython	漸進式優化
新專案追求最小二進位	nanobind	現代設計
需要跨直譯器支援 (PyPy)	cffi	PyPy 官方推薦

【效能】基準測試比較

測試案例：數值計算

計算 Fibonacci 數列第 n 項（迭代版）：

1# 純 Python 基準
2def fib_python(n):
3    if n <= 1:
4        return n
5    a, b = 0, 1
6    for _ in range(2, n + 1):
7        a, b = b, a + b
8    return b

效能數據

 1計算 fib(40)，執行 10000 次：
 2
 3工具              相對時間    說明
 4─────────────────────────────────────────
 5純 Python         1.00x      基準
 6ctypes            0.45x      呼叫 C 函式庫
 7cffi (ABI)        0.40x      動態載入
 8cffi (API)        0.15x      編譯後
 9Cython            0.08x      靜態型別
10pybind11          0.08x      C++ 編譯
11
12注意：
13- 實際數據取決於具體任務
14- 數值計算 Cython 和 pybind11 接近
15- 字串處理 pybind11 通常更快（std::string）
16- 函式呼叫開銷：ctypes > cffi ABI > cffi API ≈ Cython ≈ pybind11

函式呼叫開銷測試

 1import timeit
 2
 3# 測試空函式呼叫開銷
 4# 每個工具都實現 def noop(): pass
 5
 6results = """
 7空函式呼叫 1,000,000 次：
 8
 9工具              時間 (ms)   每次呼叫 (ns)
10───────────────────────────────────────────
11Python def        45          45
12ctypes           280         280
13cffi (ABI)       180         180
14cffi (API)        55          55
15Cython cdef       12          12  (只能從 Cython 呼叫)
16Cython cpdef      50          50
17pybind11          52          52
18"""
19
20# 結論：
21# - ctypes/cffi ABI 的呼叫開銷較大
22# - 對於頻繁呼叫的小函式，編譯方案更好
23# - Cython cdef 最快，但不能從 Python 直接呼叫

記憶體使用比較

 1匯入空模組的記憶體增加：
 2
 3工具              額外記憶體
 4────────────────────────────
 5ctypes           ~50 KB
 6cffi             ~200 KB
 7Cython module    ~100 KB
 8pybind11 module  ~150 KB
 9
10編譯後的模組大小（簡單範例）：
11
12工具              .so 檔案大小
13─────────────────────────────
14Cython           ~100 KB
15pybind11         ~200 KB
16nanobind         ~50 KB

【考量】維護性與開發體驗

學習曲線

 1難度排序（由易到難）：
 2
 31. ctypes
 4   - Python 標準庫
 5   - 不需要 C 知識（但需要理解 C 型別）
 6   - 文件完整
 7
 82. cffi
 9   - 需要寫 C 宣告
10   - ABI 模式很簡單
11   - API 模式需要建構設定
12
133. Cython
14   - Python 超集，逐步學習
15   - 需要理解 C 型別系統
16   - 建構系統有學習成本
17
184. pybind11
19   - 需要 C++ 知識
20   - 現代 C++ 語法
21   - 需要 CMake 或類似工具

除錯難度

 1除錯工具支援：
 2
 3ctypes:
 4├── 可以用 Python debugger
 5├── 段錯誤難以追蹤
 6└── 沒有型別檢查
 7
 8cffi:
 9├── API 模式有較好的錯誤訊息
10├── 可以用 C debugger (gdb)
11└── ABI 模式錯誤較難理解
12
13Cython:
14├── 可以產生帶行號的 C 程式碼
15├── 支援 gdb/lldb
16├── cython -a 產生效能報告
17└── 支援 Python profiler
18
19pybind11:
20├── C++ 除錯器完整支援
21├── 異常會轉換為 Python 異常
22├── 編譯錯誤訊息可能很長
23└── 模板錯誤較難理解

IDE 支援

 1IDE / 編輯器支援程度：
 2
 3工具          型別提示    自動完成    語法高亮
 4─────────────────────────────────────────────
 5ctypes        2/5         2/5         4/5
 6cffi          2/5         2/5         4/5
 7Cython        3/5         3/5         3/5
 8pybind11      4/5         4/5         4/5
 9
10註：
11- Cython 有 VSCode 和 PyCharm 插件
12- pybind11 使用標準 C++，IDE 支援完整
13- ctypes/cffi 的 Python 部分支援完整

【案例】知名專案的選擇

NumPy

 1NumPy 的策略：
 2
 3核心計算:
 4└── Python C API + 自訂機制
 5    - 歷史原因（比 pybind11 更早）
 6    - 需要極致效能
 7    - 大量使用 BLAS/LAPACK
 8
 9周邊工具:
10└── Cython
11    - 部分輔助模組
12    - 與 NumPy 陣列整合良好

SciPy

 1SciPy 的策略：
 2
 3主要使用:
 4├── Cython（大部分新程式碼）
 5├── Fortran（歷史遺留的數值庫）
 6└── C（某些核心演算法）
 7
 8選擇原因:
 9- Cython 與 NumPy 整合好
10- 漸進式優化現有 Python 程式碼
11- 科學計算社群熟悉

PyTorch

 1PyTorch 的策略：
 2
 3C++ 核心:
 4└── pybind11
 5    - 大量 C++ 程式碼
 6    - 複雜的類別層級
 7    - 自動微分需要 C++ 特性
 8
 9選擇原因:
10- C++ 是主要開發語言
11- 需要 RAII、模板、繼承
12- 與 CUDA 程式碼整合

Pillow (PIL)

 1Pillow 的策略：
 2
 3影像處理核心:
 4└── Python C API
 5    - 歷史遺留
 6    - 底層記憶體操作
 7
 8周邊功能:
 9└── 純 Python 或 ctypes
10    - 呼叫系統圖形庫

cryptography

1cryptography 的策略：
2
3主要使用:
4└── cffi
5    - 包裝 OpenSSL
6    - 需要 PyPy 支援
7    - 安全性考量（減少手動記憶體管理）

【建議】實務選擇指南

新專案建議

 12025 年新專案建議：
 2
 3場景 1: 優化 Python 程式碼
 4推薦: Cython
 5理由:
 6- 漸進式優化
 7- 熟悉的 Python 語法
 8- 與 NumPy 整合好
 9
10場景 2: 包裝現有 C++ 函式庫
11推薦: pybind11 或 nanobind
12理由:
13- C++ 原生支援
14- 現代化 API
15- 活躍的社群
16
17場景 3: 簡單呼叫系統 API
18推薦: ctypes
19理由:
20- 標準庫，無依賴
21- 簡單場景足夠
22
23場景 4: 需要 PyPy 支援
24推薦: cffi
25理由:
26- PyPy 官方推薦
27- 良好的效能

遷移建議

 1從 ctypes 遷移到更快的方案：
 2
 3如果瓶頸是呼叫頻率：
 4└── 考慮 cffi (API) 或 Cython
 5    - 減少每次呼叫的開銷
 6
 7如果瓶頸是計算本身：
 8└── 考慮 Cython
 9    - 可以優化 Python 迴圈
10    - 使用 C 型別
11
12從 Cython 遷移到 pybind11：
13
14通常不需要：
15- Cython 和 pybind11 效能相近
16- 遷移成本高
17
18考慮遷移如果：
19- 需要更多 C++ 特性
20- 團隊更熟悉 C++
21- 需要與 C++ 函式庫深度整合

混合使用

 1可以在同一專案中混合使用：
 2
 3範例結構：
 4my_package/
 5├── _core.cpython-311-xxx.so    # Cython：核心計算
 6├── _bindings.cpython-311-xxx.so # pybind11：C++ 函式庫綁定
 7├── _ffi.py                      # cffi：簡單 C 呼叫
 8└── utils.py                     # 純 Python
 9
10原則：
11- 選擇最適合該任務的工具
12- 保持介面一致（對使用者透明）
13- 文件記錄每個部分的技術選擇

【未來】發展趨勢

Free-threading 影響

 1Python 3.13+ Free-threading 的影響：
 2
 3需要注意的工具：
 4├── pybind11: 需要更新 GIL 管理方式
 5├── Cython: nogil 區塊的行為變化
 6└── cffi: 相對影響較小
 7
 8趨勢：
 9- nanobind 已有 Free-threading 支援
10- pybind11 正在積極適應
11- Cython 3.1 計劃支援

HPy：新一代 C API

 1HPy (https://hpyproject.org/)
 2
 3目標：
 4├── 統一的 C API（跨直譯器）
 5├── 更好的 PyPy/GraalPy 支援
 6├── 為 Free-threading 設計
 7└── 簡化記憶體管理
 8
 9狀態（2025）：
10- 仍在開發中
11- 部分專案開始採用
12- 長期可能取代 Python C API

建構系統演進

 1建構系統趨勢：
 2
 3傳統：
 4├── setup.py + setuptools
 5└── 複雜且不標準
 6
 7現代：
 8├── scikit-build-core + CMake
 9├── meson-python
10└── 統一使用 pyproject.toml
11
12建議：
13- 新專案使用 scikit-build-core 或 meson-python
14- 舊專案可以繼續使用 setup.py
15- 避免複雜的建構邏輯

總結

選擇原則

簡單優先：如果 ctypes 能滿足需求，就用 ctypes
效能驅動：當效能成為瓶頸時，才考慮編譯方案
團隊技能：選擇團隊熟悉的技術
長期維護：考慮依賴的活躍度和未來發展

快速決策

1你應該使用：
2
3ctypes    → 簡單的系統 API 呼叫
4cffi      → 需要 PyPy 支援，或包裝 C 函式庫
5Cython    → 優化 Python 程式碼，或與 NumPy 密切整合
6pybind11  → 包裝 C++ 函式庫
7nanobind  → 新專案，追求最小化

實作練習

使用本章學到的四種工具，分別實現同一個函式（如快速排序），比較：
- 程式碼行數
- 編譯時間
- 執行效能
- 除錯體驗
選擇一個你熟悉的 C 函式庫，分別用 ctypes 和 cffi 包裝，比較開發體驗
將一個 Python 效能瓶頸用 Cython 優化，記錄優化過程和效能提升

延伸閱讀

上一章：pybind11 下一模組：模組五：用 Rust 擴展 Python

6.5 封裝預編譯二進位

Mon, 02 Feb 2026 00:00:00 +0000

本章介紹 Python 套件封裝預編譯二進位的架構模式，讓 Python 能夠調用高效能的原生程式碼。

本章目標

學完本章後，你將能夠：

理解「Python 封裝二進位」的架構模式
評估何時使用這種模式
了解知名套件如何應用這種技術
在純 Python 與封裝二進位之間做出正確選擇

【概念】什麼是封裝預編譯二進位？

架構模式

這種模式將其他語言（如 Go、Rust、C++）編譯的二進位檔案，包裝在 Python 套件中：

1┌─────────────────────────────────────────┐
2│       Python API（薄封裝層）              │  ← 使用者接觸的介面
3├─────────────────────────────────────────┤
4│   subprocess / FFI / ctypes / cffi      │  ← 呼叫機制
5├─────────────────────────────────────────┤
6│   預編譯二進位（Go/Rust/C/C++）          │  ← 實際執行邏輯
7└─────────────────────────────────────────┘

與 C 擴展的差異

面向	C 擴展（模組四/五）	封裝預編譯二進位
編譯時機	安裝時編譯	發布前預編譯
使用者需求	可能需要編譯器	不需要編譯器
整合方式	Python C API / pybind11	subprocess / FFI
典型來源	專為 Python 寫的擴展	獨立的 CLI 工具或函式庫

【案例】

TensorFlow / PyTorch

1TensorFlow 架構：
2├── Python API（tf.* 模組）
3│   └── 使用者撰寫的程式碼
4├── 綁定層（pybind11）
5│   └── Python ↔ C++ 橋接
6└── C++ 核心 + CUDA
7    └── 預編譯的運算核心

選擇原因：

GPU 運算需要原生效能
大量的 C++ 程式碼庫
安裝時編譯太慢（數小時）

cryptography

1cryptography 架構：
2├── Python API（cryptography.*)
3├── cffi 綁定層
4└── OpenSSL / BoringSSL
5    └── 預編譯的加密函式庫

選擇原因：

加密演算法需要經過審計的實現
效能關鍵
支援 PyPy（cffi 是 PyPy 官方推薦）

ruff（Python Linter）

1ruff 架構：
2├── Python 封裝（ruff 套件）
3│   └── 提供 CLI 和簡單 API
4└── Rust 二進位
5    └── 實際的 lint 邏輯

選擇原因：

追求極致速度（比 Flake8 快 10-100 倍）
Rust 的記憶體安全
作為獨立工具也可使用

mermaid-ascii（PyPI 封裝）

1osl-packages/mermaid-ascii 架構：
2├── Python API（mermaid_ascii 模組）
3│   └── mermaid_to_ascii() 函式
4├── subprocess 呼叫
5└── Go 編譯的 mermaid-ascii 二進位
6    └── Mermaid → ASCII 轉換

選擇原因：

重用現有的 Go 實現
不需要 Node.js 依賴
提供 Python 友善的介面

【優點】為什麼使用這種模式？

1. 效能

核心邏輯用高效能語言實現，Python 只做介面：

1# 使用者感受不到底層是 Rust
2import ruff
3
4# 實際上是呼叫 Rust 編譯的二進位
5result = ruff.check("my_code.py")

2. 重用現有實現

不需要用 Python 重寫已經穩定的程式碼：

1情境：有一個優秀的 Go CLI 工具
2選項 A：用 Python 重寫（大量工作）
3選項 B：封裝 Go 二進位（少量工作）← 通常更好

3. 跨語言生態整合

讓 Python 使用者能夠使用其他語言的優秀工具：

1# Python 使用者不需要安裝 Go
2from mermaid_ascii import mermaid_to_ascii
3
4diagram = mermaid_to_ascii("graph LR; A-->B")

4. 維護分離

核心邏輯與 Python 封裝可以獨立更新：

1mermaid-ascii（Go）: v0.6.1 → v0.7.0（核心更新）
2mermaid-ascii（PyPI）: 0.6.1 → 0.7.0（同步更新封裝）

【缺點】這種模式的限制

1. 平台依賴

需要為每個作業系統和 CPU 架構提供預編譯二進位：

 1典型的 wheel 矩陣：
 2├── manylinux_x86_64
 3├── manylinux_aarch64
 4├── macosx_x86_64
 5├── macosx_arm64
 6└── win_amd64
 7
 8缺點：
 9- 維護成本高
10- 新平台支援需要時間
11- CI/CD 複雜度增加

2. 安裝體積

wheel 檔案較大（包含二進位）：

1套件大小比較：
2純 Python 套件   ~50 KB
3封裝二進位套件   ~5-50 MB（依二進位大小）

3. 除錯困難

錯誤可能發生在二進位層，難以追蹤：

1# 錯誤訊息可能是二進位的 stderr
2try:
3    result = some_binary_wrapper()
4except subprocess.CalledProcessError as e:
5    # e.stderr 是二進位的錯誤訊息
6    # 可能不是 Python 友善的格式

4. 無法修改核心邏輯

想改變底層行為必須重編譯核心：

1如果你需要：
2- 修改演算法
3- 加入自訂功能
4- 修復底層 bug
5
6你必須：
71. 修改原始語言的程式碼
82. 重新編譯
93. 重新打包 wheel

5. 供應鏈風險

二進位來源需要信任：

1風險考量：
2├── 二進位是否來自可信來源？
3├── 是否有可驗證的建構流程？
4└── 是否有安全審計？
5
6最佳實踐：
7├── 使用知名維護者的套件
8├── 檢查 GitHub Actions 等 CI 建構紀錄
9└── 考慮自行建構（如果可能）

【比較】純 Python vs 封裝二進位

特性比較表

面向	純 Python	封裝預編譯二進位
效能	較慢	可達原生速度
可移植性	極佳（任何有 Python 的地方）	受限於預編譯平台
除錯	容易（Python 工具鏈）	困難（跨語言）
修改靈活度	高（直接修改程式碼）	低（需重新編譯）
安裝體積	小	大（含二進位）
依賴管理	簡單	複雜
透明度	完全可見	部分黑箱
開發速度	快（Python 生態）	需要多語言技能

決策流程

 1選擇純 Python 如果：
 2├── 效能不是關鍵瓶頸
 3├── 需要頻繁修改邏輯
 4├── 需要最大可移植性
 5├── 功能相對簡單
 6└── 希望保持程式碼透明
 7
 8選擇封裝二進位如果：
 9├── 效能是關鍵需求
10├── 已有成熟的非 Python 實現
11├── 核心邏輯穩定，不常修改
12├── 需要系統級別的操作
13└── 安全性要求使用審計過的實現

【實作】如何封裝二進位

方法一：subprocess 呼叫

最簡單的封裝方式，適合 CLI 工具：

 1# my_wrapper/core.py
 2import subprocess
 3import shutil
 4from pathlib import Path
 5
 6def find_binary():
 7    """找到封裝的二進位檔案"""
 8    # 二進位通常放在套件目錄內
 9    package_dir = Path(__file__).parent
10    binary = package_dir / "bin" / "my_tool"
11
12    if binary.exists():
13        return binary
14
15    # 或者在 PATH 中尋找
16    return shutil.which("my_tool")
17
18def run_tool(input_text: str) -> str:
19    """呼叫封裝的工具"""
20    binary = find_binary()
21    if not binary:
22        raise RuntimeError("找不到 my_tool 二進位")
23
24    result = subprocess.run(
25        [str(binary)],
26        input=input_text,
27        capture_output=True,
28        text=True,
29        check=True
30    )
31    return result.stdout

方法二：ctypes / cffi

適合函式庫（.so / .dll）：

 1# my_wrapper/bindings.py
 2import ctypes
 3from pathlib import Path
 4
 5def load_library():
 6    """載入共享函式庫"""
 7    package_dir = Path(__file__).parent
 8
 9    # 根據平台選擇正確的檔案
10    import platform
11    if platform.system() == "Darwin":
12        lib_name = "libmy_tool.dylib"
13    elif platform.system() == "Windows":
14        lib_name = "my_tool.dll"
15    else:
16        lib_name = "libmy_tool.so"
17
18    lib_path = package_dir / "lib" / lib_name
19    return ctypes.CDLL(str(lib_path))
20
21# 載入並設定函式簽名
22_lib = load_library()
23_lib.process_data.argtypes = [ctypes.c_char_p]
24_lib.process_data.restype = ctypes.c_char_p
25
26def process_data(data: str) -> str:
27    """Python 友善的介面"""
28    result = _lib.process_data(data.encode('utf-8'))
29    return result.decode('utf-8')

方法三：使用專門工具

1推薦工具：
2├── PyOxidizer：打包 Python + Rust
3├── Briefcase：跨平台打包
4├── Nuitka：Python → 原生編譯
5└── 自訂 GitHub Actions：建構多平台 wheel

【打包】建立 wheel

專案結構

 1my_package/
 2├── pyproject.toml
 3├── src/
 4│   └── my_package/
 5│       ├── __init__.py
 6│       ├── core.py          # Python 封裝
 7│       └── bin/             # 預編譯二進位
 8│           ├── my_tool-linux-x64
 9│           ├── my_tool-darwin-arm64
10│           └── my_tool-windows-x64.exe
11└── scripts/
12    └── build_binaries.sh    # 建構腳本

pyproject.toml 設定

 1[build-system]
 2requires = ["hatchling"]
 3build-backend = "hatchling.build"
 4
 5[project]
 6name = "my-package"
 7version = "0.1.0"
 8description = "Python wrapper for my_tool"
 9
10[tool.hatch.build.targets.wheel]
11# 包含二進位檔案
12include = [
13    "src/my_package/bin/*"
14]
15
16# 設定平台特定的 wheel
17[tool.hatch.build.targets.wheel.hooks.custom]
18# 自訂 hook 來處理平台特定二進位

GitHub Actions 範例

 1# .github/workflows/build.yml
 2name: Build wheels
 3
 4on: [push, release]
 5
 6jobs:
 7  build:
 8    strategy:
 9      matrix:
10        os: [ubuntu-latest, macos-latest, windows-latest]
11        arch: [x64, arm64]
12
13    runs-on: ${{ matrix.os }}
14
15    steps:
16      - uses: actions/checkout@v4
17
18      - name: Build binary
19        run: |
20          # 根據目標平台建構二進位
21          ./scripts/build_binary.sh ${{ matrix.arch }}
22
23      - name: Build wheel
24        run: |
25          pip install build
26          python -m build --wheel
27
28      - name: Upload wheel
29        uses: actions/upload-artifact@v4
30        with:
31          name: wheel-${{ matrix.os }}-${{ matrix.arch }}
32          path: dist/*.whl

【案例研究】beautiful-mermaid-py

背景

將 Mermaid 圖表轉換為 ASCII 藝術的工具，存在多種實現：

專案	語言	實現方式	圖表支援
mermaid-ascii	Go	原創實現	2 種
beautiful-mermaid	TypeScript	從 Go 移植並擴展	5 種
beautiful-mermaid-py	Python	從 TypeScript 移植	5 種
osl-packages/mermaid-ascii	Python	封裝 Go 二進位	2 種

兩種 Python 方案比較

1方案 A：封裝 Go 二進位（osl-packages）
2├── 優點：效能較好、維護成本低
3├── 缺點：平台依賴、無法修改邏輯
4└── 適合：追求效能、不需自訂
5
6方案 B：純 Python 移植（beautiful-mermaid-py）
7├── 優點：無依賴、可自訂、跨平台
8├── 缺點：效能略低（但對此任務足夠）
9└── 適合：需要修改、追求簡潔

決策分析

對於 Mermaid ASCII 渲染這個需求：

1效能需求：低（渲染一次圖表不需要毫秒級優化）
2修改需求：可能（未來可能想客製化輸出格式）
3平台多樣性：高（不同開發環境）
4維護成本：純 Python 更低
5
6結論：對於這個場景，純 Python 是更好的選擇

總結

何時封裝二進位

 1適合封裝二進位：
 2├── 效能關鍵的運算（加密、ML、圖像處理）
 3├── 已有成熟的非 Python 實現
 4├── 需要系統級別的操作
 5└── 安全性要求使用審計過的程式碼
 6
 7不適合封裝二進位：
 8├── 簡單的文字處理或資料轉換
 9├── 需要頻繁修改邏輯的功能
10├── 追求最大可移植性的工具
11└── 功能用純 Python 就能達到足夠效能

架構選擇原則

效能驅動：只有當效能是瓶頸時才考慮封裝二進位
重用優先：有成熟實現時考慮封裝，否則考慮純 Python
維護成本：評估長期維護的複雜度
團隊技能：選擇團隊能夠維護的方案

模組五：用 C 擴展 Python

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

本模組介紹如何使用 C/C++ 擴展 Python，提升效能或整合現有的 C 函式庫。

為什麼學習 C 擴展？

效能極致：當 Python 太慢時的解決方案
整合現有庫：呼叫 C/C++ 函式庫
理解生態系：NumPy、SciPy 等高效能套件的實現原理

章節列表

章節	主題	關鍵收穫
5.1	ctypes 與 cffi	動態綁定 C 函式庫
5.2	Cython	Python 語法的 C 速度
5.3	pybind11	現代 C++ 綁定
5.4	選擇指南	工具比較與決策

工具選擇快速指南

1沒有原始碼 ──────→ ctypes / cffi
2純 C 函式庫 ─────→ cffi 或 Cython
3C++ 函式庫 ──────→ pybind11
4優化現有 Python ─→ Cython

先備知識

進階系列模組四：CPython 內部機制
基本的 C 語言知識（指標、結構體、記憶體管理）

學習時間

每章節約 45-60 分鐘，全模組約 3-4 小時

上一模組：模組四：CPython 內部機制 下一模組：模組六：用 Rust 擴展 Python

案例研究

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

本節收錄基於 .claude/lib 實際程式碼的案例研究，展示如何用 Cython 加速 Python 程式碼。

案例列表

案例	素材	學習重點
Cython 加速 Markdown 解析	markdown_link_checker.py	Cython 基礎、型別宣告、效能比較
使用 ctypes 呼叫系統 API	系統 API	ctypes 實戰、跨平台、效能比較

學習路徑

建議先完成本模組的理論章節，再閱讀案例研究：

理解 Python/C API 基礎
學習 Cython 語法
通過案例實踐加速技巧