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,
- unique: bool = False,
- allowed_dtypes: Collection[PolarsDataType] | PolarsDataType | None = None,
- excluded_dtypes: Collection[PolarsDataType] | PolarsDataType | None = None,
- allow_time_zones: bool = True,
- **kwargs: Any,
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.
- 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
andmax_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"] ]