Error Handling

tif1 uses a structured exception hierarchy for graceful error handling. All exceptions inherit from TIF1Error, so a single clause catches every library-specific error.

Exception Hierarchy

Common Exceptions

DataNotFoundError

Raised when requested data does not exist in the archive.

import tif1
from tif1 import DataNotFoundError

try:
    session = tif1.get_session(2025, "Invalid GP", "Race")
except DataNotFoundError as e:
    print(f"Data not found: {e}")
    print(f"Context: {e.context}")  # Additional error details

Common causes:

Misspelled event name
The session has not started yet
Data not yet available in archive

Solution:

# Check available events first
events = tif1.get_events(2025)
if "Monaco Grand Prix" in events:
    session = tif1.get_session(2025, "Monaco Grand Prix", "Race")

DriverNotFoundError

Raised when code accesses a driver that does not exist in the session.

from tif1 import DriverNotFoundError

try:
    driver = session.get_driver("XXX")
except DriverNotFoundError as e:
    print(f"Driver not found: {e}")

Solution:

# Check available drivers first
# session.drivers lists driver numbers; drivers_df lists their abbreviations
available_drivers = session.drivers_df["Driver"].tolist()
if "VER" in available_drivers:
    driver = session.get_driver("VER")

NetworkError

Raised when all CDN sources fail or timeout.

from tif1 import NetworkError

try:
    session = tif1.get_session(2025, "Monaco Grand Prix", "Race")
    laps = session.laps
except NetworkError as e:
    print(f"Network error: {e}")
    # Check circuit breaker status
    cb = tif1.get_circuit_breaker()
    if cb.state == "open":
        print("Circuit breaker is open, too many failures")

Solutions:

Check internet connection
Verify the CDN sources (jsDelivr, Hugging Face, StaticDelivr) are accessible
Reset circuit breaker if needed
Enable debug logging to see which CDN failed

InvalidDataError

Raised when fetched data is corrupted or malformed.

from tif1 import InvalidDataError

try:
    laps = session.laps
except InvalidDataError as e:
    print(f"Invalid data: {e}")
    # Clear cache and retry
    tif1.get_cache().clear()

CacheError

Raised when cache operations fail.

from tif1 import CacheError

try:
    cache = tif1.get_cache()
    cache.clear()
except CacheError as e:
    print(f"Cache error: {e}")
    # Check permissions

Error handling patterns

Graceful Degradation

Handle errors without stopping the analysis.

def safe_load_session(year, gp, session_type):
    """Load session with fallback to None."""
    try:
        return tif1.get_session(year, gp, session_type)
    except DataNotFoundError:
        print(f"No data for {year} {gp} {session_type}")
        return None
    except NetworkError:
        print(f"Network error loading {year} {gp} {session_type}")
        return None

# Use it
session = safe_load_session(2025, "Monaco Grand Prix", "Race")
if session:
    laps = session.laps

Retry Logic

Implement custom retry for transient failures.

import time
from tif1 import NetworkError

def load_with_retry(year, gp, session_type, max_retries=3):
    """Load session with exponential backoff."""
    for attempt in range(max_retries):
        try:
            return tif1.get_session(year, gp, session_type)
        except NetworkError as e:
            if attempt == max_retries - 1:
                raise
            wait_time = 2 ** attempt
            print(f"Retry {attempt + 1}/{max_retries} in {wait_time}s...")
            time.sleep(wait_time)

Batch Processing

Handle errors when processing multiple sessions.

def process_season(year):
    """Process all races with error handling."""
    events = tif1.get_events(year)
    results = []
    errors = []

    for event in events:
        try:
            session = tif1.get_session(year, event, "Race")
            laps = session.laps

            # Process data
            result = {
                "event": event,
                "total_laps": len(laps),
                "fastest_lap": laps["LapTime"].min()
            }
            results.append(result)

        except Exception as e:
            errors.append({"event": event, "error": str(e)})
            continue

    return results, errors

# Use it
results, errors = process_season(2024)
print(f"Processed {len(results)} events, {len(errors)} errors")

Context Managers

Use context managers for resource cleanup.

class SessionContext:
    """Context manager for session loading."""

    def __init__(self, year, gp, session_type):
        self.year = year
        self.gp = gp
        self.session_type = session_type
        self.session = None

    def __enter__(self):
        try:
            self.session = tif1.get_session(
                self.year, self.gp, self.session_type
            )
            return self.session
        except Exception as e:
            print(f"Failed to load session: {e}")
            return None

    def __exit__(self, exc_type, exc_val, exc_tb):
        # Cleanup if needed
        if exc_type is not None:
            print(f"Error during processing: {exc_val}")
        return False

# Use it
with SessionContext(2025, "Monaco Grand Prix", "Race") as session:
    if session:
        laps = session.laps

Debugging Errors

Enable debug logging

