Merge pull request #33 from vertti/improved-error-messages

Improve Exception Messages for Better Debugging

Author: vertti

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.15.0
+
+- Exception messages now include function names to improve debugging
+  - Input validation: `"Missing columns: ['Col'] in function 'my_func' parameter 'param'. Got columns: ['Other']"`
+- Return value validation messages now clearly state "return value" instead of just showing function name
+  - Output validation: `"Missing columns: ['Col'] in function 'my_func' return value. Got columns: ['Other']"`
+
 ## 0.14.2
 
 - Internal code quality improvements

daffy/decorators.py

@@ -50,7 +50,7 @@ def wrapper(*args: Any, **kwargs: Any) -> DF:
             result = func(*args, **kwargs)
             assert_is_dataframe(result, "return type")
             if columns:
-                validate_dataframe(result, columns, get_strict(strict))
+                validate_dataframe(result, columns, get_strict(strict), None, func.__name__, True)
             return result
 
         return wrapper
@@ -86,7 +86,7 @@ def wrapper(*args: Any, **kwargs: Any) -> R:
             param_name = get_parameter_name(func, name, *args, **kwargs)
             assert_is_dataframe(df, "parameter type")
             if columns:
-                validate_dataframe(df, columns, get_strict(strict), param_name)
+                validate_dataframe(df, columns, get_strict(strict), param_name, func.__name__)
             return func(*args, **kwargs)
 
         return wrapper

daffy/utils.py

@@ -19,8 +19,21 @@ def assert_is_dataframe(obj: Any, context: str) -> None:
         raise AssertionError(f"Wrong {context}. Expected DataFrame, got {type(obj).__name__} instead.")
 
 
-def format_param_context(param_name: Optional[str]) -> str:
-    return f" in parameter '{param_name}'" if param_name else ""
+def format_param_context(
+    param_name: Optional[str], func_name: Optional[str] = None, is_return_value: bool = False
+) -> str:
+    context_parts = []
+    if func_name:
+        context_parts.append(f"function '{func_name}'")
+
+    if is_return_value:
+        context_parts.append("return value")
+    elif param_name:
+        context_parts.append(f"parameter '{param_name}'")
+
+    if context_parts:
+        return f" in {' '.join(context_parts)}"
+    return ""
 
 
 def get_parameter(func: Callable[..., Any], name: Optional[str] = None, *args: Any, **kwargs: Any) -> Any:

daffy/validation.py

