DEV Community: Allen Yang

Insert and Manage Fields in Word Documents with Python

Allen Yang — Tue, 15 Sep 2026 02:53:26 +0000

A field is a special element in Word whose displayed content is composed of a field code and a field result, and it can update dynamically based on the environment or the document state. Common examples are the "Page X" text in footers, table of contents page numbers, cross-references to a chapter, and conditional content such as "show one phrase if a quantity is above 100". Inserting fields manually requires knowing the field code syntax, and when dozens of fields are scattered across one document, updating them one by one is tedious.

Python can automate all of this: insert different types of fields in bulk, update all field results, read the text inside fields, remove fields that are no longer needed, and even convert fields into plain text. This article demonstrates these operations 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 Simple Field into a Paragraph

Paragraph.AppendField() appends a field of a specified type to the end of a paragraph. The example below inserts a PageRef field, whose code points to a bookmark name and a display format:

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

# Get the last section and add a new paragraph
section = document.LastSection
par = section.AddParagraph()

# Insert a PageRef field and set its code
field = par.AppendField("pageRef", FieldType.FieldPageRef)
field.Code = "PAGEREF  bookmark1 \\# \"0\" \\* Arabic  \\* MERGEFORMAT"

# Update fields to get correct results
document.IsUpdateFields = True

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

The first argument of AppendField() is the display text of the field, and the second is a FieldType enum value that declares the category. FieldType.FieldNone creates an empty field, while values such as FieldType.FieldPageRef and FieldType.FieldMergeField correspond to concrete field types. After insertion, assigning the Code property is equivalent to typing the field code manually.

Creating a Conditional IF Field

The IF field performs conditional logic and is one of the most useful fields for dynamic document generation. It is more complex than a plain field: you add an IfField object to the paragraph, build up the condition, the true text, and the false text, and then close the field with an end mark:

def create_if_field(document, paragraph):
    if_field = IfField(document)
    if_field.Type = FieldType.FieldIf
    if_field.Code = "IF "
    paragraph.Items.Add(if_field)

    # Condition: the merge field Count is greater than 100
    paragraph.AppendField("Count", FieldType.FieldMergeField)
    paragraph.AppendText(" > ")
    paragraph.AppendText("\"100\" ")
    # True and false values
    paragraph.AppendText("\"Thanks\" ")
    paragraph.AppendText("\"The minimum order is 100 units\"")

    # Add the field end mark
    end = document.CreateParagraphItem(ParagraphItemType.FieldMark)
    end.Type = FieldMarkType.FieldEnd
    paragraph.Items.Add(end)
    if_field.End = end

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

# Fill the Count field with merge data
document.MailMerge.Execute(["Count"], ["2"])

# Update all fields
document.IsUpdateFields = True

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

IfField inherits from Field. It is added to the paragraph through Items.Add(), after which you assemble the content pieces. The whole field runs from its start mark to a FieldMarkType.FieldEnd end mark, and the End property links the end mark back to the field object. Combined with MailMerge.Execute() to supply the merge data, the IF field renders different text depending on the actual value.

Result Preview

Below is a preview of the Word document generated using the above code:

Updating All Fields in a Document

A field displays its "last calculated result". If the document was generated dynamically or the underlying data changed, the fields must be recalculated before saving:

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

# Update all fields before saving
document.IsUpdateFields = True

document.SaveToFile("UpdateFields.docx", FileFormat.Docx)

Set IsUpdateFields before calling SaveToFile(), and the document recalculates every field result when it is saved. This is often the final step when generating Word documents programmatically.

Reading Text from Fields

The Document.Fields property returns a collection of all fields in the document, and each field exposes its currently calculated result through the FieldText property:

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

fields = document.Fields
for i in range(fields.Count):
    field = fields.get_Item(i)
    print(field.FieldText)

document.Close()

Iterating the collection lets you quickly check whether a field took effect and whether its result is as expected, without knowing the document structure. fields[0] accesses the first field by index.

Converting Fields to Plain Text

Sometimes a document is finalized and no longer needs dynamic updates, such as an order or a contract being exported to a customer. Converting fields to plain text prevents the results from shifting when the recipient opens the file in a different environment:

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

fields = document.Fields
count = fields.Count

for i in range(0, count):
    field = fields[0]
    s = field.FieldText
    index = field.OwnerParagraph.ChildObjects.IndexOf(field)
    text_range = TextRange(document)
    text_range.Text = s
    text_range.CharacterFormat.FontSize = 24

    # Replace the field with text, then remove the field
    field.OwnerParagraph.ChildObjects.Insert(index, text_range)
    field.OwnerParagraph.ChildObjects.Remove(field)

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

The idea is to read the current field text, insert a TextRange at the field's position inside its paragraph, and then remove the field object. Because fields.Count changes as fields are removed, processing fields[0] in a loop cleans up the remaining fields one by one.

Removing Unwanted Fields

Removing a field is simpler than converting it: locate the paragraph that owns the field and delete it by index:

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

# Get the first field and its owning paragraph
field = document.Fields[0]
par = field.OwnerParagraph

# Locate the field and remove it by index
index = par.ChildObjects.IndexOf(field)
par.ChildObjects.RemoveAt(index)

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

OwnerParagraph returns the paragraph that contains the field. ChildObjects is the collection of objects inside that paragraph; after IndexOf() finds the field's subscript, RemoveAt() deletes it. To remove fields in bulk, put this logic in a loop.

Practical Tips

In Word, press Alt+F9 to toggle the display of field codes, and use it to verify that a critical field code was written correctly.
IsUpdateFields must be set before SaveToFile(), otherwise fields are not recalculated in the saved output.
For IF fields, assemble the condition strictly as "expression + comparison operator + value", and wrap text values in English double quotes.
Converting fields to text loses their dynamic behavior, so do it only when the document is finalized or about to be distributed; keep fields while the document is still being worked on.
Call document.Close() when finished to release resources.

Conclusion

This article covered the common ways to work with fields in Word documents using Python: inserting simple fields with AppendField(), building conditional fields with IfField, updating every field with IsUpdateFields, reading field text through Document.Fields, converting fields to plain text, and locating and removing fields via OwnerParagraph. With these techniques, page numbers, conditions, and merge data in dynamic documents can all be handled by a script.

Set Excel Headers and Footers Using Python

Allen Yang — Fri, 11 Sep 2026 10:23:30 +0000

Headers and footers are important supporting information when printing spreadsheets. They do not affect cell data, but they can show a document title, company name, logo, or date at the top or bottom of every page, making printed reports more consistent and professional. When a batch of workbooks needs the same header and footer, setting them by hand one by one is not practical.

Python can set Excel headers and footers in batch and with precision, including text content, font styles, odd/even page differences, and inserted images. This article demonstrates these operations using Spire.XLS for Python.

Setting Up the Environment

Install the Spire.XLS library:

pip install Spire.XLS

Then import the required modules in your script:

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

Header and footer settings are all centered on a worksheet's PageSetup property. It divides each header and footer into left, center, and right sections, accessed through LeftHeader / CenterHeader / RightHeader and LeftFooter / CenterFooter / RightFooter.

Setting a Basic Header and Footer

The simplest usage is to assign text directly to a section:

workbook = Workbook()
workbook.LoadFromFile("report.xlsx")
sheet = workbook.Worksheets[0]

# Set the left header
sheet.PageSetup.LeftHeader = "Sample Report by Spire.XLS"
# Set the center footer
sheet.PageSetup.CenterFooter = "Footer Text"

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

LeftHeader maps to the left section of the header, and CenterFooter to the center section of the footer. The six sections are independent, and you can use any subset of them as needed.

Controlling Font and Style with Format Codes

Header and footer text supports a set of format codes that take effect when written into the string. The most common are font name and size:

# &"font name"&size specifies the font and size
sheet.PageSetup.LeftHeader = "&\"Arial Unicode MS\"&18 Header Footer Sample"
sheet.PageSetup.RightFooter = "&\"Arial Unicode MS\"&18 Header Footer Sample"

The code pattern is &"font name"&size immediately followed by the text. Besides font and size, several other codes are commonly used:

&B: bold, for example &"Arial"&12&B Header;
&K + color code: sets the font color, for example &KFFC000;
&G: the image placeholder, marking where an image is inserted.

Combining these codes produces a styled header or footer, for example:

sheet.PageSetup.OddHeaderString = "&\"Arial\"&12&B&KFFC000 Odd_Header"

This line renders the header in Arial, size 12, bold, in the specified color.

Using Different Headers and Footers for Odd and Even Pages

Some documents want different headers and footers on odd and even pages (for example, a title on odd pages and a chapter name on even ones). Set DifferentOddEven to 1 to enable the feature, then set the odd and even strings separately:

sheet.PageSetup.DifferentOddEven = 1

# Odd page header and footer
sheet.PageSetup.OddHeaderString = "&\"Arial\"&12&B&KFFC000 Odd_Header"
sheet.PageSetup.OddFooterString = "&\"Arial\"&12&B&KFFC000 Odd_Footer"

# Even page header and footer
sheet.PageSetup.EvenHeaderString = "&\"Arial\"&12&B&KFF0000 Even_Header"
sheet.PageSetup.EvenFooterString = "&\"Arial\"&12&B&KFF0000 Even_Footer"

Note that once DifferentOddEven is enabled, you should use properties such as OddHeaderString / EvenHeaderString rather than the plain LeftHeader, otherwise the settings will not be distinguished by parity.

Using a Different Header and Footer on the First Page

Covers or first pages usually should not show the same header and footer as the body. Set DifferentFirst to 1, then set the first page's content separately:

sheet.PageSetup.DifferentFirst = 1

# First page header and footer
sheet.PageSetup.FirstHeaderString = "Different First page"
sheet.PageSetup.FirstFooterString = "Different First footer"

# Header and footer for the remaining pages
sheet.PageSetup.LeftHeader = "Demo of Spire.XLS"
sheet.PageSetup.CenterFooter = "Footer by Spire.XLS"

FirstHeaderString / FirstFooterString apply only to the first page, while LeftHeader, CenterFooter, and the like apply to the remaining pages. The two sets do not interfere with each other.

Inserting Images into Headers and Footers

Placing a company logo in the header or footer is also common. Provide the image through a property such as LeftHeaderImage, then set the corresponding section's text to the &G placeholder:

image = Stream("logo.png")

# Image header: provide the image, then use the &G placeholder
sheet.PageSetup.LeftHeaderImage = image
sheet.PageSetup.LeftHeader = "&G"

# Image footer
sheet.PageSetup.CenterFooterImage = image
sheet.PageSetup.CenterFooter = "&G"

&G is the fixed image placeholder; the image itself is supplied by properties such as LeftHeaderImage. The two work together to complete the setup.

Setting an image header on the first page has dedicated methods. For the first page's left section:

sheet.PageSetup.DifferentFirst = 1

imageStream = Stream("logo.png")
sheet.PageSetup.SetFirstLeftHeaderImage(imageStream)
sheet.PageSetup.SetFirstLeftFooterImage(imageStream)

sheet.PageSetup.LeftHeader = "Demo of Spire.XLS"
sheet.PageSetup.LeftFooter = "Footer by Spire.XLS"

SetFirstLeftHeaderImage() and SetFirstLeftFooterImage() are dedicated to the first page's image header and footer.

Practical Tips

Headers and footers are only visible in print preview or Page Layout view. Switch to Page Layout view with sheet.ViewMode = ViewMode.Layout to check the result.
The six sections (header left/center/right and footer left/center/right) are independent, so a report can populate only the sections it needs.
In the format code &"font name"&size, the font name must be quoted, with the size after the quotes; the order cannot be reversed.
For batch processing, loop over workbook.Worksheets and apply the same header and footer settings to every sheet to keep the workbook consistent.
Call Dispose() when finished to release resources.

Conclusion

This article covered several ways to set Excel headers and footers with Python: writing text into the six PageSetup section properties; controlling font and style with format codes such as &"font"&size, &B, and &K; distinguishing odd/even pages and the first page with DifferentOddEven and DifferentFirst; and inserting images through LeftHeaderImage together with the &G placeholder. With these techniques, consistent layout for printed reports can be handed off to a script.

Inserting and Managing Shapes in Excel Using Python

Allen Yang — Thu, 10 Sep 2026 10:03:51 +0000

In Excel, shapes are often used for process indicators, callouts, dashboard decoration, or turning scattered data into a clear diagram. Compared with plain text and cell borders, shapes express hierarchy and relationships more freely. But when the same shapes need to be added across many worksheets or files, dragging them by hand is slow and hard to keep consistent.

Python can insert shapes into worksheets in batch and with precision, and control properties such as fill, border, shadow, and layer order. Using Spire.XLS for Python, this article covers shape insertion and the management operations you are most likely to need.

Setting Up the Environment

Install the Spire.XLS library:

pip install Spire.XLS

Then import the required modules in your script:

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

Inserting Shapes

A worksheet exposes several shape collections for different kinds of shapes. The most general is PrstGeomShapes, which creates dozens of preset graphics through the PrstGeomShapeType enum. The arguments of AddPrstGeomShape() are the starting row, starting column, width, and height:

workbook = Workbook()
sheet = workbook.Worksheets[0]

# Insert a triangle with a solid fill
triangle = sheet.PrstGeomShapes.AddPrstGeomShape(2, 2, 100, 100, PrstGeomShapeType.Triangle)
triangle.Fill.ForeColor = Color.get_Yellow()
triangle.Fill.FillType = ShapeFillType.SolidColor

# Insert a heart with a gradient fill
heart = sheet.PrstGeomShapes.AddPrstGeomShape(2, 5, 100, 100, PrstGeomShapeType.Heart)
heart.Fill.ForeColor = Color.get_Red()
heart.Fill.FillType = ShapeFillType.Gradient

# Insert an arrow and a cloud
arrow = sheet.PrstGeomShapes.AddPrstGeomShape(10, 2, 100, 100, PrstGeomShapeType.CurvedRightArrow)
cloud = sheet.PrstGeomShapes.AddPrstGeomShape(10, 5, 100, 100, PrstGeomShapeType.Cloud)

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

PrstGeomShapeType includes values such as Triangle, Heart, CurvedRightArrow, Cloud, Ellipse, and RoundRect, covering common needs in flowcharts, callouts, and decoration.

For rectangles and ovals — the two most common shapes — dedicated methods offer simpler arguments:

# Insert a rectangle; RectangleShapeType can be Rect or RoundRect
rect = sheet.RectangleShapes.AddRectangle(11, 2, 60, 100, RectangleShapeType.RoundRect)
rect.Fill.FillType = ShapeFillType.SolidColor
rect.Fill.ForeColor = Color.get_DarkCyan()

# Insert an oval
oval = sheet.OvalShapes.AddOval(11, 5, 100, 100)
oval.Fill.FillType = ShapeFillType.SolidColor
oval.Fill.ForeColor = Color.get_DarkCyan()

Setting Fill, Border, and Shadow

A shape's fill is controlled by Fill.FillType, where ShapeFillType provides values such as SolidColor, Gradient, and Picture. A picture fill requires the image to be supplied through CustomPicture() first, then the type set to Picture:

# Fill a shape with a picture
cloud = sheet.PrstGeomShapes.AddPrstGeomShape(2, 5, 100, 100, PrstGeomShapeType.Cloud)
cloud.Fill.CustomPicture(Stream("logo.png"), "logo.png")
cloud.Fill.FillType = ShapeFillType.Picture

# A file path can also be used directly
oval = sheet.OvalShapes.AddOval(11, 5, 100, 100)
oval.Fill.CustomPicture("logo.png")

Borders are configured through the Line property, which controls weight and dash style:

rect.Line.Weight = 1
oval.Line.DashStyle = ShapeDashLineStyleType.Solid

Shadows add depth, and the Shadow property exposes angle, distance, size, color, blur, and transparency:

ellipse = sheet.PrstGeomShapes.AddPrstGeomShape(5, 5, 150, 100, PrstGeomShapeType.Ellipse)
ellipse.Shadow.Angle = 90
ellipse.Shadow.Distance = 10
ellipse.Shadow.Size = 150
ellipse.Shadow.Color = Color.get_Gray()
ellipse.Shadow.Blur = 30
ellipse.Shadow.Transparency = 1
ellipse.Shadow.HasCustomStyle = True

