usecli 0.2.5__tar.gz → 0.2.7__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. {usecli-0.2.5 → usecli-0.2.7}/PKG-INFO +32 -2
  2. {usecli-0.2.5 → usecli-0.2.7}/README.md +31 -1
  3. {usecli-0.2.5 → usecli-0.2.7}/pyproject.toml +1 -1
  4. {usecli-0.2.5 → usecli-0.2.7}/pyproject.toml.orig +1 -1
  5. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/__init__.py +89 -5
  6. usecli-0.2.7/src/usecli/_rich_exports.py +73 -0
  7. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/base_command.py +17 -2
  8. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/exceptions/usage.py +11 -0
  9. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/ui/title.py +6 -6
  10. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/templates/usecli.config.toml.j2 +3 -1
  11. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/progress.py +79 -6
  12. usecli-0.2.7/src/usecli/rich.py +71 -0
  13. usecli-0.2.7/src/usecli/ui.py +476 -0
  14. usecli-0.2.5/src/usecli/ui.py +0 -104
  15. {usecli-0.2.5 → usecli-0.2.7}/LICENSE +0 -0
  16. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/bundler/__init__.py +0 -0
  17. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/bundler/__main__.py +0 -0
  18. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/__init__.py +0 -0
  19. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/README.md +0 -0
  20. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/__init__.py +0 -0
  21. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/custom/README.md +0 -0
  22. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/custom/__init__.py +0 -0
  23. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/__init__.py +0 -0
  24. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/base/__init__.py +0 -0
  25. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/base/about_command.py +0 -0
  26. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/base/help_command.py +0 -0
  27. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/base/inspire_command.py +0 -0
  28. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/base/internal/__init__.py +0 -0
  29. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/base/internal/interactive_command.py +0 -0
  30. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/base/upgrade_command.py +0 -0
  31. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/core/__init__.py +0 -0
  32. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/core/utils.py +0 -0
  33. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/make/__init__.py +0 -0
  34. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/make/make_bundle_command.py +0 -0
  35. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/make/make_command.py +0 -0
  36. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/defaults/make/make_theme_command.py +0 -0
  37. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/commands/init_command.py +0 -0
  38. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/config/__init__.py +0 -0
  39. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/config/colors.py +0 -0
  40. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/__init__.py +0 -0
  41. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/_typer_compat.py +0 -0
  42. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/error/__init__.py +0 -0
  43. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/error/handler.py +0 -0
  44. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/error/utils.py +0 -0
  45. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/exceptions/__init__.py +0 -0
  46. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/exceptions/base.py +0 -0
  47. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/exceptions/config.py +0 -0
  48. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/exceptions/validation.py +0 -0
  49. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/runtime.py +0 -0
  50. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/ui/__init__.py +0 -0
  51. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/ui/list.py +0 -0
  52. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/ui/title.txt +0 -0
  53. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/validators/__init__.py +0 -0
  54. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/validators/network.py +0 -0
  55. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/validators/numeric.py +0 -0
  56. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/validators/path.py +0 -0
  57. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/core/validators/string.py +0 -0
  58. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/services/__init__.py +0 -0
  59. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/services/command_service.py +0 -0
  60. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/templates/command.py.j2 +0 -0
  61. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/templates/theme.toml.j2 +0 -0
  62. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/themes/ayu_dark.toml +0 -0
  63. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/themes/catppuccin_frappe.toml +0 -0
  64. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/themes/catppuccin_latte.toml +0 -0
  65. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/themes/catppuccin_macchiato.toml +0 -0
  66. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/themes/catppuccin_mocha.toml +0 -0
  67. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/themes/default.toml +0 -0
  68. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/themes/dracula.toml +0 -0
  69. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/themes/gruvbox_dark.toml +0 -0
  70. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/themes/nord.toml +0 -0
  71. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/themes/tokyo_night.toml +0 -0
  72. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/utils/__init__.py +0 -0
  73. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/utils/interactive/__init__.py +0 -0
  74. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/utils/interactive/prompt_input.py +0 -0
  75. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/cli/utils/interactive/terminal_menu.py +0 -0
  76. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/entry.py +0 -0
  77. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/menu.py +0 -0
  78. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/params.py +0 -0
  79. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/shared/__init__.py +0 -0
  80. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/shared/config/__init__.py +0 -0
  81. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/shared/config/globals.py +0 -0
  82. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/shared/config/manager.py +0 -0
  83. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/shared/upgrades/__init__.py +0 -0
  84. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/shared/upgrades/checker.py +0 -0
  85. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/shared/upgrades/discovery.py +0 -0
  86. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/shared/upgrades/installer.py +0 -0
  87. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/shared/upgrades/pyproject.py +0 -0
  88. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/shared/upgrades/service.py +0 -0
  89. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/shared/upgrades/settings.py +0 -0
  90. {usecli-0.2.5 → usecli-0.2.7}/src/usecli/usecli.config.toml +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: usecli
