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