tessl/pypi-cibuildwheel

Build Python wheels on CI with minimal configuration.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

CI Integration

Name: tessl/pypi-cibuildwheel
Author: tessl

Cibuildwheel provides built-in support for major CI/CD platforms with platform-specific optimizations and output formatting.

Capabilities

CI Provider Detection

Automatic detection of the current CI/CD platform.

class CIProvider(Enum):
    travis_ci = "travis"
    circle_ci = "circle_ci" 
    azure_pipelines = "azure_pipelines"
    github_actions = "github_actions"
    gitlab = "gitlab"
    cirrus_ci = "cirrus_ci"
    appveyor = "appveyor"
    other = "other"

def detect_ci_provider() -> CIProvider | None:
    """
    Detect the current CI provider based on environment variables.
    
    Returns:
        CIProvider enum value for detected provider, or None if not detected
    """

Output Formatting

CI-specific output formatting and ANSI code handling.

def fix_ansi_codes_for_github_actions(text: str) -> str:
    """
    Fix ANSI escape codes for proper display in GitHub Actions logs.
    
    Args:
        text: Text containing ANSI escape codes
        
    Returns:
        Text with ANSI codes adjusted for GitHub Actions
    """

def filter_ansi_codes(text: str, /) -> str:
    """
    Remove ANSI escape codes from text.
    
    Args:
        text: Text containing ANSI escape codes
        
    Returns:
        Text with ANSI codes removed
    """

Supported CI Platforms

GitHub Actions

Native first-class support with specialized output formatting.

