tag-sync 0.1.0__tar.gz

tag_sync-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: tag-sync
+Version: 0.1.0
+Summary: A CLI tool for syncing git tags with project versions
+Author: Tucker Beck
+Author-email: Tucker Beck <tucker.beck@gmail.com>
+License-File: LICENSE.md
+Requires-Dist: bidict>=0.23.1
+Requires-Dist: gitpython>=3.1.46
+Requires-Dist: loguru>=0.7
+Requires-Dist: py-buzz>=4.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: snick>=2.0
+Requires-Dist: typerdrive>=0.9
+Requires-Python: >=3.13
+Project-URL: homepage, https://github.com/dusktreader/tag-sync
+Project-URL: source, https://github.com/dusktreader/tag-sync
+Project-URL: changelog, https://github.com/dusktreader/tag-sync/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+[![Latest Version](https://img.shields.io/pypi/v/tag-sync?label=pypi-version&logo=python&style=plastic)](https://pypi.org/project/tag-sync/)
+[![Python Versions](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fdusktreader%2Ftag-sync%2Fmain%2Fpyproject.toml&style=plastic&logo=python&label=python-versions)](https://www.python.org/)
+[![Documentation Status](https://github.com/dusktreader/tag-sync/actions/workflows/docs.yml/badge.svg)](https://dusktreader.github.io/tag-sync/)
+
+# tag-sync
+
+![tag-sync icon](docs/source/images/tag-sync-icon.png)
+
+_A CLI tool for syncing git tags with project versions._
+
+
+## Super-quick Start
+
+Requires: Python 3.13+
+
+Install through pip:
+
+```bash
+pip install tag-sync
+```
+
+Publish a tag for the current package version:
+
+```bash
+tag-sync publish
+```
+
+
+## Documentation
+
+The complete documentation can be found at the
+[tag-sync home page](https://dusktreader.github.io/tag-sync).

tag_sync-0.1.0/README.md

@@ -0,0 +1,32 @@
+[![Latest Version](https://img.shields.io/pypi/v/tag-sync?label=pypi-version&logo=python&style=plastic)](https://pypi.org/project/tag-sync/)
+[![Python Versions](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fdusktreader%2Ftag-sync%2Fmain%2Fpyproject.toml&style=plastic&logo=python&label=python-versions)](https://www.python.org/)
+[![Documentation Status](https://github.com/dusktreader/tag-sync/actions/workflows/docs.yml/badge.svg)](https://dusktreader.github.io/tag-sync/)
+
+# tag-sync
+
+![tag-sync icon](docs/source/images/tag-sync-icon.png)
+
+_A CLI tool for syncing git tags with project versions._
+
+
+## Super-quick Start
+
+Requires: Python 3.13+
+
+Install through pip:
+
+```bash
+pip install tag-sync
+```
+
+Publish a tag for the current package version:
+
+```bash
+tag-sync publish
+```
+
+
+## Documentation
+
+The complete documentation can be found at the
+[tag-sync home page](https://dusktreader.github.io/tag-sync).

tag_sync-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "tag-sync"
+version = "0.1.0"
+description = "A CLI tool for syncing git tags with project versions"
+authors = [
+    {name = "Tucker Beck", email = "tucker.beck@gmail.com"},
+]
+readme = "README.md"
+license-files = ["LICENSE.md"]
+requires-python = ">=3.13"
+dependencies = [
+    "bidict>=0.23.1",
+    "gitpython>=3.1.46",
+    "loguru>=0.7",
+    "py-buzz>=4.0",
+    "pydantic>=2.12.5",
+    "snick>=2.0",
+    "typerdrive>=0.9",
+]
+
+[project.urls]
+homepage = "https://github.com/dusktreader/tag-sync"
+source = "https://github.com/dusktreader/tag-sync"
+changelog = "https://github.com/dusktreader/tag-sync/blob/main/CHANGELOG.md"
+
+[project.scripts]
+tag-sync = "tag_sync.cli.main:cli"
+
+
+[dependency-groups]
+dev = [
+    "debugpy~=1.8",
+    "ipython~=8.18",
+    "zensical>=0.0.31",
+    "pyclean~=3.1",
+    "pygments~=2.19",
+    "pytest~=8.3",
+    "pytest-bdd>=7.0.0",
+    "pytest-cov~=6.0",
+    "pytest-mock~=3.14",
+    "pytest-pretty~=1.2",
+    "pytest-random-order~=1.1",
+    "ruff~=0.11",
+    "ty~=0.0",
+    "typos~=1.31",
+]
+
+
+[tool.uv]
+package = true
+
+
+[tool.pytest.ini_options]
+addopts = [
+    "--random-order",
+    "--cov=src/tag_sync",
+    "--cov-report=term-missing",
+    "--cov-fail-under=85",
+    "--cov-report=xml:.coverage.xml",
+    "--junitxml=.junit.xml",
+    "--override-ini=junit_family=legacy",
+]
+testpaths = ["tests"]
+pythonpath = ["src"]
+python_files = ["test_*.py", "*_steps.py"]
+markers = [
+    "integration: Integration tests that exercise real git repos and packager files",
+    "unit: Fast unit tests with all external dependencies mocked",
+]
+
+
+[tool.ruff]
+line-length = 120
+src = ["src/tag_sync", "tests"]
+
+
+[tool.ruff.format]
+docstring-code-format = true
+
+
+[tool.typos.default]
+extend-ignore-identifiers-re = []
+
+
+[build-system]
+requires = ["uv-build>=0.1.0"]
+build-backend = "uv_build"

tag_sync-0.1.0/src/tag_sync/__init__.py

@@ -0,0 +1,5 @@
+from tag_sync.version import get_version
+
+__version__ = get_version()
+
+__all__ = ["__version__"]

tag_sync-0.1.0/src/tag_sync/cli/__init__.py

@@ -0,0 +1,3 @@
+from tag_sync.cli.main import cli
+
+__all__ = ["cli"]

tag_sync-0.1.0/src/tag_sync/cli/main.py

@@ -0,0 +1,167 @@
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from loguru import logger
+from typerdrive import add_logs_subcommand, handle_errors, terminal_message
+
+from tag_sync.exceptions import TagAlreadyPublishedError
+from tag_sync.packager import PACKAGERS, resolve_packager
+from tag_sync.pattern import Pattern
+from tag_sync.tagger import Tagger
+
+cli = typer.Typer(
+    name="tag-sync",
+    help="Sync git tags with project versions.",
+    no_args_is_help=True,
+)
+
+add_logs_subcommand(cli)
+
+DryRunOption = Annotated[bool, typer.Option("--dry-run", help="Show what would happen without making any changes")]
+PackagerOption = Annotated[
+    str | None,
+    typer.Option(
+        "--packager",
+        help=f"Packager to use for reading the project version. One of: {', '.join(PACKAGERS)}. Auto-detected when omitted.",
+    ),
+]
+DirectoryOption = Annotated[
+    Path,
+    typer.Option(
+        "--directory",
+        "-d",
+        help="Directory containing the project. Defaults to the current working directory.",
+    ),
+]
+
+
+@cli.command()
+@handle_errors("verify failed")
+def verify(
+    packager_name: PackagerOption = None,
+    directory: DirectoryOption = Path("."),
+) -> None:
+    """
+    Verify whether the current package version has a published git tag.
+
+    Uses the tagger's default pattern to convert the package's SemVer to a
+    canonical tag string, then checks whether that tag exists on origin.
+
+    The packager is auto-detected from the project directory when --packager
+    is not supplied.
+    """
+    packager = resolve_packager(packager_name, directory)
+    package_version = packager.package_version
+    default_pattern = Pattern(Tagger.DEFAULT_PATTERN_TEMPLATE)
+    tagger = Tagger(default_pattern.format(package_version))
+    version_string = tagger.pattern.format(tagger.version)
+    if tagger.is_published():
+        suffix = "is already published."
+    else:
+        suffix = "has not been published yet."
+    terminal_message(f"Version [cyan]{version_string}[/cyan] {suffix}", subject="verify")
+
+
+@cli.command()
+@handle_errors("check failed")
+def check(
+    tag_version_string: Annotated[
+        str, typer.Argument(help="Tag version string to validate against the package version")
+    ],
+    packager_name: PackagerOption = None,
+    directory: DirectoryOption = Path("."),
+) -> None:
+    """
+    Validate that a tag version matches the current package version.
+
+    The packager is auto-detected from the project directory when --packager
+    is not supplied.
+    """
+    logger.debug(f"Checking tag version: {tag_version_string}")
+    packager = resolve_packager(packager_name, directory)
+    tagger = Tagger(tag_version_string)
+    tagger.check(packager)
+    version_string = tagger.pattern.format(tagger.version)
+    terminal_message(f"Version [cyan]{version_string}[/cyan] matches the package version.", subject="check")
+
+
+@cli.command()
+@handle_errors("publish failed")
+def publish(
+    tag_version_string: Annotated[
+        str | None, typer.Argument(help="Tag version string to publish. Derived from the package version when omitted.")
+    ] = None,
+    packager_name: PackagerOption = None,
+    directory: DirectoryOption = Path("."),
+    replace: Annotated[bool, typer.Option(help="Replace existing tag if it exists")] = False,
+    dry_run: DryRunOption = False,
+) -> None:
+    """
+    Validate the project version, create a git tag, and push it to origin.
+
+    When the tag version string is supplied it is validated against the current
+    package version.  When omitted it is derived from the package version using
+    the default tag pattern, skipping the version-match check.
+
+    If the tag is already published on origin the command fails unless
+    --replace is given, in which case the existing tag is deleted locally and
+    on origin before the new one is created.
+
+    The packager is auto-detected from the project directory when --packager
+    is not supplied.
+    """
+    packager = resolve_packager(packager_name, directory)
+    explicit = tag_version_string is not None
+    if tag_version_string is None:
+        default_pattern = Pattern(Tagger.DEFAULT_PATTERN_TEMPLATE)
+        tag_version_string = default_pattern.format(packager.package_version)
+    tag: str = tag_version_string
+    tagger = Tagger(tag)
+    if explicit:
+        tagger.check(packager)
+    try:
+        tagger.require_unpublished()
+    except TagAlreadyPublishedError:
+        if not replace:
+            raise
+        if not typer.confirm(f"Tag {tag} is already on origin. Replace it?"):
+            raise typer.Abort()
+        logger.debug(f"Replacing tag: {tag}")
+        tagger.delete_local_tag(dry_run=dry_run)
+        tagger.delete_remote_tag(dry_run=dry_run)
+    logger.debug(f"Publishing tag: {tag}")
+    tagger.make_tag(dry_run=dry_run)
+    tagger.push_tag(dry_run=dry_run)
+    version_string = tagger.pattern.format(tagger.version)
+    terminal_message(
+        f"Tag [cyan]{version_string}[/cyan] published successfully.",
+        subject="publish",
+    )
+
+
+@cli.command()
+@handle_errors("nuke failed")
+def nuke(
+    tag_version_string: Annotated[str, typer.Argument(help="Tag version string to remove locally and on origin")],
+    force: Annotated[bool | None, typer.Option(help="Don't prompt to confirm deletion")] = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """
+    Remove a tag from both the local git repository and origin.
+    """
+    if force is None:
+        force = typer.confirm(
+            f"Are you sure you want to nuke tag {tag_version_string}? This will delete it locally and on origin."
+        )
+    if not force:
+        raise typer.Abort()
+    tagger = Tagger(tag_version_string)
+    logger.debug(f"Nuking tag: {tag_version_string}")
+    tagger.delete_local_tag(dry_run=dry_run)
+    tagger.delete_remote_tag(dry_run=dry_run)
+    version_string = tagger.pattern.format(tagger.version)
+    terminal_message(
+        f"Tag [cyan]{version_string}[/cyan] removed locally and from origin.",
+        subject="nuke",
+    )

tag_sync-0.1.0/src/tag_sync/constants.py

@@ -0,0 +1,7 @@
+from typing import Literal
+
+from bidict import bidict
+
+
+PRETYPE_CANONICAL = Literal["alpha", "beta", "rc", "dev"]
+type PretypeMap = bidict[str, PRETYPE_CANONICAL]

tag_sync-0.1.0/src/tag_sync/exceptions.py

@@ -0,0 +1,25 @@
+from typerdrive import TyperdriveError
+
+
+class TagSyncError(TyperdriveError):
+    """Base exception for all tag-sync errors."""
+
+
+class InvalidPatternError(TagSyncError):
+    """Raised when a Pattern regex is missing required named groups."""
+
+
+class VersionParseError(TagSyncError):
+    """Raised when a version string cannot be parsed."""
+
+
+class VersionMismatchError(TagSyncError):
+    """Raised when a tag version does not match the package version."""
+
+
+class GitError(TagSyncError):
+    """Raised when a git operation fails."""
+
+
+class TagAlreadyPublishedError(TagSyncError):
+    """Raised when a tag is already published on origin and replacement was not requested."""

tag_sync-0.1.0/src/tag_sync/packager.py

@@ -0,0 +1,123 @@
+import json
+import tomllib
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Protocol, override
+
+from tag_sync.exceptions import TagSyncError, VersionParseError
+from tag_sync.pattern import Pattern
+from tag_sync.semver import SemVer
+
+
+class Packager(ABC):
+    pattern: Pattern
+
+    def parse(self, version_string: str) -> SemVer:
+        return self.pattern.parse(version_string)
+
+    @abstractmethod
+    def extract_version_string(self) -> str: ...
+
+    def format(self, version: SemVer) -> str:
+        return self.pattern.format(version)
+
+    @property
+    def package_version(self) -> SemVer:
+        with VersionParseError.handle_errors(f"Couldn't extract package version using `{self.__class__.__name__}`"):
+            return self.parse(self.extract_version_string())
+
+
+class UvPackager(Packager):
+    def __init__(self, path: Path = Path(".")):
+        self.path = path
+        self.pattern = Pattern(
+            "<major>.<minor>.<patch><pre_type:a|b|rc|dev><pre_id>",
+            pretype_map={"a": "alpha", "b": "beta"},
+        )
+
+    @override
+    def extract_version_string(self) -> str:
+        pyproject_path = self.path / "pyproject.toml"
+        data = tomllib.loads(pyproject_path.read_text())
+        return data["project"]["version"]
+
+
+class NpmPackager(Packager):
+    def __init__(self, path: Path = Path(".")):
+        self.path = path
+        self.pattern = Pattern("<major>.<minor>.<patch>-<pre_type:alpha|beta|rc|dev>.<pre_id>")
+
+    @override
+    def extract_version_string(self) -> str:
+        package_json_path = self.path / "package.json"
+        data = json.loads(package_json_path.read_text())
+        return data["version"]
+
+
+class _PackagerFactory(Protocol):
+    def __call__(self, path: Path = ...) -> Packager: ...
+
+
+PACKAGERS: dict[str, _PackagerFactory] = {
+    "npm": NpmPackager,
+    "uv": UvPackager,
+}
+
+_MANIFEST_PACKAGER: dict[str, str] = {
+    "pyproject.toml": "uv",
+    "package.json": "npm",
+}
+
+
+def resolve_packager(packager_name: str | None, path: Path = Path(".")) -> Packager:
+    """
+    Return an instantiated `Packager` for the given directory.
+
+    When `packager_name` is `None` the packager is auto-detected from the
+    manifest files present in `path`.  When a name is provided it is looked up
+    in the `PACKAGERS` registry and instantiated with `path`.
+
+    Args:
+        packager_name: Explicit packager key (e.g. `"uv"`, `"npm"`), or `None`
+            to trigger auto-detection.
+        path: Project directory to pass to the packager.
+
+    Returns:
+        An instantiated `Packager`.
+    """
+    if packager_name is None:
+        return detect_packager(path)
+    return PACKAGERS[packager_name](path)
+
+
+def detect_packager(path: Path = Path(".")) -> Packager:
+    """
+    Auto-detect the packager from manifest files in `path`.
+
+    Looks for `pyproject.toml` (uv) and `package.json` (npm).  Raises
+    `TagSyncError` when zero or more than one manifest is found — the caller
+    should use `--packager` to be explicit in that case.
+
+    Args:
+        path: Directory to inspect.  Defaults to the current working directory.
+
+    Returns:
+        An instantiated `Packager` for the detected manifest.
+
+    Raises:
+        TagSyncError: When no manifest or multiple manifests are found.
+    """
+    found = [name for name in _MANIFEST_PACKAGER if (path / name).exists()]
+    if len(found) == 0:
+        raise TagSyncError(
+            f"No supported manifest file found in {path}. "
+            f"Expected one of: {', '.join(_MANIFEST_PACKAGER)}. "
+            "Use --packager to specify the packager explicitly."
+        )
+    if len(found) > 1:
+        raise TagSyncError(
+            f"Multiple manifest files found in {path}: {', '.join(found)}. "
+            "Use --packager to specify the packager explicitly."
+        )
+    packager_name = _MANIFEST_PACKAGER[found[0]]
+    return PACKAGERS[packager_name](path)

tag_sync-0.1.0/src/tag_sync/pattern.py

@@ -0,0 +1,118 @@
+import re
+from typing import cast
+
+from bidict import bidict
+import snick
+
+from tag_sync.constants import PRETYPE_CANONICAL, PretypeMap
+from tag_sync.exceptions import InvalidPatternError, VersionParseError
+from tag_sync.semver import SemVer
+
+
+# Parses: [prefix]<major>.<minor>.<patch>[<pre_leader>]<pre_type:t1|t2|...>[<pre_sep>]<pre_id>
+# Examples:
+#   v<major>.<minor>.<patch>-<pre_type:alpha|beta|rc|dev>.<pre_id> -> v1.2.3, v1.2.3-alpha.1, etc
+#   <major>.<minor>.<patch><pre_type:a|b|rc|dev><pre_id>           -> 1.2.3, 1.2.3a1, etc
+PATTERN_TEMPLATE = re.compile(
+    r"^(?P<prefix>.*?)"
+    r"<major>\.<minor>\.<patch>"
+    r"(?P<pre_leader>.*?)<pre_type:(?P<pre_types>[^>]+)>(?P<pre_sep>.*?)<pre_id>"
+    r"$"
+)
+
+
+class Pattern:
+    template: str
+
+    def __init__(self, template: str, pretype_map: "dict[str, PRETYPE_CANONICAL] | None" = None) -> None:
+        match = InvalidPatternError.enforce_defined(
+            PATTERN_TEMPLATE.match(template),
+            snick.dedent(
+                f"""
+                 Pattern template is not valid: {template!r}
+                 Expected format: [prefix]<major>.<minor>.<patch>[<pre_leader>]<pre_type:t1|t2|...>[<pre_sep>]<pre_id>
+                """
+            ),
+        )
+        self.template = template
+        base: PretypeMap = bidict(pretype_map) if pretype_map is not None else bidict()
+        # Ensure every canonical pre-type that isn't already a value in the
+        # supplied map gets an identity entry (raw == canonical).
+        canonical_types: tuple[PRETYPE_CANONICAL, ...] = ("alpha", "beta", "rc", "dev")
+        supplemental = {c: c for c in canonical_types if c not in base.inverse}
+        self.pretype_map: PretypeMap = bidict({**base, **supplemental})
+
+        prefix = match.group("prefix") or ""
+        pre_leader = match.group("pre_leader") or ""
+        pre_sep = match.group("pre_sep") or ""
+        self._pre_types = match.group("pre_types").split("|")
+
+        self.core_format_string = f"{prefix}{{major}}.{{minor}}.{{patch}}"
+        self.pre_format_string = f"{pre_leader}{{pre_type}}{pre_sep}{{pre_id}}"
+
+        pre_type_alt = "|".join(self._pre_types)
+        core = rf"^{prefix}(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)"
+        pre = rf"(?:{re.escape(pre_leader)}(?P<pre_type>{pre_type_alt}){re.escape(pre_sep)}(?P<pre_id>\d+))?"
+        self.regex = core + pre + r"$"
+
+    def parse(self, version_string: str) -> SemVer:
+        """
+        Parse a version string against this pattern and return a SemVer.
+
+        Raises:
+            VersionParseError: If the string does not match the pattern.
+        """
+        message: str = snick.dedent(
+            f"""
+            Invalid version string: {version_string}
+
+            Please use format {self.template}.
+
+            Examples:
+            """
+        )
+        message += "\n".join(f"- {ex}" for ex in self.examples)
+        match = VersionParseError.enforce_defined(
+            re.match(self.regex, version_string),
+            message,
+        )
+        with VersionParseError.handle_errors(f"Couldn't parse version from {version_string}"):
+            version = SemVer(
+                major=int(match.group("major")),
+                minor=int(match.group("minor")),
+                patch=int(match.group("patch")),
+            )
+            if match.group("pre_type"):
+                raw = match.group("pre_type")
+                version.pre_type = cast(PRETYPE_CANONICAL, self.pretype_map.get(raw, raw))
+                version.pre_id = int(match.group("pre_id"))
+            return version
+
+    def format(self, version: SemVer) -> str:
+        """
+        Produce a version string from the given SemVer using this Pattern.
+
+        Canonical pre_type values (e.g. 'alpha') are mapped back to their
+        pattern-native form (e.g. 'a') via the inverse of pretype_map before
+        substitution.
+        """
+        result = self.core_format_string.format(major=version.major, minor=version.minor, patch=version.patch)
+        if version.pre_type is not None and version.pre_id is not None:
+            raw_pre_type = self.pretype_map.inverse.get(version.pre_type, version.pre_type)
+            result += self.pre_format_string.format(pre_type=raw_pre_type, pre_id=version.pre_id)
+        return result
+
+    @property
+    def examples(self) -> list[str]:
+        """
+        Return four representative example version strings: two release
+        versions and two pre-release versions with fixed values.
+        """
+        pt0 = self._pre_types[0]
+        pt1 = self._pre_types[min(1, len(self._pre_types) - 1)]
+        return [
+            self.format(SemVer(major=1, minor=0, patch=0)),
+            self.format(SemVer(major=1, minor=2, patch=3)),
+            self.format(SemVer(major=2, minor=0, patch=0, pre_type=self.pretype_map[pt0], pre_id=1)),
+            self.format(SemVer(major=1, minor=2, patch=3, pre_type=self.pretype_map[pt1], pre_id=2)),
+        ]

tag_sync-0.1.0/src/tag_sync/semver.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass
+
+from tag_sync.constants import PRETYPE_CANONICAL
+
+
+@dataclass
+class SemVer:
+    major: int
+    minor: int
+    patch: int
+    pre_type: PRETYPE_CANONICAL | None = None
+    pre_id: int | None = None
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, SemVer):
+            return NotImplemented
+        return (self.major, self.minor, self.patch, self.pre_type, self.pre_id) == (
+            other.major,
+            other.minor,
+            other.patch,
+            other.pre_type,
+            other.pre_id,
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.major, self.minor, self.patch, self.pre_type, self.pre_id))

tag_sync-0.1.0/src/tag_sync/tagger.py

@@ -0,0 +1,112 @@
+import snick
+from git import Repo
+
+from tag_sync.constants import PRETYPE_CANONICAL
+from tag_sync.exceptions import GitError, TagAlreadyPublishedError, VersionMismatchError
+from tag_sync.packager import Packager
+from tag_sync.pattern import Pattern
+from tag_sync.semver import SemVer
+
+
+class Tagger:
+    pattern: Pattern
+    version: SemVer
+
+    DEFAULT_PATTERN_TEMPLATE = "v<major>.<minor>.<patch>-<pre_type:alpha|beta|rc|dev>.<pre_id>"
+
+    def __init__(
+        self,
+        version_string: str,
+        pattern_template: str | None = None,
+        pretype_map: "dict[str, PRETYPE_CANONICAL] | None" = None,
+    ):
+        self.pattern = Pattern(
+            pattern_template if pattern_template is not None else self.DEFAULT_PATTERN_TEMPLATE,
+            pretype_map=pretype_map,
+        )
+        self.version = self.parse(version_string)
+
+    def parse(self, version_string: str) -> SemVer:
+        return self.pattern.parse(version_string)
+
+    def check(self, packager: Packager) -> None:
+        """
+        Verify that the version from the packager matches this tag version.
+
+        Raises:
+            VersionMismatchError: If the versions do not match.
+        """
+        package_version = packager.package_version
+        VersionMismatchError.require_condition(
+            self.version == package_version,
+            snick.dedent(
+                f"""
+                Package version doesn't match tag version.
+
+                Tag version:     {self.pattern.format(self.version)}
+                Package version: {packager.pattern.format(package_version)}
+
+                Please update the package version.
+                """
+            ),
+        )
+
+    def is_published(self) -> bool:
+        """Check whether this tag exists on the remote."""
+        tag = self.pattern.format(self.version)
+        repo = Repo(search_parent_directories=True)
+        refs = repo.git.ls_remote("--tags", "origin", tag)
+        return bool(refs.strip())
+
+    def require_unpublished(self) -> None:
+        """
+        Raise `TagAlreadyPublishedError` if this tag is already on origin.
+
+        Raises:
+            TagAlreadyPublishedError: If the tag is already published.
+        """
+        tag = self.pattern.format(self.version)
+        TagAlreadyPublishedError.require_condition(
+            not self.is_published(),
+            f"Tag {tag} is already published on origin. Use --replace to overwrite it.",
+        )
+
+    def make_tag(self, dry_run: bool = False) -> None:
+        """Create this tag in the local git repository."""
+        tag = self.pattern.format(self.version)
+        if dry_run:
+            print(f"[dry-run] Would create tag: {tag}")
+            return
+        repo = Repo(search_parent_directories=True)
+        with GitError.handle_errors(f"Failed to create tag {tag}"):
+            repo.create_tag(tag)
+
+    def push_tag(self, dry_run: bool = False) -> None:
+        """Push this tag to the remote."""
+        tag = self.pattern.format(self.version)
+        if dry_run:
+            print(f"[dry-run] Would push tag: {tag}")
+            return
+        repo = Repo(search_parent_directories=True)
+        with GitError.handle_errors(f"Failed to push tag {tag}"):
+            repo.remotes["origin"].push(tag)
+
+    def delete_local_tag(self, dry_run: bool = False) -> None:
+        """Delete this tag from the local git repository."""
+        tag = self.pattern.format(self.version)
+        if dry_run:
+            print(f"[dry-run] Would delete local tag: {tag}")
+            return
+        repo = Repo(search_parent_directories=True)
+        with GitError.handle_errors(f"Failed to delete local tag {tag}"):
+            repo.delete_tag(repo.tag(f"refs/tags/{tag}"))
+
+    def delete_remote_tag(self, dry_run: bool = False) -> None:
+        """Delete this tag from the remote."""
+        tag = self.pattern.format(self.version)
+        if dry_run:
+            print(f"[dry-run] Would delete remote tag: {tag}")
+            return
+        repo = Repo(search_parent_directories=True)
+        with GitError.handle_errors(f"Failed to delete remote tag {tag}"):
+            repo.remotes["origin"].push(refspec=f":refs/tags/{tag}")

tag_sync-0.1.0/src/tag_sync/version.py

@@ -0,0 +1,24 @@
+import tomllib
+from importlib import metadata
+
+
+def get_version_from_metadata() -> str:
+    return metadata.version(__package__ or __name__)
+
+
+def get_version_from_pyproject() -> str:
+    with open("pyproject.toml", "rb") as file:
+        return tomllib.load(file)["project"]["version"]
+
+
+def get_version() -> str:
+    try:
+        return get_version_from_metadata()
+    except metadata.PackageNotFoundError:
+        try:
+            return get_version_from_pyproject()
+        except (FileNotFoundError, KeyError):
+            return "unknown"
+
+
+__version__ = get_version()