docs: indicate where OutOfBoundsError and ColumnNotFoundError are raised (#761)

### Summary of Changes

Indicate in the docstrings where `OutOfBoundsError` and
`ColumnNotFoundError` are raised. Previously, we only specified generic
errors like `ValueError` and `KeyError`.

---------

Co-authored-by: megalinter-bot <129584137+megalinter-bot@users.noreply.github.com>

Author: lars-reimann

src/safeds/_validation/_normalize_and_check_file_path.py

@@ -44,10 +44,15 @@ def _normalize_and_check_file_path(
     if not path.suffix:
         path = path.with_suffix(canonical_file_extension)
     elif path.suffix not in valid_file_extensions:
-        raise FileExtensionError(path, valid_file_extensions)
+        message = _build_file_extension_error_message(path.suffix, valid_file_extensions)
+        raise FileExtensionError(message)
 
     # Check if file exists
     if check_if_file_exists and not path.is_file():
         raise FileNotFoundError(f"File not found: {path}")
 
     return path
+
+
+def _build_file_extension_error_message(actual_file_extension: str, valid_file_extensions: list[str]) -> str:
+    return f"Expected path with extension in {valid_file_extensions} but got {actual_file_extension}."

src/safeds/data/labeled/containers/_tabular_dataset.py

@@ -41,7 +41,7 @@ class TabularDataset:
 
     Raises
     ------
-    KeyError
+    ColumnNotFoundError
         If a column name is not found in the data.
     ValueError
         If the target column is also an extra column.
@@ -214,6 +214,7 @@ def _into_dataloader_with_classes(self, batch_size: int, num_of_classes: int) ->
                 generator=torch.Generator(device=_get_device()),
             )
 
+
 # TODO
 def _create_dataset(features: Tensor, target: Tensor) -> Dataset:
     import torch

src/safeds/data/labeled/containers/_time_series_dataset.py

@@ -199,9 +199,9 @@ def _into_dataloader_with_window(self, window_size: int, forecast_horizon: int,
 
         Raises
         ------
-        OutOfBoundsError:
+        OutOfBoundsError
             If window_size or forecast_horizon is below 1
-        ValueError:
+        ValueError
             If the size is smaller or even than forecast_horizon + window_size
 
         Returns
@@ -262,9 +262,9 @@ def _into_dataloader_with_window_predict(
 
         Raises
         ------
-        OutOfBoundsError:
+        OutOfBoundsError
             If window_size or forecast_horizon is below 1
-        ValueError:
+        ValueError
             If the size is smaller or even than forecast_horizon + window_size
 
         Returns

src/safeds/data/tabular/containers/_row.py

@@ -79,6 +79,11 @@ def get_value(self, name: str) -> Cell:
         -------
         value:
             The value of the column.
+
+        Raises
+        ------
+        ColumnNotFoundError
+            If the column name does not exist.
         """
 
     @abstractmethod
@@ -95,6 +100,11 @@ def get_column_type(self, name: str) -> DataType:
         -------
         type:
             The type of the column.
+
+        Raises
+        ------
+        ColumnNotFoundError
+            If the column name does not exist.
         """
 
     @abstractmethod

src/safeds/data/tabular/containers/_table.py

@@ -238,7 +238,12 @@ def from_json_file(path: str | Path) -> Table:
         import polars as pl
 
         path = _normalize_and_check_file_path(path, ".json", [".json"], check_if_file_exists=True)
-        return Table._from_polars_data_frame(pl.read_json(path))
+
+        try:
+            return Table._from_polars_data_frame(pl.read_json(path))
+        except pl.PolarsPanicError:
+            # Can happen if the JSON file is empty (https://github.com/pola-rs/polars/issues/10234)
+            return Table()
 
     @staticmethod
     def from_parquet_file(path: str | Path) -> Table:
@@ -347,8 +352,14 @@ def __str__(self) -> str:
 
     @property
     def _data_frame(self) -> pl.DataFrame:
+        import polars as pl
+
         if self.__data_frame_cache is None:
-            self.__data_frame_cache = self._lazy_frame.collect()
+            try:
+                self.__data_frame_cache = self._lazy_frame.collect()
+            except pl.NoDataError:
+                # Can happen if e.g. a CSV file is empty
+                self.__data_frame_cache = pl.DataFrame()
 
         return self.__data_frame_cache
 
@@ -364,7 +375,7 @@ def column_names(self) -> list[str]:
         >>> table.column_names
         ['a', 'b']
         """
-        return self._lazy_frame.columns
+        return self.schema.column_names
 
     @property
     def number_of_columns(self) -> int:
@@ -378,7 +389,13 @@ def number_of_columns(self) -> int:
         >>> table.number_of_columns
         2
         """
-        return self._lazy_frame.width
+        import polars as pl
+
+        try:
+            return self._lazy_frame.width
+        except pl.NoDataError:
+            # Can happen if e.g. a CSV file is empty
+            return 0
 
     @property
     def number_of_rows(self) -> int:
@@ -404,7 +421,13 @@ def plot(self) -> TablePlotter:
     @property
     def schema(self) -> Schema:
         """The schema of the table."""
-        return _PolarsSchema(self._lazy_frame.schema)
+        import polars as pl
+
+        try:
+            return _PolarsSchema(self._lazy_frame.schema)
+        except pl.NoDataError:
+            # Can happen if e.g. a CSV file is empty
+            return _PolarsSchema({})
 
     # ------------------------------------------------------------------------------------------------------------------
     # Column operations
@@ -534,7 +557,7 @@ def get_column(self, name: str) -> Column:
 
         Raises
         ------
-        KeyError
+        ColumnNotFoundError
             If the column does not exist.
 
         Examples
@@ -571,7 +594,7 @@ def get_column_type(self, name: str) -> DataType:
 
         Raises
         ------
-        KeyError
+        ColumnNotFoundError
             If the column does not exist.
 
         Examples
@@ -684,7 +707,7 @@ def remove_columns_except(
 
         Raises
         ------
-        KeyError
+        ColumnNotFoundError
             If a column does not exist.
 
         Examples
@@ -800,7 +823,7 @@ def rename_column(self, old_name: str, new_name: str) -> Table:
 
         Raises
         ------
-        KeyError
+        ColumnNotFoundError
             If no column with the old name exists.
 
         Examples
@@ -848,7 +871,7 @@ def replace_column(
 
         Raises
         ------
-        KeyError
+        ColumnNotFoundError
             If no column with the old name exists.
 
         Examples
@@ -941,7 +964,7 @@ def transform_column(
 
         Raises
         ------
-        KeyError
+        ColumnNotFoundError
             If no column with the specified name exists.
 
         Examples
@@ -1067,7 +1090,7 @@ def remove_rows_by_column(
 
         Raises
         ------
-        KeyError
+        ColumnNotFoundError
             If the column does not exist.
 
         Examples
@@ -1359,7 +1382,7 @@ def sort_rows_by_column(
 
         Raises
         ------
-        KeyError
+        ColumnNotFoundError
             If the column does not exist.
 
         Examples
@@ -1417,7 +1440,7 @@ def split_rows(
 
         Raises
         ------
-        ValueError
+        OutOfBoundsError
             If `percentage_in_first` is not between 0 and 1.
 
         Examples

src/safeds/data/tabular/plotting/_table_plotter.py

@@ -227,7 +227,7 @@ def line_plot(self, x_name: str, y_name: str) -> Image:
 
         Raises
         ------
-        KeyError
+        ColumnNotFoundError
             If a column does not exist.
         TypeError
             If a column is not numeric.
@@ -290,7 +290,7 @@ def scatter_plot(self, x_name: str, y_name: str) -> Image:
 
         Raises
         ------
-        KeyError
+        ColumnNotFoundError
             If a column does not exist.
         TypeError
             If a column is not numeric.

src/safeds/data/tabular/transformation/_discretizer.py

@@ -61,7 +61,7 @@ def fit(self, table: Table, column_names: list[str] | None) -> Discretizer:
             If the table is empty.
         NonNumericColumnError
             If one of the columns, that should be fitted is non-numeric.
-        UnknownColumnNameError
+        ColumnNotFoundError
             If one of the columns, that should be fitted is not in the table.
         """
         from sklearn.preprocessing import KBinsDiscretizer as sk_KBinsDiscretizer
@@ -112,7 +112,7 @@ def transform(self, table: Table) -> Table:
             If the transformer has not been fitted yet.
         ValueError
             If the table is empty.
-        UnknownColumnNameError
+        ColumnNotFoundError
             If one of the columns, that should be transformed is not in the table.
         NonNumericColumnError
             If one of the columns, that should be fitted is non-numeric.

src/safeds/data/tabular/transformation/_label_encoder.py

@@ -40,7 +40,7 @@ def fit(self, table: Table, column_names: list[str] | None) -> LabelEncoder:
 
         Raises
         ------
-        UnknownColumnNameError
+        ColumnNotFoundError
             If column_names contain a column name that is missing in the table.
         ValueError
             If the table contains 0 rows.
@@ -99,7 +99,7 @@ def transform(self, table: Table) -> Table:
         ------
         TransformerNotFittedError
             If the transformer has not been fitted yet.
-        UnknownColumnNameError
+        ColumnNotFoundError
             If the input table does not contain all columns used to fit the transformer.
         ValueError
             If the table contains 0 rows.
@@ -141,7 +141,7 @@ def inverse_transform(self, transformed_table: Table) -> Table:
         ------
         TransformerNotFittedError
             If the transformer has not been fitted yet.
-        UnknownColumnNameError
+        ColumnNotFoundError
             If the input table does not contain all columns used to fit the transformer.
         NonNumericColumnError
             If the specified columns of the input table contain non-numerical data.

src/safeds/data/tabular/transformation/_one_hot_encoder.py

@@ -96,7 +96,7 @@ def fit(self, table: Table, column_names: list[str] | None) -> OneHotEncoder:
 
         Raises
         ------
-        UnknownColumnNameError
+        ColumnNotFoundError
             If column_names contain a column name that is missing in the table.
         ValueError
             If the table contains 0 rows.
@@ -169,7 +169,7 @@ def transform(self, table: Table) -> Table:
         ------
         TransformerNotFittedError
             If the transformer has not been fitted yet.
-        UnknownColumnNameError
+        ColumnNotFoundError
             If the input table does not contain all columns used to fit the transformer.
         ValueError
             If the table contains 0 rows.
@@ -252,7 +252,7 @@ def inverse_transform(self, transformed_table: Table) -> Table:
         ------
         TransformerNotFittedError
             If the transformer has not been fitted yet.
-        UnknownColumnNameError
+        ColumnNotFoundError
             If the input table does not contain all columns used to fit the transformer.
         NonNumericColumnError
             If the transformed columns of the input table contain non-numerical data.

src/safeds/data/tabular/transformation/_range_scaler.py

@@ -57,7 +57,7 @@ def fit(self, table: Table, column_names: list[str] | None) -> RangeScaler:
 
         Raises
         ------
-        UnknownColumnNameError
+        ColumnNotFoundError
             If column_names contain a column name that is missing in the table.
         NonNumericColumnError
             If at least one of the specified columns in the table contains non-numerical data.
@@ -121,7 +121,7 @@ def transform(self, table: Table) -> Table:
         ------
         TransformerNotFittedError
             If the transformer has not been fitted yet.
-        UnknownColumnNameError
+        ColumnNotFoundError
             If the input table does not contain all columns used to fit the transformer.
         NonNumericColumnError
             If at least one of the columns in the input table that is used to fit contains non-numerical data.
@@ -180,7 +180,7 @@ def inverse_transform(self, transformed_table: Table) -> Table:
         ------
         TransformerNotFittedError
             If the transformer has not been fitted yet.
-        UnknownColumnNameError
+        ColumnNotFoundError
             If the input table does not contain all columns used to fit the transformer.
         NonNumericColumnError
             If the transformed columns of the input table contain non-numerical data.

src/safeds/data/tabular/transformation/_simple_imputer.py

@@ -132,7 +132,7 @@ def fit(self, table: Table, column_names: list[str] | None) -> SimpleImputer:
 
         Raises
         ------
-        UnknownColumnNameError
+        ColumnNotFoundError
             If column_names contain a column name that is missing in the table
         ValueError
             If the table contains 0 rows
@@ -213,7 +213,7 @@ def transform(self, table: Table) -> Table:
         ------
         TransformerNotFittedError
             If the transformer has not been fitted yet.
-        UnknownColumnNameError
+        ColumnNotFoundError
             If the input table does not contain all columns used to fit the transformer.
         ValueError
             If the table contains 0 rows.

src/safeds/data/tabular/transformation/_standard_scaler.py

@@ -39,7 +39,7 @@ def fit(self, table: Table, column_names: list[str] | None) -> StandardScaler:
 
         Raises
         ------
-        UnknownColumnNameError
+        ColumnNotFoundError
             If column_names contain a column name that is missing in the table.
         NonNumericColumnError
             If at least one of the specified columns in the table contains non-numerical data.
@@ -103,7 +103,7 @@ def transform(self, table: Table) -> Table:
         ------
         TransformerNotFittedError
             If the transformer has not been fitted yet.
-        UnknownColumnNameError
+        ColumnNotFoundError
             If the input table does not contain all columns used to fit the transformer.
         NonNumericColumnError
             If at least one of the columns in the input table that is used to fit contains non-numerical data.
@@ -162,7 +162,7 @@ def inverse_transform(self, transformed_table: Table) -> Table:
         ------
         TransformerNotFittedError
             If the transformer has not been fitted yet.
-        UnknownColumnNameError
+        ColumnNotFoundError
             If the input table does not contain all columns used to fit the transformer.
         NonNumericColumnError
             If the transformed columns of the input table contain non-numerical data.