Python-docx 圖片提取完全指南：從 rId 到二進位資料的探險rid

# 1. 環境設定與匯入套件
# 我們需要 docx 來操作 Word，PIL 來生成/驗證圖片，io 來處理記憶體內的二進位流
from docx import Document
from docx.shared import Inches
from PIL import Image, ImageDraw
import io
import os

# 設定測試檔案路徑
temp_dir = r"D:\Temp"
docx_path = os.path.join(temp_dir, "demo_extraction.docx")

# 確保目錄存在
os.makedirs(temp_dir, exist_ok=True)
print(f"工作目錄已準備: {temp_dir}")

# 2. 生成測試用的 docx 檔案

# A. 用 PIL 畫一張圖
img = Image.new('RGB', (300, 100), color=(255, 100, 100)) # 紅色背景
d = ImageDraw.Draw(img)
d.text((10, 40), "SECRET IMAGE DATA", fill=(255, 255, 255))

# B. 存入記憶體 (BytesIO)
img_byte_arr = io.BytesIO()
img.save(img_byte_arr, format='PNG')
img_byte_arr.seek(0) # 倒帶回開頭，準備給 python-docx 讀取

# C. 寫入 Word 檔
doc = Document()
doc.add_paragraph("這是一份機密文件，下方藏著一張圖片：")
run = doc.add_paragraph().add_run()
run.add_picture(img_byte_arr, width=Inches(3.0)) # 插入圖片
doc.add_paragraph("圖片已插入完畢。")

doc.save(docx_path)
print(f"已生成測試文件: {docx_path}")

from typing import Optional
from docx.document import Document as DocxDocument

def extract_image_bytes(doc: DocxDocument, rid: str) -> Optional[bytes]:
    """
    用 rId 從 document part relationships 找出對應的圖片零件 (Part)，再取出內容。
    
    參數:
    - doc: DocxDocument 物件
    - rid: 關係 ID (如 'rId4')
    
    回傳:
    - bytes: 圖片的原始二進位資料
    """
    
    # 1. 取得關聯與零件
    # doc.part.rels 實際上是 `docx.opc.rel.Relationships` 類別的實例
    # 它不是 Python 原生的 dict，但它是「像字典一樣的物件」 (Dict-like Object)
    # 所以我們可以用 `in` 來檢查 key，也可以用 `[]` 來取值
    """
    {'rId3': <docx.opc.rel._Relationship at 0x1ec41ac0250>,
     'rId4': <docx.opc.rel._Relationship at 0x1ec41ac2950>,
     'rId5': <docx.opc.rel._Relationship at 0x1ec41ac00d0>,
     'rId6': <docx.opc.rel._Relationship at 0x1ec41ac0150>,
     'rId7': <docx.opc.rel._Relationship at 0x1ec41ac01d0>,
     'rId8': <docx.opc.rel._Relationship at 0x1ec41ac0390>,
     'rId1': <docx.opc.rel._Relationship at 0x1ec41ac0490>,
     'rId2': <docx.opc.rel._Relationship at 0x1ec41ac0290>,
     'rId9': <docx.opc.rel._Relationship at 0x1ec41ac0690>}
    """
    if rid not in doc.part.rels:
        return None
        
    rel = doc.part.rels[rid]
    """ docx.opc.rel._Relationship
    vars(rel) or rel.__dict__
    
    {'_rId': 'rId9',
     '_reltype': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image',
     '_target': <docx.parts.image.ImagePart at 0x1ec41ab5810>,
     '_baseURI': '/word',
     '_is_external': False}
    """
    
    # 透過 relationship 找到目標零件 (Target Part)
    # 這裡的 target_part 通常是 docx.parts.image.ImagePart 類別的實例
    target_part = rel.target_part
    """為什麼使用 rel.target_part ,而非 rel.target
    確保拿到物件：.target_part 是一個公開的屬性 (Property)，
    它的工作就是「掛保證」。不管底層現在存的是字串還是還沒初始化的東西，
    它會負責弄出一個完整的 Part 物件給您。
    避免碰到內部實作：底層的 _target 是內部實作細節，未來可能會改名或改變行為，
    但 .target_part 是對外的承諾介面，使用它最安全穩定。
    使用 dir(rel) 就可以看到 target_part 這個屬性
    
    vars(target_part) or target_part.__dict__
    {'_partname': '/word/media/image1.png',
     '_content_type': 'image/png',
     '_blob': b'\x89PNG\r\n\x1a\n\x00\x00...',
     '_package': None,
     '_image': None,
     '_rels': {},
     'rels': {}}
    """
    
    # 讓我們印出來看看這是什麼東西 (教學用)
    print(f"[Debug] rId={rid}")
    print(f"       -> 對應到 PartName: {target_part.partname}")
    print(f"       -> 內容類型 ContentType: {target_part.content_type}")

    # [重要] 安全機制：檢查這是不是真的圖片
    # 有時候 relationship 會指向註腳 (footnotes) 或樣式表，那些也是 XML 但不是圖片
    if "image" not in target_part.content_type:
        print(f"       -> [警告] 這不是圖片，略過 extract。")
        return None
    
    # 2. 取出資料
    # 使用 .blob (Binary Large Object) 屬性取出二進位資料
    #
    # Q: 為什麼要用 getattr(target_part, 'blob', None) 而不是直接 target_part.blob ?
    # A: 這是一種防禦性寫法。
    #    雖然理論上 ImagePart 一定有 .blob，但若是這份文件的部分零件損毀，或 python-docx 版本差異，
    #    直接用 .blob 可能會在屬性不存在時拋出 AttributeError 導致程式崩潰。
    #    getattr() 允許我們設定一個預設值 (None)，當屬性找不到時優雅地回傳 None 讓我們處理。
    return getattr(target_part, 'blob', None)

