usecli 0.1.74__tar.gz → 0.1.75__tar.gz

{usecli-0.1.74 → usecli-0.1.75}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usecli
-Version: 0.1.74
+Version: 0.1.75
 Summary: A powerful Python CLI framework for building beautiful, developer-friendly command-line tools.
 Author: Edward Boswell
 Author-email: Edward Boswell <thememium@gmail.com>
@@ -166,17 +166,75 @@ def signature(self) -> str:
     return "spec show"   # usecli spec show
 ```
 
+### JSON Output
+
+Every command inherits `--json`; commands do not declare the option themselves. The flag works before or after a command name:
+
+```sh
+usecli --json about
+usecli about --json
+```
+
+A successful invocation writes exactly one JSON document to stdout:
+
+```json
+{"ok":true,"data":null}
+```
+
+A command can return any JSON-serializable value to populate `data`:
+
+```python
+class StatusCommand(BaseCommand):
+    def signature(self) -> str:
+        return "status"
+
+    def description(self) -> str:
+        return "Show service status"
+
+    def handle(self):
+        return {"status": "ready", "workers": 3}
+```
+
+Failures preserve a non-zero exit status and use a stable error envelope:
+
+```json
+{"ok":false,"error":{"type":"UsageError","message":"No such command","code":2}}
+```
+
+In JSON mode, stdout is reserved for that document. Human-facing output, including `console.print()` and ordinary `print()`, is routed to stderr. Prompts and confirmations resolve their declared defaults without reading stdin. A prompt without a default, menus, and `--interactive` fail immediately with a structured `NonInteractiveError` instead of blocking.
+
+The existing fields `ok`, `data`, `error`, `error.type`, `error.message`, and `error.code` keep their names and types across compatible releases. New fields may be added.
+
 ### UI Components
 
 ```python
-from usecli import console, Prompt, Confirm, Menu
+from usecli import Confirm, Menu, Prompt, console
 
 console.print("[green]Done![/green]")
 name = Prompt.ask("Enter name")
 ok = Confirm.ask("Continue?")
-choice = Menu(["A", "B", "C"]).show()
+choice = Menu.select(["A", "B", "C"])
+```
+
+### Progress Indicators
+
+Use `Spinner` when the amount of work is unknown and `ProgressBar` when a total is known:
+
+```python
+from usecli import ProgressBar, Spinner
+
+with Spinner("Loading records") as spinner:
+    load_records()
+    spinner.update("Indexing records")
+
+with ProgressBar(total=len(items), description="Processing") as progress:
+    for item in items:
+        process(item)
+        progress.advance()
 ```
 
+Progress always renders to stderr, uses the active usecli theme, and is suppressed automatically in JSON mode, with `quiet=True`, or when stderr is not attached to a terminal. Calling commands do not need to detect these conditions.
+
 ### Available Commands
 
 ```

{usecli-0.1.74 → usecli-0.1.75}/README.md

@@ -138,17 +138,75 @@ def signature(self) -> str:
     return "spec show"   # usecli spec show
 ```
 
+### JSON Output
+
+Every command inherits `--json`; commands do not declare the option themselves. The flag works before or after a command name:
+
+```sh
+usecli --json about
+usecli about --json
+```
+
+A successful invocation writes exactly one JSON document to stdout:
+
+```json
+{"ok":true,"data":null}
+```
+
+A command can return any JSON-serializable value to populate `data`:
+
+```python
+class StatusCommand(BaseCommand):
+    def signature(self) -> str:
+        return "status"
+
+    def description(self) -> str:
+        return "Show service status"
+
+    def handle(self):
+        return {"status": "ready", "workers": 3}
+```
+
+Failures preserve a non-zero exit status and use a stable error envelope:
+
+```json
+{"ok":false,"error":{"type":"UsageError","message":"No such command","code":2}}
+```
+
+In JSON mode, stdout is reserved for that document. Human-facing output, including `console.print()` and ordinary `print()`, is routed to stderr. Prompts and confirmations resolve their declared defaults without reading stdin. A prompt without a default, menus, and `--interactive` fail immediately with a structured `NonInteractiveError` instead of blocking.
+
+The existing fields `ok`, `data`, `error`, `error.type`, `error.message`, and `error.code` keep their names and types across compatible releases. New fields may be added.
+
 ### UI Components
 
 ```python
-from usecli import console, Prompt, Confirm, Menu
+from usecli import Confirm, Menu, Prompt, console
 
 console.print("[green]Done![/green]")
 name = Prompt.ask("Enter name")
 ok = Confirm.ask("Continue?")
