feat: Warn, instead of raising, in is_*_dataframe / is_*_series functions (#2906)

Author: MarcoGorelli

narwhals/_exceptions.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from warnings import warn
+
+
+def find_stacklevel() -> int:
+    """Find the first place in the stack that is not inside narwhals.
+
+    Returns:
+        Stacklevel.
+
+    Taken from:
+    https://github.com/pandas-dev/pandas/blob/ab89c53f48df67709a533b6a95ce3d911871a0a8/pandas/util/_exceptions.py#L30-L51
+    """
+    import inspect
+    from pathlib import Path
+
+    import narwhals as nw
+
+    pkg_dir = str(Path(nw.__file__).parent)
+
+    # https://stackoverflow.com/questions/17407119/python-inspect-stack-is-slow
+    frame = inspect.currentframe()
+    n = 0
+    try:
+        while frame:
+            fname = inspect.getfile(frame)
+            if fname.startswith(pkg_dir) or (
+                (qualname := getattr(frame.f_code, "co_qualname", None))
+                # ignore @singledispatch wrappers
+                and qualname.startswith("singledispatch.")
+            ):
+                frame = frame.f_back
+                n += 1
+            else:  # pragma: no cover
+                break
+        else:  # pragma: no cover
+            pass
+    finally:
+        # https://docs.python.org/3/library/inspect.html
+        # > Though the cycle detector will catch these, destruction of the frames
+        # > (and local variables) can be made deterministic by removing the cycle
+        # > in a finally clause.
+        del frame
+    return n
+
+
+def issue_deprecation_warning(message: str, _version: str) -> None:  # pragma: no cover
+    """Issue a deprecation warning.
+
+    Arguments:
+        message: The message associated with the warning.
+        _version: Narwhals version when the warning was introduced. Just used for internal
+            bookkeeping.
+    """
+    warn(message=message, category=DeprecationWarning, stacklevel=find_stacklevel())
+
+
+def issue_warning(message: str, category: type[Warning]) -> None:
+    warn(message=message, category=category, stacklevel=find_stacklevel())

narwhals/_pandas_like/group_by.py

@@ -7,8 +7,8 @@
 from typing import TYPE_CHECKING, Any, ClassVar, Literal
 
 from narwhals._compliant import EagerGroupBy
+from narwhals._exceptions import issue_warning
 from narwhals._expression_parsing import evaluate_output_names_and_aliases
-from narwhals._utils import find_stacklevel
 from narwhals.dependencies import is_pandas_like_dataframe
 
 if TYPE_CHECKING:
@@ -310,12 +310,11 @@ def empty_results_error() -> ValueError:
 
 
 def warn_complex_group_by() -> None:
-    warnings.warn(
+    issue_warning(
         "Found complex group-by expression, which can't be expressed efficiently with the "
         "pandas API. If you can, please rewrite your query such that group-by aggregations "
         "are simple (e.g. mean, std, min, max, ...). \n\n"
         "Please see: "
         "https://narwhals-dev.github.io/narwhals/concepts/improve_group_by_operation/",
         UserWarning,
-        stacklevel=find_stacklevel(),
     )

narwhals/_spark_like/dataframe.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-import warnings
 from functools import reduce
 from operator import and_
 from typing import TYPE_CHECKING, Any
 
+from narwhals._exceptions import issue_warning
 from narwhals._namespace import is_native_spark_like
 from narwhals._spark_like.utils import (
     catch_pyspark_connect_exception,
@@ -19,7 +19,6 @@
 from narwhals._utils import (
     Implementation,
     ValidateBackendVersion,
-    find_stacklevel,
     generate_temporary_column_name,
     not_implemented,
     parse_columns_to_drop,
@@ -156,9 +155,9 @@ def _to_arrow_schema(self) -> pa.Schema:  # pragma: no cover
                 # We can avoid the check when we introduce `nw.Null` dtype.
                 null_type = self._native_dtypes.NullType  # pyright: ignore[reportAttributeAccessIssue]
                 if not isinstance(native_spark_dtype, null_type):
-                    warnings.warn(
+                    issue_warning(
                         f"Could not convert dtype {native_spark_dtype} to PyArrow dtype, {exc!r}",
-                        stacklevel=find_stacklevel(),
+                        UserWarning,
                     )
                 schema.append((key, pa.null()))
             else:

narwhals/_utils.py

@@ -21,9 +21,9 @@
     cast,
     overload,
 )
-from warnings import warn
 
 from narwhals._enum import NoAutoEnum
+from narwhals._exceptions import issue_deprecation_warning
 from narwhals._typing_compat import assert_never, deprecated
 from narwhals.dependencies import (
     get_cudf,
@@ -46,12 +46,7 @@
     is_polars_series,
     is_pyarrow_chunked_array,
 )
-from narwhals.exceptions import (
-    ColumnNotFoundError,
-    DuplicateError,
-    InvalidOperationError,
-    PerformanceWarning,
-)
+from narwhals.exceptions import ColumnNotFoundError, DuplicateError, InvalidOperationError
 
 if TYPE_CHECKING:
     from collections.abc import Set  # noqa: PYI025
@@ -1431,68 +1426,6 @@ def is_sequence_of(obj: Any, tp: type[_T]) -> TypeIs[Sequence[_T]]:
     )
 
 
-def find_stacklevel() -> int:
-    """Find the first place in the stack that is not inside narwhals.
-
-    Returns:
-        Stacklevel.
-
-    Taken from:
-    https://github.com/pandas-dev/pandas/blob/ab89c53f48df67709a533b6a95ce3d911871a0a8/pandas/util/_exceptions.py#L30-L51
-    """
-    import inspect
-    from pathlib import Path
-
-    import narwhals as nw
-
-    pkg_dir = str(Path(nw.__file__).parent)
-
-    # https://stackoverflow.com/questions/17407119/python-inspect-stack-is-slow
-    frame = inspect.currentframe()
-    n = 0
-    try:
-        while frame:
-            fname = inspect.getfile(frame)
-            if fname.startswith(pkg_dir) or (
-                (qualname := getattr(frame.f_code, "co_qualname", None))
-                # ignore @singledispatch wrappers
-                and qualname.startswith("singledispatch.")
-            ):
-                frame = frame.f_back
-                n += 1
-            else:  # pragma: no cover
-                break
-        else:  # pragma: no cover
-            pass
-    finally:
-        # https://docs.python.org/3/library/inspect.html
-        # > Though the cycle detector will catch these, destruction of the frames
-        # > (and local variables) can be made deterministic by removing the cycle
-        # > in a finally clause.
-        del frame
-    return n
-
-
-def issue_deprecation_warning(message: str, _version: str) -> None:  # pragma: no cover
-    """Issue a deprecation warning.
-
-    Arguments:
-        message: The message associated with the warning.
-        _version: Narwhals version when the warning was introduced. Just used for internal
-            bookkeeping.
-    """
-    warn(message=message, category=DeprecationWarning, stacklevel=find_stacklevel())
-
-
-def issue_performance_warning(message: str) -> None:
-    """Issue a performance warning.
-
-    Arguments:
-        message: The message associated with the warning.
-    """
-    warn(message=message, category=PerformanceWarning, stacklevel=find_stacklevel())
-
-
 def validate_strict_and_pass_though(
     strict: bool | None,  # noqa: FBT001
     pass_through: bool | None,  # noqa: FBT001
@@ -1727,7 +1660,7 @@ def is_eager_allowed(obj: Implementation) -> TypeIs[EagerAllowedImplementation]:
 
 
 def has_native_namespace(obj: Any) -> TypeIs[SupportsNativeNamespace]:
-    return hasattr(obj, "__native_namespace__")
+    return _hasattr_static(obj, "__native_namespace__")
 
 
 def _supports_dataframe_interchange(obj: Any) -> TypeIs[DataFrameLike]:

narwhals/dataframe.py

@@ -13,8 +13,8 @@
     TypeVar,
     overload,
 )
-from warnings import warn
 
+from narwhals._exceptions import issue_warning
 from narwhals._expression_parsing import (
     ExprKind,
     all_exprs_are_scalar_like,
@@ -24,7 +24,6 @@
 from narwhals._utils import (
     Implementation,
     Version,
-    find_stacklevel,
     flatten,
     generate_repr,
     is_compliant_dataframe,
@@ -34,7 +33,6 @@
     is_list_of,
     is_sequence_like,
     is_slice_none,
-    issue_performance_warning,
     supports_arrow_c_stream,
 )
 from narwhals.dependencies import (
@@ -43,7 +41,11 @@
     is_numpy_array_2d,
     is_pyarrow_table,
 )
-from narwhals.exceptions import InvalidIntoExprError, InvalidOperationError
+from narwhals.exceptions import (
+    InvalidIntoExprError,
+    InvalidOperationError,
+    PerformanceWarning,
+)
 from narwhals.functions import _from_dict_no_backend, _is_into_schema
 from narwhals.schema import Schema
 from narwhals.series import Series
@@ -2196,7 +2198,7 @@ def pivot(
                 "`maintain_order` has no effect and is only kept around for backwards-compatibility. "
                 "You can safely remove this argument."
             )
-            warn(message=msg, category=UserWarning, stacklevel=find_stacklevel())
+            issue_warning(msg, UserWarning)
         on = [on] if isinstance(on, str) else on
         values = [values] if isinstance(values, str) else values
         index = [index] if isinstance(index, str) else index
@@ -2692,7 +2694,7 @@ def schema(self) -> Schema:
                 "Resolving the schema of a LazyFrame is a potentially expensive operation. "
                 "Use `LazyFrame.collect_schema()` to get the schema without this warning."
             )
-            issue_performance_warning(msg)
+            issue_warning(msg, PerformanceWarning)
         return super().schema
 
     def collect_schema(self) -> Schema: