Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Expand documentation on building for the Limited API #1376

Open
bgilbert opened this issue Nov 11, 2023 · 0 comments
Open

Expand documentation on building for the Limited API #1376

bgilbert opened this issue Nov 11, 2023 · 0 comments
Labels
component: guides type: enhancement A self-contained enhancement or new feature

Comments

@bgilbert
Copy link

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: Document py-limited-api option wheel#583

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 {}},
)
@chrysle chrysle added type: enhancement A self-contained enhancement or new feature component: guides labels Nov 11, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
component: guides type: enhancement A self-contained enhancement or new feature
Projects
None yet
Development

No branches or pull requests

3 participants
@bgilbert @chrysle and others