from typing import Optional
from docx.document import Document as DocxDocument

def extract_image_bytes(doc: DocxDocument, rid: str) -> Optional[bytes]:
    """
    簡潔版：嘗試透過 rId 取得圖片 Bytes。
    使用 EAFP (Easier to Ask for Forgiveness than Permission) 風格。
    """
    try:
        # 1. 直接取得目標零件
        part = doc.part.rels[rid].target_part
        
        # 2. 為了不誤拿 xml 當圖片，這裡做最後一道極簡檢查
        # (如果在外面檢查 bytes header 會比在這裡檢查 content_type 麻煩很多)
        if "image" not in part.content_type:
            return None
            
        # 3. 回傳資料
        return part.blob
        
    except (KeyError, AttributeError):
        # rId 不存在，或是該關聯沒有零件 (Target is None)
        return None

from docx.oxml.ns import qn

# 讀取我們剛剛做好的文件
doc = Document(docx_path)

found_rids = []

# 遍歷所有段落和 Run
for p in doc.paragraphs:
    for run in p.runs:
        # 檢查這個 Run 的 XML 裡面有沒有 <w:drawing> (圖片通常包在這個標籤裡)
        if 'w:drawing' in run._element.xml:
            # 使用 XPath 找出底下的 <a:blip> 標籤
            # namespace 注意: 'a' 通常代表 main drawing namespace
            blips = run._element.xpath(".//a:blip")
            for blip in blips:
                # 取得 r:embed 屬性，這就是 rId
                rid = blip.get(qn("r:embed"))
                if rid:
                    print(f"找到圖片參考！ rId: {rid}")
                    found_rids.append(rid)

print(f"總共找到 {len(found_rids)} 個圖片參照。")

# 5. 驗證結果
if found_rids:
    target_rid = found_rids[0] # 取第一個找到的
    
    # === 使用我們的核心函式 ===
    image_data = extract_image_bytes(doc, target_rid)
    # ========================
    
    if image_data:
        print(f"\n成功提取出 {len(image_data)} bytes 的資料！")
        
        # 用 PIL 讀取這些 bytes，看看是不是我們剛剛畫的那張圖
        extracted_img = Image.open(io.BytesIO(image_data))
        
        print("提取出的圖片預覽：")
        display(extracted_img) # 在 Jupyter 顯示圖片
    else:
        print("提取失敗，回傳為 None")
else:
    print("沒有找到任何圖片 rId，無法測試。")

# 5. 驗證結果
if found_rids:
    target_rid = found_rids[0] # 取第一個找到的
    
    # === 使用我們的核心函式 ===
    image_data = extract_image_bytes(doc, target_rid)
    # ========================
    
    if image_data:
        print(f"\n成功提取出 {len(image_data)} bytes 的資料！")
        
        # 用 PIL 讀取這些 bytes，看看是不是我們剛剛畫的那張圖
        extracted_img = Image.open(io.BytesIO(image_data))
        
        print("提取出的圖片預覽：")
        display(extracted_img) # 在 Jupyter 顯示圖片
    else:
        print("提取失敗，回傳為 None")
else:
    print("沒有找到任何圖片 rId，無法測試。")