DEV Community: Allen Yang

How to Split PDF Documents with Python

Allen Yang — Wed, 30 Sep 2026 06:46:54 +0000

Large PDFs are everywhere in day-to-day work — consolidated quarterly reports, scanned contracts, batches of exported invoices. The recipient usually needs only a few pages: individual pages split out as separate files, or a specific page range handed to a different team. Doing this by hand in a PDF editor is slow and impossible to scale. With Python you can split a document page by page, extract selected pages, or even divide one oversized page into several standard pages — all of which slot naturally into automated workflows. This article demonstrates these three common splitting scenarios using Spire.PDF for Python.

Why Split PDFs with Python

Handling the job in a script has a few concrete advantages:

Batch processing: one script can process hundreds of files without manual clicks.
Flexible granularity: split a whole document page by page, extract only chosen pages, or subdivide a single long page.
Easy integration: splitting is just one step in a pipeline that may also download, archive, or email the results.

Setting Up the Environment

Install the Spire.PDF library:

pip install Spire.PDF

Then import the required modules in your script:

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

Splitting a PDF into Single-Page Documents

The most direct approach is turning every page into its own PDF. PdfDocument.Split() does this with a single filename pattern — no per-page handling required:

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

# Load the PDF document
doc = PdfDocument()
doc.LoadFromFile("Sample.pdf")

# Split by filename pattern; each page becomes an individual PDF
doc.Split("SplitDocument-{0}.pdf")

doc.Close()

Split() takes a filename template containing the {0} placeholder, which is replaced with the page index starting from 0. A 10-page document produces ten single-page files, from SplitDocument-0.pdf through SplitDocument-9.pdf. Call Close() afterwards to release the document's resources.

Extracting Specific Pages into a New PDF

More often you do not need every page — just a selection combined into a new document. The approach: create a new PdfDocument, add a same-sized page for each source page you want, then draw the source page's content into it:

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

# Load the source document
oldPdf = PdfDocument()
oldPdf.LoadFromFile("Sample.pdf")

# Create the target document
newPdf = PdfDocument()
page = None

# Extract pages at index 1 and 2 (0-based)
for i in range(1, 3):
    # Add a page with the same size as the source page
    page = newPdf.Pages.Add(oldPdf.Pages[i].Size, PdfMargins(0.0))
    # Draw the source page content onto the new page
    oldPdf.Pages[i].CreateTemplate().Draw(page, PointF(0.0, 0.0))

newPdf.SaveToFile("ExtractPages.pdf")
newPdf.Close()
oldPdf.Close()

The first argument to Pages.Add() receives the source page's Size, so the new page matches the original dimensions, and PdfMargins(0.0) zeroes out the margins to keep the content aligned. CreateTemplate() produces a drawing template of the source page, and Draw() renders it onto the new page with layout fully preserved. The loop range range(1, 3) extracts pages 2 and 3 — adjust the range to pull any combination of pages.

Splitting One Long Page into Multiple Pages

A special case: the source PDF contains a very tall page (a long screenshot, a continuous table) and you want it cut into standard-height pages. The trick is to build a document whose page height is half the source page's height, then draw the source content with automatic pagination enabled:

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

# Load the source document and get the first page
doc = PdfDocument()
doc.LoadFromFile("LongPage.pdf")
page = doc.Pages[0]

# New document: zero margins, same width, half the source height
newPdf = PdfDocument()
newPdf.PageSettings.Margins.All = 0.0
newPdf.PageSettings.Width = page.Size.Width
newPdf.PageSettings.Height = page.Size.Height / float(2)

# Add a new page and configure automatic pagination
newPage = newPdf.Pages.Add()
format = PdfTextLayout()
format.Break = PdfLayoutBreakType.FitPage
format.Layout = PdfLayoutType.Paginate

# Draw the source content; it flows onto extra pages automatically
page.CreateTemplate().Draw(newPage, PointF(0.0, 0.0), format)

