Build deterministic python wheels to distribute CLI tools (third party or your own with python and make them easily usable using python code.
- 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
)
- Python 3.8+ for host running wheel build
- For target host every 3.x should work
# with CLI dependencies
pip install binary_wheel_builder[cli]
# as SDK
pip install binary_wheel_builder
pipx install binary_wheel_builder[cli]
- 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
- Build your wheel for all platforms
binary-wheel-builder --wheel-spec my-cli-wheel.yaml
- Upload your wheel files using twine:
twine upload -r pypi dist/*
- 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.
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/*
python -m my_cli
my-cli
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"])
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.
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.
- Python 3.8+
- Poetry
poetry run pytest integration_tests/
poetry run pytest binary_wheel_builder/
poetry install
- Using platform native package management
- curl'ing dependencies