DEV Community: Allen Yang

Finding and Replacing Text in Word Documents Using Python

Allen Yang — Fri, 21 Aug 2026 07:27:58 +0000

Finding and replacing text is one of the most fundamental and frequent operations in Word document automation. Whether batch-modifying clause numbers in contracts, updating date information in reports, or standardizing terminology across multiple documents, efficient text find-and-replace capability is a core component of any document processing workflow. This article covers how to find and replace text in Word documents using Python, including plain text replacement, regex-based pattern matching, find-and-highlight, and replacing text with images.

Why Implement Find and Replace Programmatically

While Word's built-in find-and-replace feature is convenient for manual use, programmatic approaches offer irreplaceable advantages in the following scenarios:

Batch processing: Apply the same replacement across dozens of documents in a single operation
Complex matching: Use regular expressions to match text with specific patterns such as IDs, dates, or email addresses
Precise control: Apply fine-grained replacement strategies with case sensitivity and whole-word matching
Workflow integration: Embed replacement operations into larger document processing pipelines such as contract template generation or automated report creation

Environment Setup

Before starting, install the Python library that supports Word document operations.

pip install Spire.Doc

Once installed, import the relevant modules in your script to begin working.

Basic Text Replacement

The most basic replacement operation substitutes specified text in a document with new content. The Replace() method accepts four parameters: the text to find, the replacement text, whether to ignore case, and whether to match whole words only.

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

inputFile = "Sample.docx"
outputFile = "ReplaceText.docx"

# Create a document object
document = Document()

# Load the Word file from disk
document.LoadFromFile(inputFile)

# Replace "word" with "ReplacedText" in the document
# Parameters: find text, replace text, ignore case, match whole word
document.Replace("word", "ReplacedText", False, True)

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

The second and third boolean parameters of Replace() determine the strictness of matching. False means case-sensitive matching, and True as the fourth parameter means only complete words are matched rather than partial word segments. This design allows replacement operations to precisely control the matching scope and avoid unintended substitutions.

Using Regular Expressions for Replacement

When the text to match follows a pattern rather than a fixed string, regular expressions become essential. For example, replacing all identifiers starting with #, matching dates in a specific format, or finding reference numbers.

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

inputFile = "Sample.docx"
outputFile = "ReplaceByRegex.docx"

# Create a document object
document = Document()

# Load the Word file from disk
document.LoadFromFile(inputFile)

# Create a regex pattern to match words starting with #
regex = re.compile(r"#\w+\b")

# Replace all text matching the regex pattern
document.Replace(regex, "Spire.Doc")

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

Here, Python's standard re library compile() method creates a regex object, which is then passed to document.Replace(). All text matching the pattern is uniformly replaced with the target string. This approach is particularly suitable for processing text content with regular patterns, such as:

Replacing all tag identifiers like #TAG001
Redacting all email addresses to [REDACTED]
Standardizing date formats, such as converting YYYY/MM/DD to YYYY-MM-DD

Finding Text and Applying Highlight

Sometimes you don't need to replace text content but rather locate all matching instances and apply visual markers. This is highly useful in document review and keyword search result marking scenarios.

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

inputFile = "Sample.docx"
outputFile = "FindAndHighlight.docx"

# Create a document object
document = Document()

# Load the Word file from disk
document.LoadFromFile(inputFile)

# Find all matching text instances
textSelections = document.FindAllString("word", False, True)

# Iterate through matches and set highlight color
for selection in textSelections:
    selection.GetAsOneRange().CharacterFormat.HighlightColor = Color.get_Yellow()

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

The FindAllString() method returns a collection of text selections, each representing a match position in the document. Use GetAsOneRange() to obtain the corresponding text range, then access the CharacterFormat.HighlightColor property to set the highlight color. The parameter False means case-sensitive matching, and True means whole-word matching.

Replacing Text with Images

Beyond text replacement, you can also replace found text with images. This is practical in scenarios like batch-inserting logos, signatures, or product images.

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

inputFile = "Sample.docx"
outputFile = "ReplaceWithImage.docx"

# Create a document object
document = Document()

# Load the Word file from disk
document.LoadFromFile(inputFile)

# Create an image object
image = DocPicture(document)
image.LoadImage("logo.png")

# Find all "[LOGO]" placeholders
textSelections = document.FindAllString("[LOGO]", False, False)

# Replace each match with the image
for selection in textSelections:
    range = selection.GetAsOneRange()
    # Clear the original text
    range.Text = ""
    # Insert the image at the original text position
    range.ChildObjects.Add(image.Clone())

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

This approach is commonly used in template document processing: place placeholders (such as [LOGO] or [SIGNATURE]) in the document, then batch-replace them with actual images through code.

Batch Processing Multiple Documents

In real-world work, you often need to perform the same find-and-replace operation across multiple Word files in a directory. Combined with Python's file traversal capabilities, efficient batch processing becomes straightforward.

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

input_dir = "./documents"
output_dir = "./processed"

os.makedirs(output_dir, exist_ok=True)

# Iterate through all .docx files in the directory
for filename in os.listdir(input_dir):
    if filename.endswith(".docx"):
        input_path = os.path.join(input_dir, filename)
        output_path = os.path.join(output_dir, filename)

        document = Document()
        document.LoadFromFile(input_path)

        # Perform replacement
        document.Replace("Old Company Name", "New Company Name", False, True)

        document.SaveToFile(output_path, FileFormat.Docx)
        document.Close()

        print(f"Processed: {filename}")

This code iterates through all .docx files in a specified directory, performs the same text replacement on each document, and saves the results to an output directory. This pattern is highly practical in scenarios such as company renaming, terminology standardization, and template updates.

Practical Tips

Using Context-Aware Replacement

For replacement scenarios requiring more complex logic, you can check the context of each match before deciding whether to perform the replacement:

# Find all matching instances
textSelections = document.FindAllString("Python", False, True)

# Decide whether to replace based on context
for selection in textSelections:
    range = selection.GetAsOneRange()
    # Only replace when the paragraph style is a heading
    if range.OwnerParagraph.StyleName.startswith("Heading"):
        range.Text = "Python Programming"

Preserving Formatting After Replacement

When replacing text, the original character formatting (font, color, size, etc.) is preserved by default. If you need to modify formatting simultaneously, reapply it after replacement:

textSelections = document.FindAllString("old term", False, True)
for selection in textSelections:
    range = selection.GetAsOneRange()
    range.Text = "new term"
    range.CharacterFormat.Bold = True
    range.CharacterFormat.TextColor = Color.get_Blue()

Conclusion

This article covered multiple approaches to finding and replacing text in Word documents using Python, including basic text replacement, regex-based pattern replacement, find-and-highlight, image replacement, and batch file processing. These operations address the main scenarios from simple text modifications to complex pattern matching.

The core API revolves around two methods: Replace() for direct replacement supporting both plain strings and regular expressions, and FindAllString() for locating match positions that can be combined with formatting settings for highlight marking and other effects. With these fundamentals in place, you can combine them with Python's file handling capabilities to build efficient document batch processing workflows.

Add PowerPoint Slide Transitions Using Python

Allen Yang — Thu, 20 Aug 2026 10:13:13 +0000

Slide transition effects are an important means of enhancing visual appeal and audience engagement in presentations. By adding transition animations between slides, the presentation flow becomes smoother and more natural. In scenarios that require batch processing or template-based presentation generation, setting transition effects programmatically with Python eliminates the tedium of manual configuration and ensures consistent styling throughout the entire presentation.

This article covers how to add slide transition effects in PowerPoint using Python, including basic transition type configuration, advanced effect properties, and automatic advance timing.

Why Set Transition Effects Programmatically

In the following scenarios, batch-setting slide transition effects through code provides clear practical value:

Template standardization: Create unified presentation templates for an organization or team, with all slides using a consistent transition style
Batch processing: Uniformly add or adjust transition effects across a large number of existing presentations
Automated report generation: Automatically attach appropriate transition effects when programmatically generating presentations
Dynamic configuration: Automatically select matching transition styles based on slide content type

Environment Setup

Before starting, install the Python library that supports PowerPoint operations.

pip install Spire.Presentation

Once installed, import the relevant modules in your script to begin working.

Setting Basic Transition Effects

Each slide's transition effect is controlled through its SlideShowTransition property. The most basic operation is specifying a transition type for a slide, such as Push, Fade, or Wipe.

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

inputFile = "Sample.pptx"
outputFile = "SetTransitions.pptx"

# Create a presentation object
presentation = Presentation()

# Load the PPT file from disk
presentation.LoadFromFile(inputFile)

# Set push transition for the first slide
presentation.Slides[0].SlideShowTransition.Type = TransitionType.Push

# Set fade transition for the second slide with adjusted speed
presentation.Slides[1].SlideShowTransition.Type = TransitionType.Fade
presentation.Slides[1].SlideShowTransition.Speed = TransitionSpeed.Slow

# Save the document
presentation.SaveToFile(outputFile, FileFormat.Pptx2010)
presentation.Dispose()

The TransitionType enumeration defines all available transition types. Common options include Push, Fade, Cut, Circle, Comb, and Zoom. The Speed property controls the playback speed of the transition animation, supporting three levels: Fast, Medium, and Slow.

Advanced Transition Effect Properties

Beyond specifying the transition type, you can further configure detailed effect properties. For example, you can set whether the transition begins with a fade-in from a black background.

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

inputFile = "Sample.pptx"
outputFile = "TransitionEffects.pptx"

# Create a presentation object
presentation = Presentation()

# Load the PPT file from disk
presentation.LoadFromFile(inputFile)

# Set cut transition with fade-in from black
presentation.Slides[0].SlideShowTransition.Type = TransitionType.Cut
presentation.Slides[0].SlideShowTransition.Value.FromBlack = True

# Save the document
presentation.SaveToFile(outputFile, FileFormat.Pptx2010)
presentation.Dispose()

The Value property provides access to advanced transition parameters. When FromBlack is set to True, the transition animation begins with a fade from a black background, which is suitable for section breaks or emphasis moments.

Configuring Automatic Advance Timing

By default, slide transitions require a mouse click to trigger. In auto-playing presentation scenarios such as trade show displays or information dashboards, you need to set automatic advance timing so slides transition at predetermined intervals.

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

inputFile = "Sample.pptx"
outputFile = "AutoAdvance.pptx"

# Create a presentation object
presentation = Presentation()

# Load the PPT file from disk
presentation.LoadFromFile(inputFile)

# Set circle transition for the first slide, auto-advance after 3 seconds
presentation.Slides[0].SlideShowTransition.Type = TransitionType.Circle
presentation.Slides[0].SlideShowTransition.AdvanceOnClick = True
presentation.Slides[0].SlideShowTransition.AdvanceAfterTime = 3000

# Set comb transition for the second slide, auto-advance after 5 seconds
presentation.Slides[1].SlideShowTransition.Type = TransitionType.Comb
presentation.Slides[1].SlideShowTransition.Speed = TransitionSpeed.Slow
presentation.Slides[1].SlideShowTransition.AdvanceOnClick = True
presentation.Slides[1].SlideShowTransition.AdvanceAfterTime = 5000

# Set zoom transition for the third slide, auto-advance after 7 seconds
presentation.Slides[2].SlideShowTransition.Type = TransitionType.Zoom
presentation.Slides[2].SlideShowTransition.AdvanceOnClick = True
presentation.Slides[2].SlideShowTransition.AdvanceAfterTime = 7000

