我們很高興宣佈 GroupDocs.Assembly for Python v26.11 已於 2026 年 11 月 發佈。此版本帶來了重大的平台支援改進——包括首個 Linux 與 macOS 的 wheel——以及原生 Python 資料來源支援、增強的錯誤處理與升級的相依套件。它同時引入了多項新功能與破壞性變更，以符合現代 Python 實踐與 .NET 10。

此版本的新功能

  • [Feature] 為 Linux x64 與 macOS（Intel 與 Apple Silicon）新增 wheel (ASSEMBLYPYTHON-26)
  • [Feature] 新增支援將 Python dict 或 list 作為資料來源 (ASSEMBLYPYTHON-27)
  • [Feature] 新增支援 Python 文件表格載入處理器 (IDocumentTableLoadHandler) (ASSEMBLYPYTHON-28)
  • [Feature] 新增支援在 API 需要 .NET Type 時使用 Python 類型 (DocumentTableColumn.type、known_types) (ASSEMBLYPYTHON-29)
  • [Feature] 新增支援從環境變數 GROUPDOCS_LIC_PATH 讀取授權 (ASSEMBLYPYTHON-30)
  • [Enhancement] 將 GroupDocs.Assembly 更新至 26.7，並將嵌入式執行階段升級至 .NET 10.0.14 (ASSEMBLYPYTHON-31)
  • [Enhancement] 為 Python 3.5 – 3.14 提供純 Python 套件，取代編譯擴充 (ASSEMBLYPYTHON-32)
  • [Enhancement] assemble_document() 可接受單一 DataSourceInfo，亦可接受列表 (ASSEMBLYPYTHON-33)
  • [Enhancement] 為缺失檔案拋出 FileNotFoundError、為無法套用授權拋出 LicenseError、為其他引擎錯誤拋出 GroupDocsAssemblyException (ASSEMBLYPYTHON-34)
  • [Enhancement] 將 BarcodeSettings.x_resolution/y_resolution 重新命名為 xresolution/yresolution，並將 use_reflection_optimization 設為類別屬性 (ASSEMBLYPYTHON-35)
  • [Enhancement] 移除 32 位元 Windows wheel (ASSEMBLYPYTHON-36)
  • [Fix] 修復 25.5.1 中的 CVE：zlib 1.2.11 → 1.2.12（另加 4 個） (ASSEMBLYPYTHON-11)

公開 API 變更

升級者需要將 x_resolution/y_resolution 以及 set_use_reflection_optimization() 重新命名，並在捕獲 RuntimeError 的地方改為捕獲 GroupDocsAssemblyException 與 LicenseError。其他皆為新增項目。

新增類別與成員

  • groupdocs.assembly：FontSettings、FolderFontSource、IFontSource、SearchOption、OoxmlCompliance、GroupDocsAssemblyException、LicenseError、LicenseWarning。
  • LoadSaveOptions：ooxml_compliance。
  • KnownTypeSet：append()。
  • DocumentTableCollection、DocumentTableColumnCollection：get()。
  • DocumentTableRelationCollection：append()、get()。

重新命名

  • BarcodeSettings.x_resolution → BarcodeSettings.xresolution
  • BarcodeSettings.y_resolution → BarcodeSettings.yresolution

舊名稱會在讀取或賦值時拋出帶有「Did you mean」提示的 AttributeError。

移除

  • DocumentAssembler.set_use_reflection_optimization()：改為直接賦值類別屬性，例如 DocumentAssembler.use_reflection_optimization = False。

變更

  • DataSourceInfo 現在接受 dict 或 list。
  • assemble_document() 可同時接受單一 DataSourceInfo 與列表。
  • DocumentTableSet(path, load_handler) 現在接受 Python 函式或具備 handle(args) 方法的物件。
  • DocumentTableColumn.type 與 KnownTypeSet.add() 現在接受 Python 類型。
  • 引擎錯誤會拋出 FileNotFoundError、RuntimeError、LicenseError 或 GroupDocsAssemblyException。except Exception 仍可捕獲兩個版本的錯誤。

新功能

Linux 與 macOS

26.11 為 Linux x64（manylinux_2_27_x86_64，glibc 2.27 或更新）以及 macOS 12 以上的 Intel（macosx_12_0_x86_64）與 Apple Silicon（macosx_12_0_arm64）提供 wheel，此外亦支援 Windows x64。25.5 只提供 Windows wheel。pip 20.3 以上會自動選擇相符平台的 wheel。Linux 上的 .NET 執行階段需要 ICU，且呈現模板需要 libgdiplus（請參閱 Requirements）。

pip install groupdocs-assembly-net==26.11.0

Python 資料作為資料來源

DataSourceInfo 可接受 dict、dict 列表或值列表；25.5 會對 dict 拋出 TypeError。此封裝器會根據資料形狀將資料轉換為 .NET 物件，因此數字、字串、bool、datetime、date 與 Decimal 皆會以正確類型傳遞至模板，例如 <<[o.OrderDate.Month]>> 與 <<if [c.Vip]>> 在 .NET 物件上同樣可用。單一列表中的 dict 會共享同一類型，鍵的聯集決定該類型。

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

orders = [
    {"Number": 10001, "Product": "Harbor Blend whole bean coffee", "Quantity": 30, "Price": 552.0},
    {"Number": 10004, "Product": "Aged harbour cheddar", "Quantity": 8, "Price": 132.0},
]

