expense-report-generator

Expense Report Generator

Create professional expense reports from receipt data with automatic categorization and totals.

Features

• Multiple Input Formats: CSV, JSON, or manual entry
• Auto-Categorization: Classify expenses by type
• Receipt Tracking: Link receipts to expenses
• Approval Workflow: Status tracking and approver info
• Policy Compliance: Flag out-of-policy expenses
• PDF Export: Professional formatted reports
• Reimbursement Calculation: Track paid/unpaid amounts

Quick Start

from expense_report import ExpenseReportGenerator

report = ExpenseReportGenerator()

# Set report info
report.set_employee("John Doe", "EMP001", "Engineering")
report.set_period("2024-01-01", "2024-01-31")

# Add expenses
report.add_expense(
    date="2024-01-15",
    description="Client dinner",
    category="Meals",
    amount=125.50,
    receipt="receipt_001.jpg"
)

report.add_expense(
    date="2024-01-18",
    description="Uber to airport",
    category="Transportation",
    amount=45.00
)

# Generate report
report.generate_pdf("expense_report.pdf")

CLI Usage

# From CSV
python expense_report.py --input expenses.csv --employee "John Doe" --output report.pdf

# With date range
python expense_report.py --input data.csv --start 2024-01-01 --end 2024-01-31 -o report.pdf

# Set department and approver
python expense_report.py --input data.csv --employee "Jane Smith" --dept Sales \
    --approver "Bob Manager" -o report.pdf

# With policy limits
python expense_report.py --input data.csv --policy policy.json -o report.pdf

Input Format

CSV Format

date,description,category,amount,receipt,notes
2024-01-15,Client dinner at Restaurant,Meals,125.50,receipt_001.jpg,Met with ABC Corp
2024-01-16,Uber to client site,Transportation,32.00,,
2024-01-17,Office supplies,Supplies,45.99,receipt_002.jpg,
2024-01-18,Flight to NYC,Travel,450.00,flight_confirm.pdf,Project kickoff

JSON Format

{
  "employee": "John Doe",
  "employee_id": "EMP001",
  "department": "Engineering",
  "period": {"start": "2024-01-01", "end": "2024-01-31"},
  "expenses": [
    {
      "date": "2024-01-15",
      "description": "Client dinner",
      "category": "Meals",
      "amount": 125.50,
      "receipt": "receipt_001.jpg"
    }
  ]
}

Policy Configuration

{
  "limits": {
    "Meals": 75,
    "Transportation": 100,
    "Lodging": 250,
    "Supplies": 200
  },
  "requires_receipt": 25,
  "requires_approval": 500,
  "prohibited": ["Alcohol", "Personal items"]
}

API Reference

ExpenseReportGenerator Class

class ExpenseReportGenerator:
    def __init__(self)

    # Report Setup
    def set_employee(self, name: str, employee_id: str = None,
                    department: str = None) -> 'ExpenseReportGenerator'
    def set_period(self, start: str, end: str) -> 'ExpenseReportGenerator'
    def set_approver(self, name: str, title: str = None) -> 'ExpenseReportGenerator'
    def set_project(self, project_name: str, project_code: str = None) -> 'ExpenseReportGenerator'

    # Adding Expenses
    def add_expense(self, date: str, description: str, category: str,
                   amount: float, receipt: str = None, notes: str = None,
                   reimbursable: bool = True) -> 'ExpenseReportGenerator'
    def load_csv(self, filepath: str) -> 'ExpenseReportGenerator'
    def load_json(self, filepath: str) -> 'ExpenseReportGenerator'

    # Policy
    def set_policy(self, policy: Dict) -> 'ExpenseReportGenerator'
    def check_compliance(self) -> List[Dict]

    # Analysis
    def get_summary(self) -> Dict
    def by_category(self) -> Dict[str, float]
    def by_date(self) -> Dict[str, float]
    def get_total(self) -> float

    # Export
    def generate_pdf(self, output: str) -> str
    def generate_html(self, output: str) -> str
    def to_csv(self, output: str) -> str
    def to_json(self, output: str) -> str

Expense Categories

Standard categories:

• Meals: Business meals and entertainment
• Transportation: Taxi, rideshare, rental car, parking
• Travel: Flights, trains, hotels
• Lodging: Hotel, accommodation
• Supplies: Office supplies, equipment
• Communication: Phone, internet
• Professional: Conferences, training, memberships
• Other: Miscellaneous expenses

Report Summary

summary = report.get_summary()
# Returns:
# {
#     "employee": "John Doe",
#     "period": {"start": "2024-01-01", "end": "2024-01-31"},
#     "total_expenses": 1250.50,
#     "expense_count": 15,
#     "categories": {
#         "Meals": 325.00,
#         "Transportation": 180.50,
#         "Travel": 650.00,
#         "Supplies": 95.00
#     },
#     "reimbursable": 1150.50,
#     "non_reimbursable": 100.00,
#     "receipts_attached": 12,
#     "receipts_missing": 3
# }

Policy Compliance

# Set spending limits
report.set_policy({
    "limits": {
        "Meals": 75,      # Per transaction limit
        "Daily_meals": 100  # Daily limit
    },
    "requires_receipt": 25,  # Receipts required above this
    "requires_approval": 500  # Manager approval above this
})

# Check compliance
violations = report.check_compliance()
# Returns:
# [
#     {"expense_id": 3, "type": "over_limit", "category": "Meals",
#      "amount": 125.50, "limit": 75},
#     {"expense_id": 7, "type": "missing_receipt", "amount": 45.00}
# ]

Generated Report Contents

The PDF report includes:

1. Header

   • Company logo (optional)
   • Report title and date range
   • Employee information

2. Summary Section

   • Total amount
   • Category breakdown
   • Reimbursement status

3. Expense Details Table

   • Date, description, category
   • Amount, receipt status
   • Notes

4. Category Charts

   • Pie chart of spending by category
   • Daily spending bar chart

5. Compliance Notes

   • Policy violations (if any)
   • Missing receipts

6. Approval Section

   • Employee signature line
   • Approver signature line
   • Date fields

Example Workflows

Monthly Employee Report

report = ExpenseReportGenerator()
report.set_employee("Sarah Johnson", "EMP042", "Marketing")
report.set_period("2024-02-01", "2024-02-29")
report.set_approver("Mike Director", "VP Marketing")

# Load from tracking spreadsheet
report.load_csv("february_expenses.csv")

# Check policy
violations = report.check_compliance()
if violations:
    print(f"Warning: {len(violations)} policy violations")

# Generate report
report.generate_pdf("sarah_feb_expenses.pdf")
print(f"Total: ${report.get_total():,.2f}")

Project Expense Tracking

report = ExpenseReportGenerator()
report.set_employee("Project Team")
report.set_project("Website Redesign", "PRJ-2024-001")
report.set_period("2024-01-01", "2024-03-31")

# Add project expenses
report.add_expense("2024-01-15", "Design software license", "Software", 299.00)
report.add_expense("2024-02-01", "User testing incentives", "Research", 500.00)
report.add_expense("2024-02-20", "Stock photos", "Creative", 150.00)

summary = report.by_category()
print("Project Expenses by Category:")
for cat, amount in summary.items():
    print(f"  {cat}: ${amount:,.2f}")

Dependencies

• pandas>=2.0.0
• reportlab>=4.0.0
• matplotlib>=3.7.0