sprezzature-cli-gui 1.0.0__tar.gz

sprezzature_cli_gui-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Warith HARCHAOUI
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sprezzature_cli_gui-1.0.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: sprezzature-cli-gui
+Version: 1.0.0
+Summary: Auto-generate a single-file HTML GUI from any Python CLI (argparse, Click, Typer).
+Author-email: Warith HARCHAOUI <warith.harchaoui@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://harchaoui.org/warith/sprezzature/
+Project-URL: Repository, https://github.com/warith-harchaoui/sprezzature-cli-gui
+Keywords: cli,gui,argparse,click,typer,html,sprezzature
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: click
+Requires-Dist: click>=8.0; extra == "click"
+Provides-Extra: typer
+Requires-Dist: typer>=0.12; extra == "typer"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "api"
+Provides-Extra: mcp
+Requires-Dist: sprezzature-cli-gui[api]; extra == "mcp"
+Requires-Dist: fastapi-mcp>=0.3; extra == "mcp"
+Requires-Dist: mcp<2.0; extra == "mcp"
+Dynamic: license-file
+
+# sprezzature-cli-gui
+
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/warith-harchaoui/sprezzature-cli-gui/blob/main/LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+
+[![logo](https://raw.githubusercontent.com/warith-harchaoui/sprezzature-cli-gui/main/assets/logo.png)](https://harchaoui.org/warith/sprezzature/)
+
+Turn any Python command-line tool into a clickable form, automatically. A command-line
+tool takes typed text ("do this, with these options") instead of buttons and fields;
+this package reads the tool's own definition of its commands and options and builds a
+web page with a button and a field for each one, so a person who has never opened a
+terminal can still use it.
+
+Point this tool at a parser: the object inside a Python CLI that reads and validates
+the typed command. `argparse` (in Python's standard library), `Click`, and `Typer` are
+the three common ways to build one; all three are supported. Given that parser, this
+package emits a single self-contained page written in plain JavaScript and styled with
+Tailwind (a CSS framework, meaning it ships pre-made style classes instead of hand-
+written CSS). Every sub-command becomes a section, every flag a field. The page never
+runs the command itself: it assembles the exact command line as text, in the visitor's
+own browser, ready to copy and paste, to hand to a desktop app through a `Tauri`
+`invoke` call (`Tauri` wraps a web page as a native desktop app; `invoke` is how
+that wrapper lets the page call back into it), or to send to a FastAPI endpoint (a small
+Python web server) that runs it for real.
+
+For example: a CLI with a `--verbose` flag and a `convert INPUT OUTPUT` sub-command
+becomes a page with a checkbox for `--verbose` and two text fields for `INPUT` and
+`OUTPUT`; filling them in and pressing "Build command" prints the exact line
+`mytool convert in.csv out.json --verbose` for the visitor to copy.
+
+No framework, no build step: the emitted page is one static HTML file. It does load
+Tailwind's "Play" build from a CDN (`cdn.tailwindcss.com`) to turn the utility classes
+into real CSS in the visitor's browser, so opening the file needs an internet
+connection the first time; the form fields themselves still work, unstyled, without one.
+
+## Install
+
+```bash
+pip install sprezzature-cli-gui           # core (argparse)
+pip install "sprezzature-cli-gui[click]"  # add Click support
+pip install "sprezzature-cli-gui[typer]"  # add Typer support
+```
+
+## Use
+
+```bash
+# From a parser factory in an importable module
+sprezzature-cli-gui my_pkg.my_cli:build_parser > gui.html
+
+# From a script path
+sprezzature-cli-gui ./my_cli.py:make_parser > gui.html
+```
+
+When the parser cannot be imported, the tool falls back to parsing the tool's `--help`
+output, so it works even against a CLI it cannot introspect directly, including one
+that is not written in Python at all.
+
+## How it works
+
+`cli_to_gui.py` is a thin wrapper that re-exports the real implementation, which lives
+in the `sprezzature_cli_gui` package:
+
+- `adapters/`: read (introspect, meaning: examine the parser object's own fields
+  directly, rather than guess from printed text) an argparse or Click parser; or, when
+  no parser object is reachable, fall back to parsing the tool's `--help` text instead.
+- `schema.py`: the one normalized command/flag description every adapter produces, so
+  the renderer never needs to know which of the three frameworks it came from.
+- `renderer.py`: turns that description into the self-contained HTML + Tailwind +
+  plain-JavaScript page.
+- `loader.py`: resolves a `module:factory` or `path.py:factory` spec (a string naming
+  where the parser-building function lives) down to the actual parser object.
+
+## License
+
+BSD-3-Clause © Warith HARCHAOUI. Part of the [sprezzature](https://harchaoui.org/warith/sprezzature/) toolkit.

sprezzature_cli_gui-1.0.0/README.md

@@ -0,0 +1,75 @@
+# sprezzature-cli-gui
+
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/warith-harchaoui/sprezzature-cli-gui/blob/main/LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+
+[![logo](https://raw.githubusercontent.com/warith-harchaoui/sprezzature-cli-gui/main/assets/logo.png)](https://harchaoui.org/warith/sprezzature/)
+
+Turn any Python command-line tool into a clickable form, automatically. A command-line
+tool takes typed text ("do this, with these options") instead of buttons and fields;
+this package reads the tool's own definition of its commands and options and builds a
+web page with a button and a field for each one, so a person who has never opened a
+terminal can still use it.
+
+Point this tool at a parser: the object inside a Python CLI that reads and validates
+the typed command. `argparse` (in Python's standard library), `Click`, and `Typer` are
+the three common ways to build one; all three are supported. Given that parser, this
+package emits a single self-contained page written in plain JavaScript and styled with
+Tailwind (a CSS framework, meaning it ships pre-made style classes instead of hand-
+written CSS). Every sub-command becomes a section, every flag a field. The page never
+runs the command itself: it assembles the exact command line as text, in the visitor's
+own browser, ready to copy and paste, to hand to a desktop app through a `Tauri`
+`invoke` call (`Tauri` wraps a web page as a native desktop app; `invoke` is how
+that wrapper lets the page call back into it), or to send to a FastAPI endpoint (a small
+Python web server) that runs it for real.
+
+For example: a CLI with a `--verbose` flag and a `convert INPUT OUTPUT` sub-command
+becomes a page with a checkbox for `--verbose` and two text fields for `INPUT` and
+`OUTPUT`; filling them in and pressing "Build command" prints the exact line
+`mytool convert in.csv out.json --verbose` for the visitor to copy.
+
+No framework, no build step: the emitted page is one static HTML file. It does load
+Tailwind's "Play" build from a CDN (`cdn.tailwindcss.com`) to turn the utility classes
+into real CSS in the visitor's browser, so opening the file needs an internet
+connection the first time; the form fields themselves still work, unstyled, without one.
+
+## Install
+
+```bash
+pip install sprezzature-cli-gui           # core (argparse)
+pip install "sprezzature-cli-gui[click]"  # add Click support
+pip install "sprezzature-cli-gui[typer]"  # add Typer support
+```
+
+## Use
+
+```bash
+# From a parser factory in an importable module
+sprezzature-cli-gui my_pkg.my_cli:build_parser > gui.html
+
+# From a script path
+sprezzature-cli-gui ./my_cli.py:make_parser > gui.html
+```
+
+When the parser cannot be imported, the tool falls back to parsing the tool's `--help`
+output, so it works even against a CLI it cannot introspect directly, including one
+that is not written in Python at all.
+
+## How it works
+
+`cli_to_gui.py` is a thin wrapper that re-exports the real implementation, which lives
+in the `sprezzature_cli_gui` package:
+
+- `adapters/`: read (introspect, meaning: examine the parser object's own fields
+  directly, rather than guess from printed text) an argparse or Click parser; or, when
+  no parser object is reachable, fall back to parsing the tool's `--help` text instead.
+- `schema.py`: the one normalized command/flag description every adapter produces, so
+  the renderer never needs to know which of the three frameworks it came from.
+- `renderer.py`: turns that description into the self-contained HTML + Tailwind +
+  plain-JavaScript page.
+- `loader.py`: resolves a `module:factory` or `path.py:factory` spec (a string naming
+  where the parser-building function lives) down to the actual parser object.
+
+## License
+
+BSD-3-Clause © Warith HARCHAOUI. Part of the [sprezzature](https://harchaoui.org/warith/sprezzature/) toolkit.

sprezzature_cli_gui-1.0.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sprezzature-cli-gui"
+version = "1.0.0"
+description = "Auto-generate a single-file HTML GUI from any Python CLI (argparse, Click, Typer)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{name = "Warith HARCHAOUI", email = "warith.harchaoui@gmail.com"}]
+keywords = ["cli", "gui", "argparse", "click", "typer", "html", "sprezzature"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: User Interfaces",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff"]
+click = ["click>=8.0"]
+typer = ["typer>=0.12"]
+
+# HTTP surface (sprezzature_cli_gui/api.py): schema tree in, GUI HTML out.
+# Deliberately does NOT expose loader.load_parser_from_spec — importing an
+# arbitrary module behind an HTTP endpoint is remote code execution.
+api = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.30",
+]
+# MCP surface: the same routes republished as agent tools, via fastapi-mcp.
+mcp = [
+    "sprezzature-cli-gui[api]",
+    "fastapi-mcp>=0.3",
+    # fastapi-mcp 0.4.0 (the latest as of 2026-08) declares mcp>=1.12.0 with
+    # no upper bound, but calls mcp's Server(name, description) positionally
+    # -- mcp 2.0.0 made `description` keyword-only, so an unconstrained
+    # resolve breaks FastApiMCP(...) at construction time (verified: pip
+    # happily installs mcp 2.2.0 alongside fastapi-mcp 0.4.0, and
+    # `sprezzature_cli_gui.mcp` then raises TypeError on import). Pin below
+    # 2.0 until fastapi-mcp ships a fix.
+    "mcp<2.0",
+]
+[project.scripts]
+sprezzature-cli-gui-mcp = "sprezzature_cli_gui.mcp:main"
+sprezzature-cli-gui = "sprezzature_cli_gui.cli:main"
+
+[project.urls]
+Homepage = "https://harchaoui.org/warith/sprezzature/"
+Repository = "https://github.com/warith-harchaoui/sprezzature-cli-gui"
+
+[tool.setuptools.packages.find]
+include = ["sprezzature_cli_gui*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sprezzature_cli_gui-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sprezzature_cli_gui-1.0.0/sprezzature_cli_gui/__init__.py

@@ -0,0 +1,17 @@
+"""
+sprezzature-cli-gui: turn a Python command-line tool into a clickable form.
+
+Reads the parser object a Python CLI already builds for itself, whether with
+`argparse` (the standard library's tool for this), `Click`, or `Typer`, and emits a
+single self-contained web page (plain JavaScript, Tailwind CSS) that maps every
+sub-command and flag to a form field. The page builds the command line locally, in the
+visitor's browser, and shows it ready to copy, to hand to a `Tauri invoke` call (the
+bridge a desktop-app wrapper uses to run a command on the visitor's behalf), or to send
+to a FastAPI server over SSE (Server-Sent Events, a simple one-way stream a server uses
+to push live output back to the page).
+"""
+
+__version__ = "1.0.0"
+__author__ = "Warith HARCHAOUI"
+__email__ = "warith.harchaoui@gmail.com"
+__license__ = "BSD-3-Clause"

sprezzature_cli_gui-1.0.0/sprezzature_cli_gui/_argparse.py

@@ -0,0 +1,71 @@
+"""
+_argparse: one factory function for every script's command-line parser.
+
+Python's standard library builds a command-line interface around an
+``argparse.ArgumentParser`` object: you create one, register each flag
+(``--lang``, ``--out``, and so on) on it, then call ``.parse_args()`` to
+turn the words the user typed into a plain object with one attribute per
+flag. Every script in this project needs the same handful of small
+conveniences on top of that (a clean program name in ``--help``, instead
+of a long file path; multi-line help text kept exactly as written instead
+of being auto-reflowed; a ``-V``/``--version`` flag). Rather than
+repeating that setup in every script, ``make_parser(prog, description,
+epilog=None)`` builds one parser already configured that way, and each
+script starts from it.
+
+This file is duplicated on purpose into every sprezzature-* repository,
+one copy each, so a skill stays self-contained and runs on its own:
+including from a downloaded zip, with nothing available but Python's
+standard library. The copies are meant to stay byte-for-byte identical
+apart from ``SKILL_VERSION``, which each repository sets to its own
+released version. So edit the canonical copy rather than this one, unless
+this is it: ``scripts/sync_helpers.py``, in the sprezzature monorepo,
+names the canonical copy, reports the ones that have drifted, and
+propagates the change with ``--apply``.
+
+Author
+------
+`Warith HARCHAOUI, Ph.D. <https://www.linkedin.com/in/warith-harchaoui/>`_
+"""
+
+from __future__ import annotations
+
+import argparse
+
+SKILL_VERSION = "1.0.0"
+
+
+def make_parser(
+    prog: str,
+    description: str,
+    epilog: str | None = None,
+) -> argparse.ArgumentParser:
+    """Build a pre-configured argparse parser.
+
+    Parameters
+    ----------
+    prog : str
+        Program name shown in ``--help`` (e.g. ``"sprezzature-figures-make"``).
+    description : str
+        One-paragraph description shown above the options table.
+    epilog : str or None, optional
+        Text shown below the options table, usually usage examples.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Parser with ``-V``/``--version`` pre-attached.
+    """
+    parser = argparse.ArgumentParser(
+        prog=prog,
+        description=description,
+        epilog=epilog,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"%(prog)s {SKILL_VERSION}",
+    )
+    return parser

sprezzature_cli_gui-1.0.0/sprezzature_cli_gui/adapters/__init__.py

@@ -0,0 +1,23 @@
+"""
+sprezzature_cli_gui.adapters
+=====================
+
+One adapter per supported CLI framework: the small piece of code that knows
+how to read that specific framework's parser object and reduce it to the
+one shared dict shape (``prog`` / ``description`` / ``actions`` /
+``sub_commands``) the HTML renderer consumes. Because every adapter ends
+at the same shape, the renderer itself never needs to know or branch on
+which framework produced it.
+
+- :mod:`sprezzature_cli_gui.adapters.argparse`: reads a standard-library
+  :class:`argparse.ArgumentParser`, always available since argparse ships
+  with Python itself.
+- :mod:`sprezzature_cli_gui.adapters.click`: reads an optional
+  :class:`click.Command`; also covers Typer apps, which are built on Click
+  internally.
+- :mod:`sprezzature_cli_gui.adapters.help_text`: the fallback that needs no
+  parser object at all, reading a CLI's printed ``--help`` text instead
+  (used through ``--from-help``, at lower fidelity than the other two).
+"""
+
+from __future__ import annotations

sprezzature_cli_gui-1.0.0/sprezzature_cli_gui/adapters/argparse.py

@@ -0,0 +1,115 @@
+"""
+sprezzature_cli_gui.adapters.argparse
+==============================
+
+The `argparse` adapter, for Python's own built-in way of building
+command-line tools.
+
+It reads an :class:`argparse.ArgumentParser` and reduces it to the shared
+parser-tree dict, dropping the ``--help`` and ``--version`` actions along
+the way: they make sense on a terminal, where a person types commands one
+at a time, but not on a generated form, which shows every option to fill
+in at once. Since argparse ships with every Python installation, this
+adapter needs no extra dependency and is always available; :func:`walk`
+reaches for it whenever the target factory returns an argparse parser.
+
+One naming detail worth flagging: this file is itself named
+``argparse.py``, yet its own ``import argparse`` line still reaches
+Python's standard-library module of the same name, not itself. Python 3
+resolves that import from the top-level package search path first (an
+"absolute import"), so a file's own name never shadows the standard
+library, and no special handling was needed to make this work.
+
+Author
+------
+`Warith HARCHAOUI, Ph.D. <https://www.linkedin.com/in/warith-harchaoui/>`_
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from sprezzature_cli_gui.schema import NO_DEFAULT, _safe_default
+
+# Re-exported for parity with the original single-module namespace, where
+# the sentinel lived alongside these adapters.
+__all__ = ["NO_DEFAULT", "_action_kind", "serialize_action", "walk_parser"]
+
+
+def _action_kind(a: argparse.Action) -> str:
+    """
+    Map an :class:`argparse.Action` to an HTML form-field kind string.
+
+    Returns one of: ``"bool"``, ``"int"``, ``"float"``, ``"choice"``,
+    ``"text"``, ``"file"`` (for actions whose ``type`` looks like
+    :func:`open` / :class:`argparse.FileType`).
+    """
+    if isinstance(a, (argparse._StoreTrueAction, argparse._StoreFalseAction)):
+        return "bool"
+    if a.choices:
+        return "choice"
+    if a.type is None:
+        return "text"
+    if a.type is int:
+        return "int"
+    if a.type is float:
+        return "float"
+    if isinstance(a.type, argparse.FileType):
+        return "file"
+    # ``type=open`` or callable: render as text and let the user paste a path.
+    return "text"
+
+
+def serialize_action(a: argparse.Action) -> dict[str, Any]:
+    """Project one :class:`argparse.Action` into a JSON-friendly dict."""
+    return {
+        "dest": a.dest,
+        "flags": list(a.option_strings),
+        "kind": _action_kind(a),
+        "choices": list(a.choices) if a.choices else None,
+        "required": bool(a.required),
+        "default": _safe_default(a.default),
+        "help": (a.help or "").strip(),
+        "nargs": a.nargs if isinstance(a.nargs, (str, int)) else None,
+        "metavar": (
+            a.metavar
+            if isinstance(a.metavar, str)
+            else (a.metavar[0] if isinstance(a.metavar, tuple) else None)
+        ),
+    }
+
+
+def walk_parser(parser: argparse.ArgumentParser) -> dict[str, Any]:
+    """
+    Walk an :class:`argparse.ArgumentParser` into a serialisable tree.
+
+    The shape mirrors ``argparse`` itself: a ``prog`` / ``description``
+    pair, a list of leaf actions, and a (possibly empty)
+    ``sub_commands`` dict for any nested sub-parsers.
+
+    Help / version actions are filtered out; they exist only on the
+    CLI surface, not in a GUI.
+
+    See also :func:`walk` for the framework-agnostic entry point that
+    dispatches between this and :func:`walk_click`.
+    """
+    actions: list[dict[str, Any]] = []
+    sub_commands: dict[str, dict[str, Any]] = {}
+    for a in parser._actions:
+        if isinstance(a, argparse._SubParsersAction):
+            for name, sub in a.choices.items():
+                sub_commands[name] = walk_parser(sub)
+        elif isinstance(a, (argparse._HelpAction,)) or a.dest == argparse.SUPPRESS:
+            continue
+        elif getattr(a, "version", None) is not None:
+            # ``action="version"``: version banner, not a user input.
+            continue
+        else:
+            actions.append(serialize_action(a))
+    return {
+        "prog": parser.prog,
+        "description": (parser.description or "").strip(),
+        "actions": actions,
+        "sub_commands": sub_commands,
+    }