cfuicli 1.0.0__tar.gz

cfuicli-1.0.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule: {interval: weekly}
+    commit-message: {prefix: ⬆}
+  - package-ecosystem: uv
+    directory: /
+    schedule: {interval: weekly}
+    commit-message: {prefix: ⬆}

cfuicli-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: CI
+on:
+  push: {branches: [main, develop]}
+  pull_request: {branches: [main, develop]}
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest

cfuicli-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release
+on:
+  workflow_run: {workflows: [CI], branches: [main], types: [completed]}
+  workflow_dispatch:
+permissions: {contents: write, issues: write, pull-requests: write, id-token: write}
+jobs:
+  release:
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    environment: pypi   # configure the Trusted Publisher on pypi.org with this environment name
+    steps:
+      - uses: actions/checkout@v6
+        with: {fetch-depth: 0, ref: "${{ github.event.workflow_run.head_branch || github.ref }}"}
+      - uses: astral-sh/setup-uv@v7
+      - run: |
+          git config user.name "${{ github.actor }}"
+          git config user.email "${{ github.actor }}@users.noreply.github.com"
+      - id: sr
+        env: {GH_TOKEN: "${{ secrets.GITHUB_TOKEN }}"}
+        run: |
+          uvx --from python-semantic-release semantic-release version --changelog --tag --push
+          # a new tag points at HEAD only when a release was made
+          git describe --exact-match --tags HEAD >/dev/null 2>&1 && echo "released=true" >> "$GITHUB_OUTPUT" || true
+      - if: steps.sr.outputs.released == 'true'
+        run: uv build && uv publish --trusted-publishing always

cfuicli-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+.venv/
+dist/
+*.egg-info/

cfuicli-1.0.0/.gitmessage

@@ -0,0 +1,7 @@
+# <type>(<scope>): <subject>
+#
+# <body>
+#
+# types: feat fix docs style refactor perf test build ci chore revert
+# subject: imperative, lowercase, no trailing dot
+# footer: BREAKING CHANGE: ... / Closes #123

cfuicli-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

cfuicli-1.0.0/AGENTS.md

@@ -0,0 +1,4 @@
+# Agent notes
+- Use `uv run ...`; never pip.
+- Before finishing: `uv run ruff check . && uv run ruff format --check . && uv run pytest`.
+- Conventional Commits only. Keep changes minimal; no new deps without need.

cfuicli-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.0.0 (2026-10-11)
+
+- Initial Release

cfuicli-1.0.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.5
+Name: cfuicli
+Version: 1.0.0
+Summary: cf-style terminal UI and a tiny argparse app framework (help, version, update, prompts for missing options).
+Project-URL: Homepage, https://github.com/arian24b/cfui
+Author-email: Arian Omrani <arian24b@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# cfui
+
+Install: `pip install cfuicli` (import name: `cfui`).
+
+Stdlib-only terminal UI and tiny argparse framework in the style of Cloudflare's `cf` CLI.
+
+```python
+from cfui import App, Arg, ui
+
+app = App("tool", repo="https://github.com/me/tool", pypi="tool", description="Does things.")
+
+
+@app.command("greet", "Say hi", args=[Arg("--name", required=True, prompt="Your name")])
+def greet(a):
+    ui.success(f"hi {a.name}")
+
+
+def main():
+    app.main()
+```
+
+Gives you `help`, `version` (and `-v`), `update [--check]`, `-q/--quiet`, boxed errors, JSON output,
+and prompts for missing required options on a TTY (a clear error when piped or in CI).
+
+## Shared pieces (`cfui.common`)
+
+`YES`, `JSON`, `FORCE`, `DRY_RUN`, `JOBS`, `TIMEOUT`, `BACKGROUND` (ready-made `Arg`s), `confirm(msg, yes)`,
+`parse_value`, `run_parallel(items, worker, jobs)`, and `add_config(app, items=, get=, set=, reset=, path=, validate=)`
+which registers `config show|get|set|reset|path|validate`.
+
+## Releasing
+
+Conventional Commits on `main` -> CI -> `Release` workflow (python-semantic-release) bumps the version, tags and
+publishes to PyPI with a Trusted Publisher (environment `pypi`, workflow `release.yml`). See `docs/workflow.md`.

cfuicli-1.0.0/README.md

