"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = { code: "code", p: "p", ..._provideComponents(), ...props.components }, {Heading, Mermaid} = _components; if (!Heading) _missingMdxReference("Heading", true); if (!Mermaid) _missingMdxReference("Mermaid", true); return _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["tif1 uses a structured exception hierarchy to help you handle errors gracefully. All exceptions inherit from ", _jsx(_components.code, { children: "TIF1Error" }), ", making it easy to catch all library-specific errors."] }), "\n", _jsx(Heading, { level: "2", id: "exception-hierarchy", children: "Exception Hierarchy" }), "\n", _jsx(Mermaid, { chart: "graph TD\n TIF1Error[TIF1Error
Base Exception]\n\n TIF1Error --> DataNotFoundError\n TIF1Error --> NetworkError\n TIF1Error --> InvalidDataError\n TIF1Error --> CacheError\n TIF1Error --> SessionNotLoadedError\n\n DataNotFoundError --> DriverNotFoundError\n DataNotFoundError --> LapNotFoundError\n\n style TIF1Error fill:#339af0\n style DataNotFoundError fill:#ff6b6b\n style NetworkError fill:#ff6b6b\n style DriverNotFoundError fill:#ffa94d\n style LapNotFoundError fill:#ffa94d\n```python\n\n## Common Exceptions\n\n### DataNotFoundError\n\nRaised when requested data doesn't exist in the archive.\n\n```python\nimport tif1\nfrom tif1 import DataNotFoundError\n\ntry:\n session = tif1.get_session(2025, \"Invalid GP\", \"Race\")\nexcept DataNotFoundError as e:\n print(f\"Data not found: {e}\")\n print(f\"Context: {e.context}\") # Additional error details\n```python\n\n**Common causes:**\n- Misspelled event name\n- Session hasn't happened yet\n- Data not yet available in archive\n\n**Solution:**\n```python\n# Check available events first\nevents = tif1.get_events(2025)\nif \"Monaco Grand Prix\" in events:\n session = tif1.get_session(2025, \"Monaco Grand Prix\", \"Race\")\n```python\n\n### DriverNotFoundError\n\nRaised when accessing a driver that doesn't exist in the session.\n\n```python\nfrom tif1 import DriverNotFoundError\n\ntry:\n driver = session.get_driver(\"XXX\")\nexcept DriverNotFoundError as e:\n print(f\"Driver not found: {e}\")\n```python\n\n**Solution:**\n```python\n# Check available drivers first\navailable_drivers = [d[\"driver\"] for d in session.drivers]\nif \"VER\" in available_drivers:\n driver = session.get_driver(\"VER\")\n```python\n\n### NetworkError\n\nRaised when all CDN sources fail or timeout.\n\n```python\nfrom tif1 import NetworkError\n\ntry:\n session = tif1.get_session(2025, \"Monaco Grand Prix\", \"Race\")\n laps = session.laps\nexcept NetworkError as e:\n print(f\"Network error: {e}\")\n # Check circuit breaker status\n cb = tif1.get_circuit_breaker()\n if cb.state == \"open\":\n print(\"Circuit breaker is open, too many failures\")\n```python\n\n**Solutions:**\n- Check internet connection\n- Verify jsDelivr CDN is accessible\n- Reset circuit breaker if needed\n- Enable debug logging to see which CDN failed\n\n### InvalidDataError\n\nRaised when fetched data is corrupted or malformed.\n\n```python\nfrom tif1 import InvalidDataError\n\ntry:\n laps = session.laps\nexcept InvalidDataError as e:\n print(f\"Invalid data: {e}\")\n # Clear cache and retry\n tif1.get_cache().clear()\n```python\n\n### CacheError\n\nRaised when cache operations fail.\n\n```python\nfrom tif1 import CacheError\n\ntry:\n cache = tif1.get_cache()\n cache.clear()\nexcept CacheError as e:\n print(f\"Cache error: {e}\")\n # Check permissions\n```text ## Error handling patterns\n\n### Graceful Degradation\n\nHandle errors without crashing your analysis.\n\n```python\ndef safe_load_session(year, gp, session_type):\n \"\"\"Load session with fallback to None.\"\"\"\n try:\n return tif1.get_session(year, gp, session_type)\n except DataNotFoundError:\n print(f\"No data for {year} {gp} {session_type}\")\n return None\n except NetworkError:\n print(f\"Network error loading {year} {gp} {session_type}\")\n return None\n\n# Use it\nsession = safe_load_session(2025, \"Monaco Grand Prix\", \"Race\")\nif session:\n laps = session.laps\n```python\n\n### Retry Logic\n\nImplement custom retry for transient failures.\n\n```python\nimport time\nfrom tif1 import NetworkError\n\ndef load_with_retry(year, gp, session_type, max_retries=3):\n \"\"\"Load session with exponential backoff.\"\"\"\n for attempt in range(max_retries):\n try:\n return tif1.get_session(year, gp, session_type)\n except NetworkError as e:\n if attempt == max_retries - 1:\n raise\n wait_time = 2 ** attempt\n print(f\"Retry {attempt + 1}/{max_retries} in {wait_time}s...\")\n time.sleep(wait_time)\n```python\n\n### Batch Processing\n\nHandle errors when processing multiple sessions.\n\n```python\ndef process_season(year):\n \"\"\"Process all races with error handling.\"\"\"\n events = tif1.get_events(year)\n results = []\n errors = []\n\n for event in events:\n try:\n session = tif1.get_session(year, event, \"Race\")\n laps = session.laps\n\n # Process data\n result = {\n \"event\": event,\n \"total_laps\": len(laps),\n \"fastest_lap\": laps[\"LapTime\"].min()\n }\n results.append(result)\n\n except Exception as e:\n errors.append({\"event\": event, \"error\": str(e)})\n continue\n\n return results, errors\n\n# Use it\nresults, errors = process_season(2024)\nprint(f\"Processed {len(results)} events, {len(errors)} errors\")\n```python\n\n### Context Managers\n\nUse context managers for resource cleanup.\n\n```python\nclass SessionContext:\n \"\"\"Context manager for session loading.\"\"\"\n\n def __init__(self, year, gp, session_type):\n self.year = year\n self.gp = gp\n self.session_type = session_type\n self.session = None\n\n def __enter__(self):\n try:\n self.session = tif1.get_session(\n self.year, self.gp, self.session_type\n )\n return self.session\n except Exception as e:\n print(f\"Failed to load session: {e}\")\n return None\n\n def __exit__(self, exc_type, exc_val, exc_tb):\n # Cleanup if needed\n if exc_type is not None:\n print(f\"Error during processing: {exc_val}\")\n return False\n\n# Use it\nwith SessionContext(2025, \"Monaco Grand Prix\", \"Race\") as session:\n if session:\n laps = session.laps\n```python\n\n## Debugging Errors\n\n### Enable debug logging\n\nSee detailed information about what's happening.\n\n```python\nimport tif1\nimport logging\n\n# Enable debug logging\ntif1.setup_logging(logging.DEBUG)\n\n# Now all operations show detailed logs\nsession = tif1.get_session(2025, \"Monaco Grand Prix\", \"Race\")\n```python\n\n### Inspect error context\n\nAll tif1 exceptions include context information.\n\n```python\ntry:\n session = tif1.get_session(2025, \"Invalid GP\", \"Race\")\nexcept tif1.DataNotFoundError as e:\n print(f\"Error: {e}\")\n print(f\"Context: {e.context}\")\n # Context might include: year, gp, session, attempted_urls, etc.\n```python\n\n### Check circuit breaker\n\nMonitor network health.\n\n```python\ncb = tif1.get_circuit_breaker()\nprint(f\"State: {cb.state}\")\nprint(f\"Failures: {cb.failure_count}\")\nprint(f\"Last failure: {cb.last_failure_time}\")\n\n# Reset if needed\nif cb.state == \"open\":\n tif1.reset_circuit_breaker()\n```yaml\n\n## Best Practices\n\n\n \n Check data availability before processing.\n ```python\n events = tif1.get_events(2025)\n if \"Monaco Grand Prix\" in events:\n session = tif1.get_session(2025, \"Monaco Grand Prix\", \"Race\")\n ```python \n \n Catch specific exceptions rather than broad `Exception`.\n ```python\n try:\n session = tif1.get_session(2025, \"Monaco\", \"Race\")\n except tif1.DataNotFoundError:\n # Handle missing data\n pass\n except tif1.NetworkError:\n # Handle network issues\n pass\n```python\n \n \n Always log errors for debugging.\n ```python\n import logging\n logger = logging.getLogger(__name__)\n\n try:\n session = tif1.get_session(2025, \"Monaco\", \"Race\")\n except Exception as e:\n logger.error(f\"Failed to load session: {e}\", exc_info=True)\n```python\n \n \n Don't continue processing if critical data is missing.\n ```python\n session = tif1.get_session(2025, \"Monaco\", \"Race\")\n if session is None:\n raise ValueError(\"Cannot proceed without session data\")\n```python\n \n\n\n## Production Patterns\n\n### Health Checks\n\nMonitor tif1 health in production.\n\n```python\ndef check_tif1_health():\n \"\"\"Check if tif1 is operational.\"\"\"\n try:\n # Try to get events (lightweight operation)\n events = tif1.get_events(2024)\n\n # Check circuit breaker\n cb = tif1.get_circuit_breaker()\n if cb.state == \"open\":\n return False, \"Circuit breaker is open\"\n\n # Check cache\n cache = tif1.get_cache()\n if not cache.cache_dir.exists():\n return False, \"Cache directory missing\"\n\n return True, \"Healthy\"\n except Exception as e:\n return False, str(e)\n```python\n\n### Monitoring\n\nTrack errors and performance.\n\n```python\nimport time\nfrom collections import defaultdict\n\nclass TIF1Monitor:\n \"\"\"Monitor tif1 operations.\"\"\"\n\n def __init__(self):\n self.errors = defaultdict(int)\n self.timings = []\n\n def load_session(self, year, gp, session_type):\n \"\"\"Load session with monitoring.\"\"\"\n start = time.time()\n try:\n session = tif1.get_session(year, gp, session_type)\n duration = time.time() - start\n self.timings.append(duration)\n return session\n except Exception as e:\n self.errors[type(e).__name__] += 1\n raise\n\n def report(self):\n \"\"\"Generate monitoring report.\"\"\"\n return {\n \"total_errors\": sum(self.errors.values()),\n \"errors_by_type\": dict(self.errors),\n \"avg_load_time\": sum(self.timings) / len(self.timings) if self.timings else 0,\n \"max_load_time\": max(self.timings) if self.timings else 0\n }\n```python\n\n## Summary\n\nProper error handling makes your tif1 applications robust and maintainable. Always use specific exceptions, validate input, and implement appropriate retry logic for production use.\n\n---\n\n## Related Pages\n\n\n \n Exception reference\n \n \n Common issues\n \n \n Recommended patterns\n \n" })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }

​Exception Hierarchy

Exception Hierarchy