feat: stabilize Cell class

src/safeds/_typing/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import datetime
+from decimal import Decimal
+from typing import TypeAlias
+
+from safeds.data.tabular.containers import Cell
+
+_NumericLiteral: TypeAlias = int | float | Decimal
+_TemporalLiteral: TypeAlias = datetime.date | datetime.time | datetime.datetime | datetime.timedelta
+_PythonLiteral: TypeAlias = _NumericLiteral | bool | str | bytes | _TemporalLiteral
+_ConvertibleToCell: TypeAlias = _PythonLiteral | Cell | None
+_BooleanCell: TypeAlias = Cell[bool | None]
+# We cannot restrict `Cell`, because `Row.get_cell` returns a `Cell[Any]`.
+_ConvertibleToBooleanCell: TypeAlias = bool | Cell | None
+_ConvertibleToIntCell: TypeAlias = int | Cell | None
+
+
+__all__ = [
+    "_BooleanCell",
+    "_ConvertibleToBooleanCell",
+    "_ConvertibleToCell",
+    "_ConvertibleToIntCell",
+    "_NumericLiteral",
+    "_PythonLiteral",
+    "_TemporalLiteral",
+]

src/safeds/_utils/__init__.py

@@ -7,6 +7,7 @@
 if TYPE_CHECKING:
     from ._collections import _compute_duplicates
     from ._hashing import _structural_hash
+    from ._lazy import _safe_collect_lazy_frame, _safe_collect_lazy_frame_schema
     from ._plotting import _figure_to_image
     from ._random import _get_random_seed
 
@@ -15,6 +16,8 @@
     {
         "_compute_duplicates": "._collections:_compute_duplicates",
         "_structural_hash": "._hashing:_structural_hash",
+        "_safe_collect_lazy_frame": "._lazy:_safe_collect_lazy_frame",
+        "_safe_collect_lazy_frame_schema": "._lazy:_safe_collect_lazy_frame_schema",
         "_figure_to_image": "._plotting:_figure_to_image",
         "_get_random_seed": "._random:_get_random_seed",
     },
@@ -24,5 +27,7 @@
     "_compute_duplicates",
     "_figure_to_image",
     "_get_random_seed",
+    "_safe_collect_lazy_frame",
+    "_safe_collect_lazy_frame_schema",
     "_structural_hash",
 ]

src/safeds/_utils/_lazy.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from safeds.exceptions import LazyComputationError
+
+if TYPE_CHECKING:
+    import polars as pl
+
+
+def _safe_collect_lazy_frame(frame: pl.LazyFrame) -> pl.DataFrame:
+    """
+    Collect a LazyFrame into a DataFrame and raise a custom error if an error occurs.
+
+    Parameters
+    ----------
+    frame:
+        The LazyFrame to collect.
+
+    Returns
+    -------
+    frame:
+        The collected DataFrame.
+
+    Raises
+    ------
+    LazyComputationError
+        If an error occurs during the computation.
+    """
+    from polars.exceptions import PolarsError
+
+    try:
+        return frame.collect()
+    except PolarsError as e:
+        raise LazyComputationError(str(e)) from None
+
+
+def _safe_collect_lazy_frame_schema(frame: pl.LazyFrame) -> pl.Schema:
+    """
+    Collect the schema of a LazyFrame.
+
+    Parameters
+    ----------
+    frame:
+        The LazyFrame to collect the schema of.
+
+    Returns
+    -------
+    schema:
+        The collected schema.
+
+    Raises
+    ------
+    LazyComputationError
+        If an error occurs during the computation.
+    """
+    from polars.exceptions import PolarsError
+
+    try:
+        return frame.collect_schema()
+    except PolarsError as e:
+        raise LazyComputationError(str(e)) from None