nicegui-autoform 0.1.0__py3-none-any.whl

nicegui_autoform/__init__.py

@@ -0,0 +1,48 @@
+"""Render a NiceGUI web form from a command line interface.
+
+Point :class:`AutoForm` at a CLI you already have -- a cyclopts ``App``, a click
+``Command``, a ``typer.Typer``, an ``argparse.ArgumentParser``, or a plain
+dataclass or annotated function -- and it builds a form from that CLI's own
+parameter metadata and calls the same function on submit.
+
+    from nicegui import ui
+    from nicegui_autoform import AutoForm
+
+    AutoForm(app, command="train")
+    ui.run()
+"""
+
+from .adapters import Adapter, adapters, build_spec, register_adapter
+from .form import AutoForm
+from .spec import (
+    MISSING,
+    CommandSpec,
+    ContainerSpec,
+    ExcludeFromAutoform,
+    ParamSpec,
+    WidgetKind,
+)
+from .validate import collect_errors
+from .values import from_widget, to_widget
+from .widgets import choose_widget
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MISSING",
+    "Adapter",
+    "AutoForm",
+    "CommandSpec",
+    "ContainerSpec",
+    "ExcludeFromAutoform",
+    "ParamSpec",
+    "WidgetKind",
+    "__version__",
+    "adapters",
+    "build_spec",
+    "choose_widget",
+    "collect_errors",
+    "from_widget",
+    "register_adapter",
+    "to_widget",
+]

nicegui_autoform/_compat.py