3
- Version: 0.2.5
3
+ Version: 0.2.7
4
4
  Summary: A powerful Python CLI framework for building beautiful, developer-friendly command-line tools.
5
5
  Author: Edward Boswell
6
6
  Author-email: Edward Boswell <thememium@gmail.com>
@@ -233,10 +233,40 @@ from usecli import Confirm, Menu, Prompt, console
233
233
 
234
234
  console.print("[green]Done![/green]")
235
235
  name = Prompt.ask("Enter name")
236
- ok = Confirm.ask("Continue?")
236
+ port = Prompt.ask("Port", type="int", default=8000)
237
+ ratio = Prompt.ask("Ratio", type="float", default=0.5)
238
+ token = Prompt.ask("API token", password=True)
239
+ masked = Prompt.ask("PIN", mask="*")
240
+ mode = Prompt.ask("Mode [a/b/c]", choices=["a", "b", "c"], single_key=True)
241
+ ok = Confirm.ask("Continue?", single_key=True)
237
242
  choice = Menu.select(["A", "B", "C"])
238
243
  ```
239
244
 
245
+ `Prompt.ask(type=...)` parses `"string"` (default), `"int"`, or `"float"`.
246
+ `password=True` hides input entirely; `mask="*"` echoes one mask character per
247
+ keystroke (and wins if both are supplied) and falls back to hidden input
248
+ without a terminal. Single-key
249
+ `Prompt.ask(..., single_key=True)` answers single-character choices on the
250
+ first keypress; `Confirm.ask(..., single_key=True)` does the same for `y`/`n`.
251
+ Without the flag both keep Rich's line-based prompt, and non-terminal
252
+ stdin/stdout always falls back to line input. In JSON mode prompts return their
253
+ declared default or raise `NonInteractiveError`.
254
+
255
+ Rich renderables are re-exported, so commands never import `rich` directly:
256
+
257
+ ```python
258
+ from usecli import Markdown, Panel, Syntax, Table, Tree
259
+
260
+ console.print(Panel(Markdown("# Report")))
261
+ console.print(Syntax(source, "python"))
262
+ ```
263
+
264
+ `from usecli.rich import ...` exposes the same set as an explicit namespace. All
265
+ Rich console, text, layout, progress, and prompt components are covered
266
+ (`Table`, `Tree`, `Panel`, `Rule`, `Layout`, `Live`, `Progress`, `Pretty`,
267
+ `JSON`, `Traceback`, and the rest); imports stay lazy, so `import usecli` does
268
+ not load Rich.
269
+
240
270
  ### Progress Indicators
241
271
 
242
272
  Use `Spinner` when the amount of work is unknown and `ProgressBar` when a total is known:
@@ -203,10 +203,40 @@ from usecli import Confirm, Menu, Prompt, console
203
203
 
204
204
  console.print("[green]Done![/green]")
205
205
  name = Prompt.ask("Enter name")
206
- ok = Confirm.ask("Continue?")
206
+ port = Prompt.ask("Port", type="int", default=8000)
207
+ ratio = Prompt.ask("Ratio", type="float", default=0.5)
208
+ token = Prompt.ask("API token", password=True)
209
+ masked = Prompt.ask("PIN", mask="*")
210
+ mode = Prompt.ask("Mode [a/b/c]", choices=["a", "b", "c"], single_key=True)
211
+ ok = Confirm.ask("Continue?", single_key=True)
207
212
  choice = Menu.select(["A", "B", "C"])
208
213
  ```
