MLP-PPA Pickleball Calendar Generator

Generate live-updating iCalendar (ICS) files for professional pickleball tournaments from Major League Pickleball (MLP) and Professional Pickleball Association (PPA).

What This Skill Does

This skill helps you work with a Python codebase that:

Instructions

When working with this codebase, follow these guidelines:

1. Understanding the Project Structure

The project has three core modules:

Test files use the `unittest` framework with sample JSON/HTML fixtures in the root directory.

2. Running Generators

```bash

Generate all MLP calendars (7 ICS files)

python make_mlp_ics_multi.py --debug

Generate all PPA calendars (12+ ICS files)

python make_ppa_ics.py --debug

Custom options

python make_mlp_ics_multi.py --days 5 --tz America/Los_Angeles --debug

```

3. Running Tests

```bash

Run all tests

python run_tests.py

Run specific test suite

python -m unittest test_mlp_ics.py -v

python -m unittest test_ppa_parser.py -v

```

Always run tests before and after making changes.

4. Code Conventions

**Python Style:**

**ICS Generation:**

**Error Handling:**

**Testing:**

5. Technology Constraints

**Critical:** This project uses **Python standard library only**. Do not add external dependencies.

Required Python version: 3.9+ (for `zoneinfo` module)

Key modules used: `urllib`, `json`, `html.parser`, `zoneinfo`, `datetime`, `re`, `unittest`

6. Data Flow Pipelines

**MLP Pipeline:**

1. Fetch active tournaments from events API

2. For each tournament + division + date, fetch matchups

3. Deduplicate by matchup UUID

4. Generate filtered ICS files (by division, court)

**PPA Pipeline:**

1. Scrape tournament schedule pages

2. Parse HTML with custom `HTMLParser`

3. Extract events with dates, times, courts, broadcasters

4. Convert Eastern Time to UTC

5. Generate filtered ICS files (by category, broadcaster, court)

7. Common Tasks

**Adding a New Broadcaster:**

1. Add broadcaster URL pattern detection in `make_ppa_ics.py`

2. Add new output file generation in `write_all_ics_files()`

3. Add test cases in `test_ppa_parser.py`

4. Update `README.md` with new subscription URL

**Adding a New Court Type:**

1. Update `COURT_LABELS` constant in `make_mlp_ics_multi.py`

2. Add new file generation logic

3. Add test cases

4. Update `README.md`

**Fixing Parsing Issues:**

1. Use `--debug` flag to see raw API/HTML data

2. Check if sample data files match current website structure

3. Update HTML parsing regex/logic as needed

4. Add new sample files for edge cases

8. Debugging Tips

9. External Data Sources

**MLP API Endpoints:**

**PPA Website:**

**Important:** These are unofficial data sources. Website structure changes may break parsing. Always check sample data files and use `--debug` when diagnosing issues.

10. GitHub Actions

The workflow (`.github/workflows/build-ics.yml`) runs hourly:

1. Checkout code

2. Setup Python 3.11

3. Generate all ICS files with `--debug`

4. Create `index.html`

5. Deploy to GitHub Pages

11. Output Files

**MLP (7 files):**

**PPA (12+ files):**

Constraints

Example Usage

**Scenario:** Adding support for a new PPA broadcaster (e.g., ESPN+)

1. Open `make_ppa_ics.py`

2. Add URL pattern detection:

```python

if 'espnplus.com' in watch_link:

broadcaster = 'espnplus'

```

3. Add file generation in `write_all_ics_files()`:

```python

write_filtered_ics(events, 'ppa-espnplus.ics', lambda e: e.get('broadcaster') == 'espnplus')

```

4. Add test case in `test_ppa_parser.py`

5. Run `python run_ppa_tests.py`

6. Update `README.md` with subscription URL