Pitwall-CLI

Features

• Interactive prompt with contextual breadcrumbs and colorized output.
• Quick navigation: enter a year, meeting key, session key, or driver number to drill down.
• Driver data views: laps, stints, position changes, pit stops, team radio, or “all”.

Commands (interactive mode)

• year (e.g., 2024): list all Grand Prix for that season.
• meeting_key (number): list sessions for that Grand Prix.
• session_key (number): list drivers and rankings for that session.
• driver_number (number): open driver data menu.
• Driver data within a session/driver: laps, stints, position, pit, radio, all.
• gp or current: show current and next Grand Prix.
• export <endpoint> [format=csv|json] [key=value ...]: export data. Context (year/session/driver) auto-fills missing params when available.
• cache <stats|clear|info>: inspect or clear cached API responses.
• refresh: bypass cache for the current view and refetch.
• context / where: show current navigation state.
• clear: clear the screen and re-render the current view.
• back: go up one level; help: show help; exit|quit|q: leave interactive mode.

Examples

• 2025 → list 2025 Grand Prix.
• 1254 (after a year) → show sessions for that event.
• 9636 (after selecting a meeting) → show session drivers.
• 44 (after selecting a session) → open driver #44 menu.
• laps (within driver context) → show lap times.
• export laps format=csv → export current session & driver lap data to CSV using context.
• export meetings format=csv year=2024 → export all 2024 meetings.

Installation

1. Use Python 3.10+.
2. Install dependencies:

pip install -r requirements.txt

Running

• Interactive mode (recommended):

python main.py

• One-off command:

python main.py 2024
python main.py export laps format=csv session_key=9636 driver_number=44

Data exports

• Defaults to JSON; add format=csv for CSV.
• If you’re already in a session/driver context, missing params are auto-filled (e.g., current session_key or driver_number).
• Files save to the current working directory with timestamped names unless you specify filename when calling export_data programmatically.

Caching

• Cached per-endpoint with sensible expirations (sessions/meetings daily, laps/stints hourly, position every 30 minutes, default 6 hours).
• Manage via cache clear [endpoint], cache stats, or cache info.
• Use refresh to bypass cache for the current view.

Testing

Run the test suite with:

pytest

Notes

• API source: OpenF1.
• Exported CSVs include flattened nested fields to simplify downstream analysis. A simple command-line interface for accessing and exporting real-time and historical F1 data from the OpenF1 API. Made for easier access to F1 data ready for analytics.

Features

• Navigation: Hierarchical browsing from seasons to individual driver telemetry
• Export Formats: Export data as JSON or CSV for analysis
• Rich Terminal Interface: Color-coded output with intuitive navigation
• Data Coverage: Sessions, drivers, laps, stints, positions, pit stops, and more
• Intelligent Caching: Automatic local caching with smart expiration policies

Installation

Install from Source

git clone https://github.com/artemiui/pitwall-cli.git
cd pitwall-cli
pip install -r requirements.txt

Dependencies

pip install requests pandas  # Core dependencies

Quick Start

Interactive Mode

# Start the interactive CLI
python f13.py

# Or after installation:
fastlap

Single Command Mode

# View current and next Grand Prix
python f13.py gp

# Browse the 2024 season
python main.py 2024

# Export driver lap times as CSV
python f13.py export laps format=csv session_key=9636 driver_number=44

Usage Guide

flowchart TD
    A[Start: Interactive Mode] --> B{Main Menu}
    B -->|Year input 2024| C[show_year_meetings]
    B -->|'gp' or 'current'| D[show_current_gp]
    B -->|'help'| E[show_help]
    B -->|'cache stats'| F[F1Cache.stats]
    B -->|'exit/quit/q'| Z[Exit]
    
    C -->|Meeting Key 1056| G[show_meeting_sessions]
    G -->|Session Key 9636| H[show_session_drivers]
    H -->|Driver Number 44| I[show_driver_menu]
    
    I -->|'laps'| J[show_driver_laps]
    I -->|'stints'| K[show_driver_stints]
    I -->|'position'| L[show_driver_position]
    I -->|'pit'| M[show_driver_pits]
    I -->|'radio'| N[show_driver_radio]
    I -->|'all'| O[show_driver_all]
    I -->|'back'| H
    
    subgraph "Export Operations"
        P[export command] --> Q{Format?}
        Q -->|format=csv| R[export_to_csv]
        Q -->|Default/format=json| S[export_to_json]
        R --> T[flatten_json<br>for CSV structure]
    end
    
    subgraph "Cache Operations"
        U[cache command] --> V{subcommand?}
        V -->|'stats'| W[F1Cache.stats]
        V -->|'clear'| X[F1Cache.clear]
        V -->|'info'| Y[Cache info display]
    end
    
    J -->|'back'| I
    K -->|'back'| I
    L -->|'back'| I
    M -->|'back'| I
    N -->|'back'| I
    O -->|'back'| I
    H -->|'back'| G
    G -->|'back'| C
    C -->|'back'| B

