pyselfupdate 0.1.0__tar.gz

pyselfupdate-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.3
+Name: pyselfupdate
+Version: 0.1.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: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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/blob/main/CHANGELOG.md
+Provides-Extra: typer
+Description-Content-Type: text/markdown
+
+# pyselfupdate
+
+Self-update and update notification for Python CLIs installed with `uv tool`.
+
+Two things, used independently: tell the user once a day that a newer release
+exists, and install it when they ask. No runtime dependencies.
+
+```python
+from pyselfupdate import Config, notify, update
+
+config = Config(tool='mytool', owner='you')
+
+notify(config)  # once a day, one line if behind. Never raises.
+update(config)  # install the latest release. Raises on failure.
+```
+
+## Install
+
+```bash
+uv add pyselfupdate
+
+# with the ready-made typer command
+uv add "pyselfupdate[typer]"
+```
+
+Requires Python 3.11+.
+
+## Why
+
+A CLI distributed with `uv tool install` has no way to tell its user a newer
+version exists, so it silently drifts. The usual fix drags an HTTP client, a
+TOML parser and a version library into a tool that had none of them.
+
+This package has zero runtime dependencies — `urllib` for the network,
+`tomllib` for uv's receipt, and its own semver implementation — and CI enforces
+that by importing every module into a virtual environment containing nothing
+else.
+
+## notify
+
+Put it in your CLI's root callback and ignore the result:
+
+```python
+import typer
+from pyselfupdate import Config, notify
+
+app = typer.Typer()
+CONFIG = Config(tool='mytool', owner='you')
+
+
+@app.callback()
+def main() -> None:
+    notify(CONFIG)
+```
+
+Once per 24 hours, if a newer release exists, one line goes to stderr **after**
+your command's own output:
+
+```text
+mytool v1.4.0 available (running v1.3.2) — run `mytool update`
+```
+
+It never raises, never installs anything, and never prints an error. A failed
+check is recorded in the state file and swallowed, because an update notice
+must not be able to break the command the user actually typed.
+
+Nothing is printed when any of these hold:
+
+| Condition | Why |
+| --- | --- |
+| `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 |
+| Checked within the interval | One request per day, not per invocation |
+
+Presence-only, any value: `NO_AUTO_UPDATE=0` disables it, the same way
+[`NO_COLOR`](https://no-color.org) works. Set the interval separately with
+`AUTO_UPDATE_INTERVAL=6h` or `MYTOOL_AUTO_UPDATE_INTERVAL=30m`.
+
+## update
+
+```python
+from pyselfupdate import Config, check, update
+
+result = check(config)  # no filesystem, no install
+if result.update_available:
+    print(result.current, '->', result.latest)
+
+result = update(config)  # installs, raises on failure
+```
+
+Or take the whole command:
+
+```python
+from pyselfupdate.typercmd import add_update_command
+
+add_update_command(app, CONFIG)  # gives you `mytool update [--check]`
+```
+
+`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
+from under a live process, so anything imported afterwards may fail in ways
+that are hard to read. Make it the last thing your process does, or use
+`update_and_reexec` to replace the process with the new version immediately.
+
+## What will not be updated
+
+Read from uv's own receipt, written at install time, rather than guessed at
+runtime:
+
+| Receipt | Result |
+| --- | --- |
+| `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 |
+| `directory` / `path` / `editable` | Refused — reinstalling would discard a working copy |
+
+A tool that cannot be identified at all is treated as local and left alone.
+
+## Configuration
+
+```python
+Config(
+    tool='mytool',  # required: uv tool name, state dir, env prefix
+    owner='you',  # GitHub owner
+    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
+    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.
+
+## State
+
+`${XDG_STATE_HOME:-~/.local/state}/<tool>/autoupdate.json`, written atomically:
+
+```json
+{
+  "schema": 1,
+  "tool": "mytool",
+  "checked_at": "2026-07-26T15:07:15Z",
+  "checked_at_epoch": 1785078435,
+  "current_version": "v1.3.2",
+  "latest_version": "v1.4.0",
+  "last_error": "",
+  "skip": ""
+}
+```
+
+State, not config and not cache: it persists across runs, it is not authored by
+the user, and deleting it changes behaviour rather than merely costing a
+recompute. That is `XDG_STATE_HOME` by the Base Directory specification, and it
+is where `gh` puts the same thing.
+
+The timestamp is written **before** the network call. `gh` stamps only on
+success, so a rate-limited or offline user re-hits the API on every invocation
+until the window resets; an interval exists to bound the request rate, and only
+this ordering actually does that.
+
+## Siblings
+
+The same design in two other languages, sharing the state schema and the
+environment-variable contract:
+
+- [goselfupdate](https://github.com/datapointchris/goselfupdate) — replaces a Go binary
+- [bashselfupdate](https://github.com/datapointchris/bashselfupdate) — moves a git checkout to its newest tag
+
+## Licence
+
+MIT

pyselfupdate-0.1.0/README.md

@@ -0,0 +1,179 @@
+# pyselfupdate
+
+Self-update and update notification for Python CLIs installed with `uv tool`.
+
+Two things, used independently: tell the user once a day that a newer release
+exists, and install it when they ask. No runtime dependencies.
+
+```python
+from pyselfupdate import Config, notify, update
+
+config = Config(tool='mytool', owner='you')
+
+notify(config)  # once a day, one line if behind. Never raises.
+update(config)  # install the latest release. Raises on failure.
+```
+
+## Install
+
+```bash
+uv add pyselfupdate
+
+# with the ready-made typer command
+uv add "pyselfupdate[typer]"
+```
+
+Requires Python 3.11+.
+
+## Why
+
+A CLI distributed with `uv tool install` has no way to tell its user a newer
+version exists, so it silently drifts. The usual fix drags an HTTP client, a
+TOML parser and a version library into a tool that had none of them.
+
+This package has zero runtime dependencies — `urllib` for the network,
+`tomllib` for uv's receipt, and its own semver implementation — and CI enforces
+that by importing every module into a virtual environment containing nothing
+else.
+
+## notify
+
+Put it in your CLI's root callback and ignore the result:
+
+```python
+import typer
+from pyselfupdate import Config, notify
+
+app = typer.Typer()
+CONFIG = Config(tool='mytool', owner='you')
+
+
+@app.callback()
+def main() -> None:
+    notify(CONFIG)
+```
+
+Once per 24 hours, if a newer release exists, one line goes to stderr **after**
+your command's own output:
+
+```text
+mytool v1.4.0 available (running v1.3.2) — run `mytool update`
+```
+
+It never raises, never installs anything, and never prints an error. A failed
+check is recorded in the state file and swallowed, because an update notice
+must not be able to break the command the user actually typed.
+
+Nothing is printed when any of these hold:
+
+| Condition | Why |
+| --- | --- |
+| `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 |
+| Checked within the interval | One request per day, not per invocation |
+
+Presence-only, any value: `NO_AUTO_UPDATE=0` disables it, the same way
+[`NO_COLOR`](https://no-color.org) works. Set the interval separately with
+`AUTO_UPDATE_INTERVAL=6h` or `MYTOOL_AUTO_UPDATE_INTERVAL=30m`.
+
+## update
+
+```python
+from pyselfupdate import Config, check, update
+
+result = check(config)  # no filesystem, no install
+if result.update_available:
+    print(result.current, '->', result.latest)
+
+result = update(config)  # installs, raises on failure
+```
+
+Or take the whole command:
+
+```python
+from pyselfupdate.typercmd import add_update_command
+
+add_update_command(app, CONFIG)  # gives you `mytool update [--check]`
+```
+
+`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
+from under a live process, so anything imported afterwards may fail in ways
+that are hard to read. Make it the last thing your process does, or use
+`update_and_reexec` to replace the process with the new version immediately.
+
+## What will not be updated
+
+Read from uv's own receipt, written at install time, rather than guessed at
+runtime:
+
+| Receipt | Result |
+| --- | --- |
+| `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 |
+| `directory` / `path` / `editable` | Refused — reinstalling would discard a working copy |
+
+A tool that cannot be identified at all is treated as local and left alone.
+
+## Configuration
+
+```python
+Config(
+    tool='mytool',  # required: uv tool name, state dir, env prefix
+    owner='you',  # GitHub owner
+    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
+    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.
+
+## State
+
+`${XDG_STATE_HOME:-~/.local/state}/<tool>/autoupdate.json`, written atomically:
+
+```json
+{
+  "schema": 1,
+  "tool": "mytool",
+  "checked_at": "2026-07-26T15:07:15Z",
+  "checked_at_epoch": 1785078435,
+  "current_version": "v1.3.2",
+  "latest_version": "v1.4.0",
+  "last_error": "",
+  "skip": ""
+}
+```
+
+State, not config and not cache: it persists across runs, it is not authored by
+the user, and deleting it changes behaviour rather than merely costing a
+recompute. That is `XDG_STATE_HOME` by the Base Directory specification, and it
+is where `gh` puts the same thing.
+
+The timestamp is written **before** the network call. `gh` stamps only on
+success, so a rate-limited or offline user re-hits the API on every invocation
+until the window resets; an interval exists to bound the request rate, and only
+this ordering actually does that.
+
+## Siblings
+
+The same design in two other languages, sharing the state schema and the
+environment-variable contract:
+
+- [goselfupdate](https://github.com/datapointchris/goselfupdate) — replaces a Go binary
+- [bashselfupdate](https://github.com/datapointchris/bashselfupdate) — moves a git checkout to its newest tag
+
+## Licence
+
+MIT

pyselfupdate-0.1.0/pyproject.toml

@@ -0,0 +1,144 @@
+[project]
+name = "pyselfupdate"
+version = "0.1.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" }
+readme = "README.md"
+keywords = ["uv", "cli", "self-update", "update-notifier", "release"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Software Distribution",
+    "Typing :: Typed",
+]
+
+# The floor is deliberately below the 3.13 the author's own tools use. Raising
+# it excludes callers and needs a reason beyond convenience. 3.11 is what
+# `tomllib` requires, and reading uv's receipt without a TOML dependency is what
+# keeps this package dependency-free.
+requires-python = ">=3.11"
+
+# Empty, and enforced empty by CI. This is the package's main differentiator:
+# adding an update notice to a CLI should not drag an HTTP client, a TOML parser
+# and a version library into its dependency tree.
+dependencies = []
+
+[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/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "bandit>=1.7.8",
+    "mypy>=1.10.0",
+    "pre-commit>=4.3.0",
+    "pytest>=8.0.0",
+    "ruff>=0.7.0",
+    "typer>=0.12.0",
+]
+
+
+# ---------- Tool Configurations ---------- #
+
+
+[tool.bandit]
+exclude_dirs = [".git", ".mypy_cache", ".pytest_cache", ".ruff_cache", ".venv", "tests"]
+skips = ["B311", "B404", "B603"]
+
+
+[tool.codespell]
+skip = '*.lock'
+check-filenames = true
+
+
+[tool.mypy]
+pretty = true
+ignore_missing_imports = true
+check_untyped_defs = false
+warn_return_any = false
+
+
+[tool.pytest.ini_options]
+addopts = "-vv"
+minversion = "8.0"
+testpaths = ["tests"]
+
+
+[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 = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+]
+ignore = ["SIM108"]
+
+[tool.ruff.lint.isort]
+force-single-line = true
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+branch = "main"
+commit_message = "build(release): {version}"
+build_command = """
+    pip install uv
+    uv lock --upgrade-package pyselfupdate
+    git add uv.lock
+"""
+
+
+# ---------- Build System ---------- #
+
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "pyselfupdate"
+module-root = "src"

pyselfupdate-0.1.0/src/pyselfupdate/__init__.py

@@ -0,0 +1,72 @@
+"""Self-update and update notification for tools installed with `uv tool`.
+
+Two layers, used independently:
+
+    from pyselfupdate import Config, notify, update
+
+    config = Config(tool='syncer', owner='datapointchris')
+
+    notify(config)   # once a day, print one line if behind. Never raises.
+    update(config)   # install the latest release. Raises on failure.
+
+`notify` belongs in a CLI's root callback and its result should be ignored.
+`update` belongs behind an explicit `<tool> update` command, which is the only
+place update failures are ever reported.
+
+The package has no third-party dependencies. The optional typer integration
+lives in `pyselfupdate.typercmd` and is installed with the `typer` extra.
+"""
+
+from pyselfupdate.config import Config
+from pyselfupdate.errors import InstallFailedError
+from pyselfupdate.errors import InvalidConfigError
+from pyselfupdate.errors import LocalInstallError
+from pyselfupdate.errors import NoReleaseError
+from pyselfupdate.errors import NotInstalledError
+from pyselfupdate.errors import SelfUpdateError
+from pyselfupdate.errors import SourceError
+from pyselfupdate.github import GitHubSource
+from pyselfupdate.install import Installation
+from pyselfupdate.install import InstallKind
+from pyselfupdate.install import read_installation
+from pyselfupdate.notifier import Outcome
+from pyselfupdate.notifier import Skip
+from pyselfupdate.notifier import enabled
+from pyselfupdate.notifier import notify
+from pyselfupdate.source import Release
+from pyselfupdate.source import Source
+from pyselfupdate.state import State
+from pyselfupdate.state import read as read_state
+from pyselfupdate.updater import Result
+from pyselfupdate.updater import changelog
+from pyselfupdate.updater import check
+from pyselfupdate.updater import update
+from pyselfupdate.updater import update_and_reexec
+
+__all__ = [
+    'Config',
+    'GitHubSource',
+    'InstallFailedError',
+    'InstallKind',
+    'Installation',
+    'InvalidConfigError',
+    'LocalInstallError',
+    'NoReleaseError',
+    'NotInstalledError',
+    'Outcome',
+    'Release',
+    'Result',
+    'SelfUpdateError',
+    'Skip',
+    'Source',
+    'SourceError',
+    'State',
+    'changelog',
+    'check',
+    'enabled',
+    'notify',
+    'read_installation',
+    'read_state',
+    'update',
+    'update_and_reexec',
+]

pyselfupdate-0.1.0/src/pyselfupdate/config.py

@@ -0,0 +1,100 @@
+"""What to update, and how to reach it."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+
+from pyselfupdate.errors import InvalidConfigError
+from pyselfupdate.github import GitHubSource
+from pyselfupdate.install import current_version
+from pyselfupdate.source import Source
+
+DEFAULT_TIMEOUT = 10.0
+
+
+@dataclass
+class Config:
+    """Describes one updatable tool.
+
+    `tool` is the only required field. Everything else either has a working
+    default or is derived from it, so the common case is `Config(tool='syncer',
+    owner='datapointchris')`.
+    """
+
+    # The uv tool name. Names the receipt directory, the entry point, and the
+    # state file, and is what appears in messages.
+    tool: str
+
+    owner: str = ''
+    repo: str = ''
+
+    # The distribution name to read the running version from, when it differs
+    # from the tool name. Defaults to `tool`.
+    package: str = ''
+
+    # The running version. Defaults to the installed distribution's metadata,
+    # which is correct for anything installed as a uv tool.
+    version: str = ''
+
+    token: str = ''
+    timeout: float = DEFAULT_TIMEOUT
+    allow_prerelease: bool = False
+
+    # 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.
+    tag_prefix: str = ''
+
+    # Locates releases. Defaults to a GitHubSource built from the fields above.
+    source: Source | None = None
+
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    def require_source(self) -> Source:
+        """The resolved source.
+
+        `resolved()` always populates `source`, but the field stays optional so
+        that constructing a Config does not require one. This is the accessor
+        that expresses "past this point it is set", rather than each caller
+        asserting it.
+        """
+        if self.source is None:
+            raise InvalidConfigError('config was not resolved before use')
+        return self.source
+
+    def resolved(self) -> Config:
+        """A copy with every default filled in, so callers can assume they are set."""
+        if not self.tool:
+            raise InvalidConfigError('tool is required')
+
+        source = self.source
+        owner = self.owner
+        repo = self.repo or self.tool
+
+        if source is None:
+            if not owner:
+                raise InvalidConfigError('owner is required without a custom source')
+            source = GitHubSource(
+                owner=owner,
+                repo=repo,
+                token=self.token,
+                timeout=self.timeout,
+                allow_prerelease=self.allow_prerelease,
+                tag_prefix=self.tag_prefix,
+            )
+
+        package = self.package or self.tool
+        return Config(
+            tool=self.tool,
+            owner=owner,
+            repo=repo,
+            package=package,
+            version=self.version or current_version(package),
+            token=self.token,
+            timeout=self.timeout,
+            allow_prerelease=self.allow_prerelease,
+            tag_prefix=self.tag_prefix,
+            source=source,
+            metadata=self.metadata.copy(),
+        )