alver 1.0.0__tar.gz

alver-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 - Almar Klein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

alver-1.0.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: alver
+Version: 1.0.0
+Summary: Version management made easy
+Keywords: versioning,releaseing
+Author: Almar Klein
+Requires-Python: >= 3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ruff ; extra == "dev"
+Requires-Dist: pre-commit ; extra == "dev"
+Requires-Dist: pytest ; extra == "dev"
+Project-URL: Homepage, https://github.com/almarklein/alver
+Project-URL: Repository, https://github.com/almarklein/alver
+Provides-Extra: dev
+
+# alver
+
+Easily manage versions, releases and changelog. Almar's version tool (went with "simpleversion" first but that was taken).
+
+```
+usage: alver [-h] {version,bump,notes,changelog-from-gh,changelog-to-gh} ...
+
+Commands to easily manage releases and changelog
+
+* Run `alver bump vx.y.z`.
+* Edit the changelog as needed.
+* Commit and create a PR for this version bump.
+* When merged, push a tag to roll the release.
+
+positional arguments:
+  {version,bump,notes,changelog-from-gh,changelog-to-gh}
+    version             Print the current project version from _version.py.
+    bump                Bump the version and add a changelog section with gh-generated release notes.
+    notes               Print the release notes for a version from CHANGELOG.md.
+    changelog-from-gh   Create/update CHANGELOG.md sections from the GitHub releases of this repo.
+    changelog-to-gh     Update the release notes of all gh releases that have a section in CHANGELOG.md.
+
+options:
+  -h, --help            show this help message and exit
+```
+
+

alver-1.0.0/README.md

@@ -0,0 +1,26 @@
+# alver
+
+Easily manage versions, releases and changelog. Almar's version tool (went with "simpleversion" first but that was taken).
+
+```
+usage: alver [-h] {version,bump,notes,changelog-from-gh,changelog-to-gh} ...
+
+Commands to easily manage releases and changelog
+
+* Run `alver bump vx.y.z`.
+* Edit the changelog as needed.
+* Commit and create a PR for this version bump.
+* When merged, push a tag to roll the release.
+
+positional arguments:
+  {version,bump,notes,changelog-from-gh,changelog-to-gh}
+    version             Print the current project version from _version.py.
+    bump                Bump the version and add a changelog section with gh-generated release notes.
+    notes               Print the release notes for a version from CHANGELOG.md.
+    changelog-from-gh   Create/update CHANGELOG.md sections from the GitHub releases of this repo.
+    changelog-to-gh     Update the release notes of all gh releases that have a section in CHANGELOG.md.
+
+options:
+  -h, --help            show this help message and exit
+```
+

alver-1.0.0/alver/__init__.py

@@ -0,0 +1,2 @@
+# from .detail import get_detailed_version, get_version_tuple
+from ._version import __version__, version_info  # noqa: F401

alver-1.0.0/alver/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m alver``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

alver-1.0.0/alver/_version.py

@@ -0,0 +1,11 @@
+__version__ = "1.0.0"
+version_info = tuple(int(i) for i in __version__.split("."))
+
+# base_version = __version__
+# try:
+#     import alver
+# except ImportError:
+#     pass
+# else:
+#     __version__ = alver.get_detailed_version()
+#     version_info = alver.get_version_tuple(__version__)

alver-1.0.0/alver/changelog.py

@@ -0,0 +1,225 @@
+"""Read and update a Keep-a-Changelog style CHANGELOG.md.
+
+Sections are headed by ``## [name]`` or ``## [name] - date`` lines, e.g.
+``## [unreleased]`` or ``## [v1.2.3] - 23-06-2026``. Everything before the
+first section header is the preamble and is preserved as-is.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import date, datetime
+
+from .detail import get_version_tuple
+
+# Matches a section header line, e.g. "## [v1.2.3] - 23-06-2026" or "## [unreleased]"
+HEADER_RE = re.compile(r"^##\s*\[([^\]]*)\]\s*(?:-\s*(.*?))?\s*$", re.MULTILINE)
+
+# Matches a section name that is a version, e.g. "v1.2.3" or "1.2.3rc1"
+VERSION_NAME_RE = re.compile(r"v?\d+(\.\d+)*[0-9A-Za-z.\-+]*", re.IGNORECASE)
+
+# Section names that hold not-yet-released changes.
+UNRELEASED_NAMES = ("unreleased", "pending")
+
+# Template for a CHANGELOG.md that does not exist yet.
+DEFAULT_CHANGELOG = """# Changelog / release notes
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Possible sections in each release:
+
+* Added: for new features.
+* Changed: for changes in existing functionality.
+* Deprecated: for soon-to-be removed features.
+* Removed: for now removed features.
+* Fixed: for any bug fixes.
+* Security: in case of vulnerabilities.
+
+"""
+
+
+@dataclass
+class Section:
+    """A ``## [name] - date`` section of the changelog."""
+
+    name: str
+    date: str = ""
+    body: str = ""
+
+
+def norm_version(v: str) -> str:
+    """Normalize a version for comparison, so 'v1.2.3' == '1.2.3'."""
+    return v.strip().removeprefix("v").lower()
+
+
+def is_version_name(name: str) -> bool:
+    """Whether a section name looks like a version, e.g. 'v1.2.3'."""
+    return bool(VERSION_NAME_RE.fullmatch(name.strip()))
+
+
+def _version_sort_key(name: str) -> tuple:
+    """Sort key for a version section name; numeric parts compare numerically."""
+    parts = get_version_tuple(norm_version(name))
+    # Wrap each part so ints and strings never compare against each other.
+    return tuple((0, p) if isinstance(p, int) else (1, str(p)) for p in parts)
+
+
+def sort_sections(sections: list[Section]) -> list[Section]:
+    """Order sections: [unreleased]/[pending] on top, then release sections
+    sorted newest version first, then any remaining sections in original order."""
+    head: list[Section] = []
+    vers: list[Section] = []
+    rest: list[Section] = []
+    for s in sections:
+        if s.name.lower() in UNRELEASED_NAMES:
+            head.append(s)
+        elif is_version_name(s.name):
+            vers.append(s)
+        else:
+            rest.append(s)
+    vers.sort(key=lambda s: _version_sort_key(s.name), reverse=True)
+    return head + vers + rest
+
+
+def parse_changelog(text: str) -> tuple[str, list[Section]]:
+    """Split changelog text into the preamble and a list of sections."""
+    matches = list(HEADER_RE.finditer(text))
+    preamble = text[: matches[0].start()] if matches else text
+    sections = []
+    for i, m in enumerate(matches):
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        sections.append(
+            Section(
+                name=m.group(1).strip(),
+                date=(m.group(2) or "").strip(),
+                body=text[m.end() : end],
+            )
+        )
+    return preamble, sections
+
+
+def render_changelog(preamble: str, sections: list[Section]) -> str:
+    """Compose changelog text from a preamble and sections."""
+    out = preamble
+    if out and not out.endswith("\n"):
+        out += "\n"
+    blocks = []
+    for s in sections:
+        header = f"## [{s.name}]"
+        if s.date:
+            header += f" - {s.date}"
+        body = s.body.strip("\n")
+        # End a non-empty body with a newline so the next header is
+        # separated by a blank line; keep empty bodies compact.
+        blocks.append(header + "\n\n" + body + ("\n" if body else ""))
+    if blocks:
+        out += "\n".join(blocks)
+    if out.strip():
+        out = out.rstrip("\n") + "\n"
+    return out
+
+
+def bump_changelog(
+    text: str, version: str, release_notes: str, today: str | None = None
+) -> str:
+    """Return updated changelog text for releasing ``version``.
+
+    A new section ``## [version] - <today>`` is added, unless a section for
+    this version already exists, in which case that section is used. If an
+    ``[unreleased]`` or ``[pending]`` section exists, its header is removed
+    and its content is moved into the target section, followed by the given
+    release notes. Sections are sorted so that newer versions are on top.
+    """
+    if today is None:
+        today = date.today().strftime("%d-%m-%Y")
+    preamble, sections = parse_changelog(text)
+    v = norm_version(version)
+
+    unreleased = next((s for s in sections if s.name.lower() in UNRELEASED_NAMES), None)
+    target = next((s for s in sections if norm_version(s.name) == v), None)
+
+    if target is None:
+        target = Section(name=version, date=today)
+        sections.append(target)
+    if unreleased is not None:
+        sections.remove(unreleased)
+
+    # Compose the target body: existing content, then the unreleased content,
+    # then the generated release notes. The notes are skipped if already
+    # present (e.g. when bumping the same version twice).
+    parts = []
+    for chunk in (target.body, unreleased.body if unreleased else ""):
+        chunk = chunk.strip("\n")
+        if chunk:
+            parts.append(chunk)
+    notes_chunk = release_notes.strip("\n")
+    if notes_chunk and notes_chunk not in "\n\n".join(parts):
+        parts.append(notes_chunk)
+    target.body = "\n\n".join(parts)
+
+    return render_changelog(preamble, sort_sections(sections))
+
+
+def changelog_from_releases(text: str, releases: list[dict]) -> str:
+    """Create/update changelog sections from gh releases (expected newest first).
+
+    Each release is a dict with keys ``tag``, ``date`` (ISO string) and ``body``.
+    Existing ``[unreleased]``/``[pending]`` sections are kept on top. A section
+    whose version matches a release tag gets its date updated from gh, its name
+    set to the larger of the two version texts (so "v0.2.0" wins over "0.2.0"),
+    and its body set to the larger of the two notes texts (gh vs changelog);
+    a release without a section gets a new one. Sections are sorted so that
+    newer versions are on top.
+    """
+    preamble, sections = parse_changelog(text)
+    by_version = {norm_version(s.name): s for s in sections}
+
+    merged: list[Section] = []
+    used: set[str] = set()
+    for rel in releases:
+        tag = str(rel.get("tag") or "").strip()
+        if not tag:
+            continue
+        key = norm_version(tag)
+        date_str = iso_to_changelog_date(rel.get("date") or "")
+        body = str(rel.get("body") or "").strip("\n")
+        existing = by_version.get(key)
+        if existing is not None and key not in used:
+            existing.date = date_str or existing.date
+            # Keep the larger notes text, whether it comes from gh or the changelog.
+            existing.body = max([existing.body.strip("\n"), body], key=len)
+            existing.name = max([tag, existing.name], key=len)
+            merged.append(existing)
+            used.add(key)
+        else:
+            merged.append(Section(name=tag, date=date_str, body=body))
+
+    # Keep all other existing sections (including [unreleased]/[pending]).
+    for s in sections:
+        if norm_version(s.name) not in used:
+            merged.append(s)
+
+    return render_changelog(preamble, sort_sections(merged))
+
+
+def iso_to_changelog_date(s: str) -> str:
+    """Convert an ISO datetime like '2026-11-09T12:34:56Z' to '09-11-2026'."""
+    try:
+        return datetime.fromisoformat(s.replace("Z", "+00:00")).strftime("%d-%m-%Y")
+    except ValueError:
+        return s
+
+
+def extract_changelog(text: str, version: str) -> str:
+    """Return the body of the section for ``version``.
+
+    Raises KeyError if there is no section for this version.
+    """
+    _preamble, sections = parse_changelog(text)
+    v = norm_version(version)
+    for s in sections:
+        if norm_version(s.name) == v:
+            return s.body.strip("\n")
+    raise KeyError(version)

alver-1.0.0/alver/cli.py

@@ -0,0 +1,406 @@
+"""Commands to easily manage releases and changelog
+
+* Run `alver bump vx.y.z`.
+* Edit the changelog as needed.
+* Commit and create a PR for this version bump.
+* When merged, push a tag to roll the release.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from . import changelog
+
+VERSION_RE = re.compile(r"v?\d+\.\d+\.\d+(?:[.\-][0-9A-Za-z]+)*$", re.IGNORECASE)
+VERSION_LINE_RE = re.compile(r"^(__version__\s*=\s*)(['\"])([^'\"]*)\2", re.MULTILINE)
+GITHUB_REMOTE_RE = re.compile(
+    r"github\.com[:/](?P<owner>[^/]+)/(?P<repo>[^/]+?)(?:\.git)?/?$"
+)
+
+# Directories to skip when searching the repo for _version.py.
+SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "venv",
+    "env",
+    "node_modules",
+    "__pycache__",
+    ".tox",
+    ".nox",
+    ".eggs",
+    "build",
+    "dist",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="alver",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser(
+        "version", help="Print the current project version from _version.py."
+    )
+
+    p_bump = sub.add_parser(
+        "bump",
+        help="Bump the version and add a changelog section with "
+        "gh-generated release notes.",
+    )
+    p_bump.add_argument("version", help="New version, e.g. v1.2.3")
+
+    p_notes = sub.add_parser(
+        "notes", help="Print the release notes for a version from CHANGELOG.md."
+    )
+    p_notes.add_argument("version", help="Version to show notes for, e.g. v1.2.3")
+
+    sub.add_parser(
+        "changelog-from-gh",
+        help="Create/update CHANGELOG.md sections from the GitHub releases "
+        "of this repo.",
+    )
+
+    sub.add_parser(
+        "changelog-to-gh",
+        help="Update the release notes of all gh releases that have a "
+        "section in CHANGELOG.md.",
+    )
+
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 2
+    if args.command == "bump":
+        return cmd_bump(args.version)
+    elif args.command == "notes":
+        return cmd_notes(args.version)
+    elif args.command == "version":
+        return cmd_version()
+    elif args.command == "changelog-from-gh":
+        return cmd_changelog_from_gh()
+    elif args.command == "changelog-to-gh":
+        return cmd_changelog_to_gh()
+    return 2  # pragma: no cover
+
+
+def cmd_changelog_to_gh() -> int:
+    repo_dir = get_repo_dir()
+    changelog_file = get_changelog_file(
+        repo_dir
+    )  # must exist; nothing to push otherwise
+    owner, repo = get_owner_repo(repo_dir)
+    releases = get_gh_releases(owner, repo, repo_dir)
+
+    _preamble, sections = changelog.parse_changelog(
+        changelog_file.read_text(encoding="utf-8")
+    )
+    by_version = {changelog.norm_version(r["tag"]): r for r in releases}
+
+    updated = 0
+    skipped: list[str] = []
+    for s in sections:
+        if not changelog.is_version_name(s.name):
+            continue  # e.g. [unreleased]
+        rel = by_version.get(changelog.norm_version(s.name))
+        if rel is None:
+            skipped.append(s.name)
+            continue
+        body = s.body.strip("\n")
+        if not body:
+            skipped.append(s.name)
+            continue
+        # Check both version texts (section name vs release tag) and use the
+        # larger one as the tag, so e.g. "v0.2.0" wins over "0.2.0".
+        tag = max([str(rel["tag"]), s.name], key=len)
+        update_gh_release(owner, repo, tag, rel.get("id"), body, repo_dir)
+        print(f"Updated release {tag} ({owner}/{repo}) with notes from CHANGELOG.md")
+        updated += 1
+
+    for name in skipped:
+        print(f"Skipped [{name}]: no matching gh release or empty section")
+    print(f"Done: {updated} release(s) updated, {len(skipped)} section(s) skipped.")
+    return 0
+
+
+def cmd_changelog_from_gh() -> int:
+    repo_dir = get_repo_dir()
+    changelog_file = get_changelog_file(repo_dir, create=True)
+    owner, repo = get_owner_repo(repo_dir)
+    releases = get_gh_releases(owner, repo, repo_dir)
+    new_text = changelog.changelog_from_releases(
+        changelog_file.read_text(encoding="utf-8"), releases
+    )
+    changelog_file.write_text(new_text, encoding="utf-8")
+    print(
+        f"Updated {changelog_file.relative_to(repo_dir)} from {len(releases)} "
+        f"gh releases ({owner}/{repo})"
+    )
+    return 0
+
+
+def cmd_version() -> int:
+    repo_dir = get_repo_dir()
+    version_file = find_version_file(repo_dir)
+    print(load_version(version_file))
+    return 0
+
+
+def load_version(path: Path) -> str:
+    """Load a _version.py as a module and return its __version__ attribute."""
+    try:
+        spec = importlib.util.spec_from_file_location("_version", path)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        return str(mod.__version__)
+    except Exception:
+        # The module-level code failed (e.g. its package is not importable);
+        # fall back to reading the literal __version__ assignment.
+        m = VERSION_LINE_RE.search(path.read_text(encoding="utf-8"))
+        if m:
+            return m.group(3)
+        sys.exit(f"error: could not determine __version__ from {path}")
+
+
+def cmd_bump(version: str) -> int:
+    if not VERSION_RE.fullmatch(version):
+        sys.exit(f"error: invalid version {version!r}, expected something like v1.2.3")
+
+    repo_dir = get_repo_dir()
+    version_file = find_version_file(repo_dir)
+    changelog_file = get_changelog_file(repo_dir, create=True)
+
+    owner, repo = get_owner_repo(repo_dir)
+    release_notes, source = get_release_notes(owner, repo, version, repo_dir)
+
+    # The changelog header and git tag keep the "v" prefix (e.g. v1.2.3),
+    # but __version__ itself must be a plain PEP 440 version (1.2.3).
+    plain_version = version[1:] if version[:1].lower() == "v" else version
+    old_version = set_version_in_file(version_file, plain_version)
+    new_text = changelog.bump_changelog(
+        changelog_file.read_text(encoding="utf-8"), version, release_notes
+    )
+    changelog_file.write_text(new_text, encoding="utf-8")
+
+    print(
+        f"Bumped {version_file.relative_to(repo_dir)}: {old_version} -> {plain_version}"
+    )
+    print(
+        f"Updated {changelog_file.relative_to(repo_dir)}: section [{version}] "
+        f"with release notes from {source} ({owner}/{repo})"
+    )
+    return 0
+
+
+def cmd_notes(version: str) -> int:
+    repo_dir = get_repo_dir()
+    changelog_file = get_changelog_file(repo_dir)
+    try:
+        body = changelog.extract_changelog(
+            changelog_file.read_text(encoding="utf-8"), version
+        )
+    except KeyError:
+        sys.exit(f"error: no section for version {version!r} in {changelog_file}")
+    print(body)
+    return 0
+
+
+# ===== Repo helpers
+
+
+def run_git(repo_dir: Path, *args: str) -> str:
+    p = subprocess.run(["git", *args], cwd=repo_dir, capture_output=True, text=True)
+    if p.returncode != 0:
+        raise RuntimeError(f"git {' '.join(args)}: {p.stderr.strip()}")
+    return p.stdout.strip()
+
+
+def get_repo_dir() -> Path:
+    try:
+        return Path(run_git(Path.cwd(), "rev-parse", "--show-toplevel")).resolve()
+    except RuntimeError as e:
+        sys.exit(f"error: not inside a git repository ({e})")
+
+
+def get_owner_repo(repo_dir: Path) -> tuple[str, str]:
+    """Derive (owner, repo) from the git remote url, e.g. git@github.com:o/r.git."""
+    remotes = run_git(repo_dir, "remote").split()
+    if not remotes:
+        sys.exit(f"error: no git remote configured in {repo_dir}")
+    name = "origin" if "origin" in remotes else remotes[0]
+    url = run_git(repo_dir, "remote", "get-url", name)
+    m = GITHUB_REMOTE_RE.search(url)
+    if not m:
+        sys.exit(
+            f"error: could not derive org/repo from remote {name!r} url {url!r} "
+            "(only github.com remotes are supported)"
+        )
+    return m.group("owner"), m.group("repo")
+
+
+def get_changelog_file(repo_dir: Path, create: bool = False) -> Path:
+    """Return the path to CHANGELOG.md, optionally creating a default one."""
+    path = repo_dir / "CHANGELOG.md"
+    if not path.is_file():
+        if not create:
+            sys.exit(f"error: no CHANGELOG.md found at {path}")
+        path.write_text(changelog.DEFAULT_CHANGELOG, encoding="utf-8")
+        print(f"Created {path.relative_to(repo_dir)}")
+    return path
+
+
+def find_version_file(repo_dir: Path) -> Path:
+    """Find the _version.py in the repo (shallowest match wins)."""
+    matches = []
+    for dirpath, dirnames, filenames in os.walk(repo_dir):
+        dirnames[:] = [
+            d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")
+        ]
+        if "_version.py" in filenames:
+            matches.append(Path(dirpath) / "_version.py")
+    if not matches:
+        sys.exit(f"error: no _version.py found in {repo_dir}")
+    matches.sort(key=lambda p: (len(p.parts), str(p)))
+    return matches[0]
+
+
+def set_version_in_file(path: Path, version: str) -> str:
+    """Set __version__ in the given _version.py. Returns the old version."""
+    text = path.read_text(encoding="utf-8")
+    m = VERSION_LINE_RE.search(text)
+    if not m:
+        sys.exit(f"error: no __version__ assignment found in {path}")
+    old = m.group(3)
+    new_text = (
+        text[: m.start()]
+        + m.group(1)
+        + m.group(2)
+        + version
+        + m.group(2)
+        + text[m.end() :]
+    )
+    path.write_text(new_text, encoding="utf-8")
+    return old
+
+
+# ===== Release notes
+
+
+def _run_gh(cmd: list[str], repo_dir: Path):
+    """Run a gh command; return None if the gh executable is not installed."""
+    try:
+        return subprocess.run(cmd, cwd=repo_dir, capture_output=True, text=True)
+    except FileNotFoundError:
+        return None
+
+
+def get_release_notes(
+    owner: str, repo: str, tag: str, repo_dir: Path
+) -> tuple[str, str]:
+    """Get release notes for ``tag`` as generated by gh. Returns (notes, source)."""
+    base_cmd = [
+        "gh",
+        "api",
+        f"repos/{owner}/{repo}/releases/generate-notes",
+        "-f",
+        f"tag_name={tag}",
+        "--jq",
+        ".body",
+    ]
+    p = _run_gh(base_cmd, repo_dir)
+    if p is not None and p.returncode == 0 and p.stdout.strip():
+        return p.stdout.strip("\n"), "gh"
+
+    # The tag may not exist yet (bump happens before tagging); point gh at the
+    # current commit instead.
+    try:
+        head = run_git(repo_dir, "rev-parse", "HEAD")
+    except RuntimeError:
+        head = "HEAD"
+    p2 = _run_gh([*base_cmd, "-f", f"target_commitish={head}"], repo_dir)
+    if p2 is not None and p2.returncode == 0 and p2.stdout.strip():
+        return p2.stdout.strip("\n"), "gh"
+
+    err_src = (
+        (p2.stderr if p2 is not None else "")
+        or (p.stderr if p is not None else "")
+        or "gh executable not found"
+    )
+    err_lines = err_src.strip().splitlines()
+    err = err_lines[-1] if err_lines else "unknown error"
+    print(
+        f"warning: could not generate release notes with gh ({err}); "
+        "falling back to git log",
+        file=sys.stderr,
+    )
+    return git_log_notes(repo_dir), "git log"
+
+
+def get_gh_releases(owner: str, repo: str, repo_dir: Path) -> list[dict]:
+    """List published gh releases (newest first) as dicts with tag/date/body."""
+    cmd = [
+        "gh",
+        "api",
+        "--paginate",
+        f"repos/{owner}/{repo}/releases?per_page=100",
+        "--jq",
+        '.[] | select(.draft | not) | {id: .id, tag: .tag_name, date: .published_at, body: (.body // "")}',
+    ]
+    p = _run_gh(cmd, repo_dir)
+    if p is None:
+        sys.exit("error: gh executable not found; cannot list releases")
+    if p.returncode != 0:
+        sys.exit(
+            f"error: could not list gh releases for {owner}/{repo}: {p.stderr.strip()}"
+        )
+    # The jq filter emits one compact JSON object per line.
+    return [json.loads(line) for line in p.stdout.splitlines() if line.strip()]
+
+
+def update_gh_release(
+    owner: str,
+    repo: str,
+    tag: str,
+    release_id,
+    body: str,
+    repo_dir: Path,
+) -> None:
+    """PATCH the notes (body) of a gh release, by tag first, then by id."""
+    endpoints = [f"repos/{owner}/{repo}/releases/tags/{tag}"]
+    if release_id is not None:
+        endpoints.append(f"repos/{owner}/{repo}/releases/{release_id}")
+    err = "gh executable not found"
+    for endpoint in endpoints:
+        p = _run_gh(
+            ["gh", "api", "-X", "PATCH", endpoint, "-f", f"body={body}"], repo_dir
+        )
+        if p is not None and p.returncode == 0:
+            return
+        if p is not None:
+            err = p.stderr.strip().splitlines()[-1] if p.stderr.strip() else err
+    sys.exit(f"error: could not update release {tag!r} ({owner}/{repo}): {err}")
+
+
+def git_log_notes(repo_dir: Path) -> str:
+    """Fallback release notes from the git log since the previous tag."""
+    try:
+        prev = run_git(repo_dir, "describe", "--tags", "--abbrev=0")
+        rev_range = f"{prev}..HEAD"
+    except RuntimeError:
+        rev_range = "HEAD"
+    return run_git(repo_dir, "log", "--pretty=format:* %s (%h)", rev_range)

alver-1.0.0/alver/detail.py

@@ -0,0 +1,171 @@
+import logging
+import subprocess
+from pathlib import Path
+
+
+def get_detailed_version(version: str, filename: str):
+    """Get a more detailed version string, based on the git tags and history."""
+
+    # Get path to the library dir, assume that filename is the dir or a file directly in that dir
+    path = Path(filename)
+    project_name = "project"
+    if path.name.endswith(".py"):
+        path = path.parent
+
+    # Get repository dir from that, assume that the repo is exactly one directory up
+    repo_dir = path.parent
+
+    # Get sensible project name, only for reporting warnings and errors
+    project_name = path.name
+    if project_name == "src":
+        project_name = repo_dir.name
+
+    # If the repo_dir is indeed a git repo, do our thing, otherwise, just return given version
+    if repo_dir and repo_dir.joinpath(".git").is_dir():
+        base_version = version.partition("+")[0].partition(".post")[0]  # Sanity
+        getter = DetailedVersionGetter(base_version, project_name, repo_dir)
+        return getter.get_version()
+    else:
+        return version
+
+
+def get_version_tuple(v: str) -> tuple:
+    """Given a version string, produce a version tuple, where integer parts are actual integers."""
+
+    # Create raw parts
+    raw_parts = []
+    sortable, _, labels = v.partition("+")
+    raw_parts.extend(sortable.split("."))
+    if labels:
+        raw_parts.append("+")
+        raw_parts.extend(labels.split("."))
+
+    # Turn integer parts into actual integers
+    parts = []
+    for part in raw_parts:
+        if not part:
+            pass
+        elif part.startswith("post"):
+            try:
+                parts.extend(["post", int(part[4:])])
+            except ValueError:
+                parts.append(part)
+        else:
+            try:
+                parts.append(int(part))
+            except ValueError:
+                parts.append(part)
+
+    return tuple(parts)
+
+
+class DetailedVersionGetter:
+    def __init__(self, base_version: str, project_name: str, repo_dir: Path):
+        self.base_version = base_version
+        self.project_name = project_name
+        self.repo_dir = repo_dir
+        self.logger = logging.getLogger(project_name)
+
+    def warning(self, m: str) -> None:
+        self.logger.warning(m)
+
+    def get_version(self) -> str:
+        try:
+            if self.repo_dir:
+                release, post, tag, dirty = self.get_version_info_from_git()
+                result = self.get_extended_version(release, post, tag, dirty)
+
+                # Warn if release does not match base_version.
+                # Can happen between bumping and tagging. And also when merging a
+                # version bump into a working branch, because we use --first-parent.
+                if release and release != self.base_version:
+                    release2, _post, _tag, _dirty = self.get_version_info_from_git(
+                        first_parent=False
+                    )
+                    if release2 != self.base_version:
+                        self.warning(
+                            f"{self.project_name} version from git ({release})"
+                            f" and __version__ ({self.base_version}) don't match."
+                        )
+
+                return result
+
+        except Exception as err:
+            self.warning(f"Error getting refined version: {err}")
+
+        return self.base_version
+
+    def get_extended_version(
+        self, release: str, post: str, tag: str, dirty: str
+    ) -> str:
+        # Start version string (__version__ string is leading).
+        version = self.base_version
+        labels = []
+
+        if release and release != self.base_version:
+            pre_label = "from_tag_" + release.replace(".", "_")
+            labels = [pre_label, f"post{post}", tag, dirty]
+        elif post and post != "0":
+            version += f".post{post}"
+            labels = [tag, dirty]
+        elif dirty:
+            labels = [tag, dirty]
+        else:
+            # If not post and not dirty, show 'clean' version without git tag.
+            pass
+
+        # Compose final version (remove empty labels, e.g. when not dirty).
+        # Everything after the '+' is not sortable (does not get in version_info).
+        label_str = ".".join(label for label in labels if label)
+        if label_str:
+            version += "+" + label_str
+        return version
+
+    def get_version_info_from_git(
+        self, *, first_parent: bool = True
+    ) -> tuple[str, str, str, str]:
+        """
+        Get (release, post, tag, dirty) from Git.
+
+        With `release` the version number from the latest tag, `post` the
+        number of commits since that tag, `tag` the git hash, and `dirty` a string
+        that is either empty or says 'dirty'.
+        """
+        # Call out to Git.
+        command = ["git", "describe", "--long", "--always", "--tags", "--dirty"]
+        if first_parent:
+            command.append("--first-parent")
+        try:
+            p = subprocess.run(
+                command, check=False, cwd=self.repo_dir, capture_output=True
+            )
+        except Exception as e:
+            self.warning(f"Could not get {self.project_name} version: {e}")
+            p = None
+
+        # Parse the result into parts.
+        if p is None:
+            parts = ("", "", "unknown")
+        else:
+            output = p.stdout.decode(errors="ignore")
+            if p.returncode:
+                stderr = p.stderr.decode(errors="ignore")
+                self.warning(
+                    f"Could not get {self.project_name} version.\n\nstdout: "
+                    + output
+                    + "\n\nstderr: "
+                    + stderr
+                )
+                parts = ("", "", "unknown")
+            else:
+                parts = output.strip().lstrip("v").split("-")
+                if len(parts) <= 2:
+                    # No tags (and thus no post). Only git hash and maybe 'dirty'.
+                    parts = ("", "", *parts)
+
+        # Return unpacked parts.
+        release = parts[0]
+        post = parts[1]
+        tag = parts[2]
+        dirty = "dirty" if len(parts) > 3 else ""
+        return release, post, tag, dirty

alver-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+# ===== Project info
+
+[project]
+dynamic = ["version"]
+name = "alver"
+description = "Version management made easy"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Almar Klein" }]
+keywords = [
+    "versioning",
+    "releaseing"
+]
+requires-python = ">= 3.10"
+dependencies = [] 
+
+[project.optional-dependencies]
+dev = ["ruff", "pre-commit", "pytest"]
+
+[project.scripts]
+alver = "alver.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/almarklein/alver"
+Repository = "https://github.com/almarklein/alver"
+
+# ===== Building
+
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+# ===== Tooling
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "N", "B", "RUF"]
+ignore = [
+    "E501",   # Line too long
+]