DEV Community: Allen Yang

Managing Word Document Sections and Page Setup with Python

Allen Yang — Wed, 15 Apr 2026 09:35:01 +0000

When working with Word documents, sections are a fundamental concept that every developer should understand. Each section can have its own independent page settings, including margins, paper size, and page orientation. By programmatically managing document sections, you can automate tasks such as batch-adjusting page layouts or merging documents with different formatting requirements.

This article demonstrates how to use Python to add, delete, clone, and modify page settings for sections in Word documents.

Environment Setup

First, install the Spire.Doc library:

pip install Spire.Doc

This library provides a comprehensive API for Word document operations, including full support for section-level manipulations.

Understanding Document Sections

A Word document consists of one or more sections. By default, a newly created document contains a single section. Multiple sections become necessary when different parts of a document require different page configurations. Common use cases include:

Mixing portrait and landscape pages within the same document
Using different margins for different chapters
Setting distinct headers and footers for each section

Adding and Deleting Sections

Adding a New Section

The AddSection() method appends a new section to the end of the document:

from spire.doc import *
from spire.doc.common import *

# Load the document
doc = Document()
doc.LoadFromFile("input.docx")

# Add a new section
doc.AddSection()

# Save the document
doc.SaveToFile("output.docx", FileFormat.Docx2019)
doc.Close()

The newly added section inherits the page settings from the previous section. If you need different settings, modify them after adding the section.

Deleting a Section

Access all sections through the Sections collection and use the RemoveAt() method to delete a section at a specific index:

from spire.doc import *
from spire.doc.common import *

doc = Document()
doc.LoadFromFile("input.docx")

# Delete the last section
if doc.Sections.Count > 1:
    doc.Sections.RemoveAt(doc.Sections.Count - 1)

doc.SaveToFile("output.docx", FileFormat.Docx2019)
doc.Close()

When deleting sections, remember that a document must retain at least one section. Always check the section count before performing deletions.

Cloning Section Content

Section cloning is particularly useful when merging multiple documents or reusing specific content. The Clone() method creates a complete copy of a section, including all its content and formatting:

from spire.doc import *
from spire.doc.common import *

# Load the source document
srcDoc = Document()
srcDoc.LoadFromFile("source.docx")

# Create a destination document
desDoc = Document()

# Clone all sections
for i in range(srcDoc.Sections.Count):
    section = srcDoc.Sections.get_Item(i)
    # Clone the section
    cloneSection = section.Clone()
    # Add to the destination document
    desDoc.Sections.Add(cloneSection)

desDoc.SaveToFile("output.docx", FileFormat.Docx2019)
desDoc.Close()

This approach is ideal for merging multiple documents while preserving each document's original structure and formatting.

Modifying Section Page Setup

Each section has its own PageSetup property that controls margins, paper size, and other page parameters.

Setting Margins

from spire.doc import *
from spire.doc.common import *

doc = Document()
doc.LoadFromFile("input.docx")

# Iterate through all sections
for i in range(doc.Sections.Count):
    section = doc.Sections.get_Item(i)
    # Set margins (left, top, right, bottom) in points
    section.PageSetup.Margins = MarginsF(100.0, 80.0, 100.0, 80.0)

doc.SaveToFile("output.docx", FileFormat.Docx2019)
doc.Close()

The MarginsF() method accepts four parameters in order: left margin, top margin, right margin, and bottom margin. All values are specified in points (1 point ≈ 0.35 mm).

Setting Paper Size

from spire.doc import *
from spire.doc.common import *

doc = Document()
doc.LoadFromFile("input.docx")

# Modify the paper size of the first section
section = doc.Sections.get_Item(0)
section.PageSetup.PageSize = PageSize.Letter()

doc.SaveToFile("output.docx", FileFormat.Docx2019)
doc.Close()

The PageSize class provides several predefined paper sizes, such as A4(), Letter(), and Legal(). You can also define custom dimensions:

# Custom paper size (width and height in points)
section.PageSetup.PageSize = SizeF(612.0, 792.0)

Setting Page Orientation

Control page orientation through the Orientation property:

from spire.doc import *
from spire.doc.common import *

doc = Document()
doc.LoadFromFile("input.docx")

# Set the second section to landscape orientation
if doc.Sections.Count > 1:
    section = doc.Sections.get_Item(1)
    section.PageSetup.Orientation = PageOrientation.Landscape

doc.SaveToFile("output.docx", FileFormat.Docx2019)
doc.Close()

The PageOrientation enumeration includes Portrait and Landscape values.

Practical Example

The following example demonstrates how to create a document with mixed page orientations:

from spire.doc import *
from spire.doc.common import *

# Create a new document
doc = Document()

# First section: Portrait A4
section1 = doc.Sections.get_Item(0)
section1.PageSetup.PageSize = PageSize.A4()
section1.PageSetup.Orientation = PageOrientation.Portrait
section1.PageSetup.Margins = MarginsF(72.0, 72.0, 72.0, 72.0)

# Add content to the first section
paragraph1 = section1.AddParagraph()
paragraph1.AppendText("This is the first section with portrait A4 paper.")

# Add a second section: Landscape A4
section2 = doc.AddSection()
section2.PageSetup.PageSize = PageSize.A4()
section2.PageSetup.Orientation = PageOrientation.Landscape
section2.PageSetup.Margins = MarginsF(50.0, 50.0, 50.0, 50.0)

# Add content to the second section
paragraph2 = section2.AddParagraph()
paragraph2.AppendText("This is the second section with landscape A4 paper.")

doc.SaveToFile("mixed_orientation.docx", FileFormat.Docx2019)
doc.Close()

This example creates a document with two sections: the first uses portrait orientation, while the second uses landscape. This is particularly useful when a single document needs to display content in different orientations.

Important Considerations

When working with document sections, keep these points in mind:

Section indices start at 0; always validate indices before accessing sections
Deleting a section removes all content within that section
Cloning a section copies all content, including text, images, and tables
Page setup changes affect the entire section's appearance

Conclusion

Managing Word document sections with Python provides flexible control over page layout and formatting. This article covered the essential operations: adding, deleting, and cloning sections, as well as modifying page settings. These techniques are particularly valuable for document automation tasks, especially when batch-adjusting formats or merging documents with different layouts. By building on these fundamental operations, you can implement more sophisticated document processing workflows tailored to your specific requirements.

Automating Word Headers and Footers in Python

Allen Yang — Tue, 14 Apr 2026 02:31:34 +0000

Adding and Setting Headers and Footers in Word Documents Using Python

Headers and footers are commonly used elements in Word documents, displaying consistent information at the top or bottom of each page, such as document titles, company names, and page numbers. When processing large volumes of documents or adding headers and footers in batches, manual operations can be inefficient. Python can automate these tasks, improving document processing efficiency.

This article demonstrates how to add and set headers and footers in Word documents using Python and the Spire.Doc library, including common operations such as adding text, images, page numbers, and setting different headers and footers for odd and even pages.

Environment Setup

First, install the Spire.Doc library:

pip install spire.doc

After installation, the relevant functionality can be imported and used in Python code.

Basic Concepts

Before writing code, it is important to understand several basic concepts:

Section: A Word document consists of one or more sections, each with its own header and footer settings
Header: The area located at the top of the page
Footer: The area located at the bottom of the page
Paragraph: Content in headers and footers is organized and displayed through paragraphs

Adding Basic Headers and Footers

The following example demonstrates how to add headers and footers containing text and images to a Word document:

from spire.doc import *
from spire.doc.common import *

# Create a document object and load the file
document = Document()
document.LoadFromFile("Sample.docx")

# Get the first section
section = document.Sections[0]

# Get header and footer objects
header = section.HeadersFooters.Header
footer = section.HeadersFooters.Footer

# Add a paragraph to the header
headerParagraph = header.AddParagraph()

# Add an image to the header
headerPicture = headerParagraph.AppendPicture("Header.png")

# Set image size and position
headerPicture.Width = 40
headerPicture.Height = 40
headerPicture.TextWrappingStyle = TextWrappingStyle.InFrontOfText
headerPicture.HorizontalAlignment = ShapeHorizontalAlignment.Left
headerPicture.VerticalAlignment = ShapeVerticalAlignment.Outside

# Add text to the header
text = headerParagraph.AppendText("Internal Company Document")
text.CharacterFormat.FontName = "Arial"
text.CharacterFormat.FontSize = 10
text.CharacterFormat.Italic = True

# Set header paragraph right alignment
headerParagraph.Format.HorizontalAlignment = HorizontalAlignment.Right

# Add bottom border line
headerParagraph.Format.Borders.Bottom.BorderType = BorderStyle.Single
headerParagraph.Format.Borders.Bottom.Space = 0.05

# Add a paragraph to the footer
footerParagraph = footer.AddParagraph()

# Add page number field
footerParagraph.AppendField("page number", FieldType.FieldPage)
footerParagraph.AppendText(" / ")
footerParagraph.AppendField("number of pages", FieldType.FieldNumPages)

# Set footer paragraph center alignment
footerParagraph.Format.HorizontalAlignment = HorizontalAlignment.Center

# Save the document
document.SaveToFile("HeaderAndFooter.docx", FileFormat.Docx)
document.Close()

Below is the generated document's header and footer:

This code first loads an existing Word document, then retrieves the first section of the document. The header and footer objects are accessed through the HeadersFooters property, paragraphs are added using the AddParagraph() method, and images and text content are added via the AppendPicture() and AppendText() methods.

Setting Different Headers and Footers for Odd and Even Pages

In formal documents, it is often necessary to set different headers and footers for odd and even pages. For example, odd pages may display chapter titles while even pages display the document name. The following code demonstrates how to implement this functionality:

from spire.doc import *
from spire.doc.common import *

# Load the document
doc = Document()
doc.LoadFromFile("MultiplePages.docx")

# Get the first section
section = doc.Sections[0]

# Enable different headers and footers for odd and even pages
section.PageSetup.DifferentOddAndEvenPagesHeaderFooter = True

# Add odd page header
oddHeaderPara = section.HeadersFooters.OddHeader.AddParagraph()
oddHeaderText = oddHeaderPara.AppendText("Odd Page Header - Chapter Title")
oddHeaderPara.Format.HorizontalAlignment = HorizontalAlignment.Center
oddHeaderText.CharacterFormat.FontName = "Arial"
oddHeaderText.CharacterFormat.FontSize = 10

# Add even page header
evenHeaderPara = section.HeadersFooters.EvenHeader.AddParagraph()
evenHeaderText = evenHeaderPara.AppendText("Even Page Header - Document Name")
evenHeaderPara.Format.HorizontalAlignment = HorizontalAlignment.Center
evenHeaderText.CharacterFormat.FontName = "Arial"
evenHeaderText.CharacterFormat.FontSize = 10

# Add odd page footer
oddFooterPara = section.HeadersFooters.OddFooter.AddParagraph()
oddFooterText = oddFooterPara.AppendText("Odd Page Footer")
oddFooterPara.Format.HorizontalAlignment = HorizontalAlignment.Center

# Add even page footer
evenFooterPara = section.HeadersFooters.EvenFooter.AddParagraph()
evenFooterText = evenFooterPara.AppendText("Even Page Footer")
evenFooterPara.Format.HorizontalAlignment = HorizontalAlignment.Center

# Save the document
doc.SaveToFile("OddAndEvenHeaderFooter.docx", FileFormat.Docx)
doc.Close()

The generated document's header and footer are shown below:

The key step is to set the DifferentOddAndEvenPagesHeaderFooter property to True, then access and set the headers and footers for odd and even pages separately through the OddHeader, EvenHeader, OddFooter, and EvenFooter properties.

Setting Different First Page Header and Footer

Some documents require special headers and footers for the first page, or no headers and footers on the first page. This can be achieved as follows:

from spire.doc import *
from spire.doc.common import *

# Load the document
doc = Document()
doc.LoadFromFile("Sample.docx")

# Get the first section
section = doc.Sections[0]

# Enable different first page header and footer
section.PageSetup.DifferentFirstPageHeaderFooter = True

# Set first page header (can be left empty to hide header on first page)
firstHeaderPara = section.HeadersFooters.FirstPageHeader.AddParagraph()
firstHeaderText = firstHeaderPara.AppendText("First Page Specific Header")
firstHeaderPara.Format.HorizontalAlignment = HorizontalAlignment.Center

# Set regular header (for pages other than the first page)
headerPara = section.HeadersFooters.Header.AddParagraph()
headerText = headerPara.AppendText("Regular Header")
headerPara.Format.HorizontalAlignment = HorizontalAlignment.Right

# Save the document
doc.SaveToFile("FirstPageHeader.docx", FileFormat.Docx)
doc.Close()

The generated document's header and footer are shown below:

By setting the DifferentFirstPageHeaderFooter property to True, the first page's header and footer can be set using the FirstPageHeader and FirstPageFooter properties.

Adjusting Header and Footer Height

The height of headers and footers can be adjusted through the HeaderDistance and FooterDistance properties:

from spire.doc import *
from spire.doc.common import *

# Load the document
doc = Document()
doc.LoadFromFile("Sample.docx")

# Get the first section
section = doc.Sections[0]

# Set the distance from the header to the top of the page (unit: points)
section.PageSetup.HeaderDistance = 50

# Set the distance from the footer to the bottom of the page (unit: points)
section.PageSetup.FooterDistance = 50

# Add header content
header = section.HeadersFooters.Header
headerPara = header.AddParagraph()
headerPara.AppendText("Header with Adjusted Height")

# Save the document
doc.SaveToFile("AdjustedHeight.docx", FileFormat.Docx)
doc.Close()

Below is a preview of the generated Word document:

Practical Tips

Adding Page Number Formats

Page numbers are the most common element in footers and can be added in various formats:

footerParagraph = footer.AddParagraph()

# Add "Page X" format
footerParagraph.AppendText("Page ")
footerParagraph.AppendField("page number", FieldType.FieldPage)

# Add "Page X of Y" format
footerParagraph.AppendText("Page ")
footerParagraph.AppendField("page number", FieldType.FieldPage)
footerParagraph.AppendText(" of ")
footerParagraph.AppendField("number of pages", FieldType.FieldNumPages)

Adding Separator Lines

Adding separator lines to headers or footers can enhance visual effects:

# Add separator line at the bottom of the header
headerParagraph.Format.Borders.Bottom.BorderType = BorderStyle.Single
headerParagraph.Format.Borders.Bottom.Color = Color.get_Gray()
headerParagraph.Format.Borders.Bottom.LineWidth = 0.5

# Add separator line at the top of the footer
footerParagraph.Format.Borders.Top.BorderType = BorderStyle.Single
footerParagraph.Format.Borders.Top.Color = Color.get_Gray()
footerParagraph.Format.Borders.Top.LineWidth = 0.5

Setting Image Size and Position

When adding images to headers and footers, the image position can be precisely controlled:

picture = headerParagraph.AppendPicture("Logo.png")

# Set image size
headerPicture.Width = 40
headerPicture.Height = 40

# Set text wrapping style
picture.TextWrappingStyle = TextWrappingStyle.Behind

# Set horizontal position
picture.HorizontalOrigin = HorizontalOrigin.Page
picture.HorizontalAlignment = ShapeHorizontalAlignment.Left

# Set vertical position
picture.VerticalOrigin = VerticalOrigin.Page
picture.VerticalAlignment = ShapeVerticalAlignment.Top

Summary

This article has introduced various methods for adding and setting headers and footers in Word documents using Python, including adding text and images, setting different headers and footers for odd and even pages, special handling for the first page, adjusting height, and other common operations. These techniques enable efficient batch processing of documents and automated header and footer configuration.

In practical applications, these methods can be combined according to specific requirements. For example, professional headers and footers containing company logos, document titles, and page numbers can be created for formal reports, or different header and footer styles for odd and even pages can be set up for book typesetting. Mastering these techniques can significantly improve the efficiency and standardization of document processing.

Split Word Documents with Python: Chapters and Page Breaks

Allen Yang — Fri, 10 Apr 2026 10:37:55 +0000

When working with large Word documents, we often need to split a complete document into multiple independent smaller documents. For example, splitting reports containing multiple chapters by chapter, or separating long contracts by page. Manually completing these operations is not only time-consuming but also prone to errors. This article will introduce how to use Python to automate Word document splitting, supporting two methods: splitting by page breaks and section breaks.

Why Split Word Documents

In practical work, the following scenarios frequently require document splitting:

Chapter Separation: Split technical manuals, books, or reports containing multiple chapters into independent files by chapter
On-Demand Distribution: Extract specific sections from a master document based on different recipients' needs
Parallel Processing: Split large documents into smaller segments for easier multi-person collaborative editing
Archive Management: Decompose historical documents by time or theme into more manageable units
Format Conversion: Split documents by logical structure before converting to other formats

Implementing document splitting programmatically can significantly improve processing efficiency, especially in batch processing scenarios.

Environment Setup

First, install the Spire.Doc for Python library:

pip install Spire.Doc

This library provides a complete Word document operation API, supporting document splitting, merging, formatting, and other features, without requiring Microsoft Word to be installed.

Splitting Documents by Section Breaks

Section breaks are markers in Word used to divide the logical structure of a document, typically used to distinguish different chapters or sections. Splitting by section breaks is the most common document segmentation method.

Basic Splitting Example

The following code demonstrates how to split a Word document containing multiple sections into independent files:

from spire.doc import Document

inputFile = "./Data/Multi-Chapter Report.docx"
outputFolder = "Split_Results_By_Section/"

# Load the source document
document = Document()
document.LoadFromFile(inputFile)

# Iterate through all sections in the document
for i in range(document.Sections.Count):
    # Get the current section
    section = document.Sections.get_Item(i)

    # Create a new document
    newWord = Document()

    # Clone the current section and add it to the new document
    newWord.Sections.Add(section.Clone())

    # Generate output filename
    result = outputFolder + "Chapter_{}.docx".format(i + 1)

    # Save the new document
    newWord.SaveToFile(result)
    newWord.Close()

document.Close()
print("Document splitting completed, generated {} files".format(document.Sections.Count))

In this example:

The LoadFromFile() method loads the source Word document
Sections.Count gets the number of sections in the document
get_Item(i) retrieves the section object at the specified index
The Clone() method copies the complete content and formatting of the section
Each section is saved as an independent .docx file

The advantage of this method is that it maintains the integrity and independence of each chapter, including headers, footers, page settings, and other properties.

Understanding the Role of Section Breaks

Section breaks not only mark chapter boundaries but can also control:

Page Orientation: Some chapters may be landscape while others are portrait
Margins: Different chapters can have different margin settings
Headers and Footers: Each chapter can have independent header and footer content
Page Number Format: Each chapter can restart numbering

When splitting by section breaks, these properties are completely preserved in the corresponding sub-documents.

Splitting Documents by Page Breaks

Sometimes we need finer-grained splitting, such as dividing documents by page. This method is suitable for scenarios where each page needs to be an independent file, such as invoices, certificates, or forms.

Splitting by Page Example

Splitting by page breaks is more complex than splitting by sections, as it requires traversing document content paragraph by paragraph and identifying page break positions:

from spire.doc import Document, BreakType
from spire.doc.common import Paragraph

inputFile = "./Data/Multi-Page Document.docx"
outputFolder = "Split_Results_By_Page/"

# Load the source document
original = Document()
original.LoadFromFile(inputFile)

# Create a new document and add a section
newWord = Document()
section = newWord.AddSection()

# Clone styles and themes to maintain consistent formatting
original.CloneDefaultStyleTo(newWord)
original.CloneThemesTo(newWord)
original.CloneCompatibilityTo(newWord)

index = 0

# Iterate through all sections in the source document
for m in range(original.Sections.Count):
    sec = original.Sections.get_Item(m)

    # Iterate through all child objects in the section
    for k in range(sec.Body.ChildObjects.Count):
        obj = sec.Body.ChildObjects.get_Item(k)

        if isinstance(obj, Paragraph):
            para = obj

            # Clone section properties to the new document's section
            sec.CloneSectionPropertiesTo(section)

            # Add the paragraph to the new document
            section.Body.ChildObjects.Add(para.Clone())

            # Check if the paragraph contains a page break
            for j in range(para.ChildObjects.Count):
                parobj = para.ChildObjects.get_Item(j)

                if isinstance(parobj, Break) and parobj.BreakType == BreakType.PageBreak:
                    # Get the position of the page break within the paragraph
                    i = para.ChildObjects.IndexOf(parobj)

                    # Remove the page break itself
                    section.Body.LastParagraph.ChildObjects.RemoveAt(i)

                    # Save the current page as an independent file
                    resultF = outputFolder + "Page_{}.docx".format(index + 1)
                    newWord.SaveToFile(resultF, FileFormat.Docx)
                    index += 1

                    # Create a new document object for the next page
                    newWord = Document()
                    section = newWord.AddSection()

                    # Re-clone styles and themes
                    original.CloneDefaultStyleTo(newWord)
                    original.CloneThemesTo(newWord)
                    original.CloneCompatibilityTo(newWord)

                    # Clone section properties
                    sec.CloneSectionPropertiesTo(section)

                    # Add the current paragraph to the new document
                    section.Body.ChildObjects.Add(para.Clone())

                    # Handle content before and after the page break
                    if section.Paragraphs[0].ChildObjects.Count == 0:
                        # If the paragraph is empty, remove it
                        section.Body.ChildObjects.RemoveAt(0)
                    else:
                        # Remove content before the page break
                        while i >= 0:
                            section.Paragraphs[0].ChildObjects.RemoveAt(i)
                            i -= 1

        elif isinstance(obj, Table):
            # Handle table objects
            section.Body.ChildObjects.Add(obj.Clone())

# Save the last page
result = outputFolder + "Page_{}.docx".format(index + 1)
newWord.SaveToFile(result, FileFormat.Docx2013)
newWord.Close()
original.Close()

print("Document splitting by page completed, generated {} files".format(index + 1))

Key points in this example:

Traversal Structure: Traverse the document tree section by section, paragraph by paragraph, and object by object
Page Break Detection: Detect breakpoints of type BreakType.PageBreak
Content Division: Cut the content flow at page breaks and save to different documents
Format Inheritance: Maintain style consistency through methods like CloneDefaultStyleTo()
Table Handling: Process table objects separately to ensure complete copying

Technical Details

Several technical points need attention when splitting by pages:

Page Break Position: Page breaks may appear in the middle of paragraphs, requiring precise positioning and division
Empty Paragraph Cleanup: Splitting may produce empty paragraphs that need to be cleaned up to keep documents tidy
Style Cloning: Must clone the source document's styles, themes, and compatibility settings, otherwise formatting will be lost
Section Property Copying: Use CloneSectionPropertiesTo() to ensure page settings are correctly transferred

Practical Application Scenarios

Scenario 1: Batch Processing Annual Reports

Suppose a company has annual reports from 50 departments merged into one document, with one chapter per department:

import os
from spire.doc import Document

def split_annual_report(input_file, output_dir):
    """Split annual report by chapters"""
    doc = Document()
    doc.LoadFromFile(input_file)

    # Ensure output directory exists
    if not os.path.exists(output_dir):
        os.makedirs(output_dir)

    for i in range(doc.Sections.Count):
        section = doc.Sections.get_Item(i)
        new_doc = Document()
        new_doc.Sections.Add(section.Clone())

        # Extract department name from the first section title as filename
        first_para = section.Paragraphs[0] if section.Paragraphs.Count > 0 else None
        if first_para:
            dept_name = first_para.Text.strip().replace("/", "-")
            filename = "{}_Annual_Report.docx".format(dept_name)
        else:
            filename = "Department_{}_Annual_Report.docx".format(i + 1)

        filepath = os.path.join(output_dir, filename)
        new_doc.SaveToFile(filepath)
        new_doc.Close()

    doc.Close()
    print("Split {} department reports".format(doc.Sections.Count))

# Usage example
split_annual_report("./Data/Company_Annual_Summary_Report.docx", "./Department_Reports/")

Scenario 2: Extracting Specific Pages

If you need to extract specific pages from a document rather than splitting all pages:

from spire.doc import Document, BreakType

