usecli 0.1.79__tar.gz → 0.1.81__tar.gz

{usecli-0.1.79 → usecli-0.1.81}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usecli
-Version: 0.1.79
+Version: 0.1.81
 Summary: A powerful Python CLI framework for building beautiful, developer-friendly command-line tools.
 Author: Edward Boswell
 Author-email: Edward Boswell <thememium@gmail.com>
@@ -251,6 +251,35 @@ make:theme   Create new theme (usecli only)
 make:bundle  Build a standalone executable with PyInstaller (usecli only)
 ```
 
+### Upgrades
+
+Every CLI built on usecli ships `upgrade`, which detects how the running
+package was installed and delegates to the same package manager — `uv tool`,
+`pipx`, or `pip` — instead of creating a second installation:
+
+```bash
+mycli upgrade --check   # show installed/latest versions and the source
+mycli upgrade           # confirm and install the latest release
+mycli upgrade --force   # skip the prompt and the up-to-date check
+```
+
+The source comes from packaging metadata: PyPI for index installs, and the
+Git remote for PEP 610 `direct_url.json` installs. Override it in
+`usecli.config.toml` when metadata is not enough (private mirrors, missing
+`direct_url.json`, a package name that differs from the command name):
+
+```toml
+[usecli.upgrade]
+enabled = true
+source = "git"                                  # "auto" (default) | "pypi" | "git"
+package = "mycli"                               # optional
+url = "https://github.com/owner/mycli.git"      # required for "git" unless detected
+ref = "main"                                    # branch, tag, or commit
+```
+
+Frozen bundles, editable installs, and commit-pinned installs are reported
+as non-upgradeable with an explanation and manual next step.
+
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 <!-- ENTRY POINTS & PACKAGING -->

{usecli-0.1.79 → usecli-0.1.81}/README.md

@@ -221,6 +221,35 @@ make:theme   Create new theme (usecli only)
 make:bundle  Build a standalone executable with PyInstaller (usecli only)
 ```
 
+### Upgrades
+
+Every CLI built on usecli ships `upgrade`, which detects how the running
+package was installed and delegates to the same package manager — `uv tool`,
+`pipx`, or `pip` — instead of creating a second installation:
+
+```bash
+mycli upgrade --check   # show installed/latest versions and the source
+mycli upgrade           # confirm and install the latest release
+mycli upgrade --force   # skip the prompt and the up-to-date check
+```
+
+The source comes from packaging metadata: PyPI for index installs, and the
+Git remote for PEP 610 `direct_url.json` installs. Override it in
+`usecli.config.toml` when metadata is not enough (private mirrors, missing
+`direct_url.json`, a package name that differs from the command name):
+
+```toml
+[usecli.upgrade]
+enabled = true
+source = "git"                                  # "auto" (default) | "pypi" | "git"
+package = "mycli"                               # optional
+url = "https://github.com/owner/mycli.git"      # required for "git" unless detected
+ref = "main"                                    # branch, tag, or commit
+```
+
+Frozen bundles, editable installs, and commit-pinned installs are reported
+as non-upgradeable with an explanation and manual next step.
+
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 <!-- ENTRY POINTS & PACKAGING -->

{usecli-0.1.79 → usecli-0.1.81}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usecli"
-version = "0.1.79"
+version = "0.1.81"
 description = "A powerful Python CLI framework for building beautiful, developer-friendly command-line tools."
 readme = "README.md"
 requires-python = ">=3.10"

{usecli-0.1.79 → usecli-0.1.81}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usecli"
-version = "0.1.79"
+version = "0.1.81"
 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.79 → usecli-0.1.81}/src/usecli/cli/core/ui/list.py

@@ -150,8 +150,12 @@ def collect_commands_data(
             or any(alias.startswith(prefix_filter) for alias in g["aliases"])
         ]
 