@@ -0,0 +1,51 @@
+"""Version shims for the optional CLI frameworks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .spec import MISSING
+
+#: Params Typer injects into every app unless ``add_completion=False``.
+TYPER_INJECTED_PARAMS = frozenset({"install_completion", "show_completion"})
+
+
+def click_default(param: Any) -> Any:
+    """A click parameter's declared default, normalised to :data:`MISSING`.
+
+    Read straight off ``param.default`` rather than through
+    ``param.get_default(ctx)``: Typer subclasses its own vendored copy of click,
+    so a ``click.Context`` built from the installed click is not the context a
+    ``TyperOption`` expects, and on some click versions the mismatch silently
+    yields UNSET for a parameter that plainly has a default.
+
+    click 8.5 reports an unset default as ``Sentinel.UNSET`` where older
+    versions report ``None``. ``None`` is a legal default, so the two stay
+    distinguishable wherever click gives us enough to tell them apart.
+    """
+    default = getattr(param, "default", None)
+    if callable(default):
+        # click allows a zero-argument callable as a default.
+        try:
+            default = default()
+        except Exception:
+            return MISSING
+    return MISSING if _is_click_unset(default) else default
+
+
+def _is_click_unset(value: Any) -> bool:
+    if value is None:
+        return False
+    sentinel = _click_unset_sentinel()
+    if sentinel is not None and value is sentinel:
+        return True
+    # Fall back to a structural check so an unknown click release still works.
+    return type(value).__name__ == "Sentinel" and repr(value) == "Sentinel.UNSET"
+
+
+def _click_unset_sentinel() -> Any:
+    try:
+        from click import core
+    except ImportError:  # pragma: no cover - click is an optional extra
+        return None
+    return getattr(core, "UNSET", None)

nicegui_autoform/_introspect.py

@@ -0,0 +1,99 @@
+"""Typing helpers shared by the adapters.
+
+These answer the questions every adapter has to ask of a type hint: what is the
+scalar type underneath, is it a collection, what are its choices.
+"""
+
+from __future__ import annotations
+
+import enum
+import types
+from collections.abc import Sequence
+from typing import Annotated, Any, Literal, Union, get_args, get_origin
+
+from .spec import ExcludeFromAutoform
+
+_COLLECTION_ORIGINS = (list, set, frozenset, tuple, Sequence)
+
+
+def unwrap_annotated(hint: Any) -> Any:
+    """Strip ``Annotated[...]`` wrappers down to the underlying type."""
+    while get_origin(hint) is Annotated:
+        hint = get_args(hint)[0]
+    return hint
+
+
+def annotated_metadata(hint: Any) -> tuple[Any, ...]:
+    """Every piece of ``Annotated`` metadata, outermost wrapper first."""
+    meta: list[Any] = []
+    while get_origin(hint) is Annotated:
+        meta.extend(hint.__metadata__)
+        hint = get_args(hint)[0]
+    return tuple(meta)
+
+
+def has_exclude_marker(hint: Any) -> bool:
+    return any(
+        m is ExcludeFromAutoform or isinstance(m, ExcludeFromAutoform)
+        for m in annotated_metadata(hint)
+    )
+
+
+def strip_optional(hint: Any) -> Any:
+    """Reduce ``X | None`` / ``Optional[X]`` to ``X``.
+
+    A union of several real types reduces to its first member, which is what the
+    original autoform did and what a single form field can meaningfully offer.
+    """
+    if get_origin(hint) in (Union, types.UnionType):
+        args = [a for a in get_args(hint) if a is not type(None)]
+        if args:
+            return args[0]
+    return hint
+
+
+def is_collection(hint: Any) -> bool:
+    """True for ``list[str]``, ``tuple[int, ...]``, ``set[str]`` and friends."""
+    origin = get_origin(hint)
+    if origin is None:
+        return hint in _COLLECTION_ORIGINS
+    return origin in _COLLECTION_ORIGINS or (
+        isinstance(origin, type) and issubclass(origin, _COLLECTION_ORIGINS)
+    )
+
+
+def element_type(hint: Any) -> Any:
+    """The element type of a collection hint, or ``str`` if unparameterised."""
+    args = [a for a in get_args(hint) if a is not Ellipsis]
+    return strip_optional(unwrap_annotated(args[0])) if args else str
+
+
+def choices_of(hint: Any) -> tuple[str, ...] | None:
+    """Choice strings for a ``Literal`` or ``Enum`` hint, else ``None``."""
+    hint = strip_optional(unwrap_annotated(hint))
+    if get_origin(hint) is Literal:
+        return tuple(str(a) for a in get_args(hint))
+    if isinstance(hint, type) and issubclass(hint, enum.Enum):
+        return tuple(m.name for m in hint)
+    return None
+
+
+def resolve(hint: Any) -> tuple[Any, bool]:
+    """Reduce a hint to ``(scalar_type, is_multiple)``.
+
+    ``list[Path]`` becomes ``(Path, True)``; ``str | None`` becomes
+    ``(str, False)``. Unresolvable hints fall back to ``str``, which renders as a
+    text input rather than failing.
+    """
+    hint = strip_optional(unwrap_annotated(hint))
+    multiple = False
+    if is_collection(hint):
+        multiple = True
+        hint = element_type(hint)
+    if get_origin(hint) is Literal:
+        # A Literal renders as a choice list; its scalar type is that of its members.
+        args = get_args(hint)
+        return (type(args[0]) if args else str), multiple
+    if hint is Any or hint is None or hint is type(None):
+        return str, multiple
+    return hint, multiple

nicegui_autoform/adapters/__init__.py

@@ -0,0 +1,60 @@
+"""Framework adapters and the registry that dispatches between them.
+
+An adapter is any object exposing ``name``, ``matches(target)`` and
+``build(target, command)``. The bundled ones are modules. Adapters never import
+their framework at module scope: :func:`matches` first checks whether the
+framework is even in ``sys.modules``, because a caller cannot be holding a
+cyclopts ``App`` without cyclopts having been imported.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from ..spec import CommandSpec
+from . import _argparse, _click, _cyclopts, _typer, plain
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """What :func:`register_adapter` accepts."""
+
+    name: str
+
+    def matches(self, target: Any) -> bool: ...
+
+    def build(self, target: Any, command: str | None = None) -> CommandSpec: ...
+
+
+# Order matters: typer before click, since a Typer app resolves *to* a click
+# command; plain last, as the catch-all for dataclasses and bare functions.
+_ADAPTERS: list[Any] = [_cyclopts, _typer, _click, _argparse, plain]
+
+
+def register_adapter(adapter: Any, *, first: bool = True) -> None:
+    """Add a custom adapter. Registered first by default, so it can take
+    precedence over a bundled one."""
+    for attr in ("name", "matches", "build"):
+        if not hasattr(adapter, attr):
+            raise TypeError(f"adapter is missing required attribute {attr!r}")
+    _ADAPTERS.insert(0, adapter) if first else _ADAPTERS.append(adapter)
+
+
+def adapters() -> tuple[Any, ...]:
+    """The registry, in dispatch order."""
+    return tuple(_ADAPTERS)
+
+
+def build_spec(target: Any, command: str | None = None) -> CommandSpec:
+    """Introspect *target* into a :class:`~nicegui_autoform.spec.CommandSpec`."""
+    for adapter in _ADAPTERS:
+        if adapter.matches(target):
+            return adapter.build(target, command)
+    raise TypeError(
+        f"no adapter can handle {target!r} (type {type(target).__name__}). "
+        "Expected a cyclopts App, click Command, Typer app, ArgumentParser, "
+        "dataclass or annotated function."
+    )
+
+
+__all__ = ["Adapter", "adapters", "build_spec", "register_adapter"]

