vommit 0.1.0__py3-none-any.whl

vommit/__about__.py

@@ -0,0 +1,5 @@
+from .helpers import canonical_version
+
+assert __package__, "unknown package?"
+
+__version__ = canonical_version(__package__)

vommit/__init__.py

@@ -0,0 +1,18 @@
+from .bump import BumpRequest, BumpResult, run_bump
+from .changelog import Changelog
+from .config import Config
+from .errors import VommitError
+from .git import GitRepo
+from .helpers import canonical_version, throw
+
+__all__ = [
+    "BumpRequest",
+    "BumpResult",
+    "Changelog",
+    "Config",
+    "GitRepo",
+    "VommitError",
+    "canonical_version",
+    "run_bump",
+    "throw",
+]

vommit/auth.py

@@ -0,0 +1,268 @@
+"""
+The PyPI token: where it comes from, and whether it looks usable.
+
+vommit resolves the token itself rather than leaving it to the publish command,
+so that any publish tool works the same way. The token therefore passes through
+this process, which is why it only ever travels as a return value or an `env`
+mapping: never onto a `CommandResult`, never into a message.
+
+Three places are tried, in this order: the environment (so CI needs nothing set
+up), the keyring, and finally the person at the keyboard.
+
+Both things this module talks to are held rather than imported at the point of
+use: `TokenStore` takes its keyring the way `GitRepo` takes its runner, and the
+index probe takes the function that posts. A test hands over a stand-in; nothing
+has to reach into this module and swap its globals out.
+"""
+
+import dataclasses as dc
+import os
+import typing as t
+
+import keyring
+import keyring.errors
+import requests
+
+from .errors import VommitError
+
+SERVICE = "vommit"
+USERNAME = "pypi"
+
+TOKEN_VAR = "UV_PUBLISH_TOKEN"
+TOKEN_PREFIX = "pypi-"
+
+# where a token was found, for saying so out loud
+ENVIRONMENT = f"{TOKEN_VAR} environment variable"
+KEYRING = "keyring"
+PROMPT = "prompt"
+
+UPLOAD_URL = "https://upload.pypi.org/legacy/"
+# enough of an upload for the index to authenticate it before finding it wanting
+UPLOAD_FORM = {":action": "file_upload", "protocol_version": "1"}
+# A valid token gets through authentication and then is refused for the
+# deliberately incomplete upload form. Any other response is inconclusive.
+ACCEPTED = 400
+
+Authenticate = t.Callable[[], str]
+Notify = t.Callable[[str], None]
+
+_NO_BACKEND = (
+    "Over SSH or on a headless machine, install `vommit[ssh]` for a backend "
+    "that works through ssh-agent. Otherwise set `pypi.use_keyring = false` to "
+    f"be asked for the token instead, or set {TOKEN_VAR} in the environment."
+)
+
+
+class Keyring(t.Protocol):
+    """
+    The three calls this module makes into a keyring.
+
+    The `keyring` module itself satisfies this, and so does a dictionary with
+    three methods around it, which is what the tests use.
+
+    Positional-only, because the real module spells the first parameter
+    `service_name` and a stand-in has no reason to copy that.
+    """
+
+    def get_password(
+        self, service: str, username: str, /
+    ) -> str | None: ...  # pragma: no cover
+
+    def set_password(
+        self, service: str, username: str, password: str, /
+    ) -> None: ...  # pragma: no cover
+
+    def delete_password(
+        self, service: str, username: str, /
+    ) -> None: ...  # pragma: no cover
+
+
+class Response(t.Protocol):
+    """
+    As much of an HTTP response as the probe reads.
+    """
+
+    status_code: int
+
+
+#: Posts the probe upload. `requests.post` is the one that really does.
+Poster = t.Callable[..., Response]
+
+
+def environment_token() -> str | None:
+    """
+    A token the environment already provides; the path CI takes.
+    """
+    return os.environ.get(TOKEN_VAR) or None
+
+
+@dc.dataclass(frozen=True)
+class TokenStore:
+    """
+    The PyPI token as this machine keeps it.
+
+    Every keyring failure becomes a `VommitError` naming a way out, because the
+    common one is not a bug but a headless machine with no backend installed.
+    """
+
+    backend: Keyring = keyring
+    service: str = SERVICE
+    username: str = USERNAME
+
+    def stored(self) -> str | None:
+        """
+        The token in the keyring, or None when nothing is stored there yet.
+        """
+        try:
+            return self.backend.get_password(self.service, self.username) or None
+        except keyring.errors.KeyringError as error:
+            raise VommitError(
+                f"Could not read the keyring: {error}\n{_NO_BACKEND}"
+            ) from error
+
+    def store(self, token: str) -> None:
+        """
+        Write (or overwrite) the token, so rotating one is a matter of storing it.
+        """
+        try:
+            self.backend.set_password(self.service, self.username, token.strip())
+        except keyring.errors.KeyringError as error:
+            raise VommitError(
+                f"Could not write to the keyring: {error}\n{_NO_BACKEND}"
+            ) from error
+
+    def forget(self) -> bool:
+        """
+        Remove the stored token; False when there was nothing to remove.
+        """
+        try:
+            self.backend.delete_password(self.service, self.username)
+        except keyring.errors.PasswordDeleteError:
+            return False
+        except keyring.errors.KeyringError as error:
+            raise VommitError(
+                f"Could not clear the keyring: {error}\n{_NO_BACKEND}"
+            ) from error
+        return True
+
+    def available(self) -> tuple[str, str] | None:
+        """
+        The token a release would pick up, and where it came from.
+        """
+        if token := environment_token():
+            return ENVIRONMENT, token
+        if token := self.stored():
+            return KEYRING, token
+        return None
+
+    def require(self) -> str:
+        """
+        A token from the environment or the keyring, or a refusal naming the fix.
+
+        The half of the resolution that can run unattended; entrypoints that can
+        prompt wrap this with one that asks.
+        """
+        if found := self.available():
+            return found[1]
+        raise VommitError(
+            "No PyPI token found; run `vommit authenticate` to store one, "
+            f"or set {TOKEN_VAR} in the environment."
+        )
+
+
+def require_token() -> str:
+    """
+    The default `Authenticate`: this machine's keyring, asking nothing.
+    """
+    return TokenStore().require()
+
+
+def mask(token: str) -> str:
+    """
+    Enough of a token to recognise it by, never enough to use it.
+
+    A short value is not a real token, so showing nine characters of it would
+    give away most of whatever it is; those get the tail only.
+    """
+    tail = token[-4:]
+    return f"{token[:9]}...{tail}" if len(token) >= 20 else f"...{tail}"
+
+
+def check_format(token: str) -> str:
+    """
+    The token, stripped, if it looks like one at all.
+
+    Catches the realistic mistake, which is a half-copied clipboard rather than
+    a revoked token: only the index can tell you about the latter.
+    """
+    token = token.strip()
+    if not token:
+        raise VommitError("An empty PyPI token cannot be stored.")
+    if not token.startswith(TOKEN_PREFIX):
+        raise VommitError(
+            f"A PyPI token starts with {TOKEN_PREFIX!r}, and this one does not. "
+            "Check what you pasted, or pass --no-verify if you publish to an "
+            "index that issues a different kind of token."
+        )
+    return token
+
+
+def probe(
+    token: str,
+    url: str = UPLOAD_URL,
+    timeout: float = 10.0,
+    post: Poster = requests.post,
+) -> int | None:
+    """
+    What the index answers to these credentials, or None if it was unreachable.
+
+    The upload announces itself and then says nothing else, which is deliberate:
+    a token that works gets as far as being told the request is incomplete, one
+    that does not is turned away at the door with a 403.
+
+    The body has to be there. A POST to `/legacy/` with an empty body is
+    answered 405 before the credentials are looked at, which made an earlier
+    version of this check accept everything.
+    """
+    try:
+        response = post(
+            url,
+            auth=("__token__", token),
+            data=UPLOAD_FORM,
+            timeout=timeout,
+        )
+    except requests.RequestException:
+        return None
+    return response.status_code
+
+
+def verify_token(
+    token: str,
+    url: str = UPLOAD_URL,
+    timeout: float = 10.0,
+    notify: Notify = lambda _: None,
+    post: Poster = requests.post,
+) -> str:
+    """
+    The token, checked as far as it can be checked before a real upload.
+
+    An index that cannot be reached is not held against the token: refusing to
+    store one because the network is down would be its own kind of wrong.
+    """
+    token = check_format(token)
+    status = probe(token, url, timeout, post)
+    if status is None:
+        notify("Could not reach PyPI to check the token; taking it as given.")
+    elif status != ACCEPTED:
+        raise VommitError(
+            f"PyPI could not verify this token ({status}). Create a new one at "
+            "https://pypi.org/manage/account/token/ and try again."
+        )
+    return token
+
+
+def publish_env(token: str | None) -> dict[str, str]:
+    """
+    The environment a publish command needs, empty when there is no token.
+    """
+    return {TOKEN_VAR: token} if token else {}

vommit/bump.py

@@ -0,0 +1,285 @@
+import dataclasses as dc
+import datetime as dt
+import typing as t
+from pathlib import Path
+
+from .changelog import Changelog, ChangelogUpdate
+from .commits import VersionBump, highest_version_bump
+from .config import Config
+from .errors import VommitError
+from .git import GitRepo, resolve_author
+from .helpers import relative_path
+from .shell import Runner
+from .versioning import UvProject, is_prerelease, plan_bump
+
+Notify = t.Callable[[str], None]
+Confirm = t.Callable[["BumpResult"], bool]
+
+PYPROJECT = "pyproject.toml"
+LOCKFILE = "uv.lock"
+
+
+def always(_: t.Any) -> bool:
+    """
+    The default answer for callers that have nobody to ask.
+    """
+    return True
+
+
+def reject_flags(flags: list[str], because: str) -> None:
+    """
+    Refuse flags that contradict the mode the user asked for.
+    """
+    if flags:
+        raise VommitError(f"{because}; drop {' and '.join(flags)}.")
+
+
+@dc.dataclass(frozen=True)
+class BumpRequest:
+    level: VersionBump | None = None
+    version: str | None = None
+    prerelease: bool = False
+    noop: bool = False
+    allow_dirty: bool = False
+    undo: bool = False
+
+    def __post_init__(self) -> None:
+        if self.undo:
+            self._reject_alongside_undo()
+            return
+        if not self.version:
+            return
+        if self.level:
+            raise VommitError(
+                f"--version {self.version} sets an exact version; drop --{self.level}."
+            )
+        if self.prerelease:
+            raise VommitError(
+                f"--version {self.version} sets an exact version; "
+                "--prerelease would be ignored."
+            )
+
+    def targeting_flags(self, include_dirty: bool = True) -> list[str]:
+        """
+        The flags that aim this request at a new version.
+
+        Anything that takes the version as given instead of choosing one
+        (`--undo`, `--no-bump`) has the same set to reject, so the set is
+        written once here rather than once per caller.
+        """
+        return [
+            f"--{name}"
+            for name, given in (
+                ("major", self.level == "major"),
+                ("minor", self.level == "minor"),
+                ("patch", self.level == "patch"),
+                ("prerelease", self.prerelease),
+                ("version", bool(self.version)),
+                ("allow-dirty", include_dirty and self.allow_dirty),
+            )
+            if given
+        ]
+
+    def _reject_alongside_undo(self) -> None:
+        """
+        --undo takes back the last release; it cannot also aim at a new one.
+        """
+        reject_flags(self.targeting_flags(), "--undo goes back to the previous release")
+
+
+@dc.dataclass(frozen=True)
+class BumpResult:
+    previous: str | None
+    version: str
+    level: VersionBump | None
+    entry: str | None
+    changelog_path: Path | None
+    commit_message: str | None
+    tag: str | None
+    noop: bool
+    prerelease: bool = False
+    # declined at the confirmation step; nothing was written, same as a noop
+    cancelled: bool = False
+
+
+def select_level(
+    major: bool = False,
+    minor: bool = False,
+    patch: bool = False,
+) -> VersionBump | None:
+    """
+    Turn the mutually exclusive CLI flags into one level (None = derive it).
+    """
+    chosen = [
+        level
+        for level, picked in (("major", major), ("minor", minor), ("patch", patch))
+        if picked
+    ]
+    if len(chosen) > 1:
+        raise VommitError(
+            f"Pick one bump level, not {' and '.join(f'--{level}' for level in chosen)}."
+        )
+    return t.cast(VersionBump | None, chosen[0] if chosen else None)
+
+
+def run_bump(
+    config: Config,
+    runner: Runner,
+    root: Path,
+    request: BumpRequest,
+    notify: Notify = lambda _: None,
+    today: dt.date | None = None,
+    confirm: Confirm = always,
+) -> BumpResult | None:
+    """
+    Bump the version, update the changelog, commit and tag.
+
+    Returns None when the commits since the last release do not warrant a bump,
+    and a `cancelled` result when `confirm` says no. Nothing is written until
+    every step that can fail has been checked, so a missing placeholder or a
+    wrong branch leaves the project untouched.
+    """
+    git = config.active_git
+    changelog_settings = config.active_changelog
+
+    repo = GitRepo(runner=runner, root=root)
+    project = UvProject(runner=runner, root=root)
+
+    if git:
+        branch = repo.ensure_branch(git, notify)
+        repo.ensure_up_to_date(git, branch, notify)
+
+    # reading history is how the bump level is found at all, so it happens even
+    # when git integration (branch checks, committing, tagging) is switched off.
+    # only a changelog that lists prereleases has a reason to stop at one: it
+    # has already reported those commits, so repeating them would duplicate.
+    aggregating = not (changelog_settings and changelog_settings.include_prereleases)
+    tag_glob = config.git.tag_glob if config.git else None
+    stable_tag = repo.last_stable_tag(tag_glob, config.tag_version)
+    baseline = config.tag_version(stable_tag)
+
+    # aggregating means the window that feeds the changelog also decides the
+    # level, so a prerelease series that has gone quiet can still be released.
+    since = stable_tag if aggregating else repo.last_tag(tag_glob)
+    commit_messages = repo.commit_messages_since(since)
+
+    level = request.level or highest_version_bump(
+        config.resolve_version_bump_from_commit(message) for message in commit_messages
+    )
+    if not request.version and level is None:
+        return None
+
+    previous = project.current_version()
+    plan = (
+        [request.version]
+        if request.version
+        else plan_bump(
+            current=previous,
+            level=t.cast(VersionBump, level),
+            baseline=baseline,
+            prerelease_token=config.prerelease_token if request.prerelease else None,
+        )
+    )
+    next_version = project.preview(plan)
+    prerelease = is_prerelease(next_version)
+
+    changelog = (
+        Changelog(settings=changelog_settings, root=root)
+        if changelog_settings
+        else None
+    )
+    update: ChangelogUpdate | None = None
+    if changelog_settings and prerelease and not changelog_settings.include_prereleases:
+        notify(
+            f"{next_version} is a prerelease; its changes stay unlisted until "
+            "the next release."
+        )
+    elif changelog:
+        update = changelog.plan(
+            next_version, config.commit_entries(commit_messages), today
+        )
+
+    touched = [PYPROJECT]
+    if update:
+        touched.append(relative_path(update.path, root))
+
+    tag = git.format_tag(next_version) if git else None
+    commit_message = git.format_commit(next_version) if git else None
+    # guarded by the commit, like the tag check below: `commit_format = ""` is a
+    # supported bump that stages without committing, and refusing it over an
+    # author that is never passed to git would block it for no gain.
+    author = resolve_author(git.commit_author) if git and commit_message else None
+
+    if git:
+        if not request.allow_dirty:
+            _refuse_dirty(repo, touched)
+        if tag:
+            # checked here rather than at tagging time: finding out afterwards
+            # would leave a release commit that never gets a tag.
+            repo.ensure_tag_available(tag)
+
+    result = BumpResult(
+        previous=previous,
+        version=next_version,
+        level=level,
+        entry=update.entry if update else None,
+        changelog_path=update.path if update else None,
+        commit_message=commit_message,
+        tag=tag,
+        noop=request.noop,
+        prerelease=prerelease,
+    )
+    if request.noop:
+        return result
+    if not confirm(result):
+        return dc.replace(result, noop=True, cancelled=True)
+
+    lockfile_ignored = bool(git and repo.ignores(LOCKFILE))
+    applied = project.apply(plan, frozen=lockfile_ignored)
+    if applied != next_version:
+        raise VommitError(
+            f"`uv version` produced {applied}, but {next_version} was planned; "
+            "the project changed underneath us."
+        )
+
+    if update:
+        update.apply()
+
+    if git:
+        if project.lockfile.exists() and not lockfile_ignored:
+            touched.append(LOCKFILE)
+        try:
+            repo.add(touched)
+        except VommitError as error:
+            raise VommitError(
+                f"{error}\nNothing has been pushed, so `vommit bump --undo` can still "
+                f"take {next_version} back."
+            ) from error
+        if commit_message:
+            _commit(repo, commit_message, next_version, author=author)
+        if tag:
+            repo.tag(tag)
+
+    return result
+
+
+def _commit(
+    repo: GitRepo, message: str, version: str, author: str | None = None
+) -> None:
+    try:
+        repo.commit(message, author=author)
+    except VommitError as error:
+        # the version is already written by now; say where that leaves things
+        raise VommitError(
+            f"{error}\nThe changes for {version} are staged but not committed, "
+            "and no tag was created."
+        ) from error
+
+
+def _refuse_dirty(repo: GitRepo, paths: list[str]) -> None:
+    dirty = repo.dirty_paths(paths)
+    if dirty:
+        raise VommitError(
+            f"Uncommitted changes in {', '.join(dirty)}; "
+            "commit or stash them first, or pass --allow-dirty."
+        )