Clarification on a wheel's header data

I’ve sent GH-29578. Apologies for the delay.

Do we have any real examples of wheels containing headers in this location? I’ve just gone and looked at a few packages I thought might (NumPy, pybind11, PyQt6, sip, Cython), but none them seem to ship headers in a .data directory. Maybe some of them would if this confusion was cleared up - Python issue 26955 is the pybind11 author asking about it - but it doesn’t look like there’s a lot of pressure to resolve it.

If not, maybe we should deprecate the ‘headers’ directory in the wheel spec, and say that it’s up to installers how to handle it wheels using it, so ignoring that directory or refusing to install the entire wheel would be valid options.

1 Like

I would also like to know of any projects depending on either a .data/headers dir or shipping include files. I don’t know of any, but pip does have custom logic for this specific data dir, and it is more involved than the other data dirs (at least in locations.py), leading me to believe that it was important.

If no such use can be found, deprecating headers does sound like a good plan. Maybe also removing it from the PEP; I know the list of data dirs is not meant to be complete, but its inclusion feels like a blessing. Maybe the PyPA should put out a recommendation that installation of any wheels with a .data/{headers,include,platinclude,stdlib} should raise an error? I’m sure if pip adopted this behaviour any use of headers will come to light :upside_down_face: .

Also, side note in python3.11 ‘headers’ doesn’t seem to appear as a path name, instead it is ‘include’ (but I do not see ‘platinclude’).

@layday just pointed out to me that greenlet is an example of a package which does use the headers directory. It installs one file greenlet.h there.

Older versions of pybind11 also have a headers directory, although the latest one doesn’t seem to (edit: they moved to a separate package, pybind11-global). And it looks like tensorflow might use it, although the wheel that I looked at did not (they may have different ways of making wheels, I’m not sure).