DEV Community: Allen Yang

How to Add a Digital Signature to a PDF File Using Python

Allen Yang — Thu, 16 Jul 2026 08:54:36 +0000

When contracts, invoices, reports, and other documents are being circulated, a common concern arises: how can you confirm that a document was indeed issued by a specific signer and that its content has not been tampered with after signing? Digital signatures are the mechanism designed for exactly this purpose. Built on PKI (Public Key Infrastructure) technology, a digital signature binds the signer's identity to the document content — if the document is modified in any way after signing, signature verification will fail.

Compared to manually signing documents one by one in tools like Adobe Acrobat, programmatically processing signatures is far better suited for automated scenarios — for example, system-generated contracts, daily settlement reports, or workflow documents that need to be stamped upon approval. This article will walk you through adding visible signatures, invisible signatures, and timestamped signatures to PDF documents using Python, as well as verifying already-signed documents.

Problems Digital Signatures Solve

Programmatically handling digital signatures is typically driven by the following considerations:

Integrity verification: Once a signed document is altered in any way, verification immediately fails, allowing you to detect tampering.
Identity authentication: Signatures are based on the holder's certificate (PFX/PKCS#12 file), proving that the document was signed by a specific entity.
Batch automation: Approval systems and settlement systems can automatically sign documents at the time of generation, with no manual intervention required.
Long-term verifiability: When combined with a timestamp service, it can be proven that the signing occurred while the certificate was still valid, even if the certificate has since expired.

Environment Setup

For working with PDF signatures in Python, you can use Spire.PDF for Python, which can be installed via pip:

pip install Spire.Pdf

In addition to the library itself, you will need a digital certificate file for signing, typically in .pfx (or .p12) format, along with its corresponding password. Certificates can be issued by a Certificate Authority (CA), or you can use self-signed certificates during the testing phase.

Adding a Visible Digital Signature

A visible signature renders a signature field on the page, displaying information such as the signer, reason, location, and more. This is ideal for scenarios where readers need to clearly see that the document has been signed.

The core object is PdfOrdinarySignatureMaker: it takes the PDF document, the certificate file path, and the certificate password, and performs the signing operation. The visual appearance of the signature is configured separately through PdfSignatureAppearance.

from spire.pdf import *

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

# Create a signature maker using the certificate file and password
signatureMaker = PdfOrdinarySignatureMaker(doc, "Jerry.pfx", "e-iceblue")

# Configure signature metadata
signature = signatureMaker.Signature
signature.Name = "Jerry"
signature.ContactInfo = "555-123-4567"
signature.Location = "New York"
signature.Reason = "Signed by the document owner"

# Configure signature appearance
appearance = PdfSignatureAppearance(signature)
appearance.NameLabel = "Signer: "
appearance.ContactInfoLabel = "Contact: "
appearance.LocationLabel = "Location: "
appearance.ReasonLabel = "Reason: "
appearance.SignatureImage = PdfImage.FromFile("logo.png")
appearance.GraphicMode = GraphicMode.SignImageAndSignDetail

# Draw the signature field at the specified position on the first page: x, y, width, height
signatureMaker.MakeSignature("Signer:", doc.Pages.get_Item(0), 90.0, 550.0, 270.0, 90.0, appearance)

doc.SaveToFile("DigitalSignature.pdf")
doc.Dispose()

There are a few key points worth noting:

The Name, Reason, Location, and other properties set on the Signature object are written into the signature object itself. PDF readers read these values when displaying signature details.
GraphicMode determines what the signature field displays. SignImageAndSignDetail means both an image (such as a company logo) and text information are shown; you can also choose to display only the image or only the text.
The coordinate parameters in MakeSignature are measured in points, with the origin at the bottom-left corner of the page. The last four numbers correspond to the left boundary, bottom boundary, width, and height of the signature field, respectively.

Adding an Invisible Signature

In some scenarios, you may not want a visible signature field on the page — you only need to sign the document at the document level to ensure integrity. In such cases, you can create an invisible signature without appearance parameters.

from spire.pdf import *

doc = PdfDocument()
doc.LoadFromFile("SampleB_1.pdf")

# Create a signature maker
signatureMaker = PdfOrdinarySignatureMaker(doc, "Jerry.pfx", "e-iceblue")

# Pass only the signature field name without setting appearance — this creates an invisible signature
signatureMaker.MakeSignature("signName")

doc.SaveToFile("AddInvisibleSignature.pdf")
doc.Dispose()

Invisible signatures provide the same tamper-proof capabilities. PDF readers can still detect them in the signature panel; they simply do not display any visible marker on the page.

Adding a Timestamped Signature

All digital certificates have an expiration date. If you need to prove that "the signing occurred while the certificate was still valid," you need to integrate a trusted Timestamp Authority (TSA). The Security_PdfSignature class provides the ConfigureTimestamp method for specifying the TSA service URL.

from spire.pdf import *

doc = PdfDocument()
doc.LoadFromFile("SampleB_1.pdf")

# Create a signature object with a page reference
signature = Security_PdfSignature(doc, doc.Pages.get_Item(0), "Jerry.pfx", "e-iceblue", "signature")

# Set the position and size of the signature field
signature.Bounds = RectangleF(PointF(90.0, 550.0), SizeF(180.0, 90.0))
signature.NameLabel = "Digitally signed by: Jerry"
signature.Reason = "Ensuring document authenticity"

# Restrict post-signing operations: allow form filling only, forbid other modifications
signature.DocumentPermissions = PdfCertificationFlags.AllowFormFill.value | PdfCertificationFlags.ForbidChanges.value

# Configure the trusted timestamp service
signature.ConfigureTimestamp("https://freetsa.org/tsr")

doc.SaveToFile("SignedByTimestamp.pdf")
doc.Dispose()

DocumentPermissions is a practical property here — it restricts post-signing operations through a certification signature. The combination in this example means "allow continued form field filling, but forbid any other changes," making it suitable for form-type documents that still need to collect information after approval while preventing content from being tampered with.

Verifying Signed Documents

Once you have a signed document, you can iterate through the signature fields in its form and verify each signature individually.

from spire.pdf import *

doc = PdfDocument()
doc.LoadFromFile("SignedDocument.pdf")

# Access the document form
formWidget = PdfFormWidget(doc.Form)

if formWidget.FieldsWidget.Count > 0:
    for i in range(formWidget.FieldsWidget.Count):
        field = formWidget.FieldsWidget.get_Item(i)
        if isinstance(field, PdfField):
            signatureField = PdfSignatureFieldWidget(field)
            # Verify the corresponding signature using the field's full name
            valid = doc.VerifySignature(signatureField.FullName)
            print("Signature is valid" if valid else "Signature is invalid")

doc.Dispose()

VerifySignature recalculates the document content digest and compares it against the value recorded in the signature — if the document has been modified after signing, the result will be invalid. This is the final step that fulfills the "tamper-proof" promise of digital signatures.

Practical Tips

Do not hardcode certificate passwords: In the examples, passwords are written directly in the code for demonstration purposes. In production, they should be read from environment variables or a key management service.
Coordinate system: Signature field coordinates use the bottom-left corner of the page as the origin, with the y-axis increasing upward — the opposite of typical screen coordinates. Keep this in mind when positioning signature fields.
Signing order: A document can contain multiple signatures. Each subsequent signature incorporates all previous signatures into its verification scope, so the signing order affects the verification logic.
Release resources promptly: After processing, call Dispose() to release file handles held by the document, preventing file-locking issues in batch tasks.

Conclusion

This article covered four common operations related to PDF digital signatures: visible signatures, invisible signatures, timestamped signatures, and signature verification. All of them are built on the binding between a certificate file and the document content — PdfOrdinarySignatureMaker handles standard signing, Security_PdfSignature extends it with timestamping and permission control, and VerifySignature completes the verification loop.

Building on this foundation, you can further integrate form fields, document permissions, and Long-Term Validation (LTV) capabilities to create automated signing solutions tailored for contract management, approval workflows, and similar scenarios.

Automating Excel Formulas and Functions Using Python

Allen Yang — Fri, 10 Jul 2026 10:47:14 +0000

In modern data processing workflows, Excel formulas and functions are essential tools for performing calculations, analyzing data, and implementing business logic. However, manually entering and managing large numbers of formulas is not only time-consuming but also prone to errors. By automating Excel formula insertion and management with Python, developers can process spreadsheets in bulk, dynamically generate calculation logic, and ensure accuracy and consistency in data processing.

This article demonstrates how to use Python to insert various types of formulas and functions into Excel worksheets, including basic arithmetic operations, built-in functions, array formulas, and named ranges. These techniques are applicable to scenarios such as financial report automation, data analysis pipeline construction, and batch data processing.

Environment Setup

First, install the Spire.XLS for Python library:

pip install Spire.XLS

This library provides a comprehensive API for Excel file manipulation, supporting formula insertion, calculation execution, and file format conversion.

Inserting Basic Formulas

Excel formulas begin with an equals sign (=) and can contain constants, cell references, operators, and function calls. When inserting formulas using Python, simply assign the formula string to the cell's Formula property.

The following example demonstrates how to insert various basic formulas into a worksheet:

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

# Create a workbook
workbook = Workbook()
sheet = workbook.Worksheets[0]

# Set test data
sheet.Range["B2"].NumberValue = 7.3
sheet.Range["C2"].NumberValue = 5
sheet.Range["D2"].NumberValue = 8.2

# Insert string formula
sheet.Range["A4"].Text = '="hello"'
sheet.Range["B4"].Formula = '="hello"'

# Insert arithmetic formula
sheet.Range["A5"].Text = "=1+2+3+4+5-6-7+8-9"
sheet.Range["B5"].Formula = "=1+2+3+4+5-6-7+8-9"

# Insert multiplication operation
sheet.Range["A6"].Text = "=33*3/4-2+10"
sheet.Range["B6"].Formula = "=33*3/4-2+10"

# Reference other cells
sheet.Range["A7"].Text = "=Sheet1!$B$2"
sheet.Range["B7"].Formula = "=Sheet1!$B$2"

# Reference a cell range and calculate average
sheet.Range["A8"].Text = "=AVERAGE(Sheet1!$B$2:$D$2)"
sheet.Range["B8"].Formula = "=AVERAGE(Sheet1!$B$2:$D$2)"

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

This example demonstrates:

String constants: Text enclosed in double quotes
Arithmetic operations: Support for addition, subtraction, multiplication, division, and operator precedence
Cell references: Using the $ symbol to create absolute references
Range references: Using colons to specify continuous cell ranges

Using Built-in Functions

Excel provides hundreds of built-in functions covering mathematics, statistics, date/time operations, logical operations, and text processing. Python allows flexible insertion of these functions.

Mathematical and Statistical Functions

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

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

currentRow = 1

# COUNT function - count the number of arguments
sheet.Range[f"A{currentRow}"].Text = "=Count(3,5,8,10,2,34)"
sheet.Range[f"B{currentRow}"].Formula = "=Count(3,5,8,10,2,34)"
currentRow += 1

# SUM function - calculate sum
sheet.Range[f"A{currentRow}"].Text = "=SUM(18,29)"
sheet.Range[f"B{currentRow}"].Formula = "=SUM(18,29)"
currentRow += 1

# AVERAGE function - calculate average
sheet.Range[f"A{currentRow}"].Text = "=AVERAGE(12,45)"
sheet.Range[f"B{currentRow}"].Formula = "=AVERAGE(12,45)"
currentRow += 1

# MAX and MIN functions
sheet.Range[f"A{currentRow}"].Text = "=MAX(10,30)"
sheet.Range[f"B{currentRow}"].Formula = "=MAX(10,30)"
currentRow += 1

sheet.Range[f"A{currentRow}"].Text = "=MIN(5,7)"
sheet.Range[f"B{currentRow}"].Formula = "=MIN(5,7)"
currentRow += 1

