模組五：用 C 擴展 Python on Tarragon

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

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

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