pypa / pypa/packaging.python.org

Expand documentation on building for the Limited API

Open
#1,376 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

component: guides type: enhancement
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:

  1. Py_LIMITED_API, to hide non-stabilized symbols and potentially replace some macros with functions.
  2. The setuptools Extension(..., py_limited_api=True) flag, to use the correct filename for the extension module.
  3. The wheel py-limited-api option, 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

  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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.