Note the last step: the custom shadow settings only take effect once HasCustomStyle is set to True.

Grouping Shapes

When several shapes should move or scale as a single unit, group them. Get the group collection with GetGroupShapeCollection(), then pass the list of shapes to group:

shape1 = sheet.PrstGeomShapes.AddPrstGeomShape(1, 3, 50, 50, PrstGeomShapeType.RoundRect)
shape2 = sheet.PrstGeomShapes.AddPrstGeomShape(5, 3, 50, 50, PrstGeomShapeType.Triangle)

groupShapeCollection = sheet.GetGroupShapeCollection()
groupShapeCollection.Group([shape1, shape2])

Once grouped, the shapes share a single bounding box and stay aligned when repositioned.

Adjusting Layer Order

When shapes overlap, their display order is determined by the layer. The ChangeLayer() method accepts the ShapeLayerChangeType enum to move a shape forward or backward:

# Move forward one level
shape.ChangeLayer(ShapeLayerChangeType.BringForward)
# Bring to the very front
shape.ChangeLayer(ShapeLayerChangeType.BringToFront)
# Send backward one level
shape.ChangeLayer(ShapeLayerChangeType.SendBackward)
# Send to the very back
shape.ChangeLayer(ShapeLayerChangeType.SendToBack)

Picture objects support ChangeLayer() as well, with the same usage.

Deleting and Hiding Shapes

Delete a single shape with Remove(). For bulk deletion, iterate backward — otherwise the indices shift as items are removed and elements get skipped:

workbook.LoadFromFile("template.xlsx")
sheet = workbook.Worksheets[0]

# Remove the first shape
sheet.PrstGeomShapes[0].Remove()

# Remove all shapes: iterate backward
for i in range(sheet.PrstGeomShapes.Count - 1, -1, -1):
    sheet.PrstGeomShapes[i].Remove()

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

If a shape should only be hidden temporarily rather than deleted, toggle its visibility instead, so it can be restored later:

sheet.PrstGeomShapes[1].Visible = False

Exporting Shapes and Reading Their Contents

A shape can be exported as an image for reuse elsewhere:

shape = sheet.PrstGeomShapes[0]
img = shape.SaveToImage()
img.Save("shape.png")

Conversely, the Text property reads the text inside a shape, and a picture fill can be extracted as the original image:

# Read the text inside a shape
print(sheet.PrstGeomShapes[2].Text)

# Extract the picture fill of a shape
image = sheet.PrstGeomShapes[1].Fill.Picture
image.Save("extracted.png", ImageFormat.get_Png())

Practical Tips

The first two arguments of AddPrstGeomShape() are the row and column position, followed by width and height; the shape anchors near the corresponding cells, so it shifts when the row or column layout changes.
When setting a custom shadow, it is easy to forget HasCustomStyle = True, which leaves the parameters without effect.
Always delete shapes in reverse order for bulk operations; forward deletion skips elements because the collection indices change in real time.
Call Dispose() when finished to release resources.

Conclusion

This article covered the full workflow of working with shapes in Excel using Python: inserting different shapes with AddPrstGeomShape(), AddRectangle(), and AddOval(); controlling appearance through Fill, Line, and Shadow; grouping shapes with Group() and reordering them with ChangeLayer(); and deleting via Remove(), hiding via Visible, and exporting via SaveToImage(). With these operations, repetitive layout work such as dashboard decoration and diagram annotation can be handed off to a script.

Adding and Managing Hyperlinks and Actions in PDF Using Python

Allen Yang — Thu, 10 Sep 2026 09:56:20 +0000

PDF hyperlinks and actions are essential mechanisms for enhancing document interactivity. Hyperlinks allow readers to navigate from a PDF to websites, files, or other pages within the document, while actions can trigger operations such as opening files, executing JavaScript, or playing sounds. When generating reports, electronic manuals, or interactive forms, manually adding links one by one is both time-consuming and error-prone. Using Python to batch-add and manage these links and actions programmatically significantly improves efficiency and ensures consistency. This article will introduce how to create various types of hyperlinks, set navigation actions, extract and update existing links, and configure document open actions in PDF documents using Python.

Why Manage Hyperlinks Programmatically

Batch creation: Automatically add table-of-content links and cross-references when generating multi-page reports
Rich types: Support web links, in-document navigation, file launching, and JavaScript actions
Precise control: Position link regions accurately using coordinates and dimensions, avoiding manual drag-and-drop imprecision
Automation integration: Embed link creation into document generation pipelines for one-pass generation with automatic linking

Environment Setup

This article uses Spire.PDF for Python, which provides a complete API for creating and managing PDF hyperlinks and actions.

pip install Spire.PDF

Creating Web Hyperlinks

Web hyperlinks are the most common link type, allowing readers to click and navigate to external websites. Spire.PDF offers two approaches: PdfTextWebLink is convenient for quickly creating styled text links, while PdfUriAnnotation provides lower-level URI annotation control.

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

outputFile = "WebLink.pdf"

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

# Method 1: Use PdfTextWebLink to create a text web link
font = PdfTrueTypeFont("Arial", 14.0, PdfFontStyle.Underline, True)
link = PdfTextWebLink()
link.Text = "Visit E-iceblue"
link.Url = "http://www.e-iceblue.com"
link.Font = font
link.Brush = PdfBrushes.get_CadetBlue()
link.DrawTextWebLink(page.Canvas, PointF(10.0, 50.0))

# Method 2: Use PdfUriAnnotation to create a URI annotation link
text = "Google"
font2 = PdfTrueTypeFont("Arial", 14.0, PdfFontStyle.Underline, True)
size = font2.MeasureString(text)
bounds = RectangleF(10.0, 100.0, size.Width, size.Height)

uriAnnotation = PdfUriAnnotation(bounds)
uriAnnotation.Uri = "http://www.google.com"
uriAnnotation.Border = PdfAnnotationBorder(0.0)

newPage = PdfNewPage(page.Ptr)
newPage.Annotations.Add(uriAnnotation)
page.Canvas.DrawString(text, font2, PdfBrushes.get_CadetBlue(), 10.0, 100.0)

# Email links are also supported
emailLink = PdfTextWebLink()
emailLink.Text = "Send an email"
emailLink.Url = "mailto:support@e-iceblue.com"
emailLink.Font = font
emailLink.Brush = PdfBrushes.get_CadetBlue()
emailLink.DrawTextWebLink(page.Canvas, PointF(10.0, 150.0))

doc.SaveToFile(outputFile)
doc.Close()

PdfTextWebLink encapsulates both text rendering and link addition in one step, making it suitable for simple scenarios. PdfUriAnnotation requires manual calculation of the link region's RectangleF bounds, but allows further configuration of border, color, and other annotation properties.

Creating In-Document Links

In-document links allow readers to jump from one page to another within the same document, commonly used for tables of contents and cross-references. Creating an internal link requires a PdfDestination to specify the target page and position, then a PdfDocumentLinkAnnotation to create the link annotation.

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

outputFile = "DocumentLink.pdf"

doc = PdfDocument()
page1 = doc.Pages.Add()
page2 = doc.Pages.Add()

# Draw target content on the second page
page2.Canvas.DrawString("This is the target page!",
    PdfTrueTypeFont("Arial", 16.0, PdfFontStyle.Bold, True),
    PdfBrushes.get_Black(), 10.0, 50.0)

# Create a PdfDestination pointing to the second page
dest = PdfDestination(page2)
dest.Location = PointF(0.0, 50.0)
dest.Zoom = 0.5  # 50% zoom

# Create the in-document link
font = PdfTrueTypeFont("Arial", 12.0, PdfFontStyle.Regular, True)
label = "Click here to jump to page 2"
size = font.MeasureString(label)
bounds = RectangleF(10.0, 50.0, size.Width, size.Height)

annotation = PdfDocumentLinkAnnotation(bounds, dest)
annotation.Color = PdfRGBColor(Color.get_Blue())

page1.Canvas.DrawString(label, font, PdfBrushes.get_OrangeRed(), 10.0, 50.0)
newPage = PdfNewPage(page1.Ptr)
newPage.Annotations.Add(annotation)

