Apply Formatting to Numbers, Dates, and Text in Python Leave feedback

GroupDocs.Assembly for Python via .NET provides comprehensive formatting capabilities for numbers, dates, and text in templates. You can use format strings (.NET format strings, whichever language calls the assembler) and built-in text transformation functions to control how data is displayed in your documents.

The main syntax elements are:

• Format strings: <<[expression]:"format">> - apply .NET format strings
• Text functions: upper, lower, caps, firstCap - transform text case

Here are the steps to apply formatting:

• Use format strings in expression tags for numbers and dates
• Apply text transformation functions for string formatting
• Combine formatting with expressions and calculations
• Test formatting to ensure desired output

Note

Format strings follow .NET formatting conventions, not Python’s. Use standard numeric format specifiers (C, N, F, etc.) and date/time format strings (yyyy-MM-dd, etc.). The value’s Python type decides what a format string can do: an int, float or Decimal takes a numeric format, a datetime or date takes a date format, and a str is written as it is.

Format numeric values using format strings:

from decimal import Decimal

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

invoice = {
    "Amount": Decimal("1500.75"),
    "Percentage": 0.15,
    "Quantity": 25,
}

assembler = DocumentAssembler()
assembler.assemble_document("invoice-numbers.docx", "invoice-numbers-report.docx",
                            DataSourceInfo(invoice, "invoice"))

print("Numbers formatted successfully.")

Binary file (DOCX, 7 KB)

In your template, use format strings:

Amount: <<[invoice.Amount]:"C">>
Percentage: <<[invoice.Percentage]:"P">>
Quantity: <<[invoice.Quantity]:"N0">>

Common numeric format strings:

• "C" - Currency (e.g., $1,500.75)
• "N" or "N2" - Number with decimals (e.g., 1,500.75)
• "F" or "F2" - Fixed-point (e.g., 1500.75)
• "P" - Percentage (e.g., 15.00%)
• "D" - Decimal (for integers)

The currency symbol and the separators come from the culture of the process: the examples above are what en-US writes.

Format date-time values. A date format needs a datetime or a date in the data; a date kept as a string is written unchanged.

from datetime import datetime

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

report = {
    "CreatedDate": datetime(2015, 1, 15, 14, 30, 0),
    "DueDate": datetime(2015, 2, 15),
}

assembler = DocumentAssembler()
assembler.assemble_document("report-dates.docx", "report-dates-report.docx",
                            DataSourceInfo(report, "report"))

print("Dates formatted successfully.")

Binary file (DOCX, 7 KB)

Created: <<[report.CreatedDate]:"yyyy-MM-dd HH:mm">>
Due Date: <<[report.DueDate]:"MMMM dd, yyyy">>

Common date format strings:

• "yyyy-MM-dd" - 2015-01-15
• "MM/dd/yyyy" - 01/15/2015
• "MMMM dd, yyyy" - January 15, 2015
• "dd.MM.yyyy" - 15.01.2015
• "HH:mm" - 14:30

Transform text case using built-in functions:

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

product = {
    "Name": "harbor blend whole bean coffee",
    "Description": "SMALL-BATCH HOUSE ROAST",
}

assembler = DocumentAssembler()
assembler.assemble_document("product-text-case.docx", "product-text-case-report.docx",
                            DataSourceInfo(product, "product"))

print("Text formatted successfully.")

Binary file (DOCX, 7 KB)

Name: <<[product.Name]:upper>>
Description: <<[product.Description]:lower>>
Title: <<[product.Name]:caps>>
Sentence: <<[product.Name]:firstCap>>

Text transformation functions:

• :upper - Convert to UPPERCASE
• :lower - Convert to lowercase
• :caps - Capitalize Each Word
• :firstCap - Capitalize first letter only

The function names are case-sensitive: :Caps or :firstcap fails with “Expression tag is not well-formed”.

Format calculated values:

from decimal import Decimal

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

order = {"Quantity": 5, "UnitPrice": Decimal("18.40")}

assembler = DocumentAssembler()
assembler.assemble_document("order-line-total.docx", "order-line-total-report.docx",
                            DataSourceInfo(order, "order"))

print("Calculations formatted successfully.")

Binary file (DOCX, 7 KB)

Template:

Quantity: <<[order.Quantity]>>
Unit Price: <<[order.UnitPrice]:"C">>
Total: <<[order.Quantity * order.UnitPrice]:"C">>

Use custom format strings for specific requirements:

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

data = {
    "Phone": 5550142811,
    "Code": 42,
    "Rate": 0.1234,
}

assembler = DocumentAssembler()
assembler.assemble_document("custom-number-formats.docx", "custom-number-formats-report.docx",
                            DataSourceInfo(data, "data"))

print("Custom formats applied successfully.")

Binary file (DOCX, 7 KB)

Template with custom formats:

Phone: <<[data.Phone]:"(###) ###-####">>
Code: <<[data.Code]:"000">>
Rate: <<[data.Rate]:"0.00%">>

A digit placeholder format such as "(###) ###-####" needs a number: keep the phone number an int in the data, not a string.

Formatting works consistently across document types:

from datetime import datetime
from decimal import Decimal

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

invoice = {
    "Amount": Decimal("1500.75"),
    "CreatedDate": datetime(2015, 1, 15, 14, 30, 0),
}

assembler = DocumentAssembler()
assembler.assemble_document("invoice-formatting.xlsx", "invoice-formatting-report.xlsx",
                            DataSourceInfo(invoice, "invoice"))

print("Formatting applied in spreadsheet successfully.")

Binary file (XLSX, 7 KB)

The spreadsheet template holds the same tags in its cells:

Warning

Format strings and text functions are case-sensitive. Use uppercase letters for standard format specifiers (C, N, F, P) and follow .NET formatting conventions exactly.

To learn more about custom format providers, culture-specific formatting, and advanced formatting scenarios, please refer to the advanced usage section.

You may easily run the code above and see the feature in action in our GitHub examples:

• GroupDocs.Assembly for .NET examples, plugins, and showcase
• GroupDocs.Assembly for Java examples, plugins, and showcase
• GroupDocs.Assembly for Python via .NET examples, plugins, and showcase

Along with the full-featured library, we provide simple but powerful free online apps.

To assemble documents from templates and data sources, you can use the online apps from the GroupDocs.Assembly App Product Family.