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 | 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: Collection[PolarsDataType] | PolarsDataType | None = None,
excluded_dtypes: Collection[PolarsDataType] | PolarsDataType | None = None,
) SearchStrategy[Series][source]#

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

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.parametric import series
>>> from hypothesis import given

In normal usage, as a simple unit test:

>>> @given(s=series(null_probability=0.1))
... def test_repr_is_valid_string(s: pl.Series) -> None:
...     assert isinstance(repr(s), str)

Experimenting locally with a custom List dtype strategy:

>>> from polars.testing.parametric import create_list_strategy
>>> s = series(
...     strategy=create_list_strategy(
...         inner_dtype=pl.Utf8,
...         select_from=["xx", "yy", "zz"],
...     ),
...     min_size=2,
...     max_size=4,
... )
>>> s.example()  
shape: (4,)
Series: '' [list[str]]
[
    []
    ["yy", "yy", "zz"]
    ["zz", "yy", "zz"]
    ["xx"]
]