polars.testing.parametric.series

polars.testing.parametric.series(

*,

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.

Parameters:

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

min_sizeint

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

max_sizeint

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_nullbool

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

allow_chunksbool

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_time_zones

Allow generating Datetime Series with a time zone.

**kwargs

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

null_probabilityfloat

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.

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

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"]
        []
        ["xx"]
]