easybind 0.2.3__tar.gz → 0.2.5__tar.gz

{easybind-0.2.3 → easybind-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easybind
-Version: 0.2.3
+Version: 0.2.5
 Summary: Self-registering nanobind helpers (import as easybind)
 Keywords: easybind,nanobind,bindings,pymergetic
 Author-Email: PymergeticOS Maintainers <raudzus@pymergetic.com>
@@ -83,6 +83,52 @@ easybind_fetch_magic_enum()   # if you include easybind headers that need magic_
 
 When developing **inside** this repository, `easybind_add_extension(...)` is defined in the top-level `CMakeLists.txt` (not shipped in the wheel).
 
+## Bumping `{distribution}~=…` pins (downstream projects)
+
+Use **`easybind.devtools`** or the **`easybind-pin-pyproject`** CLI to rewrite every compatible-release line **`{name}~=X.Y.Z`** in a **`pyproject.toml`** for any PyPI **distribution** name **`name`** (not only **easybind**). Examples:
+
+- **cppdantic** pinning **easybind** in several tables.
+- A future project pinning **cppdantic** the same way: pass **`--distribution cppdantic`**.
+
+**CLI** (defaults: **`distribution=easybind`**, version = latest on PyPI for that distribution; run from the tree that contains **`pyproject.toml`**):
+
+```bash
+easybind-pin-pyproject --dry-run
+easybind-pin-pyproject
+easybind-pin-pyproject --installed
+easybind-pin-pyproject --version 0.2.3
+easybind-pin-pyproject --distribution cppdantic
+easybind-pin-pyproject --pyproject /path/to/pyproject.toml
+```
+
+**Other devtools CLIs** (after **`pip install`** / **`uv pip install -e .`**, or run **`scripts/…`** shims from a git checkout):
+
+```bash
+easybind-release-tag --dry-run    # next v* tag + git push (easybind repo)
+easybind-wait-pypi                # poll PyPI until pins resolve (downstream CI)
+```
+
+**Library:**
+
+```python
+from easybind.devtools import (
+    bump_compatible_pins_in_file,
+    fetch_pypi_version,
+)
+
+# Pin all easybind~= lines to latest PyPI easybind
+ver = fetch_pypi_version("easybind")
+bump_compatible_pins_in_file("pyproject.toml", "easybind", ver)
+
+# Pin all cppdantic~= lines to latest PyPI cppdantic (e.g. downstream of cppdantic)
+ver = fetch_pypi_version("cppdantic")
+bump_compatible_pins_in_file("pyproject.toml", "cppdantic", ver)
+```
+
+Shorthands **`bump_easybind_compatible_pins`** / **`bump_easybind_compatible_pins_in_file`** remain for **`distribution=\"easybind\"`** only.
+
+**CI (downstream):** **`easybind-wait-pypi`** (or **`scripts/wait_pypi_release.py`**) wraps **`wait_pypi_for_compatible_pin`** in **`easybind.devtools`** — poll PyPI until the pinned version exists. From a checkout without install, set **`PYTHONPATH`** to this repo’s **`src`** or use the shim script.
+
 ## Core idea
 - Each namespace/module defines a `ModuleNode` and a bind callback.
 - The module entry point calls `apply_init` to run the callback and recurse.

{easybind-0.2.3 → easybind-0.2.5}/README.md

@@ -54,6 +54,52 @@ easybind_fetch_magic_enum()   # if you include easybind headers that need magic_
 
 When developing **inside** this repository, `easybind_add_extension(...)` is defined in the top-level `CMakeLists.txt` (not shipped in the wheel).
 
+## Bumping `{distribution}~=…` pins (downstream projects)
+
+Use **`easybind.devtools`** or the **`easybind-pin-pyproject`** CLI to rewrite every compatible-release line **`{name}~=X.Y.Z`** in a **`pyproject.toml`** for any PyPI **distribution** name **`name`** (not only **easybind**). Examples:
+
+- **cppdantic** pinning **easybind** in several tables.
+- A future project pinning **cppdantic** the same way: pass **`--distribution cppdantic`**.
+
+**CLI** (defaults: **`distribution=easybind`**, version = latest on PyPI for that distribution; run from the tree that contains **`pyproject.toml`**):
+
+```bash
+easybind-pin-pyproject --dry-run
+easybind-pin-pyproject
+easybind-pin-pyproject --installed
+easybind-pin-pyproject --version 0.2.3
+easybind-pin-pyproject --distribution cppdantic
+easybind-pin-pyproject --pyproject /path/to/pyproject.toml
+```
+
+**Other devtools CLIs** (after **`pip install`** / **`uv pip install -e .`**, or run **`scripts/…`** shims from a git checkout):
+
+```bash
+easybind-release-tag --dry-run    # next v* tag + git push (easybind repo)
+easybind-wait-pypi                # poll PyPI until pins resolve (downstream CI)
+```
+
+**Library:**
+
+```python
+from easybind.devtools import (
+    bump_compatible_pins_in_file,
+    fetch_pypi_version,
+)
+
+# Pin all easybind~= lines to latest PyPI easybind
+ver = fetch_pypi_version("easybind")
+bump_compatible_pins_in_file("pyproject.toml", "easybind", ver)
+
+# Pin all cppdantic~= lines to latest PyPI cppdantic (e.g. downstream of cppdantic)
+ver = fetch_pypi_version("cppdantic")
+bump_compatible_pins_in_file("pyproject.toml", "cppdantic", ver)
+```
+
+Shorthands **`bump_easybind_compatible_pins`** / **`bump_easybind_compatible_pins_in_file`** remain for **`distribution=\"easybind\"`** only.
+
+**CI (downstream):** **`easybind-wait-pypi`** (or **`scripts/wait_pypi_release.py`**) wraps **`wait_pypi_for_compatible_pin`** in **`easybind.devtools`** — poll PyPI until the pinned version exists. From a checkout without install, set **`PYTHONPATH`** to this repo’s **`src`** or use the shim script.
+
 ## Core idea
 - Each namespace/module defines a `ModuleNode` and a bind callback.
 - The module entry point calls `apply_init` to run the callback and recurse.

{easybind-0.2.3 → easybind-0.2.5}/RELEASING.md

@@ -20,10 +20,27 @@ twine upload dist/*    # or TestPyPI: twine upload --repository testpypi dist/*
 
 Configure credentials with **API token** (`~/.pypirc` or environment variables) or use **trusted publishing** (OIDC) from GitHub Actions.
 
+## Helper: next semver tag + push
+
+`scripts/release_tag.py` picks the latest **`vMAJOR.MINOR.PATCH`** tag, bumps **patch** by default (or **`--minor`** / **`--major`**), then **`fetch` / `checkout` / `pull`** (unless **`--no-pull`**), creates an **annotated** tag, and **`push`**es branch + tag (unless **`--no-push`** or **`--dry-run`**).
+
+```bash
+./scripts/release_tag.py --dry-run
+./scripts/release_tag.py
+./scripts/release_tag.py --minor
+./scripts/release_tag.py --major
+```
+
+Run from the **easybind** repo root. Requires a **clean** working tree.
+
+**Tag ≠ PyPI success:** the tag appears on GitHub immediately; the **Publish** workflow can still fail (build, auditwheel, twine). Fix the branch, then tag again or re-run the workflow — PyPI may not have that version until CI goes green.
+
 ## CI upload
 
 Pushing a tag matching `v*` triggers `.github/workflows/publish.yml`, which builds and uploads to PyPI.
 
+**Downstream:** projects that pin **easybind** can use **`scripts/wait_pypi_release.py`** in their own CI (see docstring): it waits until the pinned release exists on PyPI before building — useful when the consumer tag is pushed immediately after the easybind tag.
+
 Create a **repository secret** `PYPI_API_TOKEN` with a PyPI API token scoped to this project (or switch the workflow to [trusted publishing](https://docs.pypi.org/trusted-publishers/)).
 
 ## Platforms

{easybind-0.2.3 → easybind-0.2.5}/pyproject.toml

@@ -32,6 +32,16 @@ Homepage = "https://github.com/pymergetic/easybind"
 Repository = "https://github.com/pymergetic/easybind"
 Issues = "https://github.com/pymergetic/easybind/issues"
 
+# Scripts under scripts/ add src to sys.path at runtime; pyright/pylance need this too.
+# See also pyrightconfig.json in this directory (nearest config for files under external/easybind/).
+[tool.pyright]
+extraPaths = ["src"]
+
+[project.scripts]
+easybind-pin-pyproject = "easybind.devtools.pin_pyproject:main"
+easybind-release-tag = "easybind.devtools.release_tag:main"
+easybind-wait-pypi = "easybind.devtools.wait_pypi:main"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0.0",

easybind-0.2.5/pyrightconfig.json

@@ -0,0 +1,4 @@
+{
+  "extraPaths": ["src"],
+  "include": ["src", "scripts"]
+}

easybind-0.2.5/scripts/release_tag.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Shim: run from a git checkout without installing (adds ``src`` to ``sys.path``)."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_SRC = Path(__file__).resolve().parents[1] / "src"
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+
+from easybind.devtools.release_tag import main  # noqa: E402
+
+if __name__ == "__main__":
+    raise SystemExit(main())

easybind-0.2.5/scripts/wait_pypi_release.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Shim: run from a git checkout without installing (adds ``src`` to ``sys.path``)."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_SRC = Path(__file__).resolve().parents[1] / "src"
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+
+from easybind.devtools.wait_pypi import main  # noqa: E402
+
+if __name__ == "__main__":
+    raise SystemExit(main())

easybind-0.2.5/src/easybind/devtools/__init__.py

@@ -0,0 +1,37 @@
+"""Developer helpers (PyPI version lookup, bumping ``{dist}~=…`` pins in ``pyproject.toml``)."""
+
+from easybind.devtools.pin_pyproject import (
+    bump_compatible_pins,
+    bump_compatible_pins_in_file,
+    bump_easybind_compatible_pins,
+    bump_easybind_compatible_pins_in_file,
+    compatible_pin_versions,
+    fetch_pypi_version,
+    installed_distribution_version,
+    pypi_release_exists,
+    single_compatible_pin_version,
+    wait_pypi_for_compatible_pin,
+)
+from easybind.devtools.release_helpers import (
+    ensure_clean_worktree,
+    latest_v_tag,
+    next_v_tag,
+    tag_push_commands,
+)
+
+__all__ = [
+    "bump_compatible_pins",
+    "bump_compatible_pins_in_file",
+    "bump_easybind_compatible_pins",
+    "bump_easybind_compatible_pins_in_file",
+    "compatible_pin_versions",
+    "ensure_clean_worktree",
+    "fetch_pypi_version",
+    "installed_distribution_version",
+    "latest_v_tag",
+    "next_v_tag",
+    "pypi_release_exists",
+    "single_compatible_pin_version",
+    "tag_push_commands",
+    "wait_pypi_for_compatible_pin",
+]

easybind-0.2.5/src/easybind/devtools/pin_pyproject.py

@@ -0,0 +1,251 @@
+"""Bump ``{distribution}~=…`` compatible-release pins in a ``pyproject.toml`` string or file."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import time
+from pathlib import Path
+from urllib.error import HTTPError
+from urllib.request import urlopen
+
+# PEP 440 version suitable for ``~=`` RHS in typical pyproject pins (numeric release).
+_VERSION_RE = re.compile(r"^[0-9]+(?:\.[0-9]+)*$")
+
+# Reject pathological / mistaken distribution strings (full re.escape covers the rest).
+_DIST_OK = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._-]*$")
+
+
+def _pin_pattern(distribution: str) -> re.Pattern[str]:
+    if not _DIST_OK.match(distribution):
+        raise ValueError(
+            f"invalid distribution name for pin replacement: {distribution!r} "
+            "(expected a PyPI-style name, e.g. easybind, cppdantic, scikit-build-core)"
+        )
+    return re.compile(rf"({re.escape(distribution)}~=)([0-9]+(?:\.[0-9]+)*)")
+
+
+def fetch_pypi_version(package: str = "easybind", *, timeout_s: float = 30.0) -> str:
+    """Return ``info.version`` from ``https://pypi.org/pypi/{package}/json``."""
+    url = f"https://pypi.org/pypi/{package}/json"
+    with urlopen(url, timeout=timeout_s) as r:
+        data = json.load(r)
+    return str(data["info"]["version"])
+
+
+def pypi_release_exists(package: str, version: str, *, timeout_s: float = 15.0) -> bool:
+    """Return True if ``https://pypi.org/pypi/{package}/{version}/json`` exists (release uploaded)."""
+    url = f"https://pypi.org/pypi/{package}/{version}/json"
+    try:
+        with urlopen(url, timeout=timeout_s) as r:
+            return getattr(r, "status", 200) == 200
+    except HTTPError as e:
+        if e.code == 404:
+            return False
+        raise
+
+
+def compatible_pin_versions(pyproject_toml: str, distribution: str) -> list[str]:
+    """Return every version string from ``{distribution}~=VERSION`` pins (order preserved)."""
+    pat = _pin_pattern(distribution)
+    return [m.group(2) for m in pat.finditer(pyproject_toml)]
+
+
+def single_compatible_pin_version(
+    pyproject_toml: str,
+    distribution: str,
+    *,
+    empty_pins_suffix: str = "",
+) -> str:
+    """Return the version string if all ``{distribution}~=…`` pins agree; else raise ``ValueError``."""
+    vers = compatible_pin_versions(pyproject_toml, distribution)
+    if not vers:
+        raise ValueError(
+            f"no `{distribution}~=...` pins in pyproject.toml{empty_pins_suffix}"
+        )
+    uniq = set(vers)
+    if len(uniq) != 1:
+        raise ValueError(
+            f"{distribution}~= pins disagree: {sorted(uniq)!r}; fix pyproject.toml first"
+        )
+    return vers[0]
+
+
+def wait_pypi_for_compatible_pin(
+    pyproject_toml: str,
+    distribution: str,
+    *,
+    timeout_s: float = 1800.0,
+    interval_s: float = 30.0,
+    verbose: bool = False,
+) -> tuple[str, int]:
+    """Poll PyPI until ``pypi_release_exists(distribution, version)`` for the pin.
+
+    Uses ``single_compatible_pin_version`` on *pyproject_toml*. Returns
+    ``(resolved_version, attempt_count)``. Raises ``TimeoutError`` if the release
+    never appears within *timeout_s*. With *verbose*, log progress to stdout.
+    """
+    version = single_compatible_pin_version(pyproject_toml, distribution)
+    if verbose:
+        print(
+            f"waiting for {distribution}=={version} on PyPI "
+            f"(timeout {timeout_s:.0f}s, interval {interval_s:.0f}s)...",
+            flush=True,
+        )
+    deadline = time.monotonic() + timeout_s
+    attempt = 0
+    while True:
+        attempt += 1
+        if pypi_release_exists(distribution, version):
+            return version, attempt
+        if time.monotonic() >= deadline:
+            raise TimeoutError(
+                f"timed out waiting for {distribution}=={version} on PyPI "
+                f"after {timeout_s}s ({attempt} attempts)"
+            )
+        if verbose:
+            remaining = int(max(0, deadline - time.monotonic()))
+            print(
+                f"attempt {attempt}: not yet (retry in {interval_s:.0f}s, ~{remaining}s left)...",
+                flush=True,
+            )
+        time.sleep(interval_s)
+
+
+def installed_distribution_version(package: str = "easybind") -> str:
+    """Return ``importlib.metadata.version(package)`` for the active environment."""
+    from importlib.metadata import version
+
+    return version(package)
+
+
+def bump_compatible_pins(pyproject_toml: str, distribution: str, version: str) -> tuple[str, int]:
+    """Replace each ``{distribution}~=X.Y.Z`` with ``{distribution}~={version}``.
+
+    Returns ``(new_text, replacement_count)``.
+    """
+    if not _VERSION_RE.match(version):
+        raise ValueError(f"invalid PEP 440 version for pin: {version!r}")
+
+    pat = _pin_pattern(distribution)
+
+    def repl(m: re.Match[str]) -> str:
+        return f"{m.group(1)}{version}"
+
+    new_text, n = pat.subn(repl, pyproject_toml)
+    return new_text, n
+
+
+def bump_compatible_pins_in_file(
+    pyproject: Path | str,
+    distribution: str,
+    version: str,
+    *,
+    dry_run: bool = False,
+) -> int:
+    """Read ``pyproject.toml``, apply :func:`bump_compatible_pins`, write back unless ``dry_run``.
+
+    Returns the number of replacements. Raises ``ValueError`` if no matching pin exists.
+    """
+    path = Path(pyproject)
+    text = path.read_text(encoding="utf-8")
+    new_text, n = bump_compatible_pins(text, distribution, version)
+    if n == 0:
+        raise ValueError(f"no `{distribution}~=...` pin found in {path}")
+    if new_text == text:
+        return n
+    if not dry_run:
+        path.write_text(new_text, encoding="utf-8")
+    return n
+
+
+def bump_easybind_compatible_pins(pyproject_toml: str, version: str) -> tuple[str, int]:
+    """Same as :func:`bump_compatible_pins` with ``distribution=\"easybind\"``."""
+    return bump_compatible_pins(pyproject_toml, "easybind", version)
+
+
+def bump_easybind_compatible_pins_in_file(
+    pyproject: Path | str,
+    version: str,
+    *,
+    dry_run: bool = False,
+) -> int:
+    """Same as :func:`bump_compatible_pins_in_file` with ``distribution=\"easybind\"``."""
+    return bump_compatible_pins_in_file(pyproject, "easybind", version, dry_run=dry_run)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI: ``easybind-pin-pyproject`` (see ``--help``)."""
+    ap = argparse.ArgumentParser(
+        description=(
+            "Set every {distribution}~= pin in pyproject.toml "
+            "(default distribution: easybind; default version: latest on PyPI)."
+        )
+    )
+    ap.add_argument(
+        "--distribution",
+        "-d",
+        default="easybind",
+        metavar="NAME",
+        help="PyPI distribution name to match in pins (default: easybind), e.g. cppdantic, easybind",
+    )
+    ap.add_argument(
+        "--pyproject",
+        type=Path,
+        default=None,
+        help="path to pyproject.toml (default: ./pyproject.toml under cwd)",
+    )
+    ap.add_argument(
+        "--version",
+        metavar="X.Y.Z",
+        default=None,
+        help="pin to this version (default: PyPI latest for --distribution, unless --installed)",
+    )
+    ap.add_argument(
+        "--installed",
+        action="store_true",
+        help="use the version of --distribution installed in the current environment",
+    )
+    ap.add_argument("--dry-run", action="store_true", help="do not write the file")
+    ns = ap.parse_args(argv)
+
+    if ns.version and ns.installed:
+        print("error: use only one of --version or --installed", file=sys.stderr)
+        return 2
+
+    pyproject = ns.pyproject if ns.pyproject is not None else Path.cwd() / "pyproject.toml"
+    if not pyproject.is_file():
+        print(f"error: {pyproject} not found", file=sys.stderr)
+        return 2
+
+    dist = ns.distribution.strip()
+    if not dist:
+        print("error: empty --distribution", file=sys.stderr)
+        return 2
+
+    if ns.installed:
+        ver = installed_distribution_version(dist)
+    elif ns.version:
+        ver = ns.version.strip()
+    else:
+        ver = fetch_pypi_version(dist)
+
+    if not _VERSION_RE.match(ver):
+        print(f"error: bad version string: {ver!r}", file=sys.stderr)
+        return 2
+
+    try:
+        n = bump_compatible_pins_in_file(pyproject, dist, ver, dry_run=ns.dry_run)
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    action = "would update" if ns.dry_run else "updated"
+    print(f"{action} {n} {dist}~= pin(s) to ~={ver} in {pyproject}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

easybind-0.2.5/src/easybind/devtools/release_helpers.py

@@ -0,0 +1,92 @@
+"""Plan the next ``vMAJOR.MINOR.PATCH`` tag and ``git fetch`` / ``tag`` / ``push`` commands."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+_TAG_RE = re.compile(r"^v(\d+)\.(\d+)\.(\d+)$")
+
+
+def _run(cmd: list[str], *, cwd: Path, check: bool = True) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(cmd, cwd=cwd, check=check, text=True, capture_output=True)
+
+
+def latest_v_tag(repo: Path) -> str | None:
+    """Newest ``v*`` semver tag by version tuple."""
+    p = _run(["git", "tag", "-l", "v*"], cwd=repo, check=False)
+    if p.returncode != 0:
+        return None
+    tags: list[str] = []
+    for line in p.stdout.splitlines():
+        line = line.strip()
+        if line and _TAG_RE.match(line):
+            tags.append(line)
+    if not tags:
+        return None
+    return max(tags, key=lambda t: _parse_semver(t))
+
+
+def _parse_semver(tag: str) -> tuple[int, int, int]:
+    m = _TAG_RE.fullmatch(tag.strip())
+    if not m:
+        raise ValueError(f"not a vMAJOR.MINOR.PATCH tag: {tag!r}")
+    return int(m.group(1)), int(m.group(2)), int(m.group(3))
+
+
+def _bump(major: int, minor: int, patch: int, *, level: str) -> tuple[int, int, int]:
+    if level == "major":
+        return major + 1, 0, 0
+    if level == "minor":
+        return major, minor + 1, 0
+    return major, minor, patch + 1
+
+
+def _format_tag(t: tuple[int, int, int]) -> str:
+    return f"v{t[0]}.{t[1]}.{t[2]}"
+
+
+def next_v_tag(repo: Path, *, level: str) -> tuple[str | None, str]:
+    """Return ``(latest_tag_or_none, new_tag)`` for the given bump *level*."""
+    latest = latest_v_tag(repo)
+    if latest is None:
+        ma, mi, pa = 0, 0, 0
+    else:
+        ma, mi, pa = _parse_semver(latest)
+    new_tag = _format_tag(_bump(ma, mi, pa, level=level))
+    return latest, new_tag
+
+
+def tag_push_commands(
+    new_tag: str,
+    *,
+    remote: str,
+    branch: str,
+    no_pull: bool,
+    no_push: bool,
+    tag_message: str,
+) -> list[list[str]]:
+    """Commands: optional fetch/checkout/pull, annotated tag, optional push branch + tag."""
+    cmds: list[list[str]] = []
+    if not no_pull:
+        cmds.extend(
+            [
+                ["git", "fetch", remote],
+                ["git", "checkout", branch],
+                ["git", "pull", remote, branch],
+            ]
+        )
+    cmds.append(["git", "tag", "-a", new_tag, "-m", tag_message])
+    if not no_push:
+        cmds.append(["git", "push", remote, branch])
+        cmds.append(["git", "push", remote, new_tag])
+    return cmds
+
+
+def ensure_clean_worktree(repo: Path) -> None:
+    p = _run(["git", "status", "--porcelain"], cwd=repo, check=True)
+    if p.stdout.strip():
+        raise SystemExit(
+            "working tree is not clean; commit or stash before tagging.\n" + p.stdout
+        )

easybind-0.2.5/src/easybind/devtools/release_tag.py

@@ -0,0 +1,89 @@
+"""Next semver ``v*`` tag and ``git fetch`` / ``tag`` / ``push`` (easybind repository)."""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from easybind.devtools.release_helpers import (
+    ensure_clean_worktree,
+    next_v_tag,
+    tag_push_commands,
+)
+
+
+def main(argv: list[str] | None = None, *, repo: Path | None = None) -> int:
+    """Entry point for ``easybind-release-tag`` and ``scripts/release_tag.py``.
+
+    *repo* defaults to the current working directory (run from the repository root).
+    """
+    ap = argparse.ArgumentParser(
+        description=(
+            "Create and push the next easybind release tag from the latest ``v*`` git tag.\n\n"
+            "Default: bump **patch**. Use ``--minor`` / ``--major`` for other segments.\n"
+            "If there is no ``v*`` tag yet, starts from **v0.0.0**, then bumps.\n\n"
+            "**GitHub vs PyPI:** the tag appears immediately; PyPI upload can still fail."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    g = ap.add_mutually_exclusive_group()
+    g.add_argument("--patch", action="store_const", dest="level", const="patch", help="bump patch (default)")
+    g.add_argument("--minor", action="store_const", dest="level", const="minor", help="bump minor, reset patch")
+    g.add_argument("--major", action="store_const", dest="level", const="major", help="bump major")
+    ap.set_defaults(level="patch")
+    ap.add_argument("--dry-run", action="store_true", help="print commands only; no git writes")
+    ap.add_argument("--no-pull", action="store_true", help="skip fetch/checkout/pull")
+    ap.add_argument("--no-push", action="store_true", help="tag locally only; do not push")
+    ap.add_argument("--remote", default="origin", help="git remote (default: origin)")
+    ap.add_argument("--branch", default="main", help="branch to update (default: main)")
+    ap.add_argument(
+        "--repo",
+        type=Path,
+        default=None,
+        help="git repository root (default: current working directory)",
+    )
+    ns = ap.parse_args(argv)
+
+    root = repo if repo is not None else ns.repo
+    if root is None:
+        root = Path.cwd()
+    root = root.resolve()
+    if not (root / ".git").exists() and not (root / ".git").is_file():
+        print(f"error: no git state at {root}", file=sys.stderr)
+        return 2
+
+    latest, new_tag = next_v_tag(root, level=ns.level)
+    msg = f"easybind {new_tag.removeprefix('v')}"
+    cmds = tag_push_commands(
+        new_tag,
+        remote=ns.remote,
+        branch=ns.branch,
+        no_pull=ns.no_pull,
+        no_push=ns.no_push,
+        tag_message=msg,
+    )
+
+    print(f"latest tag: {latest or '(none)'}")
+    print(f"next tag:   {new_tag}  (bump {ns.level})")
+
+    if ns.dry_run:
+        print("--- dry-run; commands not executed ---")
+        for c in cmds:
+            print("+", " ".join(c))
+        return 0
+
+    ensure_clean_worktree(root)
+    for c in cmds:
+        subprocess.run(c, cwd=root, check=True)
+
+    if ns.no_push:
+        print(f"done: created {new_tag} locally (not pushed)")
+    else:
+        print(f"done: pushed {new_tag} (remote={ns.remote}, branch={ns.branch})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

easybind-0.2.5/src/easybind/devtools/wait_pypi.py

@@ -0,0 +1,64 @@
+"""Poll PyPI until a ``{distribution}~=…`` pin is published."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from easybind.devtools.pin_pyproject import wait_pypi_for_compatible_pin
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for ``easybind-wait-pypi`` and ``scripts/wait_pypi_release.py``."""
+    ap = argparse.ArgumentParser(
+        description=(
+            "Poll PyPI until a release exists for the version pinned as "
+            "``{distribution}~=X.Y.Z`` in pyproject.toml."
+        ),
+    )
+    ap.add_argument(
+        "--pyproject",
+        type=Path,
+        default=Path("pyproject.toml"),
+        help="path to pyproject.toml (default: ./pyproject.toml)",
+    )
+    ap.add_argument(
+        "--distribution",
+        default="easybind",
+        help="distribution name in ``{name}~=…`` pins (default: easybind)",
+    )
+    ap.add_argument("--timeout", type=int, default=1800, metavar="SEC", help="max wait (default: 1800)")
+    ap.add_argument("--interval", type=int, default=30, metavar="SEC", help="seconds between checks (default: 30)")
+    ns = ap.parse_args(argv)
+
+    pp = ns.pyproject.resolve()
+    if not pp.is_file():
+        print(f"error: not a file: {pp}", file=sys.stderr)
+        return 2
+
+    text = pp.read_text(encoding="utf-8")
+    try:
+        version, attempts = wait_pypi_for_compatible_pin(
+            text,
+            ns.distribution,
+            timeout_s=float(ns.timeout),
+            interval_s=float(ns.interval),
+            verbose=True,
+        )
+    except ValueError as e:
+        raise SystemExit(str(e)) from None
+    except TimeoutError as e:
+        print(
+            f"error: {e}. "
+            "Confirm the dependency’s release workflow finished and PyPI has the artifacts.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"ok: {ns.distribution} {version} is on PyPI (attempt {attempts})", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())