Promptantic

An interactive CLI tool for populating Pydantic models using prompt-toolkit.

Read the documentation!

Features

• Interactive prompts for populating Pydantic models
• Rich formatting and syntax highlighting
• Type-aware input with validation
• Autocompletion for paths, timezones, and custom values
• Support for all common Python and Pydantic types
• Nested model support
• Union type handling via selection dialogs
• Sequence input (lists, sets, tuples)
• Customizable styling

Installation

pip install promptantic

Quick Start

from pydantic import BaseModel, Field
from promptantic import ModelGenerator

class Person(BaseModel):
    name: str = Field(description="Person's full name")
    age: int = Field(description="Age in years", gt=0)
    email: str = Field(description="Email address", pattern=r"[^@]+@[^@]+\.[^@]+")

# Create and use the generator
generator = ModelGenerator()
person = await generator.apopulate(Person)
print(person)

Supported Types

Basic Types

• str, int, float, bool, decimal.Decimal
• Constrained types (e.g., constr, conint)
• Enum classes
• Literal types

Complex Types

• list, set, tuple (with nested type support)
• Union types (with interactive type selection)
• Nested Pydantic models

Special Types

• Path (with path autocompletion)
• UUID
• SecretStr (masked input)
• datetime, date, time, timedelta
• ZoneInfo (with timezone autocompletion)
• IPv4Address, IPv6Address, IPv4Network, IPv6Network
• Email addresses (with validation)
• URLs (with validation)

Advanced Usage

Custom Completions

from pydantic import BaseModel, Field
from pathlib import Path

class Config(BaseModel):
    environment: str = Field(
        description="Select environment",
        completions=["development", "staging", "production"]
    )
    config_path: Path = Field(description="Path to config file")  # Has path completion

Nested Models

class Address(BaseModel):
    street: str = Field(description="Street name")
    city: str = Field(description="City name")
    country: str = Field(description="Country name")

class Person(BaseModel):
    name: str = Field(description="Full name")
    address: Address = Field(description="Person's address")

# Will prompt for all fields recursively
person = await ModelGenerator().apopulate(Person)

Union Types

class Student(BaseModel):
    student_id: int

class Teacher(BaseModel):
    teacher_id: str
    subject: str

class Person(BaseModel):
    name: str
    role: Student | Teacher  # Will show selection dialog

# Will prompt for type selection before filling fields
person = await ModelGenerator().apopulate(Person)

Styling

from prompt_toolkit.styles import Style
from promptantic import ModelGenerator

custom_style = Style.from_dict({
    "field-name": "bold #00aa00",  # Green bold
    "field-description": "italic #888888",  # Gray italic
    "error": "bold #ff0000",  # Red bold
})

generator = ModelGenerator(style=custom_style)

Options

generator = ModelGenerator(
    show_progress=True,        # Show field progress
    allow_back=True,          # Allow going back to previous fields
    retry_on_validation_error=True  # Retry on validation errors
)

Error Handling

from promptantic import ModelGenerator, PromptanticError

try:
    result = await ModelGenerator().apopulate(MyModel)
except KeyboardInterrupt:
    print("Operation cancelled by user")
except PromptanticError as e:
    print(f"Error: {e}")

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Built with prompt-toolkit and Pydantic.