newPdf.SaveToFile("SplitOnePage.pdf")
newPdf.Close()
doc.Close()

Two properties of PdfTextLayout do the work: Layout = PdfLayoutType.Paginate makes the drawing flow onto additional pages when it exceeds the page, and Break = PdfLayoutBreakType.FitPage cuts at the page boundary. Since the new page is half the height of the source, one long page spreads across two standard pages; decrease the height divisor to cut it into more pieces.

Practical Tips

Output location: the filename pattern in Split() can include a path prefix (for example "output/SplitDocument-{0}.pdf") to write the results into a specific directory.
0-based indexing: check doc.Pages.Count before extracting pages and choose the loop range accordingly to avoid out-of-range errors.
Granularity: for long-page splitting, a smaller divisor for Height yields more pages — tune it to the actual content height.
Resource cleanup: call Close() on both the source and target documents; this matters even more in batch processing.
Free edition: the free edition of Spire.PDF limits the number of pages processed, which is worth checking for large documents.

Conclusion

This article covered three common ways to split PDF documents in Python: using Split() to break an entire document into single-page files, using CreateTemplate().Draw() to extract selected pages into a new document, and leveraging PdfLayoutType.Paginate to divide one long page across multiple standard pages. Combined with file iteration and simple page math, these operations fit cleanly into workflows such as batch splitting and per-recipient document distribution.

How to Insert and Manage Images in PowerPoint with Python

Allen Yang — Wed, 30 Sep 2026 06:28:46 +0000

Images are almost indispensable in presentations: a company logo, a product screenshot, a flow diagram, an illustrative photo all carry information that text alone cannot. Placing one image on a slide looks simple, but precisely controlling its position, size, border, and transparency — or batch-replacing an old logo across many decks — is more than manual editing can handle.

This article uses Spire.Presentation for Python to show how to insert an image onto a slide, scale image dimensions, set the image frame's border and rotation, apply transparency, replace an existing image, and delete images from a slide in bulk.

Setting Up the Environment

Install the Spire.Presentation library:

pip install Spire.Presentation

Then import the required modules in your script:

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

Inserting an Image onto a Slide

AppendEmbedImageByPath() embeds an image into a rectangular region on a specified slide and returns an image shape object:

import math

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

imagePath = "logo.png"
# Compute a centered position
left = math.trunc(presentation.SlideSize.Size.Width / float(2)) - 280
rect = RectangleF.FromLTRB(left, 140, 120 + left, 260)

# Insert theE image on the first slide
image = presentation.Slides[0].Shapes.AppendEmbedImageByPath(
    ShapeType.Rectangle, imagePath, rect)
# Remove the default border
image.Line.FillType = FillFormatType.none

presentation.SaveToFile("InsertImage.pptx", FileFormat.Pptx2010)
presentation.Dispose()

RectangleF.FromLTRB(left, top, right, bottom) defines the image's position and size on the slide, in pixels. ShapeType.Rectangle specifies the container shape type. The inserted image has a border by default; setting Line.FillType to FillFormatType.none removes it.

Scaling Images on a Slide

Existing images can be found by iterating the Shapes collection and then resizing them via Width and Height:

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

scale = 0.5
for slide in presentation.Slides:
    for shape in slide.Shapes:
        if isinstance(shape, IEmbedImage):
            shape.Width = shape.Width * scale
            shape.Height = shape.Height * scale

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

isinstance(shape, IEmbedImage) filters out image shapes and skips text boxes, tables, and other shapes. scale = 0.5 shrinks every image to half its original size. Scaling by a single factor preserves the aspect ratio.

Setting the Image Frame Border and Rotation

The object returned when inserting an image is itself a shape, so you can set its border line style, width, and rotation angle:

import math

presentation = Presentation()

stream = Stream("logo.png")
imageData = presentation.Images.AppendStream(stream)
stream.Close()

