A library that allows the editing of content control XML components in .docx files.
Project description
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)
- DO NOT forget to add Poetry to your
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:
- Copy the path listed under
- Change the Python interpreter to the newly created Poetry virtual environment:
CTRL + SHIFT + P
to open the command menu- Type
interpreter
and hitENTER
- 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 theif __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
- Run
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
- If a variable, parameter, or function return has a type of
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
docx_form-1.0.3.tar.gz
(15.4 kB
view hashes)
Built Distribution
docx_form-1.0.3-py3-none-any.whl
(21.5 kB
view hashes)
Close
Hashes for docx_form-1.0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4395f707ddb687ef302a2157289e78d834ad4905c020eddd4222458ea3227bbf |
|
MD5 | 8de1dad2c2cbc1212c4b620298412d4f |
|
BLAKE2b-256 | b023ea8e052ecb5ee07bdb60dac4b16bdd8c867777e5796fea25536017ac8679 |