pyselfupdate 0.5.3__tar.gz → 0.5.5__tar.gz

{pyselfupdate-0.5.3 → pyselfupdate-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyselfupdate
-Version: 0.5.3
+Version: 0.5.5
 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
@@ -143,8 +143,8 @@ fail in ways that are hard to read.
 
 So make `update` the last thing the process does, then call `exit_now`. Or call
 `update_and_reexec`, which replaces the process with the release it installed,
-running the same command line. Its caller never sees the `Result`, so it writes
-`lock_warning` to stderr itself before the re-exec.
+running the same command line. `update_and_reexec` writes `lock_warning` to
+stderr itself before the re-exec, because its caller never sees the `Result`.
 
 `check` reports what `update` would install, and installs nothing:
 
@@ -221,12 +221,26 @@ later `uv tool upgrade` stays held to them.
 | Carries none | Installs unlocked and sets `lock_missing`. `lock_warning` names the tag, and `run_update` and `update_and_reexec` print it |
 | Will not clone, uv will not export its lock, or git or uv is not on `PATH` | Raises `LockUnreadableError` and installs nothing |
 
-An install from an index reads no lock, because a wheel carries none.
+An install from an index reads no lock, because a wheel carries none. It
+takes the release as a floor, `mytool>=2.0.0`, rather than a pin. uv records
+the specifier in the receipt, and `uv tool upgrade` refuses to move an exact
+pin.
 
 An update reinstalls the tool's own extras, as in `mytool[fast]`, with their
 dependencies held to the lock. Every `--with` and `--with-editable`
 requirement is passed back to uv as well.
 
+`uv tool install --force` reads nothing back from the receipt it replaces. So
+an update passes back the receipt's `--python` and the flags naming where its
+packages come from: `--index`, `--default-index`, `--index-url`,
+`--extra-index-url`, `--find-links`, `--no-index`, `--index-strategy` and
+`--keyring-provider`. Without them, a tool installed with
+`--index https://pypi.example.com/simple/` resolves its update against PyPI
+alone and is not found. An `explicit` index is left out, because only a config
+file can declare one and the reinstall reads that file again. Dropping any
+other recorded option changes how the tool resolves or builds, never whether it
+is found.
+
 ## What may be updated is read from uv's receipt, not guessed from the version
 
 uv writes `uv-receipt.toml` into the tool's directory at install time. It

{pyselfupdate-0.5.3 → pyselfupdate-0.5.5}/README.md

@@ -120,8 +120,8 @@ fail in ways that are hard to read.
 
 So make `update` the last thing the process does, then call `exit_now`. Or call
 `update_and_reexec`, which replaces the process with the release it installed,
-running the same command line. Its caller never sees the `Result`, so it writes
-`lock_warning` to stderr itself before the re-exec.
+running the same command line. `update_and_reexec` writes `lock_warning` to
+stderr itself before the re-exec, because its caller never sees the `Result`.
 
 `check` reports what `update` would install, and installs nothing:
 
@@ -198,12 +198,26 @@ later `uv tool upgrade` stays held to them.
 | Carries none | Installs unlocked and sets `lock_missing`. `lock_warning` names the tag, and `run_update` and `update_and_reexec` print it |
 | Will not clone, uv will not export its lock, or git or uv is not on `PATH` | Raises `LockUnreadableError` and installs nothing |
 
-An install from an index reads no lock, because a wheel carries none.
+An install from an index reads no lock, because a wheel carries none. It
+takes the release as a floor, `mytool>=2.0.0`, rather than a pin. uv records
+the specifier in the receipt, and `uv tool upgrade` refuses to move an exact
+pin.
 
 An update reinstalls the tool's own extras, as in `mytool[fast]`, with their
 dependencies held to the lock. Every `--with` and `--with-editable`
 requirement is passed back to uv as well.
 
+`uv tool install --force` reads nothing back from the receipt it replaces. So
+an update passes back the receipt's `--python` and the flags naming where its
+packages come from: `--index`, `--default-index`, `--index-url`,
+`--extra-index-url`, `--find-links`, `--no-index`, `--index-strategy` and
+`--keyring-provider`. Without them, a tool installed with
+`--index https://pypi.example.com/simple/` resolves its update against PyPI
+alone and is not found. An `explicit` index is left out, because only a config
+file can declare one and the reinstall reads that file again. Dropping any
+other recorded option changes how the tool resolves or builds, never whether it
+is found.
+
 ## What may be updated is read from uv's receipt, not guessed from the version
 
 uv writes `uv-receipt.toml` into the tool's directory at install time. It

{pyselfupdate-0.5.3 → pyselfupdate-0.5.5}/pyproject.toml

@@ -42,7 +42,7 @@ dev = [
     "mypy>=1.10.0",
     "pre-commit>=4.3.0",
     "pytest>=8.0.0",
-    "ruff==0.12.5",
+    "ruff==0.17.1",
     "typer>=0.12.0",
 ]
 
@@ -95,6 +95,7 @@ exclude = [
     "build",
     "dist",
 ]
+extend-exclude = ["*.md"]
 
 [tool.ruff.format]
 quote-style = "single"
@@ -158,12 +159,28 @@ major_on_zero = false
 typeCheckingMode = "standard"
 analyzeUnannotatedFunctions = true  # or pylance stops analyzing in vscode
 
+[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 } }]
+
+# The published sdist holds the package and its metadata, and none of the
+# repo's tooling or tests. hatchling's default takes the whole tree.
+[tool.hatch.build.targets.sdist]
+only-include = ["src"]
+
 [tool.forge]
 # Keys the shared toolchain standard owns, written by its generator.
 # 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 = [
     ["ruff", "line-length"],