# Insert at half the image's original dimensions
rect = RectangleF.FromLTRB(
    100, 100,
<parameter name="newString">    math.trunc(imageData.Width / float(2)) + 100,
    math.trunc(imageData.Height / float(2)) + 100)
pptImage = presentation.Slides[0].Shapes.AppendEmbedImageByImageData(
    ShapeType.Rectangle, imageData, rect)

# Border: solid, light blue, width 5
pptImage.Line.FillFormat.FillType = FillFormatType.Solid
pptImage.Line.FillFormat.SolidFillColor.Color = Color.get_LightBlue()
pptImage.Line.Width = 5
# Rotate -45 degrees
pptImage.Rotation = -45

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

AppendEmbedImageByImageData() inserts using already-loaded image data, which is useful when the same image is needed multiple times — load it once with Images.AppendStream() and reference it repeatedly. Line.FillFormat controls the border fill, and Rotation controls the angle (positive is clockwise, negative is counter-clockwise).

Applying Transparency to an Image

Transparency must be achieved through a shape fill: first load the image into the presentation's image collection, then draw a rectangle shape and fill it with that image, and finally set the transparency:

from spire.presentation import *

presentation = Presentation()
stream = Stream("logo.png")
imageData = presentation.Images.AppendStream(stream)
stream.Close()

# Read the dimensions from the image data
width, height = imageData.Width, imageData.Height
rect = RectangleF.FromLTRB(200, 100, width + 200, height + 100)
shape = presentation.Slides[0].Shapes.AppendShape(ShapeType.Rectangle, rect)
shape.Line.FillType = FillFormatType.none

# Fill the shape with the image
shape.Fill.FillType = FillFormatType.Picture
shape.Fill.PictureFill.Picture.EmbedImage = presentation.Images[0]
shape.Fill.PictureFill.FillType = PictureFillType.Stretch

# Set transparency to 50%
shape.Fill.PictureFill.Picture.Transparency = 50

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

Images.AppendStream() adds the image to the presentation's resource pool and returns the image data, from which Width and Height can be read directly — no Pillow needed. FillType = FillFormatType.Picture switches the shape fill to an image, EmbedImage points to the image object in the resource pool, and PictureFillType.Stretch stretches the image to fill the shape. Transparency ranges from 0 to 100; a larger value means more transparent. This approach is suitable when the image is used as a background or watermark.

Replacing an Existing Image

When updating a logo or swapping an image, first load the new image into the presentation's image collection, then assign it to the target image shape's EmbedImage:

ppt = Presentation()
ppt.LoadFromFile("presentation.pptx")
slide = ppt.Slides[0]

# Load the new image
stream = Stream("new_logo.png")
newImage = ppt.Images.AppendStream(stream)
stream.Close()

# Find the image titled "image1" and replace it
for shape in slide.Shapes:
    if isinstance(shape, SlidePicture):
        if shape.AlternativeTitle == "image1":
            shape.PictureFill.Picture.EmbedImage = newImage

ppt.SaveToFile("ReplaceImage.pptx", FileFormat.Pptx2013)
ppt.Dispose()

SlidePicture is the type of slide picture shapes. AlternativeTitle locates the image to replace, and assigning the new image data to PictureFill.Picture.EmbedImage completes the swap. AppendStream() adds the new image to the presentation's resource pool; the replacement only repoints the shape to the new resource.

Deleting Images from a Slide

To clean up unwanted images, iterate Shapes and remove them in reverse order:

ppt = Presentation()
ppt.LoadFromFile("presentation.pptx")
slide = ppt.Slides[0]

for i in range(slide.Shapes.Count - 1, -1, -1):
    if isinstance(slide.Shapes[i], SlidePicture):
        slide.Shapes.RemoveAt(i)

ppt.SaveToFile("RemoveImages.pptx", FileFormat.Pptx2013)
ppt.Dispose()

isinstance(slide.Shapes[i], SlidePicture) checks whether the shape is an image, and RemoveAt(i) deletes it by index. Iterating in reverse avoids index shifting after removal.

