usecli 0.1.59__tar.gz → 0.1.60__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usecli
-Version: 0.1.59
+Version: 0.1.60
 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.59 → usecli-0.1.60}/pyproject.toml

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

@@ -2,16 +2,24 @@
 
 from __future__ import annotations
 
-import shutil
 import sys
 from importlib import import_module
-from typing import Any, Optional, Sequence
+from typing import TYPE_CHECKING, Any, Optional, Sequence
 
 import click
 import typer
 from click.exceptions import BadParameter, ClickException, Exit, UsageError
 from typer.core import TyperGroup
 
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from usecli.menu import Menu
+    from usecli.params import Argument, Option
+    from usecli.ui import Confirm, Prompt
+
+    console: Console
+
 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]
@@ -23,13 +31,8 @@ except ImportError:
 
 from usecli.cli.config.colors import COLOR
 from usecli.cli.core.base_command import BaseCommand
-from usecli.cli.core.exceptions import UsecliBadParameter, UsecliUsageError
-from usecli.cli.core.ui.list import list_commands
 from usecli.cli.services.command_service import CommandService
-from usecli.menu import Menu
-from usecli.params import Argument, Option
 from usecli.shared.config.manager import get_config
-from usecli.ui import Confirm, Console, Prompt, console
 
 colors = import_module("usecli.cli.config.colors")
 theme = COLOR
@@ -37,6 +40,27 @@ theme = COLOR
 sys.modules.setdefault(__name__ + ".colors", colors)
 sys.modules.setdefault("colors", colors)
 
