Python 進階主題與實務應用

C 擴充模組（Cython、ctypes）

---

簡介

在 Python 的開發過程中，我們常會遇到 效能瓶頸、既有 C/C++ 函式庫 需要整合，或是想要 直接操作記憶體、呼叫系統層級 API 的情況。純 Python 雖然語法簡潔、開發速度快，但在計算密集或需要低階控制的場景下，往往無法滿足需求。這時，使用 C 擴充模組 成為一條重要的解決之路。

本篇文章將介紹兩種在 Python 中最常使用的 C 整合方式——Cython 與 ctypes。Cython 讓你以類似 Python 的語法寫出可編譯成 C 的程式，兼具開發便利與效能提升；ctypes 則提供了 純 Python 呼叫動態連結函式庫（.so、.dll）的介面，適合快速原型或與已有 C 函式庫互動。透過本篇的說明與範例，你將能在實務專案中選擇最適合的工具，將 Python 的彈性與 C 的效能結合起來。

---

核心概念

1. 為什麼要使用 C 擴充模組？

項目	Python (純)	Cython / ctypes
執行速度	受限於直譯器	可接近原生 C 的效能
記憶體控制	受 GC 限制	直接操作指標、結構
與既有 C 函式庫整合	需要第三方工具	直接呼叫或編譯
開發成本	低	需要編譯或介面定義

2. Cython 基礎

Cython 是一個 Python‑to‑C 編譯器，它把 .pyx 檔案（類似 Python）編譯成 C 程式，再編譯成二進位模組 (.so / .pyd)。只要在需要的地方加入型別宣告，即可大幅提升執行效能。

2.1 安裝與編譯

pip install cython           # 安裝 Cython
# 建立簡易的 setup.py

# setup.py
from setuptools import setup
from Cython.Build import cythonize

setup(
    ext_modules = cythonize("example.pyx")
)

python setup.py build_ext --inplace   # 產生 example.c 與 example.*.so

2.2 基本範例：加速迴圈

# example.pyx
def sum_range(int n):
    cdef long total = 0          # 明確宣告 C 型別
    cdef int i
    for i in range(n):
        total += i
    return total

說明：cdef 宣告的變數在編譯後會變成純 C 整數，迴圈不再走 Python 的 for 迭代器，執行速度可提升數十倍。

2.3 呼叫外部 C 函式

/* hello.c */
#include <stdio.h>

void greet(const char* name) {
    printf("Hello, %s!\n", name);
}

# hello_wrapper.pyx
cdef extern from "hello.c":
    void greet(const char* name)

def py_greet(name):
    greet(name.encode('utf-8'))   # 轉成 bytes 再傳遞

說明：cdef extern 用來告訴 Cython 有一個外部 C 函式 greet，編譯時會自動連結 hello.c。

3. ctypes 基礎

ctypes 是 Python 標準庫的一部份，提供 純 Python 的方式載入並呼叫動態連結函式庫。適合快速測試或在不想編譯的情況下使用。

3.1 載入函式庫

# ctypes_example.py
import ctypes
import os

# 假設有 libmath.so (Linux) 或 math.dll (Windows)
if os.name == "nt":
    lib = ctypes.CDLL("math.dll")
else:
    lib = ctypes.CDLL("./libmath.so")

3.2 設定函式原型

# C 函式原型: double add(double a, double b);
lib.add.argtypes = (ctypes.c_double, ctypes.c_double)   # 參數型別
lib.add.restype  = ctypes.c_double                       # 回傳型別

result = lib.add(3.5, 2.1)
print("3.5 + 2.1 =", result)   # => 5.6

3.3 操作結構體

/* struct_example.c */
typedef struct {
    int id;
    double value;
} Item;

double compute(Item* it) {
    return it->id * it->value;
}

# ctypes_struct.py
import ctypes

class Item(ctypes.Structure):
    _fields_ = [("id", ctypes.c_int),
                ("value", ctypes.c_double)]

lib = ctypes.CDLL("./struct_example.so")
lib.compute.argtypes = (ctypes.POINTER(Item),)
lib.compute.restype  = ctypes.c_double

it = Item(7, 3.14)
print("result =", lib.compute(ctypes.byref(it)))   # 7 * 3.14

3.4 呼叫系統 API（Windows 範例）

# winapi_example.py
import ctypes
from ctypes import wintypes

kernel32 = ctypes.WinDLL('kernel32', use_last_error=True)

