[Distutils] Wheel support added to distlib

Vinay Sajip vinay_sajip at yahoo.co.uk
Tue Feb 19 21:16:44 CET 2013

Following the acceptance of PEP 427 (The Wheel Binary Package Format 1.0), I've
added support for Wheel to distlib [1].

There are still some issues cropping up in my Windows and OS X tests - the test
code uses pip to install some test distributions to build wheels from, and the
issues appear to be related to the versions of pip on those machines. I expect
to have those resolved soon.

The documentation has been updated [2], but I'll just highlight some aspects of
the API. Building wheels is simple:

    from distlib.wheel import Wheel

    wheel = Wheel()

    # Set the distribution's identity
    wheel.name = 'name_of_distribution'
    wheel.version = '0.1'

    # Set the tags you need, if the defaults don't fit your needs.
    # The filename will be computed automatically.
    wheel.pyver = ['py32']
    wheel.abi = ['none']
    wheel.arch = ['linux_x86_64']

    # Indicate where the files to go in the wheel are to be found
    paths = {
        'prefix': '/path/to/installation/prefix',
        'purelib': '/path/to/purelib',  # only one of purelib
        'platlib': '/path/to/platlib',  # or platlib should be set
        'scripts': '/path/to/scripts',
        'headers': '/path/to/headers',
        'data': '/path/to/data',

    wheel.dirname = '/where/you/want/the/wheel/to/go'
    # Now build

If the 'data', 'headers' and 'scripts' keys are absent, or point to paths which
don't exist, nothing will be added to the wheel for these categories. The
'prefix' key and one of 'purelib' or 'platlib' *must* be provided, and the
paths referenced should exist.

Installing from wheels is similarly easy:

    from distlib.wheel import Wheel

    wheel = Wheel('/path/to/my_dist-0.1-py32-none-any.whl')

    # Indicate where the files in the wheel are to be installed to.
    # All the keys should point to writable paths.
    paths = {
        'prefix': '/path/to/installation/prefix',
        'purelib': '/path/to/purelib',
        'platlib': '/path/to/platlib',
        'scripts': '/path/to/scripts',
        'headers': '/path/to/headers',
        'data': '/path/to/data',

    # Now install. The method accepts a ``dry_run`` keyword
    # argument which goes through the installation procedure
    # but doesn't actually install anything.

Although some work has been done to add wheel support to pip, you don't need
this to build wheels for existing PyPI distributions if you use distlib. The
following script, wheeler.py, shows how you can use an unpatched, vanilla pip
to build wheels:


Obviously this work has just been done so there will be some rough edges, but
I would welcome feedback from anyone who wants to try it out. If you want to
report issues, you can do it on the BitBucket tracker [3]. Coverage stats are
available at [4].


Vinay Sajip

[1] https://bitbucket.org/vinay.sajip/distlib/
[2] http://distlib.readthedocs.org/en/latest/tutorial.html#using-the-wheel-api
[3] https://bitbucket.org/vinay.sajip/distlib/issues/new
[4] http://www.red-dove.com/distlib/coverage/

More information about the Distutils-SIG mailing list