HPDE Analytics CLI

Data analysis and reporting tool that allows a user to connect to the MotorsportsReg (MSR) API to export data and create reports. This tool automates the extraction of event registration data from MSR and generates Excel reports for High Performance Drivers Education (HPDE) and Time Trials program analytics.

Getting Started

These instructions will help you set up the project on your local machine for development and usage.

Prerequisites

• Python 3.8 or higher
• MotorsportsReg OAuth consumer credentials
• pip (Python package installer)

Installation

Option 1: Install from PyPI (Recommended)

pip install hpde-analytics-cli

Option 2: Install from source

1. Clone the repository:

   git clone https://github.com/Homan13/hpde-analytics-cli.git
   cd hpde-analytics-cli
   

2. Install the package:

   pip install -e .
   

Configuration

1. Configure your credentials (choose one method):

   Option A: Secure storage (Recommended)

   hpde-analytics-cli --configure
   

   This stores your credentials securely in your system's keyring (macOS Keychain, Windows Credential Locker, or Linux Secret Service).

   Option B: Environment file (Fallback)

   Create a .env file in the directory you run the tool from:

   MSR_CONSUMER_KEY=your_consumer_key_here
   MSR_CONSUMER_SECRET=your_consumer_secret_here
   MSR_BASE_URL=https://api.motorsportreg.com
   MSR_CALLBACK_PORT=8089
   

   (Working from a clone, cp .env.example .env gives you a starting point.)

   Two locations are searched, in this order:

   Location	Purpose
   .env in the working directory, or any parent	Per-project settings
   .env in the user config directory (below)	Your defaults across all directories

   The project file wins where both set the same key; the user file supplies anything it leaves out.

2. Check credential status (optional):

   hpde-analytics-cli --credential-status
   

3. Run initial authentication:

   hpde-analytics-cli --auth
   

   Follow the browser prompts to authorize the application.

Usage

Export Event Data

Export all event registration data (both raw and filtered formats):

hpde-analytics-cli --export \
  --org-id 11A1AAAA-2B2B-C333-4D4444444D4DD44D \
  --event-id <EVENT_ID> \
  --name HPDE_TT_1_2025

Parameters:

• --org-id: MSR organization ID (required)
• --event-id: MSR event ID (required)
• --name: Custom name for export folder (optional)
• --output-dir: Custom output directory (optional, defaults to output/)

Generate Time Trials Report

Generate an Excel report from exported data:

hpde-analytics-cli --report \
  --export-dir output/HPDE_TT_1_2025_20260110_123456 \
  --name HPDE_TT_1_2025

Parameters:

• --export-dir: Path to exported data folder (required)
• --name: Custom name for report file (optional)
• --report-file: Specific output path for report (optional)

Other Commands

# Configure or update API credentials (secure keyring storage)
hpde-analytics-cli --configure

# Check credential configuration status
hpde-analytics-cli --credential-status

# Re-authenticate if tokens expire
hpde-analytics-cli --auth

# Run field discovery to explore available data
hpde-analytics-cli --discover \
  --org-id <ORG_ID> \
  --event-id <EVENT_ID>

# Show all available options
hpde-analytics-cli --help

Report Features

The generated Time Trials report includes:

• Driver Information: Name, email, member ID
• Vehicle Details: Year/make/model (combined), color, tire brand, vehicle number
• Classification: TT class and class grouping (Max, Sport, Tuner, Unlimited)
• Participation Tracking:
  • Days attended (Friday/Saturday/Sunday/combinations)
  • Day count (1 Day, 2 Days, 3 Days)
  • Instructor status (Yes/No)
  • AYCE participation (Time Trials + Advanced HPDE)
  • Participation type (TT Only, TT + Instructor, TT + AYCE, TT + Instructor + AYCE)

Pivot-Ready Columns: Class Group, Day Count, and Participation Type columns are optimized for Excel pivot table analysis to track registration trends.

Project Structure