-choice = Menu(["A", "B", "C"]).show()
+choice = Menu.select(["A", "B", "C"])
+```
+
+### Progress Indicators
+
+Use `Spinner` when the amount of work is unknown and `ProgressBar` when a total is known:
+
+```python
+from usecli import ProgressBar, Spinner
+
+with Spinner("Loading records") as spinner:
+    load_records()
+    spinner.update("Indexing records")
+
+with ProgressBar(total=len(items), description="Processing") as progress:
+    for item in items:
+        process(item)
+        progress.advance()
 ```
 
+Progress always renders to stderr, uses the active usecli theme, and is suppressed automatically in JSON mode, with `quiet=True`, or when stderr is not attached to a terminal. Calling commands do not need to detect these conditions.
+
 ### Available Commands
 
 ```

{usecli-0.1.74 → usecli-0.1.75}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usecli"
-version = "0.1.74"
+version = "0.1.75"
 description = "A powerful Python CLI framework for building beautiful, developer-friendly command-line tools."
 readme = "README.md"
 authors = [{ name = "Edward Boswell", email = "thememium@gmail.com" }]

{usecli-0.1.74 → usecli-0.1.75}/src/usecli/__init__.py

@@ -20,6 +20,7 @@ if TYPE_CHECKING:
     from usecli.cli.core.base_command import BaseCommand
     from usecli.menu import Menu
     from usecli.params import Argument, Option
+    from usecli.progress import ProgressBar, Spinner
     from usecli.ui import Confirm, Prompt
 
     console: Console
@@ -37,6 +38,8 @@ _LAZY_EXPORTS = {
     "Confirm": ("usecli.ui", "Confirm"),
     "Console": ("usecli.ui", "Console"),
     "console": ("usecli.ui", "console"),
+    "Spinner": ("usecli.progress", "Spinner"),
+    "ProgressBar": ("usecli.progress", "ProgressBar"),
 }
 
 
@@ -155,18 +158,120 @@ def _ensure_cli_initialized() -> None:
             windows_expand_args=True,
             **extra,
         ):
-            return super().main(
-                args=args,
-                prog_name=prog_name,
-                complete_var=complete_var,
-                standalone_mode=False,
-                windows_expand_args=windows_expand_args,
-                **extra,
+            cli_args = list(args) if args is not None else sys.argv[1:]
+            option_args = (
+                cli_args[: cli_args.index("--")] if "--" in cli_args else cli_args
             )
+            if "--json" not in option_args:
+                return super().main(
+                    args=args,
+                    prog_name=prog_name,
+                    complete_var=complete_var,
+                    standalone_mode=False,
+                    windows_expand_args=windows_expand_args,
+                    **extra,
+                )
+
+            from contextlib import redirect_stdout
+
+            from usecli.cli.core.runtime import (
+                InvocationExit,
+                JSONSerializationError,
+                NonInteractiveError,
+                error_document,
+                execution_context,
+                serialize_document,
+                success_document,
+            )
+
+            original_stdout = sys.stdout
+            _TyperBadParameter = globals()["_TyperBadParameter"]
+            _TyperUsageError = globals()["_TyperUsageError"]
+            _TyperClickException = globals()["_TyperClickException"]
+
+            def write_document(document):
+                original_stdout.write(serialize_document(document))
+                original_stdout.flush()
+
+            def fail(error_type: str, message: str, code: int):
+                write_document(
+                    error_document(
+                        error_type=error_type,
+                        message=message,
+                        code=code,
+                    )
+                )
+                raise SystemExit(code)
+
+            with execution_context(json_mode=True):
+                try:
+                    with redirect_stdout(sys.stderr):
+                        result = super().main(
+                            args=args,
+                            prog_name=prog_name,
+                            complete_var=complete_var,
+                            standalone_mode=False,
+                            windows_expand_args=windows_expand_args,
+                            **extra,
+                        )
+                    write_document(success_document(result))
+                    return result
+                except InvocationExit as error:
+                    if error.code == 0:
+                        write_document(success_document())
+                        return None
+                    fail("Exit", str(error), error.code)
+                except Exit as error:
+                    code = error.exit_code
+                    if code == 0:
+                        write_document(success_document())
+                        return None
+                    fail("Exit", f"Command exited with status {code}", code)
+                except JSONSerializationError as error:
+                    print(f"JSONSerializationError: {error}", file=sys.stderr)
+                    fail("JSONSerializationError", str(error), 1)
+                except NonInteractiveError as error:
+                    print(f"NonInteractiveError: {error}", file=sys.stderr)
+                    fail("NonInteractiveError", str(error), error.code)
+                except (_TyperBadParameter, BadParameter) as error:
+                    error.show(file=sys.stderr)
+                    fail("BadParameter", error.format_message(), error.exit_code)
+                except (_TyperUsageError, UsageError) as error:
+                    error.show(file=sys.stderr)
+                    fail("UsageError", error.format_message(), error.exit_code)
+                except (_TyperClickException, ClickException) as error:
+                    error.show(file=sys.stderr)
+                    fail(
+                        error.__class__.__name__,
+                        error.format_message(),
+                        error.exit_code,
+                    )
+                except SystemExit as error:
+                    code = error.code if isinstance(error.code, int) else 1
+                    if code == 0:
+                        write_document(success_document())
+                        return None
+                    fail("Exit", f"Command exited with status {code}", code)
+                except Exception as error:
+                    print(
+                        f"{error.__class__.__name__}: {error}",
+                        file=sys.stderr,
+                    )
+                    fail(error.__class__.__name__, str(error), 1)
 
         def invoke(self, ctx):
             from click.exceptions import Exit
 
+            from usecli.cli.core.runtime import is_json_mode
+
+            if is_json_mode():
+                from usecli.cli.core.runtime import InvocationExit
+
+                try:
+                    return super().invoke(ctx)
+                except Exit as error:
+                    raise InvocationExit(error.exit_code) from error
+
             _TyperBadParameter = globals()["_TyperBadParameter"]
             _TyperUsageError = globals()["_TyperUsageError"]
             _TyperClickException = globals()["_TyperClickException"]
@@ -245,6 +350,8 @@ __all__ = [
     "Option",
     "Prompt",
     "Confirm",
+    "Spinner",
+    "ProgressBar",
     "colors",
     "theme",
 ]
@@ -356,12 +463,12 @@ class _FilteredListCommand:
     def invoke(self, ctx):
         from usecli.cli.core.ui.list import list_commands
 
-        list_commands(_get_app(), prefix_filter=self.prefix_filter)
+        return list_commands(_get_app(), prefix_filter=self.prefix_filter)
 
     def __call__(self, *args, **kwargs):
         from usecli.cli.core.ui.list import list_commands
 
-        list_commands(_get_app(), prefix_filter=self.prefix_filter)
+        return list_commands(_get_app(), prefix_filter=self.prefix_filter)
 
 
 def _get_default_help() -> str:
@@ -397,13 +504,23 @@ def _get_run_app_callback():
         interactive: bool = typer.Option(
             False, "--interactive", "-i", help="Run in interactive mode.", is_eager=True
         ),
-    ) -> None:
+        json_output: bool = typer.Option(
+            False,
+            "--json",
+            help="Emit one machine-readable JSON document.",
+            is_eager=True,
+        ),
+    ) -> object:
         _resolve_help()
 
         if help:
             from usecli.cli.core.ui.list import list_commands
 
