RFC: Public Wheel API

I’m requesting comments from all authors of Python packaging tools about the upcoming API exposed by the wheel library, as per issue 262.

The question for those packaging tool authors is this: What functionality would the wheel library have to expose for you to be able to use it for wheel building and/or manipulation?

The features currently requested:

  • The ability to read/write wheel specific metadata files in a structured manner
  • The ability to report the tags with which a wheel is compatible

Ideally I would like to ensure that no functionality is duplicated across the PyPA ecosystem. Wheel already depends on the packaging library for its PEP 425 tag support, and if necessary, I can add additional dependencies to other PyPA libraries.

If I hear nothing from packaging tool authors, I’ll be moving forward with the public API within two weeks. I will also take this opportunity to drop Python 2 support and bump the version to 1.0. In any case I will give the community an opportunity to review the proposed 1.0 features at least before a final release.


Thanks for the heads up!

I just quickly typed down my thoughts on the linked issue.

Notifying maintainers of possible affected library maintainers @sdispater @pf_moore @dustin @takluyver @jaraco @cjerdonek @xafer @crwilcox

1 Like

I don’t care about detecting tag compatibility, but my backend intentionally makes that the creator’s full responsibility. Feel free to integrate with packaging.tags.

If it’s basically ZipFile but without me having to concatenate/normalise the filename or special directories (but I can still write arbitrary files into those), I’m good.

1 Like

There’s discussion about moving away from inheriting from ZipFile, in the issue linked in OP.

I don’t care whether it’s a subclass. I just want it to be agnostic as to where the data is coming from and will let me provide bytes and an in-archive path and will just do it.

1 Like

To anyone following only this side and not the Github issue, a draft of the public API is now available for commenting.


I’m not sure how to comment on github, so I’ll mention it here. I would like to see a means of building (and reading) a wheel in memory. Unless I misunderstood, the API only supports disk based wheels.

Examples of use cases:

  • I download a file from a URL, and I want to introspect the data in memory.
  • I’m writing a test where I have a set of filenames and content that I want to pack into a wheel and expose via a webserver, all done in-memory, so that my test code can exercise my “install a wheel from a URL” functionality.

I can of course use a temporary disk file for this, but that adds overhead (I haven’t measured, but pip’s test suite builds a lot of throwaway wheels, and that results in pretty heavy disk usage). So an in-memory option would be better.


Sure, I can accommodate that use case. I’ll update the draft later today.

1 Like

@pf_moore one question: would you prefer supplying the filename directly to the initializer or just the various components plus an open file handle?

I don’t think it matters much to me. Components sounds like it would be more logical (why construct a filename that I’m not expecting to use myself?) but I’m fine with whatever’s more convenient to implement as I can just call make_filename if needed.

Components sounds like it would be more logical (why construct a filename that I’m not expecting to use myself?)

Because the same initializer needs to work for all use cases, including those where an existing wheel file on disk is opened.

I could keep the initializer private and provide several public class methods for instantiating the WheelFile which would cover most use cases:

  1. Open an existing file for reading
  2. Open a byte buffer (BytesIO) for reading
  3. Create a new wheel on disk
  4. Create a new wheel in memory (BytesIO)

As you said, the file names don’t matter if we’re working with just memory buffers. We could also just extract the metadata from the WHEEL file if no file name was supplied.

I’ve pushed the changes to the repo – have a look!

1 Like