pypa / pypa/packaging.python.org
Expand documentation on building for the Limited API
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.7k
- Forks
- 1.7k
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 4
Description
PyPUG has a small section on extension module API compatibility, which links to Python's nice Limited API documentation. The Python docs imply that the Limited API can be used simply by setting Py_LIMITED_API and auditing API calls in the code, but there are some packaging concerns as well. As far as I can tell, enabling the Limited API requires setting three separate knobs:
Py_LIMITED_API, to hide non-stabilized symbols and potentially replace some macros with functions.- The setuptools
Extension(..., py_limited_api=True)flag, to use the correct filename for the extension module. - The wheel
py-limited-apioption, to correctly ABI tag the wheel. See also: https://github.com/pypa/setuptools/issues/4741
These knobs are distributed across the ecosystem and there doesn't seem to be any unified documentation for them. This blog post was helpful for general understanding, but doesn't provide fully actionable advice. A concrete guide would really help.
In addition, perhaps the docs could mention how to conditionally disable the Limited API when building for older Python releases. Packages may want to continue shipping version-specific wheels for releases that haven't stabilized all of the C functions they need. I used setup.py code like this:
_abi3 = sys.version_info >= (3, 11)
setup(
ext_modules=[
Extension(
'fizzbuzz', ['fizzbuzz.c'],
define_macros=[('Py_LIMITED_API', '0x030b0000')] if _abi3 else [],
py_limited_api=_abi3,
),
],
options={'bdist_wheel': {'py_limited_api': 'cp311'} if _abi3 else {}},
)
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the existing PyPUG ABI compatibility section and the linked Python Limited API documentation, then review the setuptools and wheel concerns described in the issue. Done means a concrete, unified guide covering the three configuration knobs and explaining how to conditionally disable the Limited API for older Python releases.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100