@@ -0,0 +1,34 @@
+# cfui
+
+Install: `pip install cfuicli` (import name: `cfui`).
+
+Stdlib-only terminal UI and tiny argparse framework in the style of Cloudflare's `cf` CLI.
+
+```python
+from cfui import App, Arg, ui
+
+app = App("tool", repo="https://github.com/me/tool", pypi="tool", description="Does things.")
+
+
+@app.command("greet", "Say hi", args=[Arg("--name", required=True, prompt="Your name")])
+def greet(a):
+    ui.success(f"hi {a.name}")
+
+
+def main():
+    app.main()
+```
+
+Gives you `help`, `version` (and `-v`), `update [--check]`, `-q/--quiet`, boxed errors, JSON output,
+and prompts for missing required options on a TTY (a clear error when piped or in CI).
+
+## Shared pieces (`cfui.common`)
+
+`YES`, `JSON`, `FORCE`, `DRY_RUN`, `JOBS`, `TIMEOUT`, `BACKGROUND` (ready-made `Arg`s), `confirm(msg, yes)`,
+`parse_value`, `run_parallel(items, worker, jobs)`, and `add_config(app, items=, get=, set=, reset=, path=, validate=)`
+which registers `config show|get|set|reset|path|validate`.
+
+## Releasing
+
+Conventional Commits on `main` -> CI -> `Release` workflow (python-semantic-release) bumps the version, tags and
+publishes to PyPI with a Trusted Publisher (environment `pypi`, workflow `release.yml`). See `docs/workflow.md`.

cfuicli-1.0.0/docs/workflow.md

@@ -0,0 +1,27 @@
+# Workflow
+
+Distilled from the conventions already used across my repos (tgnews, linkcovery, ollamatools, ...).
+
+## Tooling
+- **uv** for everything: `uv sync`, `uv run pytest`, `uv add <pkg>`. Commit `uv.lock`.
+- **ruff** for lint + format (config in `pyproject.toml`, line length 120).
+- **hatchling** build backend, `src/` layout.
+
+## Branching & commits
+1. Branch from `develop`; PR into `develop`, then `develop` -> `main`.
+2. Use Conventional Commits (`git config commit.template .gitmessage`).
+   `feat` = minor, `fix`/`perf` = patch, `BREAKING CHANGE` = major.
+
+## Pipeline (`.github/workflows`)
+`CI` (ruff + pytest) -> `Release` (python-semantic-release: bumps version, writes CHANGELOG, tags)
+-> `Build` (docker image to ghcr.io, tagged version + latest).
+Dependabot bumps actions and uv deps weekly.
+
+## Starting a project
+1. "Use this template" on GitHub.
+2. Rename `project-name` / `project_name` (pyproject, Dockerfile, tests, `src/`).
+3. Fill LICENSE, README; `uv sync`; `git config commit.template .gitmessage`.
+4. Create the PyPI project + Trusted Publisher (workflow `release.yml`, environment `pypi`) before the first release.
+
+## Adding Telegram/web apps
+Secrets in `.env` (never committed; keep `.env.example` current). Timezone via `TZ` env in Dockerfile when scheduling.