# ROUND function - round numbers
sheet.Range[f"A{currentRow}"].Text = "=ROUND(7,3)"
sheet.Range[f"B{currentRow}"].Formula = "=ROUND(7,3)"
currentRow += 1

# SQRT function - square root
sheet.Range[f"A{currentRow}"].Text = "=SQRT(40)"
sheet.Range[f"B{currentRow}"].Formula = "=SQRT(40)"
currentRow += 1

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

Date and Time Functions

Handling date and time data is a common requirement in Excel automation. The following code demonstrates how to use date and time functions:

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

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

# NOW function - current date and time
sheet.Range["A1"].Text = "=NOW()"
sheet.Range["B1"].Formula = "=NOW()"
sheet.Range["B1"].Style.NumberFormat = "yyyy-MM-DD HH:mm:ss"

# DATE function - construct a date
sheet.Range["A2"].Text = "=DATE(2024,1,15)"
sheet.Range["B2"].Formula = "=DATE(2024,1,15)"
sheet.Range["B2"].Style.NumberFormat = "yyyy-MM-DD"

# TIME function - construct a time
sheet.Range["A3"].Text = "=TIME(14,30,0)"
sheet.Range["B3"].Formula = "=TIME(14,30,0)"
sheet.Range["B3"].Style.NumberFormat = "HH:mm:ss"

# YEAR, MONTH, DAY functions - extract date components
sheet.Range["A4"].Text = "=YEAR(NOW())"
sheet.Range["B4"].Formula = "=YEAR(NOW())"

sheet.Range["A5"].Text = "=MONTH(NOW())"
sheet.Range["B5"].Formula = "=MONTH(NOW())"

sheet.Range["A6"].Text = "=DAY(NOW())"
sheet.Range["B6"].Formula = "=DAY(NOW())"

# HOUR, MINUTE, SECOND functions - extract time components
sheet.Range["A7"].Text = "=HOUR(NOW())"
sheet.Range["B7"].Formula = "=HOUR(NOW())"

sheet.Range["A8"].Text = "=MINUTE(NOW())"
sheet.Range["B8"].Formula = "=MINUTE(NOW())"

sheet.Range["A9"].Text = "=SECOND(NOW())"
sheet.Range["B9"].Formula = "=SECOND(NOW())"

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

Logical and Conditional Functions

Logical functions are used to implement conditional judgments and business rules:

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

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

# IF function - conditional judgment
sheet.Range["A1"].Text = '=IF(10>5, "Greater", "Less")'
sheet.Range["B1"].Formula = '=IF(10>5, "Greater", "Less")'

# AND function - logical AND
sheet.Range["A2"].Text = "=AND(TRUE, TRUE)"
sheet.Range["B2"].Formula = "=AND(TRUE, TRUE)"

# OR function - logical OR
sheet.Range["A3"].Text = "=OR(FALSE, TRUE)"
sheet.Range["B3"].Formula = "=OR(FALSE, TRUE)"

# NOT function - logical NOT
sheet.Range["A4"].Text = "=NOT(FALSE)"
sheet.Range["B4"].Formula = "=NOT(FALSE)"

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

Text Processing Functions

Text functions are used for string manipulation and data cleaning:

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

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

# LEN function - string length
sheet.Range["A1"].Text = '=LEN("Hello World")'
sheet.Range["B1"].Formula = '=LEN("Hello World")'

# MID function - extract substring
sheet.Range["A2"].Text = '=MID("Hello World",7,5)'
sheet.Range["B2"].Formula = '=MID("Hello World",7,5)'

# VALUE function - convert text to number
sheet.Range["A3"].Text = '=VALUE("123")'
sheet.Range["B3"].Formula = '=VALUE("123")'

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

Using Array Formulas

Array formulas can perform calculations on multiple values and return either a single result or multiple results. This is particularly useful when executing matrix operations and batch data processing.

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

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

# Prepare data
sheet.Range["A1"].NumberValue = 1
sheet.Range["A2"].NumberValue = 2
sheet.Range["A3"].NumberValue = 3

sheet.Range["B1"].NumberValue = 4
sheet.Range["B2"].NumberValue = 5
sheet.Range["B3"].NumberValue = 6

sheet.Range["C1"].NumberValue = 7
sheet.Range["C2"].NumberValue = 8
sheet.Range["C3"].NumberValue = 9

# Insert array formula - LINEST function performs linear regression analysis
sheet.Range["A5:C6"].FormulaArray = "=LINEST(A1:A3,B1:C3,TRUE,TRUE)"

# Calculate all formula values
workbook.CalculateAllValue()

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

Key points:

Use the FormulaArray property instead of Formula to insert array formulas
Array formulas need to span multiple cell ranges
Call the CalculateAllValue() method to ensure formulas are calculated correctly

Using the SUBTOTAL Function

The SUBTOTAL function can perform aggregate calculations on data lists and ignore hidden rows, which is particularly useful when creating interactive reports.

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

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

# Prepare data
for row in range(1, 4):
    sheet.Range[f"A{row}"].NumberValue = row
    sheet.Range[f"B{row}"].NumberValue = row + 3
    sheet.Range[f"C{row}"].NumberValue = row + 6

# Insert different SUBTOTAL functions
# 1 represents AVERAGE
sheet.Range["A5"].Formula = "=SUBTOTAL(1,A1:C3)"

# 2 represents COUNT
sheet.Range["B5"].Formula = "=SUBTOTAL(2,A1:C3)"

# 5 represents MIN
sheet.Range["C5"].Formula = "=SUBTOTAL(5,A1:C3)"

# Calculate formulas
workbook.CalculateAllValue()

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

The first parameter of the SUBTOTAL function specifies the calculation type:

1: AVERAGE
2: COUNT
3: COUNTA (count non-empty cells)
4: MAX
5: MIN
9: SUM

Using Named Ranges and Formulas

Named ranges improve formula readability and maintainability. By replacing complex cell references with meaningful names, formulas become easier to understand.

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

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

# Set data
sheet.Range["A1"].Value = "10"
sheet.Range["A2"].Value = "20"

# Create a named range
namedRange = workbook.NameRanges.Add("SumRange")
namedRange.RefersToRange = sheet.Range["A1:A2"]

# Use the named range in a formula
sheet.Range["C1"].Formula = "=SUM(SumRange)"

# Alternatively, define a named formula directly
namedFormula = workbook.NameRanges.Add("TotalCalc")
namedFormula.NameLocal = "=SUM(A1+A2)"
sheet.Range["C2"].Formula = "TotalCalc"

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

The advantages of this approach include:

Improved readability: =SUM(SumRange) is clearer than =SUM(A1:A2)
Easier maintenance: Modifying the named range reference automatically updates all formulas using that name
Reduced errors: Avoids manual entry of complex cell references

Practical Tips

Formatting Formula Cells

To distinguish formula cells from data cells, you can apply special formatting:

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

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

# Insert formula
sheet.Range["A1"].Formula = "=SUM(B1:B10)"

# Set background color for formula cell
sheet.Range["A1"].Style.Color = Color.get_LightYellow()

# Add borders
sheet.Range["A1"].Style.Borders[BordersLineType.EdgeTop].LineStyle = LineStyleType.Thin
sheet.Range["A1"].Style.Borders[BordersLineType.EdgeBottom].LineStyle = LineStyleType.Thin

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

Forcing Formula Calculation

In some cases, you may need to immediately obtain the calculated result of a formula rather than keeping the formula itself:

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

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

sheet.Range["A1"].NumberValue = 10
sheet.Range["A2"].NumberValue = 20
sheet.Range["A3"].Formula = "=A1+A2"

# Calculate all formulas
workbook.CalculateAllValue()

# At this point, A3 value is already 30
result = sheet.Range["A3"].Value
print(f"Calculation result: {result}")

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

Handling Cross-Sheet References

When formulas need to reference data from other worksheets, use the worksheet name followed by an exclamation mark:

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

workbook = Workbook()

# Create two worksheets
sheet1 = workbook.Worksheets[0]
sheet1.Name = "Data"
sheet2 = workbook.Worksheets.Add("Calculation")

# Set data in the first worksheet
sheet1.Range["A1"].NumberValue = 100
sheet1.Range["A2"].NumberValue = 200

# Reference data from the first worksheet in the second worksheet
sheet2.Range["A1"].Formula = "=Data!A1+Data!A2"

workbook.CalculateAllValue()
workbook.SaveToFile("CrossSheetFormula.xlsx", ExcelVersion.Version2010)
workbook.Dispose()

Conclusion

This article has demonstrated various techniques for automating Excel formulas and functions using Python, including:

Inserting basic arithmetic formulas and cell references
Using mathematical, statistical, date/time, logical, and text processing functions
Executing array formulas for complex calculations
Leveraging the SUBTOTAL function for flexible aggregate calculations
Improving formula readability and maintainability through named ranges

These techniques enable developers to:

Generate spreadsheets with complex calculation logic in bulk
Automate financial models and data analysis reports
Dynamically build condition-based calculation formulas
Improve consistency and accuracy in data processing

By combining Python's programming capabilities with Excel's calculation features, you can build powerful data processing automation solutions that significantly improve工作效率 and reduce human error.

Protect and Unprotect Excel Worksheets and Workbooks Using Python

Allen Yang — Mon, 06 Jul 2026 06:25:35 +0000

In enterprise data management and report distribution scenarios, Excel files often contain sensitive information or critical formulas that need protection from unauthorized modifications. Manually setting protection passwords on each worksheet is feasible for a small number of files, but it becomes inefficient when dealing with batch processing or automated report generation.

By implementing worksheet and workbook protection programmatically with Python, security policies can be seamlessly integrated into document generation and distribution workflows. This article covers how to password-protect worksheets, lock specific cells and rows/columns, define editable ranges, hide formulas, and remove protection using Python.

Environment Setup

This article uses the Spire.XLS for Python library to work with Excel files. Install it via pip:

pip install Spire.XLS

Import the required modules in your script:

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

Understanding Excel Protection Basics

Excel's protection mechanism operates at two levels:

Worksheet protection: Restricts editing of cell contents within a worksheet. You can set a password and selectively allow certain operations (such as sorting or filtering).
Workbook protection: Restricts modifications to the workbook structure, preventing users from adding, deleting, or renaming worksheets.

In Spire.XLS, worksheet protection is implemented through the Protect() method, while workbook protection uses the Workbook.Protect() method. Every cell has a Locked property — by default, all cells are locked, but the lock only takes effect once worksheet protection is enabled.

Protect a Worksheet

The simplest form of protection is setting a password on the entire worksheet. Once protection is enabled, all cells are locked by default and users cannot edit any content:

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

# Create a workbook and load the file
workbook = Workbook()
workbook.LoadFromFile("input.xlsx")

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

# Protect the worksheet with a password
sheet.Protect("MyPassword", SheetProtectionType.All)