Practical Tips

The four arguments of RectangleF.FromLTRB are left, top, right, and bottom coordinates — not width and height — and are easy to mix up.
Inserted images have a border by default; set Line.FillType to none for a clean image with no frame.
When the same image is used multiple times, load it once with Images.AppendStream() and reference it repeatedly, which keeps the file smaller than calling AppendEmbedImageByPath() each time.
Transparency must be set through a shape fill; setting Transparency directly on an IEmbedImage has no effect.
Call presentation.Dispose() when finished to release resources.

Conclusion

This article covered the common operations for working with images in PowerPoint using Python: inserting an image onto a slide with AppendEmbedImageByPath(), scaling dimensions by iterating IEmbedImage, setting the image frame's border and rotation, achieving transparency through a shape fill, replacing an existing image via EmbedImage, and deleting images in bulk by iterating SlidePicture in reverse. Combined inside a presentation-generation script, image insertion and maintenance can be fully automated.

Insert and Manipulate Images in Excel Using Python

Allen Yang — Thu, 24 Sep 2026 09:59:37 +0000

Excel reports often need images: a company logo, a product render, an electronic signature, or a scanned document thumbnail. An image must land in the right cell, at the right size, without crowding the surrounding data. When a batch of reports all need the same logo, or a template must be cleared of old images before new ones are inserted, doing it by hand is slow and error-prone.

This article uses Spire.XLS for Python to show how to insert an image at a specific cell, adjust its offset within the cell, read its position and size, compress it to reduce file size, and delete images from a worksheet in bulk.

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 an Image at a Specific Cell

Worksheet.Pictures.Add() inserts an image at a cell location. The first two arguments are the row and column numbers, and the third is the image path:

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

# Insert an image at row 14, column 5 (i.e. E14)
sheet.Pictures.Add(14, 5, "logo.png")

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

The image is inserted at its original size, with its top-left corner aligned to the specified cell. If the image is larger than the cell, it overlaps neighboring cells. To avoid overlap, adjust the target column width and row height before inserting the image.

Adjusting the Image Offset Within a Cell

After insertion, LeftColumnOffset and TopRowOffset fine-tune the image position inside the cell, leaving a gap between the image and the cell borders:

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

sheet.Range["A1"].Text = "Align picture within a cell:"
sheet.Range["A1"].Style.VerticalAlignment = VerticalAlignType.Top

picture = sheet.Pictures.Add(1, 1, "logo.png")

# Widen the column and heighten the row to fit the image
sheet.Columns[0].ColumnWidth = 40
sheet.Rows[0].RowHeight = 200

# Offset the image inside the cell
picture.LeftColumnOffset = 100
picture.TopRowOffset = 25

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

LeftColumnOffset is the horizontal offset from the cell's left edge, and TopRowOffset is the vertical offset from the top edge, both in pixels. Combined with ColumnWidth and RowHeight to enlarge the cell first, then offsetting the image into place, you can center the image or leave whitespace around it.

Reading the Image Position and Size

An image already in a worksheet can be retrieved by index from the Pictures collection, and its position and dimensions read back:

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

picture = sheet.Pictures[0]
left = picture.Left
top = picture.Top
width = picture.Width
height = picture.Height

print(f"Left={left}, Top={top}, Width={width}, Height={height}")

workbook.Dispose()

Left and Top are the absolute coordinates of the image in the worksheet, and Width and Height are its displayed dimensions. These values are useful when aligning an image to a region or checking whether it falls outside the print area.

Compressing Images

Inserting high-resolution images quickly inflates the Excel file size. The Compress() method compresses images in a worksheet at a specified quality. The argument is an integer from 0 to 100; a smaller value means higher compression:

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

for sheet in workbook.Worksheets:
    for picture in sheet.Pictures:
        picture.Compress(50)

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

