polars_error/
lib.rs

1pub mod constants;
2mod warning;
3
4use std::borrow::Cow;
5use std::collections::TryReserveError;
6use std::convert::Infallible;
7use std::error::Error;
8use std::fmt::{self, Display, Formatter, Write};
9use std::ops::Deref;
10use std::sync::{Arc, LazyLock};
11use std::{env, io};
12pub mod signals;
13
14pub use warning::*;
15
16#[cfg(feature = "python")]
17mod python;
18
19enum ErrorStrategy {
20    Panic,
21    WithBacktrace,
22    Normal,
23}
24
25static ERROR_STRATEGY: LazyLock<ErrorStrategy> = LazyLock::new(|| {
26    if env::var("POLARS_PANIC_ON_ERR").as_deref() == Ok("1") {
27        ErrorStrategy::Panic
28    } else if env::var("POLARS_BACKTRACE_IN_ERR").as_deref() == Ok("1") {
29        ErrorStrategy::WithBacktrace
30    } else {
31        ErrorStrategy::Normal
32    }
33});
34
35#[derive(Debug, Clone)]
36pub struct ErrString(Cow<'static, str>);
37
38impl ErrString {
39    pub const fn new_static(s: &'static str) -> Self {
40        Self(Cow::Borrowed(s))
41    }
42}
43
44impl<T> From<T> for ErrString
45where
46    T: Into<Cow<'static, str>>,
47{
48    fn from(msg: T) -> Self {
49        match &*ERROR_STRATEGY {
50            ErrorStrategy::Panic => panic!("{}", msg.into()),
51            ErrorStrategy::WithBacktrace => ErrString(Cow::Owned(format!(
52                "{}\n\nRust backtrace:\n{}",
53                msg.into(),
54                std::backtrace::Backtrace::force_capture()
55            ))),
56            ErrorStrategy::Normal => ErrString(msg.into()),
57        }
58    }
59}
60
61impl AsRef<str> for ErrString {
62    fn as_ref(&self) -> &str {
63        &self.0
64    }
65}
66
67impl Deref for ErrString {
68    type Target = str;
69
70    fn deref(&self) -> &Self::Target {
71        &self.0
72    }
73}
74
75impl Display for ErrString {
76    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
77        write!(f, "{}", self.0)
78    }
79}
80
81#[derive(Debug, Clone)]
82pub enum PolarsError {
83    AssertionError(ErrString),
84    ColumnNotFound(ErrString),
85    ComputeError(ErrString),
86    Duplicate(ErrString),
87    InvalidOperation(ErrString),
88    IO {
89        error: Arc<io::Error>,
90        msg: Option<ErrString>,
91    },
92    NoData(ErrString),
93    OutOfBounds(ErrString),
94    SchemaFieldNotFound(ErrString),
95    SchemaMismatch(ErrString),
96    ShapeMismatch(ErrString),
97    SQLInterface(ErrString),
98    SQLSyntax(ErrString),
99    StringCacheMismatch(ErrString),
100    StructFieldNotFound(ErrString),
101    Context {
102        error: Box<PolarsError>,
103        msg: ErrString,
104    },
105    #[cfg(feature = "python")]
106    Python {
107        error: python::PyErrWrap,
108    },
109}
110
111impl Error for PolarsError {}
112
113impl Display for PolarsError {
114    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
115        use PolarsError::*;
116        match self {
117            ComputeError(msg)
118            | InvalidOperation(msg)
119            | OutOfBounds(msg)
120            | SchemaMismatch(msg)
121            | SQLInterface(msg)
122            | SQLSyntax(msg) => write!(f, "{msg}"),
123
124            AssertionError(msg) => write!(f, "assertion failed: {msg}"),
125            ColumnNotFound(msg) => write!(f, "not found: {msg}"),
126            Duplicate(msg) => write!(f, "duplicate: {msg}"),
127            IO { error, msg } => match msg {
128                Some(m) => write!(f, "{m}"),
129                None => write!(f, "{error}"),
130            },
131            NoData(msg) => write!(f, "no data: {msg}"),
132            SchemaFieldNotFound(msg) => write!(f, "field not found: {msg}"),
133            ShapeMismatch(msg) => write!(f, "lengths don't match: {msg}"),
134            StringCacheMismatch(msg) => write!(f, "string caches don't match: {msg}"),
135            StructFieldNotFound(msg) => write!(f, "field not found: {msg}"),
136            Context { error, msg } => write!(f, "{error}: {msg}"),
137            #[cfg(feature = "python")]
138            Python { error } => write!(f, "python: {}", error),
139        }
140    }
141}
142
143impl From<io::Error> for PolarsError {
144    fn from(value: io::Error) -> Self {
145        PolarsError::IO {
146            error: Arc::new(value),
147            msg: None,
148        }
149    }
150}
151
152#[cfg(feature = "regex")]
153impl From<regex::Error> for PolarsError {
154    fn from(err: regex::Error) -> Self {
155        PolarsError::ComputeError(format!("regex error: {err}").into())
156    }
157}
158
159#[cfg(feature = "object_store")]
160impl From<object_store::Error> for PolarsError {
161    fn from(err: object_store::Error) -> Self {
162        if let object_store::Error::Generic { store, source } = &err {
163            if let Some(polars_err) = source.as_ref().downcast_ref::<PolarsError>() {
164                return polars_err.wrap_msg(|s| format!("{} (store: {})", s, store));
165            }
166        }
167
168        std::io::Error::other(format!("object-store error: {}", err)).into()
169    }
170}
171
172#[cfg(feature = "avro-schema")]
173impl From<avro_schema::error::Error> for PolarsError {
174    fn from(value: avro_schema::error::Error) -> Self {
175        polars_err!(ComputeError: "avro-error: {}", value)
176    }
177}
178
179impl From<simdutf8::basic::Utf8Error> for PolarsError {
180    fn from(value: simdutf8::basic::Utf8Error) -> Self {
181        polars_err!(ComputeError: "invalid utf8: {}", value)
182    }
183}
184#[cfg(feature = "arrow-format")]
185impl From<arrow_format::ipc::planus::Error> for PolarsError {
186    fn from(err: arrow_format::ipc::planus::Error) -> Self {
187        polars_err!(ComputeError: "parquet error: {err:?}")
188    }
189}
190
191impl From<TryReserveError> for PolarsError {
192    fn from(value: TryReserveError) -> Self {
193        polars_err!(ComputeError: "OOM: {}", value)
194    }
195}
196
197impl From<Infallible> for PolarsError {
198    fn from(_: Infallible) -> Self {
199        unreachable!()
200    }
201}
202
203pub type PolarsResult<T> = Result<T, PolarsError>;
204
205impl PolarsError {
206    pub fn context_trace(self) -> Self {
207        use PolarsError::*;
208        match self {
209            Context { error, msg } => {
210                // If context is 1 level deep, just return error.
211                if !matches!(&*error, PolarsError::Context { .. }) {
212                    return *error;
213                }
214                let mut current_error = &*error;
215                let material_error = error.get_err();
216
217                let mut messages = vec![&msg];
218
219                while let PolarsError::Context { msg, error } = current_error {
220                    current_error = error;
221                    messages.push(msg)
222                }
223
224                let mut bt = String::new();
225
226                let mut count = 0;
227                while let Some(msg) = messages.pop() {
228                    count += 1;
229                    writeln!(&mut bt, "\t[{count}] {}", msg).unwrap();
230                }
231                material_error.wrap_msg(move |msg| {
232                    format!("{msg}\n\nThis error occurred with the following context stack:\n{bt}")
233                })
234            },
235            err => err,
236        }
237    }
238
239    pub fn wrap_msg<F: FnOnce(&str) -> String>(&self, func: F) -> Self {
240        use PolarsError::*;
241        match self {
242            AssertionError(msg) => AssertionError(func(msg).into()),
243            ColumnNotFound(msg) => ColumnNotFound(func(msg).into()),
244            ComputeError(msg) => ComputeError(func(msg).into()),
245            Duplicate(msg) => Duplicate(func(msg).into()),
246            InvalidOperation(msg) => InvalidOperation(func(msg).into()),
247            IO { error, msg } => {
248                let msg = match msg {
249                    Some(msg) => func(msg),
250                    None => func(&format!("{}", error)),
251                };
252                IO {
253                    error: error.clone(),
254                    msg: Some(msg.into()),
255                }
256            },
257            NoData(msg) => NoData(func(msg).into()),
258            OutOfBounds(msg) => OutOfBounds(func(msg).into()),
259            SchemaFieldNotFound(msg) => SchemaFieldNotFound(func(msg).into()),
260            SchemaMismatch(msg) => SchemaMismatch(func(msg).into()),
261            ShapeMismatch(msg) => ShapeMismatch(func(msg).into()),
262            StringCacheMismatch(msg) => StringCacheMismatch(func(msg).into()),
263            StructFieldNotFound(msg) => StructFieldNotFound(func(msg).into()),
264            SQLInterface(msg) => SQLInterface(func(msg).into()),
265            SQLSyntax(msg) => SQLSyntax(func(msg).into()),
266            Context { error, .. } => error.wrap_msg(func),
267            #[cfg(feature = "python")]
268            Python { error } => pyo3::Python::with_gil(|py| {
269                use pyo3::types::{PyAnyMethods, PyStringMethods};
270                use pyo3::{IntoPyObject, PyErr};
271
272                let value = error.value(py);
273
274                let msg = if let Ok(s) = value.str() {
275                    func(&s.to_string_lossy())
276                } else {
277                    func("<exception str() failed>")
278                };
279
280                let cls = value.get_type();
281
282                let out = PyErr::from_type(cls, (msg,));
283
284                let out = if let Ok(out_with_traceback) = (|| {
285                    out.clone_ref(py)
286                        .into_pyobject(py)?
287                        .getattr("with_traceback")
288                        .unwrap()
289                        .call1((value.getattr("__traceback__").unwrap(),))
290                })() {
291                    PyErr::from_value(out_with_traceback)
292                } else {
293                    out
294                };
295
296                Python {
297                    error: python::PyErrWrap(out),
298                }
299            }),
300        }
301    }
302
303    fn get_err(&self) -> &Self {
304        use PolarsError::*;
305        match self {
306            Context { error, .. } => error.get_err(),
307            err => err,
308        }
309    }
310
311    pub fn context(self, msg: ErrString) -> Self {
312        PolarsError::Context {
313            msg,
314            error: Box::new(self),
315        }
316    }
317}
318
319pub fn map_err<E: Error>(error: E) -> PolarsError {
320    PolarsError::ComputeError(format!("{error}").into())
321}
322
323#[macro_export]
324macro_rules! polars_err {
325    ($variant:ident: $fmt:literal $(, $arg:expr)* $(,)?) => {
326        $crate::__private::must_use(
327            $crate::PolarsError::$variant(format!($fmt, $($arg),*).into())
328        )
329    };
330    ($variant:ident: $err:expr $(,)?) => {
331        $crate::__private::must_use(
332            $crate::PolarsError::$variant($err.into())
333        )
334    };
335    (expr = $expr:expr, $variant:ident: $err:expr $(,)?) => {
336        $crate::__private::must_use(
337            $crate::PolarsError::$variant(
338                format!("{}\n\nError originated in expression: '{:?}'", $err, $expr).into()
339            )
340        )
341    };
342    (expr = $expr:expr, $variant:ident: $fmt:literal, $($arg:tt)+) => {
343        polars_err!(expr = $expr, $variant: format!($fmt, $($arg)+))
344    };
345    (op = $op:expr, got = $arg:expr, expected = $expected:expr) => {
346        $crate::polars_err!(
347            InvalidOperation: "{} operation not supported for dtype `{}` (expected: {})",
348            $op, $arg, $expected
349        )
350    };
351    (opq = $op:ident, got = $arg:expr, expected = $expected:expr) => {
352        $crate::polars_err!(
353            op = concat!("`", stringify!($op), "`"), got = $arg, expected = $expected
354        )
355    };
356    (un_impl = $op:ident) => {
357        $crate::polars_err!(
358            InvalidOperation: "{} operation is not implemented.", concat!("`", stringify!($op), "`")
359        )
360    };
361    (op = $op:expr, $arg:expr) => {
362        $crate::polars_err!(
363            InvalidOperation: "{} operation not supported for dtype `{}`", $op, $arg
364        )
365    };
366    (op = $op:expr, $arg:expr, hint = $hint:literal) => {
367        $crate::polars_err!(
368            InvalidOperation: "{} operation not supported for dtype `{}`\n\nHint: {}", $op, $arg, $hint
369        )
370    };
371    (op = $op:expr, $lhs:expr, $rhs:expr) => {
372        $crate::polars_err!(
373            InvalidOperation: "{} operation not supported for dtypes `{}` and `{}`", $op, $lhs, $rhs
374        )
375    };
376    (op = $op:expr, $arg1:expr, $arg2:expr, $arg3:expr) => {
377        $crate::polars_err!(
378            InvalidOperation: "{} operation not supported for dtypes `{}`, `{}` and `{}`", $op, $arg1, $arg2, $arg3
379        )
380    };
381    (oos = $($tt:tt)+) => {
382        $crate::polars_err!(ComputeError: "out-of-spec: {}", $($tt)+)
383    };
384    (nyi = $($tt:tt)+) => {
385        $crate::polars_err!(ComputeError: "not yet implemented: {}", format!($($tt)+) )
386    };
387    (opq = $op:ident, $arg:expr) => {
388        $crate::polars_err!(op = concat!("`", stringify!($op), "`"), $arg)
389    };
390    (opq = $op:ident, $lhs:expr, $rhs:expr) => {
391        $crate::polars_err!(op = stringify!($op), $lhs, $rhs)
392    };
393    (bigidx, ctx = $ctx:expr, size = $size:expr) => {
394        $crate::polars_err!(ComputeError: "\
395{} produces {} rows which is more than maximum allowed pow(2, 32) rows; \
396consider compiling with bigidx feature (polars-u64-idx package on python)",
397            $ctx,
398            $size,
399        )
400    };
401    (append) => {
402        polars_err!(SchemaMismatch: "cannot append series, data types don't match")
403    };
404    (extend) => {
405        polars_err!(SchemaMismatch: "cannot extend series, data types don't match")
406    };
407    (unpack) => {
408        polars_err!(SchemaMismatch: "cannot unpack series, data types don't match")
409    };
410    (not_in_enum,value=$value:expr,categories=$categories:expr) =>{
411        polars_err!(ComputeError: "value '{}' is not present in Enum: {:?}",$value,$categories)
412    };
413    (string_cache_mismatch) => {
414        polars_err!(StringCacheMismatch: r#"
415cannot compare categoricals coming from different sources, consider setting a global StringCache.
416
417Help: if you're using Python, this may look something like:
418
419    with pl.StringCache():
420        df1 = pl.DataFrame({'a': ['1', '2']}, schema={'a': pl.Categorical})
421        df2 = pl.DataFrame({'a': ['1', '3']}, schema={'a': pl.Categorical})
422        pl.concat([df1, df2])
423
424Alternatively, if the performance cost is acceptable, you could just set:
425
426    import polars as pl
427    pl.enable_string_cache()
428
429on startup."#.trim_start())
430    };
431    (duplicate = $name:expr) => {
432        $crate::polars_err!(Duplicate: "column with name '{}' has more than one occurrence", $name)
433    };
434    (col_not_found = $name:expr) => {
435        $crate::polars_err!(ColumnNotFound: "{:?} not found", $name)
436    };
437    (mismatch, col=$name:expr, expected=$expected:expr, found=$found:expr) => {
438        $crate::polars_err!(
439            SchemaMismatch: "data type mismatch for column {}: expected: {}, found: {}",
440            $name,
441            $expected,
442            $found,
443        )
444    };
445    (oob = $idx:expr, $len:expr) => {
446        polars_err!(OutOfBounds: "index {} is out of bounds for sequence of length {}", $idx, $len)
447    };
448    (agg_len = $agg_len:expr, $groups_len:expr) => {
449        polars_err!(
450            ComputeError:
451            "returned aggregation is of different length: {} than the groups length: {}",
452            $agg_len, $groups_len
453        )
454    };
455    (parse_fmt_idk = $dtype:expr) => {
456        polars_err!(
457            ComputeError: "could not find an appropriate format to parse {}s, please define a format",
458            $dtype,
459        )
460    };
461    (length_mismatch = $operation:expr, $lhs:expr, $rhs:expr) => {
462        $crate::polars_err!(
463            ShapeMismatch: "arguments for `{}` have different lengths ({} != {})",
464            $operation, $lhs, $rhs
465        )
466    };
467    (length_mismatch = $operation:expr, $lhs:expr, $rhs:expr, argument = $argument:expr, argument_idx = $argument_idx:expr) => {
468        $crate::polars_err!(
469            ShapeMismatch: "argument {} called '{}' for `{}` have different lengths ({} != {})",
470            $argument_idx, $argument, $operation, $lhs, $rhs
471        )
472    };
473    (assertion_error = $objects:expr, $detail:expr, $lhs:expr, $rhs:expr) => {
474        $crate::polars_err!(
475            AssertionError: "{} are different ({})\n[left]: {}\n[right]: {}",
476            $objects, $detail, $lhs, $rhs
477        )
478    };
479}
480
481#[macro_export]
482macro_rules! polars_bail {
483    ($($tt:tt)+) => {
484        return Err($crate::polars_err!($($tt)+))
485    };
486}
487
488#[macro_export]
489macro_rules! polars_ensure {
490    ($cond:expr, $($tt:tt)+) => {
491        if !$cond {
492            $crate::polars_bail!($($tt)+);
493        }
494    };
495}
496
497#[inline]
498#[cold]
499#[must_use]
500pub fn to_compute_err(err: impl Display) -> PolarsError {
501    PolarsError::ComputeError(err.to_string().into())
502}
503
504#[macro_export]
505macro_rules! feature_gated {
506    ($($feature:literal);*, $content:expr) => {{
507        #[cfg(all($(feature = $feature),*))]
508        {
509            $content
510        }
511        #[cfg(not(all($(feature = $feature),*)))]
512        {
513            panic!("activate '{}' feature", concat!($($feature, ", "),*))
514        }
515    }};
516}
517
518// Not public, referenced by macros only.
519#[doc(hidden)]
520pub mod __private {
521    #[doc(hidden)]
522    #[inline]
523    #[cold]
524    #[must_use]
525    pub fn must_use(error: crate::PolarsError) -> crate::PolarsError {
526        error
527    }
528}
polars_error/lib.rs

polars_error/
lib.rs