Configuration:

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
        with:
          python-version: '3.11'

      - 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/*.whl

Features:

Automatic ANSI code adjustment for log readability
Matrix build support for multiple platforms
Artifact upload integration
Environment variable detection

Azure Pipelines

Full support with multi-platform build capabilities.

Configuration:

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

strategy:
  matrix:
    linux:
      imageName: 'ubuntu-latest'
    mac:
      imageName: 'macOS-latest'  
    windows:
      imageName: 'windows-latest'

steps:
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.11'

- script: python -m pip install cibuildwheel
  displayName: 'Install cibuildwheel'

- script: python -m cibuildwheel --output-dir wheelhouse
  displayName: 'Build wheels'

- task: PublishBuildArtifacts@1
  inputs:
    pathToPublish: 'wheelhouse'
    artifactName: 'wheels'

Travis CI

Support for Linux and Windows builds.

Configuration:

language: python
python: "3.11"

services:
  - docker

matrix:
  include:
    - os: linux
      python: "3.11"
    - os: windows
      language: shell
      python: "3.11"

install:
  - python -m pip install cibuildwheel

script:
  - python -m cibuildwheel --output-dir wheelhouse

deploy:
  provider: releases
  api_key: $GITHUB_TOKEN
  file_glob: true
  file: wheelhouse/*.whl
  skip_cleanup: true
  on:
    tags: true

CircleCI

Docker-based builds with caching support.

Configuration:

version: 2.1

orbs:
  python: circleci/python@2.0.3

jobs:
  build-wheels:
    docker:
      - image: cimg/python:3.11
    steps:
      - checkout
      - setup_remote_docker:
          version: 20.10.7
      - python/install-packages:
          pkg-manager: pip
          pip-dependency-file: requirements.txt
      - run:
          name: Install cibuildwheel
          command: python -m pip install cibuildwheel
      - run:
          name: Build wheels
          command: python -m cibuildwheel --output-dir wheelhouse
      - store_artifacts:
          path: wheelhouse

workflows:
  build-and-test:
    jobs:
      - build-wheels

GitLab CI

Docker-based builds with GitLab-specific features.

Configuration:

image: python:3.11

stages:
  - build

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

cache:
  paths:
    - .cache/pip/
    - venv/

build-wheels:
  stage: build
  services:
    - docker:dind
  variables:
    DOCKER_DRIVER: overlay2
  before_script:
    - python -m pip install cibuildwheel
  script:
    - python -m cibuildwheel --output-dir wheelhouse
  artifacts:
    paths:
      - wheelhouse/
    expire_in: 1 week

Cirrus CI

Flexible cloud-based CI with multiple platform support.

Configuration:

task:
  name: Build wheels
  compute_engine_instance:
    image_project: cirrus-images
    image: family/docker-builder
    platform: linux
    cpu: 4
    memory: 8G

  install_script:
    - python -m pip install cibuildwheel

  build_script:
    - python -m cibuildwheel --output-dir wheelhouse

  wheels_artifacts:
    path: "wheelhouse/*"

AppVeyor

Windows-focused CI with Visual Studio integration.

Configuration:

image: Visual Studio 2019

environment:
  matrix:
    - PYTHON: "C:\\Python311"
    - PYTHON: "C:\\Python311-x64"

install:
  - "%PYTHON%\\python.exe -m pip install cibuildwheel"

build_script:
  - "%PYTHON%\\python.exe -m cibuildwheel --output-dir wheelhouse"

artifacts:
  - path: wheelhouse\*.whl
    name: wheels

CI-Specific Features

Environment Variable Detection

Cibuildwheel automatically detects CI-specific environment variables:

# GitHub Actions
GITHUB_ACTIONS = "true"
GITHUB_TOKEN = "secret_token"
GITHUB_REF = "refs/heads/main"

# Travis CI  
TRAVIS = "true"
TRAVIS_TAG = "v1.0.0"
TRAVIS_BRANCH = "main"

# Azure Pipelines
AZURE_PIPELINES = "true" 
BUILD_SOURCEBRANCH = "refs/heads/main"

# CircleCI
CIRCLECI = "true"
CIRCLE_TAG = "v1.0.0"
CIRCLE_BRANCH = "main"

Output Formatting

Each CI platform receives optimized output formatting:

GitHub Actions: ANSI codes adjusted for log viewer
Azure Pipelines: Compatible with Azure DevOps log display
GitLab CI: Optimized for GitLab's CI interface
Others: Standard ANSI formatting or plain text

Artifact Handling

Platform-specific artifact upload patterns:

# GitHub Actions
- uses: actions/upload-artifact@v4
  with:
    name: wheels-${{ matrix.os }}
    path: ./wheelhouse/*.whl

# Azure Pipelines  
- task: PublishBuildArtifacts@1
  inputs:
    pathToPublish: 'wheelhouse'
    artifactName: 'wheels'

# GitLab CI
artifacts:
  paths:
    - wheelhouse/
  expire_in: 1 week

Advanced CI Integration

Matrix Builds

Configure builds across multiple platforms and Python versions:

# GitHub Actions matrix
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    python-version: ['3.9', '3.10', '3.11']
    arch: [x86_64, aarch64]
    exclude:
      - os: windows-latest
        arch: aarch64  # Windows ARM not on all runners

Conditional Builds

Build wheels only on specific conditions:

# Build on tags only
on:
  push:
    tags:
      - 'v*'

# Or conditional job execution
jobs:
  build_wheels:
    if: startsWith(github.ref, 'refs/tags/')

Caching

Speed up builds with dependency caching:

# GitHub Actions
- uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}

# Azure Pipelines
- task: Cache@2
  inputs:
    key: 'pip | "$(Agent.OS)" | requirements.txt'
    path: $(Pipeline.Workspace)/.pip

Secret Management

Handle secrets securely in CI:

# GitHub Actions
env:
  CIBW_ENVIRONMENT: API_TOKEN=${{ secrets.API_TOKEN }}

# Azure Pipelines
variables:
  - group: build-secrets
env:
  CIBW_ENVIRONMENT: API_TOKEN=$(API_TOKEN)

Multi-Stage Builds

Separate build and deployment stages:

# GitHub Actions
jobs:
  build:
    # Build wheels
  
  test:
    needs: build
    # Test wheels
    
  deploy:
    needs: [build, test]
    if: startsWith(github.ref, 'refs/tags/')
    # Deploy to PyPI

Troubleshooting CI Issues

Common CI Problems

# Docker permission issues (Linux CI)
CIBW_CONTAINER_ENGINE = "podman"  # Alternative to Docker

# Memory constraints  
CIBW_BUILD = "cp311-*"  # Reduce build matrix

# Time limits
CIBW_TEST_SKIP = "*-linux_ppc64le *-linux_s390x"  # Skip slow tests

Debugging CI Builds

# Enable debug output
env:
  CIBW_DEBUG_TRACEBACK: 1

# Print build identifiers
- name: Debug build selection
  run: python -m cibuildwheel --print-build-identifiers

Platform-Specific Issues

# macOS code signing
env:
  CIBW_ENVIRONMENT_MACOS: CODESIGN_IDENTITY=""

# Windows long path support
env:
  CIBW_ENVIRONMENT_WINDOWS: CIBW_ENABLE_LONG_PATH_SUPPORT=1

# Linux emulation setup
- name: Set up QEMU
  uses: docker/setup-qemu-action@v2
  with:
    platforms: arm64,ppc64le,s390x