Documentation about pure python wheel building

[soxofaan]

Description

I regularly hear about cibuildwheel and while I mostly work on pure-Python prjects where wheel building is not really a big problem, I still wonder if I'm missing out on something and should consider using cibuildwheel in some way.

As far as I understand now (e.g. from #1021 and #255), cibuildwheel is not relevant for pure-python projects, but that is not obvious for the uninitiated reader as it is not explicitly mentioned in the docs.

e.g. the project summary just talks about "building wheels", but about compiling non-pure-python code, which is the hard part cibuildwheel tries to tackle I guess

Python wheels are great. Building them across Mac, Linux, Windows, on multiple versions of Python, is not.

cibuildwheel is here to help. cibuildwheel runs on your CI server - currently it supports GitHub Actions, Azure Pipelines, Travis CI, AppVeyor, CircleCI, and GitLab CI - and it builds and tests your wheels across all of your platforms.

Build log

No response

CI config

No response

[andyfaff]

If you have a pure python project, and you don't need to tailor a distributable wheel for a given OS, then cibuildwheel has less utility (I think - I'm not a cibuildwheel maintainer)

[henryiii]

It has no utility if it's a pure Python project; there's no need to download docker images, build in a special environment, using multiple versions of Python, run wheel repair (which mangles symbols), etc. if you don't build anything at all, but just provide a bunch of .py files in a zip file. In that case, you can just use:

pipx run build

In GitHub Actions, or locally, with any Python version, once, and that will prepare the SDist and wheel for your pure Python package.

[henryiii]

(Fine IMO to take improvements to the docs as long as they don't distract too much from telling people who are looking for building binaries what to do :) )

[webknjaz]

It would also be worth noting that projects with c-extensions may want to provide a pure-python any-tagged wheel, when they offer a pure-python implementation as a fallback. This is something we do in @aio-libs. There's one job running python -Im build that produces a py3-any wheel along with the sdist and a separate job matrix that makes more wheels out of that sdist. This way, when new CPython versions come out, people would still be able to avoid facing the compiler (at the expense of some runtime slowdown, though)...

[henryiii]

The setup for that is backend-specific; every backend will have some way of telling it to avoid building or to build the binary portion. It's also a bit specialized, as only a few smaller libraries or libraries made with specific tools (mypyc, for example) usually do this; it's not very easy for most large projects to maintain two implementations in two languages.

Nothing wrong with noting it, but I'd not go down the rabbit hole of trying to show how to do it. :)

[joerick]

Closing as a wontfix. As @henryiii says, for regular Python-only wheels, you can just do:

pipx run build