bin2whl 1.0.0__py3-none-any.whl

bin2whl/__init__.py

@@ -0,0 +1,24 @@
+# ----------------------------------------------------------------------------------------
+#   __init__.py
+#   -----------
+#
+#   bin2whl package initialisation.
+#
+#   (c) 2026 WaterJuice — Unlicense; see LICENSE in the project root.
+#
+#   Authors
+#   -------
+#   bena (via Claude)
+#
+#   Version History
+#   ---------------
+#   Mar 2026 - Created
+# ----------------------------------------------------------------------------------------
+
+"""bin2whl: Build Python wheels from pre-compiled binaries."""
+
+from bin2whl.version import VERSION_STR
+
+__all__ = ["__version__"]
+
+__version__ = VERSION_STR

bin2whl/__main__.py

@@ -0,0 +1,28 @@
+# ----------------------------------------------------------------------------------------
+#   __main__.py
+#   -----------
+#
+#   Entry point for python -m bin2whl.
+#
+#   (c) 2026 WaterJuice — Unlicense; see LICENSE in the project root.
+#
+#   Authors
+#   -------
+#   bena (via Claude)
+#
+#   Version History
+#   ---------------
+#   Mar 2026 - Created
+# ----------------------------------------------------------------------------------------
+
+import sys
+
+MIN_PYTHON = (3, 12)
+if sys.version_info < MIN_PYTHON:
+    print(f"Python {MIN_PYTHON[0]}.{MIN_PYTHON[1]}+ is required.", file=sys.stderr)
+    sys.exit(1)
+
+from bin2whl.cli import main  # noqa: E402
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bin2whl/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

bin2whl/argbuilder.py

@@ -0,0 +1,172 @@
+# ----------------------------------------------------------------------------------------
+#   argbuilder.py
+#   -------------
+#
+#   Argument parser wrapper with deferred execution. Provides a thin layer over
+#   argparse for consistent CLI argument handling.
+#
+#   (c) 2026 WaterJuice — Unlicense; see LICENSE in the project root.
+#
+#   Authors
+#   -------
+#   bena (via Claude)
+#
+#   Version History
+#   ---------------
+#   Mar 2026 - Created
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import argparse
+from typing import Any
+
+# ----------------------------------------------------------------------------------------
+#   Types
+# ----------------------------------------------------------------------------------------
+
+Namespace = argparse.Namespace
+
+# ----------------------------------------------------------------------------------------
+#   Classes
+# ----------------------------------------------------------------------------------------
+
+
+class ArgsParser:
+    """
+    Thin wrapper over argparse.ArgumentParser with a simplified interface.
+    """
+
+    # ------------------------------------------------------------------------------------
+    def __init__(
+        self,
+        prog: str,
+        description: str,
+        version: str,
+    ) -> None:
+        """
+        Initialise the argument parser.
+
+        Parameters:
+            prog:        Program name.
+            description: Program description shown in help.
+            version:     Version string shown with --version.
+        """
+        self._parser = argparse.ArgumentParser(
+            prog=prog,
+            description=description,
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+        )
+        self._parser.add_argument(
+            "--version",
+            action="version",
+            version=version,
+        )
+
+    # ------------------------------------------------------------------------------------
+    def add_argument(self, *args: Any, **kwargs: Any) -> argparse.Action:
+        """
+        Add an argument to the parser. Passes through to argparse.
+
+        Parameters:
+            args:   Positional arguments for argparse.
+            kwargs: Keyword arguments for argparse.
+
+        Returns:
+            The created Action.
+        """
+        return self._parser.add_argument(*args, **kwargs)
+
+    # ------------------------------------------------------------------------------------
+    def add_argument_group(self, title: str) -> "ArgGroup":
+        """
+        Add a named argument group for organising help output.
+
+        Parameters:
+            title: Group heading shown in help.
+
+        Returns:
+            An ArgGroup wrapper.
+        """
+        group = self._parser.add_argument_group(title)
+        return ArgGroup(group)
+
+    # ------------------------------------------------------------------------------------
+    def add_mutex_group(self) -> "MutexGroup":
+        """
+        Add a mutually exclusive argument group.
+
+        Returns:
+            A MutexGroup wrapper.
+        """
+        group = self._parser.add_mutually_exclusive_group()
+        return MutexGroup(group)
+
+    # ------------------------------------------------------------------------------------
+    def parse(self, argv: list[str]) -> Namespace:
+        """
+        Parse arguments and return the namespace.
+
+        Parameters:
+            argv: List of argument strings (without program name).
+
+        Returns:
+            Parsed argument namespace.
+        """
+        return self._parser.parse_args(argv)
+
+    # ------------------------------------------------------------------------------------
+    def error(self, message: str) -> None:
+        """
+        Print an error message and exit.
+
+        Parameters:
+            message: The error message to display.
+        """
+        self._parser.error(message)
+
+
+class ArgGroup:
+    """Wrapper for a named argument group."""
+
+    # ------------------------------------------------------------------------------------
+    def __init__(self, group: argparse._ArgumentGroup) -> None:  # pyright: ignore[reportPrivateUsage]
+        self._group = group
+
+    # ------------------------------------------------------------------------------------
+    def add_argument(self, *args: Any, **kwargs: Any) -> argparse.Action:
+        """
+        Add an argument to the group. Passes through to argparse.
+
+        Parameters:
+            args:   Positional arguments for argparse.
+            kwargs: Keyword arguments for argparse.
+
+        Returns:
+            The created Action.
+        """
+        return self._group.add_argument(*args, **kwargs)
+
+
+class MutexGroup:
+    """Wrapper for a mutually exclusive argument group."""
+
+    # ------------------------------------------------------------------------------------
+    def __init__(self, group: argparse._MutuallyExclusiveGroup) -> None:  # pyright: ignore[reportPrivateUsage]
+        self._group = group
+
+    # ------------------------------------------------------------------------------------
+    def add_argument(self, *args: Any, **kwargs: Any) -> argparse.Action:
+        """
+        Add an argument to the mutex group. Passes through to argparse.
+
+        Parameters:
+            args:   Positional arguments for argparse.
+            kwargs: Keyword arguments for argparse.
+
+        Returns:
+            The created Action.
+        """
+        return self._group.add_argument(*args, **kwargs)

