nicegui-autoform 0.1.0__tar.gz

nicegui_autoform-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0  # no floating v10 major tag published yet
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+          cache-suffix: release
+      # A tag that disagrees with pyproject.toml would publish a version nobody
+      # can reproduce from the tag, so fail before anything is built.
+      - name: Check tag matches project version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(uv version --short)"
+          if [ "$tag" != "$version" ]; then
+            echo "tag $GITHUB_REF_NAME does not match project version $version" >&2
+            exit 1
+          fi
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted publishing: PyPI mints a short-lived token from this job's OIDC
+    # identity, so there is no API token to store. Configure the publisher at
+    # https://pypi.org/manage/account/publishing/ with workflow "release.yml"
+    # and environment "pypi".
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nicegui-autoform
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v10.2.0  # no floating v10 major tag published yet
+      # --check-url skips files PyPI already has, so re-running the job after a
+      # partial failure is not an error.
+      - run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/

nicegui_autoform-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,43 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    # Every version the README claims support for. 3.15 is still a release
+    # candidate, so uv installs it rather than actions/setup-python.
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14", "3.15"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0  # no floating v10 major tag published yet
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+          # Without this the three matrix jobs race for one cache key and two
+          # of them fail to save.
+          cache-suffix: py${{ matrix.python-version }}
+      - run: uv sync --frozen --python ${{ matrix.python-version }}
+      - run: uv run --frozen --python ${{ matrix.python-version }} pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0  # no floating v10 major tag published yet
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+          cache-suffix: lint
+      - run: uv run --frozen ruff check .
+      - run: uv run --frozen ruff format --check .
+      - run: uv run --frozen ty check src tests examples

nicegui_autoform-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage

nicegui_autoform-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Owen Solberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nicegui_autoform-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: nicegui-autoform
+Version: 0.1.0
+Summary: Render a NiceGUI web form from a command line interface.
+Project-URL: Homepage, https://github.com/odoublewen/nicegui-autoform
+Project-URL: Issues, https://github.com/odoublewen/nicegui-autoform/issues
+Author: Owen Solberg
+License-Expression: MIT
+License-File: LICENSE
+Keywords: argparse,cli,click,cyclopts,forms,nicegui,typer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.13
+Requires-Dist: nicegui>=3.12
+Provides-Extra: all
+Requires-Dist: click>=8.1; extra == 'all'
+Requires-Dist: cyclopts>=4.0; extra == 'all'
+Requires-Dist: typer>=0.13; extra == 'all'
+Provides-Extra: click
+Requires-Dist: click>=8.1; extra == 'click'
+Provides-Extra: cyclopts
+Requires-Dist: cyclopts>=4.0; extra == 'cyclopts'
+Provides-Extra: typer
+Requires-Dist: typer>=0.13; extra == 'typer'
+Description-Content-Type: text/markdown
+
+# nicegui-autoform
+
+[![tests](https://github.com/odoublewen/nicegui-autoform/actions/workflows/tests.yml/badge.svg)](https://github.com/odoublewen/nicegui-autoform/actions/workflows/tests.yml)
+
+Render a [NiceGUI](https://nicegui.io) web form from a command line interface.
+
+If you already have a function wired up as a CLI, `AutoForm` reads that CLI's own
+parameter metadata -- types, defaults, help text, choices, flags -- and builds a form
+that calls the same function.
+
+```python
+from nicegui import ui
+from nicegui_autoform import AutoForm
+
+AutoForm(app, command="train")  # a cyclopts App, click Command, Typer app, ...
+ui.run()
+```
+
+## Supported frameworks
+
+| Framework | Install | Notes |
+|---|---|---|
+| [cyclopts](https://cyclopts.readthedocs.io) | `nicegui-autoform[cyclopts]` | Including CLIs defined with a `@dataclass` |
+| [click](https://click.palletsprojects.com) | `nicegui-autoform[click]` | |
+| [Typer](https://typer.tiangolo.com) | `nicegui-autoform[typer]` | |
+| `argparse` | built in | No callback exists, so `on_submit` is required |
+| Plain `@dataclass` or annotated function | built in | No CLI framework needed |
+
+The core package depends only on NiceGUI. CLI frameworks are optional extras and are
+imported lazily, so nothing is imported that you do not already use.
+
+## Install
+
+```bash
+uv add "nicegui-autoform[all]"
+```
+
+## Supported versions
+
+Python 3.13, 3.14 and 3.15. The dependency floors below were measured by running
+the test suite against each version rather than guessed:
+
+| Dependency | Floor | Why not lower |
+|---|---|---|
+| NiceGUI | 3.12 | NiceGUI's own `user` test fixture only works from 3.12, so earlier versions cannot be verified end to end |
+| cyclopts | 4.0 | 3.x has a different `ArgumentCollection` API |
+| click | 8.1 | 8.0 predates the parameter metadata the adapter reads |
+| Typer | 0.13 | 0.12 cannot build its commands against current click |
+
+One caveat on click 8.1 and 8.2: they report an option with no default the same
+way as `default=None`, so those two cases are indistinguishable. From click 8.3
+onwards an unset default is a distinct `UNSET` sentinel and the form can tell
+"no default" from "defaults to None".
+
+## How it works
+
+Each framework has an adapter that produces a `CommandSpec` -- a flat list of
+`ParamSpec` leaves plus the containers needed to rebuild nested objects. Everything
+downstream (widget selection, validation, rendering) works on that spec alone, so all
+frameworks get identical behaviour and a new framework only needs a new adapter.
+
+On submit the form validates its values against the spec and then calls the command's
+own function directly. It does not shell out or re-parse a command line.
+
+## Usage
+
+### Choosing a command
+
+```python
+AutoForm(cyclopts_app, command="train")
+AutoForm(typer_app, command="train")
+AutoForm(click_group, command="train")
+```
+
+A single-command CLI needs no `command=`.
+
+### Overriding the callback
+
+By default the form calls the command's own function. Pass `on_submit` to intercept it:
+
+```python
+async def run(*args, **kwargs):
+    ui.notify(f"running with {kwargs}")
+
+
+AutoForm(app, command="train", on_submit=run)
+```
+
+`on_submit` may be sync or async. For an `argparse.ArgumentParser` there is no callback
+to default to, so `on_submit` is required and receives an `argparse.Namespace`.
+
+### Nested dataclasses
+
+A cyclopts command taking a dataclass renders its fields as a labelled section, and the
+dataclass is rebuilt before the callback is called:
+
+```python
+@dataclass
+class Config:
+    """Training configuration.
+
+    Parameters
+    ----------
+    epochs: int
+        number of epochs
+    """
+
+    data: Path
+    epochs: int = 10
+
+
+@app.command
+def train(config: Config, seed: int = 0): ...
+```
+
+Help text comes from the dataclass's own numpydoc docstring, exactly as cyclopts'
+`--help` renders it.
+
+### Widgets and exclusions
+
+```python
+from nicegui_autoform import WidgetKind
+
+AutoForm(
+    app,
+    command="train",
+    exclude=["debug", "config.seed"],  # bare name or dotted path
+    widgets={"notes": WidgetKind.TEXTAREA},
+    initial={"epochs": 50},
+)
+```
+
+`Path` parameters render as a file upload by default. The upload is written to a private
+temporary directory under its **original** name, so the callback receives a real, readable
+`Path` whose `.name` is the file the user picked -- useful when the function derives an
+output name or switches on the extension. Only the basename of the client-supplied filename
+is ever used, so an uploaded name cannot escape that directory.
+
+Use `widgets={"out": WidgetKind.PATH_TEXT}` for an output path that should be typed rather
+than uploaded.
+
+## Examples
+
+Four runnable demos, one per framework:
+
+```bash
+uv run python examples/cyclopts_demo.py    # nested dataclass as a section
+uv run python examples/click_demo.py       # IntRange, Choice, repeatable option
+uv run python examples/typer_demo.py       # rich_help_panel as a section
+uv run python examples/argparse_demo.py    # on_submit receives a Namespace
+```
+
+Each has a required `data` upload. `examples/data/measurements.csv` (12 rows of
+dose/response data) is there to drop into it, and `examples/data/notes.txt` shows that a
+non-CSV extension survives the round trip. On submit each demo reads the uploaded file and
+reports its name and line count, so you can see the real file reached the function.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check
+uv run ruff format
+uv run ty check src tests examples
+```
+
+To check a dependency floor, run the suite against that exact version:
+
+```bash
+uv run --isolated --with "click==8.1.8" pytest
+```
+
+## License
+
+MIT

nicegui_autoform-0.1.0/README.md

@@ -0,0 +1,176 @@
+# nicegui-autoform
+
+[![tests](https://github.com/odoublewen/nicegui-autoform/actions/workflows/tests.yml/badge.svg)](https://github.com/odoublewen/nicegui-autoform/actions/workflows/tests.yml)
+
+Render a [NiceGUI](https://nicegui.io) web form from a command line interface.
+
+If you already have a function wired up as a CLI, `AutoForm` reads that CLI's own
+parameter metadata -- types, defaults, help text, choices, flags -- and builds a form
+that calls the same function.
+
+```python
+from nicegui import ui
+from nicegui_autoform import AutoForm
+
+AutoForm(app, command="train")  # a cyclopts App, click Command, Typer app, ...
+ui.run()
+```
+
+## Supported frameworks
+
+| Framework | Install | Notes |
+|---|---|---|
+| [cyclopts](https://cyclopts.readthedocs.io) | `nicegui-autoform[cyclopts]` | Including CLIs defined with a `@dataclass` |
+| [click](https://click.palletsprojects.com) | `nicegui-autoform[click]` | |
+| [Typer](https://typer.tiangolo.com) | `nicegui-autoform[typer]` | |
+| `argparse` | built in | No callback exists, so `on_submit` is required |
+| Plain `@dataclass` or annotated function | built in | No CLI framework needed |
+
+The core package depends only on NiceGUI. CLI frameworks are optional extras and are
+imported lazily, so nothing is imported that you do not already use.
+
+## Install
+
+```bash
+uv add "nicegui-autoform[all]"
+```
+
+## Supported versions
+
+Python 3.13, 3.14 and 3.15. The dependency floors below were measured by running
+the test suite against each version rather than guessed:
+
+| Dependency | Floor | Why not lower |
+|---|---|---|
+| NiceGUI | 3.12 | NiceGUI's own `user` test fixture only works from 3.12, so earlier versions cannot be verified end to end |
+| cyclopts | 4.0 | 3.x has a different `ArgumentCollection` API |
+| click | 8.1 | 8.0 predates the parameter metadata the adapter reads |
+| Typer | 0.13 | 0.12 cannot build its commands against current click |
+
+One caveat on click 8.1 and 8.2: they report an option with no default the same
+way as `default=None`, so those two cases are indistinguishable. From click 8.3
+onwards an unset default is a distinct `UNSET` sentinel and the form can tell
+"no default" from "defaults to None".
+
+## How it works
+
+Each framework has an adapter that produces a `CommandSpec` -- a flat list of
+`ParamSpec` leaves plus the containers needed to rebuild nested objects. Everything
+downstream (widget selection, validation, rendering) works on that spec alone, so all
+frameworks get identical behaviour and a new framework only needs a new adapter.
+
+On submit the form validates its values against the spec and then calls the command's
+own function directly. It does not shell out or re-parse a command line.
+
+## Usage
+
+### Choosing a command
+
+```python
+AutoForm(cyclopts_app, command="train")
+AutoForm(typer_app, command="train")
+AutoForm(click_group, command="train")
+```
+
+A single-command CLI needs no `command=`.
+
+### Overriding the callback
+
+By default the form calls the command's own function. Pass `on_submit` to intercept it:
+
+```python
+async def run(*args, **kwargs):
+    ui.notify(f"running with {kwargs}")
+
+
+AutoForm(app, command="train", on_submit=run)
+```
+
+`on_submit` may be sync or async. For an `argparse.ArgumentParser` there is no callback
+to default to, so `on_submit` is required and receives an `argparse.Namespace`.
+
+### Nested dataclasses
+
+A cyclopts command taking a dataclass renders its fields as a labelled section, and the
+dataclass is rebuilt before the callback is called:
+
+```python
+@dataclass
+class Config:
+    """Training configuration.
+
+    Parameters
+    ----------
+    epochs: int
+        number of epochs
+    """
+
+    data: Path
+    epochs: int = 10
+
+
+@app.command
+def train(config: Config, seed: int = 0): ...
+```
+
+Help text comes from the dataclass's own numpydoc docstring, exactly as cyclopts'
+`--help` renders it.
+
+### Widgets and exclusions
+
+```python
+from nicegui_autoform import WidgetKind
+
+AutoForm(
+    app,
+    command="train",
+    exclude=["debug", "config.seed"],  # bare name or dotted path
+    widgets={"notes": WidgetKind.TEXTAREA},
+    initial={"epochs": 50},
+)
+```
+
+`Path` parameters render as a file upload by default. The upload is written to a private
+temporary directory under its **original** name, so the callback receives a real, readable
+`Path` whose `.name` is the file the user picked -- useful when the function derives an
+output name or switches on the extension. Only the basename of the client-supplied filename
+is ever used, so an uploaded name cannot escape that directory.
+
+Use `widgets={"out": WidgetKind.PATH_TEXT}` for an output path that should be typed rather
+than uploaded.
+
+## Examples
+
+Four runnable demos, one per framework:
+
+```bash
+uv run python examples/cyclopts_demo.py    # nested dataclass as a section
+uv run python examples/click_demo.py       # IntRange, Choice, repeatable option
+uv run python examples/typer_demo.py       # rich_help_panel as a section
+uv run python examples/argparse_demo.py    # on_submit receives a Namespace
+```
+
+Each has a required `data` upload. `examples/data/measurements.csv` (12 rows of
+dose/response data) is there to drop into it, and `examples/data/notes.txt` shows that a
+non-CSV extension survives the round trip. On submit each demo reads the uploaded file and
+reports its name and line count, so you can see the real file reached the function.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check
+uv run ruff format
+uv run ty check src tests examples
+```
+
+To check a dependency floor, run the suite against that exact version:
+
+```bash
+uv run --isolated --with "click==8.1.8" pytest
+```
+
+## License
+
+MIT

nicegui_autoform-0.1.0/examples/argparse_demo.py

@@ -0,0 +1,51 @@
+"""Argparse.
+
+A parser has no callback, so ``on_submit`` is required and receives the
+``Namespace`` the form assembled.
+
+    uv run python examples/argparse_demo.py
+
+    Upload examples/data/measurements.csv into the Data field to submit.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from nicegui import ui
+
+from nicegui_autoform import AutoForm
+
+parser = argparse.ArgumentParser(prog="train", description="Train a model.")
+parser.add_argument("data", type=Path, help="the input data file")
+parser.add_argument("--epochs", type=int, default=10, help="number of epochs")
+parser.add_argument("--mode", choices=["fast", "slow"], default="fast")
+parser.add_argument("--verbose", action="store_true", help="log every step")
+parser.add_argument("--tag", dest="tags", action="append", default=[], help="repeatable label")
+
+advanced = parser.add_argument_group("Advanced")
+advanced.add_argument("--workers", type=int, default=4, help="parallel workers")
+advanced.add_argument("--seed", type=int, default=0)
+
+
+def run(args: argparse.Namespace) -> None:
+    """A parser has no callback of its own, so this receives the Namespace."""
+    lines = args.data.read_text().splitlines()
+    ui.notify(
+        f"{args.data.name} ({len(lines)} lines) with "
+        f"epochs={args.epochs}, mode={args.mode}, verbose={args.verbose}, "
+        f"tags={args.tags}, workers={args.workers}, seed={args.seed}",
+        type="positive",
+        multi_line=True,
+        close_button=True,
+    )
+
+
+@ui.page("/")
+def index() -> None:
+    ui.label("argparse").classes("text-h5")
+    AutoForm(parser, on_submit=run)
+
+
+ui.run(title="argparse demo", reload=False)

nicegui_autoform-0.1.0/examples/click_demo.py

@@ -0,0 +1,48 @@
+"""Click.
+
+uv run python examples/click_demo.py
+
+Upload examples/data/measurements.csv into the Data field to submit.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from nicegui import ui
+
+from nicegui_autoform import AutoForm
+
+
+def summarise(data: Path) -> str:
+    """Prove the upload arrived: the callback gets a real, readable file."""
+    lines = data.read_text().splitlines()
+    return f"{data.name} ({len(lines)} lines, {data.stat().st_size} bytes)"
+
+
+@click.command("train")
+@click.argument("data", type=click.Path(path_type=Path))
+@click.option("--epochs", type=int, default=10, help="number of epochs")
+@click.option("--workers", type=click.IntRange(1, 64), default=4, help="parallel workers")
+@click.option("--mode", type=click.Choice(["fast", "slow"]), default="fast")
+@click.option("--verbose/--no-verbose", default=False, help="log every step")
+@click.option("--tag", "tags", multiple=True, help="repeatable label")
+def train(data, epochs, workers, mode, verbose, tags):
+    """Train a model."""
+    ui.notify(
+        f"train(data={summarise(data)}, epochs={epochs}, workers={workers}, "
+        f"mode={mode}, verbose={verbose}, tags={list(tags)})",
+        type="positive",
+        multi_line=True,
+        close_button=True,
+    )
+
+
+@ui.page("/")
+def index() -> None:
+    ui.label("click").classes("text-h5")
+    AutoForm(train)
+
+
+ui.run(title="click demo", reload=False)

nicegui_autoform-0.1.0/examples/cyclopts_demo.py

@@ -0,0 +1,88 @@
+"""Cyclopts, including a nested dataclass rendered as a section.
+
+uv run python examples/cyclopts_demo.py
+
+Upload examples/data/measurements.csv into the Data field to submit.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+from nicegui import ui
+
+from nicegui_autoform import AutoForm
+
+app = cyclopts.App(name="trainer")
+
+
+def summarise(data: Path) -> str:
+    """Prove the upload arrived: the callback gets a real, readable file."""
+    lines = data.read_text().splitlines()
+    return f"{data.name} ({len(lines)} lines, {data.stat().st_size} bytes)"
+
+
+class Mode(enum.StrEnum):
+    fast = "fast"
+    slow = "slow"
+
+
+@dataclass
+class Tuning:
+    """Tuning.
+
+    Parameters
+    ----------
+    lr: float
+        learning rate
+    workers: int
+        parallel worker processes
+    """
+
+    lr: float = 0.001
+    workers: int = 4
+
+
+DEFAULT_TUNING = Tuning()
+
+
+@app.command
+def train(
+    data: Path,
+    epochs: int = 10,
+    mode: Mode = Mode.fast,
+    verbose: Annotated[bool, cyclopts.Parameter(help="log every step")] = False,
+    tags: list[str] = [],  # noqa: B006 - cyclopts reads the annotation, not the object
+    tuning: Tuning = DEFAULT_TUNING,
+):
+    """Train a model.
+
+    Parameters
+    ----------
+    data: Path
+        the input data file
+    epochs: int
+        number of epochs
+    mode: Mode
+        scheduling mode
+    """
+    ui.notify(
+        f"train(data={summarise(data)}, epochs={epochs}, mode={mode}, "
+        f"verbose={verbose}, tags={tags}, tuning={tuning})",
+        type="positive",
+        multi_line=True,
+        close_button=True,
+    )
+
+
+@ui.page("/")
+def index() -> None:
+    ui.label("cyclopts").classes("text-h5")
+    AutoForm(app, command="train")
+
+
+ui.run(title="cyclopts demo", reload=False)