209
214
 
215
+ `Prompt.ask(type=...)` parses `"string"` (default), `"int"`, or `"float"`.
216
+ `password=True` hides input entirely; `mask="*"` echoes one mask character per
217
+ keystroke (and wins if both are supplied) and falls back to hidden input
218
+ without a terminal. Single-key
219
+ `Prompt.ask(..., single_key=True)` answers single-character choices on the
220
+ first keypress; `Confirm.ask(..., single_key=True)` does the same for `y`/`n`.
221
+ Without the flag both keep Rich's line-based prompt, and non-terminal
222
+ stdin/stdout always falls back to line input. In JSON mode prompts return their
223
+ declared default or raise `NonInteractiveError`.
224
+
225
+ Rich renderables are re-exported, so commands never import `rich` directly:
226
+
227
+ ```python
228
+ from usecli import Markdown, Panel, Syntax, Table, Tree
229
+
230
+ console.print(Panel(Markdown("# Report")))
231
+ console.print(Syntax(source, "python"))
232
+ ```
233
+
234
+ `from usecli.rich import ...` exposes the same set as an explicit namespace. All
235
+ Rich console, text, layout, progress, and prompt components are covered
236
+ (`Table`, `Tree`, `Panel`, `Rule`, `Layout`, `Live`, `Progress`, `Pretty`,
237
+ `JSON`, `Traceback`, and the rest); imports stay lazy, so `import usecli` does
238
+ not load Rich.
239
+
210
240
  ### Progress Indicators
211
241
 
212
242
  Use `Spinner` when the amount of work is unknown and `ProgressBar` when a total is known:
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "usecli"
3
- version = "0.2.5"
3
+ version = "0.2.7"
4
4
  description = "A powerful Python CLI framework for building beautiful, developer-friendly command-line tools."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "usecli"
3
- version = "0.2.5"
3
+ version = "0.2.7"
4
4
  description = "A powerful Python CLI framework for building beautiful, developer-friendly command-line tools."
5
5
  readme = "README.md"
6
6
  authors = [{ name = "Edward Boswell", email = "thememium@gmail.com" }]
@@ -5,27 +5,87 @@ from __future__ import annotations
5
5
  import sys
6
6
  from importlib import import_module
7
7
 
8
+ # `typing` is already imported by click, so TYPE_CHECKING costs nothing extra.
9
+ # The block below gives type checkers concrete types for the lazy exports; the
10
+ # module `__getattr__` returns `Any` at runtime only.
11
+ from typing import TYPE_CHECKING
12
+
8
13
  from click import Command as _ClickCommand
9
14
 
10
- # Avoid importing typing at module level (costs ~6ms)
11
- # TYPE_CHECKING is False at runtime, so the if-block never executes
12
- TYPE_CHECKING = False
15
+ from usecli._rich_exports import RICH_EXPORT_NAMES
13
16
 
14
17
  if TYPE_CHECKING:
18
+ from collections.abc import Callable
15
19
  from typing import Any
16
20
 
17
21
  import typer
18
- from rich.console import Console
19
22
 
20
23
  from usecli.cli.config.colors import COLOR
21
24
  from usecli.cli.config.colors import COLOR as theme
22
25
  from usecli.cli.core.base_command import BaseCommand
26
+ from usecli.cli.services.command_service import CommandService
23
27
  from usecli.menu import Menu
24
28
  from usecli.params import Argument, Option
25
29
  from usecli.progress import ProgressBar, Spinner
