Python Typer Pydantic Integration Guide

Building command-line interfaces requires robust validation. Typer and Pydantic together create powerful CLI tools. This integration ensures type safety and data validation.

Typer simplifies CLI creation with type hints. Pydantic provides data validation using Python type annotations. Together they offer the best of both worlds.

Why Combine Typer and Pydantic?

Typer excels at creating command-line interfaces quickly. It uses Python type hints to generate CLI options and arguments. However, complex validation needs more power.

Pydantic fills this gap perfectly. It validates data using type annotations. It also handles settings management and environment variables.

The combination creates production-ready CLI applications. You get automatic CLI generation plus robust validation.

Basic Pydantic Model Integration

Let's start with a simple example. We'll create a user registration CLI command. The command will validate input using Pydantic.

import typer
from pydantic import BaseModel, ValidationError, validator
from typing import Optional

# Define Pydantic model for validation
class UserRegistration(BaseModel):
    username: str
    email: str
    age: int
    role: Optional[str] = "user"
    
    @validator('username')
    def username_must_be_valid(cls, v):
        if len(v) < 3:
            raise ValueError('Username must be at least 3 characters')
        return v
    
    @validator('age')
    def age_must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('Age must be positive')
        return v

app = typer.Typer()

@app.command()
def register_user(
    username: str = typer.Argument(..., help="Username for registration"),
    email: str = typer.Argument(..., help="User email address"),
    age: int = typer.Argument(..., help="User age"),
    role: str = typer.Option("user", help="User role")
):
    try:
        # Validate using Pydantic model
        user_data = UserRegistration(
            username=username,
            email=email,
            age=age,
            role=role
        )
        typer.echo(f"User {user_data.username} registered successfully!")
        typer.echo(f"Email: {user_data.email}")
        typer.echo(f"Age: {user_data.age}")
        typer.echo(f"Role: {user_data.role}")
        
    except ValidationError as e:
        typer.echo("Validation errors occurred:", err=True)
        for error in e.errors():
            typer.echo(f"- {error['loc'][0]}: {error['msg']}", err=True)
        raise typer.Exit(code=1)

if __name__ == "__main__":
    app()

This example shows basic Pydantic integration. The UserRegistration model validates all input data. Custom validators ensure business logic compliance.

Settings Management with Pydantic

Pydantic excels at settings management. It can read from environment variables and configuration files. This is perfect for application settings.

import typer
from pydantic import BaseSettings, validator
from typing import List

class AppSettings(BaseSettings):
    database_url: str
    max_connections: int = 10
    allowed_hosts: List[str] = ["localhost"]
    debug: bool = False
    
    @validator('database_url')
    def validate_database_url(cls, v):
        if not v.startswith(('postgresql://', 'sqlite://')):
            raise ValueError('Invalid database URL format')
        return v
    
    class Config:
        env_prefix = "APP_"
        case_sensitive = False

app = typer.Typer()

@app.command()
def show_settings():
    try:
        settings = AppSettings()
        typer.echo("Application Settings:")
        typer.echo(f"Database URL: {settings.database_url}")
        typer.echo(f"Max Connections: {settings.max_connections}")
        typer.echo(f"Allowed Hosts: {', '.join(settings.allowed_hosts)}")
        typer.echo(f"Debug Mode: {settings.debug}")
        
    except Exception as e:
        typer.echo(f"Error loading settings: {e}", err=True)
        raise typer.Exit(code=1)

@app.command()
def start_server(
    port: int = typer.Option(8000, help="Server port"),
    host: str = typer.Option("localhost", help="Server host")
):
    settings = AppSettings()
    typer.echo(f"Starting server on {host}:{port}")
    typer.echo(f"Using database: {settings.database_url}")
    # Server startup logic here

if __name__ == "__main__":
    app()

This settings example uses BaseSettings from Pydantic. It automatically reads environment variables with the APP_ prefix. This is ideal for configuration management.

Advanced Validation Patterns

Complex applications need advanced validation. Pydantic provides powerful validation capabilities. Let's explore some advanced patterns.

import typer
from pydantic import BaseModel, Field, ValidationError
from typing import List, Optional
from datetime import datetime

class ProjectConfig(BaseModel):
    name: str = Field(..., min_length=1, max_length=50)
    version: str = Field(..., regex=r'^\d+\.\d+\.\d+$')
    tags: List[str] = Field(default_factory=list)
    created_at: datetime = Field(default_factory=datetime.now)
    active: bool = True
    
    class Config:
        validate_assignment = True

app = typer.Typer()