-    app_name = getattr(app, "info", None)
-    app_name = getattr(app_name, "name", "usecli") or "usecli"
+    info = getattr(app, "info", None)
+    app_name = (
+        getattr(info, "name", None)
+        or get_script_command_name(default="usecli")
+        or "usecli"
+    )
 
     return {
         "usage": f"{app_name} [COMMAND] [OPTIONS] [ARGUMENTS]",

{usecli-0.1.79 → usecli-0.1.81}/src/usecli/cli/templates/usecli.config.toml.j2

@@ -12,3 +12,10 @@ hide_inspire = {{ hide_inspire | default(false) | lower }}
 
 [usecli.upgrade]
 enabled = {{ upgrade_enabled | default(true) | lower }}
+# Where upgrades come from: "auto" (detect from install metadata), "pypi", or "git".
+source = "{{ upgrade_source | default('auto') }}"
+# Git only: repository URL. Falls back to the URL in the install metadata.
+# url = "https://github.com/owner/repo.git"
+# Optional: distribution name and Git ref (branch, tag, or commit) overrides.
+# package = "my-cli"
+# ref = "main"

{usecli-0.1.79 → usecli-0.1.81}/src/usecli/shared/config/manager.py

@@ -284,8 +284,16 @@ class ConfigManager:
         "environment": "prod",
         "command_name": "usecli",
         "hide_inspire": False,
-        # Users disable the built-in `upgrade` command via [usecli.upgrade].
-        "upgrade": {"enabled": True},
+        # The built-in `upgrade` command reads [usecli.upgrade]. `source`
+        # overrides install-source detection: "auto" (packaging metadata),
+        # "pypi", or "git" (with `package`/`url`/`ref` overrides).
+        "upgrade": {
+            "enabled": True,
+            "source": "auto",
+            "package": None,
+            "url": None,
+            "ref": None,
+        },
     }
 
     def __init__(

{usecli-0.1.79 → usecli-0.1.81}/src/usecli/shared/upgrades/discovery.py

@@ -13,9 +13,13 @@ import logging
 import os
 import sys
 from dataclasses import dataclass
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 from usecli.shared.config.manager import _find_distribution_for_console_script
+from usecli.shared.upgrades.settings import config_error, from_config
+
+if TYPE_CHECKING:
+    from usecli.shared.upgrades.settings import UpgradeSettings
 
 logger = logging.getLogger(__name__)
 
@@ -170,29 +174,8 @@ def _revision_kind(revision: str | None) -> Literal["commit", "tag", "branch"] |
     return "branch"
 
 
-def discover(config: Any | None = None) -> InstallInfo:
-    """Build an :class:`InstallInfo` for the running application.
-
-    Args:
-        config: Optional ConfigManager used for the version fallback when no
-            distribution can be identified. Defaults to the global config.
-
-    Returns:
-        The discovered installation details. ``source`` is ``"unknown"`` and
-        ``pinned`` is true when the installation cannot be classified (frozen
-        bundles, unidentified distributions).
-    """
-    if getattr(sys, "frozen", False):
-        return InstallInfo(
-            package=_running_command_name() or "application",
-            version=_fallback_version(config),
-            source="unknown",
-            pinned=True,
-            pinned_reason="frozen bundle",
-            frozen=True,
-        )
-
-    dist = _find_running_distribution()
+def _from_distribution(dist: Any | None, config: Any | None) -> InstallInfo:
+    """Classify an installation from its distribution metadata."""
     if dist is None:
         logger.debug("No distribution found for the running console script")
         return InstallInfo(
@@ -285,3 +268,103 @@ def discover(config: Any | None = None) -> InstallInfo:
         pinned=True,
         pinned_reason="direct URL install",
     )
+
+
+def _override_package(
+    install: InstallInfo,
+    settings: UpgradeSettings,
+    config: Any | None,
+) -> str:
+    """Resolve the distribution name for a configured source."""
+    if settings.package:
+        return settings.package
+    if install.source != "unknown" and install.package:
+        return install.package
+    raise config_error(
+        "upgrade.source is set but the package name could not be discovered.",
+        'Set \\[usecli.upgrade] package = "<distribution name>".',
+        config,
+    )
+
+
+def _apply_settings(
+    install: InstallInfo,
+    settings: UpgradeSettings,
+    config: Any | None,
+) -> InstallInfo:
+    """Replace the discovered source with the configured one."""
+    package = _override_package(install, settings, config)
+
+    if settings.source == "pypi":
+        return InstallInfo(
+            package=package,
+            version=install.version,
+            source="index",
+            installer=install.installer,
+        )
+
+    # settings.source == "git": prefer the configured remote, then the
+    # discovered Git URL. Direct-URL and editable records are not remotes.
+    url = settings.url or (install.url if install.source == "git" else None)
+    if not url:
+        raise config_error(
+            'upgrade.source = "git" requires a repository URL.',
+            'Set \\[usecli.upgrade] url = "https://github.com/owner/repo.git".',
+            config,
+        )
+
+    # The installed revision and commit only describe ``url`` when the
+    # configured remote is the one the package was installed from.
+    same_remote = install.source == "git" and (
+        settings.url is None or settings.url == install.url
+    )
+    revision = settings.ref or (install.revision if same_remote else None)
+    pinned = _revision_kind(revision) == "commit"
+    return InstallInfo(
+        package=package,
+        version=install.version,
+        source="git",
+        installer=install.installer,
+        url=url,
+        revision=revision,
+        commit=install.commit if same_remote else None,
+        pinned=pinned,
+        pinned_reason=f"Git commit ({revision})" if pinned else None,
+    )
+
+
+def discover(config: Any | None = None) -> InstallInfo:
+    """Build an :class:`InstallInfo` for the running application.
+
+    Args:
+        config: Optional ConfigManager used for ``[usecli.upgrade]`` source
+            overrides and for the version fallback when no distribution can
+            be identified. Defaults to the global config.
+
+    Returns:
+        The discovered installation details. ``source`` is ``"unknown"`` and
+        ``pinned`` is true when the installation cannot be classified (frozen
+        bundles, unidentified distributions).
+
+    Raises:
+        UsecliConfigError: When ``[usecli.upgrade]`` configures an invalid
+            source, or omits a value that source requires.
+    """
+    if getattr(sys, "frozen", False):
+        return InstallInfo(
+            package=_running_command_name() or "application",
+            version=_fallback_version(config),
+            source="unknown",
+            pinned=True,
+            pinned_reason="frozen bundle",
+            frozen=True,
+        )
+
+    install = _from_distribution(_find_running_distribution(), config)
+    settings = from_config(config)
+    if not settings.overrides_source:
+        return install
+    return _apply_settings(install, settings, config)
+
+
+__all__ = ["InstallInfo", "InstallSource", "discover"]

usecli-0.1.81/src/usecli/shared/upgrades/settings.py

@@ -0,0 +1,129 @@
+"""Upgrade source configuration from ``[usecli.upgrade]``.
+
+The ``upgrade`` command discovers the install source from packaging
+metadata by default. CLI authors distribute builds that metadata cannot
+describe (private indexes, mirrors, Git remotes installed with a tool that
+strips ``direct_url.json``), so the source can be pinned in
+``usecli.config.toml``:
+
+.. code-block:: toml
+
+    [usecli.upgrade]
+    enabled = true
+    source = "auto"   # auto | pypi | git
+    package = "my-cli"
+    url = "https://github.com/owner/my-cli.git"   # source = "git"
+    ref = "main"                                  # branch, tag, or commit
+
+``auto`` keeps the metadata-based behaviour. Any other value is
+authoritative: discovery, checks, and installation all use it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+UpgradeSource = Literal["auto", "pypi", "git"]
+
+_SOURCES: dict[str, UpgradeSource] = {
+    "auto": "auto",
+    "pypi": "pypi",
+    "git": "git",
+}
+
+
+@dataclass(frozen=True)
+class UpgradeSettings:
+    """Upgrade source overrides configured by the CLI author.
+
+    Attributes:
+        source: Where releases come from. ``auto`` derives it from the
+            running installation's packaging metadata.
+        package: Distribution name to upgrade. Defaults to the discovered
+            distribution name.
+        url: Git remote to upgrade from. Defaults to the discovered Git URL.
+        ref: Git branch, tag, or commit to install. Defaults to the
+            discovered revision.
+    """
+
+    source: UpgradeSource = "auto"
+    package: str | None = None
+    url: str | None = None
+    ref: str | None = None
+
+    @property
+    def overrides_source(self) -> bool:
+        """Whether the configured source replaces metadata discovery."""
+        return self.source != "auto"
+
+
+def _config_file(config: Any) -> str | None:
+    path = getattr(config, "usecli_config_path", None)
+    return str(path) if path else None
+
+
+def config_error(message: str, suggestion: str, config: Any) -> Exception:
+    # Imported lazily: exceptions live in the CLI layer and import Rich.
+    from usecli.cli.core.exceptions.config import UsecliConfigError
+
+    return UsecliConfigError(
+        message,
+        config_file=_config_file(config),
+        suggestion=suggestion,
+    )
+
+
+def _text(value: Any) -> str | None:
+    """Normalize an optional string setting; blank values mean unset."""
+    if not isinstance(value, str):
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+def from_config(config: Any | None) -> UpgradeSettings:
+    """Read ``[usecli.upgrade]`` settings from a ``ConfigManager``-like object.
+
+    Args:
+        config: Config manager exposing ``get(key, default)``. Objects
+            without a ``get`` method (test doubles, ``None``) yield the
+            defaults, preserving metadata-based discovery.
+
+    Returns:
+        The resolved settings.
+
+    Raises:
+        UsecliConfigError: When ``upgrade.source`` is not one of
+            ``auto``, ``pypi``, or ``git``.
+    """
+    get = getattr(config, "get", None)
+    if get is None:
+        return UpgradeSettings()
+
+    raw_source = get("upgrade.source", "auto")
+    if raw_source is None:
+        raw_source = "auto"
+    if not isinstance(raw_source, str):
+        raise config_error(
+            f"upgrade.source must be a string, got {type(raw_source).__name__}.",
+            'Set \\[usecli.upgrade] source = "auto", "pypi", or "git".',
+            config,
+        )
+    source = _SOURCES.get(raw_source.strip().lower())
+    if source is None:
+        raise config_error(
+            f"Invalid upgrade.source '{raw_source}'.",
+            'Set \\[usecli.upgrade] source to "auto", "pypi", or "git".',
+            config,
+        )
+
+    return UpgradeSettings(
+        source=source,
+        package=_text(get("upgrade.package")),
+        url=_text(get("upgrade.url")),
+        ref=_text(get("upgrade.ref")),
+    )
+
+
+__all__ = ["UpgradeSettings", "UpgradeSource", "config_error", "from_config"]