depr(python): Deprecate size parameter in parametric testing strate…

…gies in favor of `min_size`/`max_size` (#17128)

py-polars/polars/testing/parametric/strategies/core.py

@@ -35,7 +35,6 @@ def series(  # noqa: D417
     *,
     name: str | SearchStrategy[str] | None = None,
     dtype: PolarsDataType | None = None,
-    size: int | None = None,
     min_size: int = 0,
     max_size: int = _ROW_LIMIT,
     strategy: SearchStrategy[Any] | None = None,
@@ -57,9 +56,6 @@ def series(  # noqa: D417
         constructor name-param.
     dtype : PolarsDataType, optional
         a valid polars DataType for the resulting series.
-    size : int, optional
-        if set, creates a Series of exactly this size (ignoring min_size/max_size
-        params).
     min_size : int
         if not passing an exact size, can set a minimum here (defaults to 0).
         no-op if `size` is set.
@@ -84,6 +80,13 @@ def series(  # noqa: D417
         Additional keyword arguments that are passed to the underlying data generation
         strategies.
 
+    size : int, optional
+        if set, creates a Series of exactly this size (ignoring min_size/max_size
+        params).
+
+        .. deprecated:: 1.0.0
+            Use `min_size` and `max_size` instead.
+
     null_probability : float
         Percentage chance (expressed between 0.0 => 1.0) that any Series value is null.
         This is applied independently of any None values generated by the underlying
@@ -145,6 +148,12 @@ def series(  # noqa: D417
             version="0.20.26",
         )
         allow_chunks = chunked
+    if (size := kwargs.pop("size", None)) is not None:
+        issue_deprecation_warning(
+            "`size` is deprecated. Use `min_size` and `max_size` instead.",
+            version="1.0.0",
+        )
+        min_size = max_size = size
 
     if isinstance(allowed_dtypes, (DataType, DataTypeClass)):
         allowed_dtypes = [allowed_dtypes]
@@ -177,7 +186,9 @@ def series(  # noqa: D417
             )
         dtype = draw(dtype_strat)
 
-    if size is None:
+    if min_size == max_size:
+        size = min_size
+    else:
         size = draw(st.integers(min_value=min_size, max_value=max_size))
 
     if isinstance(name, st.SearchStrategy):
@@ -220,7 +231,6 @@ def dataframes(
     lazy: Literal[False] = ...,
     min_cols: int = 0,
     max_cols: int = _COL_LIMIT,
-    size: int | None = None,
     min_size: int = 0,
     max_size: int = _ROW_LIMIT,
     include_cols: Sequence[column] | column | None = None,
@@ -240,7 +250,6 @@ def dataframes(
     lazy: Literal[True],
     min_cols: int = 0,
     max_cols: int = _COL_LIMIT,
-    size: int | None = None,
     min_size: int = 0,
     max_size: int = _ROW_LIMIT,
     include_cols: Sequence[column] | column | None = None,
@@ -262,7 +271,6 @@ def dataframes(  # noqa: D417
     lazy: bool = False,
     min_cols: int = 1,
     max_cols: int = _COL_LIMIT,
-    size: int | None = None,
     min_size: int = 0,
     max_size: int = _ROW_LIMIT,
     include_cols: Sequence[column] | column | None = None,
@@ -288,9 +296,6 @@ def dataframes(  # noqa: D417
     max_cols : int, optional
         if not passing an exact size, can set a maximum value here (defaults to
         MAX_COLS).
-    size : int, optional
-        if set, will create a DataFrame of exactly this size (and ignore
-        the min_size/max_size len params).
     min_size : int, optional
         if not passing an exact size, set the minimum number of rows in the
         DataFrame.
@@ -316,6 +321,13 @@ def dataframes(  # noqa: D417
         Additional keyword arguments that are passed to the underlying data generation
         strategies.
 
+    size : int, optional
+        if set, will create a DataFrame of exactly this size (and ignore
+        the min_size/max_size len params).
+
+        .. deprecated:: 1.0.0
+            Use `min_size` and `max_size` instead.
+
     null_probability : {float, dict[str,float]}, optional
         percentage chance (expressed between 0.0 => 1.0) that a generated value is
         None. this is applied independently of any None values generated by the
@@ -374,7 +386,8 @@ def dataframes(  # noqa: D417
     ...         column("x", dtype=pl.Int32),
     ...         column("y", dtype=pl.Float64),
     ...     ],
-    ...     size=2,
+    ...     min_size=2,
+    ...     max_size=2,
     ... )
     >>> dfs.example()  # doctest: +SKIP
     shape: (2, 2)
@@ -401,6 +414,12 @@ def dataframes(  # noqa: D417
             version="0.20.26",
         )
         allow_chunks = chunked
+    if (size := kwargs.pop("size", None)) is not None:
+        issue_deprecation_warning(
+            "`size` is deprecated. Use `min_size` and `max_size` instead.",
+            version="1.0.0",
+        )
+        min_size = max_size = size
 
     if isinstance(include_cols, column):
         include_cols = [include_cols]
@@ -418,7 +437,9 @@ def dataframes(  # noqa: D417
     if include_cols:
         cols.extend(list(include_cols))
 
-    if size is None:
+    if min_size == max_size:
+        size = min_size
+    else:
         size = draw(st.integers(min_value=min_size, max_value=max_size))
 
     # Process columns
@@ -439,7 +460,8 @@ def dataframes(  # noqa: D417
                 series(
                     name=c.name,
                     dtype=c.dtype,
-                    size=size,
+                    min_size=size,
+                    max_size=size,
                     strategy=c.strategy,
                     allow_null=c.allow_null,  # type: ignore[arg-type]
                     allow_chunks=allow_series_chunks,

py-polars/tests/unit/testing/parametric/strategies/test_core.py

@@ -45,7 +45,7 @@ def test_series_dtype_enum(s: pl.Series) -> None:
     assert all(v in s.dtype.categories for v in s)
 
 
-@given(s=series(dtype=pl.Boolean, size=5))
+@given(s=series(dtype=pl.Boolean, min_size=5, max_size=5))
 @settings(max_examples=5)
 def test_series_size(s: pl.Series) -> None:
     assert s.len() == 5
@@ -87,7 +87,7 @@ def test_dataframes_lazy(lf: pl.LazyFrame) -> None:
     assert isinstance(lf, pl.LazyFrame)
 
 
-@given(df=dataframes(cols=3, size=5))
+@given(df=dataframes(cols=3, min_size=5, max_size=5))
 @settings(max_examples=5)
 def test_dataframes_size(df: pl.DataFrame) -> None:
     assert df.height == 5