feat: Improve error message when raising integers to negative integers, improve docs

crates/polars-plan/src/dsl/function_expr/pow.rs

@@ -158,7 +158,11 @@ fn pow_on_series(base: &Series, exponent: &Series) -> PolarsResult<Option<Series
                 }
             } else {
                 let ca = base.$native_type().unwrap();
-                let exponent = exponent.strict_cast(&DataType::UInt32)?;
+                let exponent = exponent.strict_cast(&DataType::UInt32).map_err(|err| polars_err!(
+                    InvalidOperation:
+                    "{}\n\nHint: if you were trying to raise an integer to a negative integer power, please cast your base or exponent to float first.",
+                    err
+                ))?;
                 pow_to_uint_dtype(ca, exponent.u32().unwrap())
             }
         })

py-polars/polars/expr/expr.py

@@ -5540,6 +5540,9 @@ def pow(self, exponent: IntoExprColumn | int | float) -> Self:
         """
         Method equivalent of exponentiation operator `expr ** exponent`.
 
+        If the exponent is float, the result follows the dtype of exponent.
+        Otherwise, it follows dtype of base.
+
         Parameters
         ----------
         exponent
@@ -5563,6 +5566,26 @@ def pow(self, exponent: IntoExprColumn | int | float) -> Self:
         │ 4   ┆ 64   ┆ 16.0       │
         │ 8   ┆ 512  ┆ 512.0      │
         └─────┴──────┴────────────┘
+
+        Raising an integer to a positive integer results in an integer - in order
+        to raise to a negative integer, you can cast either the base or the exponent
+        to float first:
+
+        >>> df.with_columns(
+        ...     x_squared=pl.col("x").pow(2),
+        ...     x_inverse=pl.col("x").pow(-1.0),
+        ... )
+        shape: (4, 3)
+        ┌─────┬───────────┬───────────┐
+        │ x   ┆ x_squared ┆ x_inverse │
+        │ --- ┆ ---       ┆ ---       │
+        │ i64 ┆ i64       ┆ f64       │
+        ╞═════╪═══════════╪═══════════╡
+        │ 1   ┆ 1         ┆ 1.0       │
+        │ 2   ┆ 4         ┆ 0.5       │
+        │ 4   ┆ 16        ┆ 0.25      │
+        │ 8   ┆ 64        ┆ 0.125     │
+        └─────┴───────────┴───────────┘
         """
         return self.__pow__(exponent)
 

py-polars/polars/series/series.py

@@ -1877,13 +1877,18 @@ def pow(self, exponent: int | float | Series) -> Series:
         """
         Raise to the power of the given exponent.
 
+        If the exponent is float, the result follows the dtype of exponent.
+        Otherwise, it follows dtype of base.
+
         Parameters
         ----------
         exponent
             The exponent. Accepts Series input.
 
         Examples
         --------
+        Raising integers to positive integers results in integers:
+
         >>> s = pl.Series("foo", [1, 2, 3, 4])
         >>> s.pow(3)
         shape: (4,)
@@ -1894,6 +1899,19 @@ def pow(self, exponent: int | float | Series) -> Series:
             27
             64
         ]
+
+        In order to raise integers to negative integers, you can cast either the
+        base or the exponent to float:
+
+        >>> s.pow(-3.0)
+        shape: (4,)
+        Series: 'foo' [f64]
+        [
+                1.0
+                0.125
+                0.037037
+                0.015625
+        ]
         """
         if _check_for_numpy(exponent) and isinstance(exponent, np.ndarray):
             exponent = Series(exponent)

py-polars/tests/unit/operations/arithmetic/test_arithmetic.py

@@ -537,7 +537,9 @@ def test_power_series() -> None:
         a ** "hi"  # type: ignore[operator]
 
     # Raising to UInt64: raises if can't be downcast safely to UInt32...
-    with pytest.raises(pl.ComputeError, match="conversion from `u64` to `u32` failed"):
+    with pytest.raises(
+        pl.InvalidOperationError, match="conversion from `u64` to `u32` failed"
+    ):
         a**m
     # ... but succeeds otherwise.
     assert_series_equal(a**j, pl.Series([1, 4], dtype=Int64))