Skip to content

API Reference: Exceptions & Warnings

This page documents the custom warnings and exceptions in Diet Pandas.

Warning Classes

All Diet Pandas warnings inherit from DietPandasWarning, which inherits from UserWarning.

DietPandasWarning

Base class for all Diet Pandas warnings.

dietpandas.exceptions.DietPandasWarning

Bases: UserWarning

Base warning class for all Diet Pandas warnings.

Source code in src/dietpandas/exceptions.py 
 8
 9
10
11
class DietPandasWarning(UserWarning):
    """Base warning class for all Diet Pandas warnings."""

    pass

HighCardinalityWarning

Issued when attempting to convert a high-cardinality column to categorical.

dietpandas.exceptions.HighCardinalityWarning

Bases: DietPandasWarning

Warning raised when attempting to convert a high-cardinality column to category.

This warning suggests that categorical conversion may not be beneficial for columns with many unique values.

Source code in src/dietpandas/exceptions.py 
14
15
16
17
18
19
20
21
22
class HighCardinalityWarning(DietPandasWarning):
    """
    Warning raised when attempting to convert a high-cardinality column to category.

    This warning suggests that categorical conversion may not be beneficial
    for columns with many unique values.
    """

    pass

Example:

import pandas as pd
import dietpandas as dp
import warnings

df = pd.DataFrame({
    'id': range(10000)  # 10000 unique values in 10000 rows
})

# This will trigger a HighCardinalityWarning
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    dp.diet(df, warn_on_issues=True)

    if w:
        print(w[0].category)  # <class 'dietpandas.exceptions.HighCardinalityWarning'>
        print(w[0].message)   # "Column 'id' has high cardinality (100.0%)..."

PrecisionLossWarning

Issued when aggressive optimization may cause precision loss.

dietpandas.exceptions.PrecisionLossWarning

Bases: DietPandasWarning

Warning raised when aggressive optimization may cause precision loss.

This warning is raised when converting float64 to float16, which can result in loss of precision for values outside the float16 range.

Source code in src/dietpandas/exceptions.py 
25
26
27
28
29
30
31
32
33
class PrecisionLossWarning(DietPandasWarning):
    """
    Warning raised when aggressive optimization may cause precision loss.

    This warning is raised when converting float64 to float16, which can
    result in loss of precision for values outside the float16 range.
    """

    pass

Example:

import pandas as pd
import dietpandas as dp
import warnings

df = pd.DataFrame({
    'value': [1.123456789, 2.234567890, 3.345678901]
})

# Aggressive mode converts float64 -> float16, which may lose precision
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    dp.diet(df, aggressive=True, warn_on_issues=True)

    if w:
        print(w[0].category)  # <class 'dietpandas.exceptions.PrecisionLossWarning'>

OptimizationSkippedWarning

Issued when a column is skipped due to issues (e.g., all NaN values).

dietpandas.exceptions.OptimizationSkippedWarning

Bases: DietPandasWarning

Warning raised when optimization is skipped for a column.

This can occur when a column contains all NaN values or when optimization would not provide any benefit.

Source code in src/dietpandas/exceptions.py 
36
37
38
39
40
41
42
43
44
class OptimizationSkippedWarning(DietPandasWarning):
    """
    Warning raised when optimization is skipped for a column.

    This can occur when a column contains all NaN values or when
    optimization would not provide any benefit.
    """

    pass

Example:

import pandas as pd
import numpy as np
import dietpandas as dp
import warnings

df = pd.DataFrame({
    'good_col': [1, 2, 3],
    'empty_col': [np.nan, np.nan, np.nan]
})

with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    dp.diet(df, warn_on_issues=True)

    # Will warn about empty_col being all NaN
    for warning in w:
        if issubclass(warning.category, OptimizationSkippedWarning):
            print(warning.message)  # "Column 'empty_col' is entirely NaN..."

Exception Classes

OptimizationError

Raised when optimization fails unexpectedly.

dietpandas.exceptions.OptimizationError

Bases: Exception

Base exception class for Diet Pandas optimization errors.

Raised when an optimization operation fails and cannot be recovered.

Source code in src/dietpandas/exceptions.py 
47
48
49
50
51
52
53
54
class OptimizationError(Exception):
    """
    Base exception class for Diet Pandas optimization errors.

    Raised when an optimization operation fails and cannot be recovered.
    """

    pass

Example:

from dietpandas.exceptions import OptimizationError

try:
    # Some optimization operation
    result = optimize_something(data)
except OptimizationError as e:
    print(f"Optimization failed: {e}")
    # Handle the error appropriately

Controlling Warnings

Enable/Disable Warnings

import dietpandas as dp

# Enable warnings (default)
df = dp.diet(df, warn_on_issues=True)

# Disable warnings
df = dp.diet(df, warn_on_issues=False)

Filtering Specific Warnings

import warnings
from dietpandas.exceptions import HighCardinalityWarning, PrecisionLossWarning

# Ignore high cardinality warnings
warnings.filterwarnings('ignore', category=HighCardinalityWarning)

# Ignore precision loss warnings
warnings.filterwarnings('ignore', category=PrecisionLossWarning)

# Apply optimization
df = dp.diet(df, aggressive=True, warn_on_issues=True)

Treat Warnings as Errors

import warnings
from dietpandas.exceptions import PrecisionLossWarning

# Make precision loss warnings raise errors
warnings.filterwarnings('error', category=PrecisionLossWarning)

try:
    df = dp.diet(df, aggressive=True, warn_on_issues=True)
except PrecisionLossWarning as e:
    print(f"Cannot proceed: {e}")
    # Use non-aggressive mode instead
    df = dp.diet(df, aggressive=False)

Warning Messages

All warnings include: - Column name that triggered the warning - Specific issue detected - Actionable recommendation for how to address it

Example warning messages:

⚠️  HighCardinalityWarning: Column 'id' has high cardinality (98.5%) - 
    may not benefit from categorical conversion. Consider skip_columns=['id']

⚠️  PrecisionLossWarning: Aggressive mode on column 'measurement' may lose 
    precision (float64 -> float16). Verify acceptable for your use case.

⚠️  OptimizationSkippedWarning: Column 'empty' is entirely NaN - 
    consider dropping it with df.drop(columns=['empty'])

See Also