doc.SaveToFile(outputFile)
doc.Close()

The Location property of PdfDestination specifies the coordinate position on the target page, while Zoom controls the zoom level after navigation.

Creating File Links and Launch Actions

File links allow opening external files from within a PDF. PdfFileLinkAnnotation directly links to a file path, while PdfLaunchAction triggers file launching as an action and can also control whether the file opens in a new window.

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

outputFile = "FileLink.pdf"

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

# Create a launch action using PdfLaunchAction
launchAction = PdfLaunchAction("Sample.pdf")
# Set to open in a new window
launchAction.IsNewWindow = True

text = "Click to open Sample.pdf"
font = PdfTrueTypeFont("Arial", 13.0, PdfFontStyle.Regular, True)
rect = RectangleF(50.0, 50.0, 230.0, 20.0)
page.Canvas.DrawString(text, font, PdfBrushes.get_ForestGreen(), rect)

annotation = PdfActionAnnotation(rect, launchAction)
newPage = PdfNewPage(page.Ptr)
newPage.Annotations.Add(annotation)

doc.SaveToFile(outputFile)
doc.Close()

PdfActionAnnotation associates an action with a rectangular region on the page. Clicking that region triggers the action. When IsNewWindow is set to True, the target file opens in a new window.

Using GoToAction for Page Navigation

PdfGoToAction is another way to implement page navigation. It works as an action rather than an annotation. Combined with PdfActionAnnotation, it can create button-style navigation regions, and it can also be set as an automatic behavior when the document opens.

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

outputFile = "GoToAction.pdf"

doc = PdfDocument()
page1 = doc.Pages.Add()
page2 = doc.Pages.Add()

page2.Canvas.DrawString("This is Page Two.",
    PdfFont(PdfFontFamily.Helvetica, 20.0),
    PdfSolidBrush(PdfRGBColor(Color.get_Black())), 10.0, 10.0)

# Create a go-to action targeting the second page
dest = PdfDestination(page2)
dest.Location = PointF(0.0, 5.0)
dest.Mode = PdfDestinationMode.Location
dest.Zoom = 1.0
gotoAction = PdfGoToAction(dest)

# Create a button-style navigation region
buttonFont = PdfTrueTypeFont("Arial", 10.0, PdfFontStyle.Bold, True)
buttonBounds = RectangleF(0.0, 100.0, 90.0, 20.0)
format = PdfStringFormat(PdfTextAlignment.Center, PdfVerticalAlignment.Middle)

page1.Canvas.DrawRectangle(PdfBrushes.get_DarkGray(), buttonBounds)
page1.Canvas.DrawString("Go to Page 2", buttonFont,
    PdfBrushes.get_CadetBlue(), buttonBounds, format)

annotation = PdfActionAnnotation(buttonBounds, gotoAction)
annotation.Border = PdfAnnotationBorder(0.75)
newPage = PdfNewPage(page1.Ptr)
newPage.Annotations.Add(annotation)

doc.SaveToFile(outputFile)
doc.Close()

Extracting and Updating Existing Hyperlinks

For existing PDF documents, you can iterate through page annotations to extract link information or update link URLs:

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

inputFile = "Input.pdf"
outputFile = "UpdatedLinks.pdf"

doc = PdfDocument()
doc.LoadFromFile(inputFile)

# Iterate through annotations on each page
for i in range(doc.Pages.Count):
    page = doc.Pages[i]
    widgetCollection = page.AnnotationsWidget
    if widgetCollection.Count > 0:
        for j in range(widgetCollection.Count):
            annotation = widgetCollection.get_Item(j)
            # Check if it is a web link annotation
            if isinstance(annotation, PdfTextWebLinkAnnotationWidget):
                link = annotation
                print("URL: " + link.Url)
                print("Text: " + link.Text)
                # Update the link URL
                link.Url = "http://www.e-iceblue.com"

doc.SaveToFile(outputFile)
doc.Close()

Use page.AnnotationsWidget to access the annotation collection, and isinstance to check the annotation type. PdfTextWebLinkAnnotationWidget provides Url and Text properties that can be directly read or modified.

Setting Document Open Actions

The AfterOpenAction property specifies an action to execute automatically when the document opens. Common use cases include navigating to a specific page, playing sound, and removing existing actions:

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

inputFile = "Input.pdf"
outputFile = "OpenAction.pdf"

doc = PdfDocument()
doc.LoadFromFile(inputFile)

# Set to jump to page 3 at 50% zoom when opened
dest = PdfDestination(2, PointF(0.0, 100.0), 0.5)
action = PdfGoToAction(dest)
doc.AfterOpenAction = action

doc.SaveToFile(outputFile)
doc.Close()

# To remove the open action, set AfterOpenAction to None
# doc.AfterOpenAction = None

In addition to PdfGoToAction, you can also set PdfJavaScriptAction or PdfSoundAction as AfterOpenAction to execute scripts or play audio when the document opens.

Practical Tip: Auto-Generating a Linked Table of Contents

By combining PdfGoToAction with text rendering, you can automatically generate a table of contents page with page-navigation links for multi-page PDFs:

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

inputFile = "Input.pdf"
outputFile = "TOC.pdf"

doc = PdfDocument()
doc.LoadFromFile(inputFile)
pageCount = doc.Pages.Count

# Insert a TOC page at the beginning
tocPage = doc.Pages.Insert(0)
titleFont = PdfTrueTypeFont("Arial", 20.0, PdfFontStyle.Bold, True)
tocFont = PdfTrueTypeFont("Arial", 14.0, PdfFontStyle.Regular, True)

# Draw the title
tocPage.Canvas.DrawString("Table of Contents", titleFont,
    PdfBrushes.get_CornflowerBlue(), 0.0, 0.0)

# Create a TOC entry and navigation link for each page
y = 40.0
newPage = PdfNewPage(tocPage.Ptr)
for i in range(1, pageCount + 1):
    text = "Page {0}".format(i)
    size = tocFont.MeasureString(text)
    tocPage.Canvas.DrawString(text, tocFont, PdfBrushes.get_CadetBlue(), 0.0, y)

    # Create a navigation link to the target page
    dest = PdfDestination(doc.Pages[i], PointF(0.0, 0.0))
    gotoAction = PdfGoToAction(dest)
    bounds = RectangleF(0.0, y, tocPage.Canvas.ClientSize.Width, size.Height)
    action = PdfActionAnnotation(bounds, gotoAction)
    action.Border = PdfAnnotationBorder(0.0)
    newPage.Annotations.Add(action)
    y += size.Height + 10

doc.SaveToFile(outputFile)
doc.Close()

This example inserts a blank page at the beginning as the table of contents, creates a text entry for each subsequent page, and overlays a transparent PdfActionAnnotation on each entry that navigates to the corresponding page when clicked.

Summary

This article covered the complete workflow for adding and managing hyperlinks and actions in PDF documents using Python, including web links, in-document links, file launch actions, page navigation actions, link extraction and updating, and document open action configuration.

Key takeaways:

Use PdfTextWebLink for quick web link creation, and PdfUriAnnotation for finer URI annotation control
PdfDocumentLinkAnnotation combined with PdfDestination enables in-document page navigation with configurable zoom levels
PdfLaunchAction launches external files, with IsNewWindow controlling whether they open in a new window
PdfGoToAction implements page navigation as an action, associable with page regions via PdfActionAnnotation
Iterate page.AnnotationsWidget to extract and update existing links, and use AfterOpenAction to configure automatic behavior on document open

With these skills, you can add rich interactive navigation to PDF documents, auto-generate table-of-contents links, and integrate link management into your document processing pipelines.

Managing PDF Document Properties and Metadata Using Python

Allen Yang — Thu, 03 Sep 2026 10:13:17 +0000

PDF document properties (also known as metadata) contain information such as author, title, subject, and keywords. These fields play a critical role in document management systems—they make documents searchable, classifiable, and traceable. Beyond standard properties, PDF also supports custom properties for storing business-specific extension information. In practice, manually editing properties across hundreds of PDF documents is inefficient and error-prone. By managing these properties programmatically with Python, you can batch-read, set, and validate metadata, automating the document management workflow. This article covers setting standard properties, reading property information, adding custom properties, and setting document expiry dates.