cfuicli-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "cfuicli"
+version = "1.0.0"
+description = "cf-style terminal UI and a tiny argparse app framework (help, version, update, prompts for missing options)."
+readme = "README.md"
+license = "MIT"
+authors = [{name = "Arian Omrani", email = "arian24b@gmail.com"}]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/arian24b/cfui"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.8", "python-semantic-release>=9"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cfui"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "N", "UP", "S", "B", "A", "C4", "SIM", "RUF"]
+ignore = ["S101", "S110", "S603", "A002", "A001", "E731", "RUF012", "RUF001", "N818", "N806", "N801", "SIM105"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+
+[tool.semantic_release.branches.main]
+match = "main"
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"
+output_format = "md"

cfuicli-1.0.0/src/cfui/__init__.py

@@ -0,0 +1,18 @@
+from . import common, ui
+from .app import App, Arg, Command
+from .common import add_config, confirm, parse_value, run_parallel
+from .ui import Cancel, Fail
+
+__all__ = [
+    "App",
+    "Arg",
+    "Cancel",
+    "Command",
+    "Fail",
+    "add_config",
+    "common",
+    "confirm",
+    "parse_value",
+    "run_parallel",
+    "ui",
+]

cfuicli-1.0.0/src/cfui/app.py

@@ -0,0 +1,321 @@
+"""Tiny argparse framework: cf-style help, and ready-made help / version / update commands."""
+
+import argparse
+import asyncio
+import importlib.metadata
+import inspect
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import textwrap
+import urllib.request
+
+from . import ui
+
+_VALUE_ACTIONS = ("store", "append", "extend")
+_BUILTIN = ("help", "version", "update")
+
+
+class Arg:
+    """An argparse argument. `required=True` means: prompt for it on a TTY, fail with a clear error otherwise."""
+
+    def __init__(self, *flags, required=False, prompt=None, secret=False, group=None, **kw):
+        self.flags, self.required, self.prompt, self.secret, self.kw = flags, required, prompt, secret, kw
+        self.group = group or ("Arguments" if flags[0][0] != "-" else None)  # help section title
+        self.positional = not flags[0].startswith("-")
+        if self.positional and required:  # we enforce it ourselves so we can prompt
+            kw["nargs"] = "*" if kw.get("nargs") in ("+", "*") else "?"
+        elif required:
+            kw.pop("required", None)
+        self.dest = kw.get("dest") or (
+            flags[0] if self.positional else max(flags, key=len).lstrip("-").replace("-", "_")
+        )
+
+    def add_to(self, parser):
+        parser.add_argument(*self.flags, **self.kw)
+
+    def _pname(self):
+        n = self.kw.get("metavar") or self.flags[0]
+        if self.kw.get("nargs") in ("+", "*"):
+            n += "..."
+        return f"<{n}>" if self.required else f"[{n}]"
+
+    @property
+    def takes_value(self):
+        return not self.positional and self.kw.get("action", "store") in _VALUE_ACTIONS
+
+    def row(self):
+        left = ", ".join(self.flags)
+        if self.takes_value:
+            left += f" <{self.kw.get('metavar') or self.dest.upper()}>"
+        elif self.positional:
+            left = self._pname()
+        right = self.kw.get("help", "")
+        if self.required:
+            right += " [required]"
+        if self.kw.get("choices"):
+            right += f" [choices: {', '.join(map(str, self.kw['choices']))}]"
+        d = self.kw.get("default")
+        if d not in (None, False, "") and self.takes_value:
+            right += f" [default: {d}]"
+        return left, right.strip()
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message):
+        raise ui.Fail(message, f"Run `{self.prog} --help` for usage.", code=2)
+
+
+class Command:
+    def __init__(
+        self, name, help_="", fn=None, args=(), aliases=(), hidden=False, banner=False, raw=False, help_args=None
+    ):
+        self.name, self.help, self.fn, self.args = name, help_, fn, list(args)
+        self.raw, self.help_args = (
+            raw,
+            help_args,
+        )  # raw: gets the untouched argv tail as `.args`; help_args: subset shown in --help
+        self.aliases, self.hidden, self.banner = aliases, hidden, banner
+        self.commands = {}  # non-empty for a group
+
+    def command(self, name, help="", args=(), aliases=(), hidden=False, banner=False, raw=False, help_args=None):
+        def deco(fn):
+            self.commands[name] = Command(name, help, fn, args, aliases, hidden, banner, raw, help_args)
+            return fn
+
+        return deco
+
+    def group(self, name, help="", aliases=()):
+        g = self.commands[name] = Command(name, help, aliases=aliases)
+        return g
+
+    def find(self, name):
+        for c in self.commands.values():
+            if name == c.name or name in c.aliases:
+                return c
+
+
+class App(Command):
+    def __init__(
+        self, name, repo, description="", pypi=None, version=None, docs=None, global_args=(), default=None, upgrade=None
+    ):
+        super().__init__(name, description)
+        self.repo, self.pypi, self.docs = repo, pypi or name, docs or repo
+        self.version = version or _installed(self.pypi)
+        self.global_args, self.default = list(global_args), default  # default: command used when none is named
+        self.upgrade = upgrade  # optional () -> argv overriding how `update` upgrades (git checkouts, binaries...)
+        self.env_quiet = re.sub(r"\W", "_", name).upper() + "_QUIET"
+        self._builtins()
+
+    # --- built-in commands -------------------------------------------------------------------------------------
+    def _builtins(self):
+        @self.command("help", "Show help for a command", args=[Arg("topic", nargs="*", help="Command path")])
+        def _help(a):
+            self.print_help(a.topic)
+
+        @self.command("version", "Show version and repository")
+        def _version(a):
+            ui.out(self.version_text())
+
+        @self.command(
+            "update",
+            "Update to the latest version",
+            banner=True,
+            args=[Arg("--check", action="store_true", help="Only compare versions")],
+        )
+        def _update(a):
+            return self.update(a.check)
+
+    def version_text(self):
+        return f"{self.name} {self.version}\nrepo   {self.repo}\npython {sys.version.split()[0]}"
+
+    def update(self, check_only=False):
+        latest = latest_version(self.pypi)
+        ui.out(f"installed: {self.version}\nlatest:    {latest or 'unknown (offline or not published)'}")
+        if check_only:
+            return 0
+        if latest and latest == self.version:
+            ui.success("already up to date")
+            return 0
+        cmd = self.upgrade() if self.upgrade else upgrade_command(self.pypi)
+        ui.hint("running: " + " ".join(cmd))
+        return subprocess.call(cmd)
+
+    # --- help --------------------------------------------------------------------------------------------------
+    def print_help(self, path=()):
+        node, names = self, [self.name]
+        for p in path:
+            nxt = node.find(p)
+            if not nxt:
+                raise ui.Fail(
+                    f"Unknown command: {' '.join([*names[1:], p])}", f"Run `{self.name} help` to list commands.", 2
+                )
+            node = nxt
+            names.append(nxt.name)
+        ui.banner(self.name, self.version)
+        H = lambda s: ui.paint("brand", ui.bold(s))
+        C = lambda s: ui.paint("info", s)
+        use = " ".join(names)
+        leaf = not node.commands
+        line = f"{use} <command> [options]" if not leaf else f"{use}{_usage(node.args)} [options]"
+        lines = [line, ""]
+        if node.help:
+            lines += [node.help, ""]
+        if node.commands:
+            lines.append(H("Commands"))
+            cmds = sorted(
+                (c for c in node.commands.values() if not c.hidden), key=lambda c: c.name in _BUILTIN and node is self
+            )
+            rows = [(f"{use} {c.name}", c.help) for c in cmds]
+            lines += _cols(rows, C)
+            lines.append("")
+        shown = (node.args if node.help_args is None else node.help_args) if leaf else self.global_args
+        if shown and (leaf or node is self):
+            sections: dict[str, list] = {}
+            for a in shown:
+                sections.setdefault(a.group or "Options", []).append(a.row())
+            for title, rows in sections.items():
+                lines += [H(title), *_cols(rows, C), ""]
+        lines.append(H("Global flags"))
+        lines += _cols(
+            [
+                ("-q, --quiet", "Suppress non-essential output [boolean] [default: false]"),
+                ("-h, --help", "Show help [boolean]"),
+            ]
+            + ([("-v, --version", "Show version [boolean]")] if node is self else []),
+            C,
+        )
+        lines += ["", ui.paint("muted", f"For more information, visit {self.docs}")]
+        ui.out("\n".join(lines))
+
+    # --- run ---------------------------------------------------------------------------------------------------
+    def run(self, argv=None):
+        argv = list(sys.argv[1:] if argv is None else argv)
+        try:
+            return self._run(argv) or 0
+        except ui.Fail as e:
+            ui.error_box(e, e.hint)
+            return e.code
+        except (ui.Cancel, KeyboardInterrupt):
+            return 130
+        except BrokenPipeError:
+            return 0
+        except SystemExit as e:
+            if isinstance(e.code, str):  # legacy `sys.exit("message")` becomes a boxed error
+                ui.error_box(e.code)
+                return 1
+            return e.code or 0
+
+    def _run(self, argv):
+        if argv[:1] in (["-v"], ["--version"]):
+            ui.out(self.version_text())
+            return 0
+        raw = self.find(argv[0]) if argv else None
+        if raw is not None and raw.raw:  # passthrough commands see the rest of argv untouched
+            ui.quiet = bool(os.environ.get(self.env_quiet))
+            r = raw.fn(argparse.Namespace(args=argv[1:]))
+            return asyncio.run(r) if inspect.iscoroutine(r) else r
+        g = _Parser(add_help=False, allow_abbrev=False, prog=self.name)
+        g.add_argument("-q", "--quiet", action="store_true")
+        g.add_argument("-h", "--help", action="store_true")
+        for a in self.global_args:
+            a.add_to(g)
+        gns, rest = g.parse_known_args(argv)
+        ui.quiet = gns.quiet or bool(os.environ.get(self.env_quiet))
+        node, names = self, [self.name]
+        if self.default and not gns.help and (rest or not sys.stdin.isatty()) and (not rest or rest[0].startswith("-")):
+            rest = [self.default, *rest]
+        while rest and node.commands and not rest[0].startswith("-"):
+            nxt = node.find(rest[0])
+            if not nxt:
+                raise ui.Fail(f"Unknown command: {rest[0]}", f"Run `{' '.join(names)} --help` to list commands.", 2)
+            node, rest = nxt, rest[1:]
+            names.append(node.name)
+        if node.commands:  # root or group without a verb
+            if rest:
+                raise ui.Fail(f"Unknown option: {rest[0]}", f"Run `{' '.join(names)} --help` for usage.", 2)
+            self.print_help(names[1:])
+            return 0
+        if gns.help:
+            self.print_help(names[1:])
+            return 0
+        p = _Parser(add_help=False, allow_abbrev=False, prog=" ".join(names))
+        for a in node.args:
+            a.add_to(p)
+        ns = p.parse_args(rest)
+        for k, v in vars(gns).items():
+            setattr(ns, k, v)
+        for a in node.args:
+            if a.required and getattr(ns, a.dest, None) in (None, [], ""):
+                if node.banner:
+                    ui.banner(self.name, self.version)
+                flag = a.flags[0] if a.positional else max(a.flags, key=len)
+                v = ui.need(
+                    None,
+                    flag,
+                    a.prompt or a.dest.replace("_", " ").capitalize(),
+                    positional=a.positional,
+                    secret=a.secret,
+                    choices=a.kw.get("choices"),
+                    default=a.kw.get("default"),
+                )
+                setattr(ns, a.dest, _convert(a, v, flag))
+        if node.banner:
+            ui.banner(self.name, self.version)
+        r = node.fn(ns)
+        return asyncio.run(r) if inspect.iscoroutine(r) else r
+
+    def main(self, argv=None):
+        sys.exit(self.run(argv))
+
+
+def _convert(a, v, flag):
+    t = a.kw.get("type")
+    try:
+        if a.kw.get("nargs") in ("+", "*"):  # prompted text becomes a list
+            return [t(x) if t else x for x in v.replace(",", " ").split()]
+        return t(v) if t and isinstance(v, str) else v
+    except (ValueError, TypeError, argparse.ArgumentTypeError) as e:
+        raise ui.Fail(f"Invalid value for {flag}: {v!r} ({e})", code=2) from None
+
+
+def _usage(args):
+    return "".join(" " + a._pname() for a in args if a.positional)
+
+
+def _cols(rows, style):
+    width = min(max((len(left) for left, _ in rows), default=0), 36)
+    cols = shutil.get_terminal_size((100, 24)).columns
+    out = []
+    for left, right in rows:
+        wrapped = textwrap.wrap(right, max(cols - width - 4, 30)) or [""]
+        out.append(f"  {style(left)}{' ' * (width - len(left) + 2)}{wrapped[0]}")
+        out += [f"  {' ' * (width + 2)}{w}" for w in wrapped[1:]]
+    return out
+
+
+def _installed(pkg):
+    try:
+        return importlib.metadata.version(pkg)
+    except importlib.metadata.PackageNotFoundError:
+        return "unknown"
+
+
+def latest_version(pkg):
+    try:
+        with urllib.request.urlopen(f"https://pypi.org/pypi/{pkg}/json", timeout=5) as r:
+            return json.load(r)["info"]["version"]
+    except Exception:
+        return None
+
+
+def upgrade_command(pkg):
+    exe = sys.executable.replace("\\", "/")
+    if "/uv/tools/" in exe and shutil.which("uv"):
+        return ["uv", "tool", "upgrade", pkg]
+    if "/pipx/" in exe and shutil.which("pipx"):
+        return ["pipx", "upgrade", pkg]
+    return [sys.executable, "-m", "pip", "install", "-U", pkg]