tessl/pypi-cibuildwheel
Build Python wheels on CI with minimal configuration.
—
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
index.mddocs/
Cibuildwheel
A comprehensive CI-native tool for building Python wheels across multiple platforms, operating systems, and Python versions with minimal configuration. Cibuildwheel automates the complex process of creating distributable Python packages (wheels) on continuous integration servers.
Package Information
- Package Name: cibuildwheel
- Package Type: pypi
- Language: Python
- Installation:
pip install cibuildwheel
Core Imports
import cibuildwheel # Provides __version__For programmatic usage:
from cibuildwheel.architecture import Architecture
from cibuildwheel.errors import * # All error classes
from cibuildwheel.options import Options, compute_options
from cibuildwheel.selector import BuildSelector
from cibuildwheel.typing import PlatformName, PLATFORMSBasic Usage
Command Line Usage
# Install cibuildwheel
pip install cibuildwheel
# Build wheels for current platform
cibuildwheel
# Build for specific platform
cibuildwheel --platform linux
# Build for specific architectures
cibuildwheel --archs x86_64,aarch64
# Specify output directory
cibuildwheel --output-dir wheelhouse
# Build from specific package directory
cibuildwheel ./my-packageCI Integration Example
# GitHub Actions example
name: Build wheels
on: [push, pull_request]
jobs:
build_wheels:
name: Build wheels on ${{ matrix.os }}
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v4
- name: Install cibuildwheel
run: python -m pip install cibuildwheel
- name: Build wheels
run: python -m cibuildwheel --output-dir wheelhouse
- uses: actions/upload-artifact@v4
with:
name: wheels
path: ./wheelhouse/*.whlConfiguration via pyproject.toml
[tool.cibuildwheel]
# Build only for Python 3.9+
build = "cp39-* cp310-* cp311-* cp312-*"
# Skip 32-bit builds
skip = "*-win32 *-manylinux_i686"
# Test command
test-command = "pytest {project}/tests"
# Environment variables
environment = { CFLAGS="-O2" }Architecture
Cibuildwheel operates on a platform-module architecture where each supported platform (Linux, macOS, Windows, iOS, Android, Pyodide) has its own specialized build module. The tool:
- Detects or accepts target platform specification
- Selects Python configurations based on build selectors and architecture requirements
- Manages build environments including containers for Linux and virtual environments for other platforms
- Orchestrates the build process including dependency installation, wheel building, and testing
- Handles wheel repair through platform-specific tools like auditwheel and delocate
Capabilities
Command Line Interface
The primary interface for running cibuildwheel with comprehensive options for platform selection, architecture specification, build filtering, and output configuration.
def main() -> NonePlatform Support
Cross-platform wheel building with native support for major operating systems and architectures, including emulation support for cross-compilation.
PlatformName = Literal["linux", "macos", "windows", "pyodide", "android", "ios"]
PLATFORMS: Final[frozenset[PlatformName]]
def native_platform() -> PlatformNameArchitecture Management
Comprehensive architecture support with automatic detection, cross-compilation capabilities, and architecture-specific build configuration.
class Architecture(StrEnum):
x86_64: str
aarch64: str
arm64: str
# ... and many more
@staticmethod
def parse_config(config: str, platform: PlatformName) -> set[Architecture]
@staticmethod
def native_arch(platform: PlatformName) -> Architecture | NoneBuild Selection and Filtering
Advanced pattern-based build selection system for controlling which Python versions, platforms, and architectures to build for.
@dataclasses.dataclass(frozen=True, kw_only=True)
class BuildSelector:
build_config: str
skip_config: str
requires_python: SpecifierSet | None
enable: frozenset[EnableGroup]
def __call__(self, build_id: str) -> boolConfiguration Management
Comprehensive configuration system supporting TOML files, environment variables, and command-line options with validation and schema support.
@dataclasses.dataclass(frozen=True, kw_only=True)
class Options:
globals: GlobalOptions
def compute_options(platform: PlatformName, command_line_arguments: CommandLineArguments, env: Mapping[str, str]) -> OptionsEnvironment Handling
Advanced environment variable parsing with bash syntax support and context-aware evaluation for build customization.
@dataclasses.dataclass(kw_only=True)
class ParsedEnvironment:
assignments: list[EnvironmentAssignment]
def as_dictionary(self, prev_environment: Mapping[str, str], executor: bashlex_eval.EnvironmentExecutor | None = None) -> dict[str, str]
def parse_environment(env_string: str) -> ParsedEnvironmentError Handling
Structured exception hierarchy with specific error types and return codes for different failure scenarios.
class FatalError(BaseException):
return_code: int
class ConfigurationError(FatalError): ...
class NothingToDoError(FatalError): ...
# ... other specific error typesCI Integration
Built-in support for major CI/CD platforms with platform-specific optimizations and output formatting.
class CIProvider(Enum):
github_actions: str
azure_pipelines: str
# ... other providers
def detect_ci_provider() -> CIProvider | NoneUtility Functions
Helper functions for string formatting, command preparation, version parsing, and other common operations.
def format_safe(template: str, **kwargs: str | os.PathLike[str]) -> str
def prepare_command(command: str, **kwargs: PathOrStr) -> str
def strtobool(val: str) -> boolInstall with Tessl CLI
npx tessl i tessl/pypi-cibuildwheel