Что такое Python wheels?

Question

claude-haiku-4.5 · Accepted Answer

# Что такое Python Wheels

Wheel (.whl) — это современный формат дистрибьюции Python пакетов, альтернатива устаревшему egg и source distributions.

## Базовое определение

**Wheel** — это архив (ZIP), содержащий:
1. Скомпилированный Python код (.pyc файлы)
2. Нативные расширения (C, C++, Rust код, скомпилированный для конкретной платформы)
3. Данные пакета (ресурсы, конфиги)
4. Метаданные (версия, зависимости, информация об авторе)

```bash
# Структура wheel файла
my_package-1.0.0-py3-none-any.whl
├── my_package/
│   ├── __init__.py
│   ├── module.py
│   └── subpackage/
├── my_package-1.0.0.dist-info/
│   ├── WHEEL
│   ├── METADATA
│   ├── RECORD
│   └── entry_points.txt
└── (архив)
```

## Строение имени wheel

```
my_package-1.0.0-py3-none-any.whl
                ▲    ▲    ▲   ▲
         Python  |    |    Binary
         version |    |    compatibility
                 |    OS   (none = pure Python)
         ABI tag (none = no C extensions)
```

Примеры:
- `Django-4.2.0-py3-none-any.whl` — pure Python, для всех платформ
- `numpy-1.24.0-cp311-cp311-win_amd64.whl` — скомпилировано под Windows 64-bit Python 3.11
- `cryptography-41.0.0-cp39-abi3-macosx_10_12_x86_64.whl` — для macOS Intel

## Сравнение с другими форматами

```
SDIST (Source Distribution)
├─ формат: tar.gz или zip
├─ содержит: исходный код + setup.py
├─ минусы: нужна компиляция на целевой машине
├─ плюсы: маленький размер, кроссплатформенный
└─ пример: my_package-1.0.0.tar.gz

WHEEL (Built Distribution)
├─ формат: zip архив
├─ содержит: скомпилированный код
├─ плюсы: быстрая установка, гарантированная совместимость
├─ минусы: больше размер, разные версии под платформы
└─ пример: my_package-1.0.0-py3-none-any.whl
```

## Преимущества Wheels

### 1. **Быстрая установка**
```bash
# SDIST — копирование файлов
pip install my_package-1.0.0.tar.gz
# Нужна компиляция (может быть долго)

# WHEEL — просто распаковать архив
pip install my_package-1.0.0-py3-none-any.whl
# Почти мгновенно
```

### 2. **Гарантированная совместимость**
Если у тебя установлены зависимости (например, компилятор C), wheel будет работать на другой машине с тем же Python.

### 3. **Поддержка нативных расширений**
```python
# Для пакетов с C/C++ кодом (numpy, cryptography)
# SDIST требует gcc/clang на целевой машине
# WHEEL уже скомпилирован

import numpy as np
np.dot([1, 2], [3, 4])  # Это C код, выполняется быстро
```

### 4. **Кроссплатформенность (для pure Python)**
```
Flask-3.0.0-py3-none-any.whl
         ▲       ▲    ▲
      Python 3  no extension  any platform
```

Этот wheel работает на Windows, macOS, Linux, везде.

## Создание wheels

### 1. **Современный способ (pyproject.toml)**
```toml
# pyproject.toml
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "1.0.0"
description = "My awesome package"
```

```bash
# Установить инструменты
pip install build

# Собрать wheel
python -m build
# Результат: dist/my_package-1.0.0-py3-none-any.whl
```

### 2. **С C расширением (setuptools)**
```python
# setup.py
from setuptools import setup, Extension

setup(
    name="my_package",
    ext_modules=[
        Extension(
            "my_package._core",
            sources=["src/core.c"],
        ),
    ],
)
```

```bash
python -m build
# Результат: my_package-1.0.0-cp311-cp311-linux_x86_64.whl
# На других платформах/Python версиях будут разные имена
```

### 3. **С Rust (с помощью maturin)**
```toml
# pyproject.toml для Rust расширения
[build-system]
requires = ["maturin"]
build-backend = "maturin"

[project]
name = "my_rust_package"
```

```bash
maturin develop  # Сборка и установка в editable mode
maturin build    # Создать wheel
```

## Установка wheels

```bash
# Из файла
pip install /path/to/my_package-1.0.0-py3-none-any.whl

# Из PyPI (pip скачивает wheel если доступен)
pip install numpy
# Скачивает numpy-1.24.0-cp311-cp311-linux_x86_64.whl

# Несколько wheels сразу
pip install *.whl
```

## Universal wheels

```
Flask-3.0.0-py2.py3-none-any.whl
        ▲       ▲
    Python 2 и 3  any platform
```

Универсальный wheel для Python 2 и 3. Сейчас редко, т.к. Python 2 мёртв.

## Практические примеры

### Пример 1: Чистый Python пакет
```bash
my_package/
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── module.py
├── tests/
├── pyproject.toml
└── README.md

# Сборка
python -m build
# Результат: dist/my_package-1.0.0-py3-none-any.whl
# (один wheel для всех платформ)
```

### Пример 2: С нативным расширением
```bash
# Linux user
python -m build
# Результат: my_package-1.0.0-cp311-cp311-linux_x86_64.whl

# Windows user (другой wheel)
python -m build
# Результат: my_package-1.0.0-cp311-cp311-win_amd64.whl

# macOS user (intel)
# Результат: my_package-1.0.0-cp311-cp311-macosx_10_9_x86_64.whl

# macOS user (apple silicon)
# Результат: my_package-1.0.0-cp311-cp311-macosx_11_0_arm64.whl
```

Именно поэтому на PyPI один пакет имеет множество wheels.

## Binary wheels vs Source distributions

Посмотри на PyPI:
```
numpy 1.24.0
├── numpy-1.24.0.tar.gz          (source)
├── numpy-1.24.0-cp39-*.whl      (binary для Python 3.9)
├── numpy-1.24.0-cp310-*.whl     (binary для Python 3.10)
├── numpy-1.24.0-cp311-*.whl     (binary для Python 3.11)
├── numpy-1.24.0-cp312-*.whl     (binary для Python 3.12)
└── ...

pip install numpy
# Автоматически выбирает подходящий wheel
```

## Содержимое WHEEL файла

```ini
# Пример содержимого my_package-1.0.0.dist-info/WHEEL
Wheel-Version: 1.0
Generator: setuptools (68.0.0)
Root-Is-Purelib: true
Tag: py3-none-any
```

## Advanced: Wheel файлы с компилятором

Для пакетов с C расширениями нужно собирать wheels для разных платформ. GitHub Actions помогает:

```yaml
# .github/workflows/build-wheels.yml
name: Build Wheels
with:
  - uses: PyO3/maturin-action
    with:
      maturin-version: latest
```

## Где находятся wheels

1. **PyPI** — основной источник (https://pypi.org)
2. **Локально** — после сборки в `dist/` папке
3. **Requirements файл:**
```
-f ./wheels/  # Поиск wheels в локальной папке
numpy==1.24.0
```

## Итого

✅ Wheels — современный стандарт распределения Python пакетов
✅ Быстрая установка (нет компиляции на целевой машине)
✅ Поддержка нативных расширений (C, C++, Rust)
✅ Специфичные для платформы (разные для Windows/macOS/Linux)
✅ Простое создание: `python -m build`

В 99% случаев pip автоматически скачает и установит wheel если он доступен на PyPI.

Что такое Python wheels?

Комментарии (1)

Базовое определение

Строение имени wheel

Сравнение с другими форматами

Преимущества Wheels

1. Быстрая установка

2. Гарантированная совместимость

3. Поддержка нативных расширений

4. Кроссплатформенность (для pure Python)

Создание wheels

1. Современный способ (pyproject.toml)

2. С C расширением (setuptools)

3. С Rust (с помощью maturin)

Установка wheels

Universal wheels

Практические примеры

Пример 1: Чистый Python пакет

Пример 2: С нативным расширением

Binary wheels vs Source distributions

Содержимое WHEEL файла

Advanced: Wheel файлы с компилятором

Где находятся wheels

Итого