# BOOL Beep(DWORD dwFreq, DWORD dwDuration);
kernel32.Beep.argtypes = (wintypes.DWORD, wintypes.DWORD)
kernel32.Beep.restype  = wintypes.BOOL

kernel32.Beep(750, 300)   # 發出 750Hz 音，持續 300ms

4. 何時選擇 Cython？何時選擇 ctypes？

條件	Cython	ctypes
需要大量運算加速	✅ 編譯成 C，效能佳	❌ 仍走 Python 介面
已有 C 程式碼	✅ 可直接 cdef extern 整合	✅ 也可使用 CDLL
開發速度	⚠️ 需要編譯、設定 .pyx	✅ 完全 Python，快速原型
跨平台部署	⚠️ 需要重新編譯二進位	✅ 同一段程式即可跑在不同 OS
記憶體安全	✅ 靜態型別、編譯期檢查	⚠️ 需要自行管理指標、釋放

---

常見陷阱與最佳實踐

1. 忘記設定 argtypes / restype
ctypes 預設會把所有參數當作 c_int，返回值當作 c_int。未正確設定會導致資料截斷或程式崩潰。
   👉 最佳實踐：一律在載入函式後立即定義 argtypes 與 restype。

2. 字串編碼問題
   C 函式通常接受 char*（UTF‑8 或 ASCII），而 Python str 為 Unicode。直接傳遞會拋出 TypeError。
   👉 使用 encode('utf-8') 轉為 bytes，或在 Cython 中使用 cdef const char*.

3. 記憶體泄漏
   使用 ctypes 取得指向 C 動態分配記憶體的指標時，必須自行呼叫對應的 free，否則會造成泄漏。
   👉 盡量使用 ctypes 的 create_string_buffer、byref 等自動管理的方式，或在 Cython 中使用 with nogil: 搭配 RAII。

4. 編譯相容性
   Cython 產生的 C 檔案依賴於 Python 版本與 C 編譯器，不同平台或 Python 小版號可能需要重新編譯。
   👉 在 setup.py 中加上 language_level=3，並使用 wheel 來分發二進位。

5. 除錯困難
   Cython 編譯後的錯誤訊息往往指向產生的 .c 檔，而非原始 .pyx。
   👉 加入 cythonize(..., annotate=True, compiler_directives={'linetrace': True}) 產生 HTML 註解，可視化 Python 與 C 的對應。

---

實際應用場景

1. 科學運算與資料分析
   在 Pandas、NumPy 之上，使用 Cython 重新實作瓶頸函式（如自訂聚合、排序），可讓大型資料集的處理時間減半以上。

2. 影像處理與電腦視覺
   OpenCV 本身是 C++ 實作，透過 Cython 包裝自訂濾波器或特徵抽取演算法，可直接在 Python pipeline 中使用，避免頻繁的跨語言呼叫開銷。

3. 嵌入式系統與硬體介面
   使用 ctypes 直接呼叫廠商提供的 C 驅動程式（例如串列埠、GPIO），在 Raspberry Pi 或微控制器上快速完成硬體控制。

4. 遊戲開發與即時渲染
   核心渲染迴圈寫成 C 函式庫，Python 負責腳本與 UI，使用 Cython 產生的模組將兩者無縫結合，兼顧開發效率與即時效能。

5. 安全性與加密
   OpenSSL 等加密函式庫提供 C API，使用 ctypes 或 Cython 包裝後，可在 Python 應用中直接使用硬體加速的加密演算法。

---

總結

• Cython：適合需要 高效能、大量運算 或 深度整合 既有 C 程式碼的情境。透過簡潔的 .pyx 語法與型別宣告，即可將 Python 程式編譯成接近原生 C 的執行檔，效能提升可達十倍以上。
• ctypes：是 純 Python 的橋樑，適合 快速原型、呼叫第三方動態函式庫 或 系統層級 API。只要正確設定參數與回傳型別，即可安全、跨平台地使用 C 函式。

在實務開發中，往往會 先以 ctypes 完成原型驗證，再根據效能需求將關鍵部份改寫為 Cython 模組，最後以 setup.py 打包發佈。掌握這兩種工具的差異與最佳實踐，能讓你在 Python 專案中靈活運用 C 的威力，打造 高效、可靠且易於維護 的系統。祝你在未來的開發旅程中，玩得開心、寫得順手！