docs: Minor rendering fixups, inherit all exceptions from NarwhalsError (#1919)

Author: MarcoGorelli

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'`.

narwhals/dataframe.py

@@ -520,18 +520,17 @@ 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:
 
                 - As `Implementation.<BACKEND>` with `BACKEND` being `DASK`, `DUCKDB`
                     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.

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,23 +92,23 @@ 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:
         self.message = message
         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:
         self.message = message
         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."""
 
 

narwhals/stable/v1/__init__.py

@@ -183,18 +183,17 @@ 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:
 
                 - As `Implementation.<BACKEND>` with `BACKEND` being `DASK`, `DUCKDB`
                     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.