diff --git a/py-polars/polars/functions/lazy.py b/py-polars/polars/functions/lazy.py index afd8e7d127d50..6aa675f444cc5 100644 --- a/py-polars/polars/functions/lazy.py +++ b/py-polars/polars/functions/lazy.py @@ -17,7 +17,7 @@ deprecate_renamed_function, issue_deprecation_warning, ) -from polars.utils.unstable import unstable +from polars.utils.unstable import issue_unstable_warning, unstable with contextlib.suppress(ImportError): # Module not available when building docs import polars.polars as plr @@ -1636,7 +1636,17 @@ def collect_all( comm_subexpr_elim Common subexpressions will be cached and reused. streaming - Run parts of the query in a streaming fashion (this is in an alpha state) + Process the query in batches to handle larger-than-memory data. + If set to `False` (default), the entire query is processed in a single + batch. + + .. warning:: + Streaming mode is considered **unstable**. It may be changed + at any point without it being considered a breaking change. + + .. note:: + Use :func:`explain` to see if Polars can process the query in streaming + mode. Returns ------- @@ -1650,6 +1660,10 @@ def collect_all( comm_subplan_elim = False comm_subexpr_elim = False + if streaming: + issue_unstable_warning("Streaming mode is considered unstable.") + comm_subplan_elim = False + prepared = [] for lf in lazy_frames: @@ -1762,7 +1776,17 @@ def collect_all_async( comm_subexpr_elim Common subexpressions will be cached and reused. streaming - Run parts of the query in a streaming fashion (this is in an alpha state) + Process the query in batches to handle larger-than-memory data. + If set to `False` (default), the entire query is processed in a single + batch. + + .. warning:: + Streaming mode is considered **unstable**. It may be changed + at any point without it being considered a breaking change. + + .. note:: + Use :func:`explain` to see if Polars can process the query in streaming + mode. See Also -------- @@ -1788,6 +1812,10 @@ def collect_all_async( comm_subplan_elim = False comm_subexpr_elim = False + if streaming: + issue_unstable_warning("Streaming mode is considered unstable.") + comm_subplan_elim = False + prepared = [] for lf in lazy_frames: diff --git a/py-polars/polars/lazyframe/frame.py b/py-polars/polars/lazyframe/frame.py index 70d122576614f..777efe82bbe50 100644 --- a/py-polars/polars/lazyframe/frame.py +++ b/py-polars/polars/lazyframe/frame.py @@ -70,7 +70,7 @@ deprecate_saturating, issue_deprecation_warning, ) -from polars.utils.unstable import unstable +from polars.utils.unstable import issue_unstable_warning, unstable from polars.utils.various import ( _in_notebook, _prepare_row_index_args, @@ -1646,7 +1646,8 @@ def collect( batch. .. warning:: - This functionality is currently in an alpha state. + Streaming mode is considered **unstable**. It may be changed + at any point without it being considered a breaking change. .. note:: Use :func:`explain` to see if Polars can process the query in streaming @@ -1712,6 +1713,7 @@ def collect( comm_subexpr_elim = False if streaming: + issue_unstable_warning("Streaming mode is considered unstable.") comm_subplan_elim = False ldf = self._ldf.optimization_toggle( @@ -1813,17 +1815,17 @@ def collect_async( comm_subexpr_elim Common subexpressions will be cached and reused. streaming - Run parts of the query in a streaming fashion (this is in an alpha state) + Process the query in batches to handle larger-than-memory data. + If set to `False` (default), the entire query is processed in a single + batch. - Notes - ----- - In case of error `set_exception` is used on - `asyncio.Future`/`gevent.event.AsyncResult` and will be reraised by them. + .. warning:: + Streaming mode is considered **unstable**. It may be changed + at any point without it being considered a breaking change. - See Also - -------- - polars.collect_all : Collect multiple LazyFrames at the same time. - polars.collect_all_async: Collect multiple LazyFrames at the same time lazily. + .. note:: + Use :func:`explain` to see if Polars can process the query in streaming + mode. Returns ------- @@ -1832,6 +1834,16 @@ def collect_async( If `gevent=True` then returns wrapper that has `.get(block=True, timeout=None)` method. + See Also + -------- + polars.collect_all : Collect multiple LazyFrames at the same time. + polars.collect_all_async: Collect multiple LazyFrames at the same time lazily. + + Notes + ----- + In case of error `set_exception` is used on + `asyncio.Future`/`gevent.event.AsyncResult` and will be reraised by them. + Examples -------- >>> import asyncio @@ -1868,6 +1880,7 @@ def collect_async( comm_subexpr_elim = False if streaming: + issue_unstable_warning("Streaming mode is considered unstable.") comm_subplan_elim = False ldf = self._ldf.optimization_toggle(