@app.command()
def create_project(
    name: str = typer.Argument(..., help="Project name"),
    version: str = typer.Argument(..., help="Project version (semver)"),
    tags: List[str] = typer.Option([], help="Project tags"),
    active: bool = typer.Option(True, help="Is project active")
):
    try:
        config = ProjectConfig(
            name=name,
            version=version,
            tags=tags,
            active=active
        )
        
        typer.echo(f"Project '{config.name}' created successfully!")
        typer.echo(f"Version: {config.version}")
        typer.echo(f"Tags: {', '.join(config.tags) if config.tags else 'None'}")
        typer.echo(f"Active: {config.active}")
        typer.echo(f"Created: {config.created_at}")
        
    except ValidationError as e:
        typer.echo("Configuration validation failed:", err=True)
        for error in e.errors():
            field = " -> ".join(str(loc) for loc in error['loc'])
            typer.echo(f"- {field}: {error['msg']}", err=True)
        raise typer.Exit(code=1)

if __name__ == "__main__":
    app()

This example shows advanced field validation. The Field class provides additional constraints. Regex validation ensures version format compliance.

Error Handling and User Feedback

Good error handling is crucial for CLI tools. Pydantic validation errors need clear presentation. Users should understand what went wrong.

import typer
from pydantic import BaseModel, ValidationError
from typing import List

class TaskCreate(BaseModel):
    title: str
    description: str
    priority: int
    tags: List[str] = []

def validate_task_data(title: str, description: str, priority: int, tags: List[str]):
    try:
        return TaskCreate(
            title=title,
            description=description,
            priority=priority,
            tags=tags
        )
    except ValidationError as e:
        error_messages = []
        for error in e.errors():
            field = error['loc'][0]
            msg = error['msg']
            error_messages.append(f"{field}: {msg}")
        
        raise typer.BadParameter("\n".join(error_messages))

app = typer.Typer()

@app.command()
def create_task(
    title: str = typer.Argument(..., help="Task title"),
    description: str = typer.Argument(..., help="Task description"),
    priority: int = typer.Argument(..., help="Task priority (1-5)"),
    tags: List[str] = typer.Option([], help="Task tags")
):
    task_data = validate_task_data(title, description, priority, tags)
    
    typer.echo(f"Task created: {task_data.title}")
    typer.echo(f"Priority: {task_data.priority}")
    if task_data.tags:
        typer.echo(f"Tags: {', '.join(task_data.tags)}")

if __name__ == "__main__":
    app()

This error handling approach provides clear feedback. The validate_task_data function centralizes validation. It converts Pydantic errors to Typer-compatible exceptions.

Integration with Other Typer Features

Pydantic integrates well with other Typer features. You can combine it with configuration file loading and global options. This creates comprehensive CLI applications.

For configuration management, consider using Python Typer Config File CLI Argument Merging. This approach combines file-based config with command-line arguments.

When building complex applications, Python Typer Global Options with Root Callbacks can help manage shared settings across multiple commands.

For state management between commands, explore Python Typer Global State with Context. This maintains state across command executions.

Testing Your Validation

Testing validated CLI commands is essential. Typer provides testing utilities. Pydantic models make testing straightforward.

import typer
from typer.testing import CliRunner
from pydantic import BaseModel

class TestData(BaseModel):
    input_value: str
    expected_output: str

app = typer.Typer()

@app.command()
def process_data(value: str = typer.Argument(..., help="Value to process")):
    # Simulate data processing
    processed = value.upper()
    typer.echo(f"Processed: {processed}")

def test_process_data():
    runner = CliRunner()
    
    # Test valid input
    result = runner.invoke(app, ["process-data", "hello"])
    assert result.exit_code == 0
    assert "Processed: HELLO" in result.output
    
    # Test with different input
    result = runner.invoke(app, ["process-data", "world"])
    assert result.exit_code == 0
    assert "Processed: WORLD" in result.output

if __name__ == "__main__":
    test_process_data()
    print("All tests passed!")

Testing ensures your validation works correctly. The CliRunner simulates command execution. You can test various input scenarios.

Best Practices for Production

Follow these best practices for production applications. They ensure maintainable and reliable CLI tools.

Use descriptive error messages. Users should understand validation failures. Provide suggestions for correction when possible.

Keep validation logic in Pydantic models. Separate concerns between CLI interface and business logic. This makes testing easier.

Use environment-specific settings. Development, staging, and production need different configurations. Pydantic's BaseSettings handles this well.

Document your CLI commands thoroughly. Typer automatically generates help text. Enhance it with examples and usage scenarios.

Conclusion

Typer and Pydantic integration creates powerful CLI applications. You get automatic CLI generation plus robust validation. This combination scales from simple scripts to complex tools.

Pydantic handles data validation elegantly. Typer creates user-friendly command-line interfaces. Together they ensure data integrity and great user experience.

Start integrating Pydantic with your Typer applications today. You'll build more reliable and maintainable CLI tools. The type safety and validation will save debugging time.

Remember to test your validation thoroughly. Use the patterns shown in this article. Your users will appreciate the clear error messages and robust behavior.