Why Manage Document Properties Programmatically

Compared to manual editing, the programmatic approach offers these advantages:

Batch processing: Update author, keywords, and other properties across hundreds of PDF files in one run
Data consistency: Define property values in code to eliminate spelling errors and format inconsistencies from manual input
Workflow integration: Embed property management into the document generation pipeline, writing metadata automatically at creation time
Custom extensions: Store business information (department, project number, classification level) via custom properties for document categorization

Environment Setup

This article uses Spire.PDF for Python, which provides APIs for managing PDF document properties.

pip install Spire.PDF

Once installed, you can import the relevant modules in your Python script and start working.

Setting Standard Document Properties

PDF standard properties include Author, Creator, Keywords, Producer, Subject, and Title. The following code loads a PDF file and sets these properties:

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

inputFile = "Input.pdf"
outputFile = "Properties.pdf"

# Load the PDF document
doc = PdfDocument()
doc.LoadFromFile(inputFile)

# Set standard document properties
doc.DocumentInformation.Author = "E-iceblue"
doc.DocumentInformation.Creator = "E-iceblue"
doc.DocumentInformation.Keywords = "pdf, demo, document information"
doc.DocumentInformation.Producer = "Spire.Pdf"
doc.DocumentInformation.Subject = "Demo of Spire.Pdf"
doc.DocumentInformation.Title = "Document Information"

# Set file information
doc.FileInfo.CrossReferenceType = PdfCrossReferenceType.CrossReferenceStream
doc.FileInfo.IncrementalUpdate = False

# Save the document
doc.SaveToFile(outputFile)
doc.Close()

Key steps in the code:

Loading the document: LoadFromFile() loads the PDF document from a file path.
DocumentInformation object: Access and set standard properties through doc.DocumentInformation. Each property is assigned directly.
FileInfo settings: CrossReferenceType controls the cross-reference table storage format (Stream or Table). Setting IncrementalUpdate to False rewrites the entire file on save rather than applying incremental updates.

Reading Document Properties

After setting properties, you typically need to read and verify them. The following code extracts all standard properties from a PDF document:

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

inputFile = "Properties.pdf"

doc = PdfDocument()
# Read the PDF file
doc.LoadFromFile(inputFile)

# Get the document information object
docInfo = doc.DocumentInformation

# Read properties one by one
print("Author: " + docInfo.Author)
print("Creation Date: " + docInfo.CreationDate.strftime("%Y/%m/%d %H:%M:%S"))
print("Keywords: " + docInfo.Keywords)
print("Modify Date: " + docInfo.ModificationDate.strftime("%Y/%m/%d %H:%M:%S"))
print("Subject: " + docInfo.Subject)
print("Title: " + docInfo.Title)

doc.Close()

In addition to the manually set properties, the PDF document automatically maintains two timestamps:

CreationDate: The document creation time, formatable via strftime()
ModificationDate: The last modification time, automatically updated by the PDF writer

Setting Custom Document Properties

Standard properties cover the fields defined by the PDF specification. When you need to store business-specific extension information, custom properties come into play. Custom properties exist as key-value pairs where both the key name and value are freely definable:

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

inputFile = "Input.pdf"
outputFile = "CustomDocumentProperties.pdf"

doc = PdfDocument()
# Load the PDF file
doc.LoadFromFile(inputFile)

# Add custom document properties
doc.DocumentInformation.SetCustomProperty("Company", "E-iceblue")
doc.DocumentInformation.SetCustomProperty("Component", "Spire.PDF for .NET")
doc.DocumentInformation.SetCustomProperty("Name", "Daisy")
doc.DocumentInformation.SetCustomProperty("Team", "SalesTeam")

# Save the file
doc.SaveToFile(outputFile, FileFormat.PDF)
doc.Close()

The SetCustomProperty(key, value) method accepts two string parameters: the property name and the property value. Custom properties do not appear in the standard "Document Properties" tab of PDF readers but can be read programmatically, making them suitable for storing business metadata required by document management systems.

Setting Document Expiry Date

In certain scenarios, documents need an expiration date that prompts the user when the document is no longer valid. This can be achieved using a JavaScript Action:

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

inputFile = "Input.pdf"
outputFile = "SetExpiryDate.pdf"

doc = PdfDocument()
doc.LoadFromFile(inputFile)

# Build JavaScript script: check if current time exceeds the deadline
javaScript = (
    "var rightNow = new Date();"
    "var endDate = new Date('October 20, 2025 23:59:59');"
    "if(rightNow.getTime() > endDate)"
    "app.alert('This document has expired, please contact us for a new one.', 1);"
    "this.closeDoc();"
)

# Set the JavaScript as the action to execute when the document opens
js = PdfJavaScriptAction(javaScript)
doc.AfterOpenAction = js

# Save the document
doc.SaveToFile(outputFile)
doc.Close()

The AfterOpenAction property specifies a JavaScript action to execute automatically when the document opens. The script above checks the current time on open and, if the deadline has passed, displays an alert and closes the document. This approach is useful for distributing time-sensitive documents.

Practical Tips

Batch Updating Document Properties

When processing large numbers of documents, you can encapsulate property setting in a function and iterate over a directory:

import os

def update_pdf_properties(file_path, author, title, subject, keywords):
    doc = PdfDocument()
    doc.LoadFromFile(file_path)
    doc.DocumentInformation.Author = author
    doc.DocumentInformation.Title = title
    doc.DocumentInformation.Subject = subject
    doc.DocumentInformation.Keywords = keywords
    doc.FileInfo.IncrementalUpdate = False
    doc.SaveToFile(file_path)
    doc.Close()

# Batch update by iterating through a directory
directory = "./pdf_files"
for filename in os.listdir(directory):
    if filename.endswith(".pdf"):
        update_pdf_properties(
            os.path.join(directory, filename),
            author="Company Team",
            title="Quarterly Report",
            subject="Finance",
            keywords="report, 2025, quarterly"
        )

Property Validation and Auditing

In document management systems, checking property completeness is a common requirement:

def validate_pdf_properties(file_path):
    doc = PdfDocument()
    doc.LoadFromFile(file_path)
    info = doc.DocumentInformation
    missing = []
    if not info.Author:
        missing.append("Author")
    if not info.Title:
        missing.append("Title")
    if not info.Keywords:
        missing.append("Keywords")
    doc.Close()
    return missing if missing else "All required properties are set."

By checking whether properties are empty, you can quickly filter out documents with incomplete metadata, ensuring all required information is filled in before archiving.

Conclusion

This article covered the complete workflow for managing PDF document properties and metadata using Python, including setting standard properties, reading property information, adding custom properties, and setting document expiry dates.

Key takeaways:

Use the doc.DocumentInformation object to set and read standard properties (Author, Title, Subject, Keywords, etc.)
Use SetCustomProperty(key, value) to add business-specific custom properties
CreationDate and ModificationDate are automatically maintained by the system and can be formatted via strftime()
Use PdfJavaScriptAction with AfterOpenAction to implement document expiry date control

With these skills, you can integrate property management into your document processing pipeline, enabling batch setting, validation, and auditing of PDF metadata to improve document management standardization and efficiency.

Creating and Customizing Charts in Word Documents Using Python

Allen Yang — Thu, 03 Sep 2026 09:32:43 +0000

Charts are essential tools for data visualization, transforming abstract numbers into intuitive graphical representations. Embedding charts in Word documents makes reports, proposals, and analysis documents more compelling. The traditional approach of manually inserting charts in Word and editing data one by one is inefficient and prone to inconsistency. By creating charts programmatically with Python, you can build an automated pipeline from data to documents, generating standardized reports with charts in batch. This article introduces how to create multiple chart types in Word documents using Python, including setting chart titles, data series, and axis formats.

Why Create Charts Programmatically

Compared to manual operation, the programmatic approach offers the following advantages:

Batch generation: Automatically generate multiple report documents with charts from data sources
Data synchronization: Chart data comes directly from program variables or database queries, ensuring real-time accuracy
Consistent styling: Uniformly define chart dimensions, title formats, and axis styles through code, eliminating human inconsistency
Pipeline integration: Embed chart creation into document automation workflows, achieving end-to-end automation from data collection to report generation

Environment Setup

This article uses Spire.Doc for Python, which provides APIs for inserting and customizing charts in Word documents.

pip install Spire.Doc

After installation, you can import the relevant modules in your Python script and start working.

Creating a Column Chart

Column charts are one of the most commonly used chart types, suitable for comparing values across categories. The following code demonstrates how to create a column chart with a data series:

from spire.doc import *

outputFile = "ColumnChart.docx"

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

# Add descriptive text
section.AddParagraph().AppendText("Column chart.")

# Add a paragraph to host the chart
newPara = section.AddParagraph()

# Append a column chart with specified width and height
shape = newPara.AppendChart(ChartType.Column, float(500), float(300))
chart = shape.Chart

# Clear default data series
chart.Series.Clear()

# Add a custom data series
chart.Series.Add("Test Series",
                 ["Word", "PDF", "Excel", "GoogleDocs", "Office"], [
                     float(1900000),
                     float(850000),
                     float(2100000),
                     float(600000),
                     float(1500000)
                 ])

# Set Y-axis number format
chart.AxisY.NumberFormat.FormatCode = "#,##0"

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

The generated Word document:

Key steps in the code:

Append chart: The AppendChart(ChartType.Column, width, height) method adds a chart shape to the paragraph and returns a chart shape object.
Data series: The Series.Add() method accepts three parameters — series name, category list (X-axis), and value list (Y-axis).
Axis format: AxisY.NumberFormat.FormatCode sets the display format for Y-axis labels. "#,##0" applies thousand separators.

Creating a Line Chart with Title

Line charts are ideal for showing trends over time or categories. The following code creates a line chart with multiple data series and a chart title:

from spire.doc import *

outputFile = "LineChart.docx"

document = Document()
section = document.AddSection()
section.AddParagraph().AppendText("Line chart.")

newPara = section.AddParagraph()

# Append a line chart
shape = newPara.AppendChart(ChartType.Line, 500.0, 300.0)
chart = shape.Chart

# Set chart title
title = chart.Title
title.Text = "My Chart"
title.Show = True
title.Overlay = True

# Add multiple data series
seriesColl = chart.Series
seriesColl.Clear()

categories = ["C1", "C2", "C3", "C4", "C5", "C6"]

seriesColl.Add("AW Series 1", categories, [1.0, 2.0, 2.5, 4.0, 5.0, 6.0])
seriesColl.Add("AW Series 2", categories, [2.0, 3.0, 3.5, 6.0, 6.5, 7.0])

document.SaveToFile(outputFile, FileFormat.Docx)
document.Dispose()

The generated Word document:

Title settings explained:

title.Text: Sets the title text content
title.Show: Controls whether the title is displayed
title.Overlay: When set to True, the title overlays the chart without taking up additional space

Creating a Pie Chart

Pie charts display the proportional relationship of parts to a whole. A pie chart requires only one data series:

from spire.doc import *

outputFile = "PieChart.docx"

document = Document()
section = document.AddSection()
section.AddParagraph().AppendText("Pie chart.")

newPara = section.AddParagraph()

# Append a pie chart
shape = newPara.AppendChart(ChartType.Pie, 500.0, 300.0)
chart = shape.Chart

# Add a data series
chart.Series.Add("Test Series", ["Word", "PDF", "Excel"],
                          [2.7, 3.2, 0.8])

document.SaveToFile(outputFile, FileFormat.Docx)
document.Dispose()

The data series addition works the same way as with column charts. ChartType.Pie specifies the chart type as a pie chart.

Creating Scatter and Bubble Charts

Scatter charts show the correlation between two sets of data, while bubble charts add a third dimension to represent data weight.

Scatter chart:

from spire.doc import *

outputFile = "ScatterChart.docx"

document = Document()
section = document.AddSection()
section.AddParagraph().AppendText("Scatter chart.")

newPara = section.AddParagraph()

# Append a scatter chart
shape = newPara.AppendChart(ChartType.Scatter, 450.0, 300.0)
chart = shape.Chart
chart.Series.Clear()

# Add a data series with X and Y value lists
chart.Series.Add("Scatter chart", [1.0, 2.0, 3.0, 4.0, 5.0],
                 [1.0, 20.0, 40.0, 80.0, 160.0])

document.SaveToFile(outputFile, FileFormat.Docx)
document.Dispose()

Bubble chart:

from spire.doc import *

outputFile = "BubbleChart.docx"

document = Document()
section = document.AddSection()
section.AddParagraph().AppendText("Bubble chart.")

newPara = section.AddParagraph()

# Append a bubble chart
shape = newPara.AppendChart(ChartType.Bubble, float(500), float(300))
chart = shape.Chart
chart.Series.Clear()

# Add a data series with X, Y, and bubble size lists
chart.Series.Add("Test Series",
                 [2.9, 3.5, 1.1, 4.0, 4.0],
                 [1.9, 8.5, 2.1, 6.0, 1.5],
                 [9.0, 4.5, 2.5, 8.0, 5.0])

document.SaveToFile(outputFile, FileFormat.Docx)
document.Dispose()

The key difference lies in the number of parameters passed to Series.Add(): scatter charts take X and Y lists, while bubble charts take an additional third list for bubble sizes.

Creating a 3D Surface Chart

3D surface charts are suitable for displaying the three-dimensional distribution of multivariate data. The following code creates a surface chart with three data series:

from spire.doc import *

outputFile = "Surface3DChart.docx"

document = Document()
section = document.AddSection()
section.AddParagraph().AppendText("Surface3D chart.")

newPara = section.AddParagraph()

# Append a 3D surface chart
shape = newPara.AppendChart(ChartType.Surface3D, 500.0, 300.0)
chart = shape.Chart
chart.Series.Clear()

# Set title
chart.Title.Text = "My chart"

# Add multiple data series
categories = ["Word", "PDF", "Excel", "GoogleDocs", "Office"]

chart.Series.Add("Series 1", categories,
                 [1900000.0, 850000.0, 2100000.0, 600000.0, 1500000.0])
chart.Series.Add("Series 2", categories,
                 [900000.0, 50000.0, 1100000.0, 400000.0, 250000.0])
chart.Series.Add("Series 3", categories,
                 [500000.0, 820000.0, 1500000.0, 400000.0, 100000.0])

document.SaveToFile(outputFile, FileFormat.Docx)
document.Dispose()

By adding multiple data series, the surface chart can simultaneously display the 3D distribution of multiple data groups, making it suitable for comparative analysis.

Practical Tips

Auto-Selecting Chart Types Based on Data

In practice, you can encapsulate chart creation in a function to quickly add multiple charts to a single document:

def create_chart(document, chart_type, title, categories, values):
    section = document.AddSection()
    section.AddParagraph().AppendText(title)
    para = section.AddParagraph()
    shape = para.AppendChart(chart_type, 500.0, 300.0)
    chart = shape.Chart
    chart.Series.Clear()
    chart.Title.Text = title
    chart.Title.Show = True
    chart.Series.Add("Data", categories, values)
    return chart

# Usage example
doc = Document()
create_chart(doc, ChartType.Column, "Quarterly Sales",
             ["Q1", "Q2", "Q3", "Q4"], [120.0, 150.0, 180.0, 200.0])
create_chart(doc, ChartType.Line, "Monthly Growth Trend",
             ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
             [10.0, 15.0, 22.0, 28.0, 35.0, 42.0])
doc.SaveToFile("Report.docx", FileFormat.Docx)
doc.Dispose()

After encapsulating chart creation as a function, you can quickly add various chart types to the same document, which is useful for generating comprehensive reports with multiple data views.

Setting Axis Number Formats

For large numerical data, setting axis number formats improves readability:

# Thousand separator format
chart.AxisY.NumberFormat.FormatCode = "#,##0"

# Percentage format
chart.AxisY.NumberFormat.FormatCode = "0%"

# Thousand separator with decimal places
chart.AxisY.NumberFormat.FormatCode = "#,##0.00"

Conclusion

This article covered the complete workflow for creating charts in Word documents using Python, including six chart types: column, line, pie, scatter, bubble, and 3D surface charts.

