polars.testing.parametric.series

polars.testing.parametric.series(
    *,
    name: str | SearchStrategy[str] | None = None,
    dtype: PolarsDataType | None = None,
    min_size: int = 0,
    max_size: int = 5,
    strategy: SearchStrategy[Any] | None = None,
    allow_null: bool = True,
    allow_chunks: bool = True,
    allow_masked_out: 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[ForwardRef('Series')]

Hypothesis strategy for producing Polars Series.

Warning

This functionality is currently considered unstable. It may be changed at any point without it being considered a breaking change.

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.

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.

allow_masked_outbool

Allow the nulls to contain masked out elements.

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.

sizeint, optional

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

Deprecated since version 1.0.0: Use min_size and max_size instead.

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