Loading

Command Reference

Core Navigation

Command	Description	Example
[year]	Browse a specific season	2024
[meeting_key]	Select a Grand Prix	1056
[session_key]	Select a session	9636
[driver_number]	Select a driver	44
back	Navigate back one level	back
gp / current	Show current/next Grand Prix	gp

Driver Data Commands

Command	Description	Example
laps	Lap times and sector data	laps
stints	Tyre stint information	stints
position	Position changes during session	position
pit	Pit stop data	pit
radio	Team radio messages	radio
all	Show all available driver data	all

Data Export

# Export current context data as CSV
export laps format=csv

# Export specific data with parameters
export stints format=csv session_key=9636 driver_number=44

# Export meetings for a year
export meetings format=csv year=2024

# Export as JSON (default)
export laps session_key=9636

Cache Management

# Show cache statistics
cache stats

# Clear all cached data
cache clear

# Clear specific endpoint cache
cache clear sessions

# Force refresh current view
refresh

Utility Commands

Command	Description
help	Show help menu
context / where	Show current navigation context
clear	Clear screen and refresh view
exit / quit / q	Exit the application

Data Examples

Lap Time Display

DRIVER #44 - LAP TIMES
─────────────────────────────────────────────────────
LAP   TIME         S1        S2        S3      SPEED
─────────────────────────────────────────────────────
1     98.123s     32.456s   33.123s   32.544s  312 km/h
2     97.845s     32.123s   32.987s   32.735s  315 km/h
3     97.234s     31.987s   32.456s   32.791s  318 km/h

Tyre Stint Analysis

DRIVER #44 - TYRE STINTS
─────────────────────────────────────────────────────
STINT  COMPOUND    START    END    PROG.    TOTAL
─────────────────────────────────────────────────────
1      SOFT        1        22     22 laps  (22)
2      MEDIUM      23       42     20 laps  (20)  
3      SOFT        43       58     16 laps  (16)

Configuration

Cache Settings

The CLI automatically caches data in ~/.f1cli_cache/ with intelligent expiration:

Data Type	Cache Duration	Purpose
Meetings	24 hours	Grand Prix schedules rarely change
Sessions	24 hours	Session lists are stable
Driver Info	12 hours	Driver details per session
Lap Data	1 hour	Lap times could be updated
Position Data	30 minutes	Real-time positions

Environment Variables

# Increase timeout for slow connections
export F1_REQUEST_TIMEOUT=15

# Disable caching for development
export F1_DISABLE_CACHE=1

# Set custom cache directory
export F1_CACHE_DIR=~/.my_f1_cache

Development

Key Components

• F1Cache Class: Intelligent caching with expiration policies
• Context Management: Track navigation state across commands
• fetch_json(): Robust HTTP client with retry logic
• Color System: ANSI color codes for rich terminal output

Extending the CLI

To add a new data endpoint:

1. Add a new function:

def show_driver_weather(session_key: str, driver_number: str, force_refresh: bool = False):
    url = f"https://api.openf1.org/v1/weather?session_key={session_key}"
    # ... implementation

2. Add to driver menu options
3. Add command handler in process_command()

Development Setup

# Clone and setup
git clone https://github.com/yourusername/fastlap-cli.git
cd fastlap-cli
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Run tests
python -m pytest tests/

# Format code
black f13.py

Troubleshooting

Common Issues

Issue: Read timed out (read timeout=5) Solution: The CLI automatically retries with exponential backoff. For persistent issues:

# Use the refresh command to bypass cache
refresh

Issue: No data returned for session Solution: Some historical sessions may have limited data. Try:

• Checking the OpenF1 API directly: https://api.openf1.org/v1/sessions?year=2024
• Using a different session key

Issue: Colors not displaying correctly Solution: Ensure your terminal supports ANSI colors. Disable colors with:

export NO_COLOR=1

Debug Mode

# Enable debug logging
export F1_DEBUG=1
python f13.py 2024

Performance

• First load: 2-5 seconds (API fetch + cache)
• Cached load: < 0.1 seconds (local cache)
• Memory usage: < 50MB
• Cache size: Typically 10-50MB per season

API Reference

This CLI uses the OpenF1 API, which provides:

• Free access to historical F1 data
• Real-time data during live sessions
• Comprehensive endpoints for all F1 data types

Rate Limiting

The OpenF1 API has rate limits for unauthenticated access:

• Free tier: Limited requests per minute
• Paid tier: Higher limits available This CLI includes automatic rate limit detection and exponential backoff.

Acknowledgments

• OpenF1 for providing such a comprehensive, useful API without need for imports

Disclaimer: This is an independent, fan-made project and is NOT affiliated with, endorsed by, or connected to Formula 1, Formula One World Championship Limited, the FIA, or any official F1 teams, sponsors, or partners.