python: Write WHEEL tags in expanded form

[ichard26]

Hello, pip maintainer here. 👋

The wheel specification requires that the Tag field in .dist-info/WHEEL contains all of the tags in their expanded form. Leaving the compressed form unchanged is usually "fine", but pip (check only!) misidentifies the wheel as incompatible with the system when fed a compressed wheel tag set. We just got a bug report about this: pypa/pip#13709

• https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#compressed-tag-sets
• point 11 under "file contents" in https://packaging.python.org/en/latest/specifications/binary-distribution-format/#file-contents

While I'm unfamiliar with this repository and can't test the build script directly, the tag expansion logic has been tested below (it also comes from the specification FWIW).

Python 3.14.2 (main, Dec 18 2025, 12:16:31) [GCC 15.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> def expand(tag):
...     pytag, abitag, platformtag = tag.split("-")
...     for x in pytag.split('.'):
...         for y in abitag.split('.'):
...             for z in platformtag.split('.'):
...                 yield '-'.join((x, y, z))
...                 
>>> list(expand("py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64"))
['py3-none-manylinux_2_17_aarch64', 'py3-none-manylinux2014_aarch64', 'py3-none-musllinux_1_1_aarch64']
>>> 

[potiuk]

Cool. Would be great to have it fixed in the next version. Currently we had to workaround it in apache-airflow and use uv pip check in Airflow because of this problem - but we would like to get back topip check which was a deliberate choice to make our Image env verified with canonical pip check - see apache/airflow#59670

[kaxil]

@bglw Pagefind is great, thanks for building it.

We started using it in Airflow since yesterday with apache/airflow#59658 after a lot of frustration with Sphinx's search.

It would be great to get this merged in so we use this with pip and uv both.

[bglw]

Makes sense to me — thanks for opening the PR to fix!

(this reminds me, Pagefind has tipped over a pypi limit which is blocking a new publish there, I'll look at that soon as well)

[ichard26]

Sorry about failing CI. I pushed a new commit to fix Ruff format @bglw!

[bglw]

Hey @ichard26 @kaxil @potiuk — this has been rolled out in 1.5.0-alpha.3 (1.5.0a3 on pypi). There's a few irons in the fire before a full release lands, but that should be on the order of weeks all going well.

[potiuk]

I am runnig a test for it apache/airflow#59816 - but it looks great, I installed it locally and checked that pip check works with 1.5.0a3 of pagefind and pagefind-bin installed. Thanks for that!

One thing that I might want to suggest (if I correctly understand the split between pagefind and pagefind-bin) you do in the future (maybe 1.5.0) - is to explicitly pin pagefind-bin to the same version as pagefind

Currently in pagefind 1.5.0a3 you can find:

Requires-Dist: pagefind-bin<2,>=1; extra == 'bin'

I think what the intetion is however - is to always install the same "bin" version as the "non-bin" version when "bin" extra is used, so likely this would be better:

Requires-Dist: pagefind-bin==1.5.0a3; extra == 'bin'

or maybe (depending what your compatibility promises are betweeen bin and non-bin distributions).

Requires-Dist: pagefind-bin<2,>=1.5.0a3; extra == 'bin'

Side effect of the current "requires-dist" is that when you do this:

[uv] pip install pagefind[bin]>=1.5.0a3

or

[uv] pip install pagefind[bin]==1.5.0a3

It follows https://peps.python.org/pep-0440/#handling-of-pre-releases handling:

Pre-releases of any kind, including developmental releases, are implicitly excluded from all version specifiers, unless they are already present on the system, explicitly requested by the user, or if the only available version that satisfies the version specifier is a pre-release.

And it installs:

pagefind==1.5.0a3
pagefind-bin==1.4.0

Which is good by the "letter" of PEP-440, but it's not likely following the spirit and user expectation.

That's why in airflow I had to change:

 "pagefind[bin]"

into:

    "pagefind>=1.5.0a3",
    "pagefind-bin>=1.5.0a3",

Because just pagefind[bin]>=1.5.0a3 would install pagefind-bin==1.4.0

Also - another side effect of non-pinning is that if someone does today:

pip install pagefind[bin] 

and then (after you release 1.5.0)

pip install --upgrade pagefind[bin]

They will still keep pagefind-bin 1.4.0 installed - even if pagefind will be 1.5.0 (which is likely not what you would like to happen).

[bglw]

Aha, great tips, tyvm. Yes, the intention is indeed that versions are always in lockstep, which is enforced in the npm wrapper. I'm less versed in the Python publishing world so mostly I rely on helpful people pointing things like this out! :) I'll get these changes in.

[bglw]

I should also note that a big change in this current alpha (so far) is that the search in the browser has been offloaded into a web worker. I've tested it a bunch and I'm not aware of anything funky, and it's great for perceived performance, but just an FYI in case you notice anything due to that.

[potiuk]

I've tested it a bunch and I'm not aware of anything funky, and it's great for perceived performance, but just an FYI in case you notice anything due to that.

I tested it with locally build airflow docs and have not seen any issues so far. I am just about to publish this change to Airflow main and cherry-pick it to 3.1.6 so that when we publish documentation next time we will see it live. But we have a lot of contributors who work on the docs locally, so in case we see anythng funky we will let you definitely know.

Also FYI - coincidentally - I am also one of the mentors in the Apache Software Foundation incubator - and we are testing pagefind as a search solution to index our CWiki pages and we are discussing whether (and how) to index all contents instead of just a subset of it -> https://lists.apache.org/thread/ro2973lzyqd5hfdhb7fggqr39sth7gwm if you would like to chime in the discussion - feel free @bglw :)