radlermass 0.1.0__tar.gz

radlermass-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.3
+Name: radlermass
+Version: 0.1.0
+Summary: Go binaries in Python wheels.
+Author: William Woodruff
+Author-email: William Woodruff <william@yossarian.net>
+Requires-Dist: packaging>=26.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# radlermass
+
+Go binaries in Python wheels.
+
+Inspired by [go-to-wheel](https://github.com/simonw/go-to-wheel). The wheels
+install native executables, with no Python wrapper.
+
+Requires Python 3.14+ and Go. Cgo is not supported.
+
+## Usage
+
+From a checkout:
+
+```console
+$ uv run radlermass ./mytool --version 1.2.3
+```
+
+This builds the root `main` package for Linux, macOS, and Windows (amd64 and
+arm64), writing wheels to `./dist`.
+
+Use `--package-path cmd/mytool` for a subdirectory. See `uv run radlermass --help`
+for names, target selection, metadata, and linker flags.
+
+## Python API
+
+```python
+from radlermass import build_wheels
+
+wheels = build_wheels(
+    "./mytool",
+    package_path="cmd/mytool",
+    version="1.2.3",
+    readme="# My tool\n\nA Go command.",
+)
+```
+
+`build_wheels` returns a list of absolute wheel paths. `readme` accepts Markdown
+as a `str` or a file as a `pathlib.Path`; relative paths resolve against the Go
+module.
+
+## Development
+
+```console
+$ uv sync --locked
+$ uv run ruff check .
+$ uv run ruff format --check .
+$ uv run ty check
+$ uv run pytest
+$ uv build
+```

radlermass-0.1.0/README.md

@@ -0,0 +1,50 @@
+# radlermass
+
+Go binaries in Python wheels.
+
+Inspired by [go-to-wheel](https://github.com/simonw/go-to-wheel). The wheels
+install native executables, with no Python wrapper.
+
+Requires Python 3.14+ and Go. Cgo is not supported.
+
+## Usage
+
+From a checkout:
+
+```console
+$ uv run radlermass ./mytool --version 1.2.3
+```
+
+This builds the root `main` package for Linux, macOS, and Windows (amd64 and
+arm64), writing wheels to `./dist`.
+
+Use `--package-path cmd/mytool` for a subdirectory. See `uv run radlermass --help`
+for names, target selection, metadata, and linker flags.
+
+## Python API
+
+```python
+from radlermass import build_wheels
+
+wheels = build_wheels(
+    "./mytool",
+    package_path="cmd/mytool",
+    version="1.2.3",
+    readme="# My tool\n\nA Go command.",
+)
+```
+
+`build_wheels` returns a list of absolute wheel paths. `readme` accepts Markdown
+as a `str` or a file as a `pathlib.Path`; relative paths resolve against the Go
+module.
+
+## Development
+
+```console
+$ uv sync --locked
+$ uv run ruff check .
+$ uv run ruff format --check .
+$ uv run ty check
+$ uv run pytest
+$ uv build
+```

radlermass-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "radlermass"
+version = "0.1.0"
+description = "Go binaries in Python wheels."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = ["packaging>=26.0"]
+
+[[project.authors]]
+name = "William Woodruff"
+email = "william@yossarian.net"
+
+[project.scripts]
+radlermass = "radlermass._cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.15,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "ruff",
+    "ty",
+]
+
+[tool.uv.workspace]
+members = []
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "PT",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

radlermass-0.1.0/pyproject.toml.orig

@@ -0,0 +1,35 @@
+[project]
+name = "radlermass"
+version = "0.1.0"
+description = "Go binaries in Python wheels."
+readme = "README.md"
+authors = [
+    { name = "William Woodruff", email = "william@yossarian.net" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "packaging>=26.0",
+]
+
+[project.scripts]
+radlermass = "radlermass._cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.15,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "ruff",
+    "ty",
+]
+
+[tool.uv.workspace]
+members = []
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "PT"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

radlermass-0.1.0/src/radlermass/__init__.py

@@ -0,0 +1,5 @@
+"""Package Go commands as Python wheels."""
+
+from radlermass._build import build_wheels
+
+__all__ = ["build_wheels"]

radlermass-0.1.0/src/radlermass/__main__.py

@@ -0,0 +1,3 @@
+from radlermass._cli import main
+
+raise SystemExit(main())

radlermass-0.1.0/src/radlermass/_build.py

@@ -0,0 +1,149 @@
+"""Compile a Go command and package it for each requested platform."""
+
+import re
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+from packaging.utils import canonicalize_name
+from packaging.version import Version
+
+from radlermass._go import Go
+from radlermass._metadata import Metadata, validate_command
+from radlermass._platforms import macos_tag, select_targets
+from radlermass._wheel import wheel_timestamp, write_wheel
+
+
+def _resolve_package(go_dir: str | Path, package_path: str) -> tuple[Path, str]:
+    module = Path(go_dir).resolve()
+    if not module.is_dir():
+        raise ValueError(f"Go module directory not found: {go_dir}")
+    if not (module / "go.mod").is_file():
+        raise ValueError(f"Not a Go module (no go.mod): {module}")
+
+    if not package_path or Path(package_path).is_absolute():
+        raise ValueError("Package path must be a directory relative to the Go module")
+
+    package_dir = (module / package_path).resolve()
+    if not package_dir.is_relative_to(module):
+        raise ValueError("Package path must stay inside the Go module")
+    if not package_dir.is_dir():
+        raise ValueError(f"Go package directory not found: {package_path}")
+
+    return module, "./" + package_dir.relative_to(module).as_posix()
+
+
+def _linker_flags(
+    version: Version, ldflags: str | None, set_version_var: str | None
+) -> str:
+    flags = ["-s", "-w"]
+
+    if set_version_var is not None:
+        if not re.fullmatch(r"[^\s='\"\x00]+\.[A-Za-z_][A-Za-z0-9_]*", set_version_var):
+            raise ValueError(f"Invalid Go version variable: {set_version_var!r}")
+
+        flags.append(f"-X {set_version_var}={version}")
+
+    if ldflags:
+        flags.append(ldflags)
+
+    result = " ".join(flags)
+    if "\x00" in result:
+        raise ValueError("Linker flags must not contain NUL characters")
+
+    return result
+
+
+def build_wheels(
+    go_dir: str | Path,
+    *,
+    name: str | None = None,
+    version: str = "0.1.0",
+    output_dir: str | Path = "dist",
+    entry_point: str | None = None,
+    platforms: Sequence[str] | None = None,
+    go_binary: str = "go",
+    package_path: str = ".",
+    description: str | None = None,
+    author: str | None = None,
+    author_email: str | None = None,
+    license_: str | None = None,
+    url: str | None = None,
+    readme: str | Path | None = None,
+    ldflags: str | None = None,
+    set_version_var: str | None = None,
+    build_timeout: float = 300,
+) -> list[Path]:
+    """Build wheels from ``go_dir`` and return their absolute paths.
+
+    ``package_path`` selects the main package, defaulting to the module root.
+    ``readme`` is Markdown text or a Path to a UTF-8 file. Relative README paths
+    use ``go_dir``; relative ``output_dir`` paths use the working directory.
+    ``description=None`` omits the package summary.
+
+    Raises ValueError for invalid inputs, RuntimeError for Go failures or
+    timeouts, and OSError for I/O or process errors.
+
+    Existing wheels are replaced only after all builds succeed. Each replacement
+    is atomic.
+    """
+    module, package = _resolve_package(go_dir, package_path)
+
+    if name is None:
+        name = module.name
+    canonicalize_name(name, validate=True)
+
+    command = name if entry_point is None else entry_point
+    validate_command(command)
+
+    targets = select_targets(platforms)
+
+    if isinstance(readme, Path):
+        readme = (module / readme).read_text(encoding="utf-8")
+
+    metadata = Metadata(
+        name=name,
+        version=Version(version),
+        description=description,
+        author=author,
+        author_email=author_email,
+        license=license_,
+        url=url,
+        readme=readme,
+    )
+    metadata.render()  # Validate headers before invoking Go.
+
+    flags = _linker_flags(metadata.version, ldflags, set_version_var)
+    timestamp = wheel_timestamp()
+
+    go = Go(module, executable=go_binary, timeout=build_timeout)
+
+    wheel_tags = {}
+    for target in targets:
+        tag = target.tag
+        if target.goos == "darwin":
+            tag = macos_tag(go.version, tag)
+
+        wheel_tags[target] = tag
+
+    output = Path(output_dir).resolve()
+    output.mkdir(parents=True, exist_ok=True)
+
+    # Keep staged wheels on the output filesystem so each rename is atomic.
+    with tempfile.TemporaryDirectory(prefix=".radlermass-", dir=output) as temporary:
+        staging = Path(temporary)
+        binaries = go.build(package, targets, staging, flags)
+
+        wheels = []
+        for target, tag in wheel_tags.items():
+            wheel = write_wheel(
+                binary=binaries[target.goos, target.goarch],
+                output_dir=staging,
+                metadata=metadata,
+                command=command,
+                tag=tag,
+                timestamp=timestamp,
+            )
+            wheels.append(wheel)
+
+        return [wheel.replace(output / wheel.name) for wheel in wheels]

radlermass-0.1.0/src/radlermass/_cli.py

@@ -0,0 +1,82 @@
+"""Command-line interface for radlermass."""
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from radlermass._build import build_wheels
+from radlermass._platforms import TARGETS
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="radlermass", description="Compile Go commands into Python wheels."
+    )
+
+    parser.add_argument("go_dir", help="Go module directory containing go.mod")
+
+    parser.add_argument(
+        "--name", help="Distribution name (default: module directory name)"
+    )
+    parser.add_argument(
+        "--version", default="0.1.0", help="Distribution version (PEP 440)"
+    )
+
+    parser.add_argument("--output-dir", default="dist", help="Wheel output directory")
+
+    parser.add_argument(
+        "--entry-point", help="Installed command name (default: --name)"
+    )
+
+    parser.add_argument(
+        "--package-path", default=".", help="Package directory within the module"
+    )
+
+    parser.add_argument(
+        "--platforms",
+        help=f"Comma-separated targets (default: all): {', '.join(TARGETS)}",
+    )
+
+    parser.add_argument("--go-binary", default="go", help="Go executable path or name")
+
+    parser.add_argument("--description", help="Package summary")
+    parser.add_argument("--author", help="Package author")
+    parser.add_argument("--author-email", help="Package author email")
+    parser.add_argument("--license", dest="license_", help="Package license")
+    parser.add_argument("--url", help="Project URL")
+    parser.add_argument(
+        "--readme", type=Path, help="Markdown README path, relative to the Go module"
+    )
+
+    parser.add_argument("--ldflags", help="Additional Go linker flags (after -s -w)")
+    parser.add_argument(
+        "--set-version-var", help="Go string variable to set to --version"
+    )
+
+    parser.add_argument(
+        "--build-timeout",
+        type=float,
+        default=300,
+        help="Seconds allowed per Go build (default: 300)",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.platforms is not None:
+        args.platforms = [platform.strip() for platform in args.platforms.split(",")]
+
+    try:
+        wheels = build_wheels(**vars(args))
+    except (OSError, ValueError, RuntimeError) as error:
+        print(f"radlermass: {error}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("radlermass: interrupted", file=sys.stderr)
+        return 130
+
+    print(f"Built {len(wheels)} wheel(s):")
+    for wheel in wheels:
+        print(f"  {wheel}")
+
+    return 0

radlermass-0.1.0/src/radlermass/_go.py

@@ -0,0 +1,97 @@
+"""Invoke the Go toolchain in a module directory."""
+
+import math
+import os
+import shutil
+import subprocess
+from collections.abc import Sequence
+from functools import cached_property
+from pathlib import Path
+
+from radlermass._platforms import Target
+
+
+class Go:
+    def __init__(self, module: Path, executable: str, timeout: float) -> None:
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("Build timeout must be a positive, finite number")
+
+        path = shutil.which(executable)
+        if path is None:
+            raise ValueError(f"Go executable not found: {executable!r}")
+
+        # Resolve before changing the subprocess's working directory to the module.
+        self.executable = str(Path(path).absolute())
+        self.module = module
+        self.timeout = timeout
+
+    def _run(
+        self,
+        args: list[str],
+        *,
+        label: str,
+        env: dict[str, str] | None = None,
+    ) -> str:
+        try:
+            result = subprocess.run(
+                [self.executable, *args],
+                cwd=self.module,
+                env=env,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+            )
+        except subprocess.TimeoutExpired as error:
+            raise RuntimeError(f"{label} exceeded {self.timeout:g} seconds") from error
+
+        if result.returncode:
+            detail = result.stderr.strip() or result.stdout.strip()
+            raise RuntimeError(f"{label} failed (exit {result.returncode}):\n{detail}")
+
+        return result.stdout
+
+    @cached_property
+    def version(self) -> str:
+        """Return the toolchain version selected for this module."""
+        return self._run(["env", "GOVERSION"], label="Go version query").strip()
+
+    def build(
+        self,
+        package: str,
+        targets: Sequence[Target],
+        output_dir: Path,
+        ldflags: str,
+    ) -> dict[tuple[str, str], Path]:
+        """Compile once per GOOS/GOARCH pair, sharing Linux libc variants."""
+        binaries: dict[tuple[str, str], Path] = {}
+        for target in targets:
+            key = (target.goos, target.goarch)
+            if key in binaries:
+                continue
+
+            binary = output_dir / f"{target.goos}-{target.goarch}.exe"
+            env = os.environ | {
+                "GOOS": target.goos,
+                "GOARCH": target.goarch,
+                "CGO_ENABLED": "0",
+                # Wheel tags don't encode GOAMD64/GOARM64 feature levels.
+                "GOAMD64": "v1",
+                "GOARM64": "v8.0",
+            }
+
+            self._run(
+                [
+                    "build",
+                    "-trimpath",
+                    "-buildmode=exe",
+                    f"-ldflags={ldflags}",
+                    "-o",
+                    str(binary),
+                    package,
+                ],
+                env=env,
+                label=f"Go build for {target.goos}/{target.goarch}",
+            )
+            binaries[key] = binary
+
+        return binaries

radlermass-0.1.0/src/radlermass/_metadata.py

@@ -0,0 +1,57 @@
+"""Distribution names, versions, and core metadata."""
+
+import re
+from dataclasses import dataclass
+
+from packaging.metadata import RFC822Message
+from packaging.utils import canonicalize_name
+from packaging.version import Version
+
+
+def validate_command(name: str) -> None:
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", name) or name.endswith("."):
+        raise ValueError(f"Invalid command name: {name!r}")
+
+
+@dataclass(frozen=True)
+class Metadata:
+    name: str
+    version: Version
+    description: str | None = None
+    author: str | None = None
+    author_email: str | None = None
+    license: str | None = None
+    url: str | None = None
+    readme: str | None = None
+
+    @property
+    def stem(self) -> str:
+        name = canonicalize_name(self.name, validate=True).replace("-", "_")
+        return f"{name}-{self.version}"
+
+    def render(self) -> bytes:
+        # Omit Requires-Python: the wheel installs a native executable directly.
+        headers = {
+            "Metadata-Version": "2.1",
+            "Name": self.name,
+            "Version": str(self.version),
+            "Summary": self.description,
+            "Author": self.author,
+            "Author-email": self.author_email,
+            "License": self.license,
+            "Home-page": self.url,
+            "Description-Content-Type": "text/markdown"
+            if self.readme is not None
+            else None,
+        }
+
+        message = RFC822Message()
+        for key, value in headers.items():
+            if value is not None:
+                if any(ord(char) < 32 or ord(char) == 127 for char in value):
+                    raise ValueError(f"{key} must not contain control characters")
+
+                message[key] = value
+
+        message.set_payload(self.readme or "")
+        return message.as_bytes()

radlermass-0.1.0/src/radlermass/_platforms.py

@@ -0,0 +1,74 @@
+"""Supported Go targets and wheel platform tags."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from packaging.tags import mac_platforms
+from packaging.version import InvalidVersion, Version
+
+
+@dataclass(frozen=True)
+class Target:
+    goos: str
+    goarch: str
+    tag: str
+
+
+TARGETS = {
+    "linux-amd64": Target("linux", "amd64", "manylinux_2_17_x86_64"),
+    "linux-arm64": Target("linux", "arm64", "manylinux_2_17_aarch64"),
+    "linux-amd64-musl": Target("linux", "amd64", "musllinux_1_2_x86_64"),
+    "linux-arm64-musl": Target("linux", "arm64", "musllinux_1_2_aarch64"),
+    "darwin-amd64": Target("darwin", "amd64", "x86_64"),
+    "darwin-arm64": Target("darwin", "arm64", "arm64"),
+    "windows-amd64": Target("windows", "amd64", "win_amd64"),
+    "windows-arm64": Target("windows", "arm64", "win_arm64"),
+}
+
+
+def select_targets(platforms: Sequence[str] | None) -> list[Target]:
+    """Select targets in request order, defaulting to all supported platforms."""
+    selected = list(dict.fromkeys(TARGETS if platforms is None else platforms))
+    if not selected:
+        raise ValueError("Select at least one platform")
+
+    unknown = [platform for platform in selected if platform not in TARGETS]
+    if unknown:
+        raise ValueError(f"Unknown platform(s): {', '.join(unknown)}")
+
+    return [TARGETS[platform] for platform in selected]
+
+
+# https://go.dev/wiki/MinimumRequirements and the Darwin release notes.
+# Keep releases explicit: a new Go release may raise the macOS minimum.
+MACOS_MINIMUMS = {
+    (1, 16): (10, 12),
+    (1, 17): (10, 13),
+    (1, 18): (10, 13),
+    (1, 19): (10, 13),
+    (1, 20): (10, 13),
+    (1, 21): (10, 15),
+    (1, 22): (10, 15),
+    (1, 23): (11, 0),
+    (1, 24): (11, 0),
+    (1, 25): (12, 0),
+    (1, 26): (12, 0),
+    (1, 27): (13, 0),
+}
+
+
+def macos_tag(go_version: str, arch: str) -> str:
+    """Use the Go release's macOS minimum, with a floor of 11.0 on arm64."""
+    try:
+        version = Version(go_version.removeprefix("go").split("-", 1)[0])
+        minimum = MACOS_MINIMUMS[version.major, version.minor]
+    except InvalidVersion, KeyError:
+        raise ValueError(
+            f"Unknown macOS minimum for Go version {go_version!r}; "
+            "update radlermass's Go version map"
+        ) from None
+
+    if arch == "arm64":
+        minimum = max(minimum, (11, 0))
+
+    return next(mac_platforms(version=minimum, arch=arch))

radlermass-0.1.0/src/radlermass/_wheel.py

@@ -0,0 +1,90 @@
+"""Write wheels containing native executables in the scripts install scheme."""
+
+import base64
+import csv
+import hashlib
+import io
+import os
+import stat
+import time
+import zipfile
+from pathlib import Path
+from typing import BinaryIO
+
+from packaging.tags import Tag
+
+from radlermass._metadata import Metadata
+
+
+def wheel_timestamp() -> tuple[int, int, int, int, int, int]:
+    """Return a ZIP timestamp from SOURCE_DATE_EPOCH, or 1980-01-01.
+
+    Clamp values before 1980 and reject values after 2107.
+    """
+    epoch = int(os.environ.get("SOURCE_DATE_EPOCH", "315532800"))
+    if epoch > 4354819199:  # ZIP timestamps end in 2107.
+        raise ValueError("SOURCE_DATE_EPOCH is too large for a ZIP timestamp")
+
+    return time.gmtime(max(epoch, 315532800))[:6]
+
+
+def write_wheel(
+    binary: Path,
+    output_dir: Path,
+    metadata: Metadata,
+    command: str,
+    tag: str,
+    timestamp: tuple[int, int, int, int, int, int],
+) -> Path:
+    if tag.startswith("win_") and not command.lower().endswith(".exe"):
+        command += ".exe"
+
+    stem = metadata.stem
+    dist_info = f"{stem}.dist-info"
+    wheel_tag = Tag("py3", "none", tag)
+    path = output_dir / f"{stem}-{wheel_tag}.whl"
+    rows: list[tuple[str, str, str]] = []
+
+    with zipfile.ZipFile(path, "w", compression=zipfile.ZIP_DEFLATED) as wheel:
+
+        def add(member: str, source: BinaryIO, mode: int) -> None:
+            info = zipfile.ZipInfo(member, date_time=timestamp)
+            info.create_system = 3  # Unix permissions, even when building on Windows.
+            info.external_attr = (stat.S_IFREG | mode) << 16
+            info.compress_type = zipfile.ZIP_DEFLATED
+
+            digest = hashlib.sha256()
+            size = 0
+
+            with wheel.open(info, "w", force_zip64=True) as destination:
+                while chunk := source.read(1024 * 1024):
+                    destination.write(chunk)
+                    digest.update(chunk)
+                    size += len(chunk)
+
+            encoded = (
+                base64.urlsafe_b64encode(digest.digest()).rstrip(b"=").decode("ascii")
+            )
+            rows.append((member, f"sha256={encoded}", str(size)))
+
+        with binary.open("rb") as source:
+            add(f"{stem}.data/scripts/{command}", source, 0o755)
+
+        add(f"{dist_info}/METADATA", io.BytesIO(metadata.render()), 0o644)
+
+        wheel_metadata = (
+            "Wheel-Version: 1.0\n"
+            "Generator: radlermass\n"
+            "Root-Is-Purelib: false\n"
+            f"Tag: {wheel_tag}\n"
+        )
+        add(f"{dist_info}/WHEEL", io.BytesIO(wheel_metadata.encode("ascii")), 0o644)
+
+        record = f"{dist_info}/RECORD"
+        rows.append((record, "", ""))
+
+        contents = io.StringIO(newline="")
+        csv.writer(contents, lineterminator="\n").writerows(rows)
+        add(record, io.BytesIO(contents.getvalue().encode("utf-8")), 0o644)
+
+    return path