polars.testing.parametric.series(*, name: str | SearchStrategy[str] | None = None, dtype: PolarsDataType | None = None, size: int | None = None, min_size: int | None = 0, max_size: int | None = 10, strategy: SearchStrategy[object] | None = None, null_probability: float = 0.0, allow_infinities: bool = True, unique: bool = False, chunked: bool | None = None, allowed_dtypes: Sequence[PolarsDataType] | None = None, excluded_dtypes: Sequence[PolarsDataType] | None = None) SearchStrategy[Series][source]#

Strategy for producing a polars Series.

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, creates a Series of exactly this size (ignoring min/max 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.

allow_infinitiesbool, optional

optionally disallow generation of +/-inf values for floating-point dtypes.

uniquebool, optional

indicate whether Series values should all be distinct.

chunkedbool, optional

ensure that Series with more than one element have n_chunks > 1. if omitted, chunking is applied at random.

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.


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.


>>> from polars.testing.parametric 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]