Quick Start Guide Leave feedback

This guide provides a quick overview of how to set up and start using GroupDocs.Assembly for Python via .NET. The library fills templates, ordinary Word, Excel, PowerPoint, email, HTML or text documents with tags in them, with your data, and saves the result as a report.

To proceed, make sure you have:

1. Configured environment as described in the System Requirements topic.
2. Optionally you may Get a Temporary License to test all the product features.

For best practices, use a virtual environment to manage dependencies in Python applications. Learn more about virtual environments at the Create and Use Virtual Environments documentation topic.

Create a virtual environment:

py -m venv .venv

python3 -m venv .venv

python3 -m venv .venv

Activate a virtual environment:

.venv\Scripts\activate

source .venv/bin/activate

source .venv/bin/activate

After activating the virtual environment, run the following command in your terminal to install the latest version of the package:

py -m pip install groupdocs-assembly-net

python3 -m pip install groupdocs-assembly-net

python3 -m pip install groupdocs-assembly-net

Ensure the package is installed successfully. You should see the message

Successfully installed groupdocs-assembly-net-*

To quickly test the library, let’s fill the table of a Word template with the orders of one customer. The template, order-table.docx, has a heading, a table whose second row repeats for each order, and a total:

Orders of <<[customer]>>
| Order                              | Product          | Quantity          | Price                               |
| <<foreach [o in orders]>><<[o.Number]>> | <<[o.Product]>> | <<[o.Quantity]>> | <<[o.Price]:"0.00">><</foreach>> |
Total: <<[orders.Sum(o => o.Price)]:"0.00">> USD

import os

from groupdocs.assembly import DataSourceInfo, DocumentAssembler, License

def table_report():
    # Optionally set a license
    license_path = os.path.abspath("./GroupDocs.Assembly.lic")
    if os.path.exists(license_path):
        License().set_license(license_path)

    # The data: one dict per table row, with the keys the template reads
    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},
        {"Number": 10006, "Product": "Cold-pressed olive oil", "Quantity": 40, "Price": 516.0},
    ]

    # Each data source has the name the template uses for it
    assembler = DocumentAssembler()
    assembler.assemble_document("order-table.docx", "order-table-report.docx", [
        DataSourceInfo("Quayside Bistro", "customer"),
        DataSourceInfo(orders, "orders"),
    ])
    print("The report is saved to order-table-report.docx")

if __name__ == "__main__":
    table_report()

Binary file (DOCX, 8 KB)

py table_report.py

python3 table_report.py

python3 table_report.py

• DocumentAssembler(): The class that builds reports. One instance can build any number of them.
• DataSourceInfo(orders, "orders"): A data source and the name the template’s tags use for it. A list of dicts is a collection: the <<foreach [o in orders]>> band repeats the table row once for each dict, and o.Number reads the dict’s "Number" key.
• assemble_document(template, report, sources): Fills the template and writes the report. The data sources go as a list, or as one DataSourceInfo when there is only one.
• <<[orders.Sum(o => o.Price)]:"0.00">>: Template expressions can compute: Sum, Count, Where, OrderBy, GroupBy and more work on the Python list, and :"0.00" formats the number.

The data often comes from a file. This example reads the customers of Harbor Lane Provisions and their orders from customers.json, and the template orders-by-customer.docx lists the orders of each customer:

Harbor Lane Provisions: orders by customer
<<foreach [c in customers]>>
<<[c.CustomerName]>>
  • <<foreach [o in c.Order]>><<[o.Product.ProductName]>>: <<[o.ProductQuantity]>> units, <<[o.Price]>> USD, shipped <<[o.ShippingDate]:"d MMMM yyyy">>
<</foreach>>Total: <<[c.Order.Sum(o => o.Price)]>> USD
<</foreach>>

import json
from datetime import datetime

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

def parse_dates(item):
    # JSON has no dates: turn the order dates into datetime objects for the template
    for key in ("OrderDate", "ShippingDate"):
        if key in item:
            item[key] = datetime.strptime(item[key], "%Y-%m-%dT%H:%M:%S")
    return item

def json_to_pdf():
    with open("customers.json", encoding="utf-8") as f:
        customers = json.load(f, object_hook=parse_dates)

    # A Word template, a PDF report: the report's extension picks the format
    assembler = DocumentAssembler()
    assembler.assemble_document("orders-by-customer.docx", "orders-by-customer.pdf", DataSourceInfo(customers, "customers"))
    print("Customers:", len(customers))

if __name__ == "__main__":
    json_to_pdf()

Binary file (PDF, 47 KB)

py json_to_pdf.py

python3 json_to_pdf.py

python3 json_to_pdf.py

• json.load(f, object_hook=parse_dates): Reads the file into dicts and lists, which DataSourceInfo takes as they are. JSON has no date type, so the hook turns the date strings into datetime objects: the template formats ShippingDate as a date ("d MMMM yyyy").
• c.Order and o.Product.ProductName: Nested dicts and lists are read with dots, as in the JSON.
• "orders-by-customer.pdf": The report is saved in the format of its extension. The same template gives DOCX, PDF, HTML, XPS and the other supported formats.

Templates can be spreadsheets too. The template stock-sheet.xlsx has a header row and a row that repeats for each product of products.json:

Harbor Lane Provisions: stock
| Product                                   | In stock          | Discount, %     | Price                                 |
| <<foreach [p in products]>><<[p.ProductName]>> | <<[p.UnitInStock]>> | <<[p.Discount]>> | <<[p.ProductPrice]>><</foreach>> |

import json

from groupdocs.assembly import DataSourceInfo, DocumentAssembler, DocumentAssemblyOptions

def fill_spreadsheet():
    with open("products.json", encoding="utf-8") as f:
        products = json.load(f)

    # Write numbers as numbers: by default every value goes into a text cell
    assembler = DocumentAssembler()
    assembler.options = DocumentAssemblyOptions.USE_SPREADSHEET_DATA_TYPES
    assembler.assemble_document("stock-sheet.xlsx", "stock-sheet-report.xlsx", DataSourceInfo(products, "products"))
    print("Products:", len(products))

if __name__ == "__main__":
    fill_spreadsheet()

Binary file (XLSX, 8 KB)

py fill_spreadsheet.py

python3 fill_spreadsheet.py

python3 fill_spreadsheet.py

• stock-sheet.xlsx: In a spreadsheet the data band is a row of cells, from the cell that opens <<foreach>> to the cell that closes it; the report gets one row per product.
• DocumentAssemblyOptions.USE_SPREADSHEET_DATA_TYPES: Writes each value as its type, so UnitInStock and Discount are number cells that formulas can use, and ProductPrice (a string in the JSON) is a text cell. Without the option, every value is written as text.

• Supported Document Formats: Review the template and report formats.
• Licensing and Evaluation: Check details on licensing and the evaluation limits.
• Developer Guide: Dive into the template syntax, the data sources and every kind of report: tables, lists, charts, images, barcodes and email.
• Technical Support: Contact support for assistance if you encounter issues.