# order-table.docx: 一個表格，其列 <<foreach [o in orders]>><<[o.Number]>> ... <</foreach>> 會依每筆訂單重複
DocumentAssembler().assemble_document("order-table.docx", "order-table-report.docx", [
    DataSourceInfo("Quayside Bistro", "customer"),
    DataSourceInfo(orders, "orders"),
])

單一資料來源（不使用列表）

assemble_document() 可接受單一 DataSourceInfo，亦可接受多筆列表，與 .NET 的 params DataSourceInfo[] 行為相同。25.5 必須使用列表，否則會拋出 TypeError: can't build Array value from 'groupdocs.assembly.DataSourceInfo'。

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

customer = {"Name": "Quayside Bistro", "Product": "Harbor Blend whole bean coffee"}
DocumentAssembler().assemble_document("hello-world.docx", "hello-world-report.docx", DataSourceInfo(customer, "customer"))

表格載入處理器

DocumentTableSet(path, load_handler) 可接受 Python 函式 (args)，或具備 handle(args) 方法的物件，並在載入每個文件表格前呼叫。處理器可以設定該表格的 args.options，或透過 args.is_loaded = False 跳過表格；args.table_index 表示目前的表格索引。25.5 只接受編譯擴充，對 Python 函式會拋出 TypeError。

from groupdocs.assembly.data import DocumentTableOptions, DocumentTableSet


def on_table(args):
    options = DocumentTableOptions()
    options.first_row_contains_column_names = True
    args.options = options


tables = DocumentTableSet("contracts.xlsx", on_table)
for table in tables.tables:
    print(table.name, [column.name for column in table.columns])

API 需要 .NET 類型時的 Python 類型

Python 類型代表 API 所需的 .NET 類型，例如 float 代表 System.Double，int、str、bool、datetime 亦同。文件表格的欄位可設定為數值型別，以便圖表進行加總；known_types 允許模板呼叫類型的靜態成員，同時也接受 .NET 類型名稱。25.5 會因 TypeError: can't build Type value from 'type' 而失敗。

from groupdocs.assembly import DataSourceInfo, DocumentAssembler
from groupdocs.assembly.data import DocumentTable, DocumentTableOptions

options = DocumentTableOptions()
options.first_row_contains_column_names = True
contracts = DocumentTable("contracts.xlsx", 0, options)
contracts.columns["Price"].type = float

assembler = DocumentAssembler()
assembler.known_types.add("System.Math")  # 模板可呼叫 <<[Math.Round(x, 1)]>>
assembler.assemble_document("table-row.docx", "table-row-report.docx", DataSourceInfo(contracts, "contracts"))

從環境變數讀取授權

將 GROUPDOCS_LIC_PATH 設為授權檔案的路徑，或指向提供授權檔的 URL，授權會在首次呼叫引擎時自動套用，且不需要授權碼；25.5 不會讀取此變數。若授權無法套用（檔案遺失、訂閱過期、授權屬於其他產品），每次引擎呼叫都會拋出 LicenseError，並說明變數與引擎的原因，直到使用 License().set_license() 成功套用授權。將 GROUPDOCS_LIC_STRICT=0 可只產生一個 LicenseWarning 並進入評估模式。

from groupdocs.assembly import DataSourceInfo, DocumentAssembler, LicenseError

customer = {"Name": "Quayside Bistro", "Product": "Harbor Blend whole bean coffee"}
try:
    DocumentAssembler().assemble_document("hello-world.docx", "hello-world-report.docx", DataSourceInfo(customer, "customer"))
except LicenseError as e:
    print(e)  # GROUPDOCS_LIC_PATH=... could not be applied: <reason>

依類型分類的錯誤

25.5 會對所有引擎錯誤拋出裸 RuntimeError("Proxy error(<.NET exception>): ...")。26.11 則會根據情況拋出：

  • FileNotFoundError：缺少模板或資料檔（仍屬於 RuntimeError 的子類別）
  • RuntimeError：僅包含引擎訊息的模板錯誤或資料缺少的成員錯誤
  • LicenseError：授權無法套用
  • GroupDocsAssemblyException：其他引擎錯誤

LicenseError 與 GroupDocsAssemblyException 可從 groupdocs.assembly 匯入，且不繼承自 RuntimeError。

from groupdocs.assembly import DataSourceInfo, DocumentAssembler, GroupDocsAssemblyException

try:
    DocumentAssembler().assemble_document("no-such-template.docx", "report.docx", DataSourceInfo({"Name": "A"}, "customer"))
except FileNotFoundError as e:
    print("missing:", e)
except (RuntimeError, GroupDocsAssemblyException) as e:
    print("engine:", e)

程式碼範例

from groupdocs.assembly import DataSourceInfo, DocumentAssembler, FileFormat, LoadSaveOptions, OoxmlCompliance

options = LoadSaveOptions(FileFormat.DOCX)
options.ooxml_compliance = OoxmlCompliance.STRICT
customer = {"Name": "Quayside Bistro", "Product": "Harbor Blend whole bean coffee"}
DocumentAssembler().assemble_document("hello-world.docx", "hello-world-strict.docx", options, DataSourceInfo(customer, "customer"))

如何取得更新

PyPI

透過 PyPI 升級至最新套件：

groupdocs-assembly-net 26.11.0

pip install groupdocs-assembly-net==26.11.0

直接下載

從 GroupDocs.Assembly for Python v26.11 頁面下載適用於您平台的 wheel。

資源