Skip to main content
Follow these practices for the best performance, reliability, and code quality.

Performance best practices

Best Practices Workflow

Use selective data loading

Control what data gets fetched to optimize performance. Load only the necessary data.

Batch telemetry fetching

Never fetch telemetry in a loop. Use batch methods instead.

Choose the right lib

Use polars for large datasets and performance-critical code. lib="polars" returns polars DataFrames from session.laps, session.weather, session.results, session.drivers_df, and the telemetry accessors. Without polars, the session falls back to pandas.

Keep caching enabled

Never disable caching unless absolutely necessary.

Code quality best practices

Use Type Hints

tif1 ships type hints for the public API. Use them for better IDE support.

Handle errors gracefully

Always handle tif1 exceptions appropriately.

Use context managers for resources

When working with exports or databases, use context managers.

Data analysis best practices

Filter early, aggregate late

Filter data as early as possible to reduce memory usage.

Clean data before analysis

Always filter out invalid laps before analysis.

Use Vectorized Operations

Avoid loops when working with DataFrames.

Reliability best practices

Check data availability first

Before processing multiple sessions, check which sessions each event has.

Use circuit breaker awareness

Check circuit breaker status for long-running jobs.

Enable debug logging for troubleshooting

When debugging, enable detailed logging.

Memory management best practices

Process data in chunks

For large-scale analysis, process drivers one at a time.

Use Polars for large datasets

Polars frames use less memory than the pandas frames of the same session. Pass lib="polars" per session.

Clear cache periodically

For long-running applications, free the in-memory cache tiers, or clear the cache to remove all stored data.

Testing best practices

Mock network calls in tests

Do not hit the real CDN in unit tests.

Use small datasets for tests

Test with minimal data to keep tests fast.

Documentation best practices

Document the analysis

Add docstrings and comments to the analysis code.

Summary Checklist

1

Performance

  • Load only the data the analysis needs
  • Batch telemetry fetching
  • Choose appropriate lib (polars for large data)
  • Keep caching enabled
2

Code Quality

  • Use type hints
  • Handle errors gracefully
  • Use context managers
  • Follow PEP 8
3

Data Analysis

  • Filter early, aggregate late
  • Clean data before analysis
  • Use vectorized operations
  • Avoid loops
4

Reliability

  • Check data availability
  • Monitor circuit breaker
  • Enable debug logging when needed
  • Handle network errors
5

Memory

  • Process in chunks
  • Use polars for large datasets
  • Clear cache periodically
  • Delete unused DataFrames

Caching Strategy

How the cache tiers work.

Error Handling

Handle errors.

Common Use Cases

Analysis recipes.
Last modified on October 30, 2026