nicegui_autoform/adapters/_argparse.py

@@ -0,0 +1,133 @@
+"""Adapter for ``argparse``.
+
+``ArgumentParser`` keeps its actions on the private ``_actions`` list, which has
+been stable across the whole life of the module. Unlike the other frameworks an
+``ArgumentParser`` has no callback -- parsing produces a ``Namespace`` and the
+program takes it from there -- so :attr:`CommandSpec.callback` is ``None`` and
+:class:`~nicegui_autoform.form.AutoForm` requires an explicit ``on_submit``.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from ..spec import MISSING, CommandSpec, ParamSpec
+
+name = "argparse"
+
+_SKIPPED_ACTIONS = (argparse._HelpAction, argparse._VersionAction, argparse._SubParsersAction)
+_FLAG_ACTIONS = (argparse._StoreTrueAction, argparse._StoreFalseAction)
+
+
+def matches(target: Any) -> bool:
+    return isinstance(target, argparse.ArgumentParser)
+
+
+def build(target: Any, command: str | None = None) -> CommandSpec:
+    parser = _resolve_command(target, command)
+    sections = _sections(parser)
+
+    params = []
+    for action in parser._actions:
+        if isinstance(action, _SKIPPED_ACTIONS) or action.help == argparse.SUPPRESS:
+            continue
+        if action.dest == argparse.SUPPRESS:
+            continue
+        params.append(_to_param(action, sections.get(id(action))))
+
+    return CommandSpec(
+        name=parser.prog or "",
+        help=_first_line(parser.description),
+        params=tuple(params),
+        callback=None,
+        source=name,
+        extras={"parser": parser},
+    )
+
+
+def _resolve_command(parser: Any, command: str | None) -> Any:
+    subparsers = [a for a in parser._actions if isinstance(a, argparse._SubParsersAction)]
+    if command is None:
+        return parser
+    for action in subparsers:
+        if command in action.choices:
+            return action.choices[command]
+    available = sorted({name for a in subparsers for name in a.choices})
+    raise KeyError(f"{command!r} is not a subcommand of this parser; available: {available}")
+
+
+def _sections(parser: Any) -> dict[int, str]:
+    """Map each action to its argument group title, skipping argparse's defaults."""
+    default_titles = {"positional arguments", "options", "optional arguments"}
+    sections: dict[int, str] = {}
+    for group in parser._action_groups:
+        title = (group.title or "").strip()
+        if not title or title.lower() in default_titles:
+            continue
+        for action in group._group_actions:
+            sections[id(action)] = title
+    return sections
+
+
+def _to_param(action: Any, section: str | None) -> ParamSpec:
+    is_flag = isinstance(action, _FLAG_ACTIONS)
+    scalar = _resolve_type(action, is_flag)
+    multiple = (
+        isinstance(action, argparse._AppendAction)
+        or action.nargs in ("+", "*")
+        or (isinstance(action.nargs, int) and action.nargs > 1)
+    )
+
+    positional = not action.option_strings
+    required = bool(action.required) or (positional and action.nargs not in ("?", "*"))
+    default = MISSING if (required or action.default is None and positional) else action.default
+    if default is argparse.SUPPRESS:
+        default = MISSING
+
+    choices = tuple(str(c) for c in action.choices) if action.choices else None
+
+    return ParamSpec(
+        name=action.dest,
+        path=(action.dest,),
+        cli_name=action.option_strings[0] if action.option_strings else action.dest,
+        annotation=action.type,
+        type=scalar,
+        required=required,
+        default=default,
+        help=_clean(action.help),
+        choices=choices,
+        multiple=bool(multiple),
+        nargs=action.nargs if isinstance(action.nargs, int) and action.nargs > 1 else None,
+        is_flag=is_flag,
+        section=section,
+    )
+
+
+def _resolve_type(action: Any, is_flag: bool) -> Any:
+    if is_flag:
+        return bool
+    converter = action.type
+    if converter is None:
+        return str
+    # FileType is deprecated but still widely used, so the adapter has to keep
+    # mapping it to a path.
+    if isinstance(converter, argparse.FileType):  # ty: ignore[deprecated]
+        return Path
+    if isinstance(converter, type):
+        return converter
+    # A plain callable converter (e.g. a lambda) tells us nothing useful; a text
+    # input feeding the callable is the honest rendering.
+    return str
+
+
+def _clean(text: str | None) -> str | None:
+    return " ".join(text.split()) if text else None
+
+
+def _first_line(text: str | None) -> str | None:
+    if not text:
+        return None
+    stripped = text.strip()
+    return stripped.split("\n\n")[0].strip() or None

