pypa / pypa/setuptools

Document `py-limited-api` option to `bdist_wheel`

Open
#4,741 6 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

help wanted
Dominant language
Python
Stars
2.9k
Forks
1.4k
Avg merge
1d 1h
Merged PRs (30d)
1

Description

To tag a wheel containing C extension modules as compatible with multiple Python releases, one must specify the undocumented py-limited-api option to bdist_wheel, setting it to the minimum Python version supported by the wheel. Otherwise the wheel will be tagged for the current Python release only, even if its C extension modules are built against the Python Limited API.

For the record, in setup.cfg this looks like:

[bdist_wheel]
py-limited-api = cp311

Or in pyproject.toml: — see https://github.com/pypa/wheel/issues/582#issuecomment-1807234132

[tool.distutils.bdist_wheel]
py-limited-api = "cp311"

Or in setup.py:

setup(
    [...],
    options={'bdist_wheel': {'py_limited_api': 'cp311'}},
)

The latter is useful (alongside define_macros=[('Py_LIMITED_API', '0x...')]) if you need to programmatically disable the abi3 compatibility tag on older Python releases that haven't stabilized the API functions you need.

Please document this. I found it quite confusing: I defined Py_LIMITED_API, specified Extension(..., py_limited_api=True), and still got an incorrectly tagged wheel. It isn't necessarily obvious that setuptools and bdist_wheel don't share configuration, and the lack of documentation makes the problem hard to track down.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Locate the existing bdist_wheel documentation entry point; the issue does not name a documentation file or test. Document the py-limited-api option using the setup.cfg and setup.py examples, explain how it affects wheel compatibility tags, and clarify its relationship to Py_LIMITED_API and Extension(..., py_limited_api=True).

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.