fix(core): write use_polars_sort to Ray DatasetContext (fixes #354)

Ray 2.55 deprecated `DatasetContext.use_polars` in favor of
`use_polars_sort`. Writing the old attribute on every
`RayDataExecutionOptions.apply()` / `apply_remote()` emitted a
DeprecationWarning on every materialization.

Add `use_polars_sort` as the canonical field and keep `use_polars`
as a deprecated alias that forwards its value and warns once at
construction, preserving the existing API. `apply()` now writes
`ctx.use_polars_sort` only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: geoHeil

docs/changelog.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## Unreleased
+
+### :bug: Bug Fixes
+
+- avoid Ray 2.55 `DatasetContext.use_polars` DeprecationWarning on every `RayDataExecutionOptions.apply()` by writing to `use_polars_sort` ([#354](https://github.com/danielgafni/dagster-ray/issues/354))
+
+### :hammer_and_wrench: Other Improvements
+
+- add `RayDataExecutionOptions.use_polars_sort`; keep `use_polars` as a deprecated alias that forwards its value and emits a `DeprecationWarning`
+
 ## v0.4.4 (26-03-2026)
 
 ### :sparkles: Features

src/dagster_ray/configs.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
+import warnings
 from collections.abc import Mapping
 from typing import Any, Literal
 
 import dagster as dg
-from pydantic import Field
+from pydantic import Field, model_validator
 
 USER_DEFINED_RAY_KEY = "dagster-ray/config"
 DAGSTER_RAY_NAMESPACES_ENV_VAR = "DAGSTER_RAY_NAMESPACES"
@@ -77,7 +78,31 @@ class RayDataExecutionOptions(dg.Config):
     cpu_limit: int = 5000
     gpu_limit: int = 0
     verbose_progress: bool = True
-    use_polars: bool = True
+    use_polars_sort: bool = Field(
+        default=True,
+        description="Whether to use Polars for sort operations in Ray Data. Forwarded to `ray.data.DatasetContext.use_polars_sort`.",
+    )
+    use_polars: bool | None = Field(
+        default=None,
+        description="Deprecated. Use `use_polars_sort` instead. Ray 2.55 renamed the underlying `DatasetContext` attribute to `use_polars_sort`.",
+        deprecated="`use_polars` is deprecated; use `use_polars_sort` instead.",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _forward_deprecated_use_polars(cls, data: Any) -> Any:
+        if not isinstance(data, dict) or data.get("use_polars") is None:
+            return data
+        warnings.warn(
+            "`use_polars` is deprecated; use `use_polars_sort` instead. "
+            "The value has been forwarded to `use_polars_sort`.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        # Prefer an explicit `use_polars_sort`; otherwise forward the deprecated value.
+        # Keep `use_polars` on the instance so existing read access keeps working.
+        data = {**data, "use_polars_sort": data.get("use_polars_sort", data["use_polars"])}
+        return data
 
     def apply(self):
         import ray
@@ -92,7 +117,7 @@ def apply(self):
         )
 
         ctx.verbose_progress = self.verbose_progress
-        ctx.use_polars = self.use_polars
+        ctx.use_polars_sort = self.use_polars_sort
 
     def apply_remote(self):
         import ray

tests/test_configs.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import warnings
+
+import pytest
+
+from dagster_ray.configs import RayDataExecutionOptions
+
+
+def test_use_polars_sort_defaults_to_true():
+    opts = RayDataExecutionOptions()
+    assert opts.use_polars_sort is True
+    assert opts.use_polars is None
+
+
+def test_deprecated_use_polars_is_forwarded_to_use_polars_sort():
+    with pytest.warns(DeprecationWarning, match="use_polars_sort"):
+        opts = RayDataExecutionOptions(use_polars=False)
+    assert opts.use_polars_sort is False
+    # read-back of the deprecated attribute is preserved for backward compatibility
+    assert opts.use_polars is False
+
+
+def test_explicit_use_polars_sort_wins_over_deprecated_alias():
+    with pytest.warns(DeprecationWarning):
+        opts = RayDataExecutionOptions(use_polars=True, use_polars_sort=False)
+    assert opts.use_polars_sort is False
+
+
+def test_use_polars_sort_alone_does_not_warn_on_construction():
+    # Construction with only the new field must not emit our deprecation warning.
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        opts = RayDataExecutionOptions(use_polars_sort=False)
+    ours = [w for w in caught if "use_polars_sort" in str(w.message) and "deprecated" in str(w.message).lower()]
+    assert ours == []
+    assert opts.use_polars_sort is False