feat(python): When reporting unexpected types in errors, module-qualify the typename (#22390)

Author: alexander-beedie

py-polars/polars/_utils/getitem.py

@@ -7,7 +7,7 @@
 import polars.functions as F
 from polars._utils.constants import U32_MAX
 from polars._utils.slice import PolarsSlice
-from polars._utils.various import range_to_slice
+from polars._utils.various import qualified_type_name, range_to_slice
 from polars.datatypes.classes import (
     Boolean,
     Int8,
@@ -72,7 +72,7 @@ def get_series_item_by_key(
         try:
             indices = pl.Series("", key, dtype=Int64)
         except TypeError:
-            msg = f"cannot select elements using Sequence with elements of type {type(first).__name__!r}"
+            msg = f"cannot select elements using Sequence with elements of type {qualified_type_name(first)!r}"
             raise TypeError(msg) from None
 
         indices = _convert_series_to_indices(indices, s.len())
@@ -86,7 +86,7 @@ def get_series_item_by_key(
         indices = _convert_np_ndarray_to_indices(key, s.len())
         return _select_elements_by_index(s, indices)
 
-    msg = f"cannot select elements using key of type {type(key).__name__!r}: {key!r}"
+    msg = f"cannot select elements using key of type {qualified_type_name(key)!r}: {key!r}"
     raise TypeError(msg)
 
 
@@ -216,7 +216,7 @@ def _select_columns(
         elif isinstance(first, str):
             return _select_columns_by_name(df, key)  # type: ignore[arg-type]
         else:
-            msg = f"cannot select columns using Sequence with elements of type {type(first).__name__!r}"
+            msg = f"cannot select columns using Sequence with elements of type {qualified_type_name(first)!r}"
             raise TypeError(msg)
 
     elif isinstance(key, pl.Series):
@@ -254,7 +254,9 @@ def _select_columns(
             msg = f"cannot select columns using NumPy array of type {key.dtype}"
             raise TypeError(msg)
 
-    msg = f"cannot select columns using key of type {type(key).__name__!r}: {key!r}"
+    msg = (
+        f"cannot select columns using key of type {qualified_type_name(key)!r}: {key!r}"
+    )
     raise TypeError(msg)
 
 
@@ -322,7 +324,7 @@ def _select_rows(
         return _select_rows_by_index(df, indices)
 
     else:
-        msg = f"cannot select rows using key of type {type(key).__name__!r}: {key!r}"
+        msg = f"cannot select rows using key of type {qualified_type_name(key)!r}: {key!r}"
         raise TypeError(msg)
 
 

py-polars/polars/_utils/various.py

@@ -702,3 +702,31 @@ def display_dot_graph(
         plt.imshow(img)
         plt.show()
         return None
+
+
+def qualified_type_name(obj: Any, *, qualify_polars: bool = False) -> str:
+    """
+    Return the module-qualified name of the given object as a string.
+
+    Parameters
+    ----------
+    obj
+        The object to get the qualified name for.
+    qualify_polars
+        If False (default), omit the module path for our own (Polars) objects.
+    """
+    if isinstance(obj, type):
+        module = obj.__module__
+        name = obj.__name__
+    else:
+        module = obj.__class__.__module__
+        name = obj.__class__.__name__
+
+    if (
+        not module
+        or module == "builtins"
+        or (not qualify_polars and module.startswith("polars."))
+    ):
+        return name
+
+    return f"{module}.{name}"

py-polars/polars/convert/general.py

@@ -21,7 +21,11 @@
     issue_deprecation_warning,
 )
 from polars._utils.pycapsule import is_pycapsule, pycapsule_to_frame
-from polars._utils.various import _cast_repr_strings_with_schema, issue_warning
+from polars._utils.various import (
+    _cast_repr_strings_with_schema,
+    issue_warning,
+    qualified_type_name,
+)
 from polars._utils.wrap import wrap_df, wrap_s
 from polars.datatypes import N_INFER_DEFAULT, Categorical, String
 from polars.dependencies import _check_for_pyarrow
@@ -493,7 +497,7 @@ def from_arrow(
             )
         )
 
-    msg = f"expected PyArrow Table, Array, or one or more RecordBatches; got {type(data).__name__!r}"
+    msg = f"expected PyArrow Table, Array, or one or more RecordBatches; got {qualified_type_name(data)!r}"
     raise TypeError(msg)
 
 
@@ -616,7 +620,7 @@ def from_pandas(
             )
         )
     else:
-        msg = f"expected pandas DataFrame or Series, got {type(data).__name__!r}"
+        msg = f"expected pandas DataFrame or Series, got {qualified_type_name(data)!r}"
         raise TypeError(msg)
 
 

py-polars/polars/dataframe/frame.py

@@ -56,6 +56,7 @@
     no_default,
     normalize_filepath,
     parse_version,
+    qualified_type_name,
     scale_bytes,
     warn_null_comparison,
 )
@@ -4935,7 +4936,7 @@ def insert_column(self, index: int, column: IntoExprColumn) -> DataFrame:
                 cols.insert(index, column)  # type: ignore[arg-type]
                 self._df = self.select(cols)._df
             else:
-                msg = f"column must be a Series or Expr, got {column!r} (type={type(column)})"
+                msg = f"column must be a Series or Expr, got {column!r} (type={qualified_type_name(column)})"
                 raise TypeError(msg)
         return self
 
@@ -7505,19 +7506,21 @@ def join_asof(
         └─────────────┴────────────┴────────────┴──────┘
         """
         if not isinstance(other, DataFrame):
-            msg = f"expected `other` join table to be a DataFrame, got {type(other).__name__!r}"
+            msg = f"expected `other` join table to be a DataFrame, not {qualified_type_name(other)!r}"
             raise TypeError(msg)
 
         if on is not None:
             if not isinstance(on, (str, pl.Expr)):
-                msg = f"expected `on` to be str or Expr, got {type(on).__name__!r}"
+                msg = (
+                    f"expected `on` to be str or Expr, got {qualified_type_name(on)!r}"
+                )
                 raise TypeError(msg)
         else:
             if not isinstance(left_on, (str, pl.Expr)):
-                msg = f"expected `left_on` to be str or Expr, got {type(left_on).__name__!r}"
+                msg = f"expected `left_on` to be str or Expr, got {qualified_type_name(left_on)!r}"
                 raise TypeError(msg)
             elif not isinstance(right_on, (str, pl.Expr)):
-                msg = f"expected `right_on` to be str or Expr, got {type(right_on).__name__!r}"
+                msg = f"expected `right_on` to be str or Expr, got {qualified_type_name(right_on)!r}"
                 raise TypeError(msg)
 
         return (
@@ -7751,7 +7754,7 @@ def join(
         For joining on columns with categorical data, see :class:`polars.StringCache`.
         """
         if not isinstance(other, DataFrame):
-            msg = f"expected `other` join table to be a DataFrame, got {type(other).__name__!r}"
+            msg = f"expected `other` join table to be a DataFrame, not {qualified_type_name(other)!r}"
             raise TypeError(msg)
 
         return (
@@ -7840,7 +7843,7 @@ def join_where(
         └─────┴─────┴─────┴───────┴──────┴──────┴──────┴─────────────┘
         """
         if not isinstance(other, DataFrame):
-            msg = f"expected `other` join table to be a DataFrame, got {type(other).__name__!r}"
+            msg = f"expected `other` join table to be a DataFrame, not {qualified_type_name(other)!r}"
             raise TypeError(msg)
 
         return (
@@ -10864,7 +10867,7 @@ def row(
 
         elif by_predicate is not None:
             if not isinstance(by_predicate, pl.Expr):
-                msg = f"expected `by_predicate` to be an expression, got {type(by_predicate).__name__!r}"
+                msg = f"expected `by_predicate` to be an expression, got {qualified_type_name(by_predicate)!r}"
                 raise TypeError(msg)
             rows = self.filter(by_predicate).rows()
             n_rows = len(rows)

py-polars/polars/datatypes/convert.py

@@ -355,6 +355,8 @@ def maybe_cast(el: Any, dtype: PolarsDataType) -> Any:
         try:
             el = py_type(el)  # type: ignore[call-arg]
         except Exception:
-            msg = f"cannot convert Python type {type(el).__name__!r} to {dtype!r}"
+            from polars._utils.various import qualified_type_name
+
+            msg = f"cannot convert Python type {qualified_type_name(el)!r} to {dtype!r}"
             raise TypeError(msg) from None
     return el

py-polars/polars/datatypes/group.py

@@ -62,8 +62,11 @@ def __new__(
         """
         for it in items:
             if not isinstance(it, (DataType, DataTypeClass)):
-                msg = f"DataTypeGroup items must be dtypes; found {type(it).__name__!r}"
+                from polars._utils.various import qualified_type_name
+
+                msg = f"DataTypeGroup items must be dtypes; found {qualified_type_name(it)!r}"
                 raise TypeError(msg)
+
         dtype_group = super().__new__(cls, items)
         dtype_group._match_base_type = match_base_type
         return dtype_group

py-polars/polars/expr/categorical.py

@@ -2,6 +2,7 @@
 
 from typing import TYPE_CHECKING
 
+from polars._utils.various import qualified_type_name
 from polars._utils.wrap import wrap_expr
 
 if TYPE_CHECKING:
@@ -181,7 +182,7 @@ def starts_with(self, prefix: str) -> Expr:
         └────────┘
         """
         if not isinstance(prefix, str):
-            msg = f"'prefix' must be a string; found {type(prefix)!r}"
+            msg = f"'prefix' must be a string; found {qualified_type_name(prefix)!r}"
             raise TypeError(msg)
         return wrap_expr(self._pyexpr.cat_starts_with(prefix))
 
@@ -234,7 +235,7 @@ def ends_with(self, suffix: str) -> Expr:
         └────────┘
         """
         if not isinstance(suffix, str):
-            msg = f"'suffix' must be a string; found {type(suffix)!r}"
+            msg = f"'suffix' must be a string; found {qualified_type_name(suffix)!r}"
             raise TypeError(msg)
         return wrap_expr(self._pyexpr.cat_ends_with(suffix))
 

py-polars/polars/expr/datetime.py

@@ -9,6 +9,7 @@
 from polars._utils.deprecation import deprecate_function, deprecate_nonkeyword_arguments
 from polars._utils.parse import parse_into_expression, parse_into_list_of_expressions
 from polars._utils.unstable import unstable
+from polars._utils.various import qualified_type_name
 from polars._utils.wrap import wrap_expr
 from polars.datatypes import DTYPE_TEMPORAL_UNITS, Date, Int32
 
@@ -539,7 +540,7 @@ def combine(self, time: dt.time | Expr, time_unit: TimeUnit = "us") -> Expr:
         └─────────────────────────┴─────────────────────────┴─────────────────────┘
         """
         if not isinstance(time, (dt.time, pl.Expr)):
-            msg = f"expected 'time' to be a Python time or Polars expression, found {type(time).__name__!r}"
+            msg = f"expected 'time' to be a Python time or Polars expression, found {qualified_type_name(time)!r}"
             raise TypeError(msg)
         time = parse_into_expression(time)
         return wrap_expr(self._pyexpr.dt_combine(time, time_unit))

py-polars/polars/expr/string.py

@@ -12,7 +12,7 @@
 )
 from polars._utils.parse import parse_into_expression
 from polars._utils.unstable import unstable
-from polars._utils.various import find_stacklevel, no_default
+from polars._utils.various import find_stacklevel, no_default, qualified_type_name
 from polars._utils.wrap import wrap_expr
 from polars.datatypes import Date, Datetime, Time, parse_into_dtype
 from polars.datatypes.constants import N_INFER_DEFAULT
@@ -847,7 +847,9 @@ def pad_start(self, length: int, fill_char: str = " ") -> Expr:
         └──────────────┴──────────────┘
         """
         if not isinstance(fill_char, str):
-            msg = f"pad_start expects a `str`, given a `{type(fill_char)}`"
+            msg = (
+                f"pad_start expects a `str`, given a {qualified_type_name(fill_char)!r}"
+            )
             raise TypeError(msg)
         return wrap_expr(self._pyexpr.str_pad_start(length, fill_char))
 
@@ -884,7 +886,7 @@ def pad_end(self, length: int, fill_char: str = " ") -> Expr:
         └──────────────┴──────────────┘
         """
         if not isinstance(fill_char, str):
-            msg = f"pad_end expects a `str`, given a `{type(fill_char)}`"
+            msg = f"pad_end expects a `str`, given a {qualified_type_name(fill_char)!r}"
             raise TypeError(msg)
         return wrap_expr(self._pyexpr.str_pad_end(length, fill_char))
 
@@ -1640,7 +1642,7 @@ def extract_groups(self, pattern: str) -> Expr:
         └─────────────────────────────────┴───────────────────────┴──────────┘
         """
         if not isinstance(pattern, str):
-            msg = f"extract_groups expects a `str`, given a `{type(pattern)}`"
+            msg = f"extract_groups expects a `str`, given a {qualified_type_name(pattern)!r}"
             raise TypeError(msg)
         return wrap_expr(self._pyexpr.str_extract_groups(pattern))
 

py-polars/polars/expr/struct.py

@@ -4,6 +4,7 @@
 from typing import TYPE_CHECKING
 
 from polars._utils.parse import parse_into_list_of_expressions
+from polars._utils.various import qualified_type_name
 from polars._utils.wrap import wrap_expr
 
 if TYPE_CHECKING:
@@ -27,7 +28,7 @@ def __getitem__(self, item: str | int) -> Expr:
         elif isinstance(item, int):
             return wrap_expr(self._pyexpr.struct_field_by_index(item))
         else:
-            msg = f"expected type 'int | str', got {type(item).__name__!r} ({item!r})"
+            msg = f"expected type 'int | str', got {qualified_type_name(item)!r} ({item!r})"
             raise TypeError(msg)
 
     def field(self, name: str | list[str], *more_names: str) -> Expr: