easybind 0.2.3__tar.gz → 0.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easybind
-Version: 0.2.3
+Version: 0.2.4
 Summary: Self-registering nanobind helpers (import as easybind)
 Keywords: easybind,nanobind,bindings,pymergetic
 Author-Email: PymergeticOS Maintainers <raudzus@pymergetic.com>
@@ -83,6 +83,43 @@ 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
+```
+
+**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.
+
 ## 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.4}/README.md

@@ -54,6 +54,43 @@ 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
+```
+
+**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.
+
 ## 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.4}/RELEASING.md

@@ -20,6 +20,19 @@ 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.
+
 ## CI upload
 
 Pushing a tag matching `v*` triggers `.github/workflows/publish.yml`, which builds and uploads to PyPI.

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

@@ -32,6 +32,9 @@ Homepage = "https://github.com/pymergetic/easybind"
 Repository = "https://github.com/pymergetic/easybind"
 Issues = "https://github.com/pymergetic/easybind/issues"
 
+[project.scripts]
+easybind-pin-pyproject = "easybind.devtools.pin_pyproject:main"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0.0",

easybind-0.2.4/scripts/release_tag.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""Create and push the next easybind release tag from the latest ``v*`` git tag.
+
+Default: bump **patch** (0.2.3 → 0.2.4). Use ``--minor`` or ``--major`` to bump those
+segments instead (resets lower segments to 0).
+
+If there is no ``v*`` tag yet, starts from **v0.0.0** as the notional baseline, then bumps.
+
+Examples::
+
+    ./scripts/release_tag.py --dry-run
+    ./scripts/release_tag.py
+    ./scripts/release_tag.py --minor
+    ./scripts/release_tag.py --major --no-push
+
+Requires a clean ``main`` sync (fetch/checkout/pull) unless ``--no-pull``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parents[1]
+_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_version_tag(repo: Path) -> str | None:
+    """Newest ``vMAJOR.MINOR.PATCH`` tag by version tuple (no reliance on git sort)."""
+    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 _ensure_clean(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
+        )
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    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 to 0",
+    )
+    g.add_argument(
+        "--major",
+        action="store_const",
+        dest="level",
+        const="major",
+        help="bump major, reset minor and patch to 0",
+    )
+    ap.set_defaults(level="patch")
+    ap.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="print the next tag and commands only; no git writes",
+    )
+    ap.add_argument(
+        "--no-pull",
+        action="store_true",
+        help="do not fetch/checkout main/pull (still creates tag unless --dry-run)",
+    )
+    ap.add_argument(
+        "--no-push",
+        action="store_true",
+        help="create the annotated tag locally but do not push main or the tag",
+    )
+    ap.add_argument(
+        "--remote",
+        default="origin",
+        help="git remote for fetch/push (default: origin)",
+    )
+    ap.add_argument(
+        "--branch",
+        default="main",
+        help="branch to update before tagging (default: main)",
+    )
+    ns = ap.parse_args()
+
+    repo = _REPO
+    if not (repo / ".git").exists() and not (repo / ".git").is_file():
+        print(f"error: no git state at {repo}", file=sys.stderr)
+        return 2
+
+    latest = _latest_version_tag(repo)
+    if latest is None:
+        ma, mi, pa = 0, 0, 0
+    else:
+        ma, mi, pa = _parse_semver(latest)
+
+    new_ver = _bump(ma, mi, pa, level=ns.level)
+    new_tag = _format_tag(new_ver)
+
+    print(f"latest tag: {latest or '(none)'}")
+    print(f"next tag:   {new_tag}  (bump {ns.level})")
+
+    cmds: list[list[str]] = []
+    if not ns.no_pull:
+        cmds.extend(
+            [
+                ["git", "fetch", ns.remote],
+                ["git", "checkout", ns.branch],
+                ["git", "pull", ns.remote, ns.branch],
+            ]
+        )
+    cmds.append(["git", "tag", "-a", new_tag, "-m", f"easybind {new_tag.removeprefix('v')}"])
+    if not ns.no_push:
+        cmds.append(["git", "push", ns.remote, ns.branch])
+        cmds.append(["git", "push", ns.remote, new_tag])
+
+    if ns.dry_run:
+        print("--- dry-run; commands not executed ---")
+        for c in cmds:
+            print("+", " ".join(c))
+        return 0
+
+    _ensure_clean(repo)
+
+    for c in cmds:
+        subprocess.run(c, cwd=repo, 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.4/src/easybind/devtools/__init__.py

@@ -0,0 +1,19 @@
+"""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,
+    fetch_pypi_version,
+    installed_distribution_version,
+)
+
+__all__ = [
+    "bump_compatible_pins",
+    "bump_compatible_pins_in_file",
+    "bump_easybind_compatible_pins",
+    "bump_easybind_compatible_pins_in_file",
+    "fetch_pypi_version",
+    "installed_distribution_version",
+]

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

@@ -0,0 +1,170 @@
+"""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 urllib.request
+from pathlib import Path
+
+# 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 urllib.request.urlopen(url, timeout=timeout_s) as r:
+        data = json.load(r)
+    return str(data["info"]["version"])
+
+
+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())