The outer loop iterates all worksheets, the inner loop all images on each sheet. Compress(50) reduces every image to 50% quality. For reports viewed only on screen, 50 is usually enough; for reports that will be printed, 75 preserves more detail.

Deleting Images from a Worksheet

To clean old images out of a template or remove unwanted illustrations, iterate the Pictures collection and remove each one:

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

# Iterate in reverse to avoid index shifting after removal
for i in range(sheet.Pictures.Count - 1, -1, -1):
    sheet.Pictures[i].Remove()

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

Iterate from the end when deleting. Each Remove() shortens the collection by one, so a forward loop would skip images or go out of bounds. A reverse loop safely clears every image on the sheet.

Practical Tips

Set the target cell's column width and row height before inserting an image, so it does not overlap neighboring data.
LeftColumnOffset and TopRowOffset are in pixels, while ColumnWidth is in character units — do not mix them.
Compress() modifies the image data itself and is lossy; back up the original image first if it must be preserved.
To insert the same logo into multiple worksheets, put Pictures.Add() inside a for sheet in workbook.Worksheets loop.
Call workbook.Dispose() when finished to release resources.

Conclusion

This article covered the common operations for working with images in Excel using Python: inserting an image at a specific cell with Pictures.Add(), fine-tuning its position with LeftColumnOffset and TopRowOffset, reading its position and size through Left/Top/Width/Height, reducing file size with Compress(), and deleting images in bulk by iterating the Pictures collection in reverse. Combined inside a report-generation script, image insertion and maintenance can be fully automated.

Set Cell Borders and Styles in Excel Using Python

Allen Yang — Thu, 24 Sep 2026 07:19:28 +0000

A report needs more than accurate data — it needs clear layout. Borders separate rows and columns, font styles highlight key figures, and alignment keeps numbers and text in their proper places. These are the basic techniques that make an Excel report readable. When reports must be generated in batch or refreshed on a schedule, setting formats through a script is more reliable than adjusting them by hand.

This article uses Spire.XLS for Python to show how to apply borders to a cell range, create a custom style and apply it to entire rows or columns, apply Excel built-in styles, and set font properties directly.

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 *

Applying Borders to a Cell Range

The most common need is to add uniform borders to a data range. After obtaining a CellRange, use the Borders property to set them in bulk:

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

# Get the entire data range from the first row/column to the last
cr = sheet.Range[sheet.FirstRow, sheet.FirstColumn, sheet.LastRow, sheet.LastColumn]

# Set border line style and color at once
cr.Borders.LineStyle = LineStyleType.Double
cr.Borders.Color = Color.get_CadetBlue()

# Turn off diagonal borders
cr.Borders[BordersLineType.DiagonalDown].LineStyle = LineStyleType.none
cr.Borders[BordersLineType.DiagonalUp].LineStyle = LineStyleType.none

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

Borders.LineStyle and Borders.Color apply to every border inside the range at once. Diagonal borders are set by default; if they are not wanted, explicitly set DiagonalDown and DiagonalUp to LineStyleType.none. LineStyleType also includes common styles such as Thin, Medium, Dotted, and Dashed.

Creating a Custom Style and Applying It to a Row or Column

When several rows or columns share the same format, setting each cell individually is verbose. A named style can be created once and then applied to whole rows or columns:

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

# Create a named style
style = workbook.Styles.Add("headerStyle")
style.VerticalAlignment = VerticalAlignType.Center
style.HorizontalAlignment = HorizontalAlignType.Center
style.Font.Color = Color.get_Blue()
style.ShrinkToFit = True

# Define a bottom border inside the style
style.Borders[BordersLineType.EdgeBottom].Color = Color.get_OrangeRed()
style.Borders[BordersLineType.EdgeBottom].LineStyle = LineStyleType.Dotted

# Apply it to the first column
sheet.Columns[0].CellStyleName = style.Name
sheet.Columns[0].Text = "Test"

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

