name: str | SearchStrategy[str] | None = None,
dtype: PolarsDataType | None = None,
size: int | None = None,
min_size: int = 0,
max_size: int = 5,
strategy: SearchStrategy[Any] | None = None,
allow_null: bool = True,
allow_chunks: bool = True,
unique: bool = False,
allowed_dtypes: Collection[PolarsDataType] | PolarsDataType | None = None,
excluded_dtypes: Collection[PolarsDataType] | PolarsDataType | None = None,
allow_time_zones: bool = True,
**kwargs: Any,
) SearchStrategy[Series]#

Hypothesis strategy for producing Polars Series.

name{str, strategy}, optional

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

dtypePolarsDataType, optional

a valid polars DataType for the resulting series.

sizeint, optional

if set, creates a Series of exactly this size (ignoring min_size/max_size params).


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


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.


Allow nulls as possible values and allow the Null data type by default.


Allow the Series to contain multiple chunks.

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.


Allow generating Datetime Series with a time zone.


Additional keyword arguments that are passed to the underlying data generation strategies.


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 strategy.

Deprecated since version 0.20.26: Use allow_null instead.

allow_infinitiesbool, optional

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

Deprecated since version 0.20.26: Use allow_infinity instead.


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.


The strategy is generally used to generate series in a unit test:

>>> from polars.testing.parametric import series
>>> from hypothesis import given
>>> @given(s=series(min_size=3, max_size=5))
... def test_series_len(s: pl.Series) -> None:
...     assert 3 <= s.len() <= 5

Drawing examples interactively is also possible with the .example() method. This should be avoided while running tests.

>>> from polars.testing.parametric import lists
>>> s = series(strategy=lists(pl.String, select_from=["xx", "yy", "zz"]))
>>> s.example()  
shape: (4,)
Series: '' [list[str]]
        ["zz", "zz"]
        ["zz", "xx", "yy"]