usecli 0.1.76__tar.gz → 0.1.78__tar.gz

{usecli-0.1.76 → usecli-0.1.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usecli
-Version: 0.1.76
+Version: 0.1.78
 Summary: A powerful Python CLI framework for building beautiful, developer-friendly command-line tools.
 Author: Edward Boswell
 Author-email: Edward Boswell <thememium@gmail.com>
@@ -10,20 +10,22 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Developers
 Requires-Dist: case-converter>=1.2.0
-Requires-Dist: click>=8.3.1
-Requires-Dist: fzf-bin>=0.67.0
+Requires-Dist: click>=8.4.2
+Requires-Dist: fzf-bin>=0.74.1
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: pyfiglet>=1.0.4
-Requires-Dist: rich>=14.3.1
+Requires-Dist: rich>=15.0.0
 Requires-Dist: simple-term-menu>=1.6.6
-Requires-Dist: tomli>=2.4.0
-Requires-Dist: typer>=0.21.1
+Requires-Dist: tomli>=2.4.1
+Requires-Dist: typer>=0.27.0
+Requires-Dist: pyinstaller>=6.21.0 ; extra == 'pyinstaller'
 Requires-Python: >=3.10
 Project-URL: Homepage, https://github.com/thememium/usecli
 Project-URL: Documentation, https://github.com/thememium/usecli
 Project-URL: Repository, https://github.com/thememium/usecli.git
 Project-URL: Issues, https://github.com/thememium/usecli/issues
 Project-URL: Changelog, https://github.com/thememium/usecli/blob/master/CHANGELOG.md
+Provides-Extra: pyinstaller
 Description-Content-Type: text/markdown
 
 <a name="readme-top"></a>
@@ -52,6 +54,7 @@ Description-Content-Type: text/markdown
     <li><a href="#about">About</a></li>
     <li><a href="#quick-start">Quick Start</a></li>
     <li><a href="#usage">Usage</a></li>
+    <li><a href="#entry-points--packaging">Entry Points &amp; Packaging</a></li>
     <li><a href="#development">Development</a></li>
     <li><a href="#contributing">Contributing</a></li>
     <li><a href="#license">License</a></li>
@@ -163,7 +166,7 @@ Space-separated signatures create nested subcommands:
 
 ```python
 def signature(self) -> str:
-    return "spec show"   # usecli spec show
+    return "spec show"  # usecli spec show
 ```
 
 ### JSON Output
@@ -244,10 +247,115 @@ init         Initialize usecli (usecli only)
 inspire      Random quote
 make:command Create new command (usecli only)
 make:theme   Create new theme (usecli only)
+make:bundle  Build a standalone executable with PyInstaller (usecli only)
 ```
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
+<!-- ENTRY POINTS & PACKAGING -->
+
+## Entry Points &amp; Packaging
+
+A usecli CLI can be exposed in several ways, depending on how you distribute and
+run it. There are three common setups — none requires anything but the base
+`usecli` install, and the optional bundler adds PyInstaller packaging on top.
+
+### 1. Default — console script (no entry point)
+
+The simplest setup. Declare a console script in your project's `pyproject.toml`:
+
+```toml
+[project.scripts]
+mycli = "usecli:main"
+```
+
+usecli resolves your project's config automatically from the current directory
+(config discovery), so no `main.py` is required. Install and run it:
+
+```sh
+uv add usecli
+uv run mycli --help
+```
+
+This is the **default** — no entry point file of your own is needed.
+
+### 2. Custom entry point — `main.py`
+
+If you want your own entry point, use the public runtime API. It works in both
+development and frozen bundles, and accepts an optional config path (the config
+file is always named `usecli.config.toml`):
+
+```python
+# main.py
+from usecli import run
+
+if __name__ == "__main__":
+    run()  # auto-detect project config
+    # run("path/to/usecli.config.toml")          # or point at a specific config
+```
+
+Run it in development (no PyInstaller required):
+
+```sh
+uv run python main.py --help
+```
+
+Because `run()` injects the located config explicitly, a custom `main.py` works
+regardless of whether your CLI also has a `[project.scripts]` entry.
+
+### 3. Bundler — standalone executable (optional, requires PyInstaller)
+
+The bundler is an **optional** feature gated on PyInstaller being installed.
+Install it with:
+
+```sh
+uv add "usecli[pyinstaller]"
+```
+
+Once installed, a `make:bundle` command appears (usecli only) that builds your
+project into a standalone executable. It asks which mode to use via an
+interactive menu, and confirms before building (defaults to no unless `-y`):
+
+```sh
+uv run usecli make:bundle                  # menu: one file vs one folder + confirm
+uv run usecli make:bundle --mode onefile   # single-file executable
+uv run usecli make:bundle --mode onedir    # one-folder bundle
+uv run usecli make:bundle -y               # skip the confirmation
+uv run usecli make:bundle --mode onedir -y # fully programmatic
+uv run usecli make:bundle --mode onedir --zip -y  # one-folder bundle + zip
+```
+
+When building a **one-folder** bundle, `make:bundle` asks whether to also zip
+the folder into `dist/<name>.zip` (PyInstaller's recommended distribution
+format for one-folder mode). Pass `--zip` / `--no-zip` to skip the prompt and
+force a choice; with `-y` and no flag, zipping is skipped.
+
+A `usecli-bundle` console script wraps the same build, and you can drive it from
+Python too:
+
+```sh
+uv run usecli-bundle
+uv run usecli-bundle --mode onedir
+uv run usecli-bundle --mode onedir --zip
+```
+
+```python
+from usecli import pyinstaller
+
+pyinstaller()  # auto-detect config, single-file
+pyinstaller(mode="onedir")  # one-folder bundle
+pyinstaller(mode="onedir", zip=True)  # one-folder bundle + zip
+pyinstaller("path/to/usecli.config.toml")  # or point at a specific config
+```
+
+Output lands in `dist/` — `dist/mycli` for `onefile`, or a `dist/mycli/` folder
+containing the executable (plus `_internal/` with the bundled assets) for
+`onedir`. With `zip=True`, a `dist/mycli.zip` archive is created alongside the
+folder. `make:bundle` and `usecli-bundle` are only available when PyInstaller
+is installed.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 <!-- DEVELOPMENT -->
 
 ## Development

{usecli-0.1.76 → usecli-0.1.78}/README.md

@@ -24,6 +24,7 @@
     <li><a href="#about">About</a></li>
     <li><a href="#quick-start">Quick Start</a></li>
     <li><a href="#usage">Usage</a></li>
+    <li><a href="#entry-points--packaging">Entry Points &amp; Packaging</a></li>
     <li><a href="#development">Development</a></li>
     <li><a href="#contributing">Contributing</a></li>
     <li><a href="#license">License</a></li>
@@ -135,7 +136,7 @@ Space-separated signatures create nested subcommands:
 
 ```python
 def signature(self) -> str:
-    return "spec show"   # usecli spec show
+    return "spec show"  # usecli spec show
 ```
 
 ### JSON Output
@@ -216,10 +217,115 @@ init         Initialize usecli (usecli only)
 inspire      Random quote
 make:command Create new command (usecli only)
 make:theme   Create new theme (usecli only)
+make:bundle  Build a standalone executable with PyInstaller (usecli only)
 ```
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
+<!-- ENTRY POINTS & PACKAGING -->
+
+## Entry Points &amp; Packaging
+
+A usecli CLI can be exposed in several ways, depending on how you distribute and
+run it. There are three common setups — none requires anything but the base
+`usecli` install, and the optional bundler adds PyInstaller packaging on top.
+
+### 1. Default — console script (no entry point)
+
+The simplest setup. Declare a console script in your project's `pyproject.toml`:
+
+```toml
+[project.scripts]
+mycli = "usecli:main"
+```
+
+usecli resolves your project's config automatically from the current directory
+(config discovery), so no `main.py` is required. Install and run it:
+
+```sh
+uv add usecli
+uv run mycli --help
+```
+
+This is the **default** — no entry point file of your own is needed.
+
+### 2. Custom entry point — `main.py`
+
+If you want your own entry point, use the public runtime API. It works in both
+development and frozen bundles, and accepts an optional config path (the config
+file is always named `usecli.config.toml`):
+
+```python
+# main.py
+from usecli import run
+
+if __name__ == "__main__":
+    run()  # auto-detect project config
+    # run("path/to/usecli.config.toml")          # or point at a specific config
+```
+
+Run it in development (no PyInstaller required):
+
+```sh
+uv run python main.py --help
+```
+
+Because `run()` injects the located config explicitly, a custom `main.py` works
+regardless of whether your CLI also has a `[project.scripts]` entry.
+
+### 3. Bundler — standalone executable (optional, requires PyInstaller)
+
+The bundler is an **optional** feature gated on PyInstaller being installed.
+Install it with:
+
+```sh
+uv add "usecli[pyinstaller]"
+```
+
+Once installed, a `make:bundle` command appears (usecli only) that builds your
+project into a standalone executable. It asks which mode to use via an
+interactive menu, and confirms before building (defaults to no unless `-y`):
+
+```sh
+uv run usecli make:bundle                  # menu: one file vs one folder + confirm
+uv run usecli make:bundle --mode onefile   # single-file executable
+uv run usecli make:bundle --mode onedir    # one-folder bundle
+uv run usecli make:bundle -y               # skip the confirmation
+uv run usecli make:bundle --mode onedir -y # fully programmatic
+uv run usecli make:bundle --mode onedir --zip -y  # one-folder bundle + zip
+```
+
+When building a **one-folder** bundle, `make:bundle` asks whether to also zip
+the folder into `dist/<name>.zip` (PyInstaller's recommended distribution
+format for one-folder mode). Pass `--zip` / `--no-zip` to skip the prompt and
+force a choice; with `-y` and no flag, zipping is skipped.
+
+A `usecli-bundle` console script wraps the same build, and you can drive it from
+Python too:
+
+```sh
+uv run usecli-bundle
+uv run usecli-bundle --mode onedir
+uv run usecli-bundle --mode onedir --zip
+```
+
+```python
+from usecli import pyinstaller
+
+pyinstaller()  # auto-detect config, single-file
+pyinstaller(mode="onedir")  # one-folder bundle
+pyinstaller(mode="onedir", zip=True)  # one-folder bundle + zip
+pyinstaller("path/to/usecli.config.toml")  # or point at a specific config
+```
+
+Output lands in `dist/` — `dist/mycli` for `onefile`, or a `dist/mycli/` folder
+containing the executable (plus `_internal/` with the bundled assets) for
+`onedir`. With `zip=True`, a `dist/mycli.zip` archive is created alongside the
+folder. `make:bundle` and `usecli-bundle` are only available when PyInstaller
+is installed.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 <!-- DEVELOPMENT -->
 
 ## Development

{usecli-0.1.76 → usecli-0.1.78}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usecli"
-version = "0.1.76"
+version = "0.1.78"
 description = "A powerful Python CLI framework for building beautiful, developer-friendly command-line tools."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -11,14 +11,14 @@ classifiers = [
 ]
 dependencies = [
     "case-converter>=1.2.0",
-    "click>=8.3.1",
-    "fzf-bin>=0.67.0",
+    "click>=8.4.2",
+    "fzf-bin>=0.74.1",
     "jinja2>=3.1.6",
     "pyfiglet>=1.0.4",
-    "rich>=14.3.1",
+    "rich>=15.0.0",
     "simple-term-menu>=1.6.6",
-    "tomli>=2.4.0",
-    "typer>=0.21.1",
+    "tomli>=2.4.1",
+    "typer>=0.27.0",
 ]
 license = "MIT"
 license-files = ["LICEN[CS]E*"]
@@ -27,6 +27,9 @@ license-files = ["LICEN[CS]E*"]
 name = "Edward Boswell"
 email = "thememium@gmail.com"
 
+[project.optional-dependencies]
+pyinstaller = ["pyinstaller>=6.21.0"]
+
 [project.urls]
 Homepage = "https://github.com/thememium/usecli"
 Documentation = "https://github.com/thememium/usecli"
@@ -36,6 +39,7 @@ Changelog = "https://github.com/thememium/usecli/blob/master/CHANGELOG.md"
 
 [project.scripts]
 usecli = "usecli:main"
+usecli-bundle = "usecli.bundler:cli"
 
 [build-system]
 requires = ["uv_build>=0.10.2,<0.11.0"]
@@ -43,13 +47,14 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
-    "deptry>=0.24.0",
-    "isort>=7.0.0",
-    "poethepoet>=0.41.0",
-    "pytest>=9.0.2",
+    "deptry>=0.25.1",
+    "isort>=8.0.1",
+    "poethepoet>=0.48.0",
+    "pyinstaller>=6.21.0",
+    "pytest>=9.1.1",
     "pytest-cov>=7.1.0",
-    "ruff>=0.15.1",
-    "ty>=0.0.17",
+    "ruff>=0.16.1",
+    "ty>=0.0.65",
 ]
 
 [tool.deptry]
