docs: Specify strictness in cast (#20067)

crates/polars-plan/src/dsl/mod.rs

@@ -398,6 +398,7 @@ impl Expr {
 
     /// Cast expression to another data type.
     /// Throws an error if conversion had overflows.
+    /// Returns an Error if cast is invalid on rows after predicates are pushed down.
     pub fn strict_cast(self, dtype: DataType) -> Self {
         Expr::Cast {
             expr: Arc::new(self),

py-polars/polars/dataframe/frame.py

@@ -7727,8 +7727,8 @@ def cast(
             Mapping of column names (or selector) to dtypes, or a single dtype
             to which all columns will be cast.
         strict
-            Throw an error if a cast could not be done (for instance, due to an
-            overflow).
+            Raise if cast is invalid on rows after predicates are pusded down.
+            If `False`, invalid casts will produce null values.
 
         Examples
         --------

py-polars/polars/expr/expr.py

@@ -1753,7 +1753,8 @@ def cast(
         dtype
             DataType to cast to.
         strict
-            If True invalid casts generate exceptions instead of `null`\s.
+            Raise if cast is invalid on rows after predicates are pushed down.
+            If `False`, invalid casts will produce null values.
         wrap_numerical
             If True numeric casts wrap overflowing values instead of
             marking the cast as invalid.