Skip to content

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

License

Notifications You must be signed in to change notification settings

timo-reymann/python-binary-wheel-builder

Repository files navigation

binary-wheel-builder

PyPI version PyPI - Downloads LICENSE CircleCI codecov Quality Gate Status Code Smells Maintainability Rating Security Rating Renovate


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

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

About

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

Topics

Resources

License

Security policy

Stars

Watchers

Forks

Languages