@@ -75,6 +80,9 @@ typecheck = "uv run ty check"
 build = "uv build --no-sources"
 release = "bash scripts/release.sh"
 
+[tool.ty.environment]
+python-version = "3.12"
+
 [tool.ty.src]
 include = [
     "src",
@@ -90,3 +98,9 @@ exclude = [
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["cli*"]
+
+[tool.setuptools.package-data]
+cli = [
+    "**/*.toml",
+    "**/*.j2",
+]

{usecli-0.1.76 → usecli-0.1.78}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usecli"
-version = "0.1.76"
+version = "0.1.78"
 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" }]
@@ -12,18 +12,21 @@ classifiers = [
 ]
 dependencies = [
   "case-converter>=1.2.0",
-  "click>=8.3.1",
-  "fzf-bin>=0.67.0",
+  "click>=8.4.2",
+  "fzf-bin>=0.74.1",
   "jinja2>=3.1.6",
   "pyfiglet>=1.0.4",
-  "rich>=14.3.1",
+  "rich>=15.0.0",
   "simple-term-menu>=1.6.6",
-  "tomli>=2.4.0",
-  "typer>=0.21.1",
+  "tomli>=2.4.1",
+  "typer>=0.27.0",
 ]
 license = "MIT"
 license-files = ["LICEN[CS]E*"]
 
+[project.optional-dependencies]
+pyinstaller = ["pyinstaller>=6.21.0"]
+
 [project.urls]
 Homepage = "https://github.com/thememium/usecli"
 Documentation = "https://github.com/thememium/usecli"
@@ -33,6 +36,7 @@ Changelog = "https://github.com/thememium/usecli/blob/master/CHANGELOG.md"
 
 [project.scripts]
 usecli = "usecli:main"
+usecli-bundle = "usecli.bundler:cli"
 
 [build-system]
 requires = ["uv_build>=0.10.2,<0.11.0"]
@@ -40,13 +44,14 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
-  "deptry>=0.24.0",
-  "isort>=7.0.0",
-  "poethepoet>=0.41.0",
-  "pytest>=9.0.2",
+  "deptry>=0.25.1",
+  "isort>=8.0.1",
+  "poethepoet>=0.48.0",
+  "pyinstaller>=6.21.0",
+  "pytest>=9.1.1",
   "pytest-cov>=7.1.0",
-  "ruff>=0.15.1",
-  "ty>=0.0.17",
+  "ruff>=0.16.1",
+  "ty>=0.0.65",
 ]
 
 [tool.deptry]
@@ -74,6 +79,9 @@ release = "bash scripts/release.sh"
 
 [tool.ty]
 
+[tool.ty.environment]
+python-version = "3.12"
+
 [tool.ty.src]
 include = ["src", "tests"]
 exclude = ["**/__pycache__", "**/.venv"]
@@ -85,3 +93,6 @@ exclude = ["**/__pycache__", "**/.venv"]
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["cli*"]
+
+[tool.setuptools.package-data]
+cli = ["**/*.toml", "**/*.j2"]

{usecli-0.1.76 → usecli-0.1.78}/src/usecli/__init__.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 import sys
 from importlib import import_module
 
+from click import Command as _ClickCommand
+
 # Avoid importing typing at module level (costs ~6ms)
 # TYPE_CHECKING is False at runtime, so the if-block never executes
 TYPE_CHECKING = False
@@ -40,6 +42,8 @@ _LAZY_EXPORTS = {
     "console": ("usecli.ui", "console"),
     "Spinner": ("usecli.progress", "Spinner"),
     "ProgressBar": ("usecli.progress", "ProgressBar"),
+    "pyinstaller": ("usecli.bundler", "pyinstaller"),
+    "run": ("usecli.entry", "run"),
 }
 
 
@@ -84,11 +88,14 @@ def _ensure_cli_initialized() -> None:
     from usecli.cli.services.command_service import CommandService
 
     # Store exceptions for error handling
+    # Typer vendors click internally and raises its own exception types.
+    # We import them dynamically since typer._click has no type stubs.
     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:
+        _typer_exceptions = import_module("typer._click.exceptions")
+        TyperBadParameter: Any = _typer_exceptions.BadParameter
+        TyperClickException: Any = _typer_exceptions.ClickException
+        TyperUsageError: Any = _typer_exceptions.UsageError
+    except (ImportError, AttributeError):
         TyperBadParameter = BadParameter
         TyperClickException = ClickException
         TyperUsageError = UsageError
@@ -138,7 +145,7 @@ def _ensure_cli_initialized() -> None:
                 return None
 
             if cmd_name in matches:
-                if (
+                if (  # pragma: no cover - unreachable duplicate of the branch above
                     cmd_name in group_alias_to_primary
                     and group_alias_to_primary[cmd_name] != cmd_name
                 ):
@@ -252,7 +259,14 @@ def _ensure_cli_initialized() -> None:
                         write_document(success_document())
                         return None
                     fail("Exit", f"Command exited with status {code}", code)
-                except Exception as error:
+                except (
+                    OSError,
+                    RuntimeError,
+                    ValueError,
+                    TypeError,
+                    AttributeError,
+                    KeyError,
+                ) as error:
                     print(
                         f"{error.__class__.__name__}: {error}",
                         file=sys.stderr,
@@ -340,19 +354,21 @@ def _get_service():
 
 
 __all__ = [
-    "BaseCommand",
     "COLOR",
-    "console",
+    "Argument",
+    "BaseCommand",
+    "Confirm",
     "Console",
-    "main",
     "Menu",
-    "Argument",
     "Option",
+    "ProgressBar",
     "Prompt",
-    "Confirm",
     "Spinner",
-    "ProgressBar",
     "colors",
+    "console",
+    "main",
+    "pyinstaller",
+    "run",
     "theme",
 ]
 
@@ -432,32 +448,40 @@ def _build_alias_to_primary(alias_registry: dict[str, list[str]]) -> dict[str, s
 PrefixMatchingGroup = None
 
 
-class _FilteredListCommand:
+class _FilteredListCommand(_ClickCommand):
     """Command that displays a filtered list of commands."""
 
     def __init__(self, prefix_filter: str) -> None:
+        super().__init__(
+            name="filtered-list",
+            context_settings={},
+            params=[],
+            callback=None,
+            help=None,
+            epilog=None,
+            short_help=None,
+            no_args_is_help=False,
+            hidden=False,
+            deprecated=False,
+        )
         self.prefix_filter = prefix_filter
-        self.name = "filtered-list"
         self.allow_extra_args = True
         self.allow_interspersed_args = True
         self.ignore_unknown_options = True
-        self.hidden = False
-        self.deprecated = False
-        self.params = []
-        self.callback = None
-        self.help = None
-        self.epilog = None
-        self.short_help = None
-        self.no_args_is_help = False
-        self.context_settings = {}
 
     def get_short_help_str(self, limit=45):
         return ""
 
-    def make_context(self, info_name: str, args: list[str], **kwargs: object):
+    def make_context(
+        self,
+        info_name: str | None,
+        args: list[str],
+        parent: object | None = None,
+        **extra: Any,
+    ):
         from click import Context
 
-        ctx = Context(self, info_name=info_name, **kwargs)  # type: ignore[arg-type]
+        ctx = Context(self, info_name=info_name, **extra)
         return ctx
 
     def invoke(self, ctx):
@@ -615,7 +639,14 @@ def main() -> None:
         if hasattr(e, "show"):
             e.show()
         sys.exit(e.exit_code if hasattr(e, "exit_code") else 1)
-    except Exception as e:
+    except (
+        OSError,
+        RuntimeError,
+        ValueError,
+        TypeError,
+        AttributeError,
+        KeyError,
+    ) as e:
         from usecli.cli.core.exceptions import UsecliUsageError
 
         styled_error = UsecliUsageError(str(e))