# Save the document
workbook.SaveToFile("ProtectSheet.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

SheetProtectionType.All denies all operations. You can also choose more granular protection types, such as preventing only row insertion, column deletion, or other specific actions.

Lock Specific Cells

In most scenarios, you don't need to lock everything — only critical formula cells or summary data need protection. The key to achieving this is to first unlock all cells, then lock only the ones that need protection, and finally enable worksheet protection.

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

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

# Lock cell B3
sheet.Range["B3"].Style.Locked = True

# Unlock cell C3 (editable even when the sheet is protected)
sheet.Range["C3"].Style.Locked = False

# Enable worksheet protection
sheet.Protect("TestPassword", SheetProtectionType.All)

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

This approach is ideal for form-style documents where most fields should be user-editable, with only formulas, headers, and other key areas requiring protection.

Lock Specific Rows or Columns

When you need to protect entire rows or columns of data, you can iterate through and set the lock status accordingly. The following example unlocks all rows first, then locks only row 3:

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

# Unlock all rows
for i in range(0, 255):
    sheet.Rows[i].Style.Locked = False

# Lock row 3
sheet.Rows[2].Text = "Locked"
sheet.Rows[2].Style.Locked = True

# Enable protection
sheet.Protect("123", SheetProtectionType.All)

workbook.SaveToFile("LockSpecificRow.xlsx", ExcelVersion.Version2013)

Locking a specific column follows a similar pattern. The example below locks column D (the 4th column):

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

# Unlock all rows
for i in range(0, 255):
    sheet.Rows[i].Style.Locked = False

# Lock column D
sheet.Columns[3].Text = "Locked"
sheet.Columns[3].Style.Locked = True

# Enable protection
sheet.Protect("123", SheetProtectionType.All)

workbook.SaveToFile("LockSpecificColumn.xlsx", ExcelVersion.Version2013)

Define Editable Ranges

A more flexible approach is to specify certain areas as "allowed edit ranges" while the worksheet remains protected. Users can freely edit within these ranges while the rest of the worksheet stays locked:

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

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

# Define the range that users are allowed to edit
sheet.AddAllowEditRange("EditableRanges", sheet.Range["B4:E12"])

# Protect the worksheet
sheet.Protect("TestPassword", SheetProtectionType.All)

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

The AddAllowEditRange() method takes two parameters: a range name and a range reference. This approach is more intuitive than setting the Locked property on individual cells, making it especially useful when you need to open up data entry areas within a protected spreadsheet.

Protect Workbook Structure

Beyond worksheet-level protection, you can also protect the overall workbook structure to prevent users from adding, deleting, or renaming worksheets:

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

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

# Protect the workbook structure
workbook.Protect("e-iceblue")

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

Workbook protection and worksheet protection can be applied simultaneously, creating multi-layered defense from the overall structure down to individual cell contents.

Hide Formulas

In reports containing complex formulas, you may want users to see the calculated results without being able to view or modify the formulas themselves. By setting the IsFormulaHidden property and enabling protection, all formulas in the worksheet can be hidden:

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

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

# Hide all formulas in the used range
sheet.AllocatedRange.IsFormulaHidden = True

# Enable worksheet protection for the hidden setting to take effect
sheet.Protect("e-iceblue")

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

It's important to note that the IsFormulaHidden property only takes effect after worksheet protection is enabled. Setting this property alone will not hide formulas.

Unprotect a Worksheet

Removing protection requires the correct password. Use the Unprotect() method and pass in the password that was set during protection:

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

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

# Remove protection using the password
sheet.Unprotect("e-iceblue")

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

If the worksheet was protected without a password, you can call Unprotect() without passing any arguments.

Practical Tips

Combining protection with editable ranges: When building data entry templates, use AddAllowEditRange() to open up input areas, then protect the worksheet. This prevents users from accidentally modifying headers and formulas while still allowing normal business data entry.

Batch protecting multiple worksheets: Iterate through all worksheets in a workbook and apply a uniform protection password:

for i in range(workbook.Worksheets.Count):
    sheet = workbook.Worksheets[i]
    sheet.Protect("CommonPassword", SheetProtectionType.All)

Password security best practices: In production environments, passwords should not be hardcoded in source code. Use environment variables or configuration files to manage passwords, and choose sufficiently strong passwords to guard against brute-force attacks.

Conclusion

This article covered the complete approach to protecting and unprotecting Excel worksheets and workbooks using Python, including basic protection, locking specific cells and rows/columns, defining editable ranges, hiding formulas, and removing protection. These capabilities have broad practical value in automated report generation, batch file processing, and document security management scenarios.

Combined with features like conditional formatting and data validation, you can build more secure and feature-rich Excel automation solutions.

Encrypt and Decrypt PDF Documents Using Python

Allen Yang — Fri, 03 Jul 2026 10:04:14 +0000

In enterprise document management and information security, protecting PDF documents is a critical concern. Whether it's contracts, financial reports, or internal technical documentation, encryption is needed to prevent unauthorized access and tampering. Manually setting passwords on each document is not only time-consuming but also difficult to integrate into automated workflows.

Python provides a programmatic approach to batch-encrypt and decrypt PDF documents. By controlling password settings, encryption algorithm selection, and permission assignment through code, document security policies can be standardized and embedded into existing document processing pipelines. This article covers how to implement PDF encryption, permission control, and decryption using Python.

Environment Setup

This article uses the Spire.PDF for Python library to work with PDF files. Install it via pip:

pip install Spire.PDF

Import the required modules in your script:

from spire.pdf import *

Core Concepts of PDF Encryption

Before writing any code, it's important to understand several key concepts in the PDF encryption system:

User Password: The password required to open the document. Once a user password is set, anyone without the password will be unable to view the document's contents.
Owner Password: The password that controls document permissions. Users with the owner password can modify the document's security settings and permissions.
Encryption Algorithm: PDF supports multiple encryption standards, including RC4 (40-bit and 128-bit), AES-128, and AES-256. The stronger the algorithm, the better the security.
Document Permissions: Controls whether users can perform specific operations on the document, such as printing, copying text, or filling out forms.

In Spire.PDF, all of these settings are managed through the PdfPasswordSecurityPolicy class.

Encrypt a PDF Using RC4

The most basic form of encryption involves setting both a user password and an owner password on the PDF. The following example uses the RC4-128 bit encryption algorithm and allows printing and form filling:

from spire.pdf import *

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

# Create a security policy with user and owner passwords
securityPolicy = PdfPasswordSecurityPolicy("open", "test")

# Set the encryption algorithm to RC4-128 bit
securityPolicy.EncryptionAlgorithm = PdfEncryptionAlgorithm.RC4_128

# Define document permissions: forbid all, then selectively enable
dp = PdfDocumentPrivilege.ForbidAll()
dp.AllowPrint = True
dp.AllowFillFormFields = True
securityPolicy.DocumentPrivilege = dp

# Apply the encryption policy
doc.Encrypt(securityPolicy)

# Save the document
doc.SaveToFile("Encrypted_RC4.pdf")

The key logic in this code is the permission control section. ForbidAll() first sets all permissions to denied, then specific operations are enabled by setting AllowPrint and AllowFillFormFields to True. This "deny by default, grant selectively" approach is more secure than "allow by default, deny selectively," as it avoids accidentally leaving some permissions unblocked.

Increase Security with AES Encryption

AES (Advanced Encryption Standard) is a widely recognized encryption algorithm in the industry and offers stronger security than RC4. Spire.PDF supports both AES-128 and AES-256 key lengths:

from spire.pdf import *

# Load the PDF document
pdfDocument = PdfDocument()
pdfDocument.LoadFromFile("input.pdf")

# Create a security policy
securityPolicy = PdfPasswordSecurityPolicy("123456789", "M123456789")

# Use the AES-128 encryption algorithm
securityPolicy.EncryptionAlgorithm = PdfEncryptionAlgorithm.AES_128

# Forbid all permissions, allow printing only
securityPolicy.DocumentPrivilege = PdfDocumentPrivilege.ForbidAll()
securityPolicy.DocumentPrivilege.AllowPrint = True

# Encrypt and save
pdfDocument.Encrypt(securityPolicy)
pdfDocument.SaveToFile("Encrypted_AES128.pdf")
pdfDocument.Close()

Note that AES encryption requires a user password of at least 8 characters. If the password is too short, the encryption operation may fail. In production environments, it is recommended to use strong passwords that include uppercase and lowercase letters, numbers, and special characters.

High-Level Encryption with AES-256

For documents containing sensitive business data or personal information, AES-256 provides the highest level of encryption protection:

from spire.pdf import *

doc = PdfDocument()
doc.LoadFromFile("input.pdf")

# No user password (left empty), owner password only
securityPolicy = PdfPasswordSecurityPolicy("", "test")

# Use AES-256 encryption
securityPolicy.EncryptionAlgorithm = PdfEncryptionAlgorithm.AES_256

# Set permissions: allow degraded printing and form filling
dp = PdfDocumentPrivilege.ForbidAll()
dp.AllowDegradedPrinting = True
dp.AllowFillFormFields = True
securityPolicy.DocumentPrivilege = dp

doc.Encrypt(securityPolicy)
doc.SaveToFile("Encrypted_AES256.pdf")

There is a notable detail in this code: the user password is set to an empty string. This means anyone can open the document and view its contents, but the document's operational permissions (printing, copying, etc.) are protected by the owner password. This configuration is suitable for documents that need to be widely distributed but require restrictions on editing and copying.

The difference between AllowDegradedPrinting and AllowPrint is that degraded printing produces lower-resolution output, preventing high-quality document reproduction — ideal for protecting content that contains intellectual property.

Decrypt a PDF Document

Decryption requires knowledge of the owner password (or user password). Pass the password when loading the document, then call the Decrypt() method:

from spire.pdf import *

# Load the encrypted PDF using the owner password
doc = PdfDocument()
doc.LoadFromFile("Encrypted_RC4.pdf", "test")

# Decrypt the document
doc.Decrypt()

# Save as an unencrypted PDF
doc.SaveToFile("Decrypted.pdf")

If the document was opened with the user password, the owner password must also be provided for decryption:

# Load using the user password
doc.LoadFromFile("Encrypted_RC4.pdf", "open")

# Pass the owner password to decrypt
doc.Decrypt("test")

doc.SaveToFile("Decrypted.pdf")

Once decrypted, the PDF document will no longer be protected by any passwords or permissions and can be opened and edited normally.

Available Permissions at a Glance

PdfDocumentPrivilege provides a range of permission control options. Here are the commonly used permission properties:

AllowPrint: Allows high-quality printing
AllowDegradedPrinting: Allows degraded (low-resolution) printing
AllowCopy: Allows copying document content
AllowFillFormFields: Allows filling in form fields
AllowModifyContents: Allows modifying document content
AllowComment: Allows adding comments

By combining these permissions thoughtfully, you can create differentiated security policies for different document types. For example, reports distributed to clients can allow printing but prohibit copying; internal forms can allow filling but prevent other modifications.

Practical Tips

Choosing an encryption algorithm: RC4-128 offers good compatibility and is suitable for scenarios that require backward compatibility with older PDF readers. AES-128 is sufficient for most everyday needs. AES-256 is recommended for documents containing highly sensitive information. In scenarios where security requirements are not particularly strict, AES-128 is more than adequate.

Batch encryption: When you need to apply the same encryption to multiple PDFs in a folder, combine this with Python's os or pathlib module to iterate through files and apply a uniform security policy. Owner and user passwords can be managed via configuration files or environment variables to avoid hardcoding them in scripts.

Password management best practices: In real-world projects, passwords should not be written directly in source code. Use environment variables, configuration files, or key management services to store passwords and reduce the risk of credential exposure.

Conclusion

This article covered the complete approach to encrypting and decrypting PDF documents using Python, including the use of RC4, AES-128, and AES-256 encryption algorithms, as well as the configuration of user passwords, owner passwords, and document permissions. These capabilities have broad practical value in document security management, automated report generation, and content protection scenarios.

Combined with other Spire.PDF features such as watermarking, text replacement, and form handling, you can build more comprehensive document security automation solutions.

Python Guide to Freezing and Splitting Excel Panes

Allen Yang — Fri, 03 Jul 2026 10:00:37 +0000

When working with Excel spreadsheets that contain large amounts of data, users often need to keep certain rows or columns visible while scrolling through the rest of the worksheet. Freeze panes is the core feature designed for this purpose — it locks specified rows or columns in place so they remain on screen as the user scrolls. While this is straightforward to do manually, it becomes inefficient when you need to apply the same settings across multiple workbooks.

Automating freeze pane operations with Python can significantly streamline data processing workflows. Whether you're auto-freezing header rows when generating reports or applying consistent freeze settings in batch processing scenarios, a programmatic approach ensures consistency and repeatability. This article walks through how to freeze panes, retrieve freeze information, and unfreeze panes in Excel worksheets using Python.

Environment Setup

This article uses the Spire.XLS for Python library to work with Excel files. Install it via pip:

pip install Spire.XLS

Once installed, import the required modules in your Python script:

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

How Freeze Panes Works

Before diving into code, it helps to understand the mechanics behind freeze panes. Excel's freeze pane feature works by establishing a "split point": everything above and to the left of a given cell is locked in place, while everything below and to the right remains scrollable.

In the Spire.XLS API, the FreezePanes() method takes two parameters:

row: The index of the first row below the frozen area (1-based)
column: The index of the first column to the right of the frozen area (1-based)

For example, FreezePanes(2, 1) freezes row 1 (the header row) and allows scrolling starting from row 2.

Freeze the Top Row

This is the most common use case — freezing the first row of a data table as a header so that column names remain visible as the user scrolls down through the data.

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

# Create a workbook and load the file
workbook = Workbook()
workbook.LoadFromFile("input.xlsx")

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

# Freeze the top row: scrolling starts from row 2, no columns frozen
sheet.FreezePanes(2, 1)

# Save the document
workbook.SaveToFile("FreezeTopRow.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

The parameters (2, 1) mean that row 2 and all rows above it are frozen, and column 1 and all columns to its left are frozen. Since column 1 is the leftmost column, only row 1 ends up being fixed in place.

Freeze the First Column

In some data tables, the first column contains row identifiers (such as product names or dates) that need to remain visible when scrolling horizontally:

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

# Freeze the first column: no rows frozen, scrolling starts from column 2
sheet.FreezePanes(1, 2)

# Save the document
workbook.SaveToFile("FreezeFirstColumn.xlsx", ExcelVersion.Version2013)

Setting the row parameter to 1 means no rows are frozen (there is no area above row 1 to freeze), while the column parameter of 2 freezes the first column.

Freeze Rows and Columns Simultaneously

In practice, it's common to freeze both header rows and identifier columns at the same time. For example, in a sales data table where row 1 contains column headers and column 1 contains product IDs, both need to stay visible while scrolling:

# Freeze the first row and first column simultaneously
# Parameters (3, 2) freeze the first two rows and the first column
sheet.FreezePanes(3, 2)

workbook.SaveToFile("FreezeRowsAndColumns.xlsx", ExcelVersion.Version2013)

FreezePanes(3, 2) freezes rows 1–2 and column A. The area starting from row 3 and column B becomes freely scrollable. This approach is well suited for complex tables with multi-row headers or when both row and column identifiers need to be pinned.

Retrieve Freeze Pane Information

In certain automation scenarios, you may need to check whether a worksheet already has frozen panes before deciding on the next step. The GetFreezePanes() method returns the row and column indices of the current freeze position:

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

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

# Retrieve the freeze pane position
indexs = sheet.GetFreezePanes()
rowIndex = indexs[0]
colIndex = indexs[1]

# Print the freeze position
print(f"Freeze row index: {rowIndex}, freeze column index: {colIndex}")

# A return value of 0 means that direction is not frozen
if rowIndex == 0 and colIndex == 0:
    print("No freeze panes are set on the current worksheet")

workbook.Dispose()

An index value of 0 indicates that the corresponding direction (row or column) is not frozen. This is useful when batch-processing multiple files, as it allows you to quickly identify which worksheets already have freeze panes configured and which do not.

Unfreeze Panes

If you need to modify a frozen worksheet or reconfigure the freeze area, the first step is to remove the existing freeze:

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

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

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

# Remove freeze panes
sheet.RemovePanes()

# Save the document
workbook.SaveToFile("UnfreezePanes.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

The RemovePanes() method removes all freeze settings in both directions, restoring the worksheet to a fully scrollable state.

Practical Tips

Freeze position vs. data start position: Freeze pane parameters are based on absolute positions within the worksheet, not relative to the data range. If your data starts on row 3 and you want to freeze the first two rows as headers, use FreezePanes(3, 1) rather than FreezePanes(2, 1).

Combining freeze with filtering: Freezing the header row on a worksheet with auto-filter applied lets users see column headers at all times while filtering data, significantly improving the browsing experience. Apply the freeze first, then set up the filter.

Batch processing multiple worksheets: When a workbook contains multiple worksheets, you can iterate through all of them and apply a uniform freeze setting:

for i in range(workbook.Worksheets.Count):
    sheet = workbook.Worksheets[i]
    sheet.FreezePanes(2, 1)  # Freeze the top row on every sheet

Important note: Each worksheet can only have one freeze position at a time. Calling FreezePanes() again will overwrite the previous setting. To change the freeze position, there is no need to call RemovePanes() first — simply set the new position directly.

Conclusion

This article covered the complete workflow for managing freeze panes in Excel worksheets using Python, including freezing the top row, first column, both rows and columns simultaneously, retrieving freeze information, and removing freeze settings. These capabilities have practical value in batch report generation, automated data organization, and document template processing.

Combined with other Spire.XLS features such as conditional formatting, data validation, and cell merging, you can build more comprehensive Excel automation solutions.

Managing Bookmarks in PDF Documents with Python

Allen Yang — Thu, 02 Jul 2026 10:17:04 +0000

When working with lengthy PDF documents, bookmarks serve as essential navigation tools that help readers jump directly to specific sections. Whether you're dealing with technical manuals, academic papers, or corporate reports, a well-structured bookmark hierarchy can significantly improve document readability and usability. This article walks through how to manage bookmarks in PDF documents using Python, covering creation, modification, deletion, information retrieval, and expand/collapse control.

Why Manage PDF Bookmarks Programmatically

Adding bookmarks manually in a PDF reader is time-consuming, especially when dealing with batch documents or frequently updated files. Managing bookmarks programmatically offers several advantages:

Batch processing: Generate a consistent bookmark structure across hundreds of documents in a single script run
Precise control: Specify exact jump destinations, styles, and hierarchical relationships
Dynamic updates: Automatically adjust bookmark titles and structure as document content changes
Automation integration: Embed bookmark generation into your document production pipeline

Environment Setup

This article uses the Spire.PDF for Python library to manipulate PDF documents. Install it via pip:

pip install Spire.PDF

Once installed, import the required modules in your script:

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

Creating Bookmarks with Parent-Child Hierarchy

The core concept behind bookmarks is the hierarchical structure. A PDF document can contain multiple top-level bookmarks (parent bookmarks), and each parent can have multiple child bookmarks nested beneath it, forming a tree-like navigation panel.

The key steps for creating bookmarks are: set up the document and pages, draw content on the pages, then point bookmarks to the corresponding locations.

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

doc = PdfDocument()

# Set page margins and size
unitCvtr = PdfUnitConvertor()
margin = PdfMargins()
margin.Top = unitCvtr.ConvertUnits(2.54, PdfGraphicsUnit.Centimeter, PdfGraphicsUnit.Point)
margin.Bottom = margin.Top
margin.Left = unitCvtr.ConvertUnits(3.17, PdfGraphicsUnit.Centimeter, PdfGraphicsUnit.Point)
margin.Right = margin.Left

section = doc.Sections.Add()
section.PageSettings.Margins = margin
section.PageSettings.Size = PdfPageSize.A4()

# Create the first page and draw a title
page = section.Pages.Add()
font_title = PdfTrueTypeFont("Arial", 16.0, PdfFontStyle.Bold, True)
brush = PdfBrushes.get_Black()
format_center = PdfStringFormat(PdfTextAlignment.Center)
page.Canvas.DrawString("PDF Bookmark Demo Document", font_title, brush,
    page.Canvas.ClientSize.Width / 2, 10, format_center)

The code above sets up the basic document framework. PdfUnitConvertor converts units like centimeters into the internal Point unit used by PDF, ensuring precise control over page layout.

Adding Parent Bookmarks

Parent bookmarks are created using the doc.Bookmarks.Add() method, which takes a bookmark title as its parameter and returns a PdfBookmark object. Each bookmark must be associated with a PdfDestination that specifies the target page and position when the bookmark is clicked.

# Draw a chapter title on the page
font_chapter = PdfTrueTypeFont("Arial", 11.0, PdfFontStyle.Bold, True)
y = 60.0
page.Canvas.DrawString("1. Chapter One: Overview", font_chapter, PdfBrushes.get_Blue(), 0.0, y)

# Create a parent bookmark and set the jump destination
dest1 = PdfDestination(page, PointF(0.0, y))
bookmark1 = doc.Bookmarks.Add("1. Chapter One: Overview")
bookmark1.Color = PdfRGBColor(Color.get_SaddleBrown())
bookmark1.DisplayStyle = PdfTextStyle.Bold
bookmark1.Action = PdfGoToAction(dest1)

PdfDestination takes a page object and a coordinate point as arguments. PdfGoToAction binds this destination to the bookmark so that clicking it triggers the navigation. The Color and DisplayStyle properties control how the bookmark appears in the reader's navigation panel, including its text color and font style (bold, italic, etc.).

Adding Child Bookmarks

Child bookmarks are created in a similar way, with one key difference: they must be added to a PdfBookmarkCollection under the parent bookmark, rather than directly to the document's top-level bookmark collection.

# Get the child bookmark collection of the parent bookmark
childCollection = PdfBookmarkCollection(bookmark1)

# Create a child bookmark
page2 = section.Pages.Add()
y2 = 0.0
page2.Canvas.DrawString("1.1. Background", font_chapter, PdfBrushes.get_Brown(), 0.0, y2)

dest_child = PdfDestination(page2, PointF(0.0, y2))
child_bookmark = childCollection.Add("1.1. Background")
child_bookmark.Color = PdfRGBColor(Color.get_Coral())
child_bookmark.DisplayStyle = PdfTextStyle.Italic
child_bookmark.Action = PdfGoToAction(dest_child)

After obtaining the child collection via PdfBookmarkCollection(parentBookmark), calling Add() inserts a child bookmark under that parent. Child bookmarks can have their own independent colors and styles, making it easy to visually distinguish hierarchy levels in the navigation panel.

Saving the Document

Once all bookmarks have been added, save the document:

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

Modifying Existing Bookmarks

For an existing PDF document, you can load it and modify bookmark titles, colors, and styles. This is particularly useful when generating customized documents from templates.

doc = PdfDocument()
doc.LoadFromFile("input.pdf")

# Get the first top-level bookmark
bookmark = doc.Bookmarks[0]

# Modify the title
bookmark.Title = "Modified Bookmark Title"

# Change the color to black
bookmark.Color = PdfRGBColor(Color.get_Black())

# Set the style to bold
bookmark.DisplayStyle = PdfTextStyle.Bold

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

When modifying child bookmarks, you need to traverse the child collection recursively:

def update_child_bookmarks(parent_bookmark):
    children = PdfBookmarkCollection(parent_bookmark)
    for i in range(children.Count):
        child = children.get_Item(i)
        child.Color = PdfRGBColor(Color.get_Blue())
        child.DisplayStyle = PdfTextStyle.Regular
        # Recursively process deeper child bookmarks
        update_child_bookmarks(child)

# Update all child bookmarks under the first bookmark
update_child_bookmarks(doc.Bookmarks[0])

Recursive traversal ensures that every child bookmark is correctly updated, regardless of how deep the bookmark hierarchy goes.

Deleting Bookmarks

Bookmark deletion falls into two scenarios: removing a specific bookmark and clearing all bookmarks.

Deleting a Single Bookmark

Remove a specific top-level bookmark by its index:

doc = PdfDocument()
doc.LoadFromFile("input.pdf")

# Remove the first top-level bookmark (along with all its child bookmarks)
doc.Bookmarks.RemoveAt(0)

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

The RemoveAt() method also deletes all child bookmarks nested under the target bookmark. This is useful when you need to streamline a document's navigation structure.

Clearing All Bookmarks

To remove every bookmark from a document at once:

doc = PdfDocument()
doc.LoadFromFile("input.pdf")

# Clear all bookmarks
doc.Bookmarks.Clear()

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

The Clear() method empties the entire bookmark collection, making it ideal as a cleanup step before regenerating the bookmark structure from scratch.

Retrieving Bookmark Information

In automated workflows, you often need to read existing bookmark information from a PDF document, such as titles, styles, and page numbers.

Getting Bookmark Titles and Styles

doc = PdfDocument()
doc.LoadFromFile("input.pdf")

bookmarks = doc.Bookmarks
results = []

if bookmarks.Count > 0:
    results.append("PDF Bookmarks:")
    for i in range(bookmarks.Count):
        parent = bookmarks.get_Item(i)
        results.append(f"Title: {parent.Title}")
        results.append(f"Style: {parent.DisplayStyle}")

        # Recursively get child bookmarks
        children = PdfBookmarkCollection(parent)
        for j in range(children.Count):
            child = children.get_Item(j)
            results.append(f"  Child Bookmark: {child.Title}")
            results.append(f"  Style: {child.DisplayStyle}")

with open("Bookmarks_Info.txt", "w", encoding="utf-8") as f:
    f.write("\n".join(results))

doc.Close()

Getting the Page Number of a Bookmark

The target page number of a bookmark can be retrieved through the Destination.Page property. Since Pages.IndexOf() returns a zero-based index, you need to add 1 to get the actual page number:

doc = PdfDocument()
doc.LoadFromFile("input.pdf")

bookmark = doc.Bookmarks[0]
page_number = doc.Pages.IndexOf(bookmark.Destination.Page) + 1
print(f"Bookmark page number: {page_number}")

doc.Close()

Controlling Bookmark Expand and Collapse State

When a PDF reader opens a document, the bookmark panel can be either expanded or collapsed. You can control this behavior programmatically.

Expanding or Collapsing All Bookmarks

doc = PdfDocument()
doc.LoadFromFile("input.pdf")

# True expands all bookmarks, False collapses them
doc.ViewerPreferences.BookMarkExpandOrCollapse = True

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

Controlling the Expand State of Specific Bookmarks

If you only need to expand or collapse certain bookmarks, set the ExpandBookmark property on each one individually:

doc = PdfDocument()
doc.LoadFromFile("input.pdf")

# Expand the first bookmark
doc.Bookmarks.get_Item(0).ExpandBookmark = True

# Collapse the second bookmark
doc.Bookmarks.get_Item(1).ExpandBookmark = False

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

This fine-grained control is handy when you want to highlight key sections by keeping their navigation entries expanded, while collapsing less important sections to reduce visual clutter.

Setting the Zoom Level for Bookmark Navigation

When a bookmark is clicked, you can also control the page zoom level. This is useful in scenarios where precise content display matters:

doc = PdfDocument()
doc.LoadFromFile("input.pdf")

bookmarks = doc.Bookmarks
for i in range(bookmarks.Count):
    bookmark = bookmarks.get_Item(i)
    # Set zoom level: 0.5 means 50% zoom
    bookmark.Destination.Zoom = 0.5

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

A zoom value of 0 inherits the reader's current zoom setting, while any value greater than 0 specifies an explicit zoom ratio.

Conclusion

This article covered the full workflow for managing bookmarks in PDF documents using Python, including the following core operations:

Creating bookmarks: Add parent bookmarks via Bookmarks.Add() and child bookmarks via PdfBookmarkCollection
Modifying bookmarks: Update titles, colors, and text styles, with recursive support for child bookmarks
Deleting bookmarks: Use RemoveAt() to delete a specific bookmark, or Clear() to remove all bookmarks
Retrieving information: Read bookmark titles, styles, and page numbers
Controlling expand state: Globally or individually manage bookmark expand/collapse behavior
Setting zoom level: Control the page zoom ratio when a bookmark is activated

These operations can be flexibly combined for practical scenarios such as batch document processing and automated report generation. Once you've mastered bookmark management, you can further explore advanced PDF features like hyperlinks, form fields, and digital signatures.

Python Excel Comment Guide: Add, Edit, Delete, and Format Comments

Allen Yang — Fri, 26 Jun 2026 10:18:24 +0000

When collaborating on Excel data, comments are a common way to communicate. They allow users to attach notes, remarks, or review feedback to cells without altering the original data. Managing Excel comments programmatically enables batch annotation, automatic flagging of data anomalies, and consistent formatting. This article demonstrates how to add, edit, format, and delete comments in Excel files using Python.

Environment Setup

This article uses Spire.XLS for Python to work with Excel files. Install it with the following command:

pip install Spire.XLS

Once installed, import the relevant modules and you are ready to begin.

Adding a Basic Comment

The most straightforward use of comments is attaching a text note to a specific cell. You can set the comment content directly through the Comment property of a cell.

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

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

# Set cell text
sheet.Range["A1"].Text = "Product A"

# Add a comment
sheet.Range["A1"].Comment.Text = "This product has been discontinued; data is for reference only"

# Make the comment visible
sheet.Range["A1"].Comment.Visible = True

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

The Comment.Text property sets plain-text comment content, and the Visible property controls whether the comment is displayed by default. When Visible is set to False, the comment still exists but only appears when the mouse hovers over the cell.

Adding a Comment with Author Information

In multi-person collaboration scenarios, it is useful to distinguish the author of a comment. You can create a comment object using the AddComment() method and then combine the author name with the body text.

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

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

# Get the target cell
cell_range = sheet.Range["C1"]

# Add a comment and set properties
comment = cell_range.AddComment()
comment.Width = 200
comment.Visible = True

# Combine author and body text
author = "Manager Zhang"
text = "This quarter's data has been verified and is ready for publication."
comment.Text = author + ":\n" + text

# Bold the author name
font = workbook.CreateFont()
font.FontName = "Tahoma"
font.KnownColor = ExcelColors.Black
font.IsBold = True
comment.RichText.SetFont(0, len(author), font)

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

The RichText.SetFont() method applies font formatting to a specified range of characters within the comment. The parameters 0 and len(author) define the range from the first character to the end of the author name, so the author name appears in bold, clearly separated from the body text.

Creating Rich Text Comments

When a comment requires different colors or styles to distinguish information hierarchy, you can use rich text formatting.

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

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

# Create fonts with different colors
font_green = workbook.CreateFont()
font_green.FontName = "Arial"
font_green.Size = 11
font_green.KnownColor = ExcelColors.LightGreen

font_blue = workbook.CreateFont()
font_blue.FontName = "Arial"
font_blue.Size = 11
font_blue.KnownColor = ExcelColors.LightBlue

# Set cell and comment
cell_range = sheet.Range["B12"]
cell_range.Text = "Sales Data"
cell_range.RichText.SetFont(0, 16, font_green)

# Set rich text comment
cell_range.Comment.RichText.Text = "Reviewed: Data is correct"
cell_range.Comment.RichText.SetFont(0, 4, font_green)
cell_range.Comment.RichText.SetFont(5, 9, font_blue)

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

The RichText.SetFont(start_index, end_index, font) method allows you to apply different fonts to different segments of the comment text. This is useful when you need to distinguish status labels from detailed descriptions.

Setting Comment Background Color

By modifying the fill properties of a comment, you can set a background color for the comment box to make it more prominent.

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

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

# Add a comment
cell_range = sheet.Range["A1"]
cell_range.Comment.Text = "Important: This data requires verification"

# Set font color
font = workbook.CreateFont()
font.FontName = "Arial"
font.Size = 11
font.KnownColor = ExcelColors.Orange
cell_range.Comment.RichText.SetFont(0, len(cell_range.Comment.Text) - 1, font)

# Set comment background color
cell_range.Comment.Fill.FillType = ShapeFillType.SolidColor
cell_range.Comment.Fill.ForeColor = Color.get_SkyBlue()
cell_range.Comment.Visible = True

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

Once Fill.FillType is set to ShapeFillType.SolidColor, use ForeColor to specify the background color. This approach is useful for marking comment priority or category with color.

Adjusting Comment Position, Size, and Alignment

The position and dimensions of a comment box can be controlled directly through its properties, and text alignment can be set independently.

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

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

# Add a comment
sheet.Range["G5"].Text = "Data Item"
comment = sheet.Range["G5"].Comment
comment.IsVisible = True
comment.Height = 150
comment.Width = 300

# Set comment text
comment.RichText.Text = "Review note:\nThis data was exported from the system and has passed initial validation."

# Set text rotation
comment.TextRotation = TextRotationType.LeftToRight

# Set comment position (relative to the worksheet)
comment.Top = 20
comment.Left = 40

# Set text alignment
comment.VAlignment = CommentVAlignType.Center
comment.HAlignment = CommentHAlignType.Justified

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

Key property descriptions:

Height and Width: Control the pixel dimensions of the comment box
Top and Left: Control the position coordinates of the comment box on the worksheet
VAlignment: Vertical alignment — options include Top, Center, Bottom
HAlignment: Horizontal alignment — options include Left, Center, Right, Justified

Adding an Image Background to a Comment

In addition to solid colors, you can use an image as the background of a comment box, for example to embed a company logo or status icon.

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

workbook = Workbook()
sheet = workbook.Worksheets[0]
sheet.Range["C6"].Text = "Person in Charge"

# Add a comment and set image background
comment = sheet.Range["C6"].AddComment()
image = Stream("Logo.png")
comment.Fill.CustomPicture(image, "logo.png")
comment.Visible = True

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

The Fill.CustomPicture() method accepts an image stream and an image name parameter. The loaded image is used as the background fill for the comment box.

Reading and Editing Existing Comments

For existing Excel files, you can iterate through the comment collection on a worksheet to read or modify comment content.

from spire.xls import *

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

# Read the comment of a specific cell
comment_text = sheet.Range["A1"].Comment.Text
print("Comment:", comment_text)

# Read RTF format of a rich text comment
rtf_text = sheet.Range["A2"].Comment.RichText.RtfText
print("RTF Content:", rtf_text)

workbook.Dispose()

Editing existing comments is equally straightforward — access the comment collection by index and modify its properties:

# Get the first comment and update its content
comment = sheet.Comments[0]
comment.Text = "Comment content updated"

Controlling Comment Visibility

Comments can be individually hidden or shown without deleting them.

from spire.xls import *

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

# Hide a specific comment
sheet.Comments[1].IsVisible = False

# Show a specific comment
sheet.Comments[2].IsVisible = True

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

This is useful when you need to toggle comment visibility for different scenarios, such as hiding review comments before printing or presenting.

Deleting Comments

When a comment is no longer needed, you can remove it from the worksheet.

from spire.xls import *

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

# Delete the second comment
sheet.Comments[1].Remove()

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

The Remove() method permanently deletes the comment from the worksheet's comment collection. To clear all comments, iterate through the sheet.Comments collection and call Remove() on each one.

Conclusion

This article covered the common operations for managing Excel comments in Python, including:

Adding basic text comments and comments with author information
Using rich text formatting to set comments with different colors and styles
Setting comment background colors and image backgrounds
Adjusting comment position, size, and text alignment
Reading, editing, hiding, and deleting existing comments

These operations cover the main scenarios in comment management. Building on these fundamentals, you can further integrate data validation logic to automatically add comments, or batch-process comments across multiple Excel files to build more comprehensive automation workflows.

Manage Excel Worksheets in Python: Create, Copy, Delete, and Rename

Allen Yang — Fri, 26 Jun 2026 10:11:29 +0000

Worksheets are the fundamental units for organizing and separating data in Excel files. A single Excel file typically contains multiple worksheets, each storing a different type of data or presenting a different analytical view. In automation scenarios, it is common to dynamically add, copy, hide, move, and delete worksheets through code. This article demonstrates how to manage worksheets programmatically in Python.

Environment Setup

This article uses Spire.XLS for Python to work with Excel files. This library provides comprehensive APIs for managing worksheet collections, covering the most common worksheet management tasks in automation.

pip install Spire.XLS

Once installed, you can access the relevant APIs through the spire.xls module.

Adding a Worksheet

Adding a worksheet is the most basic operation. Access the Worksheets collection through a Workbook object and call the Add() method with a worksheet name to create a new sheet.

from spire.xls import *

# Create a workbook object
workbook = Workbook()

# Add a new worksheet named "DataSheet"
sheet = workbook.Worksheets.Add("DataSheet")

# Write data to the new worksheet
sheet.Range["A1"].Text = "This is the newly added worksheet"

# Save the file
workbook.SaveToFile("AddWorksheet.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

The Add() method returns the newly created worksheet object, which you can immediately use for writing data and applying formatting. By default, the new worksheet is appended at the end of all existing worksheets.

Copying a Worksheet

There are two scenarios for copying a worksheet: within the same workbook, and across workbooks.

Copying Within the Same Workbook

To copy a worksheet within the same workbook, retrieve the source worksheet's data range and copy it to a new target worksheet:

from spire.xls import *

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

# Get the source worksheet
sourceSheet = workbook.Worksheets[0]

# Create the target worksheet
targetSheet = workbook.Worksheets.Add("CopyOfSource")

# Copy data
sourceRange = sourceSheet.AllocatedRange
targetSheet.CopyFrom(sourceRange, targetSheet, targetSheet.FirstRow, targetSheet.FirstColumn, True)

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

The last parameter of the CopyFrom() method controls whether formatting is also copied. When set to True, data, styles, merged cells, and other formatting are preserved in the copy.

Copying Across Workbooks

Copying across workbooks allows you to transfer the content of a worksheet from one Excel file to another:

from spire.xls import *

# Load the source file
sourceWorkbook = Workbook()
sourceWorkbook.LoadFromFile("Source.xlsx")
srcSheet = sourceWorkbook.Worksheets[0]

# Load the target file
targetWorkbook = Workbook()
targetWorkbook.LoadFromFile("Target.xlsx")

# Add a new worksheet in the target file and copy content
targetSheet = targetWorkbook.Worksheets.Add("ImportedSheet")
targetSheet.CopyFrom(srcSheet)

targetWorkbook.SaveToFile("CopyAcrossWorkbooks.xlsx", ExcelVersion.Version2013)
targetWorkbook.Dispose()
sourceWorkbook.Dispose()

This approach is particularly useful in data consolidation scenarios, such as merging departmental data tables into a single summary file.

Hiding and Showing Worksheets

In certain cases, you may need to hide worksheets that contain auxiliary data or intermediate calculation results, so that only key information is visible to readers. You can control visibility through the Visibility property of a worksheet:

from spire.xls import *

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

# Hide a specific worksheet
workbook.Worksheets["CalcSheet"].Visibility = WorksheetVisibility.Hidden

# Show a previously hidden worksheet
workbook.Worksheets["Report"].Visibility = WorksheetVisibility.Visible

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

The WorksheetVisibility enum provides two values: Hidden and Visible. Hiding a worksheet does not delete its content — the data remains intact but is no longer visible in the Excel interface.

Moving a Worksheet

When the order of worksheets needs to be adjusted, use the MoveWorksheet() method to move a sheet to a specified position:

from spire.xls import *

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

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

# Move it to the third position (index starts at 0)
sheet.MoveWorksheet(2)

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

The MoveWorksheet() method takes an integer parameter representing the target position index. The move operation does not alter the worksheet's content or data — it only changes the order of tabs in the tab bar.

Deleting a Worksheet

When a worksheet is no longer needed, you can remove it from the workbook by index or by name:

from spire.xls import *

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

# Delete a worksheet by index
workbook.Worksheets.RemoveAt(1)

# You can also delete by name
# workbook.Worksheets.Remove("TempSheet")

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

Deletion is irreversible — once executed, the worksheet and all its data are permanently removed. Before performing batch deletions, iterate through all worksheet names first to verify which sheets will be removed.

Setting Worksheet Tab Colors

Assigning colors to worksheet tabs provides a quick visual way to distinguish between different types of data sheets, improving file readability:

from spire.xls import *

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

# Set tab colors for different worksheets
workbook.Worksheets[0].TabColor = Color.get_Red()
workbook.Worksheets[1].TabColor = Color.get_Green()
workbook.Worksheets[2].TabColor = Color.get_LightBlue()

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

The TabColor property accepts a Color object. You can use predefined colors such as Red, Green, and LightBlue, or specify custom RGB values.

Freezing Panes

Freezing panes keeps header rows or columns visible while scrolling, which is a common setting when working with large data tables:

from spire.xls import *

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

sheet = workbook.Worksheets[0]

# Freeze the first row (the area above row 2, column 1 is frozen)
sheet.FreezePanes(2, 1)

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

The FreezePanes() method takes two parameters: a row number and a column number. The area above and to the left of the specified position is frozen. For example, FreezePanes(2, 1) freezes the first row, FreezePanes(1, 2) freezes the first column, and FreezePanes(3, 2) freezes the first two rows and the first column simultaneously.

Getting All Worksheet Names

In automation workflows, you often need to retrieve the names of all worksheets in a file for further processing:

from spire.xls import *

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

# Iterate through and get all worksheet names
for sheet in workbook.Worksheets:
    print(sheet.Name)

workbook.Dispose()

This operation is commonly used to dynamically generate a worksheet list, locate a specific worksheet by name, or perform data validation before batch processing.

Conclusion

This article covered the core operations for managing Excel worksheets in Python, including adding, copying, hiding, moving, and deleting worksheets, as well as setting tab colors and freezing panes. These operations address the most common worksheet management needs in everyday Excel automation.

Key takeaways:

Use Worksheets.Add() to add a new worksheet
Use CopyFrom() to copy worksheet content within the same workbook or across workbooks
The Visibility property controls worksheet display and hiding
MoveWorksheet() adjusts the worksheet order
FreezePanes() sets frozen panes to improve the readability of large data tables

Building on these fundamentals, you can further combine data writing, formatting, and file conversion capabilities to create comprehensive Excel automation workflows.

Adding and Managing Attachments in PDF Documents Using Python

Allen Yang — Thu, 25 Jun 2026 10:03:18 +0000

In everyday document processing, the PDF attachment feature has a wide range of use cases. For instance, bundling a contract with supporting materials in a single PDF file, or attaching relevant data files and images to a technical document. While doing this manually is possible, it becomes a bottleneck when processing large volumes of documents.

Using Python, you can programmatically add, read, and remove PDF attachments efficiently, making it well-suited for integration into automated workflows.

Environment Setup

To work with PDF documents in Python, install the Spire.PDF library:

pip install Spire.PDF

This library provides a complete set of PDF document processing APIs, including attachment management.

Adding Attachments to a PDF Document

There are two common ways to add attachments to a PDF: as document-level attachments (similar to email attachments) and as attachment annotations displayed as clickable icons on the page.

Adding Document-Level Attachments

Document-level attachments appear in the PDF reader's attachment panel and are not directly visible on the page content:

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

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

# Create an attachment object with the file name
attachment = PdfAttachment("data.xlsx")

# Read the file data into the attachment
with open("data.xlsx", "rb") as f:
    attachment.Data = f.read()

# Set the description and MIME type
attachment.Description = "Source data table"
attachment.MimeType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"

# Add the attachment to the document
doc.Attachments.Add(attachment)

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

Key API notes:

PdfAttachment: Represents an attachment object; the constructor parameter is the display name of the attachment
Data property: Used to set the binary data of the attachment
MimeType property: Specifies the MIME type so the reader can identify the file correctly
Attachments.Add(): Adds the attachment to the document's attachment collection

Adding Attachment Annotations

Attachment annotations appear as icons (such as a paperclip or pushpin) on the PDF page, allowing readers to click and open them directly:

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

doc = PdfDocument()
doc.LoadFromFile("input.pdf")
page = doc.Pages[0]

# Read the file data to attach
with open("report.pdf", "rb") as f:
    data = Stream(f.read())

# Create an attachment annotation
bounds = RectangleF(50.0, 100.0, 15.0, 15.0)
annotation = PdfAttachmentAnnotation(bounds, "report.pdf", data)
annotation.Color = PdfRGBColor(Color.get_Teal())
annotation.Icon = PdfAttachmentIcon.Paperclip
annotation.Text = "Attachment: Detailed Report"

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

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

Attachment annotations support various icon styles, including Paperclip, PushPin, Graph, and Tag, allowing you to choose the most appropriate icon based on the content type.

Reading and Extracting Attachments

When you receive a PDF document containing attachments, you may need to inspect the attachment information or extract the files.

Retrieving Attachment Information

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

pdf = PdfDocument()
pdf.LoadFromFile("document_with_attachments.pdf")

# Get the attachment collection
collection = pdf.Attachments

if collection.Count > 0:
    for i in range(collection.Count):
        attachment = collection.get_Item(i)
        print(f"File Name: {attachment.FileName}")
        print(f"Description: {attachment.Description}")
        if attachment.CreationDate:
            print(f"Creation Date: {attachment.CreationDate}")
        print("---")

pdf.Close()

Extracting Attachments to Local Files

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

pdf = PdfDocument()
pdf.LoadFromFile("document_with_attachments.pdf")

collection = pdf.Attachments

# Extract all attachments
for i in range(collection.Count):
    attachment = collection.get_Item(i)
    attachment.Data.Save(attachment.FileName)

# Or extract a single attachment (e.g., the second one)
attachment = collection.get_Item(1)
attachment.Data.Save(attachment.FileName)

pdf.Close()

The attachment.Data.Save() method saves the attachment data directly to a file, automatically using the original file name.

Deleting Attachments

When cleaning up or repackaging a document, you can remove attachments that are no longer needed:

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

doc = PdfDocument()
doc.LoadFromFile("document_with_attachments.pdf")

# Delete all attachments
doc.Attachments.Clear()

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

If you need to remove only specific attachments, you can access them by index and handle them individually, or match them by file name.

Practical Tips

Before adding attachments, make sure to open files in binary mode ("rb"), otherwise data may become corrupted
Setting the correct MIME type helps PDF readers properly identify and handle the attachment content
The Flags property of attachment annotations controls interaction behavior, such as ReadOnly for read-only and Locked to prevent movement
Document-level attachments and attachment annotations can coexist without conflict

Conclusion

This article covered the basic methods of adding, extracting, and removing attachments in PDF documents using Python. These operations can be easily performed through the Spire.PDF API and are well-suited for integration into batch document processing workflows. Building on this foundation, you can combine these techniques with other PDF operations—such as page merging and text extraction—to create more complex document automation solutions.

Combining and Formatting Shapes in PowerPoint Using Python

Allen Yang — Thu, 18 Jun 2026 09:33:53 +0000

In PowerPoint presentations, shapes are fundamental elements for building visual content. By combining multiple shapes together, you can create complex graphical objects; by applying 3D effects and shadows, you can make shapes more vivid and professional. This article demonstrates how to use Python to combine, ungroup, and apply various visual effects to shapes in PowerPoint.

Why Shape Combination and Formatting Matter

When working with PowerPoint presentations, advanced shape operations offer several advantages:

Unified Management: Once multiple shapes are grouped, they can be moved, resized, or copied as a single unit
Visual Enhancement: 3D effects and shadows can elevate the professionalism and appeal of your presentation
Batch Operations: When formatting changes are applied to grouped shapes, all child shapes update synchronously
Template Creation: Programmatically generate standardized presentation templates containing complex graphics

These capabilities are particularly valuable for creating flowcharts, organizational charts, infographics, and other complex visual content.

Environment Setup

First, install the Spire.Presentation for Python library:

pip install Spire.Presentation

This library provides a comprehensive PowerPoint manipulation API that supports shape creation, formatting, grouping, and special effects processing.

Basic Implementation: Grouping Multiple Shapes

Shape grouping is the operation of merging multiple independent shape objects into a single logical unit. The following example demonstrates how to create two shapes and group them together:

from spire.presentation import *

# Create a presentation instance
ppt = Presentation()

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

# Set background image
rect = RectangleF.FromLTRB(0, 0, ppt.SlideSize.Size.Width, ppt.SlideSize.Size.Height)
slide.Shapes.AppendEmbedImageByPath(ShapeType.Rectangle, "bg.png", rect)
slide.Shapes[0].Line.FillFormat.SolidFillColor.Color = Color.get_FloralWhite()

# Create the first shape - Rectangle
rectangle = slide.Shapes.AppendShape(
    ShapeType.Rectangle, 
    RectangleF.FromLTRB(250, 180, 450, 220))
rectangle.Fill.FillType = FillFormatType.Solid
rectangle.Fill.SolidColor.KnownColor = KnownColors.SkyBlue
rectangle.Line.Width = 0.1

# Create the second shape - Ribbon
ribbon = slide.Shapes.AppendShape(
    ShapeType.Ribbon2, 
    RectangleF.FromLTRB(290, 155, 410, 235))
ribbon.Fill.FillType = FillFormatType.Solid
ribbon.Fill.SolidColor.KnownColor = KnownColors.LightPink
ribbon.Line.Width = 0.1

# Add both shapes to a list
arr = []
arr.append(rectangle)
arr.append(ribbon)

# Group the shapes
ppt.Slides[0].GroupShapes(arr)

# Save the document
ppt.SaveToFile("GroupShapes_out.pptx", FileFormat.Pptx2013)
ppt.Dispose()

Result Preview:

Key points to note:

Use the AppendShape method to create different types of shapes
Add the shapes you want to group into a list
Call the GroupShapes method and pass the shape list to complete the grouping
Grouped shapes can be manipulated as a single entity

Applying 3D Effects to Shapes

3D effects can give flat shapes a three-dimensional appearance, enhancing visual impact. The following example shows how to add different 3D effects to shapes:

from spire.presentation import *

# Create a presentation
ppt = Presentation()

# Set background
rect = RectangleF.FromLTRB(0, 0, ppt.SlideSize.Size.Width, ppt.SlideSize.Size.Height)
ppt.Slides[0].Shapes.AppendEmbedImageByPath(ShapeType.Rectangle, "bg.png", rect)
ppt.Slides[0].Shapes[0].Line.FillFormat.SolidFillColor.Color = Color.get_FloralWhite()

# Add the first shape and fill with color
shape1 = ppt.Slides[0].Shapes.AppendShape(
    ShapeType.RoundCornerRectangle, 
    RectangleF.FromLTRB(150, 150, 300, 300))
shape1.Fill.FillType = FillFormatType.Solid
shape1.Fill.SolidColor.KnownColor = KnownColors.SkyBlue

# Initialize 3D effect for shape1 and set properties
effect1 = shape1.ThreeD.ShapeThreeD
effect1.PresetMaterial = PresetMaterialType.Powder  # Material type
effect1.TopBevel.PresetType = BevelPresetType.ArtDeco  # Bevel type
effect1.TopBevel.Height = 4  # Bevel height
effect1.TopBevel.Width = 12  # Bevel width
effect1.BevelColorMode = BevelColorType.Contour  # Bevel color mode
effect1.ContourColor.KnownColor = KnownColors.LightBlue  # Contour color
effect1.ContourWidth = 3.5  # Contour width

# Add the second shape
shape2 = ppt.Slides[0].Shapes.AppendShape(
    ShapeType.Pentagon, 
    RectangleF.FromLTRB(400, 150, 550, 300))
shape2.Fill.FillType = FillFormatType.Solid
shape2.Fill.SolidColor.KnownColor = KnownColors.LightGreen

# Apply different 3D effects to shape2
effect2 = shape2.ThreeD.ShapeThreeD
effect2.PresetMaterial = PresetMaterialType.SoftEdge
effect2.TopBevel.PresetType = BevelPresetType.SoftRound
effect2.TopBevel.Height = 12
effect2.TopBevel.Width = 12
effect2.BevelColorMode = BevelColorType.Contour
effect2.ContourColor.KnownColor = KnownColors.LawnGreen
effect2.ContourWidth = 5

# Save the document
ppt.SaveToFile("Set3DEffectForShape_out.pptx", FileFormat.Pptx2013)
ppt.Dispose()

Result Preview:

Main 3D effect properties include:

PresetMaterial: Preset material types such as powder, soft edge, metal, etc.
TopBevel: Type, height, and width of the top bevel
BevelColorMode: Bevel color mode
ContourColor/ContourWidth: Contour color and width

Ungrouping Shapes

When you need to edit individual shapes within a group separately, you can ungroup them first:

from spire.presentation import *

# Load a document containing grouped shapes
ppt = Presentation()
ppt.LoadFromFile("GroupShapes.pptx")

# Get the grouped shape
groupShape = ppt.Slides[0].Shapes[0] if isinstance(ppt.Slides[0].Shapes[0], GroupShape) else None

# Ungroup the shape
ppt.Slides[0].Ungroup(groupShape)

# Save the document
ppt.SaveToFile("UngroupShapes.pptx", FileFormat.Pptx2013)
ppt.Dispose()

After ungrouping, the original child shapes are restored as independent objects and can be edited individually.

Applying Shadow Effects

In addition to 3D effects, shadows are another commonly used decorative effect for shapes:

from spire.presentation import *

# Create a presentation
ppt = Presentation()

# Add a shape
shape = ppt.Slides[0].Shapes.AppendShape(
    ShapeType.Rectangle, 
    RectangleF.FromLTRB(100, 100, 300, 200))
shape.Fill.FillType = FillFormatType.Solid
shape.Fill.SolidColor.KnownColor = KnownColors.LightBlue

# Set shadow effect
shadow = shape.Effect.D presetShadow
shadow.BlurRadius = 10  # Blur radius
shadow.Distance = 5  # Shadow distance
shadow.Direction = 45  # Shadow direction (angle)
shadow.ColorFormat.Color = Color.get_Gray()  # Shadow color

# Save the document
ppt.SaveToFile("SetShadowEffectForShape.pptx", FileFormat.Pptx2013)
ppt.Dispose()

Additional Shape Formatting Options

Gradient Fill

from spire.presentation import *

# Create a shape
shape = ppt.Slides[0].Shapes.AppendShape(
    ShapeType.Ellipse, 
    RectangleF.FromLTRB(100, 100, 300, 300))

# Set gradient fill
shape.Fill.FillType = FillFormatType.Gradient
shape.Fill.Gradient.GradientStops.Add(0, Color.get_Blue())
shape.Fill.Gradient.GradientStops.Add(1, Color.get_White())
shape.Fill.Gradient.GradientType = GradientStyleType.Horizontal

# Save the document
ppt.SaveToFile("FillShapeWithGradient.pptx", FileFormat.Pptx2013)
ppt.Dispose()

Pattern Fill

# Set pattern fill
shape.Fill.FillType = FillFormatType.Pattern
shape.Fill.Pattern.PatternType = PatternFillType.DiagonalBrick
shape.Fill.Pattern.ForeColor = Color.get_Red()
shape.Fill.Pattern.BackColor = Color.get_Yellow()

Picture Fill

# Fill shape with an image
shape.Fill.FillType = FillFormatType.Picture
shape.Fill.PictureFill.Picture.Url = "texture.jpg"
shape.Fill.PictureFill.FillType = PictureFillType.Stretch

Practical Tips

Batch Grouping Similar Shapes

When you need to group multiple shapes of the same type, you can simplify the code using loops:

# Collect all rectangle shapes
rectangles = []
for shape in slide.Shapes:
    if shape.ShapeType == ShapeType.Rectangle:
        rectangles.append(shape)

# If multiple rectangles are found, group them
if len(rectangles) > 1:
    slide.GroupShapes(rectangles)

Finding and Replacing Shapes Within Groups

You can identify and locate specific shapes using alternative text (Alt Text):

# Set alternative text for a shape
shape.AlternativeText = "MyCustomShape"

# Find shapes by alternative text
for shape in slide.Shapes:
    if shape.AlternativeText == "MyCustomShape":
        # Perform operations
        shape.Fill.SolidColor.KnownColor = KnownColors.Red

Protecting Shapes from Modification

You can lock shapes to prevent accidental modifications:

# Prevent shape modification
shape.Locking.SelectionProtection = True
shape.Locking.PositionProtection = True
shape.Locking.SizeProtection = True

Summary

This article has introduced various methods for performing advanced shape operations in PowerPoint using Python, including:

Grouping multiple shapes into a single object
Applying 3D effects to shapes (materials, bevels, contours)
Ungrouping shapes for individual editing
Adding shadow effects to enhance visual hierarchy
Filling shapes with gradients, patterns, and images
Managing and locating shapes through alternative text

These techniques can help create more professional and engaging presentations, especially for scenarios requiring complex graphic design. Through programmatic processing, you can also batch-generate standardized graphical elements, improving workflow efficiency.

Add Speaker Notes to PowerPoint Slides Using Python

Allen Yang — Thu, 18 Jun 2026 07:44:31 +0000

Speaker notes are an invaluable feature when creating presentations. They allow presenters to add comments, prompts, or detailed explanations beneath each slide—content that remains invisible to the audience during presentation mode but helps speakers organize their thoughts and maintain a smooth delivery pace.

In real-world scenarios, we often need to batch-add notes to multiple slides or extract note information from existing presentations. Manual operations are not only time-consuming but also prone to errors. By automating these tasks with Python, you can complete them efficiently and accurately.

This article demonstrates how to add speaker notes to PowerPoint slides using Python, as well as how to extract and manage existing note content. This approach is particularly useful for scenarios requiring batch processing of presentations, such as preparing training materials or organizing meeting presentations.

Environment Setup

First, install the Spire.Presentation library:

pip install Spire.Presentation

This library provides a comprehensive API for PowerPoint document manipulation, supporting the creation, modification, and reading of various presentation elements, including slide notes.

Adding Speaker Notes to Slides

Basic Workflow

The core steps for adding notes to slides include:

Load or create a PowerPoint document
Get the target slide
Access or create the notes page (NotesSlide)
Set the note text content
Save the document

Here's a complete example showing how to add notes to the first slide:

from spire.presentation import *

# Create a PowerPoint document object
presentation = Presentation()

# Load file from disk
presentation.LoadFromFile("Template_Ppt_1.pptx")

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

# Get the slide's notes page; create one if it doesn't exist
notes_slide = slide.NotesSlide
if notes_slide is None:
    notes_slide = slide.AddNotesSlide()

# Set the note text content
notes_slide.NotesTextFrame.Text = "Speaker notes: Introduce company background and project objectives"

# Save the document
presentation.SaveToFile("AddSpeakerNotes.pptx", FileFormat.Pptx2019)
presentation.Dispose()

Result Preview

In this example, the NotesSlide property is used to access the slide's notes page. If the slide doesn't have a notes page yet, you need to call the AddNotesSlide() method to create one first. Then, set the note text content through the NotesTextFrame.Text property.

Batch-Adding Notes to Multiple Slides

In practical applications, you often need to add different notes to multiple slides. This can be achieved by iterating through the slide collection:

from spire.presentation import *

# Load the presentation
presentation = Presentation()
presentation.LoadFromFile("Training_Material.pptx")

# Define note content for each slide
speaker_notes = [
    "Opening remarks: Welcome everyone to this training session",
    "Key focus: Explain core concepts of Part 1",
    "Demonstrate real-world examples here",
    "Interactive segment: Q&A and discussion",
    "Summarize key points and preview next training session"
]

# Iterate through slides and add notes
for i, slide in enumerate(presentation.Slides):
    if i < len(speaker_notes):
        # Get or create notes page
        notes_slide = slide.NotesSlide
        if notes_slide is None:
            notes_slide = slide.AddNotesSlide()

        # Set note text
        notes_slide.NotesTextFrame.Text = speaker_notes[i]

# Save the document
presentation.SaveToFile("Training_With_Notes.pptx", FileFormat.Pptx2019)
presentation.Dispose()

This method is especially suitable for handling standardized presentation templates, allowing you to quickly add structured notes to an entire slide deck.

Extracting and Managing Speaker Notes

Besides adding notes, you may sometimes need to extract note information from existing presentations for review, backup, or conversion to other formats.

Extracting Notes from a Single Slide

from spire.presentation import *

# Load the presentation
presentation = Presentation()
presentation.LoadFromFile("Presentation_With_Notes.pptx")

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

# Get the notes page
notes_slide = slide.NotesSlide

if notes_slide is not None:
    # Extract notes text frame content
    note_text = notes_slide.NotesTextFrame.Text
    print(f"Notes for slide 1: {note_text}")
else:
    print("This slide has no notes")

presentation.Dispose()

Batch-Extracting Notes from All Slides

For presentations containing multiple slides, you can iterate through all slides, extract their notes, and save them to a text file:

from spire.presentation import *

def save_notes_to_file(filename, notes_list):
    """Save notes list to a text file"""
    with open(filename, "w", encoding="utf-8") as f:
        for note in notes_list:
            f.write(note + "\n")

# Load the presentation
presentation = Presentation()
presentation.LoadFromFile("Conference_Presentation.pptx")

# Store all notes
all_notes = []

# Iterate through all slides
for i, slide in enumerate(presentation.Slides):
    notes_slide = slide.NotesSlide

    if notes_slide is not None:
        note_text = notes_slide.NotesTextFrame.Text
        note_info = f"Slide {i + 1}: {note_text}"
        all_notes.append(note_info)
    else:
        all_notes.append(f"Slide {i + 1}: No notes")

# Save to text file
save_notes_to_file("Extracted_Speaker_Notes.txt", all_notes)

print(f"Extracted {len(all_notes)} note entries in total")
presentation.Dispose()

This example demonstrates how to extract all notes from a presentation and save them to a text file, making it convenient for subsequent review or use as a speaking script.

Deleting and Modifying Notes

In certain situations, you may need to delete or modify existing note content.

Deleting Notes from a Specific Slide

from spire.presentation import *

# Load the presentation
presentation = Presentation()
presentation.LoadFromFile("Presentation.pptx")

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

# Delete notes from this slide
slide.RemoveNotesSlide()

# Save the document
presentation.SaveToFile("Presentation_No_Notes.pptx", FileFormat.Pptx2019)
presentation.Dispose()

Modifying Existing Notes

If you need to modify existing notes, you can directly reset the NotesTextFrame.Text property:

from spire.presentation import *

# Load the presentation
presentation = Presentation()
presentation.LoadFromFile("Presentation.pptx")

# Get the first slide and its notes
slide = presentation.Slides[0]
notes_slide = slide.NotesSlide

if notes_slide is not None:
    # Append or modify note content
    original_text = notes_slide.NotesTextFrame.Text
    notes_slide.NotesTextFrame.Text = original_text + "\n\nAdditional note: Please add the latest data here"

# Save the document
presentation.SaveToFile("Presentation_Updated.pptx", FileFormat.Pptx2019)
presentation.Dispose()

Practical Tips

Formatting Note Text

Note text supports basic formatting. You can add line breaks, paragraphs, and other elements using rich text:

# Use line breaks to separate different paragraphs
notes_slide.NotesTextFrame.Text = "Part 1: Background Introduction\n\nPart 2: Core Content\n\nPart 3: Summary"

Checking Whether Slides Have Notes

When processing large numbers of slides, you can first check which slides already have notes to avoid duplicate operations:

for i, slide in enumerate(presentation.Slides):
    if slide.NotesSlide is not None:
        print(f"Slide {i + 1} already has notes")
    else:
        print(f"Slide {i + 1} needs notes added")

Relationship Between Notes and Export

It's important to note that when exporting PowerPoint to PDF or image formats, speaker notes are not included in the output files by default. This makes notes truly "behind-the-scenes" content, visible only to the presenter.

Summary

This article demonstrated how to add, extract, modify, and delete speaker notes in PowerPoint slides using Python. Through these techniques, you can efficiently manage note information in presentations and improve your presentation creation workflow.

Key takeaways include:

Using the NotesSlide property to access slide notes pages
Creating new notes pages with the AddNotesSlide() method
Setting and retrieving note text using NotesTextFrame.Text
Batch-processing notes across multiple slides
Extracting notes and saving them to external files

These techniques can be applied to various scenarios, such as preparing training materials, managing meeting presentations, and generating speaking scripts. Combined with other PowerPoint automation features, you can build a complete presentation processing workflow.

Add and Edit Content Controls in Word with Python

Allen Yang — Wed, 17 Jun 2026 10:12:13 +0000

In modern document automation scenarios, content controls provide a structured way to create interactive Word documents. Content controls allow developers to embed interactive elements such as dropdown lists, date pickers, and text input fields into documents, enabling the creation of form templates, surveys, and standardized documents.

This article demonstrates how to programmatically add and manage various types of content controls in Word documents using Python and the Spire.Doc library, including combo boxes, text boxes, picture controls, date pickers, and drop-down lists.

Environment Setup

First, install the Spire.Doc for Python library:

pip install Spire.Doc

Spire.Doc is a feature-rich Word document processing library that supports creating, reading, editing, and converting Word documents without requiring Microsoft Word to be installed.

What Are Content Controls

Content controls (also known as Structured Document Tags - SDT) are container elements in Word documents that define regions for specific types of content. They offer several advantages:

Data Validation: Restrict users to input specific formats or select from predefined options
Structured Data: Facilitate subsequent data extraction and processing
User Experience: Provide intuitive interfaces such as dropdown menus and calendar pickers
Document Standardization: Ensure documents follow consistent formatting and standards

Common content control types include:

Combo Box
Text Box
Picture Control
Date Picker
Drop-Down List

Adding Combo Box Content Controls

Combo boxes allow users to select an item from a predefined list or enter custom values. This is particularly useful in scenarios requiring standardized input, such as selecting product names, departments, or categories.

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

# Create document object
document = Document()
section = document.AddSection()

# Add description text
paragraph = section.AddParagraph()
txtRange = paragraph.AppendText("Add Combo Box Content Control: ")
txtRange.CharacterFormat.Italic = True

# Create structured document tag
sd = StructureDocumentTagInline(document)
paragraph.ChildObjects.Add(sd)

# Set control type to combo box
sd.SDTProperties.SDTType = SdtType.ComboBox

# Create combo box and add options
cb = SdtComboBox()
cb.ListItems.Add(SdtListItem("Spire.Doc"))
cb.ListItems.Add(SdtListItem("Spire.XLS"))
cb.ListItems.Add(SdtListItem("Spire.PDF"))

# Apply control properties
sd.SDTProperties.ControlProperties = cb

# Set default display value
rt = TextRange(document)
rt.Text = cb.ListItems[0].DisplayText
sd.SDTContent.ChildObjects.Add(rt)

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

Output:

In the code above, the StructureDocumentTagInline class is used to create inline content controls. By setting SDTType to ComboBox, we specify the control type. The SdtComboBox object manages list items and allows dynamic addition or removal of options.

Adding Text Content Controls

Text controls allow users to input multi-line text, suitable for free-text fields such as addresses, comments, or descriptions.

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

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

# Add description
paragraph = section.AddParagraph()
txtRange = paragraph.AppendText("Add Text Content Control: ")
txtRange.CharacterFormat.Italic = True

# Create text control
sd = StructureDocumentTagInline(document)
paragraph.ChildObjects.Add(sd)
sd.SDTProperties.SDTType = SdtType.Text

# Configure text properties to allow multi-line input
text = SdtText(True)
text.IsMultiline = True
sd.SDTProperties.ControlProperties = text

# Set placeholder text
rt = TextRange(document)
rt.Text = "Enter text here..."
sd.SDTContent.ChildObjects.Add(rt)

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

Output:

The SdtText constructor accepts a boolean parameter that specifies whether multi-line input is allowed. When set to True, users can input long text containing line breaks.

Adding Picture Content Controls

Picture controls allow users to insert and manage images in documents, ideal for scenarios requiring dynamic addition of product images, logos, or signatures.

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

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

paragraph = section.AddParagraph()
txtRange = paragraph.AppendText("Add Picture Content Control: ")
txtRange.CharacterFormat.Italic = True

# Create picture control
sd = StructureDocumentTagInline(document)
paragraph.ChildObjects.Add(sd)
sd.SDTProperties.SDTType = SdtType.Picture

# Load and add image
pic = DocPicture(document)
pic.Width = 100
pic.Height = 100
pic.LoadImage("./Data/logo.png")
sd.SDTContent.ChildObjects.Add(pic)

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

Output:

Picture controls automatically handle image scaling and layout, allowing users to replace or remove images through the control interface.

Adding Date Picker Content Controls

Date pickers provide a calendar interface that enables users to select dates in a standardized format, avoiding inconsistencies in date formatting.

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

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

paragraph = section.AddParagraph()
txtRange = paragraph.AppendText("Add Date Picker Content Control: ")
txtRange.CharacterFormat.Italic = True

# Create date picker
sd = StructureDocumentTagInline(document)
paragraph.ChildObjects.Add(sd)
sd.SDTProperties.SDTType = SdtType.DatePicker

# Configure date format and calendar type
date = SdtDate()
date.CalendarType = CalendarType.Default
date.DateFormat = "yyyy.MM.dd"
date.FullDate = DateTime.get_Now()
sd.SDTProperties.ControlProperties = date

# Set default date
rt = TextRange(document)
rt.Text = "2024.01.15"
sd.SDTContent.ChildObjects.Add(rt)

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

Output:

The SdtDate object allows customization of date format strings, supporting various common date representations such as "yyyy-MM-dd" or "MM/dd/yyyy".

Adding Drop-Down List Content Controls

Unlike combo boxes, drop-down lists only allow users to select from predefined options without manual input. This is suitable for scenarios requiring strict input value restrictions.

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

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

paragraph = section.AddParagraph()
txtRange = paragraph.AppendText("Add Drop-Down List Content Control: ")
txtRange.CharacterFormat.Italic = True

# Create drop-down list
sd = StructureDocumentTagInline(document)
paragraph.ChildObjects.Add(sd)
sd.SDTProperties.SDTType = SdtType.DropDownList

# Add list items
sddl = SdtDropDownList()
sddl.ListItems.Add(SdtListItem("Engineering"))
sddl.ListItems.Add(SdtListItem("Marketing"))
sddl.ListItems.Add(SdtListItem("Human Resources"))
sd.SDTProperties.ControlProperties = sddl

# Set default option
rt = TextRange(document)
rt.Text = sddl.ListItems[0].DisplayText
sd.SDTContent.ChildObjects.Add(rt)

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

Output:

Practical Tips

Locking Content Controls

To prevent users from modifying the structure of content controls, you can lock them:

# Lock control to prevent deletion or modification
sd.SDTProperties.LockContents = True
sd.SDTProperties.LockControl = True

Customizing Control Appearance

You can customize the display style of controls:

# Set control color
sd.SDTProperties.Color = Color.get_LightBlue()

# Set display appearance
sd.SDTProperties.Appearance = SdtAppearance.BoundingBox

Extracting Control Data

Extract values from content controls in existing documents:

# Iterate through all content controls in the document
for sdt in document.GetChildObjects(True, ObjectType.StructureDocumentTagInline):
    tag = sdt if isinstance(sdt, StructureDocumentTagInline) else None
    if tag:
        # Get control type
        control_type = tag.SDTProperties.SDTType
        # Get control content
        content = tag.SDTContent.Text
        print(f"Type: {control_type}, Content: {content}")

Conclusion

Content controls provide powerful interactivity for Word document automation. Using Python and the Spire.Doc library, we can programmatically create and manage various types of content controls, including:

Combo Boxes and Drop-Down Lists: Provide standardized option selection
Text Boxes: Support free-form text input
Picture Controls: Simplify image management
Date Pickers: Ensure consistent date formatting

These controls are particularly useful for creating form templates, contracts, surveys, and standardized reports. By combining different types of content controls appropriately, you can build interactive Word documents that are both aesthetically pleasing and practical, significantly improving document processing efficiency and accuracy.

In real-world projects, it is recommended to select appropriate control types based on specific requirements and consider adding data validation logic to ensure input quality. Additionally, reasonable control layout and clear labeling can greatly enhance user experience.