+_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:
+    export = _LAZY_EXPORTS.get(name)
+    if export is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attr_name = export
+    value = getattr(import_module(module_name), attr_name)
+    globals()[name] = value
+    return value
+
+
 __all__ = [
     "BaseCommand",
     "console",
@@ -52,6 +76,10 @@ __all__ = [
 ]
 
 
+def _console():
+    return __getattr__("console")
+
+
 def _is_interactive_flag_present() -> bool:
     """Check if -i/--interactive flag is present in sys.argv.
 
@@ -206,10 +234,14 @@ class PrefixMatchingGroup(TyperGroup):
         except Exit:
             sys.exit(0)
         except (BadParameter, TyperBadParameter) 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, TyperUsageError) 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)
@@ -241,18 +273,34 @@ class FilteredListCommand(click.Command):
         Args:
             ctx: The Click context.
         """
+        from usecli.cli.core.ui.list import list_commands
+
         list_commands(app, prefix_filter=self.prefix_filter)
         return None
 
 
+def _get_default_help() -> str:
+    return "Usecli CLI - An elegant CLI framework for Python"
+
+
 app = typer.Typer(
-    help=_get_cli_help_text(),
+    help=_get_default_help(),
     invoke_without_command=True,
     no_args_is_help=False,
     cls=PrefixMatchingGroup,
     pretty_exceptions_enable=False,  # Use custom error styling
 )
 
+_help_resolved = False
+
+
+def _resolve_help():
+    global _help_resolved
+    if not _help_resolved:
+        app.info.help = _get_cli_help_text()
+        _help_resolved = True
+
+
 service = CommandService(app)
 service.load_commands()
 
@@ -278,14 +326,20 @@ def run_app(
         version: Flag to show version and exit.
         help: Flag to show help and exit.
     """
+    _resolve_help()
+
     if help:
+        from usecli.cli.core.ui.list import list_commands
+
         list_commands(app)
         raise typer.Exit()
 
     if version:
+        import shutil
+
         config = get_config()
         command_path = shutil.which(sys.argv[0]) or sys.argv[0]
-        console.print(
+        _console().print(
             f"[bold {theme.SECONDARY}]{config.get('title')} {service.version}[/bold {theme.SECONDARY}] [{theme.INFO}]({command_path})[/{theme.INFO}]"
         )
         raise typer.Exit()
@@ -305,18 +359,21 @@ def run_app(
         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(app, prefix_filter=prefix_filter)
 
 
 def main() -> None:
     """Run the CLI application with custom error handling."""
+    _resolve_help()
     config = get_config()
     command_name = config._get_command_name()
     if command_name == "usecli" and not config.is_usecli_direct_dependency():
-        console.print(
+        _console().print(
             "[bold red]Error:[/bold red] usecli is not a direct dependency of this project."
         )
-        console.print(
+        _console().print(
             "Add it to your [cyan]pyproject.toml[/cyan] dependencies or dependency-groups."
         )
         sys.exit(1)
@@ -326,10 +383,14 @@ def main() -> None:
     except Exit:
         sys.exit(0)
     except (BadParameter, TyperBadParameter) 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, TyperUsageError) 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)

{usecli-0.1.59 → usecli-0.1.60}/src/usecli/cli/commands/defaults/base/about_command.py

@@ -1,30 +1,53 @@
 from __future__ import annotations
 
-import importlib.metadata
 import os
-import platform
-import re
 import sys
-from importlib.metadata import PackageNotFoundError
-from importlib.metadata import version as get_version
 from pathlib import Path
 
-if sys.version_info >= (3, 11):
-    import tomllib
-else:
-    import tomli as tomllib
-
-from rich.console import Console
-
 from usecli.cli.config.colors import COLOR
 from usecli.cli.core.base_command import BaseCommand
-from usecli.cli.core.ui.title import get_project_name, get_script_command_name
-from usecli.shared.config.manager import ConfigManager, get_config
+from usecli.shared.config.manager import get_config
+
+
+class _LazyConsole:
+    _console = None
+
+    def _get_console(self):
+        if self._console is None:
+            from rich.console import Console
+
+            self._console = Console()
+        return self._console
+
+    def __getattr__(self, name):
+        return getattr(self._get_console(), name)
+
+
+console = _LazyConsole()
+
+
+def _load_toml(text: str):
+    if sys.version_info >= (3, 11):
+        import tomllib
+    else:
+        import tomli as tomllib
+
+    return tomllib.loads(text)
 
-console = Console()
+
+def _toml_decode_error():
+    if sys.version_info >= (3, 11):
+        pass
+    else:
+        pass
+
+    return _toml_decode_error()
 
 
 def _get_version() -> str:
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as get_version
+
     try:
         return get_version("usecli")
     except PackageNotFoundError:
@@ -36,6 +59,8 @@ def _parse_dependency_requirement(req: str) -> tuple[str, str | None]:
     if not req_core:
         return "", None
 
+    import re
+
     match = re.match(r"^([A-Za-z0-9_.-]+)", req_core)
     if not match:
         return "", None
@@ -57,11 +82,11 @@ def _parse_dependency_requirement(req: str) -> tuple[str, str | None]:
     return name, remainder
 
 
-def _get_console_script_distribution(
-    command_name: str | None,
-) -> importlib.metadata.Distribution | None:
+def _get_console_script_distribution(command_name: str | None):
     if not command_name:
         return None
+    import importlib.metadata
+
     try:
         distributions = importlib.metadata.distributions()
     except Exception:
@@ -79,9 +104,7 @@ def _get_console_script_distribution(
     return None
 
 
-def _get_package_dependencies_from_distribution(
-    dist: importlib.metadata.Distribution,
-) -> list[tuple[str, str | None]]:
+def _get_package_dependencies_from_distribution(dist) -> list[tuple[str, str | None]]:
     requires = dist.requires or []
     result: list[tuple[str, str | None]] = []
     for req in requires:
@@ -93,10 +116,12 @@ def _get_package_dependencies_from_distribution(
     return result
 
 
-def _get_dependencies(config: ConfigManager) -> list[tuple[str, str | None]]:
+def _get_dependencies(config) -> list[tuple[str, str | None]]:
     command_name = os.path.basename(sys.argv[0]) if sys.argv else None
     dist = _get_console_script_distribution(command_name)
     if dist is None:
+        from usecli.cli.core.ui.title import get_script_command_name
+
         primary_command = get_script_command_name(default=None)
         dist = _get_console_script_distribution(primary_command)
     if dist is not None:
@@ -107,8 +132,8 @@ def _get_dependencies(config: ConfigManager) -> list[tuple[str, str | None]]:
         return []
 
     try:
-        data = tomllib.loads(pyproject_path.read_text())
-    except (tomllib.TOMLDecodeError, OSError):
+        data = _load_toml(pyproject_path.read_text())
+    except (_toml_decode_error(), OSError):
         return []
 
     deps = data.get("project", {}).get("dependencies", [])
@@ -125,16 +150,18 @@ def _get_dependencies(config: ConfigManager) -> list[tuple[str, str | None]]:
     return result
 
 
-def _get_application_distribution() -> importlib.metadata.Distribution | None:
+def _get_application_distribution():
     command_name = os.path.basename(sys.argv[0]) if sys.argv else None
     dist = _get_console_script_distribution(command_name)
     if dist is None:
+        from usecli.cli.core.ui.title import get_script_command_name
+
         primary_command = get_script_command_name(default=None)
         dist = _get_console_script_distribution(primary_command)
     return dist
 
 
-def _get_application_version(config: ConfigManager) -> str:
+def _get_application_version(config) -> str:
     dist = _get_application_distribution()
     if dist is not None:
         return dist.version
@@ -146,7 +173,7 @@ def _get_application_version(config: ConfigManager) -> str:
     return _get_version()
 
 
-def _get_application_description(config: ConfigManager) -> str:
+def _get_application_description(config) -> str:
     description = config.get("description")
     if (
         config.has_key("description")
@@ -165,14 +192,14 @@ def _get_application_description(config: ConfigManager) -> str:
     )
 
 
-def _get_project_description(config: ConfigManager) -> str | None:
+def _get_project_description(config) -> str | None:
     pyproject_path = config.pyproject_path
     if not pyproject_path.exists():
         return None
 
     try:
-        data = tomllib.loads(pyproject_path.read_text())
-    except (tomllib.TOMLDecodeError, OSError):
+        data = _load_toml(pyproject_path.read_text())
+    except (_toml_decode_error(), OSError):
         return None
 
     description = data.get("project", {}).get("description")
@@ -202,6 +229,8 @@ def _get_installed_script_commands(command_name: str | None) -> list[str]:
 
 
 def _get_script_commands() -> list[str]:
+    from usecli.cli.core.ui.title import get_script_command_name
+
     primary_command = get_script_command_name(default=None)
     command_name = os.path.basename(sys.argv[0]) if sys.argv else primary_command
     installed_commands = _get_installed_script_commands(command_name)
@@ -217,8 +246,8 @@ def _get_script_commands() -> list[str]:
         return []
 
     try:
-        data = tomllib.loads(pyproject_path.read_text())
-    except (tomllib.TOMLDecodeError, OSError):
+        data = _load_toml(pyproject_path.read_text())
+    except (_toml_decode_error(), OSError):
         return []
 
     scripts = data.get("project", {}).get("scripts", {})
@@ -245,6 +274,8 @@ class AboutCommand(BaseCommand):
     def handle(self) -> None:
         config = get_config()
         version = _get_application_version(config)
+        from usecli.cli.core.ui.title import get_project_name
+
         app_name = get_project_name()
         description = _get_application_description(config)
 
@@ -262,6 +293,8 @@ class AboutCommand(BaseCommand):
         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()}")
 
@@ -282,6 +315,8 @@ class AboutCommand(BaseCommand):
         if deps:
             for dep_name, spec in deps:
                 try:
+                    from importlib.metadata import version as get_version
+
                     installed_version = get_version(dep_name)
                     self._print_row(dep_name, installed_version)
                 except Exception:

{usecli-0.1.59 → usecli-0.1.60}/src/usecli/cli/commands/defaults/base/help_command.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 from usecli.cli.core.base_command import BaseCommand
-from usecli.cli.core.ui.list import list_commands
 
 
 class HelpCommand(BaseCommand):
@@ -19,4 +18,6 @@ class HelpCommand(BaseCommand):
 
     def handle(self) -> None:
         """Handle the command execution."""
+        from usecli.cli.core.ui.list import list_commands
+
         list_commands(self.app)

{usecli-0.1.59 → usecli-0.1.60}/src/usecli/cli/commands/defaults/base/inspire_command.py

@@ -4,15 +4,10 @@ from __future__ import annotations
 
 import random
 
-from rich.console import Console
-from rich.panel import Panel
-
 from usecli.cli.config.colors import COLOR
 from usecli.cli.core.base_command import BaseCommand
 from usecli.shared.config.manager import get_config
 
-console = Console()
-
 
 class InspireCommand(BaseCommand):
     """Command for displaying random inspirational quotes."""
@@ -78,7 +73,10 @@ class InspireCommand(BaseCommand):
         selected = random.choice(quotes)
         quote, author = selected.rsplit(" - ", 1)
 
-        console.print(
+        from rich.console import Console
+        from rich.panel import Panel
+
+        Console().print(
             Panel(
                 f"{quote}\n\n[{COLOR.FOREGROUND_MUTED}]— {author}[/{COLOR.FOREGROUND_MUTED}]",
                 border_style=COLOR.PANEL_PRIMARY,

{usecli-0.1.59 → usecli-0.1.60}/src/usecli/cli/commands/defaults/core/utils.py

@@ -8,12 +8,25 @@ from datetime import datetime, timedelta
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from rich.console import Console
-
 if TYPE_CHECKING:
     pass
 
-console = Console()
+
+class _LazyConsole:
+    _console = None
+
+    def _get_console(self):
+        if self._console is None:
+            from rich.console import Console
+
+            self._console = Console()
+        return self._console
+
+    def __getattr__(self, name):
+        return getattr(self._get_console(), name)
+
+
+console = _LazyConsole()
 
 
 def is_interactive() -> bool:

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

@@ -11,18 +11,19 @@ Usage:
 
 from __future__ import annotations
 
-import importlib.metadata
-import importlib.util
 import os
 import sys
 import time
 from pathlib import Path
 from typing import Any, Callable, Final, Protocol, cast, final
 
-if sys.version_info >= (3, 11):
-    import tomllib
-else:
-    import tomli as tomllib
+
+def _import_tomllib():
+    if sys.version_info >= (3, 11):
+        import tomllib
+    else:
+        import tomli as tomllib
+    return tomllib
 
 
 PYPROJECT_TOML = "pyproject.toml"
@@ -114,6 +115,8 @@ def _get_console_script_aliases(command_name: str | None) -> set[str]:
         return set()
     aliases: set[str] = {command_name}
     try:
+        import importlib.metadata
+
         distributions = importlib.metadata.distributions()
     except Exception:
         return aliases
@@ -139,7 +142,7 @@ def _config_matches_command(path: Path, command_name: str | None) -> bool:
         return True
     try:
         data = _load_usecli_config_file(path)
-    except (tomllib.TOMLDecodeError, OSError):
+    except OSError:
         return True
     config_command = data.get("command_name")
     if not isinstance(config_command, str):
@@ -205,6 +208,8 @@ def _find_usecli_config_path_for_command(
 
 
 def _find_usecli_config_in_package() -> Path | None:
+    import importlib.util
+
     spec = importlib.util.find_spec(_get_package_name())
     if spec is None or not spec.submodule_search_locations:
         return None
@@ -222,6 +227,8 @@ def _find_usecli_config_in_package() -> Path | None:
 
 
 def _find_usecli_config_in_named_package(package_name: str) -> Path | None:
+    import importlib.util
+
     if not package_name:
         return None
     spec = importlib.util.find_spec(package_name)
@@ -241,6 +248,8 @@ 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
@@ -282,6 +291,8 @@ def _is_preferred_package_path(path: Path) -> bool:
 
 
 def _is_within_usecli_package(start_dir: Path) -> bool:
+    import importlib.util
+
     spec = importlib.util.find_spec(_get_package_name())
     if spec is None or not spec.submodule_search_locations:
         return False
@@ -365,6 +376,7 @@ def _load_usecli_config(
 
 
 def _load_usecli_config_file(config_path: Path) -> dict[str, Any]:
+    tomllib = _import_tomllib()
     try:
         data = tomllib.loads(config_path.read_text())
     except (tomllib.TOMLDecodeError, OSError):
@@ -556,6 +568,7 @@ def _resolve_theme_path(
 
 
 def _load_theme_file(theme_path: Path) -> dict[str, Any]:
+    tomllib = _import_tomllib()
     try:
         with open(theme_path, "rb") as theme_file:
             data = tomllib.load(theme_file)
@@ -578,7 +591,15 @@ def _load_theme() -> tuple[dict[str, str], dict[str, str], str, Path | None]:
         theme_name = config_theme.strip()
 
     theme_path = _resolve_theme_path(theme_name, project_root, config_values)
-    theme_data = _load_theme_file(theme_path) if theme_path else {}
+    package_default_theme = (THEMES_DIR / f"{DEFAULT_THEME_NAME}.toml").resolve()
+    if (
+        theme_name == DEFAULT_THEME_NAME
+        and theme_path
+        and theme_path.resolve() == package_default_theme
+    ):
+        theme_data = {}
+    else:
+        theme_data = _load_theme_file(theme_path) if theme_path else {}
 
     colors = _merge_theme_values(
         DEFAULT_THEME_COLORS,
@@ -711,19 +732,49 @@ def _apply_theme(
 
 
 def _ensure_theme_loaded(color_class: type[Any]) -> None:
-    global _THEME_CONTEXT
-    context = _theme_context()
-    if context == _THEME_CONTEXT:
-        return
-    colors, ansi, _, _ = _load_theme()
-    _THEME_CONTEXT = context
-    _THEME_COLORS.update(colors)
-    _THEME_ANSI.update(ansi)
+    global _THEME_CONTEXT, _THEME_LOADED
+    if _THEME_LOADED:
+        context = _theme_context()
+        if context == _THEME_CONTEXT:
+            return
+        colors, ansi, _, _ = _load_theme()
+        _THEME_CONTEXT = context
+        _THEME_COLORS.update(colors)
+        _THEME_ANSI.update(ansi)
+    else:
+        colors, ansi, _, _ = _load_theme()
+        _THEME_CONTEXT = _theme_context()
+        _THEME_COLORS.update(colors)
+        _THEME_ANSI.update(ansi)
+        _THEME_LOADED = True
     _apply_theme(cast(_ColorNamespace, color_class), _THEME_COLORS, _THEME_ANSI)
 
 
-_THEME_COLORS, _THEME_ANSI, _THEME_NAME, _THEME_PATH = _load_theme()
-_THEME_CONTEXT: tuple[Path | None, Path | None, str, Path | None] = _theme_context()
+# Deferred: _load_theme() and _theme_context() are called on first COLOR attribute access
+# via _ColorMeta.__getattribute__ -> _ensure_theme_loaded, instead of at import time.
+# This avoids ~50ms of filesystem walking during startup when colors aren't needed yet.
+_THEME_LOADED: bool = False
+_THEME_COLORS: dict[str, str] = DEFAULT_THEME_COLORS.copy()
+_THEME_ANSI: dict[str, str] = {
+    "reset": "\033[0m",
+    "primary": "",
+    "secondary": "",
+    "accent": "",
+    "foreground": "",
+    "foreground_muted": "",
+    "red": "",
+    "green": "",
+    "yellow": "",
+    "blue": "",
+}
+_THEME_NAME: str = DEFAULT_THEME_NAME
+_THEME_PATH: Path | None = None
+_THEME_CONTEXT: tuple[Path | None, Path | None, str, Path | None] = (
+    None,
+    None,
+    DEFAULT_THEME_NAME,
+    None,
+)
 
 
 class _ColorMeta(type):