docx-form

docx-form

API Documentation | PyPi Page

Description

This package allows you to easily modify the values of content controls & form fields in .docx files with Python.

Supported Content Controls

• Plain Text
• Rich Text
• Drop Down List
• Combo Box
• Date Picker
• Check Box

Supported Form Fields (To-Do)

• Text
• Drop Down
• Check Box

Installation

• Install Python (minimum version: 3.10.6)
  • Warning: Python 3.11 breaks some dependencies as of 10/28/2022. This warning will be removed when this is no longer the case.
• In a terminal, run: pip install docx-form

Usage

The file ./docx_form_tests/test.docx wil be used for the following guide.

• Create a new python file example.py
• Import docx-form:

from docx_form import DocxForm

• Initialize a DocxForm instance:

...
full_path = 'path/to/docx/file/test.docx'
document = DocxForm(full_path)

• Print the content controls:

...
document.print_all_content_controls_and_form_fields()

• View the console output & make note of the indexes:

0: RichTextContentControl | id: -1012910137 | text: Rich Text Content Control
1: RichTextContentControl | id: -1135860421 | text: Another Rich Text Content Control
2: PlainTextContentControl | id: -132710284 | text: Plain Text Content Control
3: PlainTextContentControl | id: 28152470 | text: Another Plain Text Content Control
4: CheckBoxContentControl | id: -1942055255 | text: ☐
5: CheckBoxContentControl | id: -635946620 | text: ☒
6: ComboBoxContentControl | id: 199831773 | text: Combo t Option 1
7: ComboBoxContentControl | id: -1984237200 | text: Choose an item.
8: DropDownListContentControl | id: -827207619 | text: Drop-Down Content Control
9: DropDownListContentControl | id: 2026666311 | text: Another Drop-Down Content Control
10: DatePickerContentControl | id: 645172330 | text: 9/6/2022
11: DatePickerContentControl | id: 539787165 | text: 9/7/2022

Note: The Content Controls are listed starting from the top-left of the document going from left to right on each line of the document all the way to the bottom.

• Edit the second Rich Text Content Control:

...
# Import type for proper intellisense in your editor/IDE
from docx_form.content_controls import RichTextContentControl
...
rich_text_control: RichTextContentControl = document.content_control_forms_and_form_fields[1]
rich_text_control.set_text("The example worked!")

• Save the file:

...
# Note: This will overwrite the original file
document.save()

• If document.print_all_content_controls_and_form_fields() is run again:

...
1: RichTextContentControl | id: -1135860421 | text: The example worked!
...

• Full File:

from docx_form import DocxForm
from docx_form.content_controls import RichTextContentControl

# Create a DocxForm instance
full_path = "path/to/docx/file/test.docx"
document = DocxForm(full_path)

# Kept for reference
# document.print_all_content_controls_and_form_fields()

# Edit the second Rich Text content control
rich_text_control: RichTextContentControl = (
    document.content_control_forms_and_form_fields[1]
)
rich_text_control.set_text("The example worked!")

# Note: This will overwrite the original file
document.save()

Examples

The file ./docx_form_tests/test.docx wil be used for the following examples.

Plain Text

from docx_form import DocxForm
from docx_form.content_controls import PlainTextContentControl

# Create a DocxForm instance
full_path = "path/to/docx/file/test.docx"
document = DocxForm(full_path)

# Kept for reference
# document.print_all_content_controls_and_form_fields()

# Edit the content control (remember the console output)
content_control: PlainTextContentControl = (
    document.content_control_forms_and_form_fields[2]
)
content_control.set_text("Plain text edit")

# Note: This will overwrite the original file
document.save()

Check Box

from docx_form import DocxForm
from docx_form.content_controls import CheckBoxContentControl

# Create a DocxForm instance
full_path = "path/to/docx/file/test.docx"
document = DocxForm(full_path)

# Kept for reference
# document.print_all_content_controls_and_form_fields()

# Edit the content control (remember the console output)
content_control: CheckBoxContentControl = (
    document.content_control_forms_and_form_fields[4]
)
content_control.set_check_box(True)

# Note: This will overwrite the original file
document.save()

Combo Box

from docx_form import DocxForm
from docx_form.content_controls import ComboBoxContentControl

# Create a DocxForm instance
full_path = "path/to/docx/file/test.docx"
document = DocxForm(full_path)

# Kept for reference
# document.print_all_content_controls_and_form_fields()

# Edit the content control (remember the console output)
content_control: ComboBoxContentControl = (
    document.content_control_forms_and_form_fields[6]
)
content_control.print_options()
"""
Output:
0: Display Value = "None" || Value = "Choose an item."
1: Display Value = "Combo Box Option 1" || Value = "Combo Box Option 1"
2: Display Value = "Combo Box Option 2" || Value = "Combo Box Option 2"
"""
content_control.set_text(2)

# Note: This will overwrite the original file
document.save()

Drop Down List

from docx_form import DocxForm
from docx_form.content_controls import DropDownListContentControl

# Create a DocxForm instance
full_path = "path/to/docx/file/test.docx"
document = DocxForm(full_path)

# Kept for reference
# document.print_all_content_controls_and_form_fields()

# Edit the content control (remember the console output)
content_control: DropDownListContentControl = (
    document.content_control_forms_and_form_fields[8]
)
content_control.print_options()
"""
Output:
0: Display Value = "None" || Value = "Choose an item."
1: Display Value = "Drop-Down Content Control" || Value = "Drop-Down Content Control"
"""
content_control.set_option(0)

# Note: This will overwrite the original file
document.save()

Date Picker

from datetime import datetime
from docx_form import DocxForm
from docx_form.content_controls import DatePickerContentControl

# Create a DocxForm instance
full_path = "path/to/docx/file/test.docx"
document = DocxForm(full_path)

# Kept for reference
# document.print_all_content_controls_and_form_fields()

# Edit the content control (remember the console output)
content_control: DatePickerContentControl = (
    document.content_control_forms_and_form_fields[10]
)
print(content_control.date_format) # Output: "M/d/yyyy"
new_date = datetime(1999, 12, 31)
content_control.set_date(new_date)

# Note: This will overwrite the original file
document.save()

Setup For Contribution

Requirements:

• Python (minimum version: 3.10.6)
  • Warning: Python 3.11 breaks some dependencies as of 10/28/2022. This warning will be removed when this is no longer the case.
• Poetry
  • DO NOT forget to add Poetry to your PATH (step 3)

Environment Setup

The following will be done in Visual Studio Code on a Windows machine:

• Open a terminal in the repository's root
• Run poetry install
• Run poetry env info
  • Copy the path listed under Virtualenv > Executable:
• Change the Python interpreter to the newly created Poetry virtual environment:
  • CTRL + SHIFT + P to open the command menu
  • Type interpreter and hit ENTER
  • Select + Enter interpreter path...
  • Paste the path to the virtual environment
  • Hit ENTER
• Open ./docx_form/docx_form.py (This is the root file, so do any local testing within the if __name__ == "__main__": scope)
• Click the Run button in the top-right of the editor (assuming the Python Extension is installed)
  • If no errors are thrown, you are ready to execute locally and using poetry!
• Open a Git Bash terminal in the repository's root
  • Run curl -o- https://raw.githubusercontent.com/tapsellorg/conventional-commits-git-hook/master/scripts/install.sh | sh
    • Here is the repository for the git hook: conventional-commits-git-hook
  • Run git init
  • You now have the git hook installed to ensure proper commit messages
    • Follow these guidelines for commit messages

Code Style Guide

• Do your best to follow PEP8 Guidelines
• ALL code must have Type Hints
  • If a variable, parameter, or function return has a type of Any, it WILL NOT be accepted