Why does setuptools use the `d` ABI suffix for debug python builds?

[konstin]

setuptools version

setuptools==82.0.1, wheel==0.46.3, packaging==26.0

Python version

Python 3.12 debug (apt installed)

OS

Ubuntu 24.04

Additional environment information

n/a

Description

This report is due to astral-sh/uv#18769. I'm not sure if that's a bug in setuptools (and the uv side should support it), but it seems odd because it hasn't been reported except for setuptools now.

Is it intentional that setuptools uses the cp312d tag instead of the cp312 tag when building with a debug CPython, even through both have the same ABI since Python 3.8 (https://docs.python.org/3.10/using/configure.html#python-debug-build)?

Expected behavior

No separate debug tag.

How to Reproduce

pyproject.toml

[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

setup.py

from pathlib import Path

from setuptools import Extension, setup


setup(
    name="native-demo",
    version="0.1.0",
    description="Minimal source distribution with a native extension",
    long_description=(Path(__file__).parent / "README.md").read_text(encoding="utf-8"),
    long_description_content_type="text/markdown",
    package_dir={"": "src"},
    packages=["native_demo"],
    ext_modules=[
        Extension("native_demo._native", ["src/native_demo/_native.c"]),
    ],
    python_requires=">=3.8",
)

src/native_demo/init.py

from ._native import answer

__all__ = ["answer"]

src/native_demo/_native.c

#define PY_SSIZE_T_CLEAN
#include <Python.h>

static PyObject *answer(PyObject *self, PyObject *args) {
    return PyLong_FromLong(42);
}

static PyMethodDef native_methods[] = {
    {"answer", answer, METH_NOARGS, "Return a constant from native code."},
    {NULL, NULL, 0, NULL},
};

static struct PyModuleDef native_module = {
    PyModuleDef_HEAD_INIT,
    "_native",
    "Minimal native extension.",
    -1,
    native_methods,
};

PyMODINIT_FUNC PyInit__native(void) {
    return PyModule_Create(&native_module);
}

Output

$ uv build -p python3-dbg --wheel
Building wheel...
running egg_info
writing src/native_demo.egg-info/PKG-INFO
writing dependency_links to src/native_demo.egg-info/dependency_links.txt
writing top-level names to src/native_demo.egg-info/top_level.txt
reading manifest file 'src/native_demo.egg-info/SOURCES.txt'
writing manifest file 'src/native_demo.egg-info/SOURCES.txt'
running bdist_wheel
running build
running build_py
creating build/lib.linux-x86_64-cpython-312-pydebug/native_demo
copying src/native_demo/__init__.py -> build/lib.linux-x86_64-cpython-312-pydebug/native_demo
running build_ext
building 'native_demo._native' extension
creating build/temp.linux-x86_64-cpython-312-pydebug/src/native_demo
x86_64-linux-gnu-gcc -fno-strict-overflow -Wsign-compare -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -DDYNAMIC_ANNOTATIONS_ENABLED=1 -g -Og -Wall -fPIC -I/home/konsti/.cache/uv/builds-v0/.tmpqs2Ssf/include -I/usr/include/python3.12d -c src/native_demo/_native.c -o build/temp.linux-x86_64-cpython-312-pydebug/src/native_demo/_native.o
x86_64-linux-gnu-gcc -shared -Wl,-O1 -Wl,-Bsymbolic-functions -Wl,-Bsymbolic-functions -Wl,-z,relro build/temp.linux-x86_64-cpython-312-pydebug/src/native_demo/_native.o -L/usr/lib/x86_64-linux-gnu -o build/lib.linux-x86_64-cpython-312-pydebug/native_demo/_native.cpython-312d-x86_64-linux-gnu.so
installing to build/bdist.linux-x86_64/wheel
running install
running install_lib
creating build/bdist.linux-x86_64/wheel
creating build/bdist.linux-x86_64/wheel/native_demo
copying build/lib.linux-x86_64-cpython-312-pydebug/native_demo/_native.cpython-312d-x86_64-linux-gnu.so -> build/bdist.linux-x86_64/wheel/./native_demo
copying build/lib.linux-x86_64-cpython-312-pydebug/native_demo/__init__.py -> build/bdist.linux-x86_64/wheel/./native_demo
running install_egg_info
running egg_info
writing src/native_demo.egg-info/PKG-INFO
writing dependency_links to src/native_demo.egg-info/dependency_links.txt
writing top-level names to src/native_demo.egg-info/top_level.txt
reading manifest file 'src/native_demo.egg-info/SOURCES.txt'
writing manifest file 'src/native_demo.egg-info/SOURCES.txt'
Copying src/native_demo.egg-info to build/bdist.linux-x86_64/wheel/./native_demo-0.1.0-py3.12.egg-info
running install_scripts
creating build/bdist.linux-x86_64/wheel/native_demo-0.1.0.dist-info/WHEEL
creating '/home/konsti/projects/uv/debug/native_demo-0.1.0/dist/.tmp-mth783f7/native_demo-0.1.0-cp312-cp312d-linux_x86_64.whl' and adding 'build/bdist.linux-x86_64/wheel' to it
adding 'native_demo/__init__.py'
adding 'native_demo/_native.cpython-312d-x86_64-linux-gnu.so'
adding 'native_demo-0.1.0.dist-info/METADATA'
adding 'native_demo-0.1.0.dist-info/WHEEL'
adding 'native_demo-0.1.0.dist-info/top_level.txt'
adding 'native_demo-0.1.0.dist-info/RECORD'
removing build/bdist.linux-x86_64/wheel
Successfully built dist/native_demo-0.1.0-cp312-cp312d-linux_x86_64.whl

[abravalheri]

Isn't it compatible with this spec: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#abi-tag ?

[konstin]

I'm getting mixed signals from the spec, in some locations there's still the d examples, but there's https://docs.python.org/3.10/using/configure.html#python-debug-build which says the ABIs are the same. Could it be that Python 3.8 merged the ABIs, but the packaging docs were never updated, and this never showed up as a problem before cause most users build on regular Pythons anyway?

[abravalheri]

It could be, I am not sure, I was not involved in this implementation or in the change of the spec.

It seems that packaging may also be considering this as a valid tag: https://github.com/pypa/packaging/blob/26.0/src/packaging/tags.py#L188

So possibly the best conclusion we can reach is that, if there was a change in the spec, it does not seem that it defined in a clear cut way that append the d ABI flag was invalid when defining tags for the files?

[konstin]

Sorry for the noise, it turns out the CPython docs are misleading: python/cpython#146925