depr(python): Rename LazyFrame.read/write_json to de/serialize

py-polars/polars/lazyframe/frame.py

@@ -55,6 +55,7 @@
 from polars.utils._wrap import wrap_df, wrap_expr
 from polars.utils.convert import _timedelta_to_pl_duration
 from polars.utils.deprecation import (
+    deprecate_renamed_methods,
     deprecate_renamed_parameter,
     issue_deprecation_warning,
 )
@@ -110,6 +111,16 @@
     P = ParamSpec("P")
 
 
+@deprecate_renamed_methods(
+    {
+        "read_json": "deserialize",
+        "write_json": "serialize",
+    },
+    versions={
+        "read_json": "0.18.12",
+        "write_json": "0.18.12",
+    },
+)
 class LazyFrame:
     """
     Representation of a Lazy computation graph/query against a DataFrame.
@@ -529,15 +540,15 @@ def from_json(cls, json: str) -> Self:
 
         See Also
         --------
-        read_json
+        deserialize
 
         """
         bytes = StringIO(json).getvalue().encode()
         file = BytesIO(bytes)
-        return cls._from_pyldf(PyLazyFrame.read_json(file))
+        return cls._from_pyldf(PyLazyFrame.deserialize(file))
 
     @classmethod
-    def read_json(cls, file: str | Path | IOBase) -> Self:
+    def deserialize(cls, file: str | Path | IOBase) -> Self:
         """
         Read a logical plan from a JSON file to construct a LazyFrame.
 
@@ -548,15 +559,15 @@ def read_json(cls, file: str | Path | IOBase) -> Self:
 
         See Also
         --------
-        LazyFrame.from_json, LazyFrame.write_json
+        LazyFrame.from_json, LazyFrame.serialize
 
         """
         if isinstance(file, StringIO):
             file = BytesIO(file.getvalue().encode())
         elif isinstance(file, (str, Path)):
             file = normalise_filepath(file)
 
-        return cls._from_pyldf(PyLazyFrame.read_json(file))
+        return cls._from_pyldf(PyLazyFrame.deserialize(file))
 
     @property
     def columns(self) -> list[str]:
@@ -703,16 +714,16 @@ def _repr_html_(self) -> str:
 """
 
     @overload
-    def write_json(self, file: None = ...) -> str:
+    def serialize(self, file: None = ...) -> str:
         ...
 
     @overload
-    def write_json(self, file: IOBase | str | Path) -> None:
+    def serialize(self, file: IOBase | str | Path) -> None:
         ...
 
-    def write_json(self, file: IOBase | str | Path | None = None) -> str | None:
+    def serialize(self, file: IOBase | str | Path | None = None) -> str | None:
         """
-        Write the logical plan of this LazyFrame to a file or string in JSON format.
+        Serialize the logical plan of this LazyFrame to a file or string in JSON format.
 
         Parameters
         ----------
@@ -722,7 +733,7 @@ def write_json(self, file: IOBase | str | Path | None = None) -> str | None:
 
         See Also
         --------
-        LazyFrame.read_json
+        LazyFrame.deserialize
 
         Examples
         --------
@@ -732,7 +743,7 @@ def write_json(self, file: IOBase | str | Path | None = None) -> str | None:
         ...         "bar": [6, 7, 8],
         ...     }
         ... )
-        >>> lf.write_json()
+        >>> lf.serialize()
         '{"DataFrameScan":{"df":{"columns":[{"name":"foo","datatype":"Int64","values":[1,2,3]},{"name":"bar","datatype":"Int64","values":[6,7,8]}]},"schema":{"inner":{"foo":"Int64","bar":"Int64"}},"output_schema":null,"projection":null,"selection":null}}'
 
         """
@@ -741,7 +752,7 @@ def write_json(self, file: IOBase | str | Path | None = None) -> str | None:
         to_string_io = (file is not None) and isinstance(file, StringIO)
         if file is None or to_string_io:
             with BytesIO() as buf:
-                self._ldf.write_json(buf)
+                self._ldf.serialize(buf)
                 json_bytes = buf.getvalue()
 
             json_str = json_bytes.decode("utf8")
@@ -750,7 +761,7 @@ def write_json(self, file: IOBase | str | Path | None = None) -> str | None:
             else:
                 return json_str
         else:
-            self._ldf.write_json(file)
+            self._ldf.serialize(file)
         return None
 
     def pipe(

py-polars/src/lazyframe.rs

@@ -84,7 +84,7 @@ impl PyLazyFrame {
     }
 
     #[cfg(all(feature = "json", feature = "serde_json"))]
-    fn write_json(&self, py_f: PyObject) -> PyResult<()> {
+    fn serialize(&self, py_f: PyObject) -> PyResult<()> {
         let file = BufWriter::new(get_file_like(py_f, true)?);
         serde_json::to_writer(file, &self.ldf.logical_plan)
             .map_err(|err| PyValueError::new_err(format!("{err:?}")))?;
@@ -93,7 +93,7 @@ impl PyLazyFrame {
 
     #[staticmethod]
     #[cfg(feature = "json")]
-    fn read_json(py_f: PyObject) -> PyResult<Self> {
+    fn deserialize(py_f: PyObject) -> PyResult<Self> {
         // it is faster to first read to memory and then parse: https://github.com/serde-rs/json/issues/160
         // so don't bother with files.
         let mut json = String::new();
@@ -105,7 +105,7 @@ impl PyLazyFrame {
         // we skipped the serializing/deserializing of the static in lifetime in `DataType`
         // so we actually don't have a lifetime at all when serializing.
 
-        // &str still has a lifetime. Bit its ok, because we drop it immediately
+        // &str still has a lifetime. But it's ok, because we drop it immediately
         // in this scope
         let json = unsafe { std::mem::transmute::<&'_ str, &'static str>(json.as_str()) };
 

py-polars/tests/unit/test_serde.py

@@ -15,9 +15,18 @@ def test_pickling_simple_expression() -> None:
     assert str(pickle.loads(buf)) == str(e)
 
 
-def test_serde_lazy_frame_lp() -> None:
+def test_lazyframe_serde_lp() -> None:
     lf = pl.DataFrame({"a": [1, 2, 3], "b": ["a", "b", "c"]}).lazy().select(pl.col("a"))
-    json = lf.write_json()
+    json = lf.serialize()
+
+    result = pl.LazyFrame.from_json(json).collect().to_series()
+    assert_series_equal(result, pl.Series("a", [1, 2, 3]))
+
+
+def test_lazyframe_deprecated_write_json() -> None:
+    lf = pl.DataFrame({"a": [1, 2, 3], "b": ["a", "b", "c"]}).lazy().select(pl.col("a"))
+    with pytest.deprecated_call():
+        json = lf.write_json()
 
     result = pl.LazyFrame.from_json(json).collect().to_series()
     assert_series_equal(result, pl.Series("a", [1, 2, 3]))