Warnings

errortools provides structured warning classes with factory methods for common warning types.

BaseWarning

Base class for all structured warnings.

from errortools import BaseWarning

class ExperimentalWarning(BaseWarning):
    default_detail = "This feature is experimental"

# Emit with default message
ExperimentalWarning.emit()

# Emit with custom message
ExperimentalWarning.emit("use at your own risk")

Factory methods

BaseWarning provides factory methods for common warning types:

from errortools import BaseWarning

# Deprecation warning
BaseWarning.deprecated("use new_api() instead").emit()

# Performance warning
BaseWarning.performance("O(n²) detected").emit()

# Resource usage warning
BaseWarning.resource("file handle leak").emit()

# Runtime behaviour warning
BaseWarning.runtime_behaviour("unexpected state").emit()

# Configuration warning
BaseWarning.configuration("missing optional key").emit()

Predefined warning classes

DeprecatedWarning

For deprecated features:

from errortools import DeprecatedWarning

DeprecatedWarning.emit("old_function() is deprecated, use new_function()")

PerformanceWarning

For performance concerns:

from errortools import PerformanceWarning

PerformanceWarning.emit("Large dataset detected, consider pagination")

ResourceUsageWarning

For resource usage issues:

from errortools import ResourceUsageWarning

ResourceUsageWarning.emit("Memory usage exceeds 80%")

RuntimeBehaviourWarning

For unexpected runtime behaviour:

from errortools import RuntimeBehaviourWarning

RuntimeBehaviourWarning.emit("Fallback to default configuration")

ConfigurationWarning

For configuration issues:

from errortools import ConfigurationWarning

ConfigurationWarning.emit("Optional setting 'debug' not found")

Suppressing warnings

Use ignore_warns() to suppress warnings:

from errortools import ignore_warns, DeprecatedWarning

with ignore_warns(DeprecatedWarning):
    DeprecatedWarning.emit("old api")  # Suppressed

with ignore_warns():  # Suppress all warnings
    DeprecatedWarning.emit("anything")

Integration with @deprecated and @experimental

The warning classes integrate with the decorator utilities:

from errortools import deprecated, experimental

@deprecated("Use new_function() instead")
def old_function():
    pass  # Emits DeprecatedWarning when called

@experimental("This API may change")
def new_feature():
    pass  # Emits ExperimentalWarning when called