undefined

undefined

undefined

undefined

from docxtpl import DocxTemplate, InlineImage
from docx.shared import Mm, Inches

print("docxtpl installed successfully!")

undefined

"""
Basic template rendering with variable substitution.
"""
from docxtpl import DocxTemplate
from typing import Dict, Any
from pathlib import Path

def render_simple_template(
    template_path: str,
    output_path: str,
    context: Dict[str, Any]
) -> None:
    """
    Render a template with simple variable substitution.

    Args:
        template_path: Path to .docx template
        output_path: Path for output document
        context: Dictionary of values to substitute

    Template syntax:
        {{ variable_name }} - Simple variable
        {{ object.property }} - Nested property
    """
    # Load template
    template = DocxTemplate(template_path)

    # Render with context
    template.render(context)

    # Save output
    template.save(output_path)
    print(f"Document saved to {output_path}")


def create_sample_letter(output_path: str) -> None:
    """Create a sample letter using template rendering."""

    # First, create a simple template (normally you'd have this prepared)
    # Template content would have: {{ recipient_name }}, {{ date }}, etc.

    context = {
        "recipient_name": "John Smith",
        "recipient_title": "Director of Operations",
        "company_name": "Acme Corporation",
        "street_address": "123 Business Ave",
        "city_state_zip": "New York, NY 10001",
        "date": "January 17, 2026",
        "subject": "Project Proposal",
        "salutation": "Dear Mr. Smith",
        "body_paragraph_1": """
            We are pleased to submit our proposal for the infrastructure
            upgrade project. Our team has extensive experience in similar
            projects and we are confident we can deliver exceptional results.
        """.strip(),
        "body_paragraph_2": """
            The attached documents outline our approach, timeline, and
            budget estimates. We would welcome the opportunity to discuss
            this proposal at your convenience.
        """.strip(),
        "closing": "Sincerely",
        "sender_name": "Jane Doe",
        "sender_title": "Project Manager"
    }

    # Render template
    render_simple_template("letter_template.docx", output_path, context)

