API Reference

Public API

wizdantic.wizard.run_wizard

run_wizard(
    model_class: type[_ModelT],
    *,
    console: Console | None = None,
    title: str | None = None,
    show_summary: bool = True,
) -> _ModelT

Run an interactive wizard and return a populated model instance.

This is a convenience wrapper around Wizard(...).run().

Parameters:

Name	Type	Description	Default
model_class	type[_ModelT]	The Pydantic model class to populate.	required
console	Console | None	Rich console for output. A new one is created if omitted.	None
title	str | None	Heading displayed at the top of the wizard.	None
show_summary	bool	Show a summary table after collection. Defaults to True.	True

wizdantic.wizard.Wizard

Bases: Generic[_ModelT]

Walks the user through each field of a Pydantic model, collecting and validating values interactively via Rich prompts.

Parameters:

Name	Type	Description	Default
model_class	type[_ModelT]	The Pydantic model class to populate.	required
console	Console | None	Rich console for output. A new one is created if omitted.	None
title	str | None	Heading displayed at the top of the wizard.	None
show_summary	bool	Show a summary table after collection. Defaults to True.	True

print_aborted

print_aborted(dep: DoExceptParams) -> None

Print a clean abort message when the user interrupts the wizard.

print_summary

print_summary(model: BaseModel) -> None

Print a Rich table summarizing all collected field values.

run

run() -> _ModelT

Execute the wizard and return a validated model instance.

Raises WizardAborted if the user presses Ctrl+C at any point.

wizdantic.lore.WizardLore dataclass

Annotation metadata for controlling wizard behavior on a field.

Attach to a field via typing.Annotated alongside pydantic's Field:

name: Annotated[str, Field(description="Hunter name"), WizardLore(section="Identity")]

Parameters:

Name	Type	Description	Default
section	str | None	Group this field under a named heading in the wizard.	None
hint	str | None	Display text shown dim after the label. When provided, it replaces any auto-generated format hint (e.g. (comma-separated)).	None
parser	Callable[[str], Any] | None	Custom callable (str) -> T used instead of TypeAdapter for this field. Any exception raised by the parser is caught, displayed, and the prompt retried.	None

wizdantic.console.WizardConsole

Bases: Console

Rich Console subclass that uses prompt_toolkit for input.

Replaces the default input() call with a prompt_toolkit PromptSession, which provides arrow-key line editing, input history via up/down, and reverse-i-search (Ctrl+R) out of the box. Rich's Prompt.ask and Confirm.ask call console.input() internally, so swapping in this subclass gives every wizard prompt proper terminal editing for free.

input

input(
    prompt: object = "",
    *,
    markup: bool = True,
    emoji: bool = True,
    password: bool = False,
    stream: Any = None,
) -> str

Prompt for input using prompt_toolkit instead of builtin input().

Rich renders the prompt text (with markup and emoji) to the terminal, then this method hands off to prompt_toolkit for the actual keystroke handling. Password prompts fall back to getpass since prompt_toolkit prompt with is_password=True would conflict with Rich's rendering.

Parameters:

Name	Type	Description	Default
prompt	object	The prompt text (may contain Rich markup).	''
markup	bool	Whether to interpret Rich markup in the prompt.	True
emoji	bool	Whether to interpret emoji codes in the prompt.	True
password	bool	Whether to mask input (delegates to getpass).	False
stream	Any	Optional input stream override.	None

Exceptions

wizdantic.exceptions.WizardAborted

Bases: Buzz

Raised when the user aborts the wizard with a keyboard interrupt.

Callers that need to distinguish a clean abort from other errors can catch this exception specifically. The message is always a short, human-readable explanation suitable for display in a terminal.

wizdantic.exceptions.UnsupportedFieldType

Bases: Buzz, TypeError

Raised at Wizard construction time when a field's type cannot be prompted for.

This covers multi-type unions (e.g. str | int) and non-frozen BaseModel items in sets. Inherits from TypeError for backward compatibility with code that catches TypeError from field validation.

Lore utilities

wizdantic.lore.extract_section

extract_section(field_info: FieldInfo) -> str | None

Find the wizard section for a field by scanning its Annotated metadata for a WizardLore instance.

wizdantic.lore.extract_hint

extract_hint(field_info: FieldInfo) -> str | None

Find the user-supplied hint for a field by scanning its Annotated metadata for a WizardLore instance.

wizdantic.lore.extract_parser

extract_parser(
    field_info: FieldInfo,
) -> Callable[[str], Any] | None

Find the custom parser for a field by scanning its Annotated metadata for a WizardLore instance.

Type introspection utilities

wizdantic.type_utils.unwrap_optional

unwrap_optional(annotation: Any) -> Any | None

Detect Optional[T] (or T | None) and return the inner type.

Returns the unwrapped inner type if the annotation is optional, or None if it is not. Callers typically unwrap first so they can inspect or validate the inner type independently while still supporting None as a valid value.

wizdantic.type_utils.unwrap_list

unwrap_list(annotation: Any) -> Any | None

Detect list[T] and return the item type.

Returns the item type if the annotation is a parameterized list, str if it is a bare list, or None if the annotation is not a list.

wizdantic.type_utils.unwrap_tuple

unwrap_tuple(
    annotation: Any,
) -> tuple[list[Any], bool] | None

Detect tuple[T, ...] or tuple[T1, T2, ...] and return item types.

Returns a two-element tuple of (item_types, is_homogeneous):

• For homogeneous tuple[T, ...]: ([T], True)
• For fixed-length tuple[T1, T2, T3]: ([T1, T2, T3], False)
• For bare tuple: ([str], True)
• For non-tuples: None

Parameters:

Name	Type	Description	Default
annotation	Any	The type annotation to inspect.	required

wizdantic.type_utils.unwrap_set

unwrap_set(annotation: Any) -> Any | None

Detect set[T] and return the item type.

Returns the item type if the annotation is a parameterized set, str if it is a bare set, or None if the annotation is not a set.

wizdantic.type_utils.unwrap_dict

unwrap_dict(annotation: Any) -> tuple[Any, Any] | None

Detect dict[K, V] and return the key and value types.

Returns (key_type, value_type) if the annotation is a parameterized dict, (str, str) for a bare dict, or None if it is not a dict.

wizdantic.type_utils.unwrap_literal

unwrap_literal(annotation: Any) -> tuple[Any, ...] | None

Detect Literal["a", "b", ...] and return the allowed values.

Returns a tuple of the literal values, or None if the annotation is not a Literal.

wizdantic.type_utils.is_unsupported_union

is_unsupported_union(annotation: Any) -> bool

Detect multi-type unions that wizdantic cannot prompt for.

Optional[T] (i.e. T | None) is supported and returns False. Any other union of two or more concrete types (e.g. str | int) returns True because there is no way to know which branch to prompt for.