# Save the document
presentation.SaveToFile(outputFile, FileFormat.Pptx2010)
presentation.Dispose()

Two key properties are involved here: AdvanceOnClick controls whether manual click-to-advance is enabled, and AdvanceAfterTime sets the delay before automatic advance in milliseconds. When both are enabled, the presentation supports both manual clicking and automatic timeout-based advancement. If you want auto-play only, set AdvanceOnClick to False.

Applying Uniform Transitions to All Slides

In real-world projects, you often need to batch-apply the same transition effect to all slides in a presentation. Combined with loop iteration, this can be done efficiently.

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

inputFile = "Sample.pptx"
outputFile = "UniformTransitions.pptx"

# Create a presentation object
presentation = Presentation()

# Load the PPT file from disk
presentation.LoadFromFile(inputFile)

# Apply uniform fade transition to all slides
for slide in presentation.Slides:
    slide.SlideShowTransition.Type = TransitionType.Fade
    slide.SlideShowTransition.Speed = TransitionSpeed.Medium
    slide.SlideShowTransition.AdvanceOnClick = True
    slide.SlideShowTransition.AdvanceAfterTime = 5000

# Save the document
presentation.SaveToFile(outputFile, FileFormat.Pptx2010)
presentation.Dispose()

By iterating through the presentation.Slides collection, you can apply the same transition type, speed, and advance strategy to every slide. This approach is particularly well-suited for template generation workflows where consistent transition styling is required.

Practical Tips

Choosing Different Effects by Slide Position

You can set special transition effects for the first and last slides of a presentation to enhance structural emphasis:

slides = presentation.Slides

# First slide uses fade effect
slides[0].SlideShowTransition.Type = TransitionType.Fade
slides[0].SlideShowTransition.AdvanceAfterTime = 3000

# Middle slides use push effect
for i in range(1, len(slides) - 1):
    slides[i].SlideShowTransition.Type = TransitionType.Push
    slides[i].SlideShowTransition.AdvanceAfterTime = 5000

# Last slide uses zoom effect
slides[len(slides) - 1].SlideShowTransition.Type = TransitionType.Zoom
slides[len(slides) - 1].SlideShowTransition.AdvanceAfterTime = 4000

Combining with Sound Effects

Transition effects can be combined with sound to enhance presentation impact in specific scenarios:

presentation.Slides[0].SlideShowTransition.Type = TransitionType.Push
presentation.Slides[0].SlideShowTransition.SoundMode = TransitionSoundMode.StartSound

The SoundMode property controls whether sound plays during the transition. StartSound triggers a preset sound effect when the transition begins.

Conclusion

This article covered multiple approaches to adding slide transition effects in PowerPoint using Python, including basic transition type configuration, advanced effect property control, automatic advance timing, and batch uniform application. These operations address the main use cases from manual presentations to auto-playing displays.

The core API revolves around the SlideShowTransition object, using Type to specify the transition type, Speed to control animation speed, and AdvanceAfterTime to manage automatic advance timing. With these fundamentals in place, you can explore additional transition types and effect combinations to create richer visual transitions in your presentations.

Convert PowerPoint to PDF Using Python

Allen Yang — Thu, 20 Aug 2026 10:11:47 +0000

Converting PowerPoint presentations to PDF is a common requirement in document processing and distribution workflows. PDF files offer cross-platform compatibility, consistent formatting, and read-only stability, making them ideal for final delivery, print distribution, or archival purposes. By automating this conversion with Python, you can significantly improve efficiency when handling multiple files, eliminating the time cost of manual conversion.

This article covers how to convert PowerPoint presentations to PDF using Python, including full-document conversion, specific slide export, custom page sizes, and batch processing.

Why Use Python for Format Conversion

In office automation scenarios, using Python to convert PowerPoint to PDF offers several practical advantages:

Batch processing: Convert dozens or hundreds of presentations to PDF in one operation
Consistent output: Ensure uniform page size, orientation, and formatting across all output files
Flexible control: Choose to convert the entire document or export specific slides
Easy integration: Embed the conversion logic into larger workflows such as report generation or email attachment processing

Environment Setup

Before starting, install the Python library that supports PowerPoint operations.

pip install Spire.Presentation

Once installed, import the relevant modules in your script to begin working.

Converting an Entire Presentation to PDF

The most basic conversion operation transforms a complete PowerPoint file into a single PDF document. The process involves three steps: creating a document object, loading the source file, and saving to the target format.

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

inputFile = "Sample.pptx"
outputFile = "Output.pdf"

# Create a presentation object
presentation = Presentation()

# Load the PPT file from disk
presentation.LoadFromFile(inputFile)

# Save the presentation as PDF
presentation.SaveToFile(outputFile, FileFormat.PDF)
presentation.Dispose()

The core logic here is straightforward: the Presentation object loads the PPT file, then the SaveToFile() method specifies the output path and target format FileFormat.PDF. The Dispose() method releases file resources and should not be omitted in production code.

Converting a Specific Slide to PDF

In some cases, you may need to export only a single slide rather than the entire presentation. For example, extracting a particular page from a multi-section presentation for separate distribution.

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

inputFile = "Sample.pptx"
outputFile = "SlideToPDF.pdf"

# Create a presentation object
presentation = Presentation()

# Load the PPT file from disk
presentation.LoadFromFile(inputFile)

# Get the second slide (index starts from 0)
slide = presentation.Slides[1]

# Save the specific slide as PDF
slide.SaveToFile(outputFile, FileFormat.PDF)
presentation.Dispose()

Use presentation.Slides[index] to access a specific slide by its index, then call the slide-level SaveToFile() method for independent export. Since indexing starts at 0, Slides[1] refers to the second slide.

Customizing PDF Page Size

By default, the converted PDF retains the original slide dimensions. If you need to adjust the output to a standard paper size such as A4, you can modify the slide size settings before conversion.

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

inputFile = "Sample.pptx"
outputFile = "CustomPageSize.pdf"

# Create a presentation object
presentation = Presentation()

# Load the PPT file from disk
presentation.LoadFromFile(inputFile)

# Set page size to A4
presentation.SlideSize.Type = SlideSizeType.A4

# Set page orientation to landscape
presentation.SlideSize.Orientation = SlideOrienation.Landscape

# Save as PDF
presentation.SaveToFile(outputFile, FileFormat.PDF)
presentation.Dispose()

The SlideSizeType enumeration provides multiple preset sizes including A3, A4, B5, and other standard paper formats. The Orientation property controls page direction, supporting Landscape and Portrait modes. Note that changing the page size may affect content layout, so adjustments should be tested against your source documents.

Batch Converting Multiple Files

In real-world scenarios, you often need to process multiple PowerPoint files at once. Combined with Python's file handling capabilities, batch conversion becomes straightforward.

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

input_dir = "./presentations"
output_dir = "./pdfs"

# Ensure the output directory exists
os.makedirs(output_dir, exist_ok=True)

# Iterate through all .pptx files in the directory
for filename in os.listdir(input_dir):
    if filename.endswith(".pptx"):
        input_path = os.path.join(input_dir, filename)
        output_path = os.path.join(output_dir, filename.replace(".pptx", ".pdf"))

        presentation = Presentation()
        presentation.LoadFromFile(input_path)
        presentation.SaveToFile(output_path, FileFormat.PDF)
        presentation.Dispose()

        print(f"Converted: {filename} -> {os.path.basename(output_path)}")

This code iterates through all .pptx files in a specified directory, loading and converting each one to a same-named PDF file in the target directory. The os.makedirs() call ensures the output directory exists before conversion begins.

Practical Tips

Verifying Output After Conversion

In batch processing scenarios, it is good practice to verify that each output file exists and is non-empty after conversion:

if os.path.exists(output_path) and os.path.getsize(output_path) > 0:
    print(f"Conversion successful: {output_path}")
else:
    print(f"Conversion failed: {output_path}")

Handling Different Input Formats

In addition to .pptx files, the library also supports loading legacy .ppt format files. The conversion logic remains identical — just ensure the file extension is correct:

# Load a legacy PPT format file
presentation.LoadFromFile("legacy_presentation.ppt")
presentation.SaveToFile("output.pdf", FileFormat.PDF)

Combining with Page Margin Control

If you need to adjust page margins before conversion, you can modify slide layout parameters after setting the page size to ensure the content area of the output PDF meets your printing requirements.

Conclusion

This article covered several common approaches to converting PowerPoint to PDF using Python, including full-document conversion, specific slide export, custom page sizes, and batch file processing. These operations address the main scenarios from simple one-off conversions to automated batch workflows.

The core API follows a clear pattern: load the file through the Presentation object, then specify the output format and path via SaveToFile() or the slide-level SaveToFile() method. With these fundamentals in place, you can combine them with Python's file handling capabilities to build more sophisticated document conversion pipelines.

How to Work with Text Boxes in Word Documents Using Python: Insert, Format, Extract, and Remove

Allen Yang — Fri, 14 Aug 2026 10:34:13 +0000

A text box is a free-floating container in Word, often used for sidebars, callouts, label-style layouts, or holding images and tables at fixed positions. Unlike ordinary paragraphs, a text box can be positioned independently of the body text, giving you more layout flexibility. Inserting and styling them by hand is tedious, especially when a document needs many text boxes with a consistent look.

Python can insert and format text boxes in batch, place images and tables inside them, extract their text, and remove them as needed. This article demonstrates these common tasks using Spire.Doc for Python.

Setting Up the Environment

Install the Spire.Doc library:

pip install Spire.Doc

Then import the required modules in your script:

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

Inserting a Text Box and Setting Basic Styles

A text box is inserted through a paragraph's AppendTextBox() method, whose arguments are the width and height in points. After insertion, the Format property controls the border color, line style, and fill color, while Body holds the content inside the box:

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

# Insert a 240x35 point text box
textBox = paragraph.AppendTextBox(240, 35)

# Set border and fill styles
textBox.Format.HorizontalAlignment = ShapeHorizontalAlignment.Left
textBox.Format.LineColor = Color.get_Gray()
textBox.Format.LineStyle = TextBoxLineStyle.Simple
textBox.Format.FillColor = Color.get_DarkSeaGreen()

# Add text inside the box and format it
para = textBox.Body.AddParagraph()
textRange = para.AppendText("First text box in the document")
textRange.CharacterFormat.FontName = "Lucida Sans Unicode"
textRange.CharacterFormat.FontSize = 14
textRange.CharacterFormat.TextColor = Color.get_White()
para.Format.HorizontalAlignment = HorizontalAlignment.Center

document.SaveToFile("textbox.docx", FileFormat.Docx)
document.Close()

TextBoxLineStyle offers several line styles (Simple, ThinThick, Triple, and more), while LineDashing controls solid and dashed lines (Solid, Dot, DashDotDot, and so on). Combining the two produces different border effects.

Controlling Position and Borders Precisely

By default a text box flows with the paragraphs. To pin it to a specific spot on the page, set a positioning origin and coordinates:

document = Document()
section = document.AddSection()
textBox = section.AddParagraph().AppendTextBox(310, 90)

# Add text inside the box
para = textBox.Body.AddParagraph()
textRange = para.AppendText("Spire.Doc offers a simple and effective method...")
textRange.CharacterFormat.FontSize = 13

