forked from mirrors/kingfisher
96 lines
2.4 KiB
Markdown
96 lines
2.4 KiB
Markdown
---
|
|
title: "Python Bindings"
|
|
description: "Install and use Kingfisher from Python via PyPI wheels. Build and publish wheels for multiple platforms."
|
|
---
|
|
|
|
# PyPI Wheel Distribution (Kingfisher CLI)
|
|
|
|
This document describes how to package the Kingfisher Rust binary into
|
|
platform-specific Python wheels so users can install and run `kingfisher` via
|
|
`pip` or `uv`.
|
|
|
|
## Overview
|
|
|
|
The Python package is a thin wrapper that bundles the compiled Kingfisher binary
|
|
inside `kingfisher/bin/` and exposes a `kingfisher` console entry point that
|
|
executes it.
|
|
|
|
Users can run it without installation via `uvx`:
|
|
|
|
```bash
|
|
uvx kingfisher-bin --help
|
|
```
|
|
|
|
## Build prerequisites
|
|
|
|
1. Build the Kingfisher binary for your target platform (see
|
|
[INSTALLATION.md](../getting-started/installation.md) for `make` targets).
|
|
2. Install the Python build tooling:
|
|
|
|
```bash
|
|
python -m pip install build
|
|
```
|
|
|
|
## Build a wheel
|
|
|
|
Run the helper script from the repo root:
|
|
|
|
```bash
|
|
scripts/build-pypi-wheel.sh \
|
|
--binary ./path/to/kingfisher \
|
|
--version 1.2.3 \
|
|
--plat-name manylinux_2_17_x86_64
|
|
```
|
|
|
|
For Windows, pass the `.exe` binary and a Windows platform tag:
|
|
|
|
```bash
|
|
scripts/build-pypi-wheel.sh \
|
|
--binary .\\path\\to\\kingfisher.exe \
|
|
--version 1.2.3 \
|
|
--plat-name win_amd64
|
|
```
|
|
|
|
If you only build a Windows x64 binary, you can still ship a `win_arm64` wheel
|
|
using the same executable (it runs under emulation on ARM64 Windows):
|
|
|
|
```bash
|
|
scripts/build-pypi-wheel.sh \
|
|
--binary .\\path\\to\\kingfisher.exe \
|
|
--version 1.2.3 \
|
|
--plat-name win_arm64
|
|
```
|
|
|
|
The resulting wheel will be placed in `dist-pypi/` by default.
|
|
|
|
## Test locally
|
|
|
|
```bash
|
|
python -m pip install dist-pypi/kingfisher_bin-*.whl
|
|
kingfisher --help
|
|
```
|
|
|
|
## Publish
|
|
|
|
Upload the wheels to PyPI using `twine` (or your preferred tool):
|
|
|
|
```bash
|
|
python -m pip install twine
|
|
python -m twine upload dist-pypi/*
|
|
```
|
|
|
|
### GitHub Actions (recommended)
|
|
|
|
The repository includes a `pypi-wheels` workflow that:
|
|
|
|
1. Downloads the release binaries.
|
|
2. Builds platform-tagged wheels.
|
|
3. Publishes them to PyPI using Trusted Publishing (OIDC).
|
|
|
|
To use Trusted Publishing, create a PyPI project named `kingfisher-bin` and
|
|
enable GitHub Actions as a trusted publisher for this repository and workflow.
|
|
No API token is required once Trusted Publishing is configured.
|
|
|
|
If you do not use Trusted Publishing, generate a PyPI API token and provide it
|
|
to `twine` (for example via `TWINE_USERNAME=__token__` and
|
|
`TWINE_PASSWORD=<pypi-token>`).
|