form-filler（表格填充者）

Form Filler

Fill PDF forms programmatically with structured data.

Features

• Field Detection: Auto-detect form fields
• Multiple Field Types: Text, checkbox, dropdown, radio
• Data Sources: JSON, CSV, dictionary input
• Batch Filling: Fill multiple forms from data file
• Field Mapping: Map data keys to field names
• Flatten Option: Convert to non-editable PDF
• Form Info: List all fields and their types

Quick Start

from form_filler import FormFiller

filler = FormFiller()

# Load form
filler.load("application_form.pdf")

# Fill fields
filler.fill({
    "name": "John Doe",
    "email": "john@example.com",
    "date": "2024-01-15",
    "agree": True  # Checkbox
})

# Save filled form
filler.save("filled_form.pdf")

CLI Usage

# Fill from JSON data
python form_filler.py --input form.pdf --data data.json --output filled.pdf

# List form fields
python form_filler.py --input form.pdf --list-fields

# Fill from CSV (batch)
python form_filler.py --input form.pdf --batch data.csv --output-dir filled/

# Flatten filled form
python form_filler.py --input form.pdf --data data.json --flatten --output filled.pdf

# With field mapping
python form_filler.py --input form.pdf --data data.json --mapping mapping.json -o filled.pdf

API Reference

FormFiller Class

class FormFiller:
    def __init__(self)

    # Loading
    def load(self, filepath: str) -> 'FormFiller'

    # Field Operations
    def list_fields(self) -> List[Dict]
    def get_field_info(self, field_name: str) -> Dict
    def get_field_value(self, field_name: str) -> Any

    # Filling
    def fill(self, data: Dict) -> 'FormFiller'
    def fill_field(self, name: str, value: Any) -> 'FormFiller'
    def fill_from_json(self, filepath: str) -> 'FormFiller'
    def fill_from_csv_row(self, row: Dict) -> 'FormFiller'

    # Field Mapping
    def set_mapping(self, mapping: Dict[str, str]) -> 'FormFiller'

    # Output
    def save(self, filepath: str, flatten: bool = False) -> str
    def flatten(self) -> 'FormFiller'

    # Batch Processing
    def batch_fill(self, input_form: str, data_file: str,
                  output_dir: str) -> List[str]

Field Types

Text Fields

filler.fill({
    "first_name": "John",
    "last_name": "Doe",
    "address": "123 Main St"
})

Checkboxes

filler.fill({
    "agree_terms": True,
    "subscribe": False
})

Radio Buttons

filler.fill({
    "gender": "male",  # Value of selected option
    "payment_method": "credit_card"
})

Dropdowns

filler.fill({
    "country": "USA",
    "state": "California"
})

Field Discovery

fields = filler.list_fields()
# Returns:
# [
#     {"name": "first_name", "type": "text", "required": True},
#     {"name": "agree_terms", "type": "checkbox", "value": False},
#     {"name": "country", "type": "dropdown", "options": ["USA", "Canada", "UK"]}
# ]

Field Mapping

Map data keys to form field names:

filler.set_mapping({
    "fname": "first_name",     # data key -> form field
    "lname": "last_name",
    "addr": "address_line_1"
})

filler.fill({
    "fname": "John",           # Uses mapping
    "lname": "Doe"
})

Batch Filling

From CSV

# CSV format:
# first_name,last_name,email
# John,Doe,john@example.com
# Jane,Smith,jane@example.com

filler.batch_fill(
    input_form="application.pdf",
    data_file="applicants.csv",
    output_dir="filled_forms/"
)
# Creates: filled_forms/application_0.pdf, application_1.pdf, ...

From JSON Array

# JSON format:
# [
#     {"first_name": "John", "last_name": "Doe"},
#     {"first_name": "Jane", "last_name": "Smith"}
# ]

filler.batch_fill(
    input_form="form.pdf",
    data_file="data.json",
    output_dir="output/"
)

Dependencies

• PyMuPDF>=1.23.0
• pillow>=10.0.0
• pandas>=2.0.0