bin2whl/cli.py

@@ -0,0 +1,369 @@
+# ----------------------------------------------------------------------------------------
+#   cli.py
+#   ------
+#
+#   Command-line interface entry point for bin2whl. Supports building Python wheels
+#   from pre-compiled binaries, either via a wheel.json config file or CLI arguments.
+#
+#   (c) 2026 WaterJuice — Unlicense; see LICENSE in the project root.
+#
+#   Authors
+#   -------
+#   bena (via Claude)
+#
+#   Version History
+#   ---------------
+#   Mar 2026 - Created
+#   Apr 2026 - Added multi-binary support
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import sys
+import traceback
+from pathlib import Path
+from bin2whl.config import DEFAULT_OUTPUT_DIR
+from bin2whl.config import load_config
+from bin2whl.version import VERSION_STR
+from bin2whl.wheel_builder import BinarySpec
+from bin2whl.wheel_builder import build_wheel
+from .argbuilder import ArgsParser
+from .argbuilder import Namespace
+
+# ----------------------------------------------------------------------------------------
+#   Constants
+# ----------------------------------------------------------------------------------------
+
+LICENSE_TEXT = """\
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>"""
+
+EXAMPLE_CONFIG = """\
+Single binary per platform:
+
+{
+    "name": "your-tool",
+    "version": "0.1.0",
+    "description": "A CLI tool packaged for PyPI",
+    "author": "Your Name",
+    "license": "MIT",
+    "binaries": {
+        "linux_x86_64": "dist/your-tool-linux-x86_64",
+        "linux_arm64": "dist/your-tool-linux-arm64",
+        "macos_arm64": "dist/your-tool-macos-arm64",
+        "windows_amd64": "dist/your-tool-win-x86_64.exe"
+    }
+}
+
+Multiple binaries per platform:
+
+{
+    "name": "your-suite",
+    "version": "0.1.0",
+    "binaries": {
+        "linux_x86_64": [
+            {"name": "your-server", "path": "dist/server-linux-x86_64"},
+            {"name": "your-client", "path": "dist/client-linux-x86_64"}
+        ],
+        "macos_arm64": [
+            {"name": "your-server", "path": "dist/server-darwin-arm64"},
+            {"name": "your-client", "path": "dist/client-darwin-arm64"}
+        ]
+    }
+}"""
+
+PLATFORMS_TEXT = """\
+Platform aliases (short names that expand to standard wheel tags):
+
+  linux_x86_64      → manylinux_2_17_x86_64
+  linux_amd64       → manylinux_2_17_x86_64
+  linux_aarch64     → manylinux_2_17_aarch64
+  linux_arm64       → manylinux_2_17_aarch64
+  macos_x86_64      → macosx_10_9_x86_64
+  macos_amd64       → macosx_10_9_x86_64
+  macos_arm64       → macosx_11_0_arm64
+  macos_aarch64     → macosx_11_0_arm64
+  windows_amd64     → win_amd64
+  windows_x86_64    → win_amd64
+  windows_arm64     → win_arm64
+
+Any valid wheel platform tag is also accepted directly (e.g. macosx_14_0_arm64)."""
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+def parse_args(argv: list[str]) -> Namespace:
+    """Parse command-line arguments."""
+    p = ArgsParser(
+        prog="bin2whl",
+        description=(
+            f"bin2whl: {VERSION_STR}\n"
+            "(c) 2026 WaterJuice. Unlicense.\n\n"
+            "Build Python wheels from pre-compiled binaries."
+        ),
+        version=f"bin2whl: {VERSION_STR}\npython: {sys.version.split()[0]}",
+    )
+
+    p.add_argument(
+        "--license",
+        action="version",
+        version=LICENSE_TEXT,
+        help="show license and exit",
+    )
+    p.add_argument(
+        "--example-config",
+        action="version",
+        version=EXAMPLE_CONFIG,
+        help="print an example wheel.json and exit",
+    )
+    p.add_argument(
+        "--platforms",
+        action="version",
+        version=PLATFORMS_TEXT,
+        help="list supported platform tags and exit",
+    )
+
+    common_group = p.add_argument_group("common options")
+    common_group.add_argument(
+        "--version-str",
+        "-v",
+        default=None,
+        dest="pkg_version",
+        help="package version (required for single binary mode, overrides config)",
+    )
+
+    config_group = p.add_argument_group("config file mode")
+    config_group.add_argument(
+        "--config",
+        "-c",
+        default=None,
+        help="path to config file (e.g. wheel.json)",
+    )
+
+    single_group = p.add_argument_group("single binary mode")
+    single_group.add_argument(
+        "--name",
+        "-n",
+        default=None,
+        help="package name",
+    )
+    single_group.add_argument(
+        "--binary",
+        "-b",
+        default=None,
+        help="path to binary file",
+    )
+    single_group.add_argument(
+        "--platform",
+        "-p",
+        default=None,
+        help="platform tag (see --platforms)",
+    )
+    single_group.add_argument(
+        "--description",
+        "-d",
+        default="",
+        help="package description",
+    )
+    single_group.add_argument(
+        "--author",
+        "-a",
+        default="",
+        help="author name",
+    )
+    single_group.add_argument(
+        "--author-email",
+        "-e",
+        default="",
+        help="author email",
+    )
+
+    output_group = p.add_argument_group("output")
+    output_group.add_argument(
+        "--output-dir",
+        "-o",
+        default=None,
+        help="output directory for wheel files (default: wheels)",
+    )
+
+    return p.parse(argv)
+
+
+# ----------------------------------------------------------------------------------------
+def main(argv: list[str] | None = None) -> int:
+    """
+    Main entry point for the bin2whl CLI.
+
+    Parameters:
+        argv: Command line arguments (without program name). If None, uses sys.argv[1:].
+
+    Returns:
+        Exit code (0 for success, non-zero for error)
+    """
+    if argv is None:
+        argv = sys.argv[1:]
+
+    try:
+        return _main_inner(argv)
+    except KeyboardInterrupt:
+        print()
+        print("---- Manually Terminated ----")
+        print()
+        return 1
+    except SystemExit:
+        raise
+    except BaseException as e:
+        t = "-----------------------------------------------------------------------------\n"
+        t += "UNHANDLED EXCEPTION OCCURRED!!\n"
+        t += "\n"
+        t += traceback.format_exc()
+        t += "\n"
+        t += f"EXCEPTION: {type(e)} {e}\n"
+        t += "-----------------------------------------------------------------------------\n"
+        t += "\n"
+        print(t, file=sys.stderr)
+        return 1
+
+
+# ----------------------------------------------------------------------------------------
+def _main_inner(argv: list[str]) -> int:
+    """Inner main function that does the actual work."""
+    args = parse_args(argv)
+
+    # Determine mode: single binary or config file
+    single_binary_args = [args.name, args.binary, args.platform]
+    has_single_args = any(a is not None for a in single_binary_args)
+    all_single_args = (
+        all(a is not None for a in single_binary_args) and args.pkg_version is not None
+    )
+
+    if has_single_args and not all_single_args:
+        print(
+            "Error: --name, --version-str, --binary, and --platform are all required "
+            "for single binary mode.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if has_single_args:
+        return _build_single(args)
+
+    # Config file mode requires --config
+    if args.config is not None:
+        return _build_from_config(args)
+
+    # No arguments given — show help
+    parse_args(["--help"])
+    return 0
+
+
+# ----------------------------------------------------------------------------------------
+def _build_single(args: Namespace) -> int:
+    """
+    Build a single wheel from CLI arguments.
+
+    Parameters:
+        args: Parsed command-line arguments.
+
+    Returns:
+        Exit code.
+    """
+    output_dir = Path(args.output_dir) if args.output_dir else Path(DEFAULT_OUTPUT_DIR)
+
+    try:
+        wheel_path = build_wheel(
+            binary_path=Path(args.binary),
+            name=args.name,
+            version=args.pkg_version,
+            platform=args.platform,
+            output_dir=output_dir,
+            description=args.description,
+            author=args.author,
+            author_email=args.author_email,
+        )
+    except (FileNotFoundError, IsADirectoryError, ValueError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    print(f"Built: {wheel_path}")
+    return 0
+
+
+# ----------------------------------------------------------------------------------------
+def _build_from_config(args: Namespace) -> int:
+    """
+    Build wheels from a wheel.json configuration file.
+
+    Parameters:
+        args: Parsed command-line arguments.
+
+    Returns:
+        Exit code.
+    """
+    config_path = Path(args.config)
+
+    try:
+        config = load_config(config_path)
+    except (FileNotFoundError, IsADirectoryError, ValueError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    version = args.pkg_version if args.pkg_version else config.version
+    if not version:
+        print(
+            "Error: version is required. Provide it in the config file or with --version-str.",
+            file=sys.stderr,
+        )
+        return 1
+    output_dir = Path(args.output_dir) if args.output_dir else Path(config.output_dir)
+    built_count = 0
+
+    for binary_mapping in config.binaries:
+        specs = [BinarySpec(name=e.name, path=e.path) for e in binary_mapping.entries]
+        wheel_path = build_wheel(
+            name=config.name,
+            version=version,
+            platform=binary_mapping.platform,
+            output_dir=output_dir,
+            description=config.description,
+            author=config.author,
+            author_email=config.author_email,
+            license_name=config.license_name,
+            homepage=config.homepage,
+            python_requires=config.python_requires,
+            classifiers=config.classifiers,
+            readme_content=config.readme_content,
+            binaries=specs,
+        )
+        print(f"Built: {wheel_path}")
+        built_count += 1
+
+    print(f"\n{built_count} wheel(s) built in {output_dir}/")
+    return 0