From 24077343d9e02421f475f7158eabc8a9466daba2 Mon Sep 17 00:00:00 2001 From: Marco Edward Gorelli Date: Mon, 3 Feb 2025 08:47:37 +0000 Subject: [PATCH] docs: Minor rendering fixups, inherit all exceptions from NarwhalsError (#1919) --- docs/backcompat.md | 12 ++++++------ narwhals/dataframe.py | 9 ++++----- narwhals/exceptions.py | 20 ++++++++++++-------- narwhals/stable/v1/__init__.py | 9 ++++----- 4 files changed, 26 insertions(+), 24 deletions(-) diff --git a/docs/backcompat.md b/docs/backcompat.md index 78e01e46a..a79995d26 100644 --- a/docs/backcompat.md +++ b/docs/backcompat.md @@ -115,12 +115,12 @@ The following are differences between the main Narwhals namespace and `narwhals. - Since Narwhals 1.23: - - Passing an `ibis.Table` to `from_native` returns a `LazyFrame`. In - `narwhals.stable.v1`, it returns a `DataFrame` with `level='interchange'`. - - `eager_or_interchange_only` has been removed from `from_native` and `narwhalify`. - - Order-dependent expressions can no longer be used with `narwhals.LazyFrame`. - - The following expressions have been deprecated from the main namespace: `Expr.head`, - `Expr.tail`, `Expr.gather_every`, `Expr.sample`, `Expr.arg_true`, `Expr.sort`. + - Passing an `ibis.Table` to `from_native` returns a `LazyFrame`. In + `narwhals.stable.v1`, it returns a `DataFrame` with `level='interchange'`. + - `eager_or_interchange_only` has been removed from `from_native` and `narwhalify`. + - Order-dependent expressions can no longer be used with `narwhals.LazyFrame`. + - The following expressions have been deprecated from the main namespace: `Expr.head`, + `Expr.tail`, `Expr.gather_every`, `Expr.sample`, `Expr.arg_true`, `Expr.sort`. - Since Narwhals 1.21, passing a `DuckDBPyRelation` to `from_native` returns a `LazyFrame`. In `narwhals.stable.v1`, it returns a `DataFrame` with `level='interchange'`. diff --git a/narwhals/dataframe.py b/narwhals/dataframe.py index b8f5b1e84..c608ff32d 100644 --- a/narwhals/dataframe.py +++ b/narwhals/dataframe.py @@ -520,8 +520,10 @@ def lazy( the possibility of running entirely lazily. Arguments: - backend: specifies which lazy backend collect to. This will be the underlying - backend for the resulting Narwhals LazyFrame. + backend: Which lazy backend collect to. This will be the underlying + backend for the resulting Narwhals LazyFrame. If not specified, and the + given library does not support lazy execution, then this will restrict + the API to lazy-only operations. `backend` can be specified in various ways: @@ -529,9 +531,6 @@ def lazy( or `POLARS`. - As a string: `"dask"`, `"duckdb"` or `"polars"` - Directly as a module `dask.dataframe`, `duckdb` or `polars`. - backend: The (lazy) implementation to convert to. If not specified, and the - given library does not support lazy execution, then this will restrict - the API to lazy-only operations. Returns: A new LazyFrame. diff --git a/narwhals/exceptions.py b/narwhals/exceptions.py index 94bd8ebcd..011fb9407 100644 --- a/narwhals/exceptions.py +++ b/narwhals/exceptions.py @@ -6,6 +6,10 @@ from typing_extensions import Self +class NarwhalsError(ValueError): + """Base class for all Narwhals exceptions.""" + + class FormattedKeyError(KeyError): """KeyError with formatted error message. @@ -22,7 +26,7 @@ def __str__(self: Self) -> str: return self.message -class ColumnNotFoundError(FormattedKeyError): +class ColumnNotFoundError(FormattedKeyError, NarwhalsError): """Exception raised when column name isn't present.""" def __init__(self: Self, message: str) -> None: @@ -40,15 +44,15 @@ def from_missing_and_available_column_names( return ColumnNotFoundError(message) -class ShapeError(Exception): +class ShapeError(NarwhalsError): """Exception raised when trying to perform operations on data structures with incompatible shapes.""" -class InvalidOperationError(Exception): +class InvalidOperationError(NarwhalsError): """Exception raised during invalid operations.""" -class InvalidIntoExprError(TypeError): +class InvalidIntoExprError(TypeError, NarwhalsError): """Exception raised when object can't be converted to expression.""" def __init__(self: Self, message: str) -> None: @@ -71,7 +75,7 @@ def from_invalid_type(cls: type, invalid_type: type) -> InvalidIntoExprError: return InvalidIntoExprError(message) -class AnonymousExprError(ValueError): # pragma: no cover +class AnonymousExprError(NarwhalsError): # pragma: no cover """Exception raised when trying to perform operations on anonymous expressions.""" def __init__(self: Self, message: str) -> None: @@ -88,7 +92,7 @@ def from_expr_name(cls: type, expr_name: str) -> AnonymousExprError: return AnonymousExprError(message) -class OrderDependentExprError(ValueError): +class OrderDependentExprError(NarwhalsError): """Exception raised when trying to use an order-dependent expressions with LazyFrames.""" def __init__(self: Self, message: str) -> None: @@ -96,7 +100,7 @@ def __init__(self: Self, message: str) -> None: super().__init__(self.message) -class LengthChangingExprError(ValueError): +class LengthChangingExprError(NarwhalsError): """Exception raised when trying to use an expression which changes length with LazyFrames.""" def __init__(self: Self, message: str) -> None: @@ -104,7 +108,7 @@ def __init__(self: Self, message: str) -> None: super().__init__(self.message) -class UnsupportedDTypeError(ValueError): +class UnsupportedDTypeError(NarwhalsError): """Exception raised when trying to convert to a DType which is not supported by the given backend.""" diff --git a/narwhals/stable/v1/__init__.py b/narwhals/stable/v1/__init__.py index d4281a070..b018c90a0 100644 --- a/narwhals/stable/v1/__init__.py +++ b/narwhals/stable/v1/__init__.py @@ -183,8 +183,10 @@ def lazy( the possibility of running entirely lazily. Arguments: - backend: specifies which lazy backend collect to. This will be the underlying - backend for the resulting Narwhals LazyFrame. + backend: Which lazy backend collect to. This will be the underlying + backend for the resulting Narwhals LazyFrame. If not specified, and the + given library does not support lazy execution, then this will restrict + the API to lazy-only operations. `backend` can be specified in various ways: @@ -192,9 +194,6 @@ def lazy( or `POLARS`. - As a string: `"dask"`, `"duckdb"` or `"polars"` - Directly as a module `dask.dataframe`, `duckdb` or `polars`. - backend: The (lazy) implementation to convert to. If not specified, and the - given library does not support lazy execution, then this will restrict - the API to lazy-only operations. Returns: A new LazyFrame.