richforms 0.3.0__py3-none-any.whl

richforms/__init__.py

@@ -0,0 +1,15 @@
+from richforms.api import collect_dict, collect_model, edit, edit_model, fill
+from richforms.cli import main
+from richforms.config import FormConfig
+from richforms.serializers import serialize_result
+
+__all__ = [
+    "FormConfig",
+    "edit",
+    "fill",
+    "collect_dict",
+    "collect_model",
+    "edit_model",
+    "main",
+    "serialize_result",
+]

richforms/api.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import warnings
+from collections.abc import Iterable
+from typing import Any, TypeVar, cast
+
+from pydantic import BaseModel
+from rich.console import Console
+
+from richforms.config import FormConfig, Interaction, RichInteraction
+from richforms.drafts import build_draft_path, save_draft_yaml
+from richforms.introspection import build_model_schema
+from richforms.prompts import prompt_for_value
+from richforms.render import (
+    render_editor_view,
+    render_review,
+    render_validation_ledger,
+)
+from richforms.schema import FieldNode, ModelSchema
+from richforms.serializers import Format, serialize_result
+from richforms.state import (
+    copy_initial,
+    get_nested_value,
+    has_nested_value,
+    set_nested_value,
+)
+from richforms.validate import validate_draft
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def fill(
+    model_type: type[T],
+    *,
+    initial: dict[str, Any] | None = None,
+    config: FormConfig | None = None,
+    console: Console | None = None,
+    _path_prefix: str = "",
+    _handle_interrupt: bool = True,
+) -> T:
+    cfg = config or FormConfig()
+    resolved_console = console or cfg.console or Console()
+    interaction: Interaction = cfg.interaction or RichInteraction(resolved_console)
+    schema = build_model_schema(model_type)
+    draft = copy_initial(initial)
+    first_pass = True
+    errors: dict[str, str] = {}
+
+    try:
+        while True:
+            targets = _target_nodes(schema, errors=errors, first_pass=first_pass)
+            for index, node in enumerate(targets, start=1):
+                current_value, has_default = _resolve_default(node=node, draft=draft)
+                display_path = _display_path(node.path, _path_prefix)
+                if cfg.clear_on_step and resolved_console.is_terminal:
+                    resolved_console.clear()
+                cockpit = render_editor_view(
+                    nodes=schema.leaf_nodes,
+                    node=node,
+                    index=index,
+                    total=len(targets),
+                    current_path=display_path,
+                    error=errors.get(node.path),
+                    has_default=has_default,
+                    default_value=current_value,
+                    path_prefix=_path_prefix,
+                    completed_paths=set(
+                        _prefixed_paths(_completed_paths(schema, draft), _path_prefix)
+                    ),
+                    error_paths=set(_prefixed_paths(errors.keys(), _path_prefix)),
+                    console_width=resolved_console.width,
+                )
+                resolved_console.print(cockpit)
+                value = prompt_for_value(
+                    node=node,
+                    interaction=interaction,
+                    console=resolved_console,
+                    default_value=current_value,
+                    has_default=has_default,
+                    prompt_path=display_path,
+                )
+                resolved_console.print()
+                set_nested_value(draft, node.path, value)
+
+            result = validate_draft(model_type, draft)
+            if result.model is not None:
+                resolved_console.print(render_review(result.model))
+                if cfg.confirm_before_return and not interaction.confirm(
+                    "Accept this form submission?", default=True
+                ):
+                    path = interaction.ask(
+                        "Enter a field path to edit (blank to keep current values):",
+                        default="",
+                    )
+                    errors = {path: "Manual edit requested"} if path else {}
+                    first_pass = False
+                    continue
+                return cast(T, result.model)
+
+            errors = _normalize_errors(result.errors, schema)
+            resolved_console.print(
+                render_validation_ledger(_prefixed_error_map(errors, _path_prefix))
+            )
+            first_pass = False
+    except KeyboardInterrupt:
+        if _handle_interrupt:
+            _handle_keyboard_interrupt(
+                cfg=cfg,
+                interaction=interaction,
+                console=resolved_console,
+                model_type=model_type,
+                draft=draft,
+            )
+        raise
+
+
+def edit_model(
+    instance: T,
+    *,
+    config: FormConfig | None = None,
+    console: Console | None = None,
+) -> T:
+    warnings.warn(
+        "richforms.api.edit_model is deprecated; use richforms.api.edit instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return edit(instance, config=config, console=console)
+
+
+def edit(
+    instance: T,
+    *,
+    config: FormConfig | None = None,
+    console: Console | None = None,
+) -> T:
+    return fill(
+        type(instance),
+        initial=instance.model_dump(mode="python"),
+        config=config,
+        console=console,
+    )
+
+
+def collect_model(
+    model_type: type[T],
+    *,
+    initial: dict[str, Any] | None = None,
+    config: FormConfig | None = None,
+    console: Console | None = None,
+    _path_prefix: str = "",
+    _handle_interrupt: bool = True,
+) -> T:
+    warnings.warn(
+        "richforms.api.collect_model is deprecated; use richforms.api.fill instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return fill(
+        model_type,
+        initial=initial,
+        config=config,
+        console=console,
+        _path_prefix=_path_prefix,
+        _handle_interrupt=_handle_interrupt,
+    )
+
+
+def collect_dict(
+    model_type: type[T],
+    *,
+    initial: dict[str, Any] | None = None,
+    config: FormConfig | None = None,
+    console: Console | None = None,
+) -> dict[str, Any]:
+    model = fill(model_type, initial=initial, config=config, console=console)
+    return model.model_dump(mode="python")
+
+
+def serialize_model_result(
+    model: BaseModel, *, format: Format, path: str | None = None
+) -> str | None:
+    from pathlib import Path
+
+    out_path = Path(path) if path else None
+    return serialize_result(model, format=format, path=out_path)
+
+
+def _target_nodes(
+    schema: ModelSchema, *, errors: dict[str, str], first_pass: bool
+) -> list[FieldNode]:
+    if first_pass:
+        return schema.leaf_nodes
+    return [node for node in schema.leaf_nodes if node.path in errors]
+
+
+def _resolve_default(*, node: FieldNode, draft: dict[str, Any]) -> tuple[Any, bool]:
+    if has_nested_value(draft, node.path):
+        return get_nested_value(draft, node.path), True
+    if node.has_default:
+        return node.default, True
+    return None, False
+
+
+def _normalize_errors(errors: dict[str, str], schema: ModelSchema) -> dict[str, str]:
+    if not errors:
+        return {}
+    normalized: dict[str, str] = {}
+    known_paths = schema.by_path
+    for path, message in errors.items():
+        if path in known_paths:
+            normalized[path] = message
+            continue
+        for known in known_paths:
+            if known.startswith(path + "."):
+                normalized[known] = message
+                break
+    return normalized
+
+
+def _completed_paths(schema: ModelSchema, draft: dict[str, Any]) -> list[str]:
+    return [node.path for node in schema.leaf_nodes if has_nested_value(draft, node.path)]
+
+
+def _display_path(path: str, prefix: str) -> str:
+    if not prefix:
+        return path
+    return f"{prefix}.{path}"
+
+
+def _prefixed_paths(paths: Iterable[str], prefix: str) -> list[str]:
+    return [_display_path(path, prefix) for path in paths]
+
+
+def _prefixed_error_map(errors: dict[str, str], prefix: str) -> dict[str, str]:
+    return {_display_path(path, prefix): message for path, message in errors.items()}
+
+
+def _handle_keyboard_interrupt(
+    *,
+    cfg: FormConfig,
+    interaction: Interaction,
+    console: Console,
+    model_type: type[BaseModel],
+    draft: dict[str, Any],
+) -> None:
+    style = cfg.interrupt_message_style
+    if not draft:
+        console.print("Form entry interrupted.", style=style)
+        return
+
+    save_mode = cfg.save_draft_on_interrupt
+    save_path = build_draft_path(model_type.__name__, directory=cfg.draft_directory)
+    should_save = False
+    if save_mode == "always":
+        should_save = True
+    elif save_mode == "prompt":
+        should_save = interaction.confirm(f"Save draft to {save_path}?", default=True)
+
+    if not should_save:
+        console.print("Form entry interrupted. Draft not saved.", style=style)
+        return
+
+    try:
+        save_draft_yaml(draft, path=save_path)
+    except Exception as exc:  # pragma: no cover
+        console.print(f"Form entry interrupted. Failed to save draft: {exc}", style="bold red")
+        return
+
+    console.print(
+        f"Draft saved to {save_path}. Restart with --from-file {save_path}",
+        style=style,
+    )

richforms/cli.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+import typer
+from pydantic import BaseModel
+
+from richforms.api import edit as edit_form
+from richforms.api import fill as fill_form
+from richforms.config import FormConfig
+from richforms.io import load_payload_file
+from richforms.serializers import serialize_result
+
+app = typer.Typer(help="Rich terminal forms powered by Pydantic models.")
+OutputFormat = Literal["json", "yaml"]
+
+
+@app.command(help="Create a new form.")
+def fill(
+    model: Annotated[str, typer.Argument(help="Model path as module:ModelName")],
+    from_file: Annotated[
+        Path | None, typer.Option("--from-file", help="Optional initial JSON/YAML file")
+    ] = None,
+    output: Annotated[Path | None, typer.Option("--output", help="Output file path")] = None,
+    format: Annotated[OutputFormat, typer.Option("--format", help="Output format")] = "json",
+    clear: Annotated[
+        bool,
+        typer.Option("--clear/--no-clear", help="Clear the terminal between each field"),
+    ] = True,
+) -> None:
+    model_type = _load_model_type(model)
+    initial = load_payload_file(from_file) if from_file else None
+    config = FormConfig(clear_on_step=clear)
+    try:
+        result = fill_form(model_type, initial=initial, config=config)
+    except KeyboardInterrupt as exc:
+        typer.echo("Form entry interrupted.", err=True)
+        raise typer.Exit(code=130) from exc
+    _emit_result(result=result, output=output, format=format)
+
+
+@app.command(help="Edit a saved form.")
+def edit(
+    model: Annotated[str, typer.Argument(help="Model path as module:ModelName")],
+    from_file: Annotated[
+        Path, typer.Option("--from-file", help="Input JSON/YAML file", exists=True)
+    ],
+    output: Annotated[Path | None, typer.Option("--output", help="Output file path")] = None,
+    format: Annotated[OutputFormat, typer.Option("--format", help="Output format")] = "json",
+    clear: Annotated[
+        bool,
+        typer.Option("--clear/--no-clear", help="Clear the terminal between each field"),
+    ] = True,
+) -> None:
+    model_type = _load_model_type(model)
+    payload = load_payload_file(from_file)
+    instance = model_type.model_validate(payload)
+    config = FormConfig(clear_on_step=clear)
+    try:
+        result = edit_form(instance, config=config)
+    except KeyboardInterrupt as exc:
+        typer.echo("Form entry interrupted.", err=True)
+        raise typer.Exit(code=130) from exc
+    _emit_result(result=result, output=output, format=format)
+
+
+def main() -> None:
+    app()
+
+
+def _emit_result(*, result: BaseModel, output: Path | None, format: OutputFormat) -> None:
+    payload = serialize_result(result, format=format, path=output)
+    if output:
+        typer.echo(f"Wrote {format} output to {output}")
+        return
+    typer.echo(payload or "")
+
+
+def _load_model_type(model_path: str) -> type[BaseModel]:
+    if ":" not in model_path:
+        raise typer.BadParameter("Model must use module:ModelName format")
+    module_name, _, class_name = model_path.partition(":")
+    module = importlib.import_module(module_name)
+    model_type: Any = getattr(module, class_name, None)
+    if model_type is None:
+        raise typer.BadParameter(f"Model class not found: {class_name}")
+    if not isinstance(model_type, type) or not issubclass(model_type, BaseModel):
+        raise typer.BadParameter(f"{class_name} is not a Pydantic BaseModel")
+    return model_type

richforms/config.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, Protocol
+
+from rich.console import Console
+from rich.prompt import Confirm, Prompt
+
+
+class Interaction(Protocol):
+    def ask(self, prompt: str, default: str | None = None) -> str: ...
+
+    def confirm(self, prompt: str, default: bool = True) -> bool: ...
+
+
+@dataclass(slots=True)
+class ThemeTokens:
+    ink: str = "white"
+    alloy: str = "grey50"
+    paper: str = "white"
+    probe: str = "cyan"
+    caution: str = "yellow"
+    fault: str = "red"
+    verify: str = "green"
+
+
+_PROMPT_PREFIX = "[bold cyan]▸[/bold cyan]"
+
+
+class RichInteraction:
+    def __init__(self, console: Console) -> None:
+        self.console = console
+
+    def ask(self, prompt: str, default: str | None = None) -> str:
+        value = Prompt.ask(f"{_PROMPT_PREFIX} {prompt}", default=default, console=self.console)
+        return value if value is not None else ""
+
+    def confirm(self, prompt: str, default: bool = True) -> bool:
+        return Confirm.ask(f"{_PROMPT_PREFIX} {prompt}", default=default, console=self.console)
+
+
+@dataclass(slots=True)
+class FormConfig:
+    interaction: Interaction | None = None
+    console: Console | None = None
+    theme: ThemeTokens = field(default_factory=ThemeTokens)
+    confirm_before_return: bool = True
+    save_draft_on_interrupt: Literal["prompt", "always", "never"] = "prompt"
+    draft_directory: Path | None = None
+    interrupt_message_style: str = "yellow"
+    clear_on_step: bool = True

richforms/drafts.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any
+
+import yaml
+
+
+def default_draft_directory() -> Path:
+    return Path.cwd() / ".richforms-drafts"
+
+
+def build_draft_path(model_name: str, *, directory: Path | None = None) -> Path:
+    root = directory or default_draft_directory()
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    stem = _safe_model_stem(model_name)
+    return root / f"{stem}-{timestamp}.yaml"
+
+
+def save_draft_yaml(draft: dict[str, Any], *, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with NamedTemporaryFile(
+        mode="w",
+        encoding="utf-8",
+        dir=path.parent,
+        prefix=f".{path.stem}.",
+        suffix=".tmp",
+        delete=False,
+    ) as tmp:
+        yaml.safe_dump(draft, tmp, sort_keys=False)
+        tmp_path = Path(tmp.name)
+    tmp_path.replace(path)
+
+
+def _safe_model_stem(model_name: str) -> str:
+    lowered = model_name.lower()
+    safe = "".join(ch if ch.isalnum() else "-" for ch in lowered)
+    return "-".join(part for part in safe.split("-") if part) or "model"

richforms/example/__init__.py

@@ -0,0 +1,3 @@
+from richforms.example.model import Family, Person
+
+__all__ = ["Family", "Person"]

richforms/example/model.py

@@ -0,0 +1,58 @@
+from pydantic import AnyUrl, BaseModel, Field
+
+
+class Person(BaseModel):
+    name: str = Field(..., description="Full name.", examples=["Ada Lovelace"])
+    age: int = Field(..., ge=0, description="Age in years.", examples=[36])
+    email: str = Field(
+        ...,
+        pattern=r"^[^@]+@[^@]+\.[^@]+$",
+        description="Primary contact email.",
+        examples=["ada@example.com"],
+    )
+    hobbies: list[str] = Field(
+        default_factory=list,
+        description="Optional hobbies.",
+        examples=[["math", "poetry"]],
+    )
+
+
+class Family(BaseModel):
+    family_name: str = Field(..., description="Family surname.", examples=["Lovelace"])
+    persons: list[Person] = Field(
+        ...,
+        min_length=1,
+        description="One or more family members.",
+        examples=[
+            [
+                {
+                    "name": "Ada Lovelace",
+                    "age": 36,
+                    "email": "ada@example.com",
+                    "hobbies": ["math", "poetry"],
+                }
+            ]
+        ],
+    )
+
+
+class Metadata(BaseModel):
+    name: str = Field(
+        ...,
+        title="Name",
+        description="Name of the project.",
+        examples=["richforms"],
+    )
+    repository: AnyUrl = Field(
+        ...,
+        title="Repository",
+        description="Repository URL",
+        examples=["https://github.com/shinybrar/richforms"],
+    )
+    license: str = Field("MIT", title="License", description="SPDX license")
+    version: str = Field(
+        ...,
+        title="Version",
+        description="Version of the project.",
+        examples=["0.1.0"],
+    )

richforms/exceptions.py

@@ -0,0 +1,6 @@
+class RichformsError(Exception):
+    """Base error for richforms."""
+
+
+class SerializationError(RichformsError):
+    """Raised when serialization fails."""

richforms/integrations/__init__.py

@@ -0,0 +1,4 @@
+from richforms.integrations.click import form_callback as click_form_callback
+from richforms.integrations.typer import form_callback as typer_form_callback
+
+__all__ = ["click_form_callback", "typer_form_callback"]

richforms/integrations/click.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from richforms.api import fill
+from richforms.config import FormConfig
+from richforms.io import load_payload_file
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def form_callback(model_type: type[T], *, config: FormConfig | None = None):
+    def _callback(ctx: Any, param: Any, value: Path | str | None) -> T:
+        del ctx, param
+        if value is None:
+            return fill(model_type, config=config)
+        path = value if isinstance(value, Path) else Path(value)
+        payload = load_payload_file(path)
+        return model_type.model_validate(payload)
+
+    return _callback

richforms/integrations/typer.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypeVar
+
+from pydantic import BaseModel
+
+from richforms.config import FormConfig
+from richforms.integrations.click import form_callback as click_form_callback
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def form_callback(model_type: type[T], *, config: FormConfig | None = None):
+    callback = click_form_callback(model_type, config=config)
+
+    def _callback(value: Path | None) -> T:
+        return callback(None, None, value)
+
+    return _callback