binary_wheel_builder 3.6.0

Bundle CLI applications or other binary data as wheel to use them in code or as standalone binary

binary-wheel-builder

Build deterministic python wheels to distribute CLI tools (third party or your own with python and make them easily usable using python code.

Features

• deterministic wheel file output
• Use with Python Code or as CLI
• Prebuilt data sources for your binaries
• Ready to release and ship your binaries
• Wrapper for cli calls inside Python
• Exposes wheel as module entrypoint (python -m your_cli) and adds to path (your-cli)

Requirements

• Python 3.8+ for host running wheel build
• For target host every 3.x should work

Installation

... with pip

# with CLI dependencies
pip install binary_wheel_builder[cli]

# as SDK
pip install binary_wheel_builder

... with pipx

pipx install binary_wheel_builder[cli]

Usage

Build with CLI

1. Create your config file e. g. my-cli-wheel.yaml:

   package: my_cli
   executable: my-cli-bin
   name: my-cli
   version: 0.0.1
   summary: My CLI provides nice and clean functionality on the terminal
   description: !FileContent README.md
   license: MIT
   requires_python: ">=3.8"
   classifier:
      - "License :: OSI Approved :: MIT License"
      # Check https://pypi.org/classifiers/ for all available
   project_urls:
      # Set project urls as you like
      "Homepage": "https://github.com/my-org/my-cli"
      "Source Code": "https://github.com/my-org/my-cli,git"
      "Bug Tracker": "https://github.com/my-org/my-cli/issues"
   source: !WheelSource
     # Fetch binary from GitHub releases
     implementation: binary_wheel_builder.api.wheel_sources.GithubReleaseBinarySource
     project_slug: my-org/my-cli
     version: "0.0.1"
     tag_prefix: "" # e.g. set to v when your tag is vX.Y.Z
    # Path of the binary relative to your package root
     binary_path: my_cli/my-cli-bin
     # Download file name based on platform the wheel is built for
     asset_name_mapping:
       !WellknownPlatform MAC_SILICON: "mycli-darwin-arm64"
       !WellknownPlatform MAC_INTEL: "mycli-darwin-amd64"
       !WellknownPlatform LINUX_GENERIC_x86_64: "my-cli-linux-amd64"
       !WellKnownPlatform LINUX_GENERIC_aarch64: "my-cli-linux-arm"
     # Supported platforms by the wheel
     platforms:
       - !WellknownPlatform MAC_INTEL
       - !WellknownPlatform MAC_SILICON
       - !WellknownPlatform LINUX_GENERIC_x86_64
       - !WellKnownPlatform LINUX_GENERIC_aarch64
   

2. Build your wheel for all platforms

   binary-wheel-builder --wheel-spec my-cli-wheel.yaml
   

3. Upload your wheel files using twine:

   twine upload -r pypi dist/*
   

4. Enjoy and consume your CLI as a package

If you want to have auto complete and validation right in the IDE, you can use the wheel.schema.json JSON Schema.

VSCode Guide | IntelliJ IDEA IDEs Guide

Build with Python code

If you prefer to write Python Code you use almost the same structure:

from pathlib import Path

from binary_wheel_builder.api import build_wheel, Wheel, well_known_platforms
from binary_wheel_builder.api.wheel_sources import GithubReleaseBinarySource


# Add a custom github release source
class MyCliGithubReleaseSource(GithubReleaseBinarySource):
    def __init__(self, version: str):
        super().__init__(
            "my-org/my-repo",
            version,
            {
                well_known_platforms.MAC_SILICON: "mycli-darwin-arm64",
                well_known_platforms.MAC_INTEL: "mycli-darwin-amd64",
                well_known_platforms.LINUX_GENERIC_x86_64: "my-cli-linux-amd64",
                well_known_platforms.LINUX_GENERIC_aarch64: "my-cli-linux-arm",
            },
            "my_cli/my-cli-bin"
        )


dist_folder = Path("dist")

print("Built wheels:")
for result in build_wheel(
        Wheel(
            package="my_cli",
            executable="my-cli-bin",
            name="my-cli",
            version="0.0.1",
            summary='My CLI provides nice and clean functionality on the terminal',
            license='MIT',
            requires_python=">=3.9",
            classifier=[
                'License :: OSI Approved :: MIT License',
                # Check https://pypi.org/classifiers/ for all available
            ],
            project_urls={
                'Homepage': 'https://github.com/my-org/my-cli',
                'Source Code': 'https://github.com/my-org/my-cli,git',
                'Bug Tracker': 'https://github.com/my-org/my-cli/issues',
            },
            source=MyCliGithubReleaseSource("0.0.1"),
            platforms=[
                well_known_platforms.MAC_INTEL,
                well_known_platforms.MAC_SILICON,
                well_known_platforms.LINUX_GENERIC_x86_64,
                well_known_platforms.LINUX_GENERIC_aarch64
            ]
        ),
        dist_folder
):
    print(f" > {result.file_path} [{result.checksum}]")

Afterwards upload with twine: Upload your wheel files using twine:

twine upload -r pypi dist/*

Using the generated wheel

With python module call

python -m my_cli

Using wrapper in path

my-cli

Using in Python code using exec utils

import subprocess

from my_cli import exec

# Run process and prefix stdout and stderr
exec.exec_with_templated_output(["--help"])

# Create a subprocess, specifying how to handle stdout, stderr
exec.create_subprocess(["--help"], stdout=subprocess.PIPE, stderr=subprocess.PIPE)

# Perform command with suppressed output and return finished proces instance,
# on that one can also check if the call was successfully
exec.exec_silently(["--version"])

Motivation

Sometimes managing CLI dependencies for tooling etc. can become quite a pain.

Also sometimes there are just so many options to distribute binaries, but Python is preinstalled on almost any nix machine. This opens great possibilities with using pip(x) to install dependencies or even reuse standalone CLI applications as regular dependency in your code.

Documentation

• Library documentation

Contributing

I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's:

• Reporting a bug
• Discussing the current state of the configuration
• Submitting a fix
• Proposing new features
• Becoming a maintainer

To get started please read the Contribution Guidelines.

Development

Requirements

• Python 3.8+
• Poetry

Test

Integration Tests

poetry run pytest integration_tests/

Unit Tests

poetry run pytest binary_wheel_builder/

Build

poetry install

Alternatives

• Using platform native package management
• curl'ing dependencies