26
- from usecli.ui import Confirm, Prompt
30
+ from usecli.rich import ( # noqa: F401 - re-exported via __all__
31
+ JSON,
32
+ Align,
33
+ Bar,
34
+ BarColumn,
35
+ Column,
36
+ Columns,
37
+ ConsoleOptions,
38
+ ConsoleRenderable,
39
+ Control,
40
+ DownloadColumn,
41
+ Group,
42
+ Layout,
43
+ LayoutRender,
44
+ Live,
45
+ Markdown,
46
+ MofNCompleteColumn,
47
+ Padding,
48
+ Pretty,
49
+ Progress,
50
+ ProgressColumn,
51
+ RenderableType,
52
+ RenderHook,
53
+ RichCast,
54
+ Rule,
55
+ Screen,
56
+ Segment,
57
+ Span,
58
+ SpinnerColumn,
59
+ Status,
60
+ Style,
61
+ StyleType,
62
+ Syntax,
63
+ TaskID,
64
+ TaskProgressColumn,
65
+ TextColumn,
66
+ TextType,
67
+ Theme,
68
+ TimeElapsedColumn,
69
+ TimeRemainingColumn,
70
+ TotalFileSizeColumn,
71
+ Traceback,
72
+ TransferSpeedColumn,
73
+ Tree,
74
+ get_console,
75
+ inspect,
76
+ pprint,
77
+ print_json,
78
+ reconfigure,
79
+ track,
80
+ )
81
+ from usecli.ui import Confirm, Console, Panel, Prompt, Table, Text, box
82
+
83
+ # `print` must stay the builtin at runtime; this types only the re-export.
84
+ print: Callable[..., None]
27
85
 
28
86
  console: Console
87
+ app: typer.Typer
88
+ service: CommandService
29
89
 
30
90
  # Lazy module-level placeholders - these are populated on first access
31
91
  _app: Any = None
@@ -42,10 +102,20 @@ _LAZY_EXPORTS = {
42
102
  "console": ("usecli.ui", "console"),
43
103
  "Spinner": ("usecli.progress", "Spinner"),
44
104
  "ProgressBar": ("usecli.progress", "ProgressBar"),
105
+ "Table": ("usecli.ui", "Table"),
106
+ "Text": ("usecli.ui", "Text"),
107
+ "Panel": ("usecli.ui", "Panel"),
108
+ "box": ("usecli.ui", "box"),
45
109
  "pyinstaller": ("usecli.bundler", "pyinstaller"),
46
110
  "run": ("usecli.entry", "run"),
47
111
  }
48
112
 
113
+ _RICH_EXPORTS = frozenset(RICH_EXPORT_NAMES)
114
+
115
+ # `print` must not be cached in this module's globals: the CLI code below calls
116
+ # the builtin, and a cached rich.print would silently replace it.
117
+ _UNCACHED_RICH_EXPORTS = frozenset({"print"})
118
+
49
119
 
50
120
  def __getattr__(name: str) -> Any:
51
121
  # Handle lazy exports
@@ -56,6 +126,13 @@ def __getattr__(name: str) -> Any:
56
126
  globals()[name] = value
57
127
  return value
58
128
 
129
+ # Handle Rich components re-exported under the usecli namespace
130
+ if name in _RICH_EXPORTS:
131
+ value = getattr(import_module("usecli.rich"), name)
132
+ if name not in _UNCACHED_RICH_EXPORTS:
133
+ globals()[name] = value
134
+ return value
135
+
59
136
  # Handle CLI framework components - lazy initialization
60
137
  if name in ("app", "service", "BaseCommand", "colors", "COLOR", "theme"):
61
138
  _ensure_cli_initialized()