def extract_pages(input_file, page_numbers, output_dir):
    """Extract specified pages as independent documents"""
    original = Document()
    original.LoadFromFile(input_file)

    # Simplified handling here; actual implementation needs to calculate page numbers based on page breaks
    # Complete implementation refers to the previous page-by-page splitting logic

    original.Close()

# Extract pages 3, 5, and 7
extract_pages("./Data/Manual.docx", [3, 5, 7], "./Extracted_Pages/")

Best Practices and Considerations

When using document splitting functionality, it is recommended to follow these principles:

Backup Original Files: Splitting operations do not modify the original file, but it is advisable to back up important documents before processing
Check Section Breaks: Before splitting by sections, confirm that the document actually uses section breaks to divide the structure. You can enable "Show Editing Marks" in Word to view them
Handle Complex Formatting: If the document contains many complex elements such as images, tables, and text boxes, verify that formatting is correct after splitting
Memory Management: When processing very large documents, remember to call Close() and Dispose() in a timely manner to release resources
File Naming Conventions: Design clear naming rules for generated sub-documents to facilitate subsequent management and retrieval
Error Handling: Add exception handling in production environments to ensure that failure to split a single file does not affect the overall process
Performance Optimization: For large documents with hundreds of pages, page-by-page splitting may be slow; consider multi-threading or asynchronous processing

Combining with Other Document Operations

Document splitting can be combined with other Word operations to form complete workflows:

Split + Convert: First split the document, then convert each part to PDF or HTML
Split + Merge: Extract specific chapters from multiple documents and recombine them into a new document
Split + Annotate: Automatically add review annotations to split documents
Split + Protect: Set different password protection levels for different chapters

Summary

This article introduced two main methods for splitting Word documents using Python: splitting by section breaks and splitting by page breaks. Through these techniques, we can:

Automate the task of splitting large documents
Maintain formatting integrity in split documents
Flexibly respond to different business scenario requirements
Improve document processing efficiency and accuracy

Splitting by section breaks is suitable for documents with clear logical structures, offering simple implementation and good results; splitting by page breaks provides finer-grained control, suitable for scenarios requiring page-by-page processing. Choose the appropriate method based on actual needs, and combine it with other document operation features to build a powerful document automation processing system.

After mastering these skills, developers can easily handle various document splitting requirements, providing technical support for enterprise document management, content distribution, and collaborative editing. It is recommended to flexibly apply these methods in actual projects based on document characteristics and processing objectives, and combine them with error handling and logging to create stable and reliable document processing solutions.

Managing Word Document Properties and Statistics with Python

Allen Yang — Fri, 10 Apr 2026 10:32:17 +0000

In daily office automation scenarios, adding metadata to Word documents is an important means of improving document management efficiency. By setting document properties, we can record key information such as authors, titles, and keywords, facilitating subsequent retrieval, classification, and archiving. Additionally, obtaining document statistics (such as word count and character count) helps us better evaluate document content. This article introduces how to use Python to implement Word document property management and information statistics functionality.

Why Document Property Management is Needed

In practical work, document property management has the following important application scenarios:

Document Archiving: Add metadata such as authors, titles, and keywords to documents for easier retrieval and management
Compliance Requirements: Certain industries require recording metadata such as creators, company information, and managers in documents
Workflow Management: Mark document status (such as draft, under review, approved) using custom properties
Batch Processing: Uniformly set standardized properties for enterprise document libraries to improve management standardization

By processing these tasks programmatically, work efficiency can be significantly improved while reducing human errors.

Environment Setup

First, install the Spire.Doc for Python library:

pip install Spire.Doc

This library provides a complete Word document operation API, supporting document property settings, statistics retrieval, and other functions without requiring Microsoft Word installation.

Managing Built-in Document Properties

Word documents contain rich built-in properties (also known as metadata), such as title, author, subject, and company. This information is crucial for document classification, search, and management. It can be viewed in Windows File Explorer or accessed through Word's "File > Info > Properties" panel.

Setting and Reading Built-in Properties

The following code demonstrates how to set and read various built-in properties for a Word document:

from spire.doc import Document, FileFormat

# Load document
document = Document()
document.LoadFromFile("Report Template.docx")

# Set built-in document properties
document.BuiltinDocumentProperties.Title = "2024 Annual Financial Report"
document.BuiltinDocumentProperties.Subject = "Financial Analysis"
document.BuiltinDocumentProperties.Author = "Li Ming"
document.BuiltinDocumentProperties.Company = "ABC Technology Co., Ltd."
document.BuiltinDocumentProperties.Manager = "Manager Wang"
document.BuiltinDocumentProperties.Category = "Financial Report"
document.BuiltinDocumentProperties.Keywords = "finance, report, 2024, analysis"
document.BuiltinDocumentProperties.Comments = "This document contains the company's 2024 annual financial data analysis"

# Save document
document.SaveToFile("Report with Properties.docx", FileFormat.Docx)
document.Close()

# Read the set properties
print(f"Title: {document.BuiltinDocumentProperties.Title}")
print(f"Author: {document.BuiltinDocumentProperties.Author}")
print(f"Company: {document.BuiltinDocumentProperties.Company}")
print(f"Keywords: {document.BuiltinDocumentProperties.Keywords}")

Common built-in properties include: Title (document title), Subject (subject), Author (author), Company (company name), Manager (manager), Category (category), Keywords (keywords, separated by commas), Comments (remarks), etc. This is very useful when batch processing documents, allowing documents to be classified or filtered based on property values.

Managing Custom Document Properties

In addition to built-in properties, Spire.Doc also supports adding custom properties, which are very useful for specific business scenarios. For example, marking workflow status (draft, under review, approved), recording version numbers, adding project numbers, and other business-related information. Notably, the _MarkAsFinal property can be used to mark a document as final, indicating to users that it should not be modified further.

Setting and Reading Custom Properties

from spire.doc import Document, FileFormat
from spire.doc.common import Boolean

# Load document
document = Document()
document.LoadFromFile("Project Document.docx")

# Get custom properties collection
customProperties = document.CustomDocumentProperties

# Add custom properties
customProperties.Add("Project Name", "Intelligent Office System")
customProperties.Add("Version Number", "2.0")
customProperties.Add("Review Status", "Approved")
customProperties.Add("_MarkAsFinal", Boolean(True))

# Save document
document.SaveToFile("Document with Custom Properties.docx", FileFormat.Docx2013)
document.Close()
document.Dispose()

# Read custom properties
document2 = Document()
document2.LoadFromFile("Document with Custom Properties.docx")
for i in range(document2.CustomDocumentProperties.Count):
    prop = document2.CustomDocumentProperties.get_Item(i)
    print(f"{prop.Name}: {prop.Value}")
document2.Close()

Note that some custom properties may not be directly displayed in the Word interface but can be accessed through the API.

Retrieving Document Statistics

In certain scenarios, we need to obtain basic document statistics such as word count and character count. This is useful for evaluating document length, calculating translation workload, generating document summary reports, and other scenarios.

from spire.doc import Document

# Load document
document = Document()
document.LoadFromFile("Long Document.docx")

# Get document statistics
char_count = document.BuiltinDocumentProperties.CharCount
char_count_with_space = document.BuiltinDocumentProperties.CharCountWithSpace
word_count = document.BuiltinDocumentProperties.WordCount

print(f"Character count (excluding spaces): {char_count}")
print(f"Character count (including spaces): {char_count_with_space}")
print(f"Word count: {word_count}")

document.Close()

Practical Application Example: Batch Processing Document Properties

The following is a comprehensive example showing how to batch set unified properties for multiple documents:

from spire.doc import Document, FileFormat
import os

def set_document_properties(file_path, author, company, keywords):
    """Set unified properties for a document"""
    doc = Document()
    doc.LoadFromFile(file_path)

    # Set properties
    doc.BuiltinDocumentProperties.Author = author
    doc.BuiltinDocumentProperties.Company = company
    doc.BuiltinDocumentProperties.Keywords = keywords

    # Save (overwrite original file)
    doc.SaveToFile(file_path, FileFormat.Docx)
    doc.Close()

    print(f"Processed: {file_path}")

# Batch process all Word documents in a folder
folder_path = "./Documents to Process"
author = "Technical Department"
company = "XYZ Company"
keywords = "technical documentation, internal materials"

for filename in os.listdir(folder_path):
    if filename.endswith(".docx"):
        file_path = os.path.join(folder_path, filename)
        set_document_properties(file_path, author, company, keywords)

print("Batch processing completed")

This example demonstrates how to apply document property management to actual workflows, especially suitable for enterprise document standardization scenarios.

Important Considerations

When using document property management features, please note the following points:

Property Visibility: Some custom properties may not be directly displayed in the Word interface but can be accessed through the API
Resource Release: Be sure to call the Close() and Dispose() methods after processing documents to release resources
File Format: It is recommended to use Docx or Docx2013 format to ensure compatibility
Large File Processing: For large documents, property operations may take a long time; it is advisable to execute them in background threads

Summary

This article introduced a complete solution for managing Word document properties and statistics using Python. Through these techniques, we can:

Add rich metadata to documents to improve management efficiency
Batch process document properties to achieve standardization
Retrieve document statistics to support decision-making
Mark document status and versions to optimize workflows

These features have wide applications in document management systems, collaborative office platforms, contract management, and other scenarios. Combined with other Word operation functions, complete document automation processing solutions can be built to significantly improve work efficiency.

With the development of office automation, mastering these programming skills will bring significant value to developers and enterprises. It is recommended to combine these basic functions according to specific business needs to create automated tools suitable for your own workflows.

Generate Professional Bar Charts in Excel Using Python

Allen Yang — Wed, 08 Apr 2026 09:39:45 +0000

In data analysis and report generation scenarios, data visualization is a key means to enhance information delivery efficiency. As one of the most commonly used chart types, bar charts can intuitively display numerical comparisons between different categories. By automatically generating Excel bar charts with Python, not only can large amounts of data be processed in batches, but also the consistency and professionalism of chart formatting can be ensured.

This article introduces how to use the Spire.XLS for Python library to create bar charts in Excel worksheets and customize chart elements such as titles, axes, data labels, and legends. This solution is suitable for scenarios that require dynamic report generation, automated data analysis workflows, or batch export of visualization results.

Environment Setup

First, install the Spire.XLS for Python library:

pip install Spire.XLS

This library provides a complete Excel document operation API, supporting creating, reading, modifying, and converting Excel files without requiring Microsoft Excel application installation.

Core Implementation

Creating Workbook and Populating Data

The first step in creating a bar chart is to prepare the data source. Categorical data and corresponding numerical data need to be organized in the Excel worksheet.

from spire.xls.common import *
from spire.xls import *

def CreateChartData(sheet):
    # Set headers and data
    sheet.Range["A1"].Value = "Country"
    sheet.Range["A2"].Value = "Cuba"
    sheet.Range["A3"].Value = "Mexico"
    sheet.Range["A4"].Value = "France"
    sheet.Range["A5"].Value = "Germany"

    sheet.Range["B1"].Value = "June"
    sheet.Range["B2"].NumberValue = 6000
    sheet.Range["B3"].NumberValue = 8000
    sheet.Range["B4"].NumberValue = 9000
    sheet.Range["B5"].NumberValue = 8500

    sheet.Range["C1"].Value = "August"
    sheet.Range["C2"].NumberValue = 3000
    sheet.Range["C3"].NumberValue = 2000
    sheet.Range["C4"].NumberValue = 2300
    sheet.Range["C5"].NumberValue = 4200

    # Set cell styles
    sheet.Range["A1:C1"].RowHeight = 15
    sheet.Range["A1:C1"].Style.Color = Color.get_DarkGray()
    sheet.Range["A1:C1"].Style.Font.Color = Color.get_White()
    sheet.Range["A1:C1"].Style.VerticalAlignment = VerticalAlignType.Center
    sheet.Range["A1:C1"].Style.HorizontalAlignment = HorizontalAlignType.Center
    sheet.Range["B2:C5"].Style.NumberFormat = "\"$\"#,##0"

# Create workbook
workbook = Workbook()
sheet = workbook.Worksheets[0]
sheet.Name = "Sales Data"

# Populate chart data
CreateChartData(sheet)