The style object returned by workbook.Styles.Add() supports the full set of properties: font, alignment, borders, fill, and more. Once defined, apply it through CellStyleName = style.Name to sheet.Columns[i] or sheet.Rows[i], and a single line formats the entire column or row. Replacing sheet.Columns[0] with sheet.Rows[1] applies the same style to the second row.

Applying Excel Built-in Styles

Excel ships with a set of built-in styles (such as Title, Heading, Good, Bad). They can be applied directly, saving the effort of choosing colors manually:

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

# Apply the Title style to the first row
sheet.Range["A1:E1"].BuiltInStyle = BuiltInStyles.Title

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

The BuiltInStyles enum corresponds to the predefined styles in the "Cell Styles" gallery on Excel's Home tab, which is useful when the report should match Excel's native look.

Setting Font Properties Directly

When only the font of a specific range needs to change, there is no need to create a style object — work through Range.Style.Font directly:

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

# Font name and size
sheet.Range["B1"].Style.Font.FontName = "Comic Sans MS"
sheet.Range["B1"].Style.Font.Size = 45

# Bold, italic, underline
sheet.Range["B2:D2"].Style.Font.IsBold = True
sheet.Range["B3:D7"].Style.Font.IsItalic = True
sheet.Range["B3:B7"].Style.Font.Underline = FontUnderlineType.Single

# Font color and strikethrough
sheet.Range["B1"].Style.Font.Color = Color.get_CornflowerBlue()
sheet.Range["D3"].Style.Font.IsStrikethrough = True

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

The Font object exposes properties such as FontName, Size, IsBold, IsItalic, Underline, Color, and IsStrikethrough, each settable independently. Underline takes a FontUnderlineType enum value (such as Single, Double, AccountingSingle).

Practical Tips

Borders.LineStyle applies to all borders in the range; to set only one side, use Borders[BordersLineType.EdgeBottom] and similar to target it individually.
A custom style defined once can be reused in many places, which is more efficient than per-cell formatting and easier to revise later.
ShrinkToFit = True shrinks text to fit the column width, suitable for columns whose content length is unpredictable.
Named colors like Color.get_CadetBlue() are easy to remember; Color.FromArgb(r, g, b) can specify any color.
Call workbook.Dispose() when finished to release resources.

Conclusion

This article covered several ways to format Excel cells with Python: adding borders through Borders, creating a named style with workbook.Styles.Add() and applying it to whole rows or columns, applying Excel built-in styles through BuiltInStyle, and setting font properties directly through Range.Style.Font. Combined inside a report-generation script, these operations let formatting be fully automated.

Converting Word Documents to Markdown Using Python

Allen Yang — Fri, 18 Sep 2026 10:39:24 +0000

Markdown stores content as plain text with lightweight structural markup. It renders on a wide range of documentation platforms and can equally be processed as ordinary text. When existing documents need to feed a documentation site, a static blog, a code repository, or a corpus for a large language model, Markdown is often a better intermediate format than Word: it is easier to version, easier to search in bulk, and does not depend on a particular application to open.

The difficulty is that a large amount of existing material is in .docx format. Opening each file by hand, copying the content, and re-formatting it as Markdown is slow, and with dozens or hundreds of files it barely moves forward.

Using Spire.Doc for Python, this article covers converting Word documents to Markdown, along with the related operations of PDF-to-Markdown conversion and batch processing, both of which also produce plain text. Every output in this workflow is a text file, so the result can be checked in a text editor.

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 *

Converting a Word Document to Markdown

The core operation takes two steps: load the document, then save it with FileFormat.Markdown.

doc = Document()

# Load a Word document
doc.LoadFromFile("Data/ToMarkdown.docx")

# Convert to Markdown format
doc.SaveToFile("ToMarkdown_output.md", FileFormat.Markdown)

doc.Close()

The FileFormat enum determines the output format; set it to Markdown to produce an .md file. Paragraphs are converted into their corresponding Markdown structures, headings map to # levels, and body text stays as ordinary paragraphs.

