polars.testing.series

polars.testing.series(*, name: str | SearchStrategy[str] | None = None, dtype: PolarsDataType | None = None, size: int | None = None, min_size: int | None = 0, max_size: int | None = 20, strategy: SearchStrategy[object] | None = None, null_probability: float = 0.0, unique: bool = False, allowed_dtypes: Sequence[PolarsDataType] | None = None, excluded_dtypes: Sequence[PolarsDataType] | None = None) → SearchStrategy[pli.Series]

Strategy for producing a polars Series.

Parameters

name{str, strategy}, optional

literal string or a strategy for strings (or None), passed to the Series constructor name-param.

dtypedtype, optional

a valid polars DataType for the resulting series.

sizeint, optional

if set, will create a Series of exactly this size (and ignore min/max len params).

min_sizeint, optional

if not passing an exact size, can set a minimum here (defaults to 0). no-op if size is set.

max_sizeint, optional

if not passing an exact size, can set a maximum value here (defaults to MAX_DATA_SIZE). no-op if size is set.

strategystrategy, optional

supports overriding the default strategy for the given dtype.

null_probabilityfloat, 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 underlying strategy.

uniquebool, optional

indicate whether Series values should all be distinct.

allowed_dtypes{list,set}, optional

when automatically generating Series data, allow only these dtypes.

excluded_dtypes{list,set}, optional

when automatically generating Series data, exclude these dtypes.

Notes

In actual usage this is deployed as a unit test decorator, providing a strategy that generates multiple Series with the given dtype/size characteristics for the unit test. While developing a strategy/test, it can also be useful to call .example() directly on a given strategy to see concrete instances of the generated data.

Examples

>>> from polars.testing import series
>>> from hypothesis import given
>>>
>>> @given(df=series())
... def test_repr(s: pl.Series) -> None:
...     assert isinstance(repr(s), str)
>>>
>>> s = series(dtype=pl.Int32, max_size=5)
>>> s.example()  
shape: (4,)
Series: '' [i64]
[
    54666
    -35
    6414
    -63290
]