@@ -368,9 +445,13 @@ __all__ = [
368
445
  "Console",
369
446
  "Menu",
370
447
  "Option",
448
+ "Panel",
371
449
  "ProgressBar",
372
450
  "Prompt",
373
451
  "Spinner",
452
+ "Table",
453
+ "Text",
454
+ "box",
374
455
  "colors",
375
456
  "console",
376
457
  "main",
@@ -379,6 +460,9 @@ __all__ = [
379
460
  "theme",
380
461
  ]
381
462
 
463
+ # Rich components come from usecli.rich; skip names already listed above.
464
+ __all__ += [name for name in RICH_EXPORT_NAMES if name not in __all__]
465
+
382
466
 
383
467
  def _console():
384
468
  return __getattr__("console")
@@ -0,0 +1,73 @@
1
+ """Names of Rich components re-exported by :mod:`usecli`.
2
+
3
+ Kept import-free so the package root can test membership without pulling in
4
+ Rich. :mod:`usecli.rich` statically imports every name listed here, which also
5
+ lets PyInstaller discover the submodules (``collect_all("usecli")``).
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ RICH_EXPORT_NAMES: tuple[str, ...] = (
11
+ # Console and renderable plumbing
12
+ "Console",
13
+ "ConsoleOptions",
14
+ "ConsoleRenderable",
15
+ "Group",
16
+ "RenderableType",
17
+ "RenderHook",
18
+ "RichCast",
19
+ "get_console",
20
+ "reconfigure",
21
+ "print",
22
+ "print_json",
23
+ "inspect",
24
+ "box",
25
+ # Text, styles and themes
26
+ "Span",
27
+ "Style",
28
+ "StyleType",
29
+ "Text",
30
+ "TextType",
31
+ "Theme",
32
+ # Renderables
33
+ "Align",
34
+ "Bar",
35
+ "Column",
36
+ "Columns",
37
+ "Control",
38
+ "JSON",
39
+ "Layout",
40
+ "LayoutRender",
41
+ "Live",
42
+ "Markdown",
43
+ "Padding",
44
+ "Panel",
45
+ "Pretty",
46
+ "Rule",
47
+ "Screen",
48
+ "Segment",
49
+ "Status",
50
+ "Syntax",
51
+ "Table",
52
+ "Traceback",
53
+ "Tree",
54
+ "pprint",
55
+ # Progress
56
+ "Progress",
57
+ "ProgressColumn",
58
+ "TaskID",
59
+ "TextColumn",
60
+ "BarColumn",
61
+ "SpinnerColumn",
62
+ "TimeElapsedColumn",
63
+ "TimeRemainingColumn",
64
+ "MofNCompleteColumn",
65
+ "TaskProgressColumn",
66
+ "DownloadColumn",
67
+ "TransferSpeedColumn",
68
+ "TotalFileSizeColumn",
69
+ "track",
70
+ # Prompts
71
+ "Prompt",
72
+ "Confirm",
73
+ )
@@ -289,7 +289,13 @@ class CustomHelpCommand(TyperCommand):
289
289
  from usecli.cli.core.ui.title import get_script_command_name
290
290
 
291
291
  command_name = get_script_command_name(default="usecli") or "usecli"
292
- usage = f" [bold {COLOR.WARNING}]{command_name} {self.name}[/bold {COLOR.WARNING}] [bold {COLOR.PRIMARY}][OPTIONS]{f' {arg_usage}' if arg_usage else ''}[/bold {COLOR.PRIMARY}]"
292
+ # Use the invoked command path (without the program name) so nested
293
+ # commands print "mycli savings explain", not "mycli explain".
294
+ command_path = getattr(ctx, "command_path", None)
295
+ relative_path = (
296
+ " ".join(command_path.split()[1:]) if isinstance(command_path, str) else ""
297
+ )
298
+ usage = f" [bold {COLOR.WARNING}]{command_name} {relative_path or self.name or ''}[/bold {COLOR.WARNING}] [bold {COLOR.PRIMARY}][OPTIONS]{f' {arg_usage}' if arg_usage else ''}[/bold {COLOR.PRIMARY}]"
293
299
 
294
300
  console.print()
295
301
  console.print(f"[bold {COLOR.SECONDARY}]Usage:[/bold {COLOR.SECONDARY}]")
@@ -412,9 +418,18 @@ class BaseCommand(ABC):
412
418
  return parts[0]
413
419
 
414
420
  def is_hidden(self) -> bool:
415
- """Whether ``[usecli.commands] hidden`` lists this command name."""
421
+ """Whether ``[usecli.commands] hidden`` lists this command name.
422
+
423
+ Hiding is a project-CLI concern. The ``usecli`` framework binary always
424
+ exposes its built-ins, even when run inside a project whose config hides
425
+ them, so scaffolding commands stay reachable.
426
+ """
427
+ from usecli.cli.core.ui.title import running_framework_distribution
416
428
  from usecli.shared.config.manager import get_config
417
429
 
430
+ if running_framework_distribution() is not None:
431
+ return False
432
+
418
433
  hidden = get_config().get("commands.hidden", [])
419
434
  if isinstance(hidden, str):
420
435
  hidden = [hidden]
@@ -29,6 +29,17 @@ def _get_help_text_with_command_name(ctx: ClickContext) -> str:
29
29
  # usage error was about to set. The help has already been printed as a
30
30
  # side effect by that point, so it's safe to treat this as "no
31
31
  # additional help text to append" and let the caller continue.
32
+ #
33
+ # Nested contexts already carry the invoked name. Rewriting info_name to
34
+ # the program name there doubles the program in Click's usage line
35
+ # ("mycli mycli") and drops the parent group from leaf commands. Only
36
+ # the root context needs the program name substituted.
37
+ if getattr(ctx, "parent", None) is not None:
38
+ try:
39
+ return ctx.get_help()
40
+ except Exit:
41
+ return ""
42
+
32
43
  command_name = get_script_command_name(default=getattr(ctx, "info_name", None))
33
44
  if not command_name:
34
45
  try:
@@ -32,7 +32,7 @@ def _invoked_script_name() -> str | None:
32
32
  return name
33
33
 
34
34
 
35
- def _running_framework_distribution() -> Any | None:
35
+ def running_framework_distribution() -> Any | None:
36
36
  """Return the usecli distribution when running as one of its console scripts.
37
37
 
38
38
  The invoked console script decides the process identity: ``usecli`` (or
@@ -69,7 +69,7 @@ def get_framework_description() -> str | None:
69
69
  Returns ``None`` for downstream CLIs, whose config description owns the
70
70
  banner.
71
71
  """
72
- dist = _running_framework_distribution()
72
+ dist = running_framework_distribution()
73
73
  if dist is None:
74
74
  return None
75
75
  summary = dist.metadata.get("Summary")
@@ -125,7 +125,7 @@ def get_script_command_name(default: str | None = None) -> str | None:
125
125
  The usecli binary reports itself, not the project's CLI name: a user who
126
126
  typed ``usecli`` must see ``usecli`` in usage output.
127
127
  """
128
- if _running_framework_distribution() is not None:
128
+ if running_framework_distribution() is not None:
129
129
  return "usecli"
130
130
 
131
131
  config = get_config()
@@ -149,7 +149,7 @@ def get_project_name() -> str:
149
149
  The usecli binary reports the framework name; downstream CLIs report the
150
150
  title configured for their project.
151
151
  """
152
- if _running_framework_distribution() is not None:
152
+ if running_framework_distribution() is not None:
153
153
  return "useCli"
154
154
 
155
155
  # First, try to get the title from the config
@@ -206,7 +206,7 @@ def get_project_version() -> str | None:
206
206
  CLI resolves the distribution that owns the invoked console script first,
207
207
  then falls back to ``[project].version`` in the project's pyproject.toml.
208
208
  """
209
- framework_dist = _running_framework_distribution()
209
+ framework_dist = running_framework_distribution()
210
210
  if framework_dist is not None:
211
211
  return _distribution_version(framework_dist)
212
212
 
@@ -234,7 +234,7 @@ def _banner_config():
234
234
  the downstream project being scaffolded. Downstream CLIs keep using the
235
235
  discovered project config.
236
236
  """
237
- if _running_framework_distribution() is None:
237
+ if running_framework_distribution() is None:
238
238
  return get_config()
239
239
 
240
240
  from usecli.shared.config.globals import PACKAGE_ROOT
@@ -32,7 +32,9 @@ show_version = {{ show_version | default(true) | lower }}
32
32
  show_description = {{ show_description | default(true) | lower }}
33
33
 
34
34
  [usecli.commands]
35
- # Built-in commands to leave unregistered, for example ["inspire"].
35
+ # Built-in commands to leave unregistered for this project's CLI,
36
+ # for example ["inspire"]. The `usecli` framework binary always exposes
37
+ # its own built-in commands.
36
38
  hidden = []
37
39
 
38
40
  [usecli.upgrade]
@@ -1,4 +1,9 @@
1
- """Theme-aware progress indicators for usecli commands."""
1
+ """Theme-aware progress indicators for usecli commands.
2
+
3
+ Both indicators write to stderr and are suppressed automatically in JSON mode,
4
+ quiet mode, and non-interactive terminals. Prefer importing them from the
5
+ package root (``from usecli import ProgressBar, Spinner``).
6
+ """
2
7
 
3
8
  from __future__ import annotations
4
9
 
@@ -28,7 +33,34 @@ def _is_disabled(console: Console, *, quiet: bool) -> bool:
28
33
 
29
34
 
30
35
  class Spinner:
31
- """Indeterminate progress indicator that renders only to terminal stderr."""
36
+ """Indeterminate progress indicator for work with no known total.
37
+
38
+ Renders a transient spinner and status message to stderr using the active
39
+ usecli theme. Rendering is suppressed automatically in JSON mode, in quiet
40
+ mode, when ``quiet=True``, or when stderr is not a terminal, so commands
41
+ can keep the block in place in every environment.
42
+
43
+ Use it as a context manager; the spinner line is erased on exit. Call
44
+ :meth:`update` to change the message while the block runs.
45
+
46
+ Args:
47
+ message: Initial status message.
48
+ quiet: Suppress rendering regardless of the terminal.
49
+ spinner: Rich spinner style name, for example ``"dots"`` or ``"line"``.
50
+
51
+ Attributes:
52
+ message: Current status message.
53
+ quiet: Whether rendering was explicitly suppressed.
54
+ spinner: Rich spinner style name.
55
+
56
+ Example:
57
+ >>> with Spinner("Loading records") as spinner:
58
+ ... load_records()
59
+ ... spinner.update("Indexing records")
60
+
61
+ Note:
62
+ Instances are not thread-safe.
63
+ """
32
64
 
33
65
  def __init__(
34
66
  self,
@@ -77,14 +109,45 @@ class Spinner:
77
109
  self._task_id = None
78
110
 
79
111
  def update(self, message: str) -> None:
80
- """Replace the status message without changing command behavior."""
112
+ """Change the status message shown while the block runs.
113
+
114
+ Safe to call before entering the context manager: the message is
115
+ applied when the spinner starts. The message is still recorded when
116
+ rendering is suppressed, so later ``update`` calls remain consistent.
117
+ """
81
118
  self.message = message
82
119
  if self._progress is not None and self._task_id is not None:
83
120
  self._progress.update(self._task_id, description=message)
84
121
 
85
122
 
86
123
  class ProgressBar:
87
- """Determinate progress bar that renders only to terminal stderr."""
124
+ """Determinate progress bar for work with a known total.
125
+
126
+ Renders the description, a bar, and a percentage to stderr using the active
127
+ usecli theme. Advance it with :meth:`advance`, or set absolute progress
128
+ with :meth:`update`. Rendering is suppressed automatically in JSON mode, in
129
+ quiet mode, when ``quiet=True``, or when stderr is not a terminal; counters
130
+ still update, so command logic never branches on the environment.
131
+
132
+ Args:
133
+ total: Number of steps expected.
134
+ description: Label shown before the bar.
135
+ quiet: Suppress rendering regardless of the terminal.
136
+
137
+ Attributes:
138
+ total: Number of steps expected.
139
+ description: Current label.
140
+ completed: Steps recorded so far.
141
+
142
+ Example:
143
+ >>> with ProgressBar(total=len(items), description="Processing") as bar:
144
+ ... for item in items:
145
+ ... process(item)
146
+ ... bar.advance()
147
+
148
+ Note:
149
+ Not thread-safe; update from the thread that entered the context.
150
+ """
88
151
 
89
152
  def __init__(
90
153
  self,
@@ -142,7 +205,12 @@ class ProgressBar:
142
205
  self._task_id = None
143
206
 
144
207
  def advance(self, amount: float = 1) -> None:
145
- """Advance the tracked task by ``amount`` steps."""
208
+ """Record ``amount`` completed steps.
209
+
210
+ ``amount`` may be fractional when ``total`` is fractional. The local
211
+ counter is always updated; the rendered bar refreshes only while the
212
+ context manager is active and rendering is enabled.
213
+ """
146
214
  self.completed += amount
147
215
  if self._progress is not None and self._task_id is not None:
148
216
  self._progress.advance(self._task_id, amount)
@@ -153,7 +221,12 @@ class ProgressBar:
153
221
  completed: float | None = None,
154
222
  description: str | None = None,
155
223
  ) -> None:
156
- """Update completed work and/or the displayed description."""
224
+ """Set completed steps, the description, or both.
225
+
226
+ ``None`` leaves the corresponding field unchanged. Local state is
227
+ always updated; the rendered bar refreshes only while the context
228
+ manager is active and rendering is enabled.
229
+ """
157
230
  if completed is not None:
158
231
  self.completed = completed
159
232
  if description is not None:
@@ -0,0 +1,71 @@
1
+ # ruff: noqa: F401
2
+ # This module exists to re-export Rich's public API.
3
+ """Rich components re-exported under the ``usecli`` namespace.
4
+
5
+ Use this when a project should not import ``rich`` directly::
6
+
7
+ from usecli.rich import Markdown, Syntax, Table, Tree
8
+
9
+ Every name here is also available from the package root, lazily::
10
+
11
+ from usecli import Markdown, Syntax, Table, Tree
12
+
13
+ The imports below are static on purpose: PyInstaller's ``collect_all("usecli")``
14
+ then discovers the Rich submodules for frozen CLI bundles.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ from rich import box, get_console, inspect, print, print_json, reconfigure
20
+ from rich.align import Align
21
+ from rich.bar import Bar
22
+ from rich.columns import Columns
23
+ from rich.console import (
24
+ Console,
25
+ ConsoleOptions,
26
+ ConsoleRenderable,
27
+ Group,
28
+ RenderableType,
29
+ RenderHook,
30
+ RichCast,
31
+ )
32
+ from rich.control import Control
33
+ from rich.json import JSON
34
+ from rich.layout import Layout, LayoutRender
35
+ from rich.live import Live
36
+ from rich.markdown import Markdown
37
+ from rich.padding import Padding
38
+ from rich.panel import Panel
39
+ from rich.pretty import Pretty, pprint
40
+ from rich.progress import (
41
+ BarColumn,
42
+ DownloadColumn,
43
+ MofNCompleteColumn,
44
+ Progress,
45
+ ProgressColumn,
46
+ SpinnerColumn,
47
+ TaskID,
48
+ TaskProgressColumn,
49
+ TextColumn,
50
+ TimeElapsedColumn,
51
+ TimeRemainingColumn,
52
+ TotalFileSizeColumn,
53
+ TransferSpeedColumn,
54
+ track,
55
+ )
56
+ from rich.prompt import Confirm, Prompt
57
+ from rich.rule import Rule
58
+ from rich.screen import Screen
59
+ from rich.segment import Segment
60
+ from rich.status import Status
61
+ from rich.style import Style, StyleType
62
+ from rich.syntax import Syntax
63
+ from rich.table import Column, Table
64
+ from rich.text import Span, Text, TextType
65
+ from rich.theme import Theme
66
+ from rich.traceback import Traceback
67
+ from rich.tree import Tree
68
+
69
+ from usecli._rich_exports import RICH_EXPORT_NAMES
70
+
71
+ __all__ = list(RICH_EXPORT_NAMES)