pyselfupdate 0.5.4__tar.gz → 0.5.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyselfupdate
-Version: 0.5.4
+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:
 

{pyselfupdate-0.5.4 → 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:
 

{pyselfupdate-0.5.4 → 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.4 → pyselfupdate-0.5.5}/src/pyselfupdate/install.py

@@ -95,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.
     """
@@ -442,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.4 → 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.4 → 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.4 → 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