release-creator 0.1.0__py3-none-any.whl

release_creator/__init__.py

@@ -0,0 +1 @@
+"""Tools for consistent project releases."""

release_creator/__main__.py

@@ -0,0 +1,6 @@
+"""Run release-creator as a module."""
+
+from release_creator.cli import main
+
+if __name__ == "__main__":
+    main()

release_creator/cli.py

@@ -0,0 +1,38 @@
+"""Keep command registration separate from release work."""
+
+import argparse
+
+lazy from release_creator.fragments.cli import register as register_fragments
+lazy from release_creator.notes.cli import register as register_notes
+lazy from release_creator.tags.cli import register as register_tags
+
+
+def main() -> None:
+    """Report command input errors through argparse's exit path."""
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        args.handler(args)
+    except (OSError, ValueError) as error:
+        parser.error(str(error))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Expose the same parser to Sphinx and the executable.
+
+    Returns:
+        Parser shared by the documentation and command line.
+
+    """
+    parser = argparse.ArgumentParser(description="Release preparation tools")
+    commands = parser.add_subparsers(dest="command", required=True)
+    register_notes(commands)
+    register_fragments(commands)
+    register_tags(commands)
+    return parser
+
+
+__all__ = [
+    "build_parser",
+    "main",
+]

release_creator/fragments/__init__.py

@@ -0,0 +1 @@
+"""Named fragment handling for release preparation."""

release_creator/fragments/cli.py

@@ -0,0 +1,32 @@
+"""Keep fragment options beside PR link insertion."""
+
+from pathlib import Path
+lazy import argparse
+
+lazy from release_creator.fragments.git import commit_subjects_from_git
+lazy from release_creator.fragments.links import add_pull_request_links
+
+
+def register(commands: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    """Keep fragment options with the fragment command."""
+    fragments = commands.add_parser("fragments", help="link named fragments to their squash pull requests")
+    fragments.add_argument("--directory", type=Path, default=Path("changelog.d"), help="Towncrier fragment directory")
+    fragments.add_argument("--repository", required=True, help="GitHub owner/repository")
+    source = fragments.add_mutually_exclusive_group(required=True)
+    source.add_argument("--commit-map", type=Path, help="TSV file of fragment names and squash subjects")
+    source.add_argument("--git", action="store_true", help="read each fragment's introducing squash commit from Git")
+    fragments.set_defaults(handler=_link)
+
+
+def _link(args: argparse.Namespace) -> None:
+    commit_subjects = (
+        dict(line.split("\t", 1) for line in args.commit_map.read_text(encoding="utf-8").splitlines())
+        if args.commit_map is not None
+        else commit_subjects_from_git(args.directory)
+    )
+    add_pull_request_links(args.directory, args.repository, commit_subjects)
+
+
+__all__ = [
+    "register",
+]

release_creator/fragments/git.py

@@ -0,0 +1,39 @@
+"""Read introducing squash subjects from Git history."""
+
+import shutil
+import subprocess  # ruff: ignore[suspicious-subprocess-import]  # Fragment provenance comes from the local Git checkout.
+lazy from pathlib import Path
+
+
+def commit_subjects_from_git(directory: Path) -> dict[str, str]:
+    """Read the commit subject that first added each named fragment.
+
+    Returns:
+        Fragment filenames mapped to their introducing subjects.
+
+    Raises:
+        FileNotFoundError: Git is not installed.
+        ValueError: Git cannot read the checkout history.
+
+    """
+    if (git := shutil.which("git")) is None:
+        msg = "Git is required to read fragment history"
+        raise FileNotFoundError(msg)
+    subjects: dict[str, str] = {}
+    for fragment in sorted(directory.glob("+*.*")):
+        result = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]  # Fixed Git command; the fragment path is a separate argument.
+            [git, "log", "-1", "--format=%s", "--diff-filter=A", "HEAD", "--", str(fragment)],
+            capture_output=True,
+            check=False,
+            text=True,
+        )
+        if result.returncode:
+            msg = result.stderr.strip() or f"could not read Git history for {fragment}"
+            raise ValueError(msg)
+        subjects[fragment.name] = result.stdout.strip()
+    return subjects
+
+
+__all__ = [
+    "commit_subjects_from_git",
+]

release_creator/fragments/links.py

@@ -0,0 +1,75 @@
+"""Associate named Towncrier fragments with merged pull requests."""
+
+from __future__ import annotations
+
+import re
+lazy from pathlib import Path
+
+
+def add_pull_request_links(directory: Path, repository: str, commit_subjects: dict[str, str]) -> None:
+    """Add pull request links to named fragments using squash commit subjects.
+
+    Raises:
+        ValueError: A fragment has no unambiguous squash commit or already names a pull request.
+
+    """
+    if not re.fullmatch(
+        r"""
+        (?P<owner>[A-Za-z0-9_.-]+)  # GitHub owner
+        /                            # Repository separator
+        (?P<name>[A-Za-z0-9_.-]+)   # GitHub repository
+        """,
+        repository,
+        re.VERBOSE,
+    ):
+        msg = f"invalid repository: {repository}"
+        raise ValueError(msg)
+    for fragment in sorted(directory.glob("+*.*")):
+        subject = commit_subjects.get(fragment.name, "")
+        if (
+            match := re.search(
+                r"""
+                \(\#                    # Squash merge PR marker
+                (?P<number>\d+)       # Pull request number
+                \)$                    # Marker ends the subject
+                """,
+                subject,
+                re.VERBOSE,
+            )
+        ) is None:
+            msg = f"no squash pull request number for {fragment}: {subject}"
+            raise ValueError(msg)
+        content = fragment.read_text(encoding="utf-8").rstrip()
+        if re.search(
+            rf"""
+            https://github\.com/       # GitHub host
+            {re.escape(repository)}    # This repository
+            /pull/                      # Pull request route
+            (?P<number>\d+)            # Existing pull request link
+            """,
+            content,
+            re.VERBOSE,
+        ):
+            msg = f"pull request already linked in {fragment}"
+            raise ValueError(msg)
+        link = f"([#{match['number']}](https://github.com/{repository}/pull/{match['number']}))"
+        content, count = re.subn(
+            r"""
+            (?P<before>,?\s+)           # Optional comma and space before author credit
+            by
+            (?P<after>\s+)             # Space after credit marker
+            (?=\[@|:user:)              # Markdown or RST author link
+            """,
+            f" {link} by ",
+            content,
+            count=1,
+            flags=re.VERBOSE,
+        )
+        if not count:
+            content = f"{content.removesuffix('.')} {link}."
+        fragment.write_text(f"{content}\n", encoding="utf-8")
+
+
+__all__ = [
+    "add_pull_request_links",
+]

release_creator/fragments/template.jinja2

@@ -0,0 +1,20 @@
+{% set release = "release-" + versiondata.version | replace(".", "-") %}
+<a name="{{ release }}"></a>
+
+## {{ versiondata.version }} ({{ versiondata.date }})
+
+{% for section, _ in sections.items() %}
+{% for category, _ in definitions.items() if category in sections[section] %}
+{% if sections[section][category] %}
+{% set name = definitions[category]["name"] %}
+<a name="{{ release }}-{{ name | lower | replace(" ", "-") }}"></a>
+
+### {{ name }}
+
+{% for text, _ in sections[section][category].items() %}
+- {{ text }}
+{% endfor %}
+
+{% endif %}
+{% endfor %}
+{% endfor %}

release_creator/notes/__init__.py

@@ -0,0 +1 @@
+"""Release note preparation and rendering."""

release_creator/notes/cli.py

@@ -0,0 +1,42 @@
+"""Keep note options beside their renderer."""
+
+import sys
+from pathlib import Path
+lazy import argparse
+
+lazy from release_creator.notes.render import ReleaseContext, render_markdown, render_rst
+
+
+def register(commands: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    """Keep note options with the note command."""
+    notes = commands.add_parser("notes", help="render notes from a tagged changelog")
+    notes.add_argument("--changelog", type=Path, required=True, help="tagged Markdown or reStructuredText changelog")
+    notes.add_argument("--tag", required=True, help="release tag to render")
+    notes.add_argument("--repository", required=True, help="GitHub owner/repository")
+    notes.add_argument("--previous", help="previous tag for the comparison link")
+    notes.add_argument("--artifact-url", help="HTTPS link to the published package or artifact")
+    notes.add_argument("--artifact-label", default="PyPI release", help="text for the artifact link")
+    notes.add_argument("--issue-role", choices=("issue", "pull"), default="issue", help="target of RST issue roles")
+    notes.add_argument("--generated-notes", type=Path, help="GitHub generated notes for New Contributors credits")
+    notes.set_defaults(handler=_render)
+
+
+def _render(args: argparse.Namespace) -> None:
+    context = ReleaseContext(
+        tag=args.tag,
+        repository=args.repository,
+        previous=args.previous,
+        artifact_url=args.artifact_url,
+        artifact_label=args.artifact_label,
+    )
+    changelog = args.changelog.read_text(encoding="utf-8")
+    generated = args.generated_notes.read_text(encoding="utf-8") if args.generated_notes is not None else None
+    if args.changelog.suffix == ".rst":
+        sys.stdout.write(render_rst(changelog, context, issue_role=args.issue_role, generated_notes=generated))
+    else:
+        sys.stdout.write(render_markdown(changelog, context, generated_notes=generated))
+
+
+__all__ = [
+    "register",
+]

release_creator/notes/render.py

@@ -0,0 +1,341 @@
+"""Render release notes from tagged changelogs."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Final
+
+lazy import mdformat
+
+_CATEGORIES: Final = {
+    "Added": "Features",
+    "Changes": "Changes",
+    "Fixed": "Bug fixes",
+    "Documentation": "Documentation",
+    "Breaking changes": "Breaking changes",
+    "Security": "Security",
+    "Performance": "Performance",
+    "Deprecated": "Deprecations",
+    "Removed": "Removals",
+    "Packaging": "Packaging",
+}
+
+
+@dataclass(frozen=True, kw_only=True)
+class ReleaseContext:
+    """Links and identity for one GitHub Release."""
+
+    tag: str
+    repository: str
+    previous: str | None = None
+    artifact_url: str | None = None
+    artifact_label: str = "PyPI release"
+
+
+def render_markdown(changelog: str, context: ReleaseContext, generated_notes: str | None = None) -> str:
+    """Render one Markdown release section for GitHub without wrapped list items.
+
+    Returns:
+        The complete GitHub Release body.
+
+
+    """
+    _validate_context(context)
+    notes = mdformat.text(_extract_body(changelog, context.tag), options={"wrap": "no"}, extensions={"gfm"}).strip()
+    return _finish(notes, context, generated_notes)
+
+
+def render_rst(
+    changelog: str, context: ReleaseContext, issue_role: str = "issue", generated_notes: str | None = None
+) -> str:
+    """Render one reStructuredText release section for GitHub.
+
+    Returns:
+        The complete GitHub Release body.
+
+    Raises:
+        ValueError: The issue role must name a GitHub issue or pull request.
+
+    """
+    _validate_context(context)
+    if issue_role not in {"issue", "pull"}:
+        msg = f"invalid issue role: {issue_role}"
+        raise ValueError(msg)
+    notes = mdformat.text(
+        _extract_rst_body(changelog, context, issue_role), options={"wrap": "no"}, extensions={"gfm"}
+    ).strip()
+    return _finish(notes, context, generated_notes)
+
+
+def _finish(notes: str, context: ReleaseContext, generated_notes: str | None) -> str:
+    if generated_notes is not None and (contributors := _new_contributors(notes, generated_notes, context.tag)):
+        notes = f"{notes}\n\n{contributors}" if notes else contributors
+    if context.artifact_url is not None:
+        link = f"[{context.artifact_label}]({context.artifact_url})"
+        notes = f"{notes}\n\n{link}" if notes else link
+    comparison = (
+        f"compare/{context.previous}...{context.tag}" if context.previous is not None else f"commits/{context.tag}"
+    )
+    if notes:
+        notes += "\n\n"
+    return f"{notes}**Full Changelog**: https://github.com/{context.repository}/{comparison}\n"
+
+
+def _new_contributors(notes: str, generated_notes: str, tag: str) -> str:
+    if (
+        section := re.search(
+            r"""
+            ^\#\#\ New\ Contributors\s*\n  # Generated contributor heading
+            (?P<entries>.*?)            # Lines until the next heading
+            (?=^\#\#\ |\Z)              # Next section or end of body
+            """,
+            generated_notes,
+            re.MULTILINE | re.DOTALL | re.VERBOSE,
+        )
+    ) is None:
+        return ""
+    credited = {
+        match["handle"]
+        for match in re.finditer(
+            r"""
+            @(?P<handle>[A-Za-z0-9-]+)  # Credited GitHub handle
+            """,
+            notes,
+            re.VERBOSE,
+        )
+    }
+    entries = [
+        f"- @{match['handle']} made their first contribution in #{match['number']}"
+        for line in section["entries"].splitlines()
+        if (
+            match := re.fullmatch(
+                r"""
+                [-*]\ @(?P<handle>[A-Za-z0-9-]+)  # Generated contributor bullet
+                \ made\ their\ first\ contribution\ in\ \#
+                (?P<number>\d+)                   # First PR number
+                """,
+                line.strip(),
+                re.VERBOSE,
+            )
+        )
+        and match["handle"] in credited
+    ]
+    if not entries:
+        return ""
+    anchor = f"release-{tag.replace('.', '-')}-new-contributors"
+    return f'<a name="{anchor}"></a>\n\n### New Contributors\n\n' + "\n".join(entries)
+
+
+def _extract_rst_body(changelog: str, context: ReleaseContext, issue_role: str) -> str:
+    lines = changelog.splitlines()
+    version = re.compile(
+        r"""
+        ^v?                             # Optional release prefix
+        (?P<tag>\d+\.\d+\.\d+)        # Numeric version
+        \ \((?P<date>[^)]+)\)$          # Parenthesized release date
+        """,
+        re.VERBOSE,
+    )
+    headings = [
+        index
+        for index, line in enumerate(lines)
+        if (match := version.fullmatch(line.strip())) and match["tag"] == context.tag.removeprefix("v")
+    ]
+    if len(headings) != 1:
+        msg = f"expected one changelog section for {context.tag}, found {len(headings)}"
+        raise ValueError(msg)
+    end = next(
+        (index for index in range(headings[0] + 1, len(lines)) if version.fullmatch(lines[index].strip())),
+        len(lines),
+    )
+    sections: dict[str, list[str]] = {}
+    category: str | None = None
+    index = headings[0] + 1
+    while index < end:
+        line = lines[index].strip()
+        if index + 1 < end and re.fullmatch(
+            r"""
+            (?P<underline>[-=~^]{3,})   # RST heading underline
+            """,
+            lines[index + 1].strip(),
+            re.VERBOSE,
+        ):
+            category = _require_category(line)
+            sections.setdefault(category, [])
+            index += 2
+            continue
+        if line.startswith("- "):
+            if category is None:
+                msg = f"release item outside a category: {line}"
+                raise ValueError(msg)
+            sections[category].append(_convert_rst(line, context.repository, issue_role))
+        elif line and line[0] not in "*=~^" and not line.startswith(".. _"):
+            if category is None or not sections[category]:
+                msg = f"unexpected release text: {line}"
+                raise ValueError(msg)
+            sections[category][-1] += f" {_convert_rst(line, context.repository, issue_role)}"
+        index += 1
+    body: list[str] = []
+    for name, entries in sections.items():
+        if entries:
+            anchor = f"release-{context.tag.replace('.', '-')}-{name.lower().replace(' ', '-')}"
+            body.extend((f'<a name="{anchor}"></a>', "", f"### {_CATEGORIES[name]}", "", *entries, ""))
+    return "\n".join(body).strip()
+
+
+def _require_category(name: str) -> str:
+    if name not in _CATEGORIES:
+        msg = f"unknown changelog category: {name}"
+        raise ValueError(msg)
+    return name
+
+
+def _convert_rst(line: str, repository: str, issue_role: str) -> str:
+    issue_target = "pull" if issue_role == "pull" else "issues"
+    line = re.sub(
+        r"""
+        :(?:pr|pull):`       # Pull request role
+        (?P<number>\d+)       # Pull request number
+        `                     # Role terminator
+        """,
+        lambda match: f"[#{match['number']}](https://github.com/{repository}/pull/{match['number']})",
+        line,
+        flags=re.VERBOSE,
+    )
+    line = re.sub(
+        r"""
+        :issue:`              # Issue role
+        (?P<number>\d+)       # Issue number
+        `                     # Role terminator
+        """,
+        lambda match: f"[#{match['number']}](https://github.com/{repository}/{issue_target}/{match['number']})",
+        line,
+        flags=re.VERBOSE,
+    )
+    line = re.sub(
+        r"""
+        :user:`               # GitHub user role
+        (?P<handle>[A-Za-z0-9-]+)  # GitHub handle
+        `                     # Role terminator
+        """,
+        lambda match: f"@{match['handle']}",
+        line,
+        flags=re.VERBOSE,
+    )
+    line = re.sub(
+        r"""
+        `@(?P<handle>[A-Za-z0-9-]+)  # Link text and GitHub handle
+        \ <https://github\.com/(?P=handle)>`_  # Matching profile URL
+        """,
+        lambda match: f"@{match['handle']}",
+        line,
+        flags=re.VERBOSE,
+    )
+    line = re.sub(
+        r"""
+        ``(?P<code>[^`]+)``   # RST inline code
+        """,
+        r"`\g<code>`",
+        line,
+        flags=re.VERBOSE,
+    )
+    line = re.sub(
+        r"""
+        :(?:[a-z]+:)?[a-z]+:`  # RST role with optional domain
+        ~?(?P<name>[^`]+)`     # Referenced name, with optional short display
+        """,
+        lambda match: f"`{match['name'].split('.')[-1]}`",
+        line,
+        flags=re.VERBOSE,
+    )
+    return line.replace(" - by ", " by ")
+
+
+def _validate_context(context: ReleaseContext) -> None:
+    if not re.fullmatch(
+        r"""
+        (?P<tag>[A-Za-z0-9][A-Za-z0-9_.-]*)  # URL-safe release tag
+        """,
+        context.tag,
+        re.VERBOSE,
+    ):
+        msg = f"invalid release tag: {context.tag}"
+        raise ValueError(msg)
+    if context.previous is not None and not re.fullmatch(
+        r"""
+        (?P<tag>[A-Za-z0-9][A-Za-z0-9_.-]*)  # URL-safe previous tag
+        """,
+        context.previous,
+        re.VERBOSE,
+    ):
+        msg = f"invalid previous tag: {context.previous}"
+        raise ValueError(msg)
+    if not re.fullmatch(
+        r"""
+        (?P<owner>[A-Za-z0-9_.-]+)  # GitHub owner
+        /                            # Repository separator
+        (?P<name>[A-Za-z0-9_.-]+)   # GitHub repository
+        """,
+        context.repository,
+        re.VERBOSE,
+    ):
+        msg = f"invalid repository: {context.repository}"
+        raise ValueError(msg)
+    if context.artifact_url is not None and not context.artifact_url.startswith("https://"):
+        msg = "artifact URL must use HTTPS"
+        raise ValueError(msg)
+
+
+def _extract_body(changelog: str, tag: str) -> str:
+    version = re.compile(
+        r"""
+        ^\#\#\                         # Markdown version heading
+        (?P<tag>[^\s(]+)               # Release tag
+        (?:\ \([^)]+\))?                # Optional release date
+        $                               # End of heading
+        """,
+        re.VERBOSE,
+    )
+    lines = changelog.splitlines()
+    headings = [index for index, line in enumerate(lines) if (match := version.fullmatch(line)) and match["tag"] == tag]
+    if len(headings) != 1:
+        msg = f"expected one changelog section for {tag}, found {len(headings)}"
+        raise ValueError(msg)
+
+    body: list[str] = []
+    version_anchor = re.compile(
+        r"""
+        ^<a\ name="release-             # Version anchor prefix
+        (?P<version>v?\d+(?:-\d+){2})  # Dotted version encoded for an anchor
+        "></a>$                         # Anchor terminator
+        """,
+        re.VERBOSE,
+    )
+    author = re.compile(
+        r"""
+        \[@(?P<handle>[A-Za-z0-9-]+)\]  # GitHub handle in link text
+        \(https://github\.com/(?P=handle)\)  # Matching profile URL
+        """,
+        re.VERBOSE,
+    )
+    for source_line in lines[headings[0] + 1 :]:
+        if version.fullmatch(source_line) or version_anchor.fullmatch(source_line):
+            break
+        line = source_line
+        if source_line.startswith("### "):
+            category = source_line[4:]
+            if category not in _CATEGORIES:
+                msg = f"unknown changelog category: {category}"
+                raise ValueError(msg)
+            line = f"### {_CATEGORIES[category]}"
+        body.append(author.sub(lambda match: f"@{match['handle']}", line))
+
+    return "\n".join(body).strip()
+
+
+__all__ = [
+    "ReleaseContext",
+    "render_markdown",
+    "render_rst",
+]

release_creator/tags/__init__.py

@@ -0,0 +1 @@
+"""Select numeric release tags."""

release_creator/tags/cli.py

@@ -0,0 +1,57 @@
+"""Keep tag selection options beside the command."""
+
+import sys
+lazy import argparse
+lazy from datetime import UTC, datetime
+lazy from pathlib import Path
+
+lazy from release_creator.tags.select import next_tag, parse_tag, previous_tag, require_newer_tag
+
+
+def register(commands: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    """Register numeric tag validation and predecessor selection."""
+    tags = commands.add_parser("tags", help="calculate, validate, or compare numeric release tags")
+    tags.add_argument("tag", nargs="?", help="major.minor.patch release tag")
+    choice = tags.add_mutually_exclusive_group()
+    choice.add_argument(
+        "--next",
+        choices=("auto", "major", "minor", "patch", "calver"),
+        help="calculate a version from pending fragments",
+    )
+    choice.add_argument("--previous", action="store_true", help="print the preceding tag from standard input")
+    choice.add_argument("--require-newer", action="store_true", help="require a tag newer than those on standard input")
+    tags.add_argument(
+        "--directory", type=Path, default=Path("changelog.d"), help="pending fragment directory for --next"
+    )
+    tags.set_defaults(handler=_select)
+
+
+def _select(args: argparse.Namespace) -> None:
+    if args.next is not None:
+        if args.tag is not None:
+            msg = "omit the tag when calculating the next version"
+            raise ValueError(msg)
+        version = next_tag(
+            args.next,
+            sys.stdin.read().splitlines(),
+            [path.name for path in args.directory.glob("*.*.md")],
+            datetime.now(UTC).date(),
+        )
+        sys.stdout.write(f"{version}\n")
+        return
+    if args.tag is None:
+        msg = "provide a tag or --next"
+        raise ValueError(msg)
+    parse_tag(args.tag)
+    if not args.previous and not args.require_newer:
+        return
+    tags = sys.stdin.read().splitlines()
+    if args.require_newer:
+        require_newer_tag(args.tag, tags)
+    elif (previous := previous_tag(args.tag, tags)) is not None:
+        sys.stdout.write(f"{previous}\n")
+
+
+__all__ = [
+    "register",
+]

release_creator/tags/select.py

@@ -0,0 +1,119 @@
+"""Validate numeric tags and find their predecessors."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from datetime import date
+
+
+def next_tag(bump: str, tags: list[str], fragments: list[str], release_date: date) -> str:
+    """Choose a release version from existing tags and pending fragments.
+
+    Returns:
+        The next major.minor.patch or year.month.patch version.
+
+    Raises:
+        ValueError: The bump is unknown, no fragments exist, or the result is not newer.
+
+    """
+    if not fragments:
+        msg = "no changelog fragments to release"
+        raise ValueError(msg)
+    versions: list[tuple[int, int, int]] = []
+    for tag in tags:
+        try:
+            versions.append(parse_tag(tag))
+        except ValueError:
+            continue
+    current = max(versions, default=(0, 0, 0))
+    if bump == "auto":
+        bump = (
+            "major"
+            if any(fragment.endswith(".breaking.md") for fragment in fragments)
+            else "minor"
+            if any(fragment.endswith(".feature.md") for fragment in fragments)
+            else "patch"
+        )
+    match bump:
+        case "major":
+            version = (current[0] + 1, 0, 0)
+        case "minor":
+            version = (current[0], current[1] + 1, 0)
+        case "patch":
+            version = (current[0], current[1], current[2] + 1)
+        case "calver":
+            year_month = release_date.year, release_date.month
+            version = (*year_month, current[2] + 1 if current[:2] == year_month else 0)
+        case _:
+            msg = f"unknown version bump: {bump}"
+            raise ValueError(msg)
+    if version <= current:
+        msg = f"calculated version must be newer than {'.'.join(map(str, current))}"
+        raise ValueError(msg)
+    return ".".join(map(str, version))
+
+
+def parse_tag(tag: str) -> tuple[int, int, int]:
+    """Parse a major.minor.patch release tag.
+
+    Returns:
+        The numeric major, minor, and patch components.
+
+    Raises:
+        ValueError: The tag is not a numeric release version.
+
+    """
+    match tag.split("."):
+        case [major, minor, patch] if all(part.isascii() and part.isdecimal() for part in (major, minor, patch)):
+            return int(major), int(minor), int(patch)
+        case _:
+            msg = f"expected a major.minor.patch version: {tag}"
+            raise ValueError(msg)
+
+
+def previous_tag(tag: str, tags: list[str]) -> str | None:
+    """Select the greatest numeric release tag before ``tag``.
+
+    Returns:
+        The preceding tag, or ``None`` when this is the first release.
+
+    """
+    target = parse_tag(tag)
+    candidates: list[tuple[tuple[int, int, int], str]] = []
+    for candidate in tags:
+        try:
+            version = parse_tag(candidate)
+        except ValueError:
+            continue
+        if version < target:
+            candidates.append((version, candidate))
+    return max(candidates, default=((), ""))[1] or None
+
+
+def require_newer_tag(tag: str, tags: list[str]) -> None:
+    """Require ``tag`` to follow every existing numeric release tag.
+
+    Raises:
+        ValueError: A matching or newer release tag already exists.
+
+    """
+    target = parse_tag(tag)
+    versions: list[tuple[int, int, int]] = []
+    for candidate in tags:
+        try:
+            versions.append(parse_tag(candidate))
+        except ValueError:
+            continue
+    if versions and target <= max(versions):
+        msg = f"{tag} must be newer than the latest release tag"
+        raise ValueError(msg)
+
+
+__all__ = [
+    "next_tag",
+    "parse_tag",
+    "previous_tag",
+    "require_newer_tag",
+]

release_creator-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: release-creator
+Version: 0.1.0
+Summary: Release preparation tools for changelogs and GitHub
+Project-URL: Documentation, https://release-creator.readthedocs.io/
+Project-URL: Source, https://github.com/tox-dev/release-creator
+Project-URL: Tracker, https://github.com/tox-dev/release-creator/issues
+Author-email: Bernát Gábor <gaborjbernat@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: GitHub releases,changelog,release automation,release notes,towncrier
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Typing :: Typed
+Requires-Python: >=3.15
+Requires-Dist: mdformat-gfm<2,>=1
+Requires-Dist: mdformat<2,>=1
+Description-Content-Type: text/markdown
+
+# release-creator
+
+![release-creator logo](https://raw.githubusercontent.com/tox-dev/release-creator/main/docs/_static/logo-128.png)
+
+[![PyPI](https://img.shields.io/pypi/v/release-creator?style=flat-square)](https://pypi.org/project/release-creator/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/release-creator.svg)](https://pypi.org/project/release-creator/)
+[![check](https://github.com/tox-dev/release-creator/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/release-creator/actions/workflows/check.yaml)
+
+Release preparation tools for Python projects. The `notes` command renders a tagged changelog section for a GitHub
+Release. Other release tasks can use separate commands.
+
+The [documentation](https://release-creator.readthedocs.io/) has a tutorial, how-to guides, a generated command
+reference, and an explanation of the changelog format.
+
+## Render GitHub Release notes
+
+Run the current release from PyPI:
+
+```bash
+uvx --from 'release-creator' release-creator notes \
+  --changelog docs/changelog.md \
+  --tag 1.2.3 \
+  --repository tox-dev/example \
+  --previous 1.2.2 \
+  --artifact-url https://pypi.org/project/example/1.2.3/ > release-notes.md
+```
+
+For automation, replace `release-creator` after `--from` with a tested `release-creator==VERSION`. The command reads the
+tagged section, maps `Added` to `Features` and `Fixed` to `Bug fixes`, changes linked author handles to GitHub mentions,
+and leaves bullets unwrapped. It keeps stable category anchors, omits empty categories when they are absent from the
+source, and adds artifact and comparison links. Use `--artifact-label` for an ecosystem other than PyPI; omit
+`--artifact-url` when there is no external artifact.
+
+The command also accepts a `.rst` changelog with the same category names. For projects whose `:issue:` role points at
+PRs, pass `--issue-role pull`:
+
+```bash
+uvx --from 'release-creator' release-creator notes \
+  --changelog docs/changelog.rst \
+  --tag 1.2.3 \
+  --repository tox-dev/example \
+  --previous 1.2.2 \
+  --issue-role pull \
+  --artifact-url https://pypi.org/project/example/1.2.3/ > release-notes.md
+```
+
+The changelog is the source of truth. The command does not infer changes from commits or generate an author list. Add
+verified human credits to changelog entries before release; omit bot credits. The GitHub Release may add a
+`New Contributors` section by passing `--generated-notes` with the body from GitHub's generate-notes API. Only handles
+credited in the changelog are kept; the generated-notes banner and other generated sections are discarded.
+
+Named Towncrier fragments need no issue or PR number. Before Towncrier builds the changelog, run
+`release-creator fragments --repository owner/repo --git`. The command reads each fragment's introducing squash commit,
+adds its PR link, and fails if the subject does not end in `(#number)`. For a checkout without Git history, pass a
+tab-separated subject map with `--commit-map commits.tsv` instead.
+
+The `tags` command calculates a version from pending fragments, validates numeric tags, and selects the preceding tag
+for GitHub comparisons:
+
+```bash
+git tag --list | uvx --from 'release-creator' release-creator tags --next auto
+git tag --list | uvx --from 'release-creator' release-creator tags 1.2.3 --require-newer
+git tag --list | uvx --from 'release-creator' release-creator tags 1.2.3 --previous
+```
+
+## Development and releases
+
+See [contributing](https://github.com/tox-dev/release-creator/blob/main/CONTRIBUTING.md) for the fragment format and release process. The package uses the same `notes`
+command for its own GitHub Releases. Run `tox -e 3.15,type,pkg_meta,docs` and `prek run --all-files` before a PR.

release_creator-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+release_creator/__init__.py,sha256=s0siT-8PQHxn08gsUQha1Xp6xa5fCp9O3_Yy--i6amo,45
+release_creator/__main__.py,sha256=JDDX8heZr8tpT9if1lgXHUcDQQNTcsnrOdYKvoE3b_I,116
+release_creator/cli.py,sha256=L3X62d7rTqY9eTlObuGuBU-1ntA35LgknZnhvj0Albg,1050
+release_creator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+release_creator/fragments/__init__.py,sha256=DE2jxQF71lvRCWMLTkYG2qaE-z2Gn_QNkO9usStKT6c,55
+release_creator/fragments/cli.py,sha256=A3qVjEzcnMHAbwEbTE6i_L5q2O-uzpRNvSY3Ecy8Rvg,1424
+release_creator/fragments/git.py,sha256=Gwha7SihfAsy54ahJsIJwvIRBfjLDNmCu5HxMuNtKEs,1406
+release_creator/fragments/links.py,sha256=E_c6CTsUHxv348f4CU42Ubt5qORTPIkEJ1dEJOkjpfg,2596
+release_creator/fragments/template.jinja2,sha256=cxYtpokGJ6w9f_vgW-tEEK649jZeBEFAfIAt9Z9vzFM,568
+release_creator/notes/__init__.py,sha256=sLz-XO9tCXqr0wu1xcdjyN5aDtaYeajMSChQukN8_ME,46
+release_creator/notes/cli.py,sha256=i7dxMx73KZtLQf8H7-BBmdXua5_YjTKqukIB0ARzTis,1966
+release_creator/notes/render.py,sha256=yeyDvImms0FwqDH4ZwZ7iZsv55KPIsCfL6NJfoZNskU,11464
+release_creator/tags/__init__.py,sha256=H5Hrex281tq_T0ZnlZcq955jMDddBMhiBPBxyeQioK0,35
+release_creator/tags/cli.py,sha256=-5BalQKXmE8871v4bbO5uCSX__YG5zRKAExkQFtTdR0,2131
+release_creator/tags/select.py,sha256=2b6dC8sdiDPZ2n2rxqRJJyJCznA136Tt6UKnjS0i3kE,3630
+release_creator-0.1.0.dist-info/METADATA,sha256=vEboXr-l1u9hIAkqHTGnZbqBjnEHAqSPHU29YmttMQQ,4912
+release_creator-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+release_creator-0.1.0.dist-info/entry_points.txt,sha256=RP9cxwFYasRlvAa-xbO62lmLXlygMlGVbaNGE3lmHTY,61
+release_creator-0.1.0.dist-info/licenses/LICENSE,sha256=kOJeH68qSq6o2V7o5_VziwUqGswMnFgGgQH5Mahr1Yg,1023
+release_creator-0.1.0.dist-info/RECORD,,

release_creator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

release_creator-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+release-creator = release_creator.cli:main

release_creator-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,18 @@
+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.