See detailed information about the operations in progress.

import tif1
import logging

# Enable debug logging
tif1.setup_logging(logging.DEBUG)

# Now all operations show detailed logs
session = tif1.get_session(2025, "Monaco Grand Prix", "Race")

Inspect error context

All tif1 exceptions include context information.

try:
    session = tif1.get_session(2025, "Invalid GP", "Race")
except tif1.DataNotFoundError as e:
    print(f"Error: {e}")
    print(f"Context: {e.context}")
    # Context might include: year, gp, session, attempted_urls, etc.

Check circuit breaker

Monitor network health.

cb = tif1.get_circuit_breaker()
print(f"State: {cb.state}")
print(f"Failures: {cb.failures}")
print(f"Last failure: {cb.last_failure_time}")

# Reset if needed
if cb.state == "open":
    tif1.reset_circuit_breaker()

Best Practices

Validate Input

Check data availability before processing.

events = tif1.get_events(2025)
if "Monaco Grand Prix" in events:
    session = tif1.get_session(2025, "Monaco Grand Prix", "Race")

Use Specific Exceptions

Catch specific exceptions rather than broad Exception.

try:
    session = tif1.get_session(2025, "Monaco", "Race")
except tif1.DataNotFoundError:
    # Handle missing data
    pass
except tif1.NetworkError:
    # Handle network issues
    pass

Log Errors

Always log errors for debugging.

import logging
logger = logging.getLogger(__name__)

try:
    session = tif1.get_session(2025, "Monaco", "Race")
except Exception as e:
    logger.error(f"Failed to load session: {e}", exc_info=True)

Fail Fast

Do not continue processing when critical data is missing.

session = tif1.get_session(2025, "Monaco", "Race")
if session is None:
    raise ValueError("Cannot proceed without session data")

Production Patterns

Health Checks

Monitor tif1 health in production.

def check_tif1_health():
    """Check if tif1 is operational."""
    try:
        # Try to get events (lightweight operation)
        events = tif1.get_events(2024)

        # Check circuit breaker
        cb = tif1.get_circuit_breaker()
        if cb.state == "open":
            return False, "Circuit breaker is open"

        # Check cache
        cache = tif1.get_cache()
        if not cache.cache_dir.exists():
            return False, "Cache directory missing"

        return True, "Healthy"
    except Exception as e:
        return False, str(e)

Monitoring

Track errors and performance.

import time
from collections import defaultdict

class TIF1Monitor:
    """Monitor tif1 operations."""

    def __init__(self):
        self.errors = defaultdict(int)
        self.timings = []

    def load_session(self, year, gp, session_type):
        """Load session with monitoring."""
        start = time.time()
        try:
            session = tif1.get_session(year, gp, session_type)
            duration = time.time() - start
            self.timings.append(duration)
            return session
        except Exception as e:
            self.errors[type(e).__name__] += 1
            raise

    def report(self):
        """Generate monitoring report."""
        return {
            "total_errors": sum(self.errors.values()),
            "errors_by_type": dict(self.errors),
            "avg_load_time": sum(self.timings) / len(self.timings) if self.timings else 0,
            "max_load_time": max(self.timings) if self.timings else 0
        }

Summary

Proper error handling makes tif1 applications robust and maintainable. Always use specific exceptions, validate input, and add retry logic for production use.

Exceptions API

Exception reference

Troubleshooting

Common issues

Best Practices

Recommended patterns

Get Started

Guides

Concepts

Reference

Error Handling

Exception Hierarchy

Common Exceptions

DataNotFoundError

DriverNotFoundError

NetworkError

InvalidDataError

CacheError

Error handling patterns

Graceful Degradation

Retry Logic

Batch Processing

Context Managers

Debugging Errors

Enable debug logging

Inspect error context

Check circuit breaker

Best Practices

Production Patterns

Health Checks

Monitoring

Summary

Exceptions API

Troubleshooting

Best Practices

​Exception Hierarchy

​Common Exceptions

​DataNotFoundError

​DriverNotFoundError

​NetworkError

​InvalidDataError

​CacheError

​Error handling patterns

​Graceful Degradation

​Retry Logic

​Batch Processing

​Context Managers

​Debugging Errors

​Enable debug logging

​Inspect error context

​Check circuit breaker

​Best Practices

​Production Patterns

​Health Checks

​Monitoring

​Summary

​Related Pages

Exceptions API

Troubleshooting

Best Practices

Exception Hierarchy

Common Exceptions

DataNotFoundError

DriverNotFoundError

NetworkError

InvalidDataError

CacheError

Error handling patterns

Graceful Degradation

Retry Logic

Batch Processing

Context Managers

Debugging Errors

Enable debug logging

Inspect error context

Check circuit breaker

Best Practices

Production Patterns

Health Checks

Monitoring

Summary

Related Pages