The same Document object can also be saved to other formats as needed, for example producing a docx and a PDF in the same run:

doc.SaveToFile("output.docx", FileFormat.Docx)
doc.SaveToFile("output.pdf", FileFormat.PDF)

The reverse direction works too: a Markdown file can be loaded and saved as another format, and LoadFromFile() recognizes the .md extension automatically.

doc.LoadFromFile("Data/FromMarkdown.md")
doc.SaveToFile("FromMarkdown_docx.docx", FileFormat.Docx)

One thing worth noting here: the output is plain text, so checking the result needs no Word or image viewer. Opening the .md file in a text editor is enough, and it also makes line-by-line diffing in version control straightforward.

Converting a PDF Document to Markdown

Alongside Word, a large share of existing material is PDF. PDF conversion goes through a different interface: construct a PdfToMarkdownConverter with the source file path, then call ConvertToMarkdown() to write the output.

from spire.pdf import *

inputFile = "DeleteImage.pdf"
outputFile = "out2.md"

# Create a converter with the input PDF file
converter = PdfToMarkdownConverter(inputFile)

# Convert the PDF content to Markdown and save it
converter.ConvertToMarkdown(outputFile)

Conversion behavior is adjusted through the MarkdownOptions property. If only the text matters and the images in the PDF do not need to be processed, set IgnoreImage to True to skip them:

converter = PdfToMarkdownConverter(inputFile)

# Skip processing images in the PDF
converter.MarkdownOptions.IgnoreImage = True

converter.ConvertToMarkdown(outputFile)

For text-heavy material, skipping images often yields cleaner output and shortens the conversion.

Converting Documents in Batch

Once single-file conversion is wrapped in a function, batch processing is just a loop. The following example walks every .docx file in a directory and converts each to a .md file of the same name:

import os

input_folder = "documents"
output_folder = "markdown"

for filename in os.listdir(input_folder):
    if not filename.lower().endswith(".docx"):
        continue

    doc = Document()
    doc.LoadFromFile(os.path.join(input_folder, filename))

    md_name = os.path.splitext(filename)[0] + ".md"
    doc.SaveToFile(os.path.join(output_folder, md_name), FileFormat.Markdown)
    doc.Close()

Keeping the output filename identical to the input (only the extension changes) makes the source easy to trace and lets later steps match files by name.

Practical Tips

Markdown has limited expressive power. Elements such as text boxes, multi-column layouts, headers and footers, and complex table styling have no native syntax in Markdown, so they may be dropped or degraded into ordinary paragraphs after conversion. Run a representative document through first to confirm how the content you care about survives.
Verify the output programmatically. Because the result is plain text, a script can check whether a file is empty, whether heading levels are correct, and whether key paragraphs are present — far more reliable than reading each file by hand.
For PDF-to-Markdown conversion, whether the source is a text-based or a scanned PDF makes a large difference. Text-based PDFs allow text to be extracted directly, whereas a scanned PDF is essentially a set of images and needs OCR before usable text exists.
Pay attention to the filtering condition in batch tasks. On Windows, opening a document in Word creates temporary files whose names start with ~$; filtering by extension and excluding those keeps unrelated files out of the run.
Call Close() when finished to release resources. This matters especially inside a batch loop, where otherwise file handles accumulate.

Conclusion

This article covered converting documents to Markdown with Python: loading a Word document through Document and saving it with FileFormat.Markdown, while the same object can also be saved as docx, PDF, and other formats; handling PDFs with PdfToMarkdownConverter and MarkdownOptions.IgnoreImage; and converting a whole folder with a single loop. Because every output is a text file, both verification and downstream processing can be done by script, which suits batch workflows such as documentation sites and corpus preparation.

Adding Watermarks to Word Documents Using Python

Allen Yang — Thu, 17 Sep 2026 09:59:52 +0000