-            list_commands(_get_app())
+            data = list_commands(_get_app())
+            from usecli.cli.core.runtime import is_json_mode
+
+            if is_json_mode():
+                return data
             raise typer.Exit()
 
         if version:
@@ -421,6 +538,13 @@ def _get_run_app_callback():
 
         interactive_requested = interactive or _is_interactive_flag_present()
 
+        from usecli.cli.core.runtime import is_json_mode
+
+        if interactive_requested and is_json_mode():
+            from usecli.cli.core.runtime import NonInteractiveError
+
+            raise NonInteractiveError("Interactive mode is unavailable in JSON mode")
+
         if interactive_requested:
             from usecli.cli.commands.defaults.base.internal.fzf_command import (
                 run_interactive,
@@ -436,7 +560,7 @@ def _get_run_app_callback():
                 prefix_filter = ctx.obj.get("prefix_filter")
             from usecli.cli.core.ui.list import list_commands
 
-            list_commands(_get_app(), prefix_filter=prefix_filter)
+            return list_commands(_get_app(), prefix_filter=prefix_filter)
 
     globals()["run_app"] = run_app
     return run_app

{usecli-0.1.74 → usecli-0.1.75}/src/usecli/cli/commands/defaults/base/about_command.py

@@ -257,7 +257,9 @@ class AboutCommand(BaseCommand):
     def description(self) -> str:
         return "Display detailed information about the application"
 
-    def handle(self) -> None:
+    def handle(self) -> dict[str, object]:
+        import platform
+
         config = get_config()
         version = _get_application_version(config)
         from usecli.cli.core.ui.title import get_project_name
@@ -265,6 +267,38 @@ class AboutCommand(BaseCommand):
         app_name = get_project_name()
         description = _get_application_description(config)
 
+        dist = _get_application_distribution()
+        name_label = "Cli Name" if dist is not None else "Application Name"
+        version_label = "Cli Version" if dist is not None else "Application Version"
+
+        script_commands = _get_script_commands() or ["usecli"]
+
+        deps = _get_dependencies(config)
+        dependencies: list[dict[str, str | None]] = []
+        for dep_name, spec in deps:
+            try:
+                from importlib.metadata import version as get_version
+
+                installed_version = get_version(dep_name)
+                dependencies.append({"name": dep_name, "version": installed_version})
+            except Exception:
+                dependencies.append({"name": dep_name, "version": spec})
+
+        data: dict[str, object] = {
+            "name": app_name,
+            "version": version,
+            "description": description,
+            "python_version": platform.python_version(),
+            "platform": platform.platform(),
+            "entry_points": script_commands,
+            "dependencies": dependencies,
+        }
+
+        from usecli.cli.core.runtime import is_json_mode
+
+        if is_json_mode():
+            return data
+
         console.print()
         console.print(f"[bold {COLOR.PRIMARY}]Description[/bold {COLOR.PRIMARY}]")
         console.print(f"[{COLOR.PRIMARY}]─" * 78)
@@ -273,22 +307,14 @@ class AboutCommand(BaseCommand):
         console.print()
         console.print(f"[bold {COLOR.PRIMARY}]Environment[/bold {COLOR.PRIMARY}]")
         console.print(f"[{COLOR.PRIMARY}]─" * 78)
-
-        dist = _get_application_distribution()
-        name_label = "Cli Name" if dist is not None else "Application Name"
-        version_label = "Cli Version" if dist is not None else "Application Version"
         self._print_row(name_label, app_name)
         self._print_row(version_label, version)
-        import platform
-
         self._print_row("Python Version", platform.python_version())
         self._print_row("Platform", f"[{COLOR.FOREGROUND_MUTED}]{platform.platform()}")
 
         console.print()
         console.print(f"[bold {COLOR.PRIMARY}]Entry Points[/bold {COLOR.PRIMARY}]")
         console.print(f"[{COLOR.PRIMARY}]─" * 78)
-
-        script_commands = _get_script_commands() or ["usecli"]
         for index, command in enumerate(script_commands):
             label = "Primary command" if index == 0 else "Command"
             self._print_row(command, label)
@@ -296,8 +322,6 @@ class AboutCommand(BaseCommand):
         console.print()
         console.print(f"[bold {COLOR.PRIMARY}]Dependencies[/bold {COLOR.PRIMARY}]")
         console.print(f"[{COLOR.PRIMARY}]─" * 78)
-
-        deps = _get_dependencies(config)
         if deps:
             for dep_name, spec in deps:
                 try:
@@ -313,17 +337,10 @@ class AboutCommand(BaseCommand):
         else:
             self._print_row("Dependencies", "unable to load")
 
-        # console.print()
-        # console.print(f"[bold {COLOR.PRIMARY}]Features[/bold {COLOR.PRIMARY}]")
-        # console.print(f"[{COLOR.PRIMARY}]─" * 78)
-        #
-        # self._print_row("Prefix Matching", f"[{COLOR.SECONDARY}]ENABLED")
-        # self._print_row("Rich UI", f"[{COLOR.SECONDARY}]ENABLED")
-        # self._print_row("Command Scaffolding", f"[{COLOR.SECONDARY}]ENABLED")
-        # self._print_row("Interactive Menus", f"[{COLOR.SECONDARY}]ENABLED")
-        # self._print_row("Fuzzy Finder", f"[{COLOR.SECONDARY}]ENABLED")
         console.print()
 
+        return data
+
     def _print_row(self, label: str, value: str) -> None:
         visible_value = console.render_str(value).plain
         right_align_column = 76

{usecli-0.1.74 → usecli-0.1.75}/src/usecli/cli/commands/defaults/base/inspire_command.py

@@ -24,7 +24,7 @@ class InspireCommand(BaseCommand):
         """Return the command description."""
         return "Show a random inspirational quote"
 
-    def handle(self) -> None:
+    def handle(self) -> dict[str, str]:
         """Handle the command execution."""
 
         quotes = [
@@ -73,6 +73,13 @@ class InspireCommand(BaseCommand):
         selected = random.choice(quotes)
         quote, author = selected.rsplit(" - ", 1)
 
+        data = {"quote": quote, "author": author}
+
+        from usecli.cli.core.runtime import is_json_mode
+
+        if is_json_mode():
+            return data
+
         from rich.console import Console
         from rich.panel import Panel
 
@@ -84,3 +91,5 @@ class InspireCommand(BaseCommand):
                 title_align="left",
             )
         )
+
+        return data

{usecli-0.1.74 → usecli-0.1.75}/src/usecli/cli/commands/defaults/base/internal/fzf_command.py

@@ -90,6 +90,8 @@ def _get_optional_options(
             continue
         if "--interactive" in option_names or "-i" in option_names:
             continue
+        if "--json" in option_names:
+            continue
 
         help_text = param.help or ""
         param_name = param.name or ""