docx-properties 0.2.0

Library for reading and editing properties in Word documents

docx_properties

docx_properties is a Python library designed for reading, editing, and managing custom and core metadata properties in Microsoft Word .docx documents. It allows developers to programmatically interact with properties such as title, subject, author, and custom-defined metadata fields.

Features

• Custom Properties:
  • Read, update, and filter custom properties in Word documents.
  • Add new custom properties or modify existing ones.
• Core Properties:
  • Access core document properties like title, subject, creator, and revision number.
• Field Updates:
  • Automatically update fields in Word documents (Windows only, requires pywin32).
• Command-Line Interface (CLI):
  • Quickly manage document properties without writing Python code.

Installation

Install the library using pip:

pip install docx_properties

For Windows users who require field updating functionality:

pip install pywin32

Usage

Python API

The library provides an easy-to-use API for interacting with Word document properties.

Example: Setting a Custom Property

You can use the set_custom_property method to add or update custom properties in a Word document.

from docx_properties import DocxProperties

# Open the Word document
doc = DocxProperties("example.docx")

# Set or update a custom property
property_name = "ApprovalStatus"
property_value = "Approved"

# Add the custom property to the document
success = doc.set_custom_property(property_name, property_value)

if success:
    print(f"The custom property '{property_name}' was successfully set to '{property_value}'.")
else:
    print(f"Failed to set the custom property '{property_name}'.")

Example: Setting Multiple Properties

You can set multiple properties by calling set_custom_property multiple times.

# Set multiple custom properties
doc.set_custom_property("ApprovalStatus", "Approved")
doc.set_custom_property("Version", 2.1)
doc.set_custom_property("ReviewedBy", "John Doe")

Example: Boolean and Numeric Properties

The library supports various data types for custom properties, such as strings, integers, floats, and booleans.

# Boolean property
doc.set_custom_property("IsConfidential", True)

# Numeric property
doc.set_custom_property("DocumentID", 12345)

---

CLI Usage

The library also includes a command-line interface (CLI) for quickly managing properties.

Setting a Custom Property via CLI

docxprop set-custom example.docx ApprovalStatus Approved

---

Field Updates (Windows Only)

If you need to update fields in your Word document (e.g., updating a table of contents or other dynamic fields), use the update_fields method. This functionality requires pywin32 and is only available on Windows.

# Update fields in the document
if doc.update_fields():
    print("Fields were successfully updated.")
else:
    print("Field updating failed. Ensure pywin32 is installed.")

---

Advanced Features

Filtering Properties

You can filter custom properties by type and value.

# Get all boolean custom properties with the value False
false_properties = doc.filter_custom_properties(filter_type="boolean", filter_value=False)

for name, prop in false_properties.items():
    print(f"Property: {name}, Value: {prop.value}")

Reading Core Properties

Access core metadata such as the document title, creator, and modification date.

core_properties = doc.get_core_properties()
for name, prop in core_properties.items():
    print(f"Core Property: {name}, Value: {prop.value} (Type: {prop.type})")

---

License

This project is licensed under the MIT License.