hpde-analytics-cli/
├── .env.example                  # Credential template
├── .gitignore                    # Git exclusions
├── pyproject.toml                # Package configuration
├── README.md                     # This file
├── hpde_analytics_cli/
│   ├── __init__.py
│   ├── main.py                   # CLI entry point
│   ├── paths.py                  # Config, token and output path resolution
│   ├── auth/
│   │   ├── __init__.py
│   │   ├── credentials.py        # Secure credential management
│   │   └── oauth.py              # OAuth 1.0a authentication
│   ├── api/
│   │   ├── __init__.py
│   │   └── client.py             # MSR API client
│   └── utils/
│       ├── __init__.py
│       ├── data_export.py        # Data export to JSON/CSV
│       ├── field_discovery.py    # API field enumeration
│       └── report_generator.py   # Excel report generation
├── output/                       # Export and report output (not in version control)
└── tests/                        # Unit tests

File Locations

Exports and reports are written relative to the directory you run the command from, so the tool behaves the same whether installed from PyPI or run from a clone. OAuth tokens go to a per-user config directory, so they survive upgrades and stay out of your project folders.

The user config directory is the native location for your platform:

Set HPDE_CONFIG_DIR to override it. The token file is written readable only by you (mode 0600 on POSIX systems). A token left by version 6.0.7 or earlier is moved to the new location automatically on first run, so you will not need to re-authenticate.

Export Structure

Each export creates two data sets:

HPDE_TT_1_2025_20260110_123456/
├── raw_data/                     # Complete API responses (for reference)
│   ├── profile_full.json
│   ├── calendar_full.json
│   ├── calendar_full.csv
│   ├── entrylist_full.json
│   ├── entrylist_full.csv
│   ├── attendees_full.json
│   ├── attendees_full.csv
│   ├── assignments_full.json
│   └── assignments_full.csv
├── profile.json                  # Filtered data for Time Trials
├── calendar.json
├── entrylist.json
├── entrylist.csv
├── attendees.json
├── attendees.csv
├── assignments.json
├── assignments.csv
└── export_summary.json

Running the tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests with coverage
pytest

Deployment

This is a command-line tool designed to run locally. No deployment infrastructure is required.

For scheduled/automated execution:

• Consider setting up cron jobs (Linux/Mac) or Task Scheduler (Windows)
• Ensure OAuth tokens are refreshed as needed
• Store reports in a centralized location for team access

Built With

• Python 3 - Programming language
• requests - HTTP library
• requests-oauthlib - OAuth 1.0a support
• python-dotenv - Environment variable management
• openpyxl - Excel file generation
• keyring - Secure credential storage
• MotorsportsReg API - Event registration data source

Contributing

In Progress - Contribution guidelines to be developed

Versioning

This project uses Semantic Versioning (SemVer):

• MAJOR version for incompatible API changes
• MINOR version for new functionality in a backward compatible manner
• PATCH version for backward compatible bug fixes

Releases are automated by release-please from Conventional Commit messages on main. Version numbers are owned by that automation and should never be edited by hand.

To see the version you have installed:

hpde-analytics-cli --version

For the current release and full history, see Releases and CHANGELOG.md.

Authors

• Kevin Homan

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• SCCA Washington DC Region for supporting the Time Trials program
• MotorsportsReg.com for providing API access
• WDCR HPDE program for combined event management

Security Notes

Important:

• Never commit a .env file to version control
• OAuth consumer secrets and access tokens must be kept confidential
• The .gitignore file is configured to exclude these sensitive files automatically
• Use hpde-analytics-cli --configure to store credentials securely in your system keyring
• Access tokens live outside the project in the user config directory, written mode 0600
• Exported data contains registrant names and email addresses; output/ is gitignored, but take the same care with it that you would with any roster

Support

For issues or questions related to this tool, contact the WDCR Time Trials administration.

For MotorsportsReg API issues, refer to the MotorsportsReg API documentation.