**Nested Object Access:**
```python
"""
Access nested objects and complex data structures in templates.
"""
from docxtpl import DocxTemplate
from dataclasses import dataclass, asdict
from typing import List, Dict, Optional
from datetime import date

@dataclass
class Address:
    """Address data structure."""
    street: str
    city: str
    state: str
    zip_code: str
    country: str = "USA"

    @property
    def full_address(self) -> str:
        return f"{self.street}\n{self.city}, {self.state} {self.zip_code}"


@dataclass
class Contact:
    """Contact information."""
    name: str
    email: str
    phone: str
    title: Optional[str] = None


@dataclass
class Company:
    """Company data structure."""
    name: str
    address: Address
    contacts: List[Contact]
    industry: str
    website: str

    def to_dict(self) -> Dict:
        """Convert to dictionary for template rendering."""
        return {
            "name": self.name,
            "address": asdict(self.address),
            "contacts": [asdict(c) for c in self.contacts],
            "industry": self.industry,
            "website": self.website
        }


def render_with_nested_data(
    template_path: str,
    output_path: str,
    company: Company
) -> None:
    """
    Render template with nested data structures.

    Template syntax for nested access:
        {{ company.name }}
        {{ company.address.street }}
        {{ company.contacts[0].email }}
    """
    template = DocxTemplate(template_path)

    context = {
        "company": company.to_dict(),
        "generated_date": date.today().strftime("%B %d, %Y")
    }

    template.render(context)
    template.save(output_path)

undefined

"""
Use loops to render lists, tables, and repeated content.
"""
from docxtpl import DocxTemplate
from typing import List, Dict, Any
from dataclasses import dataclass
from decimal import Decimal

@dataclass
class LineItem:
    """Invoice line item."""
    description: str
    quantity: int
    unit_price: Decimal
    discount: Decimal = Decimal("0")

    @property
    def subtotal(self) -> Decimal:
        return self.quantity * self.unit_price * (1 - self.discount / 100)


@dataclass
class Invoice:
    """Invoice data structure."""
    invoice_number: str
    date: str
    due_date: str
    client_name: str
    client_address: str
    items: List[LineItem]
    tax_rate: Decimal = Decimal("8.5")
    notes: str = ""

    @property
    def subtotal(self) -> Decimal:
        return sum(item.subtotal for item in self.items)

    @property
    def tax_amount(self) -> Decimal:
        return self.subtotal * self.tax_rate / 100

    @property
    def total(self) -> Decimal:
        return self.subtotal + self.tax_amount

    def to_context(self) -> Dict[str, Any]:
        """Convert to template context."""
        return {
            "invoice_number": self.invoice_number,
            "date": self.date,
            "due_date": self.due_date,
            "client_name": self.client_name,
            "client_address": self.client_address,
            "items": [
                {
                    "description": item.description,
                    "quantity": item.quantity,
                    "unit_price": f"${item.unit_price:.2f}",
                    "discount": f"{item.discount}%" if item.discount else "",
                    "subtotal": f"${item.subtotal:.2f}"
                }
                for item in self.items
            ],
            "subtotal": f"${self.subtotal:.2f}",
            "tax_rate": f"{self.tax_rate}%",
            "tax_amount": f"${self.tax_amount:.2f}",
            "total": f"${self.total:.2f}",
            "notes": self.notes
        }


def render_invoice(
    template_path: str,
    output_path: str,
    invoice: Invoice
) -> None:
    """
    Render invoice template with line items.

    Template syntax for loops:
        {%tr for item in items %}
        {{ item.description }} | {{ item.quantity }} | {{ item.unit_price }}
        {%tr endfor %}

    Note: {%tr %} is for table rows, {%p %} for paragraphs
    """
    template = DocxTemplate(template_path)
    context = invoice.to_context()
    template.render(context)
    template.save(output_path)


def render_list_document(
    template_path: str,
    output_path: str,
    items: List[str],
    title: str
) -> None:
    """
    Render document with bullet list.

    Template syntax for paragraph loops:
        {%p for item in items %}
        - {{ item }}
        {%p endfor %}
    """
    template = DocxTemplate(template_path)

    context = {
        "title": title,
        "items": items,
        "item_count": len(items)
    }

    template.render(context)
    template.save(output_path)

Template syntax:
    {%p for dept in departments %}
    Department: {{ dept.name }}
    {%p for emp in dept.employees %}
    - {{ emp.name }} ({{ emp.role }})
    {%p endfor %}
    {%p endfor %}
"""
template = DocxTemplate(template_path)

context = {
    "company_name": "TechCorp",
    "departments": departments
}

template.render(context)
template.save(output_path)

undefined

"""
Use conditionals to include or exclude content based on data.
"""
from docxtpl import DocxTemplate
from typing import Dict, Any, Optional
from dataclasses import dataclass
from enum import Enum

class ContractType(Enum):
    FULL_TIME = "full_time"
    PART_TIME = "part_time"
    CONTRACTOR = "contractor"


class ConfidentialityLevel(Enum):
    STANDARD = "standard"
    HIGH = "high"
    RESTRICTED = "restricted"


@dataclass
class EmployeeContract:
    """Employee contract data."""
    employee_name: str
    position: str
    department: str
    start_date: str
    contract_type: ContractType
    salary: float
    bonus_eligible: bool
    stock_options: Optional[int] = None
    confidentiality_level: ConfidentialityLevel = ConfidentialityLevel.STANDARD
    probation_period_months: int = 3
    remote_work_allowed: bool = False
    relocation_package: bool = False

    def to_context(self) -> Dict[str, Any]:
        """Convert to template context with conditional flags."""
        return {
            "employee_name": self.employee_name,
            "position": self.position,
            "department": self.department,
            "start_date": self.start_date,
            "salary": f"${self.salary:,.2f}",

            # Contract type flags for conditionals
            "is_full_time": self.contract_type == ContractType.FULL_TIME,
            "is_part_time": self.contract_type == ContractType.PART_TIME,
            "is_contractor": self.contract_type == ContractType.CONTRACTOR,
            "contract_type_display": self.contract_type.value.replace("_", " ").title(),

            # Benefit flags
            "bonus_eligible": self.bonus_eligible,
            "has_stock_options": self.stock_options is not None,
            "stock_options": self.stock_options,

            # Additional terms
            "confidentiality_level": self.confidentiality_level.value,
            "is_high_confidentiality": self.confidentiality_level in [
                ConfidentialityLevel.HIGH,
                ConfidentialityLevel.RESTRICTED
            ],
            "probation_period_months": self.probation_period_months,
            "remote_work_allowed": self.remote_work_allowed,
            "relocation_package": self.relocation_package
        }


def render_contract(
    template_path: str,
    output_path: str,
    contract: EmployeeContract
) -> None:
    """
    Render contract with conditional sections.

    Template syntax for conditionals:
        {% if is_full_time %}
        Full-time benefits section...
        {% endif %}

        {% if bonus_eligible %}
        Bonus clause...
        {% else %}
        Standard compensation only.
        {% endif %}

        {% if is_high_confidentiality %}
        Additional NDA requirements...
        {% endif %}
    """
    template = DocxTemplate(template_path)
    context = contract.to_context()
    template.render(context)
    template.save(output_path)


def render_with_conditions(
    template_path: str,
    output_path: str,
    data: Dict[str, Any]
) -> None:
    """
    Render template with various conditional patterns.

    Supported conditional patterns:
        {% if condition %} ... {% endif %}
        {% if condition %} ... {% else %} ... {% endif %}
        {% if condition %} ... {% elif other %} ... {% else %} ... {% endif %}
        {% if value > 100 %} ... {% endif %}
        {% if value in list %} ... {% endif %}
    """
    template = DocxTemplate(template_path)
    template.render(data)
    template.save(output_path)

Template example:
    Performance Score: {{ score }}

    {% if score >= 90 %}
    OUTSTANDING PERFORMANCE
    {% elif score >= 75 %}
    MEETS EXPECTATIONS
    {% elif score >= 60 %}
    NEEDS IMPROVEMENT
    {% else %}
    PERFORMANCE PLAN REQUIRED
    {% endif %}

    {% if has_warnings %}
    Warnings:
    {%p for warning in warnings %}
    - {{ warning }}
    {%p endfor %}
    {% endif %}
"""
template = DocxTemplate(template_path)

# Add computed flags to context
score = performance_data.get("score", 0)
context = {
    **performance_data,
    "performance_level": (
        "Outstanding" if score >= 90 else
        "Meets Expectations" if score >= 75 else
        "Needs Improvement" if score >= 60 else
        "Below Expectations"
    ),
    "has_warnings": len(performance_data.get("warnings", [])) > 0
}

template.render(context)
template.save(output_path)

undefined

"""
Generate tables dynamically from data.
"""
from docxtpl import DocxTemplate
from typing import List, Dict, Any
import pandas as pd

def render_data_table(
    template_path: str,
    output_path: str,
    headers: List[str],
    rows: List[List[Any]],
    table_title: str = ""
) -> None:
    """
    Render a simple data table.

    Template structure:
        {{ table_title }}

        | Header 1 | Header 2 | Header 3 |
        |----------|----------|----------|
        {%tr for row in rows %}
        | {{ row[0] }} | {{ row[1] }} | {{ row[2] }} |
        {%tr endfor %}
    """
    template = DocxTemplate(template_path)

    # Convert rows to list of dicts for easier template access
    row_dicts = []
    for row in rows:
        row_dict = {f"col{i}": val for i, val in enumerate(row)}
        row_dicts.append(row_dict)

    context = {
        "table_title": table_title,
        "headers": headers,
        "rows": row_dicts,
        "column_count": len(headers)
    }

    template.render(context)
    template.save(output_path)


def render_pandas_table(
    template_path: str,
    output_path: str,
    df: pd.DataFrame,
    title: str = ""
) -> None:
    """
    Render a pandas DataFrame as a table.

    Template:
        {%tr for row in data %}
        {%tc for cell in row %}{{ cell }}{%tc endfor %}
        {%tr endfor %}
    """
    template = DocxTemplate(template_path)

    # Convert DataFrame to list of dicts
    headers = df.columns.tolist()
    data = df.values.tolist()

    context = {
        "title": title,
        "headers": headers,
        "data": data,
        "row_count": len(data),
        "col_count": len(headers)
    }

    template.render(context)
    template.save(output_path)


def render_grouped_table(
    template_path: str,
    output_path: str,
    grouped_data: Dict[str, List[Dict]]
) -> None:
    """
    Render table with grouped rows and subtotals.

    Template:
        {%tr for group_name, items in groups.items() %}
        {{ group_name }} ({{ items|length }} items)
        {%tr for item in items %}
        | {{ item.name }} | {{ item.value }} |
        {%tr endfor %}
        Subtotal: {{ group_subtotals[group_name] }}
        {%tr endfor %}
    """
    template = DocxTemplate(template_path)

    # Calculate subtotals
    subtotals = {}
    for group, items in grouped_data.items():
        subtotals[group] = sum(item.get("value", 0) for item in items)

    context = {
        "groups": grouped_data,
        "group_subtotals": subtotals,
        "total": sum(subtotals.values())
    }

    template.render(context)
    template.save(output_path)


class TableBuilder:
    """
    Builder for complex table structures.
    """

    def __init__(self):
        self.headers: List[str] = []
        self.rows: List[Dict] = []
        self.footer_row: Dict = {}
        self.title: str = ""

    def set_title(self, title: str) -> 'TableBuilder':
        """Set table title."""
        self.title = title
        return self

    def set_headers(self, headers: List[str]) -> 'TableBuilder':
        """Set column headers."""
        self.headers = headers
        return self

    def add_row(self, **kwargs) -> 'TableBuilder':
        """Add a data row."""
        self.rows.append(kwargs)
        return self

    def add_rows_from_dicts(self, rows: List[Dict]) -> 'TableBuilder':
        """Add multiple rows from list of dicts."""
        self.rows.extend(rows)
        return self

    def add_rows_from_dataframe(self, df: pd.DataFrame) -> 'TableBuilder':
        """Add rows from DataFrame."""
        self.headers = df.columns.tolist()
        self.rows = df.to_dict('records')
        return self

    def set_footer(self, **kwargs) -> 'TableBuilder':
        """Set footer row (e.g., totals)."""
        self.footer_row = kwargs
        return self

    def auto_calculate_footer(self, columns: List[str], operation: str = "sum") -> 'TableBuilder':
        """Auto-calculate footer values."""
        for col in columns:
            values = [row.get(col, 0) for row in self.rows if isinstance(row.get(col), (int, float))]
            if operation == "sum":
                self.footer_row[col] = sum(values)
            elif operation == "avg":
                self.footer_row[col] = sum(values) / len(values) if values else 0
            elif operation == "count":
                self.footer_row[col] = len(values)

        return self

    def to_context(self) -> Dict[str, Any]:
        """Convert to template context."""
        return {
            "table_title": self.title,
            "headers": self.headers,
            "rows": self.rows,
            "footer": self.footer_row,
            "has_footer": bool(self.footer_row),
            "row_count": len(self.rows)
        }

    def render(self, template_path: str, output_path: str) -> None:
        """Render to document."""
        template = DocxTemplate(template_path)
        template.render(self.to_context())
        template.save(output_path)

undefined

"""
Insert images into templates with proper sizing.
"""
from docxtpl import DocxTemplate, InlineImage
from docx.shared import Mm, Inches, Cm
from pathlib import Path
from typing import Optional, Union
from io import BytesIO
import requests

def add_image_to_template(
    template_path: str,
    output_path: str,
    image_path: str,
    context: dict,
    width: Optional[Union[Mm, Inches, Cm]] = None,
    height: Optional[Union[Mm, Inches, Cm]] = None
) -> None:
    """
    Add an image to a template.

    Template syntax:
        {{ image }}

    Args:
        template_path: Path to template
        output_path: Path for output
        image_path: Path to image file
        context: Additional context data
        width: Image width (optional)
        height: Image height (optional)
    """
    template = DocxTemplate(template_path)

    # Create InlineImage
    image = InlineImage(
        template,
        image_path,
        width=width,
        height=height
    )

    # Add image to context
    context["image"] = image

    template.render(context)
    template.save(output_path)


def add_image_from_url(
    template: DocxTemplate,
    url: str,
    width: Optional[Mm] = None
) -> InlineImage:
    """
    Create InlineImage from URL.

    Args:
        template: DocxTemplate instance
        url: Image URL
        width: Desired width

    Returns:
        InlineImage object
    """
    response = requests.get(url)
    response.raise_for_status()

    image_stream = BytesIO(response.content)

    return InlineImage(
        template,
        image_stream,
        width=width
    )


def render_document_with_images(
    template_path: str,
    output_path: str,
    data: dict,
    images: dict
) -> None:
    """
    Render document with multiple images.

    Template:
        Company Logo: {{ logo }}

        Product Images:
        {% for product in products %}
        {{ product.name }}: {{ product.image }}
        {% endfor %}
    """
    template = DocxTemplate(template_path)

    # Process images
    context = data.copy()

    for key, image_info in images.items():
        if isinstance(image_info, str):
            # Simple path
            context[key] = InlineImage(template, image_info, width=Mm(50))
        elif isinstance(image_info, dict):
            # Dict with path and dimensions
            context[key] = InlineImage(
                template,
                image_info["path"],
                width=image_info.get("width"),
                height=image_info.get("height")
            )

    template.render(context)
    template.save(output_path)


class ImageHandler:
    """
    Handle images for template rendering.
    """

    def __init__(self, template: DocxTemplate):
        self.template = template
        self._images: dict = {}

    def add_image(
        self,
        key: str,
        source: Union[str, BytesIO],
        width: Optional[int] = None,
        height: Optional[int] = None,
        unit: str = "mm"
    ) -> 'ImageHandler':
        """
        Add an image to the handler.

        Args:
            key: Context key for the image
            source: File path or BytesIO stream
            width: Width in specified units
            height: Height in specified units
            unit: Unit type ('mm', 'inches', 'cm')
        """
        # Convert units
        if unit == "mm":
            w = Mm(width) if width else None
            h = Mm(height) if height else None
        elif unit == "inches":
            w = Inches(width) if width else None
            h = Inches(height) if height else None
        elif unit == "cm":
            w = Cm(width) if width else None
            h = Cm(height) if height else None
        else:
            w = h = None

        self._images[key] = InlineImage(
            self.template,
            source,
            width=w,
            height=h
        )

        return self

    def add_image_from_url(
        self,
        key: str,
        url: str,
        width: int = 50,
        unit: str = "mm"
    ) -> 'ImageHandler':
        """Add image from URL."""
        response = requests.get(url)
        response.raise_for_status()

        image_stream = BytesIO(response.content)

        return self.add_image(key, image_stream, width=width, unit=unit)

    def get_context(self) -> dict:
        """Get images as context dictionary."""
        return self._images.copy()