tessl/pypi-polars

Blazingly fast DataFrame library for Python with lazy and eager evaluation modes

—

Pending

Overview

Eval results

Files

Error Handling and Exceptions

Name: tessl/pypi-polars
Author: tessl

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.

Capabilities

Base Exception Classes

Foundation exception classes that all Polars errors inherit from.

class PolarsError(Exception):
    """Base class for all Polars-related errors."""

class PolarsIoError(PolarsError):
    """Error related to I/O operations (file reading, writing, network)."""

class PolarsPanicError(PolarsError):
    """Error due to internal panic in Rust code."""

Data and Schema Errors

Errors related to data validation, schema mismatches, and structural issues.

class ColumnNotFoundError(PolarsError):
    """Error when referencing non-existent column."""

class SchemaError(PolarsError):
    """Error related to DataFrame schema validation."""

class SchemaFieldNotFoundError(SchemaError):
    """Error when accessing non-existent schema field."""

class DataTypeError(PolarsError):
    """Error related to data type operations and casting."""

class ShapeError(PolarsError):
    """Error due to incompatible DataFrame shapes."""

class DuplicateError(PolarsError):
    """Error due to duplicate data or operations."""

class StructFieldNotFoundError(PolarsError):
    """Error when accessing non-existent struct field."""

Computation Errors

Errors that occur during data processing and computation operations.

class ComputeError(PolarsError):
    """General computation error during data processing."""

class InvalidOperationError(PolarsError):
    """Error due to invalid operation on data."""

SQL-Related Errors

Errors specific to SQL interface operations and query execution.

class SQLInterfaceError(PolarsError):
    """Error in SQL interface operations."""

class SQLSyntaxError(PolarsError):
    """Error due to invalid SQL syntax."""

Warning Classes

Warning types for non-fatal issues and performance notifications.

class PolarsWarning(UserWarning):
    """Base class for Polars warnings."""

class PerformanceWarning(PolarsWarning):
    """Warning about potential performance issues."""

class CategoricalRemappingWarning(PolarsWarning):
    """Warning when categorical values are remapped."""

Usage Examples

Exception Handling Patterns

import polars as pl
from polars.exceptions import (
    ColumnNotFoundError, 
    SchemaError, 
    ComputeError,
    DataTypeError
)

df = pl.DataFrame({
    "name": ["Alice", "Bob", "Charlie"],
    "age": [25, 30, 35]
})

# Handle column not found
try:
    result = df.select("nonexistent_column")
except ColumnNotFoundError as e:
    print(f"Column error: {e}")
    # Fallback to available columns
    result = df.select("name")

# Handle data type errors
try:
    result = df.with_columns(
        pl.col("name").cast(pl.Int32)  # Invalid cast
    )
except DataTypeError as e:
    print(f"Type conversion error: {e}")
    # Use appropriate type
    result = df.with_columns(
        pl.col("age").cast(pl.String).alias("age_str")
    )

Schema Validation

# Handle schema mismatches
try:
    schema = pl.Schema({
        "name": pl.String,
        "age": pl.Int32,
        "salary": pl.Float64  # Required field
    })
    
    df_with_schema = pl.DataFrame({
        "name": ["Alice"],
        "age": [25]
        # Missing salary column
    }, schema=schema)
    
except SchemaError as e:
    print(f"Schema validation failed: {e}")
    # Create DataFrame with complete schema
    df_with_schema = pl.DataFrame({
        "name": ["Alice"],
        "age": [25],
        "salary": [50000.0]
    }, schema=schema)

I/O Error Handling

# Handle file I/O errors
try:
    df = pl.read_csv("nonexistent_file.csv")
except PolarsIoError as e:
    print(f"I/O error: {e}")
    # Create empty DataFrame or use default data
    df = pl.DataFrame({"col1": [], "col2": []})

# Handle network/cloud storage errors
try:
    df = pl.read_parquet("s3://bucket/file.parquet")
except PolarsIoError as e:
    print(f"Network/storage error: {e}")
    # Retry with local file or alternative source
    df = pl.read_parquet("local_backup.parquet")

Computation Error Recovery

# Handle computation errors gracefully
try:
    result = df.with_columns([
        (pl.col("age") / 0).alias("invalid_division")  # Division by zero
    ])
except ComputeError as e:
    print(f"Computation error: {e}")
    # Use safe computation
    result = df.with_columns([
        pl.when(pl.col("age") > 0)
        .then(100.0 / pl.col("age"))
        .otherwise(None)
        .alias("safe_division")
    ])

SQL Error Handling

from polars.exceptions import SQLSyntaxError, SQLInterfaceError

# Handle SQL syntax errors
try:
    result = pl.sql("SELCT * FROM df", df=df)  # Typo in SELECT
except SQLSyntaxError as e:
    print(f"SQL syntax error: {e}")
    # Use correct syntax
    result = pl.sql("SELECT * FROM df", df=df)

# Handle SQL interface errors
try:
    ctx = pl.SQLContext()
    result = ctx.execute("SELECT * FROM nonexistent_table")
except SQLInterfaceError as e:
    print(f"SQL interface error: {e}")
    # Register table first
    ctx.register("my_table", df)
    result = ctx.execute("SELECT * FROM my_table")

Warning Handling

import warnings
from polars.exceptions import PerformanceWarning, CategoricalRemappingWarning

# Filter specific warnings
warnings.filterwarnings("ignore", category=PerformanceWarning)

# Or handle warnings as exceptions
warnings.filterwarnings("error", category=CategoricalRemappingWarning)

try:
    # Operation that might trigger categorical remapping
    df_cat = pl.DataFrame({
        "category": ["A", "B", "C"]
    }).with_columns(
        pl.col("category").cast(pl.Categorical)
    )
    
    # This might trigger remapping warning
    result = df_cat.with_columns(
        pl.col("category").cat.set_ordering("lexical")
    )
    
except CategoricalRemappingWarning as w:
    print(f"Categorical warning treated as error: {w}")
    # Handle the warning case

Comprehensive Error Handling

def safe_dataframe_operation(df, operation_func):
    """Safely execute DataFrame operation with comprehensive error handling."""
    try:
        return operation_func(df)
    except ColumnNotFoundError:
        print("Column not found - using available columns")
        return df.select(df.columns[:3])  # Use first 3 columns
    except DataTypeError:
        print("Data type error - converting to string")
        return df.with_columns(pl.all().cast(pl.String))
    except SchemaError:
        print("Schema error - using flexible schema")
        return df
    except ComputeError as e:
        print(f"Computation failed: {e}")
        return df.head(0)  # Return empty DataFrame with same schema
    except PolarsIoError as e:
        print(f"I/O error: {e}")
        return None
    except PolarsError as e:
        print(f"General Polars error: {e}")
        return df
    except Exception as e:
        print(f"Unexpected error: {e}")
        return None

# Usage
def risky_operation(df):
    return df.select("nonexistent_col").with_columns(
        pl.col("name").cast(pl.Int32)
    )

result = safe_dataframe_operation(df, risky_operation)

Install with Tessl CLI