Key takeaways:

Use AppendChart(ChartType, width, height) to append a chart to a paragraph, specifying the chart type via the ChartType enum
Add data series with chart.Series.Add() — the number of parameters varies by chart type (scatter charts need X/Y lists, bubble charts need X/Y/size lists)
Set chart title text, visibility, and overlay using chart.Title
Customize axis number display format with chart.AxisY.NumberFormat.FormatCode

With these skills, you can integrate chart creation into report generation pipelines, automatically producing Word documents with visualized charts from business data, significantly improving the efficiency and consistency of data report generation.

Insert and Manage OLE Objects in Excel with Python

Allen Yang — Fri, 28 Aug 2026 09:58:59 +0000

OLE (Object Linking and Embedding) objects are a powerful data embedding mechanism in Excel that allows external documents—such as Word files, PDF documents, PowerPoint presentations, audio files, and more—to be embedded directly into worksheets. This makes Excel not just a spreadsheet tool but a container for multiple types of documents. In automated report generation, data archiving, and document management scenarios, inserting and extracting OLE objects programmatically can significantly improve efficiency. This article provides a detailed guide on how to insert, extract, and manage OLE objects in Excel worksheets using Python.

Why Manage OLE Objects Programmatically

Compared with manually inserting objects in Excel, a programmatic approach offers the following advantages:

Batch embedding: Embed multiple external documents into worksheets in a single pass without manual operation
Automated archiving: Bind associated documents with data storage, ensuring data and contextual documents are not separated
Document extraction: Batch extract embedded documents from worksheets for subsequent processing or conversion
Workflow integration: Integrate OLE object operations into data processing pipelines for end-to-end automation

Environment Setup

This article uses Spire.XLS for Python, which provides a comprehensive API for manipulating Excel workbooks and worksheets, including OLE object insertion and extraction.

pip install Spire.XLS

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

Inserting OLE Objects

The core of inserting an OLE object is providing the source file path and a preview image for display. The following code demonstrates how to embed an Excel file as an OLE object into a worksheet:

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


def GenerateImage(fileName):
        book = Workbook()
        book.LoadFromFile(fileName)
        book.Worksheets[0].PageSetup.LeftMargin = 0
        book.Worksheets[0].PageSetup.RightMargin = 0
        book.Worksheets[0].PageSetup.TopMargin = 0
        book.Worksheets[0].PageSetup.BottomMargin = 0
        return book.Worksheets[0].ToImage(1, 1, 19, 5)

inputFile = "./Data/InsertOLEObjects.xls"
outputFile = "InsertOLEObjects.xlsx"

# Create a workbook and get the first worksheet
workbook = Workbook()
ws = workbook.Worksheets[0]
ws.Range["A1"].Text = "Here is an OLE Object."

# Generate a preview image and insert the OLE object
image = GenerateImage(inputFile)
oleObject = ws.OleObjects.Add(inputFile, image, OleLinkType.Embed)
oleObject.Location = ws.Range["B4"]
oleObject.ObjectType = OleObjectType.ExcelWorksheet

# Save the file
workbook.SaveToFile(outputFile, ExcelVersion.Version2010)
workbook.Dispose()

Key steps in the code:

Generate a preview image: The GenerateImage() function loads the source file and converts its first page to an image, which serves as the visual placeholder for the OLE object in the worksheet.
Add the OLE object: The OleObjects.Add() method accepts three parameters — the source file path, the preview image, and the link type. OleLinkType.Embed means the object is embedded in the workbook (rather than externally linked).
Set position and type: The Location property specifies the anchor cell for the OLE object in the worksheet, and the ObjectType property sets the type of the embedded object (in this case, an Excel worksheet).

Inserting Audio Files as OLE Objects

In addition to document files, OLE objects also support embedding multimedia files such as audio. The following code demonstrates how to embed a WAV audio file into a worksheet:

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


inputFile = "./Data/WAVFileSample.wav"
inputimg = "./Data/SpireXls.png"
outputFile = "InsertWavFileOLEObject.xlsx"

# Create a workbook and get the first worksheet
workbook = Workbook()
sheet = workbook.Worksheets[0]

# Use a custom image as preview and add the audio OLE object
with Stream(inputimg) as fs:
    oleObject = sheet.OleObjects.Add(inputFile, fs, OleLinkType.Embed)

# Set position and object type
oleObject.Location = sheet.Range["B4"]
oleObject.ObjectType = OleObjectType.Package

workbook.SaveToFile(outputFile, ExcelVersion.Version2010)
workbook.Dispose()

The main differences from inserting document files are:

Preview image source: An external image file (SpireXls.png) is used as the preview image through a Stream object, rather than being auto-generated from the source file.
Object type: OleObjectType.Package indicates that the file is embedded as a generic package object, suitable for non-document file types such as audio and video.

Extracting OLE Objects

In document management and data archiving scenarios, extracting embedded OLE objects from Excel worksheets is a common requirement. The following code demonstrates how to extract different types of embedded documents from a worksheet:

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


def WriteAllBytes(fname: str, data):
    fp = open(fname, "wb")
    for d in data:
        fp.write(d)
    fp.close()

inputFile = "./Data/ExtractOle2.xlsx"

workbook = Workbook()
workbook.LoadFromFile(inputFile)
sheet = workbook.Worksheets[0]

# Check if the worksheet contains OLE objects
if sheet.HasOleObjects:
    for obj in sheet.OleObjects:
        type = obj.ObjectType
        # Extract Word document
        if type is OleObjectType.WordDocument:
            WriteAllBytes("ExtractedWord.docx", obj.OleData)
        # Extract PDF document
        elif type is OleObjectType.AdobeAcrobatDocument:
            WriteAllBytes("ExtractedPDF.pdf", obj.OleData)
        # Extract PowerPoint document
        elif type is OleObjectType.PowerPointSlide:
            WriteAllBytes("ExtractedPPT.pptx", obj.OleData)

workbook.Dispose()

Core logic of the extraction process:

Detect OLE objects: The HasOleObjects property first checks whether the worksheet contains any OLE objects, avoiding unnecessary iteration.
Type identification: The ObjectType property identifies the specific type of each OLE object, such as WordDocument, AdobeAcrobatDocument, or PowerPointSlide.
Data extraction: The OleData property returns the raw binary data of the OLE object, which is written to the corresponding file using the WriteAllBytes() function.

Getting Original Document Names of OLE Objects

Each OLE object retains the original document name information, which is useful for tracking the source of embedded documents:

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

inputFile = "Data/ExtractOleObjectName.xlsx"

# Create a workbook and load the file
workbook = Workbook()
workbook.LoadFromFile(inputFile)

# Get the first worksheet
sheet = workbook.Worksheets[0]

information = ""

# Iterate through all OLE objects and get original document names
for ole in sheet.OleObjects:
    ole_name = ole.OriginName
    information += ole_name + "\r\n"

print(information)

workbook.Dispose()

The OriginName property returns the original file name used when the OLE object was embedded. By iterating through all OLE objects and collecting name information, you can quickly generate an inventory of embedded documents.

Practical Tips

Batch Extracting and Categorizing OLE Objects

In practice, a worksheet may contain multiple types of OLE objects. The following code shows how to batch extract and save them by category:

type_mapping = {
    OleObjectType.WordDocument: ".docx",
    OleObjectType.AdobeAcrobatDocument: ".pdf",
    OleObjectType.PowerPointSlide: ".pptx",
    OleObjectType.ExcelWorksheet: ".xlsx"
}

if sheet.HasOleObjects:
    for index, obj in enumerate(sheet.OleObjects):
        ext = type_mapping.get(obj.ObjectType, ".bin")
        filename = f"ole_object_{index}{ext}"
        WriteAllBytes(filename, obj.OleData)
        print(f"Extracted: {filename} (type: {obj.ObjectType})")

By using a type mapping dictionary to convert ObjectType to file extensions, you can automatically assign correct suffixes to extracted files, making them easier to open and process later.

Iterating Across Multiple Worksheets

When multiple worksheets in a workbook contain OLE objects, you need to iterate through all worksheets for extraction:

for sheet_index in range(workbook.Worksheets.Count):
    sheet = workbook.Worksheets[sheet_index]
    if sheet.HasOleObjects:
        for obj in sheet.OleObjects:
            print(f"Worksheet {sheet_index + 1}: {obj.OriginName} - {obj.ObjectType}")

This code scans the entire workbook and reports the name and type of each OLE object in every worksheet, which is useful for document auditing and content inventory scenarios.

Conclusion

This article provided a detailed walkthrough of the complete workflow for managing OLE objects in Excel worksheets with Python, covering four core operations: inserting document objects, inserting multimedia files, extracting embedded documents, and retrieving object information.

Key takeaways:

Use the OleObjects.Add() method to insert OLE objects, providing the source file path, preview image, and link type
Set the object type via the ObjectType property — use specific type enums for documents and Package for multimedia files
Use HasOleObjects for detection and the OleData property to extract the raw binary data of embedded documents
Retrieve the original document name through the OriginName property to track embedding sources

With these skills, you can integrate OLE object management into document processing workflows, enabling automatic embedding, batch extraction, and categorized archiving of external documents, effectively improving the automation level of document management.

Add and Manage Comments in PowerPoint with Python

Allen Yang — Fri, 28 Aug 2026 09:46:35 +0000

In team collaboration and presentation review scenarios, the comment feature plays a critical role. Reviewers add comments to slides to propose changes, flag questions, or record feedback, while presentation authors need to read, respond to, and manage those comments. When dealing with large numbers of slides or batch review processes, managing comments manually is both inefficient and error-prone. This article provides a detailed guide on how to add, extract, modify, and delete comments in PowerPoint presentations programmatically with Python, enabling fully automated comment management.

Why Manage Comments Programmatically

Compared with manually operating comments in the PowerPoint application, a programmatic approach offers the following advantages:

Batch review: Extract comments from all slides in a single pass to generate review reports
Automated workflows: Integrate comment management into CI/CD pipelines or document processing workflows
Precise control: Position comments using coordinates to ensure accurate annotation placement
Collaboration integration: Export comment data to project management tools or feedback tracking systems

Environment Setup

Before starting, install the Python library that supports PowerPoint operations. This article uses Spire.Presentation for Python, which provides a comprehensive API for manipulating PPTX-format presentations.

pip install Spire.Presentation

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

Adding Comments

Adding comments is the foundational operation of comment management. In PowerPoint, each comment is associated with an author and a specific slide position. The following code demonstrates how to add a comment to a slide:

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

inputFile = "./Data/AddComment.pptx"
outputFile = "AddComment.pptx"

# Create a Presentation object and load the file
presentation = Presentation()
presentation.LoadFromFile(inputFile)

# Add a comment author
author = presentation.CommentAuthors.AddAuthor("E-iceblue", "comment:")

# Set the comment position coordinates
point = PointF.Empty()
point.X = 18
point.Y = 25

# Add a comment to the first slide
presentation.Slides[0].AddComment(
    author, "This is a comment", point, DateTime.get_Now())

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

Key steps in the code:

Create an author: The AddAuthor() method accepts two parameters — the author name and the author initials (typically used as an identifier prefix in comments). Each comment must be associated with a registered author.
Position the comment: The PointF object specifies the anchor position of the comment on the slide. The X and Y properties represent the horizontal and vertical coordinates, respectively.
Add the comment: The AddComment() method accepts four parameters — the author object, the comment text, the position coordinates, and the posting time. DateTime.get_Now() sets the current time as the comment timestamp.

Extracting Slide Comments

In review workflows, extracting comment information is a critical step for generating review reports. The following code shows how to extract all comments from a specific slide:

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

def AppendAllText(fname: str, text: List[str]):
    fp = open(fname, "w")
    for s in text:
        fp.write(s + "\n")
    fp.close()

inputFile = "./Data/Template_Ppt_5.pptx"
outputFile = "ExtractComments.txt"

# Create a Presentation object and load the file
presentation = Presentation()
presentation.LoadFromFile(inputFile)

cs = []

# Get all comments from the first slide
comments = presentation.Slides[0].Comments

# Iterate through comments and collect text
i = 0
while i < len(comments):
    cs.append(comments[i].Text + "\r\n")
    i += 1

# Save to a text file
AppendAllText(outputFile, cs)
presentation.Dispose()

Slides[0].Comments returns the collection of all comments on the first slide. By iterating through this collection and accessing the Text property of each comment, you can retrieve all comment text content.

Getting Detailed Comment Information

Beyond the comment text, complete comment information includes the author name and posting time. By iterating through the CommentAuthors collection, you can obtain richer comment metadata:

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

def AppendAllText(fname: str, text: List[str]):
    fp = open(fname, "w")
    for s in text:
        fp.write(s + "\n")
    fp.close()

inputFile = "./Data/Comments.pptx"
outputFile = "GetSlideComments.txt"

# Create a Presentation object and load the file
presentation = Presentation()
cs = []
presentation.LoadFromFile(inputFile)

# Iterate through all comment authors
for commentAuthor in presentation.CommentAuthors:
    # Iterate through each author's comments
    for comment in commentAuthor.CommentsList:
        # Get comment information
        commentText = comment.Text
        authorName = comment.AuthorName
        time = comment.DateTime
        cs.append("Comment text: " + commentText + "\n" + "Comment author: " +
                  authorName + "\n" + "Posted on: " + time.ToString())

AppendAllText(outputFile, cs)
presentation.Dispose()

This code retrieves complete comment information through a two-level iteration:

The outer loop iterates through the CommentAuthors collection to access each comment author
The inner loop iterates through the author's CommentsList to extract the text, author name, and timestamp of each comment

This approach is particularly useful for generating structured review reports with comments grouped by author.

Modifying and Deleting Comments

During the review process, it is often necessary to modify comment content or remove comments that are no longer needed. The following code demonstrates both modification and deletion operations:

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

inputFile = "./Data/DeleteComment.pptx"
outputFile = "DeleteComment.pptx"

# Create a Presentation object and load the file
presentation = Presentation()
presentation.LoadFromFile(inputFile)

# Modify the text of the second comment
presentation.Slides[0].Comments[1].Text = "Updated comment text"

# Delete the third comment
presentation.Slides[0].DeleteComment(presentation.Slides[0].Comments[2])

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

Core explanations for both operations:

Modifying a comment: Assign a new value directly to the Comments[index].Text property to update the comment text. This approach is suitable for correcting erroneous descriptions or adding supplementary information.
Deleting a comment: The DeleteComment() method accepts a comment object as a parameter and permanently removes it from the slide. You must first access the comment object through the Comments collection by index, then pass it to the method for deletion.

Practical Tips

Batch Extracting Comments from All Slides

In real-world review scenarios, you often need to extract comments from all slides in the presentation. This can be achieved by iterating through the slides collection:

all_comments = []
for i in range(presentation.Slides.Count):
    slide = presentation.Slides[i]
    for j in range(len(slide.Comments)):
        comment = slide.Comments[j]
        all_comments.append({
            "slide": i + 1,
            "text": comment.Text,
            "author": comment.AuthorName
        })

After collecting comment data into a list, you can further export it to CSV, JSON, or directly generate a review report.

Filtering Comments by Author

When multiple reviewers add comments simultaneously, filtering by author helps quickly locate feedback from a specific reviewer:

target_author = "E-iceblue"
for commentAuthor in presentation.CommentAuthors:
    if commentAuthor.Name == target_author:
        for comment in commentAuthor.CommentsList:
            print(f"Comment: {comment.Text}  Time: {comment.DateTime}")

Conclusion

This article provided a detailed walkthrough of the complete workflow for managing comments in PowerPoint presentations with Python, covering the four core operations: adding, extracting, modifying, and deleting comments.

Key takeaways:

Use CommentAuthors.AddAuthor() to register comment authors and Slides[index].AddComment() to add comments
Access and extract comments on a slide through the Slides[index].Comments collection
Iterate through the CommentAuthors collection to obtain complete comment information including author names and timestamps
Modify comment text via the Comments[index].Text property and remove comments using the DeleteComment() method

With these skills, you can integrate comment management into automated review workflows, enabling batch extraction, filtering, and report generation for comments, significantly improving team collaboration efficiency.

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.