nicegui_autoform/adapters/_click.py

@@ -0,0 +1,215 @@
+"""Adapter for click.
+
+``Command.params`` gives fully resolved ``Option``/``Argument`` objects. The one
+sharp edge is the default sentinel: click 8.5 reports an unset default as
+``click.core.UNSET`` rather than ``None``, which :mod:`nicegui_autoform._compat`
+normalises.
+"""
+
+from __future__ import annotations
+
+import enum
+import sys
+from dataclasses import replace
+from pathlib import Path
+from typing import Any, get_type_hints
+
+from .._compat import TYPER_INJECTED_PARAMS, click_default
+from .._introspect import resolve
+from ..spec import MISSING, CommandSpec, ParamSpec
+
+name = "click"
+
+
+def matches(target: Any) -> bool:
+    click = sys.modules.get("click")
+    return click is not None and isinstance(target, click.Command)
+
+
+def build(target: Any, command: str | None = None, *, source: str = name) -> CommandSpec:
+    cmd = _resolve_command(target, command)
+
+    params = []
+    for param in cmd.params:
+        if getattr(param, "hidden", False) or param.name in TYPER_INJECTED_PARAMS:
+            continue
+        params.append(_to_param(param))
+
+    return CommandSpec(
+        name=cmd.name or "",
+        help=_first_line(cmd.help),
+        params=_enrich_from_callback(tuple(params), cmd.callback),
+        callback=cmd.callback,
+        source=source,
+        extras={"click_command": cmd},
+    )
+
+
+def _enrich_from_callback(params: tuple[ParamSpec, ...], callback: Any) -> tuple[ParamSpec, ...]:
+    """Recover types that the click ``ParamType`` could not express.
+
+    Typer's ``TyperChoice`` keeps only the choice strings, discarding the Enum
+    class the callback actually expects -- but the callback's own annotation
+    still has it. Since we call that callback directly, its annotation is the
+    authority whenever click could only tell us ``str``.
+    """
+    if callback is None:
+        return params
+
+    try:
+        hints = get_type_hints(callback)
+    except Exception:  # unresolvable forward refs; the click types stand alone
+        return params
+
+    enriched = []
+    for param in params:
+        hint = hints.get(param.name)
+        if hint is None:
+            enriched.append(param)
+            continue
+        scalar, multiple = resolve(hint)
+        is_enum = isinstance(scalar, type) and issubclass(scalar, enum.Enum)
+        if is_enum or param.type is str:
+            enriched.append(
+                replace(param, type=scalar, annotation=hint, multiple=param.multiple or multiple)
+            )
+        else:
+            enriched.append(param)
+    return tuple(enriched)
+
+
+def _resolve_command(target: Any, command: str | None) -> Any:
+    """Narrow a group to a single command.
+
+    Groups are identified by having a ``commands`` mapping rather than by
+    ``isinstance(target, click.Group)``: Typer's ``TyperGroup`` subclasses its
+    own vendored click, so the isinstance check would quietly treat a group as a
+    single command.
+    """
+    subcommands = getattr(target, "commands", None)
+    if not subcommands:
+        if command is not None and command != target.name:
+            raise KeyError(
+                f"{target.name!r} is a single command, not a group containing {command!r}"
+            )
+        return target
+
+    names = [n for n, c in subcommands.items() if not getattr(c, "hidden", False)]
+    if command is not None:
+        if command not in subcommands:
+            raise KeyError(f"{command!r} is not a command of this group; available: {names}")
+        return subcommands[command]
+    if len(names) == 1:
+        return subcommands[names[0]]
+    raise ValueError(
+        f"this group has {len(names)} commands, so command= is required; available: {names}"
+    )
+
+
+def _to_param(param: Any) -> ParamSpec:
+    scalar, choices, minimum, maximum = _resolve_type(param.type)
+    default = click_default(param)
+    nargs = param.nargs if isinstance(param.nargs, int) else None
+    multiple = bool(param.multiple) or (nargs is not None and nargs != 1)
+
+    if multiple and (default is MISSING or default is None or default in ((), [])):
+        # Parsing a multiple option that was never passed yields an empty tuple,
+        # never None -- so an empty list is the honest starting value however
+        # this click version reports the unset default (UNSET since 8.5, None
+        # before that).
+        default = [] if not param.required else MISSING
+    if param.required:
+        default = MISSING
+
+    opts = list(param.opts or [])
+    secondary = list(param.secondary_opts or [])
+
+    return ParamSpec(
+        name=param.name,
+        path=(param.name,),
+        cli_name=opts[0] if opts else param.name,
+        annotation=param.type,
+        type=scalar,
+        required=bool(param.required),
+        default=default,
+        help=_clean(getattr(param, "help", None)),
+        choices=choices,
+        multiple=multiple,
+        nargs=nargs if nargs not in (None, 1, -1) else None,
+        is_flag=bool(getattr(param, "is_flag", False)) or scalar is bool,
+        negative_cli_name=secondary[0] if secondary else None,
+        section=getattr(param, "rich_help_panel", None),
+        env_var=_env_vars(param),
+        minimum=minimum,
+        maximum=maximum,
+    )
+
+
+def _resolve_type(
+    param_type: Any,
+) -> tuple[Any, tuple[str, ...] | None, float | None, float | None]:
+    """Map a click ``ParamType`` to ``(python type, choices, minimum, maximum)``.
+
+    Deliberately duck-typed rather than ``isinstance``-based: Typer ships its own
+    vendored copy of click, so ``typer.models.TyperPath`` is not a
+    ``click.Path`` and its scalar types report ``name='int'`` where real click
+    reports ``'integer'``. Matching on the MRO's class names plus the type's own
+    ``name`` covers both, and keeps working across click releases.
+    """
+    class_names = " ".join(c.__name__ for c in type(param_type).__mro__)
+    type_name = (getattr(param_type, "name", "") or "").lower()
+
+    choices = getattr(param_type, "choices", None)
+    if choices is not None:
+        return str, tuple(_choice_label(c) for c in choices), None, None
+
+    if "IntRange" in class_names or type_name == "integer range":
+        return int, None, _bound(param_type, "min"), _bound(param_type, "max")
+    if "FloatRange" in class_names or type_name == "float range":
+        return float, None, _bound(param_type, "min"), _bound(param_type, "max")
+    if "Path" in class_names or "File" in class_names or type_name in {"path", "filename", "file"}:
+        return Path, None, None, None
+    if "DateTime" in class_names or type_name == "datetime":
+        return str, None, None, None
+    if "Bool" in class_names or type_name in {"boolean", "bool"}:
+        return bool, None, None, None
+    if "Int" in class_names or type_name in {"integer", "int"}:
+        return int, None, None, None
+    if "Float" in class_names or type_name == "float":
+        return float, None, None, None
+    return str, None, None, None
+
+
+def _choice_label(choice: Any) -> str:
+    """The string a choice is shown and submitted as.
+
+    ``click.Choice`` accepts an Enum directly and keeps its members, whereas
+    Typer flattens an Enum to its values before click ever sees it. Preferring a
+    string ``.value`` makes both produce the same labels.
+    """
+    if isinstance(choice, enum.Enum):
+        return choice.value if isinstance(choice.value, str) else choice.name
+    return str(choice)
+
+
+def _bound(param_type: Any, attr: str) -> float | None:
+    value = getattr(param_type, attr, None)
+    return float(value) if value is not None else None
+
+
+def _env_vars(param: Any) -> tuple[str, ...]:
+    envvar = getattr(param, "envvar", None)
+    if not envvar:
+        return ()
+    return (envvar,) if isinstance(envvar, str) else tuple(envvar)
+
+
+def _clean(text: str | None) -> str | None:
+    return " ".join(text.split()) if text else None
+
+
+def _first_line(text: str | None) -> str | None:
+    if not text:
+        return None
+    stripped = text.strip()
+    return stripped.split("\n\n")[0].strip() or None