[python-package] Add categorical support for Polars/Arrow via Narwhals

.ci/conda-envs/ci-core.txt

@@ -21,7 +21,7 @@ cffi>=1.16
 dask>=2025.4.0
 joblib>=1.3.2
 matplotlib-base>=3.7.3
-narwhals>=1.15
+narwhals>=2.11
 numpy>=1.24.4
 pandas>2.0
 polars>=1.0.0

.ci/pip-envs/requirements-oldest.txt

@@ -6,7 +6,7 @@
 # see https://devguide.python.org/versions/
 #
 cffi==1.15.1
-narwhals==1.15.0
+narwhals==2.11.0
 numpy==1.22.4
 pandas==1.3.4
 polars==1.0.0

.pre-commit-config.yaml

@@ -106,7 +106,7 @@ repos:
         verbose: true
         additional_dependencies:
           - matplotlib>=3.9.1
-          - narwhals>=1.15
+          - narwhals>=2.11
           - pandas>=2.0
           - scikit-learn>=1.5.2
   - repo: https://github.com/zizmorcore/zizmor-pre-commit

docs/Advanced-Topics.rst

@@ -23,12 +23,12 @@ Categorical Feature Support
 -  Use ``categorical_feature`` to specify the categorical features.
    Refer to the parameter ``categorical_feature`` in `Parameters <./Parameters.rst#categorical_feature>`__.
 
--  Categorical features will be cast to ``int32`` (integer codes will be extracted from pandas categoricals in the Python-package) so they must be encoded as non-negative integers (negative values will be treated as missing)
+-  Categorical features will be cast to ``int32`` (integer codes will be extracted from categorical or enum dtypes in the Python-package) so they must be encoded as non-negative integers (negative values will be treated as missing)
    less than ``Int32.MaxValue`` (2147483647).
    It is best to use a contiguous range of integers started from zero.
    Floating point numbers in categorical features will be rounded towards 0.
 
--  When using ``pandas.DataFrame`` inputs with columns of dtype ``category``, LightGBM will
+-  For dataframe inputs with categorical or enum dtypes, LightGBM will
    align categories to those observed during training before converting them to integer values.
    This ensures consistent encoding between training and prediction without additional preprocessing.
 

docs/Parameters.rst

@@ -949,7 +949,7 @@ Dataset Parameters
 
    -  add a prefix ``name:`` for column name, e.g. ``categorical_feature=name:c1,c2,c3`` means c1, c2 and c3 are categorical features
 
-   -  **Note**: all values will be cast to ``int32`` (integer codes will be extracted from pandas categoricals in the Python-package)
+   -  **Note**: all values will be cast to ``int32`` (integer codes will be extracted from categorical or enum dtypes in the Python-package)
 
    -  **Note**: index starts from ``0`` and it doesn't count the label column when passing type is ``int``
 

include/LightGBM/config.h

@@ -784,7 +784,7 @@ struct Config {
   // desc = used to specify categorical features
   // desc = use number for index, e.g. ``categorical_feature=0,1,2`` means column\_0, column\_1 and column\_2 are categorical features
   // desc = add a prefix ``name:`` for column name, e.g. ``categorical_feature=name:c1,c2,c3`` means c1, c2 and c3 are categorical features
-  // desc = **Note**: all values will be cast to ``int32`` (integer codes will be extracted from pandas categoricals in the Python-package)
+  // desc = **Note**: all values will be cast to ``int32`` (integer codes will be extracted from categorical or enum dtypes in the Python-package)
   // desc = **Note**: index starts from ``0`` and it doesn't count the label column when passing type is ``int``
   // desc = **Note**: all values should be less than ``Int32.MaxValue`` (2147483647)
   // desc = **Note**: using large values could be memory consuming. Tree decision rule works best when categorical features are presented by consecutive integers starting from zero

pixi.toml

@@ -4,7 +4,7 @@ name = "lightgbm"
 platforms = ["linux-64", "linux-aarch64", "osx-64", "osx-arm64", "win-64"]
 
 [dependencies]
-narwhals = ">=1.15"
+narwhals = ">=2.11"
 numpy = ">=1.21.3"
 pip = "*"
 python = ">=3.10"
@@ -15,7 +15,7 @@ scipy = "*"
 cffi = "1.15.*"
 joblib = "1.3.*"
 matplotlib-base = "3.7.*"
-narwhals = "1.15.*"
+narwhals = "2.11.*"
 numpy = "1.22.*"
 pandas = "1.3.*"
 polars = "1.0.*"