程式碼對照 · _base_converter.py · MarkItDown 繁中教學站

大方向

這 105 行定義了整個系統的「最小公約數」：任何「能把檔案變成 Markdown」的東西都叫 DocumentConverter，任何轉換結果都是 DocumentConverterResult。兩個方法的簽名刻意一致，保證 accepts() 回 True 時 convert() 一定能處理。

1. DocumentConverterResult（結果物件）

DocumentConverterResult.__init__(markdown, *, title=None) 結果唯一必填是 Markdown 字串；title 可選。

title 為 keyword-only、可選——目前只有部分 converter（如 EPUB）會填。未來新增中繼資料只需加欄位，不破壞既有呼叫。

text_content（property + setter）軟棄用markdown 的別名，向後相容舊程式碼。

docstring 明說「soft-deprecated」，新程式碼請用 markdown 或 __str__。 __str__ 直接回傳 markdown——所以 print(result) 就是印 Markdown。

2. DocumentConverter（抽象父類）

DocumentConverter.accepts(file_stream, stream_info, **kwargs) -> bool 協定快速判斷「該不該由我轉」。

判定的主要依據依序：stream_info.mimetype、stream_info.extension； HTTP 抓來的會看 stream_info.url（Wikipedia/YouTube 就是靠 URL 判斷）；甚至可看 filename（如 Dockerfile/Makefile 這種知名檔名）。

陷阱提醒（官方註解）：像 OutlookMsgConverter 這種必須「偷讀」串流才能判斷的 converter，讀完必須把位置 seek 回去——因為緊接著 convert() 會從原位置開始讀。

DocumentConverter.convert(file_stream, stream_info, **kwargs) -> DocumentConverterResult 協定把檔案流讀成 Markdown 結果。

接受 seek/tell/read 的 file-like 物件 + StreamInfo + 全域 kwargs。可拋：FileConversionException（型別認得但轉失敗）、MissingDependencyException （缺依賴）。兩個方法都是 NotImplementedError，強迫子類實作。