+    ["ruff", "extend-exclude"],
     ["ruff", "format", "quote-style"],
     ["ruff", "format", "indent-style"],
     ["ruff", "format", "skip-magic-trailing-comma"],
@@ -197,24 +214,6 @@ managed = [
 # and extra that names them, so a local run and CI cannot disagree.
 pinned = ["ruff"]
 
-# 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 } }]
-
-# 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.3 → pyselfupdate-0.5.5}/src/pyselfupdate/install.py

@@ -77,6 +77,11 @@ class Installation:
     # editable back.
     with_requirements: tuple[str, ...] = ()
 
+    # uv flags reproducing the receipt's Python and package sources, from
+    # `_source_flags`. `uv tool install --force` reads neither back from the
+    # receipt it replaces, so an update passes them itself.
+    source_flags: tuple[str, ...] = ()
+
     # Names of the receipt requirements `_requirement_line` returns None for.
     # `read_installation` records them rather than raising: the notify gate
     # treats a failed read as a local install and prints no notice. `update`
@@ -90,6 +95,7 @@ def tool_dir() -> Path:
     `UV_TOOL_DIR` first. Otherwise uv's data directory: `%APPDATA%\\uv` on
     Windows, where uv ignores `XDG_DATA_HOME`, and `$XDG_DATA_HOME/uv` or
     `~/.local/share/uv` everywhere else.
+
     Resolved from the environment rather than by running `uv tool dir`, which
     costs a subprocess on a path that runs before every command.
     """
@@ -122,7 +128,8 @@ def read_installation(tool: str) -> Installation:
     except (OSError, tomllib.TOMLDecodeError) as error:
         raise NotInstalledError(f'cannot read {receipt}: {error}') from error
 
-    requirements = (payload.get('tool') or {}).get('requirements') or []
+    recorded = payload.get('tool') or {}
+    requirements = recorded.get('requirements') or []
     own = next((requirement for requirement in requirements if requirement.get('name') == tool), None)
     if own is None:
         raise NotInstalledError(f'{receipt} lists no requirement named {tool}')
@@ -140,7 +147,7 @@ def read_installation(tool: str) -> Installation:
 
     def installed_as(kind: InstallKind, url: str = '', revision: str = '') -> Installation:
         extras = tuple(own.get('extras') or ())
-        return Installation(tool, kind, url, revision, extras, tuple(rebuilt), tuple(unrebuildable))
+        return Installation(tool, kind, url, revision, extras, tuple(rebuilt), _source_flags(recorded), tuple(unrebuildable))
 
     # A local checkout, however uv spelled it. Reinstalling one would
     # discard the working copy the user is developing against.
@@ -156,6 +163,43 @@ def read_installation(tool: str) -> Installation:
     return installed_as(InstallKind.INDEX)
 
 
+def _source_flags(recorded: dict) -> tuple[str, ...]:
+    """The uv flags that reinstall onto the receipt's Python from the receipt's package sources.
+
+    Without them a reinstall resolves against PyPI alone and moves to uv's
+    default Python. uv records a setting from a flag, the environment or a
+    config file alike, and cannot say which. An `explicit` or `flat` index only
+    a config file can declare, and that file is read again by the reinstall, so
+    it is left out. Dropping any other recorded option changes how the tool
+    resolves or builds, never whether its packages can be found.
+    """
+    options = recorded.get('options') or {}
+    pairs: list[tuple[str, str]] = []
+    if recorded.get('python'):
+        pairs.append(('--python', str(recorded['python'])))
+    for index in options.get('index') or ():
+        if index.get('explicit') or index.get('format', 'simple') != 'simple' or not index.get('url'):
+            continue
+        if index.get('default'):
+            pairs.append(('--default-index', str(index['url'])))
+        else:
+            name = index.get('name')
+            pairs.append(('--index', f'{name}={index["url"]}' if name else str(index['url'])))
+    if options.get('index-url'):
+        pairs.append(('--index-url', str(options['index-url'])))
+    pairs += [('--extra-index-url', str(url)) for url in options.get('extra-index-url') or ()]
+    pairs += [('--find-links', str(location)) for location in options.get('find-links') or ()]
+    pairs += [(f'--{key}', str(options[key])) for key in ('index-strategy', 'keyring-provider') if options.get(key)]
+    if options.get('no-index'):
+        pairs.append(('--no-index', ''))
+
+    # A source declared in a config file is recorded again beside the flag that
+    # passes it back. Passing each source once holds it at two copies, rather
+    # than adding one to the receipt per update.
+    distinct = dict.fromkeys(pairs)
+    return tuple(part for flag, value in distinct for part in (flag, value) if part)
+
+
 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 `#`.
 
@@ -221,11 +265,15 @@ def current_version(package: str) -> str:
 
 
 def requirement_for(installation: Installation, ref: str) -> str:
-    """The requirement string that installs `ref` of an already-installed tool, with the extras it has."""
+    """The requirement string that installs `ref` of an already-installed tool, with the extras it has.
+
+    An index install takes `ref` as a floor. uv records the specifier in the
+    receipt, and `uv tool upgrade` refuses to move an exact pin.
+    """
     named = f'{installation.tool}[{",".join(installation.extras)}]' if installation.extras else installation.tool
     if installation.kind is InstallKind.GIT:
         return f'{named} @ git+{installation.url}@{ref}'
-    return f'{named}=={ref.removeprefix("v")}'
+    return f'{named}>={ref.removeprefix("v")}'
 
 
 @dataclass(frozen=True)
@@ -355,7 +403,14 @@ def _pins_from_export(exported: str, extras: dict[str, tuple[str, ...]]) -> Pins
     return Pins(tuple(constraints), tuple(overrides))
 
 
-def run_install(requirement: str, *, quiet: bool = True, pins: Pins | None = None, with_requirements: Sequence[str] = ()) -> None:
+def run_install(
+    requirement: str,
+    *,
+    quiet: bool = True,
+    pins: Pins | None = None,
+    with_requirements: Sequence[str] = (),
+    source_flags: Sequence[str] = (),
+) -> None:
     """Install a requirement over any existing tool of that name, held to `pins` when given.
 
     `with_requirements` are requirements-file lines installed beside the tool,
@@ -374,7 +429,7 @@ def run_install(requirement: str, *, quiet: bool = True, pins: Pins | None = Non
             listed = Path(scratch) / 'with.txt'
             listed.write_text(''.join(f'{line}\n' for line in with_requirements), encoding='utf-8')
             beside = ['--with-requirements', str(listed)]
-        command = [executable, 'tool', 'install', '--force', *held, *beside, requirement]
+        command = [executable, 'tool', 'install', '--force', *source_flags, *held, *beside, requirement]
         if quiet:
             command.insert(1, '--quiet')
         completed = _run(command)
@@ -388,11 +443,11 @@ def _run(command: list[str], cwd: Path | None = None) -> subprocess.CompletedPro
 
 
 def _reason(completed: subprocess.CompletedProcess[str]) -> str:
-    """Everything a failing command printed, rather than one line of it.
+    """Everything a failing command printed.
 
-    uv puts a lock's schema error on its first line, git puts a missing ref on
-    its last, and uv wraps a resolution failure so its last line is half a
-    sentence.
+    No single line carries the reason: uv puts a lock's schema error on its
+    first line, git puts a missing ref on its last, and uv wraps a resolution
+    failure so its last line is half a sentence.
     """
     return (completed.stderr or completed.stdout or '').strip() or f'exit status {completed.returncode}'
 

{pyselfupdate-0.5.3 → pyselfupdate-0.5.5}/src/pyselfupdate/notifier.py

@@ -124,10 +124,6 @@ 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. 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
     the cheap direction to be wrong in.

{pyselfupdate-0.5.3 → pyselfupdate-0.5.5}/src/pyselfupdate/typercmd.py

@@ -32,10 +32,39 @@ from pyselfupdate.updater import install_release
 from pyselfupdate.updater import require_updatable
 
 
+def update_help(tool: str, name: str, markup_mode: str | None) -> str:
+    """The update command's help: one line on what it does, then annotated examples.
+
+    Each example keeps a line of its own under each of typer's markup modes,
+    which lay out a help's later paragraphs differently. Markdown joins a
+    paragraph's lines, so the examples sit in a fenced block there. Rich markup
+    keeps the lines as written and would print a fence's backticks. Without
+    rich, click rewraps every paragraph that does not open with its `\\b`
+    marker.
+    """
+    command = f'{tool} {name}'
+    width = len(command) + len(' --no-changelog') + 2
+    examples = '\n'.join(
+        f'{call:<{width}}{purpose}'
+        for call, purpose in (
+            (command, 'install the newest and list its commits'),
+            (f'{command} --check', 'only report whether a newer one exists'),
+            (f'{command} --no-changelog', 'install it without listing its commits'),
+        )
+    )
+    if markup_mode == 'markdown':
+        block = f'```text\n{examples}\n```'
+    elif markup_mode == 'rich':
+        block = examples
+    else:
+        block = f'\b\n{examples}'
+    return f'Update {tool} to the latest release\n\nExamples:\n\n{block}'
+
+
 def add_update_command(app: typer.Typer, config: Config, *, name: str = 'update') -> None:
     """Register `<tool> update` on an existing typer app."""
 
-    @app.command(name=name, help=f'Update {config.tool} to the latest release')
+    @app.command(name=name, help=update_help(config.tool, name, app.rich_markup_mode))
     def update_command(
         check_only: bool = typer.Option(False, '--check', help='Report whether an update is available without installing it'),
         skip_changelog: bool = typer.Option(False, '--no-changelog', help='Do not list the commits between versions'),
@@ -52,17 +81,15 @@ def run_update(config: Config, *, check_only: bool = False, skip_changelog: bool
     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
-    prints what it already holds and exits without unwinding. Both halves of
-    that come from a real failure. A tool that fetched its changelog after
-    replacing its own environment died on its HTTP client's lazy import of a
-    transport module. The release it had just installed did not depend on that
-    module, so the install had deleted it.
+    same installs. `updater.installed_from_release` says why a version alone
+    cannot decide.
+
+    Everything that reaches the network or imports a module happens before the
+    install; after it, this process only prints what it already holds and exits
+    without unwinding. An import after the install can name a module the new
+    release no longer ships, which the install has already deleted. An HTTP
+    client's lazy import of its transport is one, and it raises ImportError
+    after the update has succeeded.
     """
     tool = config.tool
     try:

{pyselfupdate-0.5.3 → pyselfupdate-0.5.5}/src/pyselfupdate/updater.py

@@ -97,9 +97,8 @@ def installed_from_release(installation: Installation, tag_prefix: str) -> bool:
 
     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.
+    `install_ref` takes. `Installation.revision` holds a branch or a commit in
+    the same field, so only the value tells them apart.
 
     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
@@ -131,7 +130,13 @@ def install_release(config: Config, result: Result, installation: Installation,
 
     ref = result.release.install_ref()
     pins = read_lock(installation.url, ref, extras=installation.extras) if installation.kind is InstallKind.GIT else None
-    run_install(requirement_for(installation, ref), quiet=quiet, pins=pins, with_requirements=installation.with_requirements)
+    run_install(
+        requirement_for(installation, ref),
+        quiet=quiet,
+        pins=pins,
+        with_requirements=installation.with_requirements,
+        source_flags=installation.source_flags,
+    )
 
     return Result(
         current=result.current,