Bug Report: NumPy Build Failure on Python 3.12 Due to Missing `distutils`

[rahlk]

Summary

Installation fails on Python 3.12.5 when trying to build numpy==1.23.5 due to the removal of distutils from the Python standard library in Python 3.12. The package manager attempts to build an older version of NumPy that depends on distutils, which is no longer available.

Environment

• Python Version: CPython 3.12.5
• Operating System: macOS (using pyenv)
• Package Manager: uv
• Project Version: codeanalyzer-python v0.1.10

Error Details

× Failed to build `numpy==1.23.5`
├─▶ The build backend returned an error
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)

    [stderr]
    Traceback (most recent call last):
      File "<string>", line 8, in <module>
      File "/Users/sinhas/.cache/uv/builds-v0/.tmp0bq7uK/lib/python3.12/site-packages/setuptools/__init__.py", line 10, in <module>
        import distutils.core
    ModuleNotFoundError: No module named 'distutils'

    hint: `distutils` was removed from the standard library in Python 3.12. Consider adding a constraint (like `numpy >1.23.5`) to avoid building a version of `numpy` that depends on `distutils`.
help: `numpy` (v1.23.5) was included because `codeanalyzer-python` (v0.1.10) depends on `numpy`

Root Cause

The current dependency specification in pyproject.toml allows NumPy versions that are incompatible with Python 3.12:

# Current specification
"numpy>=1.21.0,<1.24.0; python_version < '3.11'",
"numpy>=1.24.0,<2.0.0; python_version >= '3.11'",

The issue is that Python 3.12 falls under the python_version >= '3.11' condition, but NumPy versions 1.24.0 and below still depend on distutils, which was removed in Python 3.12.

Proposed Solution

Update the NumPy dependency constraints in pyproject.toml to handle Python 3.12 specifically:

# Updated specification
"numpy>=1.21.0,<1.24.0; python_version < '3.11'",
"numpy>=1.24.0,<2.0.0; python_version >= '3.11' and python_version < '3.12'",
"numpy>=1.26.0,<2.0.0; python_version >= '3.12'",

Alternative Solutions

1. Pin to a specific NumPy version: Use numpy>=1.26.0 for Python 3.12+ since NumPy 1.26.0+ officially supports Python 3.12
2. Add upper bound for Python version: Consider adding python_version < '3.12' to the existing constraint
3. Install distutils separately: Add setuptools as a dependency, though this is not recommended as a long-term solution

Steps to Reproduce

1. Use Python 3.12.5
2. Clone the repository
3. Run uv sync or similar package installation command
4. Observe the NumPy build failure

Impact

• Prevents installation on Python 3.12
• Affects users trying to use the latest Python version
• May affect CI/CD pipelines running on Python 3.12

References

• NumPy Python 3.12 Support
• PEP 632: Deprecate distutils module
• Python 3.12 What's New - Removed Modules