The above code creates a data table with three columns: the first column contains country names (categories), and the second and third columns contain sales data for June and August respectively. By setting cell styles, the header has a dark background with white font, and the value area uses currency format display.

Creating Basic Bar Chart

After data preparation is complete, a bar chart object can be created based on these data ranges.

# Add chart to worksheet
chart = sheet.Charts.Add()

# Set chart data range
chart.DataRange = sheet.Range["A1:C5"]
chart.SeriesDataFromRange = False

# Set chart position and size
chart.LeftColumn = 1
chart.TopRow = 6
chart.RightColumn = 11
chart.BottomRow = 29

# Set chart type to clustered column chart
chart.ChartType = ExcelChartType.ColumnClustered

The Charts.Add() method creates a new chart object in the worksheet. The data range used by the chart is specified through the DataRange property, and SeriesDataFromRange is set to False to indicate manual series data configuration. The chart position is defined by row and column indices, placing the chart below the data here.

Customizing Chart Title and Axes

Chart readability largely depends on the clarity of titles and axes.

# Set chart title
chart.ChartTitle = "Sales Market Analysis by Country"
chart.ChartTitleArea.IsBold = True
chart.ChartTitleArea.Size = 12

# Set category axis (X-axis)
chart.PrimaryCategoryAxis.Title = "Country"
chart.PrimaryCategoryAxis.Font.IsBold = True
chart.PrimaryCategoryAxis.TitleArea.IsBold = True

# Set value axis (Y-axis)
chart.PrimaryValueAxis.Title = "Sales Amount (USD)"
chart.PrimaryValueAxis.HasMajorGridLines = False
chart.PrimaryValueAxis.MinValue = 1000
chart.PrimaryValueAxis.TitleArea.IsBold = True
chart.PrimaryValueAxis.TitleArea.TextRotationAngle = 90

PrimaryCategoryAxis represents the horizontal axis, used to display category labels; PrimaryValueAxis represents the vertical axis, used to display numerical scales. Setting HasMajorGridLines = False hides major gridlines, making the chart cleaner. The TextRotationAngle property allows rotation of the axis title angle, set to 90 degrees for vertical display here.

Configuring Data Series and Labels

The visual effect of data series directly impacts the chart's information delivery.

# Configure data series
for cs in chart.Series:
    cs.Format.Options.IsVaryColor = True
    cs.DataPoints.DefaultDataPoint.DataLabels.HasValue = True

IsVaryColor = True makes each data point use different colors, enhancing visual distinction. DataLabels.HasValue = True displays specific value labels above each bar, allowing readers to quickly obtain precise data.

Setting Legend Position

The legend helps readers understand what different colors represent.

# Set legend position
chart.Legend.Position = LegendPositionType.Top

Placing the legend at the top of the chart avoids obscuring the data area while maintaining a compact layout.

Saving the File

After completing all settings, save the workbook to a file.

# Save file
workbook.SaveToFile("ClusteredColumn.xlsx", ExcelVersion.Version2010)
workbook.Dispose()

Chart Effect Preview

Below is the bar chart effect created by the above operations:

Advanced Customization Features

Creating 3D Bar Charts

In addition to 2D bar charts, 3D bar charts with立体 effects can be created to enhance visual impact.

# Create workbook
workbook_3d = Workbook()
sheet_3d = workbook_3d.Worksheets[0]
sheet_3d.Name = "Sales Data"

# Populate data
CreateChartData(sheet_3d)

# Add 3D bar chart
chart_3d = sheet_3d.Charts.Add()
chart_3d.DataRange = sheet_3d.Range["A1:C5"]
chart_3d.SeriesDataFromRange = False

# Set position and size
chart_3d.LeftColumn = 1
chart_3d.TopRow = 6
chart_3d.RightColumn = 11
chart_3d.BottomRow = 29

# Set chart type to 3D clustered column chart
chart_3d.ChartType = ExcelChartType.Column3DClustered

# Set title and axes (same as 2D chart)
chart_3d.ChartTitle = "Sales Market Analysis by Country"
chart_3d.ChartTitleArea.IsBold = True
chart_3d.ChartTitleArea.Size = 12

chart_3d.PrimaryCategoryAxis.Title = "Country"
chart_3d.PrimaryCategoryAxis.Font.IsBold = True
chart_3d.PrimaryCategoryAxis.TitleArea.IsBold = True

chart_3d.PrimaryValueAxis.Title = "Sales Amount (USD)"
chart_3d.PrimaryValueAxis.HasMajorGridLines = False
chart_3d.PrimaryValueAxis.MinValue = 1000
chart_3d.PrimaryValueAxis.TitleArea.IsBold = True
chart_3d.PrimaryValueAxis.TitleArea.TextRotationAngle = 90

for cs in chart_3d.Series:
    cs.Format.Options.IsVaryColor = True
    cs.DataPoints.DefaultDataPoint.DataLabels.HasValue = True

chart_3d.Legend.Position = LegendPositionType.Top

# Save 3D chart file
workbook_3d.SaveToFile("ClusteredColumn_3D.xlsx", ExcelVersion.Version2010)
workbook_3d.Dispose()

Effect preview:

3D bar charts are implemented by setting ChartType to Column3DClustered. This chart type is particularly useful when displaying multi-level data or emphasizing depth perception.

Adjusting Chart Size and Position

In practical applications, it may be necessary to dynamically adjust the chart size and position according to page layout.

# Adjust chart position
chart.LeftColumn = 2
chart.TopRow = 8

# Adjust chart size
chart.RightColumn = 12
chart.BottomRow = 30

By modifying the LeftColumn, TopRow, RightColumn, and BottomRow properties, the position and dimensions of the chart in the worksheet can be precisely controlled.

Customizing Data Label Format

Data labels can be further customized to display richer information.

# Get the first data series
series = chart.Series[0]

# Customize data labels
for dataPoint in series.DataPoints:
    dataPoint.DataLabels.HasValue = True
    dataPoint.DataLabels.HasPercentage = False
    dataPoint.DataLabels.Font.Size = 10
    dataPoint.DataLabels.Font.Color = Color.get_Blue()

By iterating through data points, font size, color, and display content can be set individually for each data label.

Practical Tips

Batch Creating Multiple Charts

When multiple charts need to be created for different datasets, loop structures can be used to simplify the code.

datasets = [
    {"name": "Q1", "range": "A1:D5"},
    {"name": "Q2", "range": "F1:I5"},
    {"name": "Q3", "range": "A10:D14"}
]

for i, dataset in enumerate(datasets):
    chart = sheet.Charts.Add()
    chart.DataRange = sheet.Range[dataset["range"]]
    chart.ChartType = ExcelChartType.ColumnClustered
    chart.ChartTitle = dataset["name"]
    chart.TopRow = 6 + i * 25  # Arrange charts vertically

This method can quickly generate a series of uniformly formatted charts, suitable for quarterly reports or monthly analysis scenarios.

Exporting Charts as Images

Generated charts can be exported as image formats for embedding into other documents or web pages.

# Save chart as image
chart.SaveToImage("chart.png")

This feature allows charts to be reused in PowerPoint presentations, PDF reports, or web pages.

Summary

This article introduced the complete process of creating and customizing bar charts in Excel using Python. Through the Spire.XLS for Python library, the following functions can be easily implemented:

Create 2D and 3D bar charts based on worksheet data
Customize chart titles, axes, legends, and data labels
Adjust chart position, size, and visual styles
Batch generate multiple charts and export as images

These techniques can be applied to automated report generation, data visualization pipelines, and enterprise-level document processing systems. By combining different chart types and customization options, various complex data presentation requirements can be met.

Automate PowerPoint SmartArt with Python

Allen Yang — Fri, 03 Apr 2026 10:18:33 +0000

When creating professional PowerPoint presentations, SmartArt graphics serve as a powerful visualization tool capable of presenting complex information, processes, or hierarchical structures in an intuitive manner. Whether displaying organizational charts, flowcharts, cycles, or list information, SmartArt helps audiences quickly grasp key content points. This article provides an in-depth exploration of how to programmatically create, customize, and manipulate SmartArt graphics in PowerPoint presentations using Python.

Why Programmatically Generate SmartArt

Although manually creating SmartArt graphics is intuitive, it proves inefficient in the following scenarios:

Batch Report Generation: Creating SmartArt with identical structures for multiple departments or projects
Dynamic Data-Driven Content: Generating visual charts in real-time based on data returned from databases or APIs
Template Automation: Automatically generating standardized presentation documents in enterprise applications
Frequent Version Updates: Rapidly regenerating content when organizational structures or processes change frequently

By manipulating SmartArt through Python programming, automated processing for the above scenarios can be achieved, significantly improving work efficiency.

Environment Preparation

Before starting, install the Python library that supports PowerPoint operations. Spire.Presentation for Python provides comprehensive SmartArt manipulation APIs, including creation, style modification, node addition, and more.

pip install Spire.Presentation

After installation, import the relevant modules in your Python script. Note that manipulating SmartArt requires importing the ISmartArt interface and related enumeration types.

Basic SmartArt Creation

The first step in creating a SmartArt graphic is to initialize a presentation object, then add a SmartArt shape on the specified slide. SmartArt is created via the AppendSmartArt() method, which requires specifying position, dimensions, and layout type.

from spire.presentation.common import *
from spire.presentation import *

# Create presentation object
presentation = Presentation()

# Get the first slide
slide = presentation.Slides[0]

# Add SmartArt graphic
# Parameters: X coordinate, Y coordinate, width, height, layout type
smartArt = slide.Shapes.AppendSmartArt(
    200, 60, 300, 300, 
    SmartArtLayoutType.Gear
)

# Save document
presentation.SaveToFile("output.pptx", FileFormat.Pptx2010)
presentation.Dispose()

The code above creates a basic gear-shaped SmartArt graphic. The SmartArtLayoutType enumeration defines multiple predefined layout styles, each suitable for different information display scenarios.

SmartArt Layout Types Explained

SmartArt offers rich layout options, and selecting the appropriate layout is crucial for effective communication. Common layout types include:

List Layouts

Suitable for displaying parallel items or key points:

# Horizontal bullet list
smartArt = slide.Shapes.AppendSmartArt(
    100, 100, 400, 200,
    SmartArtLayoutType.HorizontalBulletList
)

Process Layouts

Used to display steps, sequences, or workflows:

# Basic process
smartArt = slide.Shapes.AppendSmartArt(
    100, 100, 500, 150,
    SmartArtLayoutType.BasicProcess
)

Cycle Layouts

Ideal for displaying periodic or iterative concepts:

# Cycle diagram
smartArt = slide.Shapes.AppendSmartArt(
    150, 100, 350, 350,
    SmartArtLayoutType.Cycle
)

Hierarchy Layouts

Commonly used for organizational charts or tree structures:

# Organization chart
smartArt = slide.Shapes.AppendSmartArt(
    100, 50, 500, 400,
    SmartArtLayoutType.OrganizationChart
)

Relationship Layouts

Display connections or relationships between components:

# Radial diagram
smartArt = slide.Shapes.AppendSmartArt(
    150, 100, 400, 400,
    SmartArtLayoutType.Radial
)

Other common layouts include matrix, pyramid, picture lists, etc. Selecting the appropriate layout type should be based on the logical structure of the information being conveyed.

Adding and Removing Nodes

After creating SmartArt, custom content typically needs to be added. Each SmartArt graphic consists of multiple nodes, each containing text and potentially child nodes.

Adding New Nodes

# Clear default nodes
to_remove = []
for node in smartArt.Nodes:
    to_remove.append(node)
for subnode in to_remove:
    smartArt.Nodes.RemoveNode(subnode)

# Add custom nodes
node1 = smartArt.Nodes.AddNode()
node1.TextFrame.Text = "First Item"

node2 = smartArt.Nodes.AddNode()
node2.TextFrame.Text = "Second Item"

node3 = smartArt.Nodes.AddNode()
node3.TextFrame.Text = "Third Item"

The AddNode() method adds a new node to the SmartArt. For hierarchy layouts, child nodes can also be added to build tree structures.

Adding Child Nodes

For organizational charts and other hierarchies, child nodes can be added:

# Add child nodes to parent node
parentNode = smartArt.Nodes.AddNode()
parentNode.TextFrame.Text = "General Manager"