Watermarks are a familiar visual cue in business documents. A "Confidential" or "Draft" label tells readers how a file should be handled, and a faint company logo reinforces branding without distracting from the content. Doing this by hand means opening every file, opening the watermark dialog, and repeating the same steps — error-prone when you have a folder of reports to process. With Python you can apply a consistent text or picture watermark across an entire batch of Word documents, which fits naturally into report generation or pre-distribution pipelines. This article shows how to add text watermarks, add picture watermarks, and remove watermarks using Spire.Doc for Python.

Why Add Watermarks with Python

Driving watermarks from a script has a few concrete advantages:

Batch processing: one script stamps hundreds of documents with the same watermark, no manual clicks.
Consistent styling: font, size, color, and angle are all set in code, so every document looks identical.
Repeatable: watermarking becomes one step in a larger pipeline that may also convert, merge, or split files.

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 *

Adding a Text Watermark

A text watermark is the most common case — a word such as "Confidential" or a company name tiled across the page background. Spire.Doc represents it with a TextWatermark object. After setting the text, font size, color, and layout, assign it to document.Watermark:

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

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

# Create a text watermark and configure its appearance
txtWatermark = TextWatermark()
txtWatermark.Text = "Confidential"
txtWatermark.FontSize = 95
txtWatermark.Color = Color.get_Blue()
txtWatermark.Layout = WatermarkLayout.Diagonal

# Apply the watermark to the document
document.Watermark = txtWatermark

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

Output:

TextWatermark() constructs an empty watermark object. Text holds the string to display, FontSize controls how large the watermark text renders, Color is taken from a predefined color through a static method such as Color.get_Blue(), and Layout decides how the text is arranged — WatermarkLayout.Diagonal slants the text along the diagonal so it fills the page. Assigning the object to document.Watermark and saving writes the watermark into the file.

Adding an Image Watermark

Instead of text, you may want a company logo or seal as the watermark. The PictureWatermark object handles image watermarks; SetPicture() points to the image file, while Scaling and IsWashout adjust its size and fade:

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

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

# Create a picture watermark and configure its appearance
picture = PictureWatermark()
picture.SetPicture("Logo.png")
picture.Scaling = 250
picture.IsWashout = False

# Apply the watermark to the document
document.Watermark = picture

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

Output:

SetPicture() accepts a local image path and works with common formats such as PNG and JPG. Scaling is a percentage of the image's original size — 250 places the logo at 250% of its native dimensions, which is useful when you want it prominent. IsWashout controls the "washout" fade effect; False keeps the image at full strength without fading. Assign it to document.Watermark and save.

Removing a Watermark

When a document is finalized and ready for official release, you often need to strip the draft watermark. Whether the original watermark was text or an image, setting document.Watermark to None clears it in one step:

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

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

# Setting the watermark to None removes both text and picture watermarks
document.Watermark = None

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

This works for both text and picture watermarks, so you do not need to track which type was applied. Note that it removes the document-level watermark; a watermark that was manually embedded as a header picture falls outside document.Watermark and is handled separately.

Practical Tips

Layout: besides WatermarkLayout.Diagonal, the layout enum also offers a horizontal arrangement, so you can switch the orientation to match the document style.
Color: Color.get_Blue() is only one predefined color; Color.get_Red(), Color.get_Gray(), and others are available, and Color.FromArgb(r, g, b) lets you specify any custom color.
Washout: setting IsWashout to True on a picture watermark produces a lighter, less intrusive background that works well as a brand tint.
Resource cleanup: call document.Close() after each document to release the file handle.
Free edition: the free edition of Spire.Doc adds an evaluation warning to the output and caps the page count, which matters when processing large batches.

Conclusion

This article covered the three common ways to work with Word watermarks in Python: TextWatermark for text watermarks, PictureWatermark for image watermarks, and assigning None to document.Watermark to remove either type. With these in hand, combined with simple file iteration, watermarking slots cleanly into automated report generation and document distribution workflows.

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.