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

[MarcoGorelli]

closes #15897

I'll maintain that the change introduced in #15506 is a net-positive, and that avoiding floating point imprecision for this operation is desirable - so I've just improved the error message and docs

Demo:

In [1]: import polars as pl
   ...: data = pl.DataFrame({"a": [1,2,3]})
   ...: data.select([pl.col("a").pow(-1)])
---------------------------------------------------------------------------
InvalidOperationError                     Traceback (most recent call last)
Cell In[1], line 3
      1 import polars as pl
      2 data = pl.DataFrame({"a": [1,2,3]})
----> 3 data.select([pl.col("a").pow(-1)])

File ~/polars-dev/py-polars/polars/dataframe/frame.py:8318, in DataFrame.select(self, *exprs, **named_exprs)
   8218 def select(
   8219     self, *exprs: IntoExpr | Iterable[IntoExpr], **named_exprs: IntoExpr
   8220 ) -> DataFrame:
   8221     """
   8222     Select columns from this DataFrame.
   8223 
   (...)
   8316     └───────────┘
   8317     """
-> 8318     return self.lazy().select(*exprs, **named_exprs).collect(_eager=True)

File ~/polars-dev/py-polars/polars/lazyframe/frame.py:1846, in LazyFrame.collect(self, type_coercion, predicate_pushdown, projection_pushdown, simplify_expression, slice_pushdown, comm_subplan_elim, comm_subexpr_elim, cluster_with_columns, no_optimization, streaming, background, _eager, **_kwargs)
   1843 # Only for testing purposes atm.
   1844 callback = _kwargs.get("post_opt_callback")
-> 1846 return wrap_df(ldf.collect(callback))

InvalidOperationError: conversion from `i32` to `u32` failed in column 'literal' for 1 out of 1 values: [-1]

Hint: if you were trying to raise an integer to a negative integer power, please cast your base or exponent to float first.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.37%. Comparing base (fa12a8e) to head (ca70f63).

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #16827      +/-   ##
==========================================
- Coverage   81.37%   81.37%   -0.01%     
==========================================
  Files        1424     1424              
  Lines      187594   187598       +4     
  Branches     2691     2691              
==========================================
- Hits       152656   152652       -4     
- Misses      34443    34451       +8     
  Partials      495      495              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[ritchie46]

Nice one @MarcoGorelli. I really love those improved error messages. 👍