[python-package] support Python 3.13 (#6668)

* [python-package] support Python 3.13

* update everything in the base conda environment, not just conda

* python packages now use 'cp' instead of 'cpython'

* fix python_package

* get more logs

* try to force a better solver error

* merge latest

* use build= explicitly

* restore all CI, revert debugging changes

* Update .ci/test.sh

* empty commit to re-trigger CI

* update docs conda env

* pin to specific OS and mambaforge

* Update .github/workflows/python_package.yml

Co-authored-by: Nikita Titov <nekit94-08@mail.ru>

* update default Python version in .vsts-ci.yml

* remove upper-version pins

* update RTD image

---------

Co-authored-by: Nikita Titov <nekit94-08@mail.ru>

Author: jameslamb

.ci/test-windows.ps1

@@ -66,7 +66,7 @@ if ($env:TASK -eq "swig") {
 conda init powershell
 conda activate
 conda config --set always_yes yes --set changeps1 no
-conda update -q -y conda "python=$env:PYTHON_VERSION[build=*cpython]"
+conda update -q -y conda "python=$env:PYTHON_VERSION[build=*_cp*]"
 
 if ($env:PYTHON_VERSION -eq "3.7") {
     $env:CONDA_REQUIREMENT_FILE = "$env:BUILD_SOURCESDIRECTORY/.ci/conda-envs/ci-core-py37.txt"
@@ -80,7 +80,7 @@ $condaParams = @(
     "-y",
     "-n", "$env:CONDA_ENV",
     "--file", "$env:CONDA_REQUIREMENT_FILE",
-    "python=$env:PYTHON_VERSION[build=*cpython]"
+    "python=$env:PYTHON_VERSION[build=*_cp*]"
 )
 conda create @condaParams ; Assert-Output $?
 

.ci/test.sh

@@ -64,8 +64,9 @@ if [[ "$TASK" == "cpp-tests" ]]; then
     exit 0
 fi
 
-# including python=version[build=*cpython] to ensure that conda doesn't fall back to pypy
-CONDA_PYTHON_REQUIREMENT="python=${PYTHON_VERSION}[build=*cpython]"
+# including python=version=[build=*_cp*] to ensure that conda prefers CPython and doesn't fall back to
+# other implementations like pypy
+CONDA_PYTHON_REQUIREMENT="python=${PYTHON_VERSION}[build=*_cp*]"
 
 if [[ $TASK == "if-else" ]]; then
     conda create -q -y -n "${CONDA_ENV}" "${CONDA_PYTHON_REQUIREMENT}" numpy

.github/workflows/cuda.yml

@@ -81,19 +81,19 @@ jobs:
         include:
           - method: wheel
             compiler: gcc
-            python_version: "3.10"
+            python_version: "3.11"
             cuda_version: "12.6.1"
             linux_version: "ubuntu22.04"
             task: cuda
           - method: source
             compiler: gcc
-            python_version: "3.12"
+            python_version: "3.13"
             cuda_version: "12.2.2"
             linux_version: "ubuntu22.04"
             task: cuda
           - method: pip
             compiler: clang
-            python_version: "3.11"
+            python_version: "3.12"
             cuda_version: "11.8.0"
             linux_version: "ubuntu20.04"
             task: cuda

.github/workflows/linkchecker.yml

@@ -10,7 +10,7 @@ on:
 env:
   COMPILER: gcc
   OS_NAME: 'linux'
-  PYTHON_VERSION: '3.12'
+  PYTHON_VERSION: '3.13'
   TASK: 'check-links'
 
 jobs:

.github/workflows/python_package.yml

@@ -28,32 +28,32 @@ jobs:
         include:
           - os: macos-13
             task: regular
-            python_version: '3.10'
+            python_version: '3.11'
           - os: macos-13
             task: sdist
-            python_version: '3.11'
+            python_version: '3.12'
           - os: macos-13
             task: bdist
-            python_version: '3.8'
+            python_version: '3.9'
           - os: macos-13
             task: if-else
-            python_version: '3.9'
+            python_version: '3.10'
           - os: macos-14
             task: bdist
             method: wheel
-            python_version: '3.10'
+            python_version: '3.11'
           - os: macos-13
             task: mpi
             method: source
-            python_version: '3.11'
+            python_version: '3.12'
           - os: macos-13
             task: mpi
             method: pip
-            python_version: '3.12'
+            python_version: '3.13'
           - os: macos-13
             task: mpi
             method: wheel
-            python_version: '3.9'
+            python_version: '3.10'
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -113,12 +113,19 @@ jobs:
             --rm \
             -v $(pwd):/opt/lgb-build \
             -w /opt/lgb-build \
-            python:3.12 \
+            python:3.13 \
             /bin/bash ./.ci/test-python-latest.sh
-  test-oldest-versions:
+  test-old-versions:
     name: Python - oldest supported versions (ubuntu-latest)
     runs-on: ubuntu-latest
     timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        # end-of-life Python versions
+        python_version:
+          - '3.7'
+          - '3.8'
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -140,12 +147,12 @@ jobs:
             --rm \
             -v $(pwd):/opt/lgb-build \
             -w /opt/lgb-build \
-            python:3.7 \
+            python:${{ matrix.python_version }} \
             /bin/bash ./.ci/test-python-oldest.sh
   all-python-package-jobs-successful:
     if: always()
     runs-on: ubuntu-latest
-    needs: [test, test-latest-versions, test-oldest-versions]
+    needs: [test, test-latest-versions, test-old-versions]
     steps:
       - name: Note that all tests succeeded
         uses: re-actors/alls-green@v1.2.2

.github/workflows/static_analysis.yml

@@ -19,7 +19,7 @@ env:
   COMPILER: 'gcc'
   MAKEFLAGS: '-j4'
   OS_NAME: 'linux'
-  PYTHON_VERSION: '3.12'
+  PYTHON_VERSION: '3.13'
 
 jobs:
   test:

.readthedocs.yaml

@@ -1,8 +1,8 @@
 version: 2
 build:
-  os: "ubuntu-20.04"
+  os: "ubuntu-24.04"
   tools:
-    python: "miniconda3-4.7"
+    python: "mambaforge-23.11"
 conda:
   environment: docs/env.yml
 formats:

.vsts-ci.yml

@@ -10,7 +10,7 @@ pr:
 variables:
   AZURE: 'true'
   CMAKE_BUILD_PARALLEL_LEVEL: 4
-  PYTHON_VERSION: '3.12'
+  PYTHON_VERSION: '3.13'
   runCodesignValidationInjection: false
   skipComponentGovernanceDetection: true
   Codeql.Enabled: false
@@ -96,19 +96,19 @@ jobs:
       matrix:
         regular:
           TASK: regular
-          PYTHON_VERSION: '3.10'
+          PYTHON_VERSION: '3.11'
         sdist:
           TASK: sdist
-          PYTHON_VERSION: '3.8'
+          PYTHON_VERSION: '3.9'
         bdist:
           TASK: bdist
-          PYTHON_VERSION: '3.9'
+          PYTHON_VERSION: '3.10'
         inference:
           TASK: if-else
         mpi_source:
           TASK: mpi
           METHOD: source
-          PYTHON_VERSION: '3.9'
+          PYTHON_VERSION: '3.10'
         gpu_source:
           TASK: gpu
           METHOD: source
@@ -162,7 +162,7 @@ jobs:
           TASK: sdist
         bdist:
           TASK: bdist
-          PYTHON_VERSION: '3.10'
+          PYTHON_VERSION: '3.11'
         inference:
           TASK: if-else
         mpi_source:
@@ -171,23 +171,23 @@ jobs:
         mpi_pip:
           TASK: mpi
           METHOD: pip
-          PYTHON_VERSION: '3.11'
+          PYTHON_VERSION: '3.12'
         mpi_wheel:
           TASK: mpi
           METHOD: wheel
-          PYTHON_VERSION: '3.9'
+          PYTHON_VERSION: '3.10'
         gpu_source:
           TASK: gpu
           METHOD: source
-          PYTHON_VERSION: '3.11'
+          PYTHON_VERSION: '3.12'
         gpu_pip:
           TASK: gpu
           METHOD: pip
-          PYTHON_VERSION: '3.10'
+          PYTHON_VERSION: '3.11'
         gpu_wheel:
           TASK: gpu
           METHOD: wheel
-          PYTHON_VERSION: '3.9'
+          PYTHON_VERSION: '3.10'
         cpp_tests:
           TASK: cpp-tests
           METHOD: with-sanitizers
@@ -298,10 +298,10 @@ jobs:
       matrix:
         regular:
           TASK: regular
-          PYTHON_VERSION: '3.10'
+          PYTHON_VERSION: '3.11'
         sdist:
           TASK: sdist
-          PYTHON_VERSION: '3.9'
+          PYTHON_VERSION: '3.10'
         bdist:
           TASK: bdist
         swig:
@@ -347,10 +347,10 @@ jobs:
       matrix:
         regular:
           TASK: regular
-          PYTHON_VERSION: '3.10'
+          PYTHON_VERSION: '3.11'
         sdist:
           TASK: sdist
-          PYTHON_VERSION: '3.9'
+          PYTHON_VERSION: '3.10'
         bdist:
           TASK: bdist
         swig:

docs/README.rst

@@ -35,7 +35,7 @@ Run the following from the root of this repository to pull the relevant image an
         --env READTHEDOCS=true \
         --workdir=/opt/LightGBM/docs \
         --entrypoint="" \
-        readthedocs/build:ubuntu-20.04-2021.09.23 \
+        readthedocs/build:ubuntu-24.04-2024.06.17 \
         /bin/bash build-docs.sh
 
 When that code completes, open ``docs/_build/html/index.html`` in your browser.

docs/env.yml

@@ -4,15 +4,15 @@ channels:
   - conda-forge
 dependencies:
   - breathe>=4.35
-  - python=3.10
-  - r-base=4.3.2
-  - r-data.table=1.14.10
-  - r-jsonlite=1.8.8
-  - r-knitr=1.45
-  - r-markdown=1.12
-  - r-matrix=1.6_4
-  - r-pkgdown=2.0.7
+  - python=3.12
+  - r-base>=4.3.3
+  - r-data.table=1.16.4
+  - r-jsonlite=1.8.9
+  - r-knitr=1.49
+  - r-markdown=1.13
+  - r-matrix=1.6_5
+  - r-pkgdown=2.1.1
   - r-roxygen2=7.3.2
-  - scikit-learn>=1.4.0
-  - sphinx>=6.0
-  - sphinx_rtd_theme>=2.0
+  - scikit-learn>=1.6.1
+  - sphinx>=8.1.3
+  - sphinx_rtd_theme>=3.0.1

python-package/pyproject.toml

@@ -16,6 +16,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering :: Artificial Intelligence"
 ]
 dependencies = [