usecli 0.1.60__tar.gz → 0.1.63__tar.gz

{usecli-0.1.60 → usecli-0.1.63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usecli
-Version: 0.1.60
+Version: 0.1.63
 Summary: A powerful Python CLI framework for building beautiful, developer-friendly command-line tools.
 Author: Edward Boswell
 Author-email: Edward Boswell <thememium@gmail.com>

{usecli-0.1.60 → usecli-0.1.63}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usecli"
-version = "0.1.60"
+version = "0.1.63"
 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.63/src/usecli/__init__.py

@@ -0,0 +1,457 @@
+"""Usecli CLI main entry point."""
+
+from __future__ import annotations
+
+import sys
+from importlib import import_module
+
+# Avoid importing typing at module level (costs ~6ms)
+# TYPE_CHECKING is False at runtime, so the if-block never executes
+TYPE_CHECKING = False
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    import typer
+    from rich.console import Console
+
+    from usecli.cli.core.base_command import BaseCommand
+    from usecli.menu import Menu
+    from usecli.params import Argument, Option
+    from usecli.ui import Confirm, Prompt
+
+    console: Console
+
+# Lazy module-level placeholders - these are populated on first access
+_app: Any = None
+_service: Any = None
+_help_resolved: bool = False
+
+_LAZY_EXPORTS = {
+    "Menu": ("usecli.menu", "Menu"),
+    "Argument": ("usecli.params", "Argument"),
+    "Option": ("usecli.params", "Option"),
+    "Prompt": ("usecli.ui", "Prompt"),
+    "Confirm": ("usecli.ui", "Confirm"),
+    "Console": ("usecli.ui", "Console"),
+    "console": ("usecli.ui", "console"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    # Handle lazy exports
+    export = _LAZY_EXPORTS.get(name)
+    if export is not None:
+        module_name, attr_name = export
+        value = getattr(import_module(module_name), attr_name)
+        globals()[name] = value
+        return value
+
+    # Handle CLI framework components - lazy initialization
+    if name in ("app", "service", "BaseCommand", "colors", "theme"):
+        _ensure_cli_initialized()
+        return globals()[name]
+
+    # Handle run_app callback
+    if name == "run_app":
+        _ensure_cli_initialized()
+        _get_run_app_callback()
+        return globals()[name]
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def _ensure_cli_initialized() -> None:
+    """Lazily initialize the CLI framework components."""
+    # Use BaseCommand as the guard - it's set last, so if it's present,
+    # initialization completed successfully.
+    if "BaseCommand" in globals():
+        return
+
+    global _app, _service
+
+    import typer
+    from click.exceptions import BadParameter, ClickException, Exit, UsageError
+    from typer.core import TyperGroup
+
+    from usecli.cli.config.colors import COLOR
+    from usecli.cli.core.base_command import BaseCommand
+    from usecli.cli.services.command_service import CommandService
+
+    # Store exceptions for error handling
+    try:
+        from typer._click.exceptions import BadParameter as TyperBadParameter  # type: ignore[import-untyped]
+        from typer._click.exceptions import ClickException as TyperClickException  # type: ignore[import-untyped]
+        from typer._click.exceptions import UsageError as TyperUsageError  # type: ignore[import-untyped]
+    except ImportError:
+        TyperBadParameter = BadParameter
+        TyperClickException = ClickException
+        TyperUsageError = UsageError
+
+    # Store in globals for use by other functions
+    globals()["_TyperBadParameter"] = TyperBadParameter
+    globals()["_TyperClickException"] = TyperClickException
+    globals()["_TyperUsageError"] = TyperUsageError
+    globals()["_Exit"] = Exit
+    globals()["_BadParameter"] = BadParameter
+    globals()["_ClickException"] = ClickException
+    globals()["_UsageError"] = UsageError
+    globals()["_TyperGroup"] = TyperGroup
+
+    # Create PrefixMatchingGroup now that TyperGroup is available
+    class PrefixMatchingGroup(TyperGroup):
+        """Custom Typer group that supports prefix matching for commands."""
+
+        def get_command(self, ctx, cmd_name):
+            """Get a command by name, with prefix matching fallback."""
+            rv = TyperGroup.get_command(self, ctx, cmd_name)
+            if rv is not None:
+                return rv
+
+            app = _get_app()
+            group_alias_registry = _get_group_alias_registry(app)
+            group_alias_to_primary = _build_alias_to_primary(group_alias_registry)
+
+            if (
+                cmd_name in group_alias_to_primary
+                and group_alias_to_primary[cmd_name] != cmd_name
+            ):
+                return TyperGroup.get_command(
+                    self, ctx, group_alias_to_primary[cmd_name]
+                )
+
+            matches = [x for x in self.list_commands(ctx) if x.startswith(cmd_name)]
+            group_aliases = [
+                alias for aliases in group_alias_registry.values() for alias in aliases
+            ]
+            matches.extend(
+                [alias for alias in group_aliases if alias.startswith(cmd_name)]
+            )
+            matches = list(dict.fromkeys(matches))
+
+            if not matches:
+                return None
+
+            if cmd_name in matches:
+                if (
+                    cmd_name in group_alias_to_primary
+                    and group_alias_to_primary[cmd_name] != cmd_name
+                ):
+                    return TyperGroup.get_command(
+                        self, ctx, group_alias_to_primary[cmd_name]
+                    )
+                return TyperGroup.get_command(self, ctx, cmd_name)
+
+            return _FilteredListCommand(cmd_name)
+
+        def main(
+            self,
+            args=None,
+            prog_name=None,
+            complete_var=None,
+            standalone_mode=True,
+            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,
+            )
+
+        def invoke(self, ctx):
+            from click.exceptions import BadParameter, ClickException, Exit, UsageError
+
+            try:
+                return super().invoke(ctx)
+            except Exit:
+                sys.exit(0)
+            except BadParameter as e:
+                from usecli.cli.core.exceptions import UsecliBadParameter
+
+                styled_error = UsecliBadParameter(e.message, ctx=e.ctx, param=e.param)
+                styled_error.show()
+                sys.exit(styled_error.exit_code)
+            except UsageError as e:
+                from usecli.cli.core.exceptions import UsecliUsageError
+
+                styled_error = UsecliUsageError(e.message, ctx=e.ctx)
+                styled_error.show()
+                sys.exit(styled_error.exit_code)
+            except ClickException as e:
+                if hasattr(e, "show"):
+                    e.show()
+                sys.exit(e.exit_code if hasattr(e, "exit_code") else 1)
+
+    globals()["PrefixMatchingGroup"] = PrefixMatchingGroup
+
+    # Setup module aliasing
+    colors = import_module("usecli.cli.config.colors")
+    globals()["colors"] = colors
+    globals()["theme"] = COLOR
+    sys.modules.setdefault(__name__ + ".colors", colors)
+    sys.modules.setdefault("colors", colors)
+
+    # Create app and service
+    _app = typer.Typer(
+        help="Usecli CLI - An elegant CLI framework for Python",
+        invoke_without_command=True,
+        no_args_is_help=False,
+        cls=PrefixMatchingGroup,
+        pretty_exceptions_enable=False,
+    )
+    globals()["app"] = _app
+
+    # Set BaseCommand BEFORE load_commands() since commands import it
+    globals()["BaseCommand"] = BaseCommand
+
+    _service = CommandService(_app)
+    _service.load_commands()
+    globals()["service"] = _service
+
+    # Register the callback eagerly so --version/--help work
+    # even when the app is accessed directly (e.g. smoke tests).
+    _get_run_app_callback()
+
+
+def _get_app():
+    _ensure_cli_initialized()
+    return _app
+
+
+def _get_service():
+    _ensure_cli_initialized()
+    return _service
+
+
+__all__ = [
+    "BaseCommand",
+    "console",
+    "Console",
+    "main",
+    "Menu",
+    "Argument",
+    "Option",
+    "Prompt",
+    "Confirm",
+    "colors",
+    "theme",
+]
+
+
+def _console():
+    return __getattr__("console")
+
+
+def _is_interactive_flag_present() -> bool:
+    """Check if -i/--interactive flag is present in sys.argv.
+
+    This allows the interactive flag to work regardless of position,
+    e.g., both 'usecli -i magic' and 'usecli magic -i' will work.
+
+    Returns:
+        True if -i or --interactive is found in sys.argv, False otherwise.
+    """
+    return "-i" in sys.argv or "--interactive" in sys.argv
+
+
+def _get_cli_help_text() -> str:
+    from usecli.shared.config.manager import get_config
+
+    fallback = "Usecli CLI - An elegant CLI framework for Python"
+    fallback_description = "An elegant CLI framework for Python"
+    config = get_config()
+
+    description = config.get("description")
+    has_description = (
+        config.has_key("description")
+        and isinstance(description, str)
+        and description.strip()
+    )
+
+    title = config.get("title")
+    has_title = config.has_key("title") and isinstance(title, str) and title.strip()
+
+    command_name = config.get("command_name")
+    has_command_name = (
+        config.has_key("command_name")
+        and isinstance(command_name, str)
+        and command_name.strip()
+    )
+
+    if not has_description and not has_title and not has_command_name:
+        return fallback
+
+    display_name = (
+        title.strip()
+        if has_title
+        else command_name.strip()
+        if has_command_name
+        else "Usecli CLI"
+    )
+    display_description = (
+        description.strip() if has_description else fallback_description
+    )
+    return f"{display_name} - {display_description}"
+
+
+def _get_group_alias_registry(app: Any) -> dict[str, list[str]]:
+    registry = getattr(app, "_usecli_group_aliases", {})
+    return registry if isinstance(registry, dict) else {}
+
+
+def _build_alias_to_primary(alias_registry: dict[str, list[str]]) -> dict[str, str]:
+    alias_to_primary: dict[str, str] = {}
+    for primary, aliases in alias_registry.items():
+        alias_to_primary[primary] = primary
+        for alias in aliases:
+            alias_to_primary[alias] = primary
+    return alias_to_primary
+
+
+# PrefixMatchingGroup is created lazily by _ensure_cli_initialized()
+# to avoid importing typer at module level.
+PrefixMatchingGroup = None
+
+
+class _FilteredListCommand:
+    """Command that displays a filtered list of commands."""
+
+    def __init__(self, prefix_filter: str) -> None:
+        self.prefix_filter = prefix_filter
+        self.name = "filtered-list"
+
+    def __call__(self, *args, **kwargs):
+        from usecli.cli.core.ui.list import list_commands
+
+        list_commands(_get_app(), prefix_filter=self.prefix_filter)
+
+
+def _get_default_help() -> str:
+    return "Usecli CLI - An elegant CLI framework for Python"
+
+
+def _resolve_help():
+    global _help_resolved
+    if not _help_resolved:
+        app = _get_app()
+        app.info.help = _get_cli_help_text()
+        _help_resolved = True
+
+
+def _get_run_app_callback():
+    """Get the run_app callback function."""
+    if "run_app" in globals():
+        return globals()["run_app"]
+
+    import typer
+
+    # Inject typer into module globals so annotation evaluation works
+    # (required because `from __future__ import annotations` makes them strings)
+    globals()["typer"] = typer
+
+    @_app.callback()
+    def run_app(
+        ctx: typer.Context,
+        version: bool = typer.Option(
+            None, "--version", "-v", help="Show the version and exit.", is_eager=True
+        ),
+        help: bool = typer.Option(None, "--help", "-h", is_eager=True),
+        interactive: bool = typer.Option(
+            False, "--interactive", "-i", help="Run in interactive mode.", is_eager=True
+        ),
+    ) -> None:
+        _resolve_help()
+
+        if help:
+            from usecli.cli.core.ui.list import list_commands
+
+            list_commands(_get_app())
+            raise typer.Exit()
+
+        if version:
+            import shutil
+
+            from usecli.shared.config.manager import get_config
+
+            config = get_config()
+            service = _get_service()
+            command_path = shutil.which(sys.argv[0]) or sys.argv[0]
+            _console().print(
+                f"[bold {globals()['theme'].SECONDARY}]{config.get('title')} {service.version}[/bold {globals()['theme'].SECONDARY}] [{globals()['theme'].INFO}]({command_path})[/{globals()['theme'].INFO}]"
+            )
+            raise typer.Exit()
+
+        interactive_requested = interactive or _is_interactive_flag_present()
+
+        if interactive_requested:
+            from usecli.cli.commands.defaults.base.internal.fzf_command import (
+                run_interactive,
+            )
+
+            cmd_parts = [ctx.invoked_subcommand] if ctx.invoked_subcommand else None
+            run_interactive(_get_app(), cmd_parts=cmd_parts)
+            raise typer.Exit()
+
+        if ctx.invoked_subcommand is None:
+            prefix_filter: str | None = None
+            if ctx.obj and isinstance(ctx.obj, dict):
+                prefix_filter = ctx.obj.get("prefix_filter")
+            from usecli.cli.core.ui.list import list_commands
+
+            list_commands(_get_app(), prefix_filter=prefix_filter)
+
+    globals()["run_app"] = run_app
+    return run_app
+
+
+def main() -> None:
+    """Run the CLI application with custom error handling."""
+    from click.exceptions import BadParameter, ClickException, Exit, UsageError
+
+    _ensure_cli_initialized()
+    _resolve_help()
+
+    from usecli.shared.config.manager import get_config
+
+    config = get_config()
+    command_name = config._get_command_name()
+    if command_name == "usecli" and not config.is_usecli_direct_dependency():
+        _console().print(
+            "[bold red]Error:[/bold red] usecli is not a direct dependency of this project."
+        )
+        _console().print(
+            "Add it to your [cyan]pyproject.toml[/cyan] dependencies or dependency-groups."
+        )
+        sys.exit(1)
+
+    # Setup the callback
+    _get_run_app_callback()
+
+    try:
+        _get_app()()
+    except Exit:
+        sys.exit(0)
+    except BadParameter as e:
+        from usecli.cli.core.exceptions import UsecliBadParameter
+
+        styled_error = UsecliBadParameter(e.message, ctx=e.ctx, param=e.param)
+        styled_error.show()
+        sys.exit(styled_error.exit_code)
+    except UsageError as e:
+        from usecli.cli.core.exceptions import UsecliUsageError
+
+        styled_error = UsecliUsageError(e.message, ctx=e.ctx)
+        styled_error.show()
+        sys.exit(styled_error.exit_code)
+    except ClickException as e:
+        if hasattr(e, "show"):
+            e.show()
+        sys.exit(e.exit_code if hasattr(e, "exit_code") else 1)
+
+
+if __name__ == "__main__":
+    main()

{usecli-0.1.60 → usecli-0.1.63}/src/usecli/cli/config/colors.py

@@ -39,6 +39,78 @@ _SKIP_DIRS = {
     "pipx",
     "venvs",
 }
+
+_MAX_RGLOB_DEPTH = 6
+
+_WALK_SKIP_ALWAYS: frozenset[str] = frozenset(
+    {
+        ".git",
+        "__pycache__",
+        "node_modules",
+        ".tox",
+        ".nox",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".auto",
+        ".eggs",
+        "*.egg-info",
+    }
+)
+
+_WALK_SKIP_VENV: frozenset[str] = frozenset(
+    {
+        ".venv",
+        "venv",
+        "site-packages",
+        "dist-packages",
+        "__pypackages__",
+        "pipx",
+        "venvs",
+    }
+)
+
+
+def _walk_for_filename(
+    directory: Path,
+    filename: str,
+    depth: int,
+    max_depth: int,
+    skip_dirs: frozenset[str],
+    results: list[Path],
+) -> None:
+    if depth > max_depth:
+        return
+    try:
+        entries = list(directory.iterdir())
+    except (PermissionError, OSError):
+        return
+    for entry in entries:
+        try:
+            if entry.is_file() and entry.name == filename:
+                results.append(entry)
+            elif entry.is_dir() and entry.name not in skip_dirs:
+                _walk_for_filename(
+                    entry, filename, depth + 1, max_depth, skip_dirs, results
+                )
+        except (PermissionError, OSError):
+            continue
+
+
+def _rglob_limited(
+    root_dir: Path,
+    filename: str,
+    *,
+    skip_venv: bool = True,
+    max_depth: int = _MAX_RGLOB_DEPTH,
+) -> list[Path]:
+    """Depth-bounded recursive filename search that prunes dirs during the walk."""
+    skip_dirs = _WALK_SKIP_ALWAYS | _WALK_SKIP_VENV if skip_venv else _WALK_SKIP_ALWAYS
+    results: list[Path] = []
+    _walk_for_filename(root_dir, filename, 0, max_depth, skip_dirs, results)
+    return results
+
+
 DEFAULT_THEME_COLORS: dict[str, str] = {
     "primary": "#60D7FF",
     "secondary": "#5EFF87",
@@ -68,13 +140,7 @@ def _find_usecli_config_path(
     if not root_dir.exists() or not root_dir.is_dir():
         return None
 
-    candidates = [path for path in root_dir.rglob(USECLI_CONFIG_TOML)]
-    if skip_venv:
-        candidates = [
-            path
-            for path in candidates
-            if not any(part in _SKIP_DIRS for part in path.parts)
-        ]
+    candidates = _rglob_limited(root_dir, USECLI_CONFIG_TOML, skip_venv=skip_venv)
     if not candidates:
         return None
 
@@ -109,17 +175,28 @@ def _get_command_name() -> str | None:
     return command if command else None
 
 
+_distributions_cache: list[Any] | None = None
+
+
+def _get_distributions() -> list[Any]:
+    global _distributions_cache
+    if _distributions_cache is not None:
+        return _distributions_cache
+    try:
+        import importlib.metadata
+
+        _distributions_cache = list(importlib.metadata.distributions())
+    except Exception:
+        _distributions_cache = []
+    return _distributions_cache
+
+
 def _get_console_script_aliases(command_name: str | None) -> set[str]:
     """Get all aliases for a console script from package metadata."""
     if not command_name:
         return set()
     aliases: set[str] = {command_name}
-    try:
-        import importlib.metadata
-
-        distributions = importlib.metadata.distributions()
-    except Exception:
-        return aliases
+    distributions = _get_distributions()
     for dist in distributions:
         try:
             entry_points = dist.entry_points
@@ -163,13 +240,7 @@ def _find_usecli_config_path_for_command(
     if not root_dir.exists() or not root_dir.is_dir():
         return None
 
-    candidates = [path for path in root_dir.rglob(USECLI_CONFIG_TOML)]
-    if skip_venv:
-        candidates = [
-            path
-            for path in candidates
-            if not any(part in _SKIP_DIRS for part in path.parts)
-        ]
+    candidates = _rglob_limited(root_dir, USECLI_CONFIG_TOML, skip_venv=skip_venv)
     if not candidates:
         return None
 
@@ -217,9 +288,7 @@ def _find_usecli_config_in_package() -> Path | None:
         package_root = Path(location)
         if not package_root.exists() or not package_root.is_dir():
             continue
-        candidates = [
-            path for path in package_root.rglob(USECLI_CONFIG_TOML) if path.exists()
-        ]
+        candidates = _rglob_limited(package_root, USECLI_CONFIG_TOML, skip_venv=False)
         if candidates:
             candidates.sort(key=lambda path: (len(path.parts), str(path)))
             return candidates[0]
@@ -238,9 +307,7 @@ def _find_usecli_config_in_named_package(package_name: str) -> Path | None:
         package_root = Path(location)
         if not package_root.exists() or not package_root.is_dir():
             continue
-        candidates = [
-            path for path in package_root.rglob(USECLI_CONFIG_TOML) if path.exists()
-        ]
+        candidates = _rglob_limited(package_root, USECLI_CONFIG_TOML, skip_venv=False)
         if candidates:
             candidates.sort(key=lambda path: (len(path.parts), str(path)))
             return candidates[0]
@@ -248,15 +315,10 @@ def _find_usecli_config_in_named_package(package_name: str) -> Path | None:
 
 
 def _find_usecli_config_for_console_script() -> Path | None:
-    import importlib.metadata
-
     command_name = os.path.basename(sys.argv[0]) if sys.argv else ""
     if not command_name:
         return None
-    try:
-        distributions = importlib.metadata.distributions()
-    except Exception:
-        return None
+    distributions = _get_distributions()
     for dist in distributions:
         try:
             entry_points = dist.entry_points
@@ -334,10 +396,8 @@ def _find_project_root(start_dir: Path | None = None) -> Path | None:
         current = parent
 
     search_root = git_root or start_dir.resolve()
-    config_match = _find_usecli_config_path(search_root, start_dir, skip_venv=True)
-    if config_match:
-        return config_match.parent
 
+    # Try fast lookups before expensive rglob (perf: global tools).
     console_match = _find_usecli_config_for_console_script()
     if console_match:
         return console_match.parent
@@ -346,6 +406,10 @@ def _find_project_root(start_dir: Path | None = None) -> Path | None:
     if package_match:
         return package_match.parent
 
+    config_match = _find_usecli_config_path(search_root, start_dir, skip_venv=True)
+    if config_match:
+        return config_match.parent
+
     return git_root
 
 
@@ -357,18 +421,19 @@ def _load_usecli_config(
 
     config_path = project_root / USECLI_CONFIG_TOML
     if not config_path.exists():
-        config_path = _find_usecli_config_path_for_command(
-            project_root,
-            project_root,
-            skip_venv=True,
-        )
-    if not config_path or not config_path.exists():
+        # Try fast lookups before expensive rglob (perf: global tools).
         console_match = _find_usecli_config_for_console_script()
         if console_match:
             return _load_usecli_config_file(console_match), console_match
         package_match = _find_usecli_config_in_package()
         if package_match:
             config_path = package_match
+    if not config_path or not config_path.exists():
+        config_path = _find_usecli_config_path_for_command(
+            project_root,
+            project_root,
+            skip_venv=True,
+        )
     if not config_path or not config_path.exists():
         return {}, None