DOCSEARCHbyAlgolia
Submit Docs

wheel Documentation

repository·main·Indexed 20 days ago

https://github.com/pypa/wheel

A command line tool for manipulating Python wheel files according to PEP 427. It provides utilities to convert legacy .egg files or Windows installers to wheels, unpack and repack archives with RECORD file regeneration, inspect metadata via wheel info, and modify Python, ABI, or platform tags using wheel tags. Requires Python 3.9 or higher.

Tokens
8.8K
Snippets
48
Records
55
Agent score
62%

What's inside wheel

  1. Overview of the wheel command line tool

    main
    The wheel package provides a command line tool for manipulating Python wheel files as defined in PEP 427. It is used for tasks such as converting legacy .egg archives to .whl format, unpacking or repacking wheel archives, and managing platform tags within existing wheels.

  2. Use the wheel CLI to manage binary wheels

    main

    The wheel command-line tool is used to install and operate on binary wheels in the PEP 427 format. It provides several subcommands for unpacking, repacking, converting, and inspecting wheel files.

    wheel [command] [options]

  3. Convert eggs or Windows installers to wheels using `wheel convert`

    main

    The wheel convert command allows you to transform legacy .egg files (created with bdist_egg) or Windows installers (.exe files created with bdist_wininst) into modern .whl (wheel) files.

    Egg Naming Requirements To be successfully converted, egg names must follow these standard formats:

    • Pure Python eggs: <project>-<version>-pyX.Y
    • Binary eggs: <project>-<version>-pyX.Y-<arch>

    If the filename does not match these patterns, the command will fail with an error and return exit code 1.

    # Convert a single egg file
$ wheel convert foobar-1.2.3-py2.7.egg

  4. Prepare a new release

    main

    To release a new version of wheel, follow these steps in order:

    1. Update the changelog: Edit docs/news.rst and replace **UNRELEASED** with the version and date in the format **X.Y.Z (20XX-YY-ZZ)**.
    2. Update the version attribute: In src/wheel/__init__.py, update the __version__ attribute to match the new version number (exclude the date).
    3. Tag the release: Create a new git tag that matches the version number exactly.
    4. Push the tag: Push the tag to GitHub. This triggers the automated workflow that packages the project and publishes artifacts to PyPI.

  5. Submit a Pull Request

    main

    When contributing to wheel, submit Pull Requests against the main branch. Ensure you provide a description of your changes and include tests that cover your modifications. You can automate issue closing by using phrases like fixes #1259 in your commit messages.

    # Standard workflow for contributing
$ git clone git@github.com:pypa/wheel.git
$ cd wheel
# ... make changes ...
$ git add <modified> ...
$ git commit -m "fixes #1259"
$ git push git@github.com:yourname/wheel.git

  6. Unpack a wheel file with `wheel unpack`

    main

    Use the wheel unpack command to extract the contents of a .whl file. Unlike a standard unzip command, wheel unpack validates the integrity of the files by checking that their hashes and sizes match the entries in the wheel's RECORD file. If a mismatch is detected, the command will exit with an error (exit code 1) and raise a wheel.install.BadWheelFile exception.

    To unpack a wheel into a specific directory, use the -d or --dest option.

    # Unpack a wheel into the current directory
wheel unpack someproject-1.5.0-py2-py3-none.whl

# Unpack a wheel into a specific destination directory
wheel unpack someproject-1.5.0-py2-py3-none.whl -d /path/to/destination

  8. Show help for the wheel command

    main

    To see the available commands and options for the wheel tool, use the --help flag or the help command. For specific details on a subcommand, use wheel <command> --help.

    wheel --help
# OR
wheel help
# For specific commands:
wheel unpack --help

  10. When to install the wheel package

    main
    As of setuptools v70.1, the setuptools bdist_wheel command no longer requires the wheel package to be installed to function. You should only install this package if you specifically need to use the wheel command line tool for manual manipulation of wheel files (e.g., unpacking, repacking, or adding/removing tags).

  11. Build a wheel for your project

    main

    To create a wheel distribution for your project, use the build module. This is the recommended way to build wheels rather than using setup.py directly.

    1. Install the build package.
    2. Run the build command with the --wheel flag.

    The resulting wheel file will be placed in the dist/ directory with a filename following the pattern yourproject-<tags>.whl.

    python -m pip install build
python -m build --wheel