pyselfupdate 0.5.0__tar.gz → 0.5.2__tar.gz

pyselfupdate-0.5.2/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.coverage
+coverage.xml
+*.egg-info/

pyselfupdate-0.5.0/README.md → pyselfupdate-0.5.2/PKG-INFO

@@ -1,3 +1,26 @@
+Metadata-Version: 2.5
+Name: pyselfupdate
+Version: 0.5.2
+Summary: Self-update and update notification for Python CLIs installed with uv tool
+Project-URL: Repository, https://github.com/datapointchris/pyselfupdate
+Project-URL: Issues, https://github.com/datapointchris/pyselfupdate/issues
+Project-URL: Changelog, https://github.com/datapointchris/pyselfupdate/releases
+Author-email: Chris Birch <datapointchris@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,release,self-update,update-notifier,uv
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Software Distribution
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: typer
+Requires-Dist: typer>=0.12.0; extra == 'typer'
+Description-Content-Type: text/markdown
+
 # pyselfupdate
 
 Self-update and update notification for Python CLIs installed with `uv tool`.
@@ -71,7 +94,7 @@ Nothing is printed when any of these hold:
 | `NO_AUTO_UPDATE` or `MYTOOL_NO_AUTO_UPDATE` is set | Opted out |
 | `CI`, `BUILD_NUMBER`, `RUN_ID`, `GITHUB_ACTIONS`, `CODESPACES` | Not a human |
 | stdout or stderr is not a terminal | `mytool list > out 2>&1` must stay clean |
-| Installed from a local path, an editable checkout, or a branch | Nothing to compare against |
+| Installed from a local path, an editable checkout, a branch or a commit | Nothing to compare against |
 | Checked within the interval | One request per day, not per invocation |
 
 Presence-only, any value: `NO_AUTO_UPDATE=0` disables it, the same way
@@ -90,6 +113,13 @@ if result.update_available:
 result = update(config)  # installs, raises on failure
 ```
 
+`check` compares versions and reads nothing else. A branch build's version can
+rank below the release it is ahead of. Three commits past `v1.2.3`, a tool
+versioned from git tags builds as `1.2.3-post.3`, which semver ranks below
+`v1.2.3`. Call `require_updatable` before reporting what `check` found. It
+reads uv's receipt and refuses every install `update` refuses, as
+[What will not be updated](#what-will-not-be-updated) lists.
+
 Or take the whole command:
 
 ```python
@@ -98,6 +128,9 @@ from pyselfupdate.typercmd import add_update_command
 add_update_command(app, CONFIG)  # gives you `mytool update [--check]`
 ```
 
+`mytool update --check` reads the receipt first, as `update` does. On an
+install `update` refuses, it prints the same refusal and exits 1.
+
 `update` runs `uv tool install --force`, which **rebuilds the virtual
 environment the running interpreter lives in**. Unlike replacing a Unix binary
 — where the process holds an inode and is untouched — this pulls modules out
@@ -153,12 +186,21 @@ runtime:
 | --- | --- |
 | `git = "...git?rev=v1.2.3"` | Updatable |
 | `name = "mytool"` (from an index) | Updatable |
-| `git = "...git"` with no `rev` | Refused — tracks a branch, so its version says nothing about how far behind it is |
+| `git = "...git"` with no `rev` | Refused — tracks the default branch, so its version says nothing about how far behind it is |
+| `git = "...git?rev=main"`, or a `rev` naming a commit | Refused — uv writes `rev=` for whatever followed the `@`, so a `rev` counts as a release only when it is `tag_prefix` followed by a semantic version |
 | `directory` / `path` / `editable` | Refused — reinstalling would discard a working copy |
 | A `--with` requirement no requirements-file line reproduces, such as a relative path | Refused with `NotInstalledError` — the update would drop it |
 
 A tool that cannot be identified at all is treated as local and left alone.
 
+`update` and `mytool update --check` refuse every row marked Refused. The
+notice stays silent on each of them except the `--with` row, because a newer
+release is still worth knowing about there.
+
+A caller with a custom `source` whose refs carry a prefix sets `tag_prefix` to
+match. Without it, a tag install from that source is refused as a branch
+install.
+
 ## Configuration
 
 ```python

pyselfupdate-0.5.0/PKG-INFO → pyselfupdate-0.5.2/README.md

@@ -1,27 +1,3 @@
-Metadata-Version: 2.4
-Name: pyselfupdate
-Version: 0.5.0
-Summary: Self-update and update notification for Python CLIs installed with uv tool
-Keywords: uv,cli,self-update,update-notifier,release
-Author: Chris Birch
-Author-email: Chris Birch <datapointchris@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: System :: Software Distribution
-Classifier: Typing :: Typed
-Requires-Dist: typer>=0.12.0 ; extra == 'typer'
-Requires-Python: >=3.11
-Project-URL: Repository, https://github.com/datapointchris/pyselfupdate
-Project-URL: Issues, https://github.com/datapointchris/pyselfupdate/issues
-Project-URL: Changelog, https://github.com/datapointchris/pyselfupdate/releases
-Provides-Extra: typer
-Description-Content-Type: text/markdown
-
 # pyselfupdate
 
 Self-update and update notification for Python CLIs installed with `uv tool`.
@@ -95,7 +71,7 @@ Nothing is printed when any of these hold:
 | `NO_AUTO_UPDATE` or `MYTOOL_NO_AUTO_UPDATE` is set | Opted out |
 | `CI`, `BUILD_NUMBER`, `RUN_ID`, `GITHUB_ACTIONS`, `CODESPACES` | Not a human |
 | stdout or stderr is not a terminal | `mytool list > out 2>&1` must stay clean |
-| Installed from a local path, an editable checkout, or a branch | Nothing to compare against |
+| Installed from a local path, an editable checkout, a branch or a commit | Nothing to compare against |
 | Checked within the interval | One request per day, not per invocation |
 
 Presence-only, any value: `NO_AUTO_UPDATE=0` disables it, the same way
@@ -114,6 +90,13 @@ if result.update_available:
 result = update(config)  # installs, raises on failure
 ```
 
+`check` compares versions and reads nothing else. A branch build's version can
+rank below the release it is ahead of. Three commits past `v1.2.3`, a tool
+versioned from git tags builds as `1.2.3-post.3`, which semver ranks below
+`v1.2.3`. Call `require_updatable` before reporting what `check` found. It
+reads uv's receipt and refuses every install `update` refuses, as
+[What will not be updated](#what-will-not-be-updated) lists.
+
 Or take the whole command:
 
 ```python
@@ -122,6 +105,9 @@ from pyselfupdate.typercmd import add_update_command
 add_update_command(app, CONFIG)  # gives you `mytool update [--check]`
 ```
 
+`mytool update --check` reads the receipt first, as `update` does. On an
+install `update` refuses, it prints the same refusal and exits 1.
+
 `update` runs `uv tool install --force`, which **rebuilds the virtual
 environment the running interpreter lives in**. Unlike replacing a Unix binary
 — where the process holds an inode and is untouched — this pulls modules out
@@ -177,12 +163,21 @@ runtime:
 | --- | --- |
 | `git = "...git?rev=v1.2.3"` | Updatable |
 | `name = "mytool"` (from an index) | Updatable |
-| `git = "...git"` with no `rev` | Refused — tracks a branch, so its version says nothing about how far behind it is |
+| `git = "...git"` with no `rev` | Refused — tracks the default branch, so its version says nothing about how far behind it is |
+| `git = "...git?rev=main"`, or a `rev` naming a commit | Refused — uv writes `rev=` for whatever followed the `@`, so a `rev` counts as a release only when it is `tag_prefix` followed by a semantic version |
 | `directory` / `path` / `editable` | Refused — reinstalling would discard a working copy |
 | A `--with` requirement no requirements-file line reproduces, such as a relative path | Refused with `NotInstalledError` — the update would drop it |
 
 A tool that cannot be identified at all is treated as local and left alone.
 
+`update` and `mytool update --check` refuse every row marked Refused. The
+notice stays silent on each of them except the `--with` row, because a newer
+release is still worth knowing about there.
+
+A caller with a custom `source` whose refs carry a prefix sets `tag_prefix` to
+match. Without it, a tag install from that source is refused as a branch
+install.
+
 ## Configuration
 
 ```python

pyselfupdate-0.5.0/pyproject.toml.orig → pyselfupdate-0.5.2/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyselfupdate"
-version = "0.5.0"
+dynamic = ["version"]
 description = "Self-update and update notification for Python CLIs installed with uv tool"
 authors = [{ name = "Chris Birch", email = "datapointchris@gmail.com" }]
 license = "MIT"
@@ -112,6 +112,15 @@ select = [
     "SIM",  # flake8-simplify
     "I",    # isort
     "ICN",  # flake8-import-conventions
+    # flake8-bandit by rule, never as the family. Most of what the family
+    # reports is a subprocess call made on purpose, and silencing that takes an
+    # ignore list that grows with every project.
+    "S102",  # exec
+    "S113",  # an HTTP request with no timeout, which can hang forever
+    "S301",  # pickle, which runs code from the bytes it loads
+    "S307",  # eval
+    "S324",  # md5 or sha1 used for security
+    "S501",  # TLS certificate verification turned off
 ]
 ignore = [
     "SIM108",  # ternary operator — often less readable
@@ -131,15 +140,15 @@ datetime = "dt"
 sqlalchemy = "sa"
 "pyspark.sql.functions" = "sf"
 "pyspark.sql.types" = "st"
+dataclasses = "dc"
 
 [tool.semantic_release]
-version_toml = ["pyproject.toml:project.version"]
-commit_message = "build(release): {version}"
-build_command = """
-    pip install uv
-    uv lock --upgrade-package pyselfupdate
-    git add uv.lock
-"""
+# A feature release on 0.x stays on 0.x. python-semantic-release v10 defaults
+# this to false, which makes the next release of a 0.x project 1.0.0.
+allow_zero_version = true
+# 1.0 is a compatibility promise, so a breaking change on 0.x is a minor bump.
+# Removing this key is how the project reaches 1.0.
+major_on_zero = false
 
 
 # ---------- Build System ---------- #
@@ -165,6 +174,7 @@ managed = [
     ["ruff", "lint", "isort", "force-single-line"],
     ["ruff", "lint", "flake8-import-conventions", "banned-from"],
     ["ruff", "lint", "flake8-import-conventions", "extend-aliases", "datetime"],
+    ["ruff", "lint", "flake8-import-conventions", "extend-aliases", "dataclasses"],
     ["ruff", "lint", "flake8-import-conventions", "extend-aliases", "sqlalchemy"],
     ["ruff", "lint", "flake8-import-conventions", "extend-aliases", "pyspark.sql.functions"],
     ["ruff", "lint", "flake8-import-conventions", "extend-aliases", "pyspark.sql.types"],
@@ -187,10 +197,24 @@ managed = [
 # and extra that names them, so a local run and CI cannot disagree.
 pinned = ["ruff"]
 
-[build-system]
-requires = ["uv_build>=0.12.2,<0.13.0"]
-build-backend = "uv_build"
+# The release tag is the version. python-semantic-release finds no file to
+# stamp, so it tags the merge commit itself and writes no release commit.
+# uv_build cannot do this: its metadata has no dynamic version field.
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+style = "semver"
+
+# A new commit or tag changes the version, so it has to invalidate uv's cache.
+[tool.uv]
+cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]
 
-[tool.uv.build-backend]
-module-name = "pyselfupdate"
-module-root = "src"
+# The published sdist holds the package and its metadata, and none of the
+# repo's tooling or tests, as uv_build's did.
+[tool.hatch.build.targets.sdist]
+only-include = ["src"]
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning"]
+build-backend = "hatchling.build"

{pyselfupdate-0.5.0 → pyselfupdate-0.5.2}/src/pyselfupdate/config.py

@@ -51,7 +51,8 @@ class Config:
 
     # Selects one release stream in a repository publishing several, as in
     # "cli/" for tags of the form cli/v1.2.3. Configures the default GitHub
-    # source and is unused when `source` is supplied.
+    # source. Whatever the source, a git install whose receipt `rev` is not
+    # this prefix followed by a semantic version is refused as a branch install.
     tag_prefix: str = ''
 
     # Locates releases. Defaults to a GitHubSource built from the fields above.

{pyselfupdate-0.5.0 → pyselfupdate-0.5.2}/src/pyselfupdate/errors.py

@@ -15,11 +15,13 @@ class InvalidConfigError(SelfUpdateError):
 
 
 class LocalInstallError(SelfUpdateError):
-    """The tool was installed from a local path or as an editable checkout.
+    """The running build is not a release, so no release can be compared against it.
 
-    Reinstalling would discard a working copy for a release that may be older,
-    with no way to tell which is newer. This is the analog of goselfupdate's
-    ErrDevBuild.
+    Raised for an install from a local path or an editable checkout, for a git
+    install from a branch or a commit rather than a release tag, and for a
+    running version that is not a semantic version. Reinstalling would replace
+    the build with a release that may be older, with no way to tell which is
+    newer. This is the analog of goselfupdate's ErrDevBuild.
     """
 
 

{pyselfupdate-0.5.0 → pyselfupdate-0.5.2}/src/pyselfupdate/github.py

@@ -88,10 +88,9 @@ DEFAULT_TOKEN_COMMAND = 'gh auth token'  # nosec B105
 
 Authenticating is the default because the alternative is not "no credential" but
 "sixty requests an hour, charged per IP address and shared by every host behind
-one egress". Measured 2026-08-21 across one household: two machines checking on a
-timer held that pool at zero for whole hours, and every tool on the network that
-asked anonymously was refused. A default that has to be opted into is a default
-nobody sets, and eleven of fourteen tools here had not.
+one egress". Two machines checking on a timer can hold that pool at zero for
+whole hours, and every tool behind the same address that asks anonymously is
+then refused. A default that has to be opted into is a default nobody sets.
 """
 
 

{pyselfupdate-0.5.0 → pyselfupdate-0.5.2}/src/pyselfupdate/install.py

@@ -27,6 +27,7 @@ from dataclasses import field
 from enum import Enum
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as installed_version
+from itertools import chain
 from pathlib import Path
 
 from pyselfupdate.errors import InstallFailedError
@@ -63,9 +64,10 @@ class Installation:
     kind: InstallKind
     url: str = ''
 
-    # The requested revision, empty when the install tracks the default branch.
-    # An empty value on a GIT install is the interesting case: the tool was
-    # installed from a moving target, so "up to date" has no meaning.
+    # Whatever followed the `@` at install time: a tag, a branch or a commit,
+    # which uv records alike as `rev=`. Empty when the install follows the
+    # default branch. `updater.installed_from_release` reads it as a release
+    # tag or refuses it.
     revision: str = ''
 
     extras: tuple[str, ...] = ()
@@ -81,9 +83,6 @@ class Installation:
     # raises NotInstalledError on them instead of dropping them.
     _unrebuildable: tuple[str, ...] = field(default=(), repr=False)
 
-    def is_updatable(self) -> bool:
-        return self.kind is not InstallKind.LOCAL
-
 
 def tool_dir() -> Path:
     """uv's tool directory.
@@ -153,8 +152,9 @@ def read_installation(tool: str) -> Installation:
 def _split_git(git: str) -> tuple[str, dict[str, str], str]:
     """A receipt's git source as its URL, its query and the commit after `#`.
 
-    uv writes `...git?rev=v1.2.3` for a pinned install and omits the query
-    entirely for one that follows the default branch.
+    uv writes `...git?rev=v1.2.3` for `@v1.2.3`, `...git?rev=main` for
+    `@main`, and omits the query entirely for an install that follows the
+    default branch.
     """
     rest, _, commit = git.partition('#')
     url, _, query = rest.partition('?')
@@ -281,7 +281,7 @@ def read_lock(url: str, ref: str, *, extras: Sequence[str] = ()) -> Pins | None:
         lock = checkout / LOCK_NAME
         if not lock.is_file():
             return None
-        exported = _run([uv, *EXPORT, *(flag for extra in extras for flag in ('--extra', extra))], cwd=checkout)
+        exported = _run([uv, *EXPORT, *chain.from_iterable(('--extra', extra) for extra in extras)], cwd=checkout)
         if exported.returncode != 0:
             raise LockUnreadableError(f'uv export would not read the uv.lock at {ref}: {_reason(exported)}')
         try:
@@ -308,7 +308,9 @@ def _override_extras(lock: dict, extras: Sequence[str]) -> dict[str, tuple[str,
     for package in lock.get('package') or []:
         packages.setdefault(package.get('name', ''), []).append(package)
     project = ({'editable': '.'}, {'virtual': '.'})
-    roots = [name for name, entries in packages.items() for package in entries if package.get('source') in project]
+    roots: list[str] = []
+    for name, entries in packages.items():
+        roots.extend(name for package in entries if package.get('source') in project)
 
     active: dict[str, set[str]] = {root: set(extras) for root in roots}
     pending = list(roots)
@@ -316,7 +318,8 @@ def _override_extras(lock: dict, extras: Sequence[str]) -> dict[str, tuple[str,
         name = pending.pop()
         for package in packages.get(name, ()):
             groups = package.get('optional-dependencies') or {}
-            edges = [*(package.get('dependencies') or ()), *(edge for extra in sorted(active[name]) for edge in groups.get(extra, ()))]
+            optional = chain.from_iterable(groups.get(extra, ()) for extra in sorted(active[name]))
+            edges = [*(package.get('dependencies') or ()), *optional]
             for edge in edges:
                 target, wanted = edge.get('name', ''), set(edge.get('extra') or ())
                 if target not in active or not wanted <= active[target]:

{pyselfupdate-0.5.0 → pyselfupdate-0.5.2}/src/pyselfupdate/notifier.py

@@ -22,17 +22,18 @@ from typing import TextIO
 from pyselfupdate import state as state_module
 from pyselfupdate.config import Config
 from pyselfupdate.errors import SelfUpdateError
-from pyselfupdate.install import InstallKind
 from pyselfupdate.install import read_installation
 from pyselfupdate.updater import check
+from pyselfupdate.updater import installed_from_release
 
 DEFAULT_INTERVAL = dt.timedelta(hours=24)
 
-# Environment variables. Presence-only, any value including empty -- the
+# The environment variables every tool honors, beside its own `<TOOL>_` forms.
+# The disable switch is presence-only, any value including empty -- the
 # NO_COLOR convention -- so that NO_AUTO_UPDATE=0 cannot mean "on". The interval
 # gets its own name precisely so presence and value never share one variable.
-FLEET_DISABLE = 'NO_AUTO_UPDATE'
-FLEET_INTERVAL = 'AUTO_UPDATE_INTERVAL'
+_SHARED_DISABLE_VARIABLE = 'NO_AUTO_UPDATE'
+_SHARED_INTERVAL_VARIABLE = 'AUTO_UPDATE_INTERVAL'
 
 CI_VARIABLES = ('CI', 'BUILD_NUMBER', 'RUN_ID', 'GITHUB_ACTIONS', 'CODESPACES')
 
@@ -97,19 +98,20 @@ def notify(
 def enabled(config: Config, *, interactive: bool | None = None) -> tuple[bool, Skip | None]:
     """Whether a check would run, without touching the network or the clock.
 
-    Backs a fleet dashboard and a `<tool> update --why`. The interval is
-    deliberately not consulted: this answers "is this tool opted in", not "is it
-    due".
+    For a caller that reports why a tool does or does not check, such as a
+    dashboard listing installed tools or a `<tool> update --why`. The interval
+    is deliberately not consulted: this answers "is this tool opted in", not "is
+    it due".
     """
     if _disabled_by_env(config.tool):
         return False, Skip.DISABLED
     if _asking_for_help():
         return False, Skip.HELP
-    if not (_is_interactive() if interactive is None else interactive):
+    if not (is_interactive() if interactive is None else interactive):
         return False, Skip.NOT_A_TTY
     if _in_ci():
         return False, Skip.CI
-    if _is_local_install(config.tool):
+    if _is_local_install(config):
         return False, Skip.LOCAL_INSTALL
     return True, None
 
@@ -122,9 +124,9 @@ def _asking_for_help() -> bool:
     screen. Nothing a notice is for happens on a help screen, and the check
     costs a releases-API call and a state write every time.
 
-    It lands hardest on a reader that walks a tool's help. Measured 2026-08-22:
-    reading doit's twenty commands meant twenty-one invocations, each one
-    reaching this.
+    It lands hardest on a reader that walks a tool's help. Reading every
+    command's help is one invocation per command plus one for the root, and
+    each of them reaches this.
 
     A `--` ends the scan, because everything after it is the command's own
     argument. Skipping when it should not have costs a missed notice, which is
@@ -201,14 +203,14 @@ def _emit(message: str, *, out: TextIO | None, defer: bool) -> None:
 
 
 def _disabled_by_env(tool: str) -> bool:
-    return FLEET_DISABLE in os.environ or _tool_variable(tool, 'NO_AUTO_UPDATE') in os.environ
+    return _SHARED_DISABLE_VARIABLE in os.environ or _tool_variable(tool, 'NO_AUTO_UPDATE') in os.environ
 
 
 def _in_ci() -> bool:
     return any(name in os.environ for name in CI_VARIABLES)
 
 
-def _is_interactive(streams: Iterable[Any] | None = None) -> bool:
+def is_interactive(streams: Iterable[Any] | None = None) -> bool:
     """Both streams must be terminals.
 
     Checking both matters: `tool list | jq` should still be allowed to notify on
@@ -232,35 +234,34 @@ def _is_interactive(streams: Iterable[Any] | None = None) -> bool:
     return True
 
 
-def _is_local_install(tool: str) -> bool:
+def _is_local_install(config: Config) -> bool:
     """A local, editable, or branch-tracking install must never be nagged.
 
     Failing closed: anything that cannot be positively identified as a pinned
     release install is treated as local, because a false negative here prints a
-    wrong notice on every command in a dev checkout.
+    wrong notice on every command in a dev checkout. `update` refuses the same
+    installs, through the same `installed_from_release`.
     """
     try:
-        installation = read_installation(tool)
+        installation = read_installation(config.tool)
     except SelfUpdateError:
         return True
-    if installation.kind is InstallKind.LOCAL:
-        return True
-    return installation.kind is InstallKind.GIT and not installation.revision
+    return not installed_from_release(installation, config.tag_prefix)
 
 
 def _interval(tool: str, override: dt.timedelta | None) -> dt.timedelta:
     if override is not None:
         return override
-    for name in (_tool_variable(tool, 'AUTO_UPDATE_INTERVAL'), FLEET_INTERVAL):
+    for name in (_tool_variable(tool, 'AUTO_UPDATE_INTERVAL'), _SHARED_INTERVAL_VARIABLE):
         raw = os.environ.get(name)
         if raw:
-            parsed = _parse_interval(raw)
+            parsed = parse_interval(raw)
             if parsed is not None:
                 return parsed
     return DEFAULT_INTERVAL
 
 
-def _parse_interval(raw: str) -> dt.timedelta | None:
+def parse_interval(raw: str) -> dt.timedelta | None:
     """Parse `30m`, `24h`, `7d`, or a bare number of seconds."""
     raw = raw.strip().lower()
     if not raw:

{pyselfupdate-0.5.0 → pyselfupdate-0.5.2}/src/pyselfupdate/typercmd.py

@@ -25,7 +25,6 @@ import typer
 
 from pyselfupdate.config import Config
 from pyselfupdate.errors import SelfUpdateError
-from pyselfupdate.install import Installation
 from pyselfupdate.install import exit_now
 from pyselfupdate.updater import changelog
 from pyselfupdate.updater import check
@@ -49,8 +48,13 @@ def run_update(config: Config, *, check_only: bool = False, skip_changelog: bool
 
     Split out from the command so a CLI that wants its own flags, or that nests
     the command under a group, does not have to reimplement the reporting. The
-    output format is identical to goselfupdate's, because a fleet that reports
-    the same thing three different ways is a fleet you have to read carefully.
+    output format is identical to goselfupdate's, so tools built on either
+    library report an update in the same words.
+
+    `check_only` reads the receipt first, as an update does, and refuses the
+    same installs. A branch build's version can rank below the release it is
+    ahead of, so a check that skipped the receipt would offer that older
+    release as an update.
 
     The step order is the load-bearing part. Everything that reaches the network
     or imports a module happens before the install; after it, this process only
@@ -61,10 +65,8 @@ def run_update(config: Config, *, check_only: bool = False, skip_changelog: bool
     on, and so had just deleted.
     """
     tool = config.tool
-    installation: Installation | None = None
     try:
-        if not check_only:
-            installation = require_updatable(config)
+        installation = require_updatable(config)
         result = check(config)
     except SelfUpdateError as error:
         typer.echo(f'✗ {tool} update failed: {error}', err=True)
@@ -76,7 +78,7 @@ def run_update(config: Config, *, check_only: bool = False, skip_changelog: bool
 
     subjects = [] if skip_changelog else changelog(config, result.current, result.latest)
 
-    if installation is None:
+    if check_only:
         typer.echo(f'✓ {tool} update available: {result.current} → {result.latest}')
         _echo_changes(subjects)
         return

{pyselfupdate-0.5.0 → pyselfupdate-0.5.2}/src/pyselfupdate/updater.py

@@ -58,7 +58,12 @@ class Result:
 
 
 def check(config: Config) -> Result:
-    """Report whether a newer release exists, without installing anything."""
+    """Report whether a newer release exists, without installing anything.
+
+    Compares versions and reads nothing else. A branch build's version can rank
+    below the release it is ahead of, so a caller reporting the result runs
+    `require_updatable` first, as `update` and `typercmd.run_update` do.
+    """
     resolved = config.resolved()
     current = _current_version(resolved)
 
@@ -81,11 +86,34 @@ def require_updatable(config: Config) -> Installation:
     `typercmd.run_update` does, to fetch a changelog while the environment is
     still intact -- keeps the refusal ahead of the network by starting here.
     """
-    installation = read_installation(config.resolved().tool)
-    _require_updatable(installation)
+    resolved = config.resolved()
+    installation = read_installation(resolved.tool)
+    _require_updatable(installation, resolved.tag_prefix)
     return installation
 
 
+def installed_from_release(installation: Installation, tag_prefix: str) -> bool:
+    """Whether the running build is a release, so its version can be compared with the latest one.
+
+    An index install is. A git install is when its revision is a release tag:
+    `tag_prefix` followed by a semantic version, the form a release's
+    `install_ref` takes. uv writes `?rev=` for whatever followed the `@`.
+    `@main` and `@v1.2.3` land in the same field, so only the value tells a
+    branch from a tag.
+
+    A build from a branch reports a version that ranks wrongly against a
+    release. Versioned from git tags, a branch three commits past v1.2.3 builds
+    as `1.2.3-post.3+g<sha>`, a semver pre-release that ranks below the v1.2.3
+    it is ahead of.
+    """
+    if installation.kind is InstallKind.INDEX:
+        return True
+    if installation.kind is not InstallKind.GIT:
+        return False
+    revision = installation.revision
+    return revision.startswith(tag_prefix) and semver.is_valid(revision[len(tag_prefix) :])
+
+
 def install_release(config: Config, result: Result, installation: Installation, *, quiet: bool = True) -> Result:
     """Install the release `result` names, over the running one.
 
@@ -156,12 +184,12 @@ def changelog(config: Config, from_version: str, to_version: str) -> list[str]:
 
 
 def _current_version(config: Config) -> str:
-    """The running version, canonicalized, rejecting one that is not a release.
+    """The running version, canonicalized, rejecting one that is not a semantic version.
 
-    An install that tracks a git branch rather than a tag reports whatever
-    version was in pyproject.toml when it was built, which says nothing about
-    how far behind the checkout is. Comparing it against a tag would claim an
-    update is available on every run, or none ever.
+    An empty version, from a distribution that is not installed, fails here, and
+    so does a PEP 440 form such as `1.2.3.post3.dev0`. A branch build's version
+    usually parses, so `installed_from_release` refuses a branch install from
+    the receipt instead.
     """
     canonical = semver.canonical(config.version)
     if not semver.is_valid(canonical):
@@ -169,14 +197,14 @@ def _current_version(config: Config) -> str:
     return canonical
 
 
-def _require_updatable(installation: Installation) -> None:
+def _require_updatable(installation: Installation, tag_prefix: str) -> None:
     if installation.kind is InstallKind.LOCAL:
         raise LocalInstallError(
             f'{installation.tool} is installed from {installation.url}; update the checkout instead of reinstalling over it'
         )
-    if installation.kind is InstallKind.GIT and not installation.revision:
+    if not installed_from_release(installation, tag_prefix):
         raise LocalInstallError(
-            f'{installation.tool} is installed from a branch rather than a tag, '
+            f'{installation.tool} is installed from {installation.revision or "its default branch"} rather than a release tag, '
             f'so a release version cannot be compared against it; '
             f'reinstall from a tagged release to enable updates'
         )

pyselfupdate-0.5.0/pyproject.toml

@@ -1,300 +0,0 @@
-[project]
-name = "pyselfupdate"
-version = "0.5.0"
-description = "Self-update and update notification for Python CLIs installed with uv tool"
-license = "MIT"
-license-files = ["LICENSE"]
-readme = "README.md"
-keywords = [
-    "uv",
-    "cli",
-    "self-update",
-    "update-notifier",
-    "release",
-]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Environment :: Console",
-    "Intended Audience :: Developers",
-    "Programming Language :: Python :: 3 :: Only",
-    "Topic :: Software Development :: Libraries",
-    "Topic :: System :: Software Distribution",
-    "Typing :: Typed",
-]
-requires-python = ">=3.11"
-dependencies = []
-
-[[project.authors]]
-name = "Chris Birch"
-email = "datapointchris@gmail.com"
-
-[project.optional-dependencies]
-typer = ["typer>=0.12.0"]
-
-[project.urls]
-Repository = "https://github.com/datapointchris/pyselfupdate"
-Issues = "https://github.com/datapointchris/pyselfupdate/issues"
-Changelog = "https://github.com/datapointchris/pyselfupdate/releases"
-
-[dependency-groups]
-dev = [
-    "bandit>=1.7.8",
-    "mypy>=1.10.0",
-    "pre-commit>=4.3.0",
-    "pytest>=8.0.0",
-    "ruff==0.12.5",
-    "typer>=0.12.0",
-]
-
-[tool.bandit]
-exclude_dirs = [
-    ".git",
-    ".mypy_cache",
-    ".pytest_cache",
-    ".ruff_cache",
-    ".venv",
-    "tests",
-]
-skips = [
-    "B311",
-    "B404",
-    "B603",
-]
-
-[tool.codespell]
-skip = "*.lock"
-check-filenames = true
-check-hidden = true
-builtin = "clear,rare"
-uri-ignore-words-list = "*"
-
-[tool.mypy]
-pretty = true
-ignore_missing_imports = true
-check_untyped_defs = false
-warn_return_any = false
-
-[tool.pytest.ini_options]
-minversion = "8.0"
-testpaths = ["tests"]
-verbosity_assertions = 2
-
-[tool.refurb]
-enable_all = true
-
-[tool.ruff]
-line-length = 140
-exclude = [
-    ".git",
-    "__pycache__",
-    ".mypy_cache",
-    ".ruff_cache",
-    ".vscode",
-    ".venv",
-    "build",
-    "dist",
-]
-
-[tool.ruff.format]
-quote-style = "single"
-indent-style = "space"
-skip-magic-trailing-comma = false
-line-ending = "auto"
-docstring-code-format = true
-
-[tool.ruff.lint]
-select = [
-    "E",
-    "F",
-    "UP",
-    "B",
-    "SIM",
-    "I",
-    "ICN",
-]
-ignore = ["SIM108"]
-
-[tool.ruff.lint.isort]
-force-single-line = true
-
-[tool.ruff.lint.per-file-ignores]
-"__init__.py" = ["F401"]
-
-[tool.ruff.lint.flake8-import-conventions]
-banned-from = [
-    "datetime",
-    "pyspark.sql.functions",
-    "pyspark.sql.types",
-]
-
-[tool.ruff.lint.flake8-import-conventions.extend-aliases]
-datetime = "dt"
-sqlalchemy = "sa"
-"pyspark.sql.functions" = "sf"
-"pyspark.sql.types" = "st"
-
-[tool.semantic_release]
-version_toml = ["pyproject.toml:project.version"]
-commit_message = "build(release): {version}"
-build_command = """
-    pip install uv
-    uv lock --upgrade-package pyselfupdate
-    git add uv.lock
-"""
-
-[tool.pyright]
-typeCheckingMode = "standard"
-analyzeUnannotatedFunctions = true
-
-[tool.forge]
-managed = [
-    [
-    "ruff",
-    "line-length",
-],
-    [
-    "ruff",
-    "format",
-    "quote-style",
-],
-    [
-    "ruff",
-    "format",
-    "indent-style",
-],
-    [
-    "ruff",
-    "format",
-    "skip-magic-trailing-comma",
-],
-    [
-    "ruff",
-    "format",
-    "line-ending",
-],
-    [
-    "ruff",
-    "format",
-    "docstring-code-format",
-],
-    [
-    "ruff",
-    "lint",
-    "select",
-],
-    [
-    "ruff",
-    "lint",
-    "ignore",
-],
-    [
-    "ruff",
-    "lint",
-    "isort",
-    "force-single-line",
-],
-    [
-    "ruff",
-    "lint",
-    "flake8-import-conventions",
-    "banned-from",
-],
-    [
-    "ruff",
-    "lint",
-    "flake8-import-conventions",
-    "extend-aliases",
-    "datetime",
-],
-    [
-    "ruff",
-    "lint",
-    "flake8-import-conventions",
-    "extend-aliases",
-    "sqlalchemy",
-],
-    [
-    "ruff",
-    "lint",
-    "flake8-import-conventions",
-    "extend-aliases",
-    "pyspark.sql.functions",
-],
-    [
-    "ruff",
-    "lint",
-    "flake8-import-conventions",
-    "extend-aliases",
-    "pyspark.sql.types",
-],
-    [
-    "ruff",
-    "lint",
-    "per-file-ignores",
-    "__init__.py",
-],
-    [
-    "mypy",
-    "pretty",
-],
-    [
-    "mypy",
-    "ignore_missing_imports",
-],
-    [
-    "mypy",
-    "check_untyped_defs",
-],
-    [
-    "mypy",
-    "warn_return_any",
-],
-    [
-    "pyright",
-    "typeCheckingMode",
-],
-    [
-    "pyright",
-    "analyzeUnannotatedFunctions",
-],
-    [
-    "codespell",
-    "check-filenames",
-],
-    [
-    "codespell",
-    "check-hidden",
-],
-    [
-    "codespell",
-    "builtin",
-],
-    [
-    "codespell",
-    "uri-ignore-words-list",
-],
-    [
-    "pytest",
-    "ini_options",
-    "verbosity_assertions",
-],
-    [
-    "pytest",
-    "ini_options",
-    "minversion",
-],
-    [
-    "pytest",
-    "ini_options",
-    "testpaths",
-],
-]
-pinned = ["ruff"]
-
-[tool.uv.build-backend]
-module-name = "pyselfupdate"
-module-root = "src"
-
-[build-system]
-requires = ["uv_build>=0.12.2,<0.13.0"]
-build-backend = "uv_build"