# Position the box relative to the page
textBox.Format.HorizontalOrigin = HorizontalOrigin.Page
textBox.Format.HorizontalPosition = 120
textBox.Format.VerticalOrigin = VerticalOrigin.Page
textBox.Format.VerticalPosition = 100

# Set line style, color, and width
textBox.Format.LineStyle = TextBoxLineStyle.Double
textBox.Format.LineColor = Color.get_CornflowerBlue()
textBox.Format.LineDashing = LineDashing.Solid
textBox.Format.LineWidth = 5

# Set the internal margins
textBox.Format.InternalMargin.Top = 15
textBox.Format.InternalMargin.Bottom = 10
textBox.Format.InternalMargin.Left = 12
textBox.Format.InternalMargin.Right = 10

document.SaveToFile("textbox_format.docx", FileFormat.Docx)
document.Close()

HorizontalOrigin / VerticalOrigin set the coordinate reference (the page, here), and HorizontalPosition / VerticalPosition give the concrete coordinates. InternalMargin controls the spacing between text and border, each side individually.

Inserting an Image into a Text Box

A text box can hold more than text — you can also fill its background with an image:

document = Document()
section = document.AddSection()
textBox = section.AddParagraph().AppendTextBox(220, 220)

# Set the position
textBox.Format.HorizontalOrigin = HorizontalOrigin.Page
textBox.Format.HorizontalPosition = 50
textBox.Format.VerticalOrigin = VerticalOrigin.Page
textBox.Format.VerticalPosition = 50

# Fill the text box with a picture
textBox.Format.FillEfects.Type = BackgroundType.Picture
textBox.Format.FillEfects.SetPicture("logo.png")

document.SaveToFile("image_textbox.docx", FileFormat.Docx)
document.Close()

Setting FillEfects.Type to BackgroundType.Picture and calling FillEfects.SetPicture() fills the whole box with the image, effectively using it as the box's background.

Inserting a Table into a Text Box

A text box can also contain a table, which is useful for receipts and detail cards that need aligned content:

document = Document()
section = document.AddSection()
textBox = section.AddParagraph().AppendTextBox(300, 100)

textBox.Format.HorizontalOrigin = HorizontalOrigin.Page
textBox.Format.HorizontalPosition = 140
textBox.Format.VerticalOrigin = VerticalOrigin.Page
textBox.Format.VerticalPosition = 50

# Add a title inside the box
title = textBox.Body.AddParagraph().AppendText("Table 1")

# Add a table and define its size
table = textBox.Body.AddTable(True)
table.ResetCells(4, 4)

data = [
    ["Name", "Age", "Gender", "ID"],
    ["John", "28", "Male", "0023"],
    ["Steve", "30", "Male", "0024"],
    ["Lucy", "26", "Female", "0025"],
]
for i in range(4):
    for j in range(4):
        table.Rows[i].Cells[j].AddParagraph().AppendText(data[i][j])

# Apply a built-in table style
table.ApplyStyle(DefaultTableStyle.TableColorful2)

document.SaveToFile("table_textbox.docx", FileFormat.Docx)
document.Close()

Body.AddTable(True) creates a table inside the box, ResetCells() sets the row and column count, and ApplyStyle() applies a preset style. Cells are filled one by one just like a regular table.

Extracting Text from Text Boxes

The reverse operation is just as common: reading the contents of text boxes from an existing document. Text boxes live among a paragraph's child objects, so you need to traverse them level by level:

document = Document()
document.LoadFromFile("document_with_textboxes.docx")

if document.TextBoxes.Count > 0:
    with open("extracted.txt", "w", encoding="utf-8") as f:
        for i in range(document.Sections.Count):
            section = document.Sections.get_Item(i)
            for j in range(section.Paragraphs.Count):
                paragraph = section.Paragraphs.get_Item(j)
                for k in range(paragraph.ChildObjects.Count):
                    obj = paragraph.ChildObjects.get_Item(k)
                    if obj.DocumentObjectType == DocumentObjectType.TextBox:
                        textbox = obj
                        for x in range(textbox.ChildObjects.Count):
                            child = textbox.ChildObjects.get_Item(x)
                            if child.DocumentObjectType == DocumentObjectType.Paragraph:
                                f.write(child.Text)
                            elif child.DocumentObjectType == DocumentObjectType.Table:
                                table = child
                                for r in range(table.Rows.Count):
                                    for c in range(table.Rows[r].Cells.Count):
                                        for p in range(table.Rows[r].Cells[c].Paragraphs.Count):
                                            f.write(table.Rows[r].Cells[c].Paragraphs.get_Item(p).Text)

document.Close()

The DocumentObjectType enum identifies each object: content inside a text box can be either a paragraph or a table, and the two must be handled separately. This logic can be used to batch-collect information scattered across many text boxes.

Removing a Text Box

Unwanted text boxes can be removed by index or cleared all at once:

document = Document()
document.LoadFromFile("template.docx")

# Remove the first text box
document.TextBoxes.RemoveAt(0)

# To clear all text boxes, use:
# document.TextBoxes.Clear()

document.SaveToFile("removed_textbox.docx", FileFormat.Docx)
document.Close()

The TextBoxes collection holds every text box in the document; RemoveAt() removes one by index, and Clear() removes them all.

Practical Tips

Text box dimensions and coordinates are in points; one inch is about 72 points, so convert when needed.
For fixed positioning, set HorizontalOrigin / VerticalOrigin to Page before setting Position, otherwise the coordinates may be computed against a different reference.
For CJK documents, specify a CJK font (such as Microsoft YaHei) explicitly to avoid font fallback shifting the layout across machines.
Call Close() when finished to release the file handle.

Conclusion

This article covered the full workflow of working with text boxes in Word using Python: inserting them with AppendTextBox(), styling and positioning them through the Format property, placing images and tables inside, extracting their contents by traversing DocumentObjectType, and removing them via the TextBoxes collection. With these techniques, you can hand tedious text box layout over to a script and keep your documents consistent and efficient.

How to Build an AI Agent for Automated Contract Review and Generation

Allen Yang — Thu, 13 Aug 2026 07:48:06 +0000

Every Monday morning, a procurement team opens the same inbox and finds the same pile: supplier agreements. Master services agreements, NDAs, purchase orders, amendments — a dozen or more new documents, each one sent over as a PDF or a Word file by a vendor whose formatting matches nothing your team has seen before.

Here is what has to happen to each of them before the week is over:

someone reads the agreement and pulls out the key terms — who the parties are, how much it is worth, when it starts, how it can be ended;
the same terms are keyed by hand into a review tracker;
the agreement is checked against company policy and approved or sent back;
and for every vendor that passes, a brand-new contract has to be produced — the standard template opened, a dozen fields replaced, and an export to PDF — per vendor, every time.

At most companies this workflow is manual, repetitive, and error-prone. It is also exactly the kind of job an AI document agent was built for. In this article I'll walk through why, and then build one in .NET that reviews a batch of agreements, applies approval rules, and generates a signed-ready contract for every vendor that passes.

The manual workflow, and why it hurts

Strip the manual process down to its shape and it looks like this:

PDF contracts 
→ read each one 
→ key terms into Excel 
→ human approval 
→ re-type into a contract template 
→ export PDF per vendor

It is the shape of a pipeline with a human in the middle of every hop, and that shape is what makes it expensive:

The same document gets read multiple times. Review, logging, and drafting each mean opening the agreement again. Three passes over the same text, by the same people.
Data is copied by hand. The vendor name, the contract value, the payment terms travel from a PDF into a spreadsheet cell by cell. Transposition errors happen. Fields get skipped. Nobody notices until the contract goes out wrong.
Every approved vendor means a fresh contract. Opening the template, replacing a dozen {{Placeholder}} fields, exporting a PDF — repeated once per vendor, with the formatting that legal and finance care about hanging on your ability to do it identically every time.
Volume spikes break the plan. A new supplier panel, a quarter-end push, an audit — the backlog multiplies and the team just works later.

None of these tasks are hard. They are simply numerous and uniform, which is precisely the profile of work that software should absorb.

The idea: an agent that reads, decides, and writes documents

The workflow collapses if one component can do three things:

Understand a document — read a supplier agreement in whatever format the vendor sent, and pull out the parties, value, dates, and obligations.
Decide — apply your company's approval rules to what it extracted.
Manipulate — take a contract template and a list of approved vendors, and produce one well-formed, properly formatted contract per vendor.

That is the difference between an AI chatbot (reads text, talks back) and an AI agent (reads a document, acts on it, and produces a new document as the result). The pipeline becomes:

Documents 
→ AI review 
→ structured data 
→ business rules 
→ approved vendors 
→ contract generation

The person who used to copy fields between files now approves exceptions and reviews the output. Everything in the middle is automated.

Building it in .NET with Spire.Agent.Office

In a .NET application, this workflow can be implemented with Spire.Agent.Office — a document AI agent SDK that exposes one AI() processor for Word, Excel, PowerPoint, and PDF documents. The design is simple: you load a document with the ordinary Spire API, attach the agent, and give it a natural-language instruction. The agent figures out the rest.

The setup is a NuGet package and a token:

dotnet add package Spire.Agent.Office

Spire.Agent.Office activates its AI features with a SpireToken (free and commercial editions are available from the vendor site), and it works on .NET 10 across Windows, macOS, Linux, and Docker.

Step 1 — Configure the agent once

All four formats share one configuration. Create an AIOptions, set the token, and point WorkDir at the folder where sessions and generated files should land:

using Spire.Agent.Office.AI;
using Spire.Agent.Office.Extensions;

AIOptions agent = new AIOptions
{
    SpireToken = spireToken,       // from your Spire.Agent.Office account
    WorkDir    = @"C:\legal-ops\work",
    TimeoutMs  = 300_000
};

WorkDir matters: it is where the agent keeps its session folders — we'll look inside one of them in a moment.

Step 2 — Review every agreement in the inbox

The core call is ExecuteInstruction(document, instruction, outputPath, attachments). Point it at a document object, describe what you want in plain language, and it returns an AIResult. Here we load each PDF that arrived this week and ask for a structured review brief:

using Spire.Pdf;

string reviewInstruction =
    "Review this supplier agreement and write a Markdown brief: a one-row table with " +
    "the parties, effective date, contract value, payment terms, liability cap, and " +
    "termination notice, then a bullet list of any clauses that look unusual for a " +
    "standard supplier agreement.";

foreach (string file in Directory.GetFiles(inboxPath, "*.pdf"))
{
    string briefPath = Path.Combine(
        briefsPath, Path.GetFileNameWithoutExtension(file) + ".md");

    using (PdfDocument agreement = new PdfDocument())
    {
        agreement.LoadFromFile(file);

        AIResult result = agreement.AI(agent).ExecuteInstruction(
            agreement, reviewInstruction, briefPath, Array.Empty<string>());

        if (result is null || !result.Success)
            throw new InvalidOperationException(
                $"Review failed for {Path.GetFileName(file)}: {result?.ErrorMessage}");
    }
}

The agent reads the PDF in its native format — no text-extraction preprocessing, no per-layout rules. A few minutes of agent runtime replaces the read-and-copy part of the week.

Step 3 — Let business rules make the call

This is the step people usually skip, and it is the one that keeps an AI workflow defensible. The decision — which vendors pass — should not be left to a language model. It belongs in deterministic, auditable code:

// The agent extracts; your code decides.
var approved = new List<ReviewResult>();
foreach (ReviewResult r in ParseBriefs(briefsPath))          // from Step 2
{
    bool passes = r.PartyCount >= 2
               && r.LiabilityCap >= 1_000_000m               // our floor
               && r.TerminationNotice <= 60;                 // days
    if (passes) approved.Add(r);
}
WriteVendorList(@"C:\legal-ops\data\approved-vendors.xlsx", approved);

(ParseBriefs and WriteVendorList are whatever you already use to read a tracker and emit a spreadsheet — or you can ask the agent to write the extracted fields straight to .xlsx, .json, or .csv. The important thing is where the decision lives: in code, where it can be reviewed, versioned, and quoted in an audit.)

Only vendors that pass move to the last step.

Step 4 — Generate one contract per approved vendor

Now the agent does the part a deterministic SDK would do with dozens of Replace calls: take one template plus the approval list and produce a contract for every row.

using Spire.Doc;

string[] attachments = { @"C:\legal-ops\data\approved-vendors.xlsx" };

using (Document contract = new Document())
{
    contract.LoadFromFile(@"C:\legal-ops\templates\supplier-contract.docx");

    AIResult result = contract.AI(agent).ExecuteInstruction(
        contract,
        "Issue one purchase contract per approved vendor: read 'approved-vendors.xlsx' " +
        "row by row, fill the {{Placeholder}} fields in this template with each vendor's " +
        "data, preserve the template layout and styling, and save each contract as an " +
        "independent PDF in the work directory.",
        null,                              // one file per vendor, written by the agent
        attachments);

    if (result is null || !result.Success)
        throw new InvalidOperationException(
            $"Contract generation failed: {result?.ErrorMessage}");
}

The template carries the placeholders; the spreadsheet carries the data; one instruction drives every contract. Clause numbering, tables, and fonts survive because the output is produced by a deterministic document engine, not a language model improvising a file format. And note the null output path: with no single file for the agent to return, it writes one PDF per vendor — into its own session folder under WorkDir.

Under the hood: what the agent actually left on disk

Here is the part I find most interesting, and the reason an agent like this is trustworthy enough for a legal workflow. When you call ExecuteInstruction, the agent runs a session, and every session is written to disk under WorkDir:

C:\legal-ops\work\
└─ .office_use_tmp\
   └─ Word\
      └─ 0812093540_c6825d69dd\     ← one session per ExecuteInstruction call
         ├─ process.csx             ← the C# script the agent generated
         ├─ input.docx              ← the contract template it worked on
         ├─ approved-vendors.xlsx   ← the approval list it read
         ├─ output_Brightpath_Analytics_Ltd.pdf
         ├─ output_Evercrest_Digital_Solutions_Inc.pdf
         └─ output_Novalune_Systems_LLC.pdf

Each session folder is flat and self-contained: the input documents, the generated script, and one output file per approved vendor — named after the vendor — sitting side by side. The session id is a timestamp plus a short hash, so folders don't collide when you run the agent in batches.

The agent doesn't mutate your files by magic. It plans the task, writes a real C# script (process.csx) that drives the Spire document APIs, executes it with the .NET scripting runtime, and stages the inputs and outputs in the session folder. The script is self-contained: it pulls in the Spire packages it needs with its own #r "nuget: ..." directives at the top, so it runs against the exact versions it names — independent of whatever your application happens to have loaded.

That last point is worth being concrete about, because process.csx is exactly what you would expect a .NET developer to write by hand:

// process.csx — the agent generated this script (abridged)
var workDir = Args[0];
using (var wb = new Workbook())
{
    wb.LoadFromFile(Path.Combine(workDir, "approved-vendors.xlsx"));
    // ... read each vendor row into `vendors`
}

foreach (var v in vendors)
{
    var doc = new Document();
    doc.LoadFromFile(Path.Combine(workDir, "input.docx"));
    doc.Replace("{{Vendor Name}}", v["Vendor Name"]);
    doc.Replace("{{Payment Terms}}", v["Payment Terms"]);
    doc.Replace("{{Contract Term}}", v["Contract Term"]);
    var fileName = "output_" + v["Vendor Name"].Replace(' ', '_') + ".pdf";
    doc.SaveToFile(Path.Combine(workDir, fileName), Spire.Doc.FileFormat.PDF);
    doc.Dispose();
}

The agent read the approval workbook, loaded the template for every row, replaced the placeholders one by one, and exported a PDF per vendor — then left the script on disk for you to read. That is the deterministic document layer doing its job: the model decided what to fill, and the script is the ordinary Spire API code that filled it.

Three practical consequences:

It's inspectable. Open process.csx and you can read the exact operations that were run on your template — which placeholders were replaced, how the PDFs were exported. There is no opaque black box to take on faith.
It's auditable. The session folder is a complete record: input documents in, the script, output documents out. For contracts, that paper trail is the difference between automation you can defend and automation you can only hope about.
The output is a real document. Because the script drives a deterministic engine, the result is a well-formed .docx or .pdf, not a text blob. The model decides what to do; the engine guarantees how the file is built.

This is why a document agent is different from "AI that summarizes PDFs": it leaves a reproducible, inspectable trace, and it hands back files you can sign.

Why an agent instead of just an LLM?

If you have access to an LLM API, the temptation is to skip the document layer and "generate a contract" with a prompt. That fails in three ways that matter here:

LLMs can't reliably read or write Office files. They see text, not the structure of a .docx or .pdf. Reading a Word template, keeping a table intact, and emitting a valid PDF means building your own extraction and reconstruction pipeline.
Formatting is the deliverable. Contract templates carry clause numbering, tables, and fonts that legal and finance care about. A raw LLM returns text; the formatting you lose is exactly what matters to the recipient.
You own the whole orchestration. Prompt design, parsing, file I/O, and error handling all become your code to maintain, on top of the LLM's non-determinism.

An agent pairs the model's language understanding with a deterministic document layer: the model decides what to extract and fill, and the document layer guarantees the file. That is the difference between a demo and a workflow a team can ship — and, as we just saw, the difference is literally inspectable on disk.

The pattern doesn't stop at contracts

Notice that the pipeline — understand → decide → manipulate → batch — has nothing contract-specific in it. The same agent, with a different instruction and a different template, handles the jobs teams automate next:

Resume screening: extract candidate details from a folder of PDF/DOCX resumes, apply hiring rules, generate offer letters.
Invoice processing: pull invoice number, vendor, amount, and tax from PDFs, flag exceptions, emit a payment report.
RFP response: read the requirements document, match them against your capability library, and draft a proposal.
Vendor quote comparison: normalize quotes from PDF and Excel, compare line by line, and produce a purchasing analysis.

Each one is the same architecture: an instruction in, a real document out, and a session folder on disk showing exactly what happened.

Wrapping up

Contract review and generation is one of the fastest places to get value from an AI document agent: a batch of PDFs in, a list of approved vendors decided by code, and one signed-ready contract per vendor out — with a reproducible process.csx session you can audit behind every file.

The workflow we built runs in seconds per document, replaces the read-and-copy part of a legal analyst's week, and keeps the two things an AI should never do out of the loop: the binary approval decision stays in code, and the final document stays a real, well-formed file.

If you want to try it, the Spire.Agent.Office getting-started tutorial walks through the integration, and the product overview covers the four agents (Word, Excel, PowerPoint, PDF) it exposes. The example above is the whole integration surface — everything else is the instruction.

How to Set PowerPoint Slide Backgrounds in Python

Allen Yang — Thu, 13 Aug 2026 07:02:42 +0000

The slide background sets the visual tone for an entire presentation. Whether you are applying brand colors, using gradients for depth, or placing a full-screen image, background setup is the first step before arranging content. Setting backgrounds manually slide by slide is time-consuming, especially for large decks that need a consistent look.

Python can set slide backgrounds in batch and with precision. Using Spire.Presentation for Python, this article walks through solid, gradient, and image backgrounds, as well as how to apply a uniform background across a deck via the slide master.

Setting Up the Environment

Install the Spire.Presentation library:

pip install Spire.Presentation

Then import the required modules in your script:

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

Background settings are all centered on each slide's SlideBackground property. Let's go through each option.

Setting a Solid Background

A solid background is the simplest and most common choice. Create a Presentation object, load the deck, then set the background type to Custom and the fill type to solid for the target slide:

presentation = Presentation()
presentation.LoadFromFile("sample.pptx")

# Get the first slide and set the background type
slide = presentation.Slides[0]
slide.SlideBackground.Type = BackgroundType.Custom

# Use a solid fill
slide.SlideBackground.Fill.FillType = FillFormatType.Solid
slide.SlideBackground.Fill.SolidColor.Color = Color.get_SkyBlue()

presentation.SaveToFile("solid_background.pptx", FileFormat.Pptx2013)
presentation.Dispose()

Two points matter here: SlideBackground.Type must be set to BackgroundType.Custom, otherwise later fill settings have no effect; and Fill.SolidColor.Color picks the color through the Color.get_*() family, such as Color.get_SkyBlue().

Setting a Gradient Background

A gradient transitions smoothly between two or more colors and adds more depth than a solid fill. The core of a gradient is its gradient stops — each stop defines a position and a color, and together they form the full gradient.

The most basic approach is to append two known-color stops:

slide = presentation.Slides[0]
slide.SlideBackground.Type = BackgroundType.Custom
slide.SlideBackground.Fill.FillType = FillFormatType.Gradient

# Set the gradient shape and style
slide.SlideBackground.Fill.Gradient.GradientShape = GradientShapeType.Linear
slide.SlideBackground.Fill.Gradient.GradientStyle = GradientStyle.FromCorner1

# Append two stops: position (0~1) and color
slide.SlideBackground.Fill.Gradient.GradientStops.AppendByKnownColors(1, KnownColors.SkyBlue)
slide.SlideBackground.Fill.Gradient.GradientStops.AppendByKnownColors(0, KnownColors.White)

The first argument of AppendByKnownColors() is the stop position, ranging from 0 to 1; the second is the color. The code above produces a linear gradient from white (position 0) to sky blue (position 1).

For finer control, use AppendByColor() to set any position and color, and adjust the direction with LinearGradientFill.Angle:

slide.SlideBackground.Fill.FillType = FillFormatType.Gradient
slide.SlideBackground.Fill.Gradient.GradientStops.AppendByColor(0.1, Color.get_LightSeaGreen())
slide.SlideBackground.Fill.Gradient.GradientStops.AppendByColor(0.7, Color.get_LightCyan())
slide.SlideBackground.Fill.Gradient.GradientShape = GradientShapeType.Linear
slide.SlideBackground.Fill.Gradient.LinearGradientFill.Angle = 45

Angle is measured in degrees and controls the gradient direction. Combining it with multiple stops produces quite refined gradients.

Setting an Image Background

To use an image as the background — for covers or promotional slides — first embed the image into the presentation, then reference it from the background. The flow is: read the image stream, obtain an image reference with Images.AppendStream(), then set the background fill to picture and point it at that reference:

# Read and embed the image into the presentation
stream = Stream("background.png")
imageData = presentation.Images.AppendStream(stream)

# Set the background to picture
slide = presentation.Slides[0]
slide.SlideBackground.Type = BackgroundType.Custom
slide.SlideBackground.Fill.FillType = FillFormatType.Picture
slide.SlideBackground.Fill.PictureFill.FillType = PictureFillType.Stretch
slide.SlideBackground.Fill.PictureFill.Picture.EmbedImage = imageData

PictureFill.FillType = PictureFillType.Stretch stretches the image to cover the whole slide, and Picture.EmbedImage binds it to the previously embedded image data.

Another way to achieve an image background is to skip the background property and instead place a full-screen image shape at the bottom layer. This treats the image as a normal shape, which is convenient when stacking text or other elements on top:

rect = RectangleF.FromLTRB(0, 0, presentation.SlideSize.Size.Width, presentation.SlideSize.Size.Height)
presentation.Slides[0].Shapes.AppendEmbedImageByPath(ShapeType.Rectangle, "background.png", rect)

RectangleF.FromLTRB() defines a rectangle covering the full slide using its actual width and height. The two methods suit different situations: the former is background semantics, while the latter is shape semantics, easier to combine with overlaid content.

Applying a Uniform Background via the Slide Master

When an entire deck needs the same background, setting it slide by slide is inefficient. A better approach is to set the master background — every slide that uses the master inherits it:

presentation = Presentation()

# Set the master background to a solid color
presentation.Masters[0].SlideBackground.Type = BackgroundType.Custom
presentation.Masters[0].SlideBackground.Fill.FillType = FillFormatType.Solid
presentation.Masters[0].SlideBackground.Fill.SolidColor.Color = Color.get_LightSalmon()

presentation.SaveToFile("master_background.pptx", FileFormat.Pptx2013)
presentation.Dispose()

Masters[0] is the deck's default slide master. After changing its background, newly created slides inherit it, keeping the whole deck visually consistent. When a specific slide needs an exception, override that slide's background individually.

Practical Tips

Always set SlideBackground.Type = BackgroundType.Custom before configuring a fill — solid, gradient, and picture settings will be ignored otherwise, and it is the step most easily missed.
For image backgrounds, use an image whose aspect ratio matches the slide and pair it with PictureFillType.Stretch to avoid empty margins; for mismatched images, consider laying the image down as a shape and cropping manually.
For batch processing, iterate over presentation.Slides in a loop and apply the same background settings to every slide to keep the style uniform.
Call Dispose() when finished to release resources and avoid locking the file.

Conclusion

This article covered several ways to set PowerPoint slide backgrounds with Python: solid backgrounds via FillType.Solid and SolidColor; gradient backgrounds via gradient stops, GradientShape, and LinearGradientFill.Angle; image backgrounds via Images.AppendStream() and a full-screen image shape; and deck-wide backgrounds via Masters[0].SlideBackground. With these techniques, you can hand background layout over to a script and keep every deck visually consistent.

Python Guide to Converting Word Documents and PDFs

Allen Yang — Fri, 07 Aug 2026 10:55:40 +0000

Word and PDF are two of the most common document formats, but they serve different purposes. Word is designed for editing and layout, while PDF is meant for distribution and printing. In day-to-day work you often need to move between them — exporting a contract or report from Word to PDF to send to a client, or converting a received PDF back to Word for further editing. Doing this manually, file by file, is tedious, especially when you have dozens or hundreds of documents.

Python can handle such conversions in batch, processing an entire folder with a single script. Using Spire.Doc for Python and Spire.PDF for Python, this article walks through both directions — Word to PDF and PDF to Word — along with common conversion options.

Setting Up the Environment

Install the library that matches your needs. For Word-to-PDF conversion, install Spire.Doc:

pip install Spire.Doc

For PDF-to-Word conversion, install Spire.PDF:

pip install Spire.PDF

If you need both directions, install them together:

pip install Spire.Doc Spire.PDF

Each library brings its own document object: Spire.Doc provides Document, and Spire.PDF provides PdfDocument.

Converting a Word Document to PDF

Word-to-PDF conversion is one of the most common tasks — for example, freezing an editable draft into a final, tamper-resistant version. With Spire.Doc, the process is straightforward: load the Word document, then save it in PDF format.

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

# Load a Word document
document = Document()
document.LoadFromFile("annual_report.docx")

# Save it as PDF
document.SaveToFile("annual_report.pdf", FileFormat.PDF)
document.Close()

The first argument of SaveToFile() is the output path; the second specifies the output format. Passing FileFormat.PDF tells the library to perform the full Word-to-PDF conversion, preserving layout elements such as pagination, fonts, and images.

If the source is an older .doc file, it is safer to specify the format explicitly when loading:

document.LoadFromFile("legacy_document.doc", FileFormat.Doc)

Controlling the Conversion with Parameters

Saving directly usually produces good results, but some scenarios require finer control over the output. This is where the ToPdfParameterList object comes in.

Keeping Bookmarks in the PDF

For long documents, you may want readers to jump between sections as easily as they use a table of contents. You can generate bookmarks from the document headings:

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

document = Document()
document.LoadFromFile("user_manual.docx")

# Create conversion parameters
params = ToPdfParameterList()
# Generate bookmarks from headings
params.CreateWordBookmarks = True
params.CreateWordBookmarksUsingHeadings = True

document.SaveToFile("user_manual.pdf", params)
document.Close()

When CreateWordBookmarksUsingHeadings is True, bookmarks are generated from the document's heading styles; when set to False, only explicit Word bookmarks in the document are used.

Embedding Fonts for Consistent Rendering

If the machine that opens the converted PDF does not have the fonts used in the document, the text can be substituted and the layout may break. Embedding the fonts into the PDF avoids this:

document = Document()
document.LoadFromFile("flyer.docx")

params = ToPdfParameterList()
# Embed all fonts into the PDF
params.IsEmbeddedAllFonts = True

document.SaveToFile("flyer.pdf", params)
document.Close()

The trade-off is a larger file size, which is usually acceptable for formal documents where layout consistency matters.

Protecting the PDF with a Password

If a PDF should only be viewable by specific people, you can encrypt it during conversion:

from spire.doc.common import *

document = Document()
document.LoadFromFile("business_plan.docx")

params = ToPdfParameterList()
params.PdfSecurity.Encrypt(
    "owner123",
    "user123",
    PdfPermissionsFlags.Default,
    PdfEncryptionKeySize.Key128Bit
)

document.SaveToFile("business_plan.pdf", params)
document.Close()

The first two arguments of PdfSecurity.Encrypt() are the owner password and the user password. The owner password grants full control (including permission changes), while the user password is required to open the file.

Converting a PDF Document to Word

The reverse direction is equally common: when PDF content needs to be edited, quoted, or re-laid-out, converting it back to Word is the most convenient route. Using Spire.PDF's PdfDocument object, you load the PDF and save it as a Word file.

from spire.pdf import *
from spire.pdf.common import *

# Load a PDF document
pdf = PdfDocument()
pdf.LoadFromFile("requirements.pdf")

# Save as .docx
pdf.SaveToFile("requirements.docx", FileFormat.DOCX)
pdf.Close()

FileFormat.DOCX targets the modern Word format. If the recipient uses an older Word version, you can switch to FileFormat.DOC to produce a .doc file:

pdf.SaveToFile("requirements.doc", FileFormat.DOC)

A note on expectations: a PDF does not store semantic information such as paragraphs or tables, so the converted Word file is an editable text layout. Content that was an image in the PDF stays an image after conversion; it does not become editable text automatically. This type of conversion suits scenarios where you need to edit the text, not where you need to edit image content.

Setting Properties on the Converted Word Document

The output Word document inherits some basic properties, but you can also specify metadata such as title, author, and subject in advance through PdfToDocConverter:

from spire.pdf import *
from spire.pdf.common import *

# Create the converter and specify the input PDF
converter = PdfToDocConverter("research_report.pdf")
# Set properties for the output document
converter.DocxOptions.Title = "Research Report"
converter.DocxOptions.Authors = "Marketing Team"
converter.DocxOptions.Subject = "Q3 User Survey"

# Convert to .docx
converter.SaveToDocx("research_report.docx")

DocxOptions supports several fields — title, author, subject, category, and more — which is useful for filling in consistent metadata when exporting documents in batch.

Practical Tips

For batch conversion, iterate over a directory with os.listdir(), calling LoadFromFile() and SaveToFile() in a loop to process an entire folder at once.
Font issues in Word-to-PDF conversion appear most often with CJK documents; prefer IsEmbeddedAllFonts or SetCustomFontsFolders() to point the converter at the needed fonts.
If the source PDF is a scan (pages that are entirely images), the converted Word file cannot be edited as text — OCR is required first.
Call Close() after conversion to release file handles and avoid locking files that later writes may need.

Conclusion

This article covered the complete flow of converting between Word and PDF with Python. Spire.Doc handles Word-to-PDF conversion through SaveToFile() with FileFormat.PDF, and ToPdfParameterList provides control over bookmarks, font embedding, and encryption. Spire.PDF handles the reverse direction via FileFormat.DOCX or PdfToDocConverter, including document properties. Both directions support batch processing, so you can leave tedious format conversions to a script.

How to Encrypt and Protect Word Documents with Python

Allen Yang — Fri, 07 Aug 2026 10:46:04 +0000

Word documents often contain sensitive content such as contracts, financial statements, or internal policies. When sharing these files, you frequently need to restrict access — either requiring a password to open the document, or allowing reading only while blocking edits. Setting these options manually in Word is tedious, and it becomes impractical when distributing many files at once. Python can handle this in a unified way: a single script can add passwords, apply editing restrictions, and even leave specific paragraphs editable across a whole batch of documents.

This article demonstrates how to encrypt Word documents, apply editing protection, define editable ranges, and remove protection using Spire.Doc for Python.

Setting Up the Environment

Install the Spire.Doc library:

pip install Spire.Doc

Then import the required modules in your script:

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

Encrypting a Document with a Password

The most direct form of protection is setting an open password. Only users who enter the correct password can view the content. Encryption is done with the Encrypt() method:

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

# Set the open password
document.Encrypt("E-iceblue")

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

After encryption, opening the file prompts for a password. The string passed to Encrypt() is the open password, and the document is written to disk in encrypted form when saved.

Restricting Editing with Protection Types

If the document should be viewable but not modifiable, use the Protect() method. It takes two arguments: the protection type and a password. The password is required to remove protection, and the protection type is specified by the ProtectionType enum.

document = Document()
document.LoadFromFile("meeting_minutes.docx")

# Allow reading only; modifications require the password
document.Protect(ProtectionType.AllowOnlyReading, "123456")

document.SaveToFile("minutes_readonly.docx", FileFormat.Docx2013)
document.Close()

ProtectionType offers several levels of granularity:

AllowOnlyReading: reading only; all editing operations are blocked;
AllowOnlyFormFields: only form fields can be filled, suitable for documents that need input;
NoProtection: removes all protection.

The choice of protection type depends on how the document will be used. For example, a notice that needs to collect information can work well with AllowOnlyFormFields.

Leaving Editable Ranges in a Protected Document

In some scenarios, the whole document should be read-only, but specific paragraphs must remain editable — for instance, a signature line in a contract or answer areas in a survey. The approach is to protect the document first, then wrap the editable paragraphs with PermissionStart and PermissionEnd tags:

document = Document()
document.LoadFromFile("survey.docx")

# Protect the whole document first
document.Protect(ProtectionType.AllowOnlyReading, "password")

# Create a pair of start and end tags for the editable range
start = PermissionStart(document, "editID")
end = PermissionEnd(document, "editID")

# Insert the tags at the beginning and end of the first paragraph
first_paragraph = document.Sections[0].Paragraphs[0]
first_paragraph.ChildObjects.Insert(0, start)
first_paragraph.ChildObjects.Add(end)

document.SaveToFile("survey_editable.docx", FileFormat.Docx)
document.Close()

PermissionStart and PermissionEnd share the same ID to identify one range; the content between them is the editable area. Readers can then modify the marked paragraphs while the rest of the document stays protected.

Locking Specific Sections

For documents made up of multiple sections, you can protect only part of them. The idea is to enable protection on the whole document first, then set ProtectForm = False on the sections that should remain editable:

document = Document()

# Add two sections with text
s1 = document.AddSection()
s2 = document.AddSection()
s1.AddParagraph().AppendText("Section 1: protected content")
s2.AddParagraph().AppendText("Section 2: editable content")

# Protect the whole document with the form fields protection type
document.Protect(ProtectionType.AllowOnlyFormFields, "123")

# Unprotect section 2
s2.ProtectForm = False

document.SaveToFile("section_protection.docx", FileFormat.Docx2013)
document.Close()

A typical use case is a document whose first part contains fixed instructions, while the second part holds forms or content meant for the reader to fill in.

Opening an Encrypted Document and Removing Protection

To modify a protected document later, load it with the password and then remove the protection:

document = Document()

# Load the encrypted document with its password
document.LoadFromFile("contract_encrypted.docx", FileFormat.Docx, "E-iceblue")

# Remove all protection
document.Protect(ProtectionType.NoProtection)

document.SaveToFile("contract_decrypted.docx", FileFormat.Docx)
document.Close()

The third argument of LoadFromFile() is the document's open password. Calling Protect(ProtectionType.NoProtection) afterwards removes the editing restrictions.

Practical Tips

Passwords are stored only in the generated file; the script itself does not record them. If a password is lost, the encrypted document cannot be opened normally, so manage passwords outside the script.
Protect() and Encrypt() can be combined: set an open password first, then apply editing protection, forming a double layer of defense.
For batch processing, put passwords and file paths in a list or loop to encrypt an entire batch of documents at once.

Conclusion

This article walked through the complete workflow of encrypting Word documents, applying editing protection, defining editable ranges, protecting individual sections, and removing protection with Python. The core APIs are Encrypt(), Protect(), PermissionStart / PermissionEnd, and the ProtectForm property. In real projects, these operations can be wrapped into functions and applied to batches of documents in a loop, replacing a large amount of repetitive manual work with a consistent security policy.

How to Efficiently Combine Multiple Excel Files with Python

Allen Yang — Fri, 31 Jul 2026 07:45:26 +0000

In real-world work, data is often scattered across multiple Excel files — sales reports split by month, employee information organized by department, or order data tallied by region. When it comes time to consolidate and analyze, the first step is merging these files into a single workbook. Copying and pasting dozens of worksheets by hand is both time-consuming and error-prone; a single slip can lose formatting or miss data.

This article shows how to use Python to merge multiple Excel files (.xlsx and .xls) into one workbook. After merging, each source file's worksheets are preserved under their original names and in their original order, with formatting and data fully intact — ready for sorting, filtering, or data analysis.

Why Merge Excel Files with Code

Replacing manual merging with code brings three main benefits:

Batch processing - Whether there are 3 files or 30, the process is identical, and everything completes in a single run
Format preservation - Worksheets are copied along with cell styles, formulas, and other content, avoiding the formatting chaos caused by manual pasting
Reusable workflow - The merging logic can be wrapped into a script and run on a weekly or monthly schedule, forming a stable data consolidation routine

Environment Setup

This article uses the Spire.XLS for Python library, which can be installed with:

pip install Spire.XLS

Merging Multiple Excel Files

The core idea is simple: create a new workbook as the target, then load each source file in a loop and copy its worksheets one by one into the target workbook. The AddCopy method handles worksheet copying, and its second parameter, WorksheetCopyType.CopyAll, ensures that everything — data, formatting, formulas, and more — is copied along.

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

# Files to merge
files = ["Sales_January.xlsx", "Sales_February.xlsx", "Sales_March.xls"]

# Create the target workbook and specify its version
newbook = Workbook()
newbook.Version = ExcelVersion.Version2013

# Clear the default worksheet to avoid a blank sheet in the result
newbook.Worksheets.Clear()

# Temporary workbook for loading source files one at a time
tempbook = Workbook()

for file in files:
    # Load the source file
    tempbook.LoadFromFile(file)
    # Copy each worksheet from the source file into the target workbook
    for sheet in tempbook.Worksheets:
        newbook.Worksheets.AddCopy(sheet, WorksheetCopyType.CopyAll)

# Save the merged result
newbook.SaveToFile("Merged.xlsx", ExcelVersion.Version2013)

newbook.Dispose()
tempbook.Dispose()

A few key points:

A new Workbook() comes with an empty worksheet named "Sheet1"; calling Worksheets.Clear() removes it so the final file contains only the data actually merged in
LoadFromFile automatically detects the .xlsx and .xls formats from the file content, so mixed-format files can be processed together
Each loop iteration reloads a file and overwrites tempbook, so no matter how many files are merged, only one copy of source data stays in memory at a time
Merged worksheets keep their original names and order, making it easy to tell where the data came from

Merging Selected Worksheets

Sometimes you only need part of each file's worksheets rather than all of them. Since the first argument of AddCopy accepts a worksheet object, you can grab the sheets you need by index and decide which ones to copy:

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

newbook = Workbook()
newbook.Worksheets.Clear()
tempbook = Workbook()

# Load the first source file
tempbook.LoadFromFile("Sales_January.xlsx")

# Copy only the first two worksheets
newbook.Worksheets.AddCopy(tempbook.Worksheets[0], WorksheetCopyType.CopyAll)
newbook.Worksheets.AddCopy(tempbook.Worksheets[1], WorksheetCopyType.CopyAll)

newbook.SaveToFile("MergedSelected.xlsx", ExcelVersion.Version2013)
newbook.Dispose()
tempbook.Dispose()

This index-based approach suits scenarios where the file structure is fixed. If there are many source files with a uniform structure, you can also combine it with conditional logic to copy only the worksheets that meet certain criteria — for example, only sheets containing a specific keyword — enabling selective merging.

Practical Tips

Automatically Collecting Files with glob

Hard-coding the file list becomes cumbersome when there are many files. Instead, you can use the glob module from Python's standard library to match files by pattern:

import glob

files = glob.glob("./reports/*.xlsx") + glob.glob("./reports/*.xls")

As long as you drop files into the specified directory, the script automatically collects all of them for merging — and you don't need to touch the code when new files are added.

Controlling the Output Version

The ExcelVersion enumeration controls the output format when saving: Version2013 produces .xlsx files, while Version2010 is compatible with Excel 2010 and later. If the merged result is going to colleagues who use older versions of Excel, choosing a lower version is the safer bet.

Releasing Resources Promptly

Workbook objects consume system resources. In batch-processing scenarios, calling Dispose() after the work is done prevents memory from growing continuously during long-running processes.

Conclusion

This article covered how to merge multiple Excel files with Python: create a target workbook and clear its default worksheet, load each source file in a loop, copy the worksheets into the target workbook with AddCopy, and finally save the result. This workflow fits common scenarios such as report consolidation and data archiving, bringing scattered data together into a single file.

Building on this foundation, you can also sort, filter, or format the worksheets before or after merging to create a more complete Excel automation pipeline.

How to Add Text Headers and Footers to PDF Using Python

Allen Yang — Fri, 31 Jul 2026 07:05:01 +0000

PDF is the standard format for document distribution and archiving, and headers and footers are an indispensable part of formal documents—elements such as company names, document titles, section information, and page numbers all rely on them. For developers, manually adding headers and footers to a PDF that is dozens or even hundreds of pages long is clearly impractical. When documents need to be generated in batches on a regular basis, a programmatic approach is almost the only viable option.

This article explains how to add headers and footers to PDF documents using Python, covering plain-text headers and footers, image headers, different headers for different pages, and automatic page numbers generated through page templates.

Why Add Headers and Footers Programmatically

Handling PDF headers and footers in code offers several practical advantages over manual editing:

Batch Processing — Iterate through all pages with a loop and apply uniform headers and footers to the entire document in a single run
Dynamic Content — Elements like page numbers and section numbers can be generated automatically based on the document state, with no manual maintenance required
Consistent Styling — Fonts, colors, and alignment are controlled uniformly by code, avoiding the inconsistencies of manual work

Environment Setup

This article uses the Spire.PDF library to process PDF documents. Install it as follows:

pip install Spire.PDF

The library provides complete PDF creation and editing capabilities. Headers and footers are implemented by drawing text, images, and lines on the page canvas. Note that the PDF coordinate system has its origin at the bottom-left corner of the page, and the unit is points (1 point = 1/72 inch).

Adding Text Headers and Footers

To add uniform text headers and footers to an entire document, the most common approach is to iterate through all pages and draw the content on each page's canvas. The following code adds right-aligned header text at the top of every page, and a separator line with page numbers at the bottom:

from spire.pdf.common import *
from spire.pdf import *

doc = PdfDocument()
doc.LoadFromFile("Input.pdf")
margin = doc.PageSettings.Margins

# Define the pen, font, and alignment
pen = PdfPen(PdfBrushes.get_Black(), 0.75)
font = PdfTrueTypeFont("Arial", 12.0, PdfFontStyle.Italic, True)
brush = PdfBrushes.get_Black()
format = PdfStringFormat(PdfTextAlignment.Right)
format.MeasureTrailingSpaces = True
space = font.Height * 0.75

for i in range(doc.Pages.Count):
    page = doc.Pages.get_Item(i)
    x = margin.Left
    width = page.Canvas.ClientSize.Width - margin.Left - margin.Right

    # Header: draw a separator line + text
    y = margin.Top - space
    page.Canvas.DrawLine(pen, x, y, x + width, y)
    page.Canvas.DrawString("Internal Use", font, brush, x + width, y - font.Height, format)

    # Footer: draw a separator line + page number
    y = page.Canvas.ClientSize.Height - margin.Bottom + space
    page.Canvas.DrawLine(pen, x, y, x + width, y)
    label = "{0} / {1}".format(i + 1, doc.Pages.Count)
    page.Canvas.DrawString(label, font, brush, x + width, y + 1, format)

doc.SaveToFile("HeaderAndFooter.pdf")
doc.Close()

Output preview:

A few key points to note:

PdfTrueTypeFont specifies the font name, size, and style; PdfFontStyle.Italic means italic, and the last Boolean parameter controls whether the font is embedded
PdfStringFormat controls text alignment; setting MeasureTrailingSpaces = True makes right-aligned text account for trailing spaces, ensuring precise positioning
The header sits above the top margin and the footer below the bottom margin; font.Height * 0.75 reserves a reasonable gap between the text and the separator line

Inserting Images in Headers

Many documents place a company logo in the header. Images are also drawn on the canvas—load the image with PdfImage.FromFile(), then call DrawImage() to specify where it should be drawn:

headerImage = PdfImage.FromFile("Logo.png")
page.Canvas.DrawImage(headerImage, PointF(0.0, 0.0))

The second parameter of DrawImage() is the coordinate of the image's top-left corner. If you need to control the image size, you can pass additional width and height parameters (in points)—for example, to shrink the logo by half:

page.Canvas.DrawImage(headerImage, 50.0, 20.0,
    headerImage.Width / 2.0, headerImage.Height / 2.0)

Setting Different Headers for Different Pages

Documents with many sections often require a different header for each chapter. Since headers are implemented by drawing on specific pages, you can simply draw different content per page index:

rect = RectangleF(PointF(0.0, 20.0), SizeF(doc.PageSettings.Size.Width, 50.0))

# Page 1: red, bold, center-aligned
font1 = PdfTrueTypeFont("Arial", 15.0, PdfFontStyle.Bold, True)
format1 = PdfStringFormat()
format1.Alignment = PdfTextAlignment.Center
doc.Pages[0].Canvas.DrawString("Chapter 1 Overview", font1, PdfBrushes.get_Red(), rect, format1)

# Page 2: black, regular, left-aligned
font2 = PdfTrueTypeFont("Arial", 15.0, PdfFontStyle.Regular, True)
format2 = PdfStringFormat()
format2.Alignment = PdfTextAlignment.Left
doc.Pages[1].Canvas.DrawString("Chapter 2 Implementation", font2, PdfBrushes.get_Black(), rect, format2)

Here, doc.Pages[index] is used to access a specific page directly, and each page can then be given its own font, color, and alignment. If a document has many sections, you can first calculate the page ranges for each chapter and then combine that with a loop for batch drawing.

Managing Headers and Footers with Page Templates

When headers and footers need to apply to all pages of a document and take effect automatically, using a page template (PdfPageTemplateElement) is a more elegant solution. Templates are decoupled from page content and are applied automatically to any pages added later:

from spire.pdf.common import *
from spire.pdf import *

# Create a document and set the page size and margins
doc = PdfDocument()
doc.PageSettings.Size = PdfPageSize.A4()
doc.PageSettings.Margins = PdfMargins(50.0, 50.0, 50.0, 50.0)
pageSize = doc.PageSettings.Size

# Create a header template: draw the logo and a separator line
headerSpace = PdfPageTemplateElement(pageSize.Width, 50.0)
headerSpace.Foreground = False
image = PdfImage.FromFile("Logo.png")
headerSpace.Graphics.DrawImage(image, 50.0, 20.0, image.Width / 2.0, image.Height / 2.0)
pen = PdfPen(PdfBrushes.get_LightGray(), 1.0)
headerSpace.Graphics.DrawLine(pen, 50.0, 45.0, pageSize.Width - 50.0, 45.0)

# Create a footer template: use automatic fields to draw "Page x of y"
footerSpace = PdfPageTemplateElement(pageSize.Width, 50.0)
footerSpace.Foreground = False
footerSpace.Graphics.DrawLine(pen, 50.0, 0.0, pageSize.Width - 50.0, 0.0)
number = PdfPageNumberField()
count = PdfPageCountField()
compositeField = PdfCompositeField(
    PdfTrueTypeFont("Arial", 10.0, PdfFontStyle.Regular, True),
    PdfBrushes.get_Black(), "Page {0} of {1}", [number, count])
compositeField.StringFormat = PdfStringFormat(PdfTextAlignment.Left, PdfVerticalAlignment.Top)
compositeField.Bounds = RectangleF(PointF(50.0, 5.0), SizeF(200.0, 20.0))
widget = PdfGraphicsWidget(compositeField.Ptr)
widget.Draw(footerSpace.Graphics)

# Apply the templates to the top and bottom of the document
doc.Template.Top = headerSpace
doc.Template.Bottom = footerSpace

# Add a page and save
doc.Pages.Add()
doc.SaveToFile("TemplateHeaderFooter.pdf", FileFormat.PDF)
doc.Close()

The key here is the two automatic fields, PdfPageNumberField and PdfPageCountField: they don't store concrete values but are replaced automatically with the current page number and total page count at render time, so there's no need to iterate through pages manually. PdfCompositeField combines multiple fields into a single formatted text string. Setting the template's Foreground property to False places the template content behind the page content, so it never obscures the body text.

Practical Tips

Preserve existing page content: Drawing headers and footers directly onto existing pages can overwrite the body text. You can first save the original page as a template with page.CreateTemplate(), draw the headers and footers on the new page, and then render the original content to the bottom layer via PdfGraphicsWidget, adding headers and footers without damaging the content.
Semi-transparent effects: Calling page.Canvas.SetTransparency(0.5) lowers the opacity of subsequent drawing, letting headers and footers appear in a watermark-like style that is visually softer.
Remember font embedding: The last Boolean parameter of the PdfTrueTypeFont constructor controls whether the font is embedded in the document. Setting it to True ensures fonts render consistently when the document is opened on other devices.

Conclusion

This article covered several ways to add headers and footers to PDF documents using Python: drawing text and images on the canvas for custom headers and footers, setting different content per page by page index, and using page templates with automatic fields to manage page numbers uniformly. In practice, you can choose the approach that fits your document structure—simple uniform headers and footers can be done with a drawing loop, while page templates are the more convenient choice when you need automatic page numbers or batch generation.

Once you've mastered these techniques, you can combine them with find-and-replace, watermarks, layers, and other operations to build a complete document automation pipeline.

How to Draw Lines, Rectangles, and Shapes in PDF Using Python

Allen Yang — Wed, 29 Jul 2026 09:47:19 +0000

In everyday document processing, PDF has become the go-to format for distribution and archiving thanks to its cross-platform consistency. However, when generating PDFs, text content alone is often not enough—many scenarios require adding visual elements to the document, such as drawing dividers, highlighting rectangular areas, or adding decorative shapes. Whether you're dividing sections in a report or sketching prototype elements in a design draft, programmatic drawing is a fundamental and practical skill.

This article introduces how to draw common graphics in PDF documents using Python, including lines, rectangles, ellipses, and more complex custom paths.

Why Draw Graphics Programmatically

Drawing graphics in PDF through code offers several advantages over manual operations:

Precise Control — The coordinates, dimensions, colors, and transparency of graphics can be defined precisely through parameters, eliminating the deviations caused by manual dragging
Batch Generation — With loops and conditional logic, you can generate large volumes of documents containing graphical elements at once
Dynamic Content — Automatically adjust the position and style of graphics based on data sources, making it ideal for reports and templates

Environment Setup

This article uses the Spire.PDF library to create PDF documents and draw graphics. Install it as follows:

pip install Spire.PDF

This library provides comprehensive PDF manipulation capabilities, including page management, graphics drawing, and text rendering.

Drawing Basic Shapes

Spire.PDF provides a series of drawing methods through the PdfCanvas object. All drawing operations are performed on the page's Canvas. The canvas uses a coordinate system with the origin at the bottom-left corner of the page, and the unit is points (1 point = 1/72 inch).

Drawing Lines

Drawing a line is the most basic graphics operation. Use the DrawLine() method by specifying the start and end coordinates.

from spire.pdf.common import *
from spire.pdf import *

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

# Save the canvas state
state = page.Canvas.Save()

# Create a pen (black, line width 1 point)
pen = PdfPen(PdfRGBColor(Color.get_Black()), 1.0)

# Draw a horizontal line from (50, 100) to (400, 100)
page.Canvas.DrawLine(pen, 50.0, 100.0, 400.0, 100.0)

# Draw a diagonal line from (50, 100) to (225, 300)
pen2 = PdfPen(PdfRGBColor(Color.get_Red()), 1.0)
page.Canvas.DrawLine(pen2, 50.0, 100.0, 225.0, 300.0)

# Restore the canvas state
page.Canvas.Restore(state)

# Save the document
doc.SaveToFile("DrawLines.pdf")
doc.Close()

PdfPen is the core tool for drawing lines—it determines the color and width of the line. The first two parameters of DrawLine() are the start coordinates, and the last two are the end coordinates. It's a good practice to call Save() and Restore() around each drawing operation to avoid affecting previous drawing settings with subsequent operations.

Drawing Dashed Lines

In real-world development, dashed lines are often used to separate sections or mark boundaries. This can be achieved by setting the pen's DashStyle and DashPattern properties.

# Create a red pen with a line width of 3 points
pen = PdfPen(PdfRGBColor(Color.get_Red()), 3.0)

# Set the dash style
pen.DashStyle = PdfDashStyle.Dash
pen.DashPattern = [1, 4, 1]  # Dash pattern: 1pt solid, 4pt gap, 1pt solid

# Draw the dashed line
page.Canvas.DrawLine(pen, 50.0, 200.0, 400.0, 200.0)

The PdfDashStyle enum provides predefined dash styles (Dash, Dot, DashDot, etc.), while DashPattern allows you to define a more precise custom dash pattern—the numbers in the array alternately represent the lengths of solid segments and gaps.

Drawing Rectangles

Rectangles are among the most commonly used shapes for document annotation. You can draw either a rectangular border or a filled rectangle.

# Draw a rectangular border
pen = PdfPen(PdfRGBColor(Color.get_Black()), 0.5)
# Parameters: pen, x, y, width, height
page.Canvas.DrawRectangle(pen, 100.0, 150.0, 200.0, 120.0)

# Draw a filled rectangle
pen2 = PdfPen(PdfRGBColor(Color.get_Black()), 1.0)
brush = PdfSolidBrush(PdfRGBColor(Color.get_OrangeRed()))
rect = RectangleF(PointF(100.0, 300.0), SizeF(200.0, 120.0))
page.Canvas.DrawRectangle(pen2, brush, rect)

DrawRectangle() has two common overloads: one draws only the border and accepts a pen along with position parameters; the other draws a fill as well and takes an additional PdfBrush object. PdfSolidBrush is the most commonly used fill brush, filling the interior of a shape with a single color.

Drawing Ellipses

Ellipses and circles are common in diagram annotations and can be drawn using the DrawEllipse() method.

# Draw an elliptical border (defined by a bounding rectangle)
pen = PdfPen(PdfRGBColor(Color.get_CadetBlue()), 1.0)
# The parameters define the bounding rectangle; the ellipse is drawn inside it
page.Canvas.DrawEllipse(pen, 220.0, 320.0, 100.0, 90.0)

# Draw a filled ellipse
brush = PdfSolidBrush(PdfRGBColor(Color.get_CadetBlue()))
page.Canvas.DrawEllipse(brush, 380.0, 325.0, 80.0, 80.0)

# The third and fourth parameters control the horizontal and vertical radii
# When both are equal, the ellipse becomes a perfect circle
page.Canvas.DrawEllipse(brush, 100.0, 450.0, 50.0, 50.0)  # This draws a perfect circle

An ellipse is essentially defined by its bounding rectangle: the closer the rectangle is to a square, the closer the ellipse is to a perfect circle. This approach is conceptually similar to the way ellipses are drawn on an HTML Canvas.

Drawing Custom Paths

For complex shapes like stars or polygons, you can combine multiple line segments using the PdfPath object and then draw them all at once with the DrawPath() method.

import math

# Calculate the five vertices of a pentagon
points = [None] * 5
for i in range(5):
    x = float(math.cos(i * 2 * math.pi / 5))
    y = float(math.sin(i * 2 * math.pi / 5))
    points[i] = PointF(x, y)

# Create a path and add line segments
path = PdfPath()
path.AddLine(points[2], points[0])
path.AddLine(points[0], points[3])
path.AddLine(points[3], points[1])
path.AddLine(points[1], points[4])
path.AddLine(points[4], points[2])

# Draw the path outline
pen = PdfPen(PdfRGBColor(Color.get_DeepSkyBlue()), 0.02)
page.Canvas.ScaleTransform(50.0, 50.0)
page.Canvas.TranslateTransform(5.0, 5.0)
page.Canvas.DrawPath(pen, path)

# Draw the filled path
brush = PdfSolidBrush(PdfRGBColor(Color.get_DeepSkyBlue()))
page.Canvas.DrawPath(pen, brush, path)

PdfPath supports building shapes segment by segment using methods like AddLine(), AddArc(), and AddCurve(). ScaleTransform() and TranslateTransform() are used to scale and translate the coordinate system, making it easy to draw the same shape at different positions.

Controlling Shape Transparency

Transparency control creates richer visual effects when shapes overlap. Use the SetTransparency() method to set the transparency level for subsequent drawing operations.

# Set transparency (range 0.0~1.0, where 0.0 is fully transparent and 1.0 is fully opaque)
page.Canvas.SetTransparency(0.5, 0.5)

# Shapes drawn after this will be rendered at 50% opacity
pen = PdfPen(PdfRGBColor(Color.get_Black()), 1.0)
brush = PdfSolidBrush(PdfRGBColor(Color.get_Red()))
page.Canvas.DrawRectangle(pen, brush, RectangleF(PointF(200.0, 300.0), SizeF(200.0, 100.0)))

# Set a different transparency level
page.Canvas.SetTransparency(0.2, 0.2)
page.Canvas.DrawRectangle(pen, brush, RectangleF(PointF(300.0, 250.0), SizeF(200.0, 100.0)))

Transparency is especially useful when working with multi-layered shapes, such as distinguishing different levels of annotations in a product design draft.

Complete Example: Drawing Multiple Shapes Together

The following code combines all the drawing operations introduced above into a single document, producing a comprehensive example that includes lines, rectangles, ellipses, and custom paths.

from spire.pdf.common import *
from spire.pdf import *
import math

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

# Save the canvas state
state = page.Canvas.Save()

# 1. Draw a line
pen = PdfPen(PdfRGBColor(Color.get_Black()), 1.0)
page.Canvas.DrawLine(pen, 50.0, 50.0, 200.0, 50.0)

# 2. Draw a dashed line
pen_dash = PdfPen(PdfRGBColor(Color.get_Red()), 2.0)
pen_dash.DashStyle = PdfDashStyle.Dash
page.Canvas.DrawLine(pen_dash, 50.0, 80.0, 200.0, 80.0)

# 3. Draw a rectangular border
pen_rect = PdfPen(PdfRGBColor(Color.get_Blue()), 1.0)
page.Canvas.DrawRectangle(pen_rect, 50.0, 120.0, 150.0, 100.0)

# 4. Draw a filled rectangle
pen_fill = PdfPen(PdfRGBColor(Color.get_Black()), 0.5)
brush_fill = PdfSolidBrush(PdfRGBColor(Color.get_OrangeRed()))
page.Canvas.DrawRectangle(pen_fill, brush_fill, 
    RectangleF(PointF(50.0, 250.0), SizeF(150.0, 100.0)))

# 5. Draw an ellipse
brush_ellipse = PdfSolidBrush(PdfRGBColor(Color.get_CadetBlue()))
page.Canvas.DrawEllipse(brush_ellipse, 300.0, 120.0, 100.0, 80.0)

# 6. Draw a perfect circle
page.Canvas.DrawEllipse(brush_ellipse, 300.0, 250.0, 60.0, 60.0)

# Restore the canvas state
page.Canvas.Restore(state)

# Save
doc.SaveToFile("ShapesDemo.pdf")
doc.Close()

Output preview:

Conclusion

This article introduced the basic methods for drawing graphics in PDF documents using Python, covering common elements such as lines, dashed lines, rectangles, ellipses, and custom paths. In real-world development, these fundamental drawing capabilities can be combined and applied to many scenarios—for instance, drawing table borders in reports, adding annotation frames in design drafts, or creating decorative lines in certificate templates.

Once you've mastered these basic graphics techniques, you can explore more advanced drawing capabilities such as gradient fills, shape transformations, and layer management to meet more complex document processing needs.

Configuring Excel Page Layout and Print Settings Using Python

Allen Yang — Fri, 24 Jul 2026 10:15:54 +0000

In everyday work, Excel files are frequently printed — reports, inventories, invoices, and more. However, without proper page layout settings, printouts often suffer from truncated content, uneven margins, missing header rows, and other issues that undermine the document's professionalism and readability.

By programmatically configuring Excel page layout parameters with Python, you can apply print-ready settings at the moment the file is generated, eliminating tedious manual adjustments. This article walks through how to set margins, paper size, page orientation, print area, print title rows/columns, and fit-to-page scaling using Spire.XLS for Python.

Prerequisites

Install the required Python package:

pip install Spire.XLS

Setting Page Margins

Page margins define the distance between the printed content and the edges of the paper. Proper margins make printouts look cleaner and more readable.

You can set the top, bottom, left, and right margins independently through the TopMargin, BottomMargin, LeftMargin, and RightMargin properties of the PageSetup object. Values are specified in inches.

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

workbook = Workbook()
workbook.LoadFromFile("input.xlsx")

sheet = workbook.Worksheets[0]
pageSetup = sheet.PageSetup

# Set page margins (in inches)
pageSetup.TopMargin = 3
pageSetup.BottomMargin = 2
pageSetup.LeftMargin = 1
pageSetup.RightMargin = 1

workbook.SaveToFile("SetMargins.xlsx", ExcelVersion.Version2010)
workbook.Dispose()

The code above sets the top margin to 3 inches, the bottom margin to 2 inches, and both the left and right margins to 1 inch. Adjust these values as needed to suit your print requirements.

Setting Page Orientation

When a worksheet contains many columns, landscape orientation is usually a better choice than portrait, as it prevents content from exceeding the paper width.

You can switch the page orientation via the PageSetup.Orientation property:

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

workbook = Workbook()
workbook.LoadFromFile("input.xlsx")

sheet = workbook.Worksheets[0]

# Set page orientation to landscape
sheet.PageSetup.Orientation = PageOrientationType.Landscape

workbook.SaveToFile("SetOrientation.xlsx", ExcelVersion.Version2010)
workbook.Dispose()

The PageOrientationType enumeration provides two options: Portrait (vertical) and Landscape (horizontal). By default, Excel uses portrait orientation.

Setting Paper Size

Different printing scenarios may call for different paper sizes. For instance, everyday office documents typically use Letter or A4, while large reports may require A3.

You can specify the paper size through the PageSetup.PaperSize property:

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

workbook = Workbook()

sheet = workbook.Worksheets[0]

# Set paper size to A4
sheet.PageSetup.PaperSize = PaperSizeType.PaperA4

workbook.SaveToFile("SetPaperSize.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

The PaperSizeType enumeration supports a wide range of standard paper sizes, including PaperA3, PaperA4, PaperA5, PaperLetter, PaperLegal, and more. Choose the one that matches your printer's supported paper types.

Setting the Print Area

When a worksheet contains a large amount of data but only a portion of it needs to be printed, you can define a print area to specify exactly which cells should appear on the printout.

Use the PageSetup.PrintArea property to specify the print range as a cell address string:

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

workbook = Workbook()
workbook.LoadFromFile("input.xlsx")

sheet = workbook.Worksheets[0]
pageSetup = sheet.PageSetup

# Set the print area to A1:E5
pageSetup.PrintArea = "A1:E5"

workbook.SaveToFile("SetPrintArea.xlsx", ExcelVersion.Version2010)
workbook.Dispose()

Once a print area is defined, Excel will only print the content within that range, ignoring everything outside it. This is especially useful when working with large datasets.

Setting Print Title Rows and Title Columns

When data spans multiple printed pages, header rows typically appear only on the first page, leaving subsequent pages without column headings and making the content harder to follow. By setting Print Title Rows, you can have specific rows automatically repeated at the top of every printed page.

Similarly, when a worksheet has many columns and prints across multiple pages horizontally, you can set Print Title Columns to repeat specific columns on every page.

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

workbook = Workbook()
workbook.LoadFromFile("input.xlsx")

sheet = workbook.Worksheets[0]
pageSetup = sheet.PageSetup

# Set rows 1 and 2 as print title rows (repeated on every page)
pageSetup.PrintTitleRows = "$1:$2"

# Set columns A and B as print title columns (repeated on every page)
pageSetup.PrintTitleColumns = "$A:$B"

workbook.SaveToFile("SetPrintTitles.xlsx", ExcelVersion.Version2010)
workbook.Dispose()

Note that title row and column references use the $ notation — for example, $1:$2 refers to rows 1 through 2, and $A:$B refers to columns A through B. This is consistent with Excel's absolute reference syntax.

Scaling to Fit the Page

When content exceeds a single page, you can use fit-to-page settings to automatically scale it across a specified number of pages. This approach is more convenient than manually adjusting the zoom percentage.

Use the FitToPagesTall and FitToPagesWide properties to control how many pages the content should span vertically and horizontally:

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

workbook = Workbook()
workbook.LoadFromFile("input.xlsx")

sheet = workbook.Worksheets[0]
pageSetup = sheet.PageSetup

# Fit all content to 1 page tall and 1 page wide
pageSetup.FitToPagesTall = 1
pageSetup.FitToPagesWide = 1

workbook.SaveToFile("FitToPage.xlsx", ExcelVersion.Version2010)
workbook.Dispose()

Setting both properties to 1 shrinks all content onto a single page. If the worksheet has many rows but few columns, you can set FitToPagesTall to a larger value or to 0 (which removes the vertical page limit), while keeping FitToPagesWide at 1 to ensure the content width stays within one page.

Complete Example: Comprehensive Page Layout Configuration

The following example combines all of the settings above, configuring margins, orientation, paper size, print area, and print title rows for a single worksheet:

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

workbook = Workbook()
workbook.LoadFromFile("input.xlsx")

sheet = workbook.Worksheets[0]
pageSetup = sheet.PageSetup

# Page margins
pageSetup.TopMargin = 2.5
pageSetup.BottomMargin = 2
pageSetup.LeftMargin = 1
pageSetup.RightMargin = 1

# Page orientation and paper size
pageSetup.Orientation = PageOrientationType.Landscape
pageSetup.PaperSize = PaperSizeType.PaperA4

# Print area
pageSetup.PrintArea = "A1:H50"

# Print title rows (repeat row 1 on every page)
pageSetup.PrintTitleRows = "$1:$1"

# Scale to fit page width
pageSetup.FitToPagesTall = 0
pageSetup.FitToPagesWide = 1

workbook.SaveToFile("FullPageSetup.xlsx", ExcelVersion.Version2010)
workbook.Dispose()

This code is well-suited for a typical landscape A4 report scenario: it applies sensible margins, restricts the print range, ensures the header row repeats on every page, and scales the content to fit the page width automatically.

Summary

This article covered several common techniques for configuring Excel page layout with Python, including page margins, orientation, paper size, print area, print title rows/columns, and fit-to-page scaling. These settings are invaluable in everyday office workflows and automated report generation, allowing developers to finalize print parameters programmatically and reduce manual intervention.

Beyond the features discussed here, Spire.XLS also supports additional page setup properties such as print quality, first page number, and header/footer margins — all of which can be explored further based on your specific requirements.