@@ -47,7 +47,12 @@ def _find_dtype_mismatches(
 
 
 def validate_dataframe(
-    df: DataFrameType, columns: Union[ColumnsList, ColumnsDict], strict: bool, param_name: Optional[str] = None
+    df: DataFrameType,
+    columns: Union[ColumnsList, ColumnsDict],
+    strict: bool,
+    param_name: Optional[str] = None,
+    func_name: Optional[str] = None,
+    is_return_value: bool = False,
 ) -> None:
     df_columns = list(df.columns)  # Cache the column list conversion
     all_missing_columns = []
@@ -69,7 +74,7 @@ def validate_dataframe(
             all_dtype_mismatches.extend(_find_dtype_mismatches(column_spec, df, expected_dtype, df_columns))
             all_matched_by_regex.update(find_regex_matches(column_spec, df_columns))
 
-    param_info = format_param_context(param_name)
+    param_info = format_param_context(param_name, func_name, is_return_value)
 
     if all_missing_columns:
         raise AssertionError(f"Missing columns: {all_missing_columns}{param_info}. Got {describe_dataframe(df)}")

docs/usage.md

@@ -48,9 +48,11 @@ def get_all_cars():
 In case one of the listed columns is missing from the DataFrame, a helpful assertion error is thrown:
 
 ```python
-AssertionError("Column Price missing from DataFrame. Got columns: ['Brand']")
+AssertionError("Missing columns: ['Price'] in function 'get_all_cars' return value. Got columns: ['Brand']")
 ```
 
+The error message clearly indicates that this is a **return value** validation failure in the function `get_all_cars`.
+
 ## Combined Validation
 
 To check both input and output, just use both annotations on the same function:
@@ -63,6 +65,10 @@ def filter_cars(car_df):
     return filtered_cars_df
 ```
 
+Note that error messages will clearly distinguish between input and output validation failures:
+- Input validation: `"Missing columns: ['Price'] in function 'filter_cars' parameter 'car_df'. Got columns: ['Brand']"`
+- Output validation: `"Missing columns: ['Price'] in function 'filter_cars' return value. Got columns: ['Brand']"`
+
 ## Column Pattern Matching with Regex
 
 You can use regex patterns to match column names that follow a specific pattern. This is useful when working with dynamic column names or when dealing with many similar columns.
@@ -83,7 +89,7 @@ In this example:
 If no columns match a regex pattern, an error is raised:
 
 ```
-AssertionError: Missing columns: ['r/Price_\d+/']. Got columns: ['Brand', 'Model']
+AssertionError: Missing columns: ['r/Price_\d+/'] in function 'process_data' parameter 'df'. Got columns: ['Brand', 'Model']
 ```
 
 Regex patterns are also considered in strict mode. Any column matching a regex pattern is considered valid.
@@ -105,7 +111,7 @@ columns={"Brand": "object", "Price": "int64"}
 This will not only check that the specified columns are found from the DataFrame but also that their `dtype` is the expected. In case of a wrong `dtype`, an error message similar to following will explain the mismatch:
 
 ```
-AssertionError("Column Price has wrong dtype. Was int64, expected float64")
+AssertionError("Column Price in function 'process_cars' parameter 'car_df' has wrong dtype. Was int64, expected float64")
 ```
 
 ### Combining Regex Patterns with Data Type Validation
@@ -126,7 +132,7 @@ In this example:
 If a column matches the regex pattern but has the wrong dtype, an error is raised:
 
 ```
-AssertionError: Column Price_2 has wrong dtype. Was float64, expected int64
+AssertionError: Column Price_2 in function 'process_data' parameter 'df' has wrong dtype. Was float64, expected int64
 ```
 
 ## Strict Mode
@@ -142,7 +148,7 @@ def process_cars(car_df):
 will, when `car_df` contains columns `["Brand", "Price"]` raise an error:
 
 ```
-AssertionError: DataFrame contained unexpected column(s): Price
+AssertionError: DataFrame in function 'process_cars' parameter 'car_df' contained unexpected column(s): Price
 ```
 
 ## Project-wide Configuration

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "daffy"
-version = "0.14.2"
+version = "0.15.0"
 description = "Function decorators for Pandas and Polars Dataframe column name and data type validation"
 authors = [
  { name="Janne Sinivirta", email="[email protected]" },

tests/test_df_in.py

@@ -106,7 +106,7 @@ def test_fn(my_input: Any, _df: DataFrameType) -> DataFrameType:
     with pytest.raises(AssertionError) as excinfo:
         test_fn("foo", _df=df)
 
-    assert "DataFrame in parameter '_df' contained unexpected column(s): Price" in str(excinfo.value)
+    assert "DataFrame in function 'test_fn' parameter '_df' contained unexpected column(s): Price" in str(excinfo.value)
 
 
 def test_correct_input_with_columns_and_dtypes_pandas(basic_pandas_df: pd.DataFrame) -> None:
@@ -133,7 +133,10 @@ def test_fn(my_input: Any) -> Any:
     with pytest.raises(AssertionError) as excinfo:
         test_fn(basic_pandas_df)
 
-    assert "Column Price in parameter 'my_input' has wrong dtype. Was int64, expected float64" in str(excinfo.value)
+    assert (
+        "Column Price in function 'test_fn' parameter 'my_input' has wrong dtype. Was int64, expected float64"
+        in str(excinfo.value)
+    )
 
 
 def test_dtype_mismatch_polars(basic_polars_df: pl.DataFrame) -> None:
@@ -144,7 +147,10 @@ def test_fn(my_input: Any) -> Any:
     with pytest.raises(AssertionError) as excinfo:
         test_fn(basic_polars_df)
 
-    assert "Column Price in parameter 'my_input' has wrong dtype. Was Int64, expected Float64" in str(excinfo.value)
+    assert (
+        "Column Price in function 'test_fn' parameter 'my_input' has wrong dtype. Was Int64, expected Float64"
+        in str(excinfo.value)
+    )
 
 
 @pytest.mark.parametrize(("df"), [pd.DataFrame(cars), pl.DataFrame(cars)])
@@ -155,7 +161,9 @@ def test_fn(my_input: Any) -> Any:
 
     with pytest.raises(AssertionError) as excinfo:
         test_fn(df[["Brand"]])
-    assert "Missing columns: ['Price'] in parameter 'my_input'. Got columns: ['Brand']" in str(excinfo.value)
+    assert "Missing columns: ['Price'] in function 'test_fn' parameter 'my_input'. Got columns: ['Brand']" in str(
+        excinfo.value
+    )
 
 
 @pytest.mark.parametrize(("df"), [pd.DataFrame(cars), pl.DataFrame(cars)])
@@ -166,7 +174,10 @@ def test_fn(my_input: Any) -> Any:
 
     with pytest.raises(AssertionError) as excinfo:
         test_fn(df[["Brand"]])
-    assert "Missing columns: ['Price', 'Extra'] in parameter 'my_input'. Got columns: ['Brand']" in str(excinfo.value)
+    assert (
+        "Missing columns: ['Price', 'Extra'] in function 'test_fn' parameter 'my_input'. Got columns: ['Brand']"
+        in str(excinfo.value)
+    )
 
 
 @pytest.mark.parametrize(
@@ -256,7 +267,9 @@ def test_fn(my_input: Any) -> Any:
     with pytest.raises(AssertionError) as excinfo:
         test_fn(df)
 
-    assert "DataFrame in parameter 'my_input' contained unexpected column(s): Price" in str(excinfo.value)
+    assert "DataFrame in function 'test_fn' parameter 'my_input' contained unexpected column(s): Price" in str(
+        excinfo.value
+    )
 
 
 def test_regex_column_with_dtype_pandas(basic_pandas_df: pd.DataFrame) -> None:
@@ -289,7 +302,10 @@ def test_fn(my_input: Any) -> Any:
     with pytest.raises(AssertionError) as excinfo:
         test_fn(df)
 
-    assert "Column Price_2 in parameter 'my_input' has wrong dtype. Was float64, expected int64" in str(excinfo.value)
+    assert (
+        "Column Price_2 in function 'test_fn' parameter 'my_input' has wrong dtype. Was float64, expected int64"
+        in str(excinfo.value)
+    )
 
 
 def test_regex_column_with_dtype_polars(basic_polars_df: pl.DataFrame) -> None:
@@ -323,7 +339,7 @@ def test_fn(cars: DataFrameType, ext_cars: DataFrameType) -> int:
     with pytest.raises(AssertionError) as excinfo:
         test_fn(cars=basic_df, ext_cars=extended_df)
 
-    assert "Missing columns: ['NonExistent'] in parameter 'ext_cars'" in str(excinfo.value)
+    assert "Missing columns: ['NonExistent'] in function 'test_fn' parameter 'ext_cars'" in str(excinfo.value)
 
 
 def test_check_columns_handles_invalid_column_type_in_list() -> None:
@@ -384,3 +400,34 @@ def test_fn(df: pd.DataFrame) -> pd.DataFrame:
     df = pd.DataFrame({"A": [1, 2], "B": [3, 4]})
     result = test_fn(df)
     assert result is not None
+
+
+def test_function_name_appears_in_missing_columns_exception() -> None:
+    @df_in(columns=["Brand", "NonExistentColumn"])
+    def my_test_function(df: pd.DataFrame) -> pd.DataFrame:
+        return df
+
+    df = pd.DataFrame({"Brand": ["Toyota", "Honda"]})
+
+    with pytest.raises(AssertionError) as excinfo:
+        my_test_function(df)
+
+    # Should include function name in the exception message
+    assert "my_test_function" in str(excinfo.value)
+    assert "Missing columns: ['NonExistentColumn']" in str(excinfo.value)
+
+
+def test_function_name_appears_in_dtype_mismatch_exception() -> None:
+    @df_in(columns={"Brand": "object", "Price": "float64"})
+    def another_test_function(df: pd.DataFrame) -> pd.DataFrame:
+        return df
+
+    df = pd.DataFrame({"Brand": ["Toyota"], "Price": [100]})  # Price is int64, not float64
+
+    with pytest.raises(AssertionError) as excinfo:
+        another_test_function(df)
+
+    # Should include function name in the exception message
+    assert "another_test_function" in str(excinfo.value)
+    assert "Column Price" in str(excinfo.value)
+    assert "wrong dtype" in str(excinfo.value)

tests/test_df_out.py

@@ -64,7 +64,7 @@ def test_fn() -> DataFrameType:
     with pytest.raises(AssertionError) as excinfo:
         test_fn()
 
-    assert "DataFrame contained unexpected column(s): Price" in str(excinfo.value)
+    assert "DataFrame in function 'test_fn' return value contained unexpected column(s): Price" in str(excinfo.value)
 
 
 @pytest.mark.parametrize(("df"), [pd.DataFrame(cars), pl.DataFrame(cars)])
@@ -76,7 +76,9 @@ def test_fn() -> DataFrameType:
     with pytest.raises(AssertionError) as excinfo:
         test_fn()
 
-    assert "Missing columns: ['FooColumn']. Got columns: ['Brand', 'Price']" in str(excinfo.value)
+    assert "Missing columns: ['FooColumn'] in function 'test_fn' return value. Got columns: ['Brand', 'Price']" in str(
+        excinfo.value
+    )
 
 
 def test_df_out_with_df_modification(basic_pandas_df: pd.DataFrame, extended_pandas_df: pd.DataFrame) -> None:
@@ -116,7 +118,7 @@ def test_fn() -> pd.DataFrame:
     with pytest.raises(AssertionError) as excinfo:
         test_fn()
 
-    assert "Missing columns: ['r/NonExistent_[0-9]/']" in str(excinfo.value)
+    assert "Missing columns: ['r/NonExistent_[0-9]/'] in function 'test_fn' return value" in str(excinfo.value)
 
 
 def test_regex_column_pattern_with_strict_in_output(basic_pandas_df: pd.DataFrame) -> None:
@@ -130,7 +132,7 @@ def test_fn() -> pd.DataFrame:
     with pytest.raises(AssertionError) as excinfo:
         test_fn()
 
-    assert "DataFrame contained unexpected column(s): Price" in str(excinfo.value)
+    assert "DataFrame in function 'test_fn' return value contained unexpected column(s): Price" in str(excinfo.value)
 
 
 def test_regex_column_with_dtype_in_output_pandas(basic_pandas_df: pd.DataFrame) -> None:
@@ -161,7 +163,9 @@ def test_fn() -> pd.DataFrame:
     with pytest.raises(AssertionError) as excinfo:
         test_fn()
 
-    assert "Column Price_2 has wrong dtype. Was float64, expected int64" in str(excinfo.value)
+    assert "Column Price_2 in function 'test_fn' return value has wrong dtype. Was float64, expected int64" in str(
+        excinfo.value
+    )
 
 
 def test_regex_column_with_dtype_in_output_polars(basic_polars_df: pl.DataFrame) -> None:
@@ -190,4 +194,73 @@ def test_fn() -> pd.DataFrame:
     with pytest.raises(AssertionError) as excinfo:
         test_fn()
 
-    assert "DataFrame contained unexpected column(s): Price" in str(excinfo.value)
+    assert "DataFrame in function 'test_fn' return value contained unexpected column(s): Price" in str(excinfo.value)
+
+
+def test_function_name_appears_in_missing_columns_exception_output() -> None:
+    @df_out(columns=["Brand", "NonExistentColumn"])
+    def my_output_function() -> pd.DataFrame:
+        return pd.DataFrame({"Brand": ["Toyota", "Honda"]})
+
+    with pytest.raises(AssertionError) as excinfo:
+        my_output_function()
+
+    # Should include function name in the exception message
+    assert "my_output_function" in str(excinfo.value)
+    assert "Missing columns: ['NonExistentColumn']" in str(excinfo.value)
+
+
+def test_function_name_appears_in_dtype_mismatch_exception_output() -> None:
+    @df_out(columns={"Brand": "object", "Price": "float64"})
+    def another_output_function() -> pd.DataFrame:
+        return pd.DataFrame({"Brand": ["Toyota"], "Price": [100]})  # Price is int64, not float64
+
+    with pytest.raises(AssertionError) as excinfo:
+        another_output_function()
+
+    # Should include function name in the exception message
+    assert "another_output_function" in str(excinfo.value)
+    assert "Column Price" in str(excinfo.value)
+    assert "wrong dtype" in str(excinfo.value)
+
+
+def test_return_value_validation_clearly_states_return_value_missing_columns() -> None:
+    @df_out(columns=["Brand", "MissingColumn"])
+    def function_with_return_validation() -> pd.DataFrame:
+        return pd.DataFrame({"Brand": ["Toyota", "Honda"]})
+
+    with pytest.raises(AssertionError) as excinfo:
+        function_with_return_validation()
+
+    # Should clearly state this is a return value validation failure
+    assert "return value" in str(excinfo.value)
+    assert "function_with_return_validation" in str(excinfo.value)
+    assert "Missing columns: ['MissingColumn']" in str(excinfo.value)
+
+
+def test_return_value_validation_clearly_states_return_value_dtype_mismatch() -> None:
+    @df_out(columns={"Brand": "object", "Price": "float64"})
+    def function_with_dtype_validation() -> pd.DataFrame:
+        return pd.DataFrame({"Brand": ["Toyota"], "Price": [100]})  # Price is int64, not float64
+
+    with pytest.raises(AssertionError) as excinfo:
+        function_with_dtype_validation()
+
+    # Should clearly state this is a return value validation failure
+    assert "return value" in str(excinfo.value)
+    assert "function_with_dtype_validation" in str(excinfo.value)
+    assert "wrong dtype" in str(excinfo.value)
+
+
+def test_return_value_validation_clearly_states_return_value_extra_columns() -> None:
+    @df_out(columns=["Brand"], strict=True)
+    def function_with_extra_columns() -> pd.DataFrame:
+        return pd.DataFrame({"Brand": ["Toyota"], "Price": [100]})
+
+    with pytest.raises(AssertionError) as excinfo:
+        function_with_extra_columns()
+
+    # Should clearly state this is a return value validation failure
+    assert "return value" in str(excinfo.value)
+    assert "function_with_extra_columns" in str(excinfo.value)
+    assert "unexpected column(s): Price" in str(excinfo.value)