Excel Quote Automation Tool

This repository now follows a Quotr-style quotation architecture in Python.

Current version: 1.2.0

Core stack:

• pandas for tabular data shaping
• xlwings for Excel input/output automation
• pdfme for PDF generation

The product shape is:

• Read one standardized Excel input file
• Build one unified quotation document
• Apply a named visual template
• Export the same quotation to Excel, PDF, HTML, DOCX, and PNG
• Support a simple desktop UI for non-technical users

Reference Direction

This project now uses these local references:

• quotr as the main product and template-system reference
• Invoices-Generator as a lightweight Excel-to-document workflow reference

Gap analysis:

• docs/QUOTR_GAP_ANALYSIS.md

Project Structure

excel_automation/
  app/
    main.py
    ui.py
    config.py
    exceptions.py
    messages.py
    models.py
    validators.py
    quote_service.py
    template_registry.py
    output_utils.py
    excel_service.py
    pdf_service.py
    html_service.py
    docx_service.py
    png_service.py
  docs/
  sample_data/
  templates/
  tests/
  output/
  requirements.txt

Input Contract

The parser now supports multiple real-workbook variations while keeping one unified quote model.

Supported metadata patterns:

• Fixed cells such as B1:B8 with labels in column A
• Row-based label/value pairs such as Customer -> Acme Trading
• English and Chinese field labels for customer info, quote number, dates, remark, and discount

Supported table patterns:

• Auto-detect the worksheet instead of always using the first worksheet
• Auto-detect the header row instead of assuming row 10
• Header aliases such as Product Name, Specification, Qty, Sales Price, 品名, 规格型号, 数量, 单价

Required item columns:

• Item
• Description
• Quantity
• Unit Price

Optional item columns:

• Unit

Layout details and exact supported aliases:

• docs/SUPPORTED_WORKBOOK_LAYOUTS.md

Templates

Named quotation templates:

• simple
• apple

The same quote document can be rendered with different templates.

Quick Start

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python -m app.main --bootstrap
python -m app.main --input sample_data\sample_quote_input.xlsx --analyze-input
python -m app.main --input sample_data\sample_quote_input.xlsx --output output --template simple
python -m app.main --input sample_data\sample_quote_input.xlsx --output output --template apple --pdf --html --docx --png
python -m app.main --ui

Requirements:

• Python environment with the packages in requirements.txt
• Local Microsoft Excel installation for xlwings

Desktop UI

The UI supports:

• Chinese labels and messages
• Input file selection
• Output folder selection
• Template selection
• Excel export
• Optional PDF export
• Optional HTML export
• Optional DOCX export
• Optional PNG export

Input Analysis

Analyze a workbook before export:

python -m app.main --input sample_data\sample_quote_input.xlsx --analyze-input

The analysis reports:

• workbook classification
• selected worksheet
• detected and missing canonical headers
• populated metadata fields
• the main acceptance or rejection reason

Packaging

Recommended packaging command:

.\build.ps1

Keep these beside the executable for delivery:

• templates\quote_template.xlsx
• sample_data\sample_quote_input.xlsx
• sample_data\sample_quote_input_alias_layout.xlsx
• sample_data\sample_quote_input_chinese_layout.xlsx

To clean temporary build and test artifacts before delivery:

.\clean.ps1

Tests

Run tests with:

python -m unittest discover -s tests
python -m pytest -q tests

Run Excel integration tests only when you explicitly want COM-backed coverage:

$env:RUN_EXCEL_INTEGRATION="1"
python -m unittest discover -s tests
python -m pytest -q tests

Notes

• The project uses local files only
• Excel read/write is implemented with xlwings
• PDF export uses pdfme
• The app can export Excel, PDF, HTML, DOCX, and PNG from the same quotation data
• --bootstrap refreshes all supported sample workbook layouts