pyselfupdate 0.2.2__tar.gz → 0.3.0__tar.gz

{pyselfupdate-0.2.2 → pyselfupdate-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyselfupdate
-Version: 0.2.2
+Version: 0.3.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
@@ -167,34 +167,54 @@ Config(
     repo='mytool',  # defaults to tool
     package='mytool',  # distribution name, defaults to tool
     version='1.2.3',  # defaults to the installed distribution's metadata
-    token='',  # defaults to $GITHUB_TOKEN, then $GH_TOKEN, then token_func
-    token_func=None,  # called only when a request is made; for a credential that costs a subprocess
+    token='',  # see Authentication below; you almost certainly want the default
+    token_func=None,  # a source of your own, tried before $GITHUB_TOKEN_COMMAND
     tag_prefix='',  # e.g. 'cli/' for tags like cli/v1.2.3
     allow_prerelease=False,
     source=None,  # a custom Source; anything with latest_release()
 )
 ```
 
-Without a token, GitHub allows 60 API requests per hour per IP and rejects
-private repositories outright. One check per day per tool is far inside that; a
-shared egress address is not.
+## Authentication
 
-A private repository therefore needs a real token, and the usual source is the
-`gh` CLI. Pass it as `token_func`, not `token`:
+**Authenticated by default. Configure nothing.** `GitHubSource` runs `gh auth
+token` when a request is about to be made, and sends what it prints.
 
-```python
-def gh_token() -> str:
-    result = subprocess.run(['gh', 'auth', 'token'], capture_output=True, text=True)
-    return result.stdout.strip() if result.returncode == 0 else ''
+The alternative is not "no credential". It is 60 requests an hour, charged **per
+IP address** and shared with every other anonymous caller behind the same
+egress. A default that has to be opted into is a default nobody sets.
+
+Four sources, first non-empty wins:
+
+| Source | Set by | Default |
+| --- | --- | --- |
+| `Config.token` | you, in code | unset |
+| `$GITHUB_TOKEN`, then `$GH_TOKEN` | whoever runs your CLI | unset |
+| `token_func()` | you, in code | unset |
+| `$GITHUB_TOKEN_COMMAND` | whoever runs your CLI | `gh auth token` |
 
+`$GITHUB_TOKEN_COMMAND` both redirects and disables, which is what a switch has
+to do to be worth having:
 
-Config(tool='mytool', owner='you', token_func=gh_token)
+```bash
+GITHUB_TOKEN_COMMAND='pass show github/token'   # use this instead
+GITHUB_TOKEN_COMMAND='op read op://vault/gh/token'
+GITHUB_TOKEN_COMMAND=''                         # run nothing, stay anonymous
 ```
 
-`token_func` is called only when a request is actually about to be made.
-Resolving the token eagerly into `token` instead puts that subprocess in front
-of every invocation of your CLI — including the overwhelming majority where the
-notify gate declines to check at all, which is otherwise free.
+It never raises. A command that is not installed, exits non-zero, or takes
+longer than ten seconds degrades to an unauthenticated request, which still
+works against a public repository.
+
+`token_func` is now only for a credential neither the environment nor a command
+can produce. It is called lazily, for the same reason the command is: the notify
+gate resolves a `Config` on every invocation and declines most of them without
+reaching the network, and a subprocess in front of that gate is the entire cost
+worth avoiding.
+
+**This lives on `GitHubSource`, not on `Config`.** A credential is the host's
+business — a `Source` for another forge brings its own variable and its own
+command, and nothing above the `Source` protocol learns either name.
 
 ## State
 

{pyselfupdate-0.2.2 → pyselfupdate-0.3.0}/README.md

@@ -143,34 +143,54 @@ Config(
     repo='mytool',  # defaults to tool
     package='mytool',  # distribution name, defaults to tool
     version='1.2.3',  # defaults to the installed distribution's metadata
-    token='',  # defaults to $GITHUB_TOKEN, then $GH_TOKEN, then token_func
-    token_func=None,  # called only when a request is made; for a credential that costs a subprocess
+    token='',  # see Authentication below; you almost certainly want the default
+    token_func=None,  # a source of your own, tried before $GITHUB_TOKEN_COMMAND
     tag_prefix='',  # e.g. 'cli/' for tags like cli/v1.2.3
     allow_prerelease=False,
     source=None,  # a custom Source; anything with latest_release()
 )
 ```
 
-Without a token, GitHub allows 60 API requests per hour per IP and rejects
-private repositories outright. One check per day per tool is far inside that; a
-shared egress address is not.
+## Authentication
 
-A private repository therefore needs a real token, and the usual source is the
-`gh` CLI. Pass it as `token_func`, not `token`:
+**Authenticated by default. Configure nothing.** `GitHubSource` runs `gh auth
+token` when a request is about to be made, and sends what it prints.
 
-```python
-def gh_token() -> str:
-    result = subprocess.run(['gh', 'auth', 'token'], capture_output=True, text=True)
-    return result.stdout.strip() if result.returncode == 0 else ''
+The alternative is not "no credential". It is 60 requests an hour, charged **per
+IP address** and shared with every other anonymous caller behind the same
+egress. A default that has to be opted into is a default nobody sets.
+
+Four sources, first non-empty wins:
+
+| Source | Set by | Default |
+| --- | --- | --- |
+| `Config.token` | you, in code | unset |
+| `$GITHUB_TOKEN`, then `$GH_TOKEN` | whoever runs your CLI | unset |
+| `token_func()` | you, in code | unset |
+| `$GITHUB_TOKEN_COMMAND` | whoever runs your CLI | `gh auth token` |
 
+`$GITHUB_TOKEN_COMMAND` both redirects and disables, which is what a switch has
+to do to be worth having:
 
-Config(tool='mytool', owner='you', token_func=gh_token)
+```bash
+GITHUB_TOKEN_COMMAND='pass show github/token'   # use this instead
+GITHUB_TOKEN_COMMAND='op read op://vault/gh/token'
+GITHUB_TOKEN_COMMAND=''                         # run nothing, stay anonymous
 ```
 
-`token_func` is called only when a request is actually about to be made.
-Resolving the token eagerly into `token` instead puts that subprocess in front
-of every invocation of your CLI — including the overwhelming majority where the
-notify gate declines to check at all, which is otherwise free.
+It never raises. A command that is not installed, exits non-zero, or takes
+longer than ten seconds degrades to an unauthenticated request, which still
+works against a public repository.
+
+`token_func` is now only for a credential neither the environment nor a command
+can produce. It is called lazily, for the same reason the command is: the notify
+gate resolves a `Config` on every invocation and declines most of them without
+reaching the network, and a subprocess in front of that gate is the entire cost
+worth avoiding.
+
+**This lives on `GitHubSource`, not on `Config`.** A credential is the host's
+business — a `Source` for another forge brings its own variable and its own
+command, and nothing above the `Source` protocol learns either name.
 
 ## State
 

{pyselfupdate-0.2.2 → pyselfupdate-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyselfupdate"
-version = "0.2.2"
+version = "0.3.0"
 description = "Self-update and update notification for Python CLIs installed with uv tool"
 readme = "README.md"
 keywords = [
@@ -74,9 +74,9 @@ check_untyped_defs = false
 warn_return_any = false
 
 [tool.pytest.ini_options]
-addopts = "-vv"
 minversion = "8.0"
 testpaths = ["tests"]
+verbosity_assertions = 2
 
 [tool.refurb]
 enable_all = true
@@ -216,7 +216,7 @@ managed = [
     [
     "pytest",
     "ini_options",
-    "addopts",
+    "verbosity_assertions",
 ],
     [
     "pytest",

{pyselfupdate-0.2.2 → pyselfupdate-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "pyselfupdate"
-version = "0.2.2"
+version = "0.3.0"
 description = "Self-update and update notification for Python CLIs installed with uv tool"
 authors = [{ name = "Chris Birch", email = "datapointchris@gmail.com" }]
 license = { text = "MIT" }
@@ -71,9 +71,9 @@ warn_return_any = false
 # `pyright` so both basedpyright and Pylance read it.
 
 [tool.pytest.ini_options]
-addopts = "-vv"
 minversion = "8.0"
 testpaths = ["tests"]
+verbosity_assertions = 2
 
 
 [tool.refurb]
@@ -138,7 +138,7 @@ typeCheckingMode = "standard"
 analyzeUnannotatedFunctions = true  # or pylance stops analyzing in vscode
 
 [tool.forge]
-# Keys the standard owns, written by `forge dies run maintenance/sync-pyproject.sh`.
+# Keys the standard owns, written by `forge repos apply pyproject`.
 # Dropping one from the template removes it here on the next sync; a key absent
 # from this list belongs to the project and is never touched. Do not hand-edit.
 managed = [
@@ -159,7 +159,7 @@ managed = [
     ["pyright", "typeCheckingMode"],
     ["pyright", "analyzeUnannotatedFunctions"],
     ["codespell", "check-filenames"],
-    ["pytest", "ini_options", "addopts"],
+    ["pytest", "ini_options", "verbosity_assertions"],
     ["pytest", "ini_options", "minversion"],
     ["pytest", "ini_options", "testpaths"],
 ]

{pyselfupdate-0.2.2 → pyselfupdate-0.3.0}/src/pyselfupdate/github.py

@@ -8,12 +8,17 @@ from __future__ import annotations
 
 import json
 import os
+import shlex
+import shutil
+import subprocess
 import urllib.error
 import urllib.parse
 import urllib.request
 from collections.abc import Callable
 from dataclasses import dataclass
 from dataclasses import field
+from datetime import UTC
+from datetime import datetime
 
 from pyselfupdate.errors import NoReleaseError
 from pyselfupdate.errors import SelfUpdateError
@@ -24,36 +29,100 @@ API = 'https://api.github.com'
 DEFAULT_TIMEOUT = 10.0
 
 
+TOKEN_COMMAND_ENV = 'GITHUB_TOKEN_COMMAND'
+
+DEFAULT_TOKEN_COMMAND = 'gh auth token'
+"""What runs when nothing overrides it.
+
+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.
+"""
+
+
 def token_from_env() -> str:
-    """A token from the environment, or an empty string.
+    """A token from the environment, or an empty string."""
+    return os.environ.get('GITHUB_TOKEN') or os.environ.get('GH_TOKEN') or ''
+
 
-    Deliberately does not shell out to `gh auth token`. A library should not
-    spawn a subprocess a caller did not ask for, and a caller who wants that
-    behaviour can pass the token in. This matches goselfupdate.
+def token_from_command() -> str:
+    """A token from `$GITHUB_TOKEN_COMMAND`, or from `gh auth token`.
+
+    One lever that both redirects and disables, which is what a switch has to do
+    to be worth having. Unset runs the default; set to a command runs that one;
+    set to empty runs nothing and the request goes out unauthenticated.
+
+        GITHUB_TOKEN_COMMAND='pass show github/token'
+        GITHUB_TOKEN_COMMAND=''
+
+    Named for the thing it produces rather than for turning something off. A
+    `NO_GH_TOKEN` cannot say "use this other source" and reads as a claim about
+    whether one exists rather than an instruction about whether to use one.
+
+    This lives on `GitHubSource` rather than on `Config`, because the credential
+    is the host's business. A source for another forge brings its own variable
+    and its own command, and nothing above `Source` learns either name.
+
+    Never raises. Every failure -- no such command, a non-zero exit, a binary
+    that is not installed -- degrades to an unauthenticated request, which still
+    works against a public repository.
     """
-    return os.environ.get('GITHUB_TOKEN') or os.environ.get('GH_TOKEN') or ''
+    command = os.environ.get(TOKEN_COMMAND_ENV, DEFAULT_TOKEN_COMMAND)
+    argv = shlex.split(command)
+    if not argv:
+        return ''
+
+    # Resolved to a full path so the call is not a partial-path lookup, which is
+    # what bandit's B607 is about and what makes a PATH entry able to answer.
+    binary = shutil.which(argv[0])
+    if not binary:
+        return ''
+    try:
+        result = subprocess.run([binary, *argv[1:]], capture_output=True, text=True, check=False, timeout=COMMAND_TIMEOUT_SECONDS)  # noqa: S603
+    except (OSError, subprocess.SubprocessError):
+        return ''
+    return result.stdout.strip() if result.returncode == 0 else ''
+
+
+COMMAND_TIMEOUT_SECONDS = 10.0
+"""A credential helper that hangs must not hang the command someone typed.
+
+`gh` is a local read, but the variable takes an arbitrary command and a password
+manager can block on a locked vault or a touch prompt that nobody is there to
+answer -- and the update check runs unattended on a timer.
+"""
 
 
 @dataclass
 class GitHubSource:
     """Releases published on GitHub.
 
-    Without a token GitHub allows 60 API requests per hour per IP address and
-    rejects private repositories outright.
+    Authenticates by default. Without a credential GitHub allows 60 API requests
+    an hour *per IP address* -- shared with every other anonymous caller behind
+    the same egress -- and rejects private repositories outright.
+
+    Four sources, first non-empty wins: `token`, `$GITHUB_TOKEN`/`$GH_TOKEN`,
+    `token_func`, then `$GITHUB_TOKEN_COMMAND` defaulting to `gh auth token`.
     """
 
     owner: str
     repo: str
     token: str = ''
 
-    # Resolves a token when `token` is empty and neither environment variable is
-    # set. Called only when a request is actually about to be made.
+    # A source of a caller's own, tried before the command. Called only when a
+    # request is actually about to be made.
     #
     # It exists because a credential can be expensive to obtain -- a keychain
-    # prompt, a `gh auth token` subprocess -- and a caller that resolves such a
-    # token eagerly into `token` pays for it on every invocation, including the
-    # ones where the notify gate declines to check at all. That gate is
-    # otherwise free, and a subprocess spawn in front of it is the entire cost.
+    # prompt, a subprocess -- and a caller that resolves such a token eagerly
+    # into `token` pays for it on every invocation, including the ones where the
+    # notify gate declines to check at all. That gate is otherwise free, and a
+    # spawn in front of it is the entire cost.
+    #
+    # Reaching for `gh` no longer needs one: that is the default below. This is
+    # for a credential neither the environment nor a command can produce.
     token_func: Callable[[], str] | None = None
 
     timeout: float = DEFAULT_TIMEOUT
@@ -67,6 +136,16 @@ class GitHubSource:
 
     headers: dict[str, str] = field(default_factory=dict)
 
+    # Resolved once per source, because a check that also fetches a changelog
+    # makes several requests and the command behind this can be a vault unlock.
+    # None means "not yet asked", which an empty string cannot say.
+    _resolved_token: str | None = field(default=None, init=False, repr=False, compare=False)
+
+    def _credential(self) -> str:
+        if self._resolved_token is None:
+            self._resolved_token = self.token or token_from_env() or (self.token_func() if self.token_func else '') or token_from_command()
+        return self._resolved_token
+
     def latest_release(self) -> Release:
         if self.tag_prefix or self.allow_prerelease:
             return self._latest_from_list()
@@ -147,7 +226,7 @@ class GitHubSource:
         request.add_header('Accept', 'application/vnd.github+json')
         request.add_header('X-GitHub-Api-Version', '2022-11-28')
         request.add_header('User-Agent', 'pyselfupdate')
-        token = self.token or token_from_env() or (self.token_func() if self.token_func else '')
+        token = self._credential()
         if token:
             request.add_header('Authorization', f'Bearer {token}')
         for name, value in self.headers.items():
@@ -160,7 +239,7 @@ class GitHubSource:
             with urllib.request.urlopen(request, timeout=self.timeout) as response:  # noqa: S310  # nosec B310
                 return json.load(response)
         except urllib.error.HTTPError as error:
-            raise _http_error(self.owner, self.repo, error) from error
+            raise _http_error(self.owner, self.repo, error, authenticated=bool(token)) from error
         except urllib.error.URLError as error:
             raise SelfUpdateSourceFailure(f'cannot reach {API}: {error.reason}') from error
         except json.JSONDecodeError as error:
@@ -176,7 +255,7 @@ class SelfUpdateSourceFailure(SourceError):
     """
 
 
-def _http_error(owner: str, repo: str, error: urllib.error.HTTPError) -> SelfUpdateError:
+def _http_error(owner: str, repo: str, error: urllib.error.HTTPError, *, authenticated: bool) -> SelfUpdateError:
     if error.code == 404:
         # A private repository reached without a token is indistinguishable
         # from one that does not exist, and saying so is more useful than
@@ -185,10 +264,46 @@ def _http_error(owner: str, repo: str, error: urllib.error.HTTPError) -> SelfUpd
     if error.code in (401, 403):
         remaining = error.headers.get('x-ratelimit-remaining') if error.headers else None
         if remaining == '0':
-            return SelfUpdateSourceFailure('GitHub API rate limit exceeded; set GITHUB_TOKEN to raise it')
+            return SelfUpdateSourceFailure(_rate_limit_message(error, authenticated=authenticated))
         return SelfUpdateSourceFailure(f'GitHub refused the request for {owner}/{repo} ({error.code})')
     return SelfUpdateSourceFailure(f'GitHub returned {error.code} for {owner}/{repo}')
 
 
+def _rate_limit_message(error: urllib.error.HTTPError, *, authenticated: bool) -> str:
+    """Which ceiling was hit, and what to do about that one.
+
+    The two are different problems with different fixes, and one sentence for
+    both sent the wrong instruction to whichever case it was not written for.
+    Telling someone to supply a token when the request already carried one is
+    the worse half: it reads as advice to go and configure something that is
+    already configured.
+
+    The authenticated case should be rare, so it says when the ceiling lifts
+    rather than what to change -- there is nothing to change.
+    """
+    resets = _reset_clock(error)
+    if authenticated:
+        return f"GitHub's authenticated rate limit (5,000/hour) is exhausted{resets}"
+    return (
+        "GitHub's anonymous rate limit (60/hour, shared by every host on this IP) is exhausted"
+        f'{resets}. Run `gh auth login`, or set GITHUB_TOKEN, for the 5,000/hour authenticated limit'
+    )
+
+
+def _reset_clock(error: urllib.error.HTTPError) -> str:
+    """`; resets at 14:22 UTC`, or nothing when the header is absent or unusable.
+
+    A wall-clock time rather than "in 43 minutes", because the message is read
+    out of a state file long after the request that produced it and a duration
+    would be counted from the wrong instant.
+    """
+    header = error.headers.get('x-ratelimit-reset') if error.headers else None
+    try:
+        moment = datetime.fromtimestamp(int(header or ''), tz=UTC)
+    except (TypeError, ValueError, OSError, OverflowError):
+        return ''
+    return f'; resets at {moment:%H:%M} UTC'
+
+
 def _quote(ref: str) -> str:
     return urllib.parse.quote(ref, safe='')