0
# Error Handling and Exceptions
1
2
Comprehensive exception hierarchy for handling data errors, computation failures, and I/O issues with specific error types for precise error handling and debugging in data processing workflows.
3
4
## Capabilities
5
6
### Base Exception Classes
7
8
Foundation exception classes that all Polars errors inherit from.
9
10
```python { .api }
11
class PolarsError(Exception):
12
"""Base class for all Polars-related errors."""
13
14
class PolarsIoError(PolarsError):
15
"""Error related to I/O operations (file reading, writing, network)."""
16
17
class PolarsPanicError(PolarsError):
18
"""Error due to internal panic in Rust code."""
19
```
20
21
### Data and Schema Errors
22
23
Errors related to data validation, schema mismatches, and structural issues.
24
25
```python { .api }
26
class ColumnNotFoundError(PolarsError):
27
"""Error when referencing non-existent column."""
28
29
class SchemaError(PolarsError):
30
"""Error related to DataFrame schema validation."""
31
32
class SchemaFieldNotFoundError(SchemaError):
33
"""Error when accessing non-existent schema field."""
34
35
class DataTypeError(PolarsError):
36
"""Error related to data type operations and casting."""
37
38
class ShapeError(PolarsError):
39
"""Error due to incompatible DataFrame shapes."""
40
41
class DuplicateError(PolarsError):
42
"""Error due to duplicate data or operations."""
43
44
class StructFieldNotFoundError(PolarsError):
45
"""Error when accessing non-existent struct field."""
46
```
47
48
### Computation Errors
49
50
Errors that occur during data processing and computation operations.
51
52
```python { .api }
53
class ComputeError(PolarsError):
54
"""General computation error during data processing."""
55
56
class InvalidOperationError(PolarsError):
57
"""Error due to invalid operation on data."""
58
```
59
60
### SQL-Related Errors
61
62
Errors specific to SQL interface operations and query execution.
63
64
```python { .api }
65
class SQLInterfaceError(PolarsError):
66
"""Error in SQL interface operations."""
67
68
class SQLSyntaxError(PolarsError):
69
"""Error due to invalid SQL syntax."""
70
```
71
72
### Warning Classes
73
74
Warning types for non-fatal issues and performance notifications.
75
76
```python { .api }
77
class PolarsWarning(UserWarning):
78
"""Base class for Polars warnings."""
79
80
class PerformanceWarning(PolarsWarning):
81
"""Warning about potential performance issues."""
82
83
class CategoricalRemappingWarning(PolarsWarning):
84
"""Warning when categorical values are remapped."""
85
```
86
87
## Usage Examples
88
89
### Exception Handling Patterns
90
91
```python
92
import polars as pl
93
from polars.exceptions import (
94
ColumnNotFoundError,
95
SchemaError,
96
ComputeError,
97
DataTypeError
98
)
99
100
df = pl.DataFrame({
101
"name": ["Alice", "Bob", "Charlie"],
102
"age": [25, 30, 35]
103
})
104
105
# Handle column not found
106
try:
107
result = df.select("nonexistent_column")
108
except ColumnNotFoundError as e:
109
print(f"Column error: {e}")
110
# Fallback to available columns
111
result = df.select("name")
112
113
# Handle data type errors
114
try:
115
result = df.with_columns(
116
pl.col("name").cast(pl.Int32) # Invalid cast
117
)
118
except DataTypeError as e:
119
print(f"Type conversion error: {e}")
120
# Use appropriate type
121
result = df.with_columns(
122
pl.col("age").cast(pl.String).alias("age_str")
123
)
124
```
125
126
### Schema Validation
127
128
```python
129
# Handle schema mismatches
130
try:
131
schema = pl.Schema({
132
"name": pl.String,
133
"age": pl.Int32,
134
"salary": pl.Float64 # Required field
135
})
136
137
df_with_schema = pl.DataFrame({
138
"name": ["Alice"],
139
"age": [25]
140
# Missing salary column
141
}, schema=schema)
142
143
except SchemaError as e:
144
print(f"Schema validation failed: {e}")
145
# Create DataFrame with complete schema
146
df_with_schema = pl.DataFrame({
147
"name": ["Alice"],
148
"age": [25],
149
"salary": [50000.0]
150
}, schema=schema)
151
```
152
153
### I/O Error Handling
154
155
```python
156
# Handle file I/O errors
157
try:
158
df = pl.read_csv("nonexistent_file.csv")
159
except PolarsIoError as e:
160
print(f"I/O error: {e}")
161
# Create empty DataFrame or use default data
162
df = pl.DataFrame({"col1": [], "col2": []})
163
164
# Handle network/cloud storage errors
165
try:
166
df = pl.read_parquet("s3://bucket/file.parquet")
167
except PolarsIoError as e:
168
print(f"Network/storage error: {e}")
169
# Retry with local file or alternative source
170
df = pl.read_parquet("local_backup.parquet")
171
```
172
173
### Computation Error Recovery
174
175
```python
176
# Handle computation errors gracefully
177
try:
178
result = df.with_columns([
179
(pl.col("age") / 0).alias("invalid_division") # Division by zero
180
])
181
except ComputeError as e:
182
print(f"Computation error: {e}")
183
# Use safe computation
184
result = df.with_columns([
185
pl.when(pl.col("age") > 0)
186
.then(100.0 / pl.col("age"))
187
.otherwise(None)
188
.alias("safe_division")
189
])
190
```
191
192
### SQL Error Handling
193
194
```python
195
from polars.exceptions import SQLSyntaxError, SQLInterfaceError
196
197
# Handle SQL syntax errors
198
try:
199
result = pl.sql("SELCT * FROM df", df=df) # Typo in SELECT
200
except SQLSyntaxError as e:
201
print(f"SQL syntax error: {e}")
202
# Use correct syntax
203
result = pl.sql("SELECT * FROM df", df=df)
204
205
# Handle SQL interface errors
206
try:
207
ctx = pl.SQLContext()
208
result = ctx.execute("SELECT * FROM nonexistent_table")
209
except SQLInterfaceError as e:
210
print(f"SQL interface error: {e}")
211
# Register table first
212
ctx.register("my_table", df)
213
result = ctx.execute("SELECT * FROM my_table")
214
```
215
216
### Warning Handling
217
218
```python
219
import warnings
220
from polars.exceptions import PerformanceWarning, CategoricalRemappingWarning
221
222
# Filter specific warnings
223
warnings.filterwarnings("ignore", category=PerformanceWarning)
224
225
# Or handle warnings as exceptions
226
warnings.filterwarnings("error", category=CategoricalRemappingWarning)
227
228
try:
229
# Operation that might trigger categorical remapping
230
df_cat = pl.DataFrame({
231
"category": ["A", "B", "C"]
232
}).with_columns(
233
pl.col("category").cast(pl.Categorical)
234
)
235
236
# This might trigger remapping warning
237
result = df_cat.with_columns(
238
pl.col("category").cat.set_ordering("lexical")
239
)
240
241
except CategoricalRemappingWarning as w:
242
print(f"Categorical warning treated as error: {w}")
243
# Handle the warning case
244
```
245
246
### Comprehensive Error Handling
247
248
```python
249
def safe_dataframe_operation(df, operation_func):
250
"""Safely execute DataFrame operation with comprehensive error handling."""
251
try:
252
return operation_func(df)
253
except ColumnNotFoundError:
254
print("Column not found - using available columns")
255
return df.select(df.columns[:3]) # Use first 3 columns
256
except DataTypeError:
257
print("Data type error - converting to string")
258
return df.with_columns(pl.all().cast(pl.String))
259
except SchemaError:
260
print("Schema error - using flexible schema")
261
return df
262
except ComputeError as e:
263
print(f"Computation failed: {e}")
264
return df.head(0) # Return empty DataFrame with same schema
265
except PolarsIoError as e:
266
print(f"I/O error: {e}")
267
return None
268
except PolarsError as e:
269
print(f"General Polars error: {e}")
270
return df
271
except Exception as e:
272
print(f"Unexpected error: {e}")
273
return None
274
275
# Usage
276
def risky_operation(df):
277
return df.select("nonexistent_col").with_columns(
278
pl.col("name").cast(pl.Int32)
279
)
280
281
result = safe_dataframe_operation(df, risky_operation)
282
```