childNode1 = parentNode.Nodes.AddNode()
childNode1.TextFrame.Text = "Department Manager A"

childNode2 = parentNode.Nodes.AddNode()
childNode2.TextFrame.Text = "Department Manager B"

Complex hierarchical structures can be built by recursively adding child nodes.

Removing Nodes

When specific nodes need to be deleted, use the RemoveNode() method:

# Remove the first node
if smartArt.Nodes.Count > 0:
    smartArt.Nodes.RemoveNode(smartArt.Nodes[0])

Note that after removing nodes, remaining nodes automatically adjust their positions and layout.

Setting Node Text Styles

Each node's text can be formatted through the TextFrame property, including font, color, size, etc.:

node = smartArt.Nodes.AddNode()
node.TextFrame.Text = "Important Title"

# Set text fill style
node.TextFrame.TextRange.Fill.FillType = FillFormatType.Solid
node.TextFrame.TextRange.Fill.SolidColor.KnownColor = KnownColors.Black

# Set font size (via FontHeight property)
node.TextFrame.TextRange.FontHeight = 18

# Set bold
node.TextFrame.TextRange.IsBold = True

Text style settings are similar to regular text boxes but remain constrained by the overall SmartArt style.

SmartArt Color Styles

SmartArt provides various preset color schemes that can be quickly applied through the ColorStyle property:

# Set colorful theme
smartArt.ColorStyle = SmartArtColorType.ColorfulAccentColors

# Set monochromatic gradient
smartArt.ColorStyle = SmartArtColorType.GradientLoopAccent3

# Set colored fill
smartArt.ColorStyle = SmartArtColorType.ColoredFillAccent1

The SmartArtColorType enumeration defines dozens of color schemes, including monochromatic, multicolor, gradient, and other styles. Selecting appropriate color schemes maintains consistency with the overall presentation theme.

SmartArt Style Effects

Beyond colors, SmartArt supports various visual effect styles set through the Style property:

# Set 3D effect
smartArt.Style = SmartArtStyleType.ThreeD

# Set flat effect
smartArt.Style = SmartArtStyleType.Flat

# Set subtle effect
smartArt.Style = SmartArtStyleType.SubtleEffect

# Set intense effect
smartArt.Style = SmartArtStyleType.IntenseEffect

Style effects affect visual characteristics such as shadows, gloss, and three-dimensionality of SmartArt. It's generally recommended to combine colors and styles for optimal visual results.

Comprehensive Example: Creating a Complete Project Flowchart

The following complete example demonstrates how to create a styled project flowchart:

from spire.presentation.common import *
from spire.presentation import *

# Create presentation
presentation = Presentation()
slide = presentation.Slides[0]

# Add process-type SmartArt
smartArt = slide.Shapes.AppendSmartArt(
    50, 100, 600, 200,
    SmartArtLayoutType.BasicProcess
)

# Clear default nodes
to_remove = [node for node in smartArt.Nodes]
for node in to_remove:
    smartArt.Nodes.RemoveNode(node)

# Add project phase nodes
phases = ["Requirements Analysis", "Design", "Development", "Testing", "Deployment"]
for phase in phases:
    node = smartArt.Nodes.AddNode()
    node.TextFrame.Text = phase

    # Set text style
    node.TextFrame.TextRange.Fill.FillType = FillFormatType.Solid
    node.TextFrame.TextRange.Fill.SolidColor.KnownColor = KnownColors.White
    node.TextFrame.TextRange.FontHeight = 14
    node.TextFrame.TextRange.IsBold = True

# Apply colorful theme
smartArt.ColorStyle = SmartArtColorType.ColorfulAccentColors

# Apply flat effect
smartArt.Style = SmartArtStyleType.Flat

# Save file
presentation.SaveToFile("ProjectProcess.pptx", FileFormat.Pptx2010)
presentation.Dispose()

This example creates a five-phase flowchart with clear white text labels for each phase, applying vibrant color themes and a modern flat design style.

Practical Tips

Dynamically Generating SmartArt

In practical applications, SmartArt content often comes from external data sources. Nodes can be dynamically generated by iterating through datasets:

# Assume department list retrieved from database
departments = GetDepartmentsFromDatabase()

for dept in departments:
    node = smartArt.Nodes.AddNode()
    node.TextFrame.Text = dept.Name
    # Different colors can be set based on department attributes

Adjusting SmartArt Position and Size

To ensure proper SmartArt positioning on slides, coordinates can be pre-calculated:

# Calculate centered position
slideWidth = presentation.SlideSize.Size.Width
slideHeight = presentation.SlideSize.Size.Height
smartArtWidth = 500
smartArtHeight = 300

left = (slideWidth - smartArtWidth) / 2
top = (slideHeight - smartArtHeight) / 2

smartArt = slide.Shapes.AppendSmartArt(
    left, top, smartArtWidth, smartArtHeight,
    SmartArtLayoutType.Matrix
)

Combining Multiple Layouts

In complex presentations, different SmartArt layouts can be used across different slides to display different dimensions of information, forming a complete information system.

Summary

SmartArt graphics serve as a powerful visualization tool in PowerPoint. Programmatically creating and manipulating SmartArt through Python enables efficient document automation. This article covered:

How to create SmartArt graphics using the AppendSmartArt() method
Selecting appropriate layout types to match information structure
Managing node content through Nodes.AddNode() and RemoveNode()
Setting text styles and formatting
Applying ColorStyle and Style properties to beautify SmartArt
Dynamic generation techniques for practical application scenarios

After mastering these skills, further exploration of more complex operations becomes possible, such as modifying node hierarchies, customizing connection lines, combining with other shape elements, and building comprehensive presentation automation generation systems.

How to Add Annotations and Markups to PDFs Using Python

Allen Yang — Thu, 02 Apr 2026 10:07:17 +0000

In PDF document processing scenarios, adding annotations is a practical and common requirement. Whether for document review, collaborative editing, or content marking, annotation functionality enables us to add notes, highlight key points, or insert comments without modifying the original text. This article will provide a comprehensive guide on how to add various types of annotations and markups to PDF documents using Python.

Why Add Annotations to PDF Documents

Manually adding annotations to PDF documents is not only inefficient but also makes it difficult to maintain consistent formatting. Implementing this functionality programmatically offers the following advantages:

Batch Processing - Add annotations with identical formatting to multiple documents at once
Precise Control - Pixel-level positioning of annotations to ensure perfect alignment with document content
Rich Types - Programmatically create various annotations including highlights, underlines, free text, stamps, and more
Style Consistency - Uniformly configure colors, opacity, borders, and other properties to maintain a professional appearance

Environment Setup

First, install a Python library that supports PDF operations. This article uses Spire.PDF for Python, which provides a complete PDF annotation API.

pip install Spire.PDF

This library supports multiple annotation types including text markup, free text, stamps, lines, attachments, and more, meeting various document annotation requirements.

Core Annotation Types

Spire.PDF supports a rich variety of annotation types, each with its specific application scenarios:

1. Free Text Annotation

Free text annotations allow adding editable text boxes on PDF pages, suitable for adding detailed explanations or comments.

from spire.pdf import *

# Create PDF document
doc = PdfDocument()
page = doc.Pages.Add()

# Define annotation area
rect = RectangleF(100.0, 200.0, 200.0, 50.0)

# Create free text annotation
textAnnotation = PdfFreeTextAnnotation(rect)
textAnnotation.Text = "\nThis is a free text annotation"

# Set font and border
font = PdfTrueTypeFont("Arial", 12.0, PdfFontStyle.Regular, True)
textAnnotation.Font = font

# Set border style
border = PdfAnnotationBorder(1.5)
textAnnotation.Border = border
textAnnotation.BorderColor = PdfRGBColor(Color.get_Blue())

# Set line ending style
textAnnotation.LineEndingStyle = PdfLineEndingStyle.Circle

# Set background color and opacity
textAnnotation.Color = PdfRGBColor(Color.get_LightBlue())
textAnnotation.Opacity = 0.8

# Add to page
page.AnnotationsWidget.Add(textAnnotation)

# Save document
doc.SaveToFile("FreeTextAnnotation.pdf")
doc.Close()

Key API Explanation:

PdfFreeTextAnnotation - Creates editable text annotation, requires specifying a rectangular area
PdfAnnotationBorder - Defines border width to make the annotation appearance clearer
PdfLineEndingStyle - Controls the ending style of annotation borders (circle, arrow, square, etc.)
Opacity - Sets transparency level (0.0-1.0), where 0.0 is fully transparent and 1.0 is fully opaque

2. Text Markup Annotation

Text markup annotations are used to highlight, underline, or strikethrough specific text, making them the most commonly used feature in document review.

from spire.pdf import *

# Load existing PDF document
doc = PdfDocument()
doc.LoadFromFile("template.pdf")
page = doc.Pages[0]

# Get text position to mark
font = PdfTrueTypeFont("Arial", 12.0, PdfFontStyle.Regular, True)
format = PdfStringFormat()

# Draw prompt text
prompt = "Text to highlight:"
page.Canvas.DrawString(prompt, font, PdfBrushes.get_DodgerBlue(), 0.0, 50.0)

# Calculate target text position
x = font.MeasureString(prompt, format).Width
label = "This is an important paragraph"
page.Canvas.DrawString(label, font, PdfBrushes.get_OrangeRed(), x, 50.0)

# Create highlight annotation
incorrectWordLocation = PointF(x, 50.0)
markupText = "Important content reminder"
annotation = PdfTextMarkupAnnotation(
    markupText, 
    "Important paragraph",
    RectangleF(x, 50.0, 100.0, 20.0), 
    font
)

# Set highlight type to highlight
annotation.TextMarkupAnnotationType = PdfTextMarkupAnnotationType.Highlight

# Set highlight color
annotation.TextMarkupColor = PdfRGBColor(Color.get_Yellow())

# Add to page
page.AnnotationsWidget.Add(annotation)

# Save document
doc.SaveToFile("TextMarkupAnnotation.pdf")
doc.Close()

Supported Markup Types:

Highlight - Highlight display, similar to highlighter pen effect
Underline - Add underline
StrikeOut - Add strikethrough
Squiggly - Add wavy line

3. Line Annotation

Line annotations are used to draw straight lines with arrows in documents, suitable for indicating, connecting, or measuring.

from spire.pdf import *

doc = PdfDocument()
page = doc.Pages.Add()

# Define start and end point coordinates of the line [x1, y1, x2, y2]
linePoints = [100, 400, 300, 400]

# Create line annotation
lineAnnotation = PdfLineAnnotation(linePoints, "Dimension measurement")

# Set line intent (affects how the reader displays it)
lineAnnotation.LineIntent = PdfLineIntent.LineDimension

# Set start and end styles
lineAnnotation.BeginLineStyle = PdfLineEndingStyle.ClosedArrow
lineAnnotation.EndLineStyle = PdfLineEndingStyle.Diamond

# Set line color and background color
lineAnnotation.InnerLineColor = PdfRGBColor(Color.get_Green())
lineAnnotation.BackColor = PdfRGBColor(Color.get_Green())

# Set border style
lineAnnotation.lineBorder.BorderStyle = PdfBorderStyle.Solid
lineAnnotation.lineBorder.BorderWidth = 2

# Add to page
page.AnnotationsWidget.Add(lineAnnotation)

# Save document
doc.SaveToFile("LineAnnotation.pdf")
doc.Close()

Line Style Options:

PdfLineEndingStyle.None - No line ending decoration
PdfLineEndingStyle.Butt - Butt endpoint
PdfLineEndingStyle.ClosedArrow - Closed arrow
PdfLineEndingStyle.OpenArrow - Open arrow
PdfLineEndingStyle.Diamond - Diamond endpoint
PdfLineEndingStyle.Circle - Circle endpoint

4. Rubber Stamp Annotation

Rubber stamp annotations are used to add predefined or custom status markers, such as "Approved", "Confidential", "Draft", etc.

from spire.pdf import *
from datetime import datetime

# Load PDF document
document = PdfDocument()
document.LoadFromFile("document.pdf")
page = document.Pages[0]

# Create custom stamp template
template = PdfTemplate(150.0, 60.0)

# Set font and color
font1 = PdfTrueTypeFont("Arial", 14.0, PdfFontStyle.Bold, True)
brush = PdfSolidBrush(PdfRGBColor(Color.get_Red()))

# Draw rounded rectangle border
rectangle = RectangleF(PointF(5.0, 5.0), SizeF(140.0, 50.0))
path = PdfPath()
path.AddArc(rectangle.X, rectangle.Y, 10.0, 10.0, 180.0, 90.0)
path.AddArc(rectangle.X + rectangle.Width - 10.0, rectangle.Y, 10.0, 10.0, 270.0, 90.0)
path.AddArc(rectangle.X + rectangle.Width - 10.0, rectangle.Y + rectangle.Height - 10.0, 
            10.0, 10.0, 0.0, 90.0)
path.AddArc(rectangle.X, rectangle.Y + rectangle.Height - 10.0, 10.0, 10.0, 90.0, 90.0)
path.CloseFigure()
template.Graphics.DrawPath(PdfPen(brush, 2.0), path)

# Draw stamp text
stampText = "✓ Approved\n" + datetime.now().strftime("%Y-%m-%d")
template.Graphics.DrawString(stampText, font1, brush, PointF(10.0, 15.0))

# Create rubber stamp annotation
stamp = PdfRubberStampAnnotation(RectangleF(PointF(400.0, 50.0), SizeF(150.0, 60.0)))
appearance = PdfAppearance(stamp)
appearance.Normal = template
stamp.Appearance = appearance

# Set metadata
stamp.Author = "Reviewer"
stamp.Subject = "Document Approval"
stamp.ModifiedDate = datetime.now()

# Add to page
page.AnnotationsWidget.Add(stamp)

# Save document
document.SaveToFile("StampAnnotation.pdf")
document.Close()

Predefined Stamp Icons:

If you don't want to customize stamps, you can use built-in icons:

# Use predefined "Draft" stamp
stamp = PdfRubberStampAnnotation(
    RectangleF(100.0, 100.0, 100.0, 40.0), 
    "Draft status"
)
stamp.Icon = PdfRubberStampAnnotationIcon.Draft
stamp.Color = PdfRGBColor(Color.get_Plum())
page.AnnotationsWidget.Add(stamp)

Common predefined icons include:

Draft - Draft
Approved - Approved
Confidential - Confidential
Final - Final version
Experimental - Experimental

5. Popup Annotation

Popup annotations are typically used in conjunction with other annotations, displaying detailed information when hovering the mouse over them.

from spire.pdf import *

doc = PdfDocument()
page = doc.Pages.Add()

# First create a text markup
font = PdfTrueTypeFont("Arial", 12.0, PdfFontStyle.Regular, True)
page.Canvas.DrawString("Hover over the annotation to view notes", font, 
                       PdfBrushes.get_Black(), 50.0, 100.0)

# Create popup annotation
popupRect = RectangleF(PointF(100.0, 150.0), SizeF.Empty())
popupAnnotation = PdfPopupAnnotation(popupRect, "This is detailed annotation information\nCan contain multiple lines of text")

# Set icon style
popupAnnotation.Icon = PdfPopupIcon.Paragraph

# Set whether to expand by default
popupAnnotation.Open = True

# Set color
popupAnnotation.Color = PdfRGBColor(Color.get_Yellow())

# Add to page
page.AnnotationsWidget.Add(popupAnnotation)

# Save document
doc.SaveToFile("PopupAnnotation.pdf")
doc.Close()

6. Polygon and Polyline Annotation

Polygon and polyline annotations are used to create annotation areas with custom shapes.

from spire.pdf import *
from datetime import datetime

doc = PdfDocument()
page = doc.Pages.Add()

# Create polygon annotation (closed shape)
polygon = PdfPolygonAnnotation(
    page, 
    [PointF(100.0, 200.0), PointF(150.0, 180.0), PointF(200.0, 200.0), 
     PointF(180.0, 250.0), PointF(120.0, 250.0)]
)

# Set polygon properties
polygon.Color = PdfRGBColor(Color.get_PaleVioletRed())
polygon.Text = "Key focus area"
polygon.Author = "Reviewer"
polygon.Subject = "Area marking"
polygon.BorderEffect = PdfBorderEffect.BigCloud  # Cloud border effect
polygon.ModifiedDate = datetime.now()

# Add to page
page.AnnotationsWidget.Add(polygon)

# Save document
doc.SaveToFile("PolygonAnnotation.pdf")
doc.Close()

Comprehensive Example: Creating a Review Document with Multiple Annotation Types

In practical applications, multiple annotation types are often used in combination. The following example demonstrates how to add multiple types of annotations to a single document:

from spire.pdf import *
from datetime import datetime

# Create document
doc = PdfDocument()
margin = PdfMargins()
margin.Top = 50
margin.Bottom = 50
margin.Left = 50
margin.Right = 50
page = doc.Pages.Add(PdfPageSize.A4(), margin)

# Add title
titleFont = PdfTrueTypeFont("Arial", 16.0, PdfFontStyle.Bold, True)
page.Canvas.DrawString("Document Review Example", titleFont, 
                       PdfBrushes.get_Black(), 0.0, 30.0)

# Add body text
contentFont = PdfTrueTypeFont("Arial", 12.0, PdfFontStyle.Regular, True)
content = "This is a text content that needs review. Some parts need to be highlighted, and some parts need comments added."
page.Canvas.DrawString(content, contentFont, 
                       PdfBrushes.get_Black(), 0.0, 80.0)

# 1. Add free text annotation
freeTextRect = RectangleF(50.0, 150.0, 250.0, 60.0)
freeText = PdfFreeTextAnnotation(freeTextRect)
freeText.Text = "\nReview comments:\nThe wording here needs to be clearer and more precise"
freeText.Font = PdfTrueTypeFont("Arial", 12.0, PdfFontStyle.Regular, True)
freeText.Color = PdfRGBColor(Color.get_LightYellow())
freeText.Opacity = 0.9
page.AnnotationsWidget.Add(freeText)

# 2. Add rubber stamp annotation
stampTemplate = PdfTemplate(120.0, 50.0, True)
stampFont = PdfTrueTypeFont("Arial", 12.0, PdfFontStyle.Bold, True)
stampBrush = PdfSolidBrush(PdfRGBColor(Color.get_Red()))
stampTemplate.Graphics.DrawString("Needs Revision", stampFont, stampBrush, PointF(10.0, 15.0))

stamp = PdfRubberStampAnnotation(RectangleF(PointF(350.0, 150.0), SizeF(120.0, 50.0)))
stampAppearance = PdfAppearance(stamp)
stampAppearance.Normal = stampTemplate
page.AnnotationsWidget.Add(stamp)

# 3. Add line annotation pointing to specific location
linePoints = [320, 200, 350, 180]
lineAnnot = PdfLineAnnotation(linePoints, "Refer to this section")
lineAnnot.BeginLineStyle = PdfLineEndingStyle.Butt
lineAnnot.EndLineStyle = PdfLineEndingStyle.ClosedArrow
lineAnnot.InnerLineColor = PdfRGBColor(Color.get_Blue())
page.AnnotationsWidget.Add(lineAnnot)

# Save document
doc.SaveToFile("ComprehensiveReview.pdf")
doc.Close()

Generated Result Preview:

Practical Tips

Setting Annotation Author and Timestamp

annotation = PdfFreeTextAnnotation(rect)
annotation.Author = "John Smith"  # Set author
annotation.CreationDate = datetime.now()  # Creation time
annotation.ModifiedDate = datetime.now()  # Modification time

Controlling Annotation Display Hierarchy

# Set annotation flags
annotation.Flags = PdfAnnotationFlags.Locked  # Lock annotation to prevent deletion
# Or use other flags
# PdfAnnotationFlags.Hidden - Hide annotation
# PdfAnnotationFlags.NoView - Do not display in view
# PdfAnnotationFlags.ReadOnly - Read-only mode

Extracting All Annotations from a Page

# Load document and get annotation collection
doc = PdfDocument()
doc.LoadFromFile("annotated.pdf")
annotations = doc.Pages[0].AnnotationsWidget

# Iterate through all annotations
if annotations.Count > 0:
    for i in range(annotations.Count):
        annotation = annotations.get_Item(i)

        # Handle different annotations based on type
        if isinstance(annotation, PdfFreeTextAnnotationWidget):
            print(f"Free text: {annotation.Text}")
        elif isinstance(annotation, PdfTextMarkupAnnotationWidget):
            print(f"Highlight text: {annotation.Text}")

        print(f"Author: {annotation.Author}")
        print(f"Modification date: {annotation.ModifiedDate}")

Summary

This article has introduced methods for adding various types of annotations to PDF documents using Python. Through the rich API provided by Spire.PDF, developers can:

Create multiple annotation types including free text, highlights, lines, stamps, and more
Precisely control annotation properties such as position, color, opacity, and more
Batch process document review and annotation tasks
Extract and manage existing annotation information

These capabilities make PDF annotation automation possible, significantly improving the efficiency of document collaboration and review. In actual projects, different annotation types can be combined according to specific requirements to create professional interactive PDF documents.

Automate Word Paragraph Formatting with Python

Allen Yang — Fri, 27 Mar 2026 10:39:15 +0000

When creating professional Word documents, paragraph formatting is a crucial step in enhancing document readability and professionalism. Whether for business reports, technical documentation, or academic papers, appropriate paragraph spacing, indentation, shading, and alignment can significantly improve the visual appearance and reading experience of documents. This article provides a comprehensive guide on how to use Python to programmatically apply various formatting settings to paragraphs in Word documents, including spacing control, background colors, indentation adjustments, and style applications.

Why Automate Paragraph Formatting

Although Microsoft Word provides a graphical interface for manual paragraph formatting, automating this process through code is more efficient in the following scenarios:

Batch Document Processing: Apply company standard formats uniformly across large numbers of documents
Template Generation Systems: Automatically create document templates that meet specific layout requirements
Standardized Reports: Ensure all generated reports maintain consistent paragraph styles
Dynamic Content Creation: Automatically apply different formatting rules based on content type

By using Python to control paragraph formatting programmatically, you can transform these repetitive formatting tasks into reusable automated workflows, significantly improving work efficiency.

Environment Setup

Before starting, you need to install a Python library that supports Word document manipulation. Spire.Doc for Python provides a comprehensive API for working with DOCX format documents, including complete paragraph formatting control capabilities.

pip install Spire.Doc

Once installation is complete, you can import the relevant modules in your Python scripts to edit documents.

Core Concept: Paragraph Format Object Model

Before setting paragraph formatting with Spire.Doc, it's important to understand its basic object hierarchy:

Document: Represents the entire Word document object
Section: A section within the document, used to organize different parts of content
Paragraph: The paragraph object, containing text and formatting information
ParagraphFormat: The paragraph format object that controls properties like spacing, indentation, and alignment
CharacterFormat: The character format object that controls text color, background color, and other text properties

The basic workflow is: create or load a document → access paragraph objects → obtain ParagraphFormat → set format properties → save the document.

Basic Paragraph Spacing Settings

Paragraph spacing is the most fundamental element in controlling document readability. Through code, you can precisely control spacing before and after paragraphs:

from spire.doc import *
from spire.doc.common import *

outputFile = "SetParagraphSpacing.docx"

# Create a Word document
document = Document()

# Add a new section
section = document.AddSection()

# Add a title paragraph
titlePara = section.AddParagraph()
titleText = titlePara.AppendText("Paragraph Spacing Settings Example")
titleText.CharacterFormat.FontSize = 16
titleText.CharacterFormat.Bold = True

# Add the first content paragraph
para1 = section.AddParagraph()
para1.AppendText("This is the first paragraph. By using code, you can precisely control the spacing between paragraphs, making the document look more professional and easier to read.")

# Set spacing before paragraph to 10 points
para1.Format.BeforeAutoSpacing = False
para1.Format.BeforeSpacing = 10

# Set spacing after paragraph to 10 points
para1.Format.AfterAutoSpacing = False
para1.Format.AfterSpacing = 10

# Add the second content paragraph
para2 = section.AddParagraph()
para2.AppendText("This is the second paragraph. Each paragraph can be configured with independent spacing properties to achieve flexible layout effects.")
para2.Format.BeforeSpacing = 10
para2.Format.AfterSpacing = 10

# Save the document
document.SaveToFile(outputFile, FileFormat.Docx2013)
document.Close()

Key Points Explained:

The BeforeSpacing and AfterSpacing properties specify spacing in points (pt), where 1 point = 1/72 inch
When BeforeAutoSpacing and AfterAutoSpacing are set to False, you can manually specify exact spacing values
Each paragraph can be independently configured with spacing properties, enabling flexible layout control

Setting Paragraph Shading and Background Color

Adding background color to paragraphs can effectively highlight important information or distinguish different content blocks:

from spire.doc import *
from spire.doc.common import *

inputFile = "./Data/Template_Docx_1.docx"
outputFile = "SetParagraphShading.docx"

# Create a Word document
document = Document()

# Load file from disk
document.LoadFromFile(inputFile)

# Get the first paragraph
paragraph = document.Sections[0].Paragraphs[0]

# Set background color for the entire paragraph
paragraph.Format.BackColor = Color.get_Yellow()

# Get the third paragraph
paragraph = document.Sections[0].Paragraphs[2]

# Find specific text
selection = paragraph.Find("Christmas", True, False)
textRange = selection.GetAsOneRange()

# Set background color only for the selected text
textRange.CharacterFormat.TextBackgroundColor = Color.get_Yellow()

# Save the document
document.SaveToFile(outputFile, FileFormat.Docx2013)
document.Close()

This example demonstrates two different approaches to setting background color:

ParagraphFormat.BackColor: Sets background color for the entire paragraph area
CharacterFormat.TextBackgroundColor: Sets background color only for specific text ranges

Applying Built-in Styles

Word provides a rich collection of built-in styles that enable quick application of professional formatting combinations:

from spire.doc import *
from spire.doc.common import *

outputFile = "ApplyParagraphStyles.docx"

# Create a Word document
document = Document()
section = document.AddSection()

# Apply Heading 1 style
para1 = section.AddParagraph()
text1 = para1.AppendText("This is Heading 1")
para1.ApplyStyle(BuiltinStyle.Heading1)

# Apply Heading 2 style
para2 = section.AddParagraph()
text2 = para2.AppendText("This is Heading 2")
para2.ApplyStyle(BuiltinStyle.Heading2)

# Apply Normal style
para3 = section.AddParagraph()
text3 = para3.AppendText("This is a body paragraph using the default Normal style.")
para3.ApplyStyle(BuiltinStyle.Normal)

# Apply Quote style
para4 = section.AddParagraph()
text4 = para4.AppendText("This is quoted text displayed using the Quote style.")
para4.ApplyStyle(BuiltinStyle.Quote)

# Save the document
document.SaveToFile(outputFile, FileFormat.Docx2013)
document.Close()

Advantages of Using Built-in Styles:

Quickly apply predefined formatting combinations, including font, size, color, spacing, and more
Maintain document style consistency
Facilitate subsequent unified modification of style definitions
Support automatic table of contents generation

Creating Custom List Styles

In addition to using built-in styles, you can create custom numbered list styles:

from spire.doc import *
from spire.doc.common import *

outputFile = "CreateCustomListStyle.docx"

# Create a Word document
document = Document()
section = document.AddSection()

# Add level 1 heading
para1 = section.AddParagraph()
para1.AppendText("Chapter One")
para1.ApplyStyle(BuiltinStyle.Heading1)
para1.ListFormat.ApplyNumberedStyle()

# Add level 2 heading
para2 = section.AddParagraph()
para2.AppendText("Section One")
para2.ApplyStyle(BuiltinStyle.Heading2)

# Create custom numbered style
listStyle2 = document.Styles.Add(ListType.Numbered, "MyStyle2")
levels = listStyle2.ListRef.Levels

for i in range(levels.Count):
    listLevel = levels.get_Item(i)
    listLevel.UsePrevLevelPattern = True
    listLevel.NumberPrefix = "1."

para2.ListFormat.ApplyStyle(listStyle2.Name)

# Add level 3 heading
listStyle3 = document.Styles.Add(ListType.Numbered, "MyStyle3")
levels1 = listStyle3.ListRef.Levels

for i in range(levels1.Count):
    listLevel = levels1.get_Item(i)
    listLevel.UsePrevLevelPattern = True
    listLevel.NumberPrefix = "1.1."

# Add multiple level 3 headings
for i in range(4):
    para3 = section.AddParagraph()
    para3.AppendText("Subsection")
    para3.ApplyStyle(BuiltinStyle.Heading3)
    para3.ListFormat.ApplyStyle(listStyle3.Name)

# Save the document
document.SaveToFile(outputFile, FileFormat.Docx2013)
document.Close()

This example demonstrates how to:

Create multi-level numbered styles
Set numbered prefix formats (such as "1." and "1.1.")
Apply custom styles to paragraphs
Build hierarchical document structures

Practical Technique: Combining Multiple Format Settings

In practical applications, you typically need to apply multiple formatting settings simultaneously to achieve ideal layout effects:

from spire.doc import *
from spire.doc.common import *

outputFile = "CombinedFormatting.docx"

document = Document()
section = document.AddSection()

# Create a paragraph with multiple formatting options
para = section.AddParagraph()
text = para.AppendText("This is an example paragraph with rich formatting")

# Set character formatting
text.CharacterFormat.FontSize = 14
text.CharacterFormat.Bold = True
text.CharacterFormat.TextColor = Color.get_DarkBlue()

# Set paragraph formatting
para.Format.BeforeSpacing = 12
para.Format.AfterSpacing = 12
para.Format.LeftIndent = 20
para.Format.RightIndent = 20
para.Format.FirstLineIndent = 24

# Set background color
para.Format.BackColor = Color.get_LightYellow()

# Save the document
document.SaveToFile(outputFile, FileFormat.Docx2013)
document.Close()

Summary

This article has introduced various methods for using Python to set Word document paragraph formatting, including:

Precise control of spacing before and after paragraphs
Setting background colors for paragraphs and text
Applying built-in styles for quick formatting
Creating custom numbered list styles
Combining multiple formatting options to achieve complex layouts

Through these techniques, you can achieve complete automation of document formatting, significantly improving the efficiency and quality of document processing. Whether processing existing documents in bulk or dynamically generating new documents, mastering these paragraph formatting skills is invaluable.

Further learning directions include: setting line spacing, controlling page breaks, applying borders, creating style templates, and other advanced formatting control features.

Insert and Manage Images in Word with Python

Allen Yang — Thu, 26 Mar 2026 06:06:19 +0000

Images are essential elements for conveying information and enhancing visual appeal when creating professional documents. Whether it's product reports, technical documentation, or marketing materials, appropriately inserting and processing images can significantly improve the professionalism and readability of documents. This article will provide a comprehensive guide on how to insert images in Word documents using Python and perform various advanced operations, including position adjustment, size settings, text wrapping, and special effects application.

Why Process Images Programmatically

Although Microsoft Word provides an intuitive image insertion interface, automating image handling through code is more efficient in the following scenarios:

Batch Document Generation: Automatically generate specification sheets containing images for hundreds of products
Dynamic Content Creation: Automatically insert corresponding images based on image paths in a database
Standardized Layout: Ensure consistent image dimensions, positions, and styles across all documents
Automated Reporting Systems: Read images from the file system and generate uniformly formatted report documents

By controlling image insertion through Python programming, these repetitive tasks can be transformed into reusable automated workflows.

Environment Setup

Before starting, you need to install a Python library that supports Word document operations. Spire.Doc for Python provides comprehensive APIs for DOCX format document manipulation, including complete image insertion and processing capabilities.

pip install Spire.Doc

After installation, you can import the relevant modules in your Python script for document editing.

Core Concepts: Image Object Model

Before inserting images with Spire.Doc, it's important to understand its basic object hierarchy:

Document: Represents the entire Word document object
Section: A section in the document used to organize different parts of content
Paragraph: Paragraph objects that承载 text, images, and other elements
DocPicture: Image object representing an image inserted into the document
TextWrappingStyle: Text wrapping style that controls the layout relationship between images and surrounding text

The basic workflow is: create or load a document → access sections and paragraphs → create image objects → set image properties → insert into paragraphs → save the document.

Basic Image Insertion

The most fundamental image insertion operation involves loading an image file and adding it to the document. The following example demonstrates how to insert an image in a Word document:

from spire.doc import *

outputFile = "InsertImage.docx"

# Create a new Word document
doc = Document()
section = doc.AddSection()

# Add a title
titlePara = section.AddParagraph()
titlePara.AppendText("Image Insertion Example")
titlePara.ApplyStyle(BuiltinStyle.Heading1)

# Add descriptive text
para = section.AddParagraph()
para.AppendText("Here is a sample image:")

# Create image object
picture = DocPicture(doc)
picture.LoadImage("./Sample.png")

# Set image dimensions
picture.Width = 300.0
picture.Height = 200.0

# Insert image into paragraph
para.ChildObjects.Add(picture)

# Save the document
doc.SaveToFile(outputFile, FileFormat.Docx)
doc.Close()

Output:

Key points:

DocPicture is the core class for inserting images
LoadImage() method loads an image from a file path
Width and Height properties set dimensions in points (1 point = 0.3528 mm)
Images are added to the paragraph's child object collection via ChildObjects.Add()

Precise Image Positioning

Besides inserting images in the text flow, you can precisely control the absolute position of images on the page:

from spire.doc import *

doc = Document()
section = doc.AddSection()
para = section.AddParagraph()

# Add descriptive text
para.AppendText("Demonstrating precisely positioned images:")

# Create image
picture = DocPicture(doc)
picture.LoadImage("./Logo.png")

# Set absolute position
# Set image text wrapping style to Behind (or InFrontOf) to enable absolute positioning
picture.TextWrappingStyle = TextWrappingStyle.Behind
# Horizontal position relative to the left edge of the page (in points)
picture.HorizontalPosition = 100.0
# Vertical position relative to the top edge of the page (in points)
picture.VerticalPosition = 150.0

# Set dimensions
picture.Width = 200.0
picture.Height = 150.0

# Set positioning reference
picture.HorizontalOrigin = HorizontalOrigin.Page
picture.VerticalOrigin = VerticalOrigin.Page

# Insert image
para.ChildObjects.Add(picture)

doc.SaveToFile("PositionedImage.docx", FileFormat.Docx)
doc.Close()

Output:

Key properties:

HorizontalPosition: X coordinate of the image relative to the horizontal origin
VerticalPosition: Y coordinate of the image relative to the vertical origin
HorizontalOrigin: Reference origin for horizontal position (Page/Margin/Column)
VerticalOrigin: Reference origin for vertical position (Page/Margin/Column)

This positioning method is suitable for scenarios where you need to place logos, watermarks, or specific layout elements at fixed positions.

Text Wrapping Styles

Word provides various text wrapping options for images. Spire.Doc supports setting these wrapping styles to control the layout relationship between images and surrounding text:

from spire.doc import *

doc = Document()
section = doc.AddSection()

# Create a document with multiple paragraphs of text
for i in range(5):
    para = section.AddParagraph()
    para.AppendText("This is sample text to demonstrate text wrapping effects. " * 3)

# Get the first paragraph
paragraph = section.Paragraphs[0]

# Create image
picture = DocPicture(doc)
picture.LoadImage("./Sample.png")
picture.Width = 150.0
picture.Height = 150.0

# Set text wrapping style
# Available values: Inline, Square, Tight, Through, TopAndBottom, Behind, InFrontOf
picture.TextWrappingStyle = TextWrappingStyle.Square
picture.TextWrappingType = TextWrappingType.Both

# Insert image at the beginning of the paragraph
paragraph.ChildObjects.Insert(0, picture)

doc.SaveToFile("TextWrap.docx", FileFormat.Docx)
doc.Close()

Output:

Common text wrapping styles include:

Inline: The image is treated as a character and flows with the text
Square: Text wraps around the image in a rectangular shape
Tight: Text wraps closely along the contour of the image
Through: Text can flow into open areas of the image
TopAndBottom: Text appears only above and below the image, not on the sides
Behind: The image appears behind the text as a background
InFrontOf: The image appears in front of the text, covering it

Choosing the appropriate wrapping style is crucial for creating professional text-image layouts.

Special Image Effects Processing

Beyond position and wrapping settings, you can apply various special effects to images, such as transparency settings:

from spire.doc import *

# Load an existing document
doc = Document()
doc.LoadFromFile("ImageTemplate.docx")

# Iterate through all paragraphs in the document
for i in range(doc.Sections.Count):
    section = doc.Sections.get_Item(i)
    for j in range(section.Paragraphs.Count):
        para = section.Paragraphs.get_Item(j)
        # Find all image objects
        for k in range(para.ChildObjects.Count):
            obj = para.ChildObjects.get_Item(k)
            if isinstance(obj, DocPicture):
                picture = obj
                # Set specified color as transparent
                picture.TransparentColor = Color.FromRgb(80, 163, 209)

doc.SaveToFile("TransparentImage.docx", FileFormat.Docx)
doc.Close()

Effect comparison:

Application scenarios for transparency settings:

Remove Solid Backgrounds: Make solid-color backgrounds of product images transparent
Create Watermark Effects: Make parts of images transparent to show underlying content
Image Compositing: Achieve layering effects with multiple overlapping images

Comprehensive Application: Inserting Images in Product Catalogs

In practical applications, you often need to combine multiple image processing techniques. The following example demonstrates a simplified product catalog generation scenario:

from spire.doc import *

def create_product_catalog(products):
    """
    Create a single-page product catalog

    Args:
        products: List of products, each as a tuple of (product name, image path, description)
    """
    doc = Document()
    section = doc.AddSection()

    # Page title
    title_para = section.AddParagraph()
    title_para.AppendText("Product Catalog")
    title_para.ApplyStyle(BuiltinStyle.Title)
    title_para.Format.Alignment = HorizontalAlignment.Center
    title_para.Format.AfterSpacing = 20  # Spacing between title and entries

    # Product entry list
    for productName, imagePath, description in products:
        # Create a table to display product information in rows
        table = section.AddTable()
        table.ResetCells(1, 2)  # One row, two columns
        table.TableFormat.IsAutoResized = True
        table.TableFormat.HorizontalAlignment = RowAlignment.Left
        table.Rows[0].Height = 60  # Row height to ensure image display

        # Left column: Image
        cell_img = table.Rows[0].Cells[0]
        para_img = cell_img.AddParagraph()
        para_img.Format.Alignment = HorizontalAlignment.Center
        picture = DocPicture(doc)
        picture.LoadImage(imagePath)
        picture.Width = 50  # Adjust as needed
        picture.Height = 50
        para_img.ChildObjects.Add(picture)

        # Right column: Name + Description
        cell_text = table.Rows[0].Cells[1]
        para_text = cell_text.AddParagraph()
        para_text.Format.Alignment = HorizontalAlignment.Left

        name_run = para_text.AppendText(productName + ": ")
        name_run.CharacterFormat.Bold = True
        para_text.AppendText(description)

        # Empty line below table
        section.AddParagraph().AppendText("")

    return doc

# Example data
products = [
    ("Product A", "./Word.png", "Detailed description of Product A..."),
    ("Product B", "./Watermark.png", "Detailed description of Product B..."),
    ("Product C", "./PDF.png", "Detailed description of Product C..."),
]

doc = create_product_catalog(products)
doc.SaveToFile("ProductCatalog.docx", FileFormat.Docx)
doc.Close()

Output:

This comprehensive example demonstrates how to combine image insertion, positioning, text wrapping, and other techniques to create professional product catalog documents.

Practical Tips and Best Practices

When working with Word images in real projects, the following tips can improve development efficiency and quality:

1. Batch Insert Images

When inserting images for multiple products or items, use loops for batch processing:

image_paths = ["./img1.png", "./img2.png", "./img3.png"]

for i, path in enumerate(image_paths):
    para = section.AddParagraph()
    picture = DocPicture(doc)
    picture.LoadImage(path)
    picture.Width = 200.0
    picture.Height = 150.0
    para.ChildObjects.Add(picture)

2. Standardize Image Dimensions

To ensure consistent image sizes across documents, define standardized dimension constants:

# Define standard image dimensions (in points)
IMAGE_WIDTH_SMALL = 150.0
IMAGE_HEIGHT_SMALL = 100.0

IMAGE_WIDTH_LARGE = 400.0
IMAGE_HEIGHT_LARGE = 300.0

# Usage example
picture.Width = IMAGE_WIDTH_SMALL
picture.Height = IMAGE_HEIGHT_SMALL

3. Fine-tune Image Position Offsets

Adjust image positions for better visual effects:

# Center align based on page width
page_width = sec.PageSetup.PageSize.Width
picture.HorizontalPosition = (page_width - picture.Width) / 2

4. Error Handling

Handle cases where image files may not exist:

import os

def safe_insert_image(doc, image_path):
    if not os.path.exists(image_path):
        print(f"Warning: Image file does not exist - {image_path}")
        return False

    picture = DocPicture(doc)
    try:
        picture.LoadImage(image_path)
        return True
    except Exception as e:
        print(f"Failed to load image: {e}")
        return False

Summary

This article has provided a comprehensive introduction to inserting and processing images in Word documents using Python, covering everything from basic insertion to advanced processing. By mastering these techniques, you can achieve:

Programmatic image insertion and resizing
Precise control of image positions on pages
Professional layout with different text wrapping styles
Special effects such as transparency
Batch image insertion tasks

These skills are particularly valuable for scenarios requiring batch generation of product catalogs, automated reporting systems, or document template development. Combined with Python's data processing capabilities, you can build powerful document automation systems that transform tedious manual image processing into efficient, reusable automated workflows.

Master Word Text Styles and Effects Using Python

Allen Yang — Mon, 23 Mar 2026 10:07:35 +0000

When working with Word documents, text formatting is a fundamental and essential task. Whether creating professional reports, designing polished documents, or generating standardized files in bulk, controlling fonts, sizes, colors, and various text effects is an indispensable skill. This article provides a detailed guide on how to use Python to apply different text formats and styles in Word documents, including basic font settings, advanced text effects, and paragraph style applications.

Why Programmatic Text Formatting Is Needed

Manually setting text formats in Word is intuitive but can be inefficient in the following scenarios:

Batch Document Processing: Applying consistent formatting standards across hundreds of documents.
Dynamic Content Generation: Automatically generating formatted document content based on data sources.
Format Standardization: Ensuring that all output documents have uniform fonts and styles.
Automated Reporting: Extracting data from databases and generating visually formatted report documents.

By using Python to control text formatting programmatically, repetitive tasks can be automated, significantly improving efficiency.

Environment Setup

Before getting started, you need to install a Python library that supports Word document operations. Spire.Doc for Python provides a comprehensive API for manipulating DOCX files, including full text formatting capabilities.

pip install Spire.Doc

After installation, you can import the necessary modules in your Python scripts to begin editing documents.

Core Concepts: Document Object Model

Before manipulating Word documents with Spire.Doc, it is important to understand its basic object hierarchy:

Document: Represents the entire Word document.
Section: Represents a section in the document, used to organize different parts.
Paragraph: Represents a paragraph object that contains text and other elements.
TextRange: Represents a text range, used for character-level formatting.
CharacterFormat: Represents character formatting properties, including font and style attributes.

The typical workflow is: create or load a document → access sections and paragraphs → obtain text ranges → apply character formatting → save the document.

Basic Font Settings

The most fundamental text formatting includes setting the font name, size, and color. The following example demonstrates how to modify font properties in an existing Word document:

from spire.doc import *

# Load the document
doc = Document()
doc.LoadFromFile("Sample.docx")

# Access the first section
section = doc.Sections[0]

# Access a specific paragraph
paragraph = section.Paragraphs[1]

# Create a CharacterFormat object
characterFormat = CharacterFormat(doc)

# Set font properties
characterFormat.FontName = "Arial"
characterFormat.FontSize = 16
characterFormat.TextColor = Color.get_Blue()

# Apply the character format to all child objects in the paragraph
for i in range(paragraph.ChildObjects.Count):
    childObj = paragraph.ChildObjects.get_Item(i)
    if isinstance(childObj, TextRange):
        childObj.ApplyCharacterFormat(characterFormat)

# Save the document
doc.SaveToFile("SetFont.docx", FileFormat.Docx)
doc.Close()

The resulting document:

Key points:

CharacterFormat is the core class for text formatting.
FontName specifies the font family (e.g., Arial, Calibri).
FontSize sets the font size in points.
TextColor can use predefined colors or custom RGB values.
ApplyCharacterFormat() applies the formatting to a text range.

Advanced Text Effects

Beyond basic settings, Spire.Doc supports a wide variety of visual text effects, including strikethrough, shadow, outline, emboss, and more:

from spire.doc import *

# Create a new document
document = Document()
sec = document.AddSection()

# Add a title
titleParagraph = sec.AddParagraph()
titleParagraph.AppendText("Demonstration of Font Styles and Effects")
titleParagraph.ApplyStyle(BuiltinStyle.Title)

# Add various text effects
paragraph = sec.AddParagraph()

# Strikethrough
tr = paragraph.AppendText("Strikethrough text ")
tr.CharacterFormat.IsStrikeout = True

paragraph.AppendBreak(BreakType.LineBreak)

# Shadow
tr = paragraph.AppendText("Shadow text ")
tr.CharacterFormat.IsShadow = True

paragraph.AppendBreak(BreakType.LineBreak)

# Small caps
tr = paragraph.AppendText("Small caps text ")
tr.CharacterFormat.IsSmallCaps = True

paragraph.AppendBreak(BreakType.LineBreak)

# Double strikethrough
tr = paragraph.AppendText("Double strikethrough text ")
tr.CharacterFormat.DoubleStrike = True

paragraph.AppendBreak(BreakType.LineBreak)

# Outline
tr = paragraph.AppendText("Outlined text ")
tr.CharacterFormat.IsOutLine = True

paragraph.AppendBreak(BreakType.LineBreak)

# All caps
tr = paragraph.AppendText("All caps text ")
tr.CharacterFormat.AllCaps = True

paragraph.AppendBreak(BreakType.LineBreak)

# Subscript and superscript
tr = paragraph.AppendText("H")
tr = paragraph.AppendText("2")
tr.CharacterFormat.SubSuperScript = SubSuperScript.SubScript

tr = paragraph.AppendText(" and E=mc")
tr = paragraph.AppendText("2")
tr.CharacterFormat.SubSuperScript = SubSuperScript.SuperScript

paragraph.AppendBreak(BreakType.LineBreak)

# Emboss
tr = paragraph.AppendText("Embossed text ")
tr.CharacterFormat.Emboss = True
tr.CharacterFormat.TextColor = Color.get_White()

paragraph.AppendBreak(BreakType.LineBreak)

# Hidden text
tr = paragraph.AppendText("Visible text: ")
tr = paragraph.AppendText("Hidden text ")
tr.CharacterFormat.Hidden = True

paragraph.AppendBreak(BreakType.LineBreak)

# Engrave
tr = paragraph.AppendText("Engraved text ")
tr.CharacterFormat.Engrave = True
tr.CharacterFormat.TextColor = Color.get_White()

# Save the document
document.SaveToFile("AdvancedTextEffects.docx", FileFormat.Docx)
document.Close()

The resulting document:

These special effects can be used in the following scenarios:

Strikethrough: Mark items that have been deleted or completed
Shading and Embossing: Emphasize important information or create visual hierarchy
Superscript and Subscript: Professional documents such as mathematical formulas and chemical molecular formulas
Hidden Text: Store notes without displaying them in printed documents

Font Combinations and Complex Formatting

In practical applications, it is often necessary to apply multiple formatting effects simultaneously or assign different font families for Western and East Asian text:

```python id="0b7sd7"

Set fonts for mixed text

tr = paragraph.AppendText("Mixed fonts: Calibri for English + SimSun for Chinese ")
tr.CharacterFormat.FontNameAscii = "Calibri"
tr.CharacterFormat.FontNameNonFarEast = "Calibri"
tr.CharacterFormat.FontNameFarEast = "Simsun"