Migration Guide

This guide covers migrating to the latest simple-resume version. It introduces improved error handling, a new programmatic API, and a consolidated CLI under the simple-resume command.

Who Should Read This

CLI Users (Low Impact): If you use only command-line tools, switch to the new simple-resume generate command and update YAML files.
Programmatic Users (High Impact): If you import simple-resume functions in Python code, update imports and API calls to use the new simple_resume module.
Custom Template Authors (Medium Impact): If you maintain custom Jinja2 templates, minor syntax updates for dictionary access may be required.

Breaking Changes Summary

Component	Previous Behavior	New Requirement	Action Required
YAML Structure	`template` key was inside `config` block.	`template` key is now at root level.	Move `template` key out of `config` block.
Programmatic API	Functions imported from `generate_pdf`, `generate_html`.	Functions now imported from `simple_resume`.	Update import statements, function calls.
Jinja2 Templates	Dictionary access used dot notation.	Dictionary access now uses bracket notation.	Update custom templates to use bracket notation (e.g., `group["items"]`).
Error Handling	Library raised generic exceptions.	Library now has specific exception hierarchy.	Update `try...except` blocks for specific exceptions (optional).
CLI Entry Points	CLI invoked by directly executing Python files.	CLI now invoked through unified `simple-resume` command.	Use `uv run simple-resume generate --format pdf` instead of direct Python file execution.

Quick Migration Example

For CLI Users

YAML File Changes

The template property moved from the config section to the YAML file's root.

Before (v0.0.x):

config:
  template: resume_with_bars
  theme_color: "#0395DE"
  sidebar_color: "#F6F6F6"

After (v0.1.0+):

template: resume_with_bars
config:
  theme_color: "#0395DE"
  sidebar_color: "#F6F6F6"

Command-Line Changes

The commands now use a single entry point.

Before (v0.0.x):

# Old direct Python file execution
uv run python src/simple_resume/generate_pdf.py --data-dir resume_private
uv run python src/simple_resume/generate_html.py --open

After (v0.1.0+):

# Unified CLI command
uv run simple-resume generate --format pdf --data-dir resume_private
uv run simple-resume generate --format html --open

For Programmatic Users

Python API Changes

The API was restructured to provide greater functionality.

Before (v0.0.x):

from simple_resume import generate_pdf as generate_pdf_cli

# Old approach: Call CLI function directly
generate_pdf_cli()

After (v0.1.0+):

from simple_resume import generate_pdf

# New approach: Use the functional API with result objects
result = generate_pdf(name="my_resume", data_dir="resume_private")

if result.is_success():
    print(f"Generated: {result.output_path}")
else:
    print(f"Error: {result.error}")

Batch Processing Example

from simple_resume.shell.session import ResumeSession

with ResumeSession(data_dir="resumes/") as session:
    for resume_name in ["resume_1", "resume_2", "resume_3"]:
        result = session.generate_pdf(resume_name)
        print(f"{resume_name}: {result.status}")

Detailed Migration Steps

Step 1: Update YAML Files

Action: Move the template property from the config block to the root level of YAML files.

Reason: This change separates structural (template) from styling (colors) configuration.

Validation:

# Test your updated YAML files
uv run simple-resume generate --format pdf --data-dir your_dir

Step 2: Update Custom Templates

Action: In custom Jinja2 templates, replace dot notation with bracket notation for dictionary access.

Reason: New data model requires bracket notation for consistency.

Step 3: Update Programmatic Usage

Action: If using simple-resume as a library, migrate code from old CLI-style imports to the new generation API.

Before (v0.0.x):

from simple_resume import generate_pdf as generate_resume_pdf
from simple_resume.shell.runtime.content import get_content

data = get_content("resume.yaml")
pdf_path = generate_resume_pdf(data, "output.pdf")

After (v0.1.0+):

from simple_resume import generate_pdf
from simple_resume.core.resume import Resume

# Option 1: Generate from a file name (recommended)
result = generate_pdf(name="resume", data_dir=".")
if result.is_success():
    print(f"PDF saved to: {result.output_path}")

# Option 2: Generate from a Resume object (advanced)
resume = Resume.from_yaml("resume.yaml")
resume.hydrate()  # Process Markdown and apply the theme
result = resume.to_pdf("output.pdf")

Step 4: Update Error Handling

Action: If catching exceptions from simple-resume, update code to catch new, more specific exceptions.

Before (v0.0.x):

try:
    generate_pdf_cli()
except Exception as e:
    print(f"Error: {e}")

After (v0.1.0+):

from simple_resume.exceptions import (
    ResumeValidationError,
    TemplateRenderError,
    FileOperationError,
)

try:
    result = generate_pdf(name="resume")
    if not result.is_success():
        print(f"Generation failed: {result.error}")
except ResumeValidationError as e:
    print(f"Invalid YAML data: {e}")
except TemplateRenderError as e:
    print(f"Template error: {e}")
except FileOperationError as e:
    print(f"File I/O error: {e}")

Exception Hierarchy:

Simple-ResumeError (base)
├── ResumeValidationError    # Invalid YAML structure
├── TemplateRenderError      # Jinja2 rendering issues
├── FileOperationError       # File not found, permission denied
└── PaletteError             # Color scheme issues

New Features

The v0.1.0 release includes these new features:

Fluent API

Chain operations on Resume objects for more readable and maintainable code.

from simple_resume.core.resume import Resume

resume = (
    Resume.from_yaml("input.yaml")
    .hydrate()
    .apply_palette("Professional Blue")
    .to_pdf("output.pdf")
)

Session Management

The new session management system processes multiple resumes more efficiently with shared configuration, reducing I/O overhead by up to 40% in batch operations.

from simple_resume.shell.session import ResumeSession

with ResumeSession(data_dir="resumes/") as session:
    for name in ["resume_tech", "resume_academic"]:
        result = session.generate_pdf(name)

Rich Result Objects

The generation functions now return detailed result objects.

result = generate_pdf(name="resume")

if result.is_success():
    print(f"Generated: {result.output_path}")
    print(f"  Size: {result.file_size} bytes")
    print(f"  Duration: {result.duration}ms")
else:
    print(f"Failed: {result.error}")
    print(f"  Stage: {result.failed_at}")

Enhanced Color Palette System

Programmatically generate color palettes.

# In your YAML file
config:
  palette:
    source: generator
    type: hcl
    size: 6
    seed: 42
    hue_range: [210, 260]
    luminance_range: [0.35, 0.85]
    chroma: 0.12

See the Color Schemes Guide for more details.

LaTeX Rendering Support

Generate LaTeX documents in addition to HTML and PDF.

config:
  output_mode: latex

uv run simple-resume generate --format pdf --data-dir resumes

Migration Checklist

Use this checklist to track migration progress.

CLI Users

Update all YAML files: move template key to root level.
Test generation with new uv run simple-resume generate command.
Update documentation or scripts referencing old command syntax.
Update dictionary access to bracket notation in custom templates.
Verify output matches expectations.

Programmatic Users

Update import statements to use new simple_resume module.
Replace old CLI function calls with new API functions.
Update error handling to use new specific exception classes.
Use the new session management feature for batch operations if applicable.
Review and update custom template code.
Update tests to verify new API behavior.
Update documentation or comments referencing old API.

Template Authors

Update your custom templates to use bracket notation instead of dot notation for dictionary access.
Test templates with new data model.
Verify all template variables are accessible.
Document template updates.

API Timeline

Version	Status	Notes
v0.0.x	Legacy	Previous version with basic functionality.
v0.1.x	Current	Stable API with modern architecture.
v0.2.x	Future	Planned enhancements and new features.

Recommendation: Use the current stable API for all new development.

Getting Help

If you encounter issues during migration, follow these steps:

Review the Usage Guide and Development Guide.
Search for similar issues on GitHub.
If no solution found, open a new issue or start a discussion.
When reporting a bug, include the following information:
- The version of simple-resume you are using.
- A sanitized sample of your YAML file.
- The error message or a description of the unexpected behavior.
- The steps to reproduce the issue.

Uh oh!

Migration Guide

Migration Guide

Who Should Read This

Breaking Changes Summary

Quick Migration Example

For CLI Users

YAML File Changes

Command-Line Changes

For Programmatic Users

Python API Changes

Batch Processing Example

Detailed Migration Steps

Step 1: Update YAML Files

Step 2: Update Custom Templates

Step 3: Update Programmatic Usage

Step 4: Update Error Handling

New Features

Fluent API

Session Management

Rich Result Objects

Enhanced Color Palette System

LaTeX Rendering Support

Migration Checklist

CLI Users

Programmatic Users

Template Authors

API Timeline

Getting Help

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally