Metadata-Version: 2.4
Name: meeps
Version: 0.2.0
Summary: Advanced League of Legends esports analytics library with player performance statistics, contract tracking, and comprehensive tournament data
License-Expression: MIT
License-File: LICENSE
Keywords: leaguepedia,league-of-legends,esports,analytics,performance-statistics,player-data,gaming,riot-games,tournaments,contracts,kda,fantasy-sports
Author: Thomas Barrepitous
Author-email: barrepitousthomas@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Provides-Extra: cache
Requires-Dist: lol-dto (>=2.0.0,<3.0.0)
Requires-Dist: lol-id-tools (>=2.0.0,<3.0.0)
Requires-Dist: mwclient (>=0.10.1,<0.11.0)
Requires-Dist: mwrogue (>=0.1.0,<0.2.0)
Requires-Dist: rapidfuzz (<3.0)
Requires-Dist: requests-cache (>=1.0.0,<2.0.0) ; extra == "cache"
Project-URL: Documentation, https://github.com/thomasbarrepitous/meeps#readme
Project-URL: Homepage, https://github.com/thomasbarrepitous/meeps
Project-URL: Repository, https://github.com/thomasbarrepitous/meeps
Description-Content-Type: text/markdown

# meeps - Enhanced Leaguepedia Parser

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Features](https://img.shields.io/badge/features-10_modules-green.svg)](#features)

A **comprehensive** Leaguepedia parser providing easy access to League of Legends esports data. This enhanced fork extends the original with extensive coverage of player statistics, contracts, standings, and performance analytics.

## ✨ Features

**🚀 Advanced Performance Analytics**
- 📊 **Match Statistics** - Individual player KDA, damage, CS, vision score, and performance grading
- 📈 **Performance Analytics** - Kill participation, gold share, multikill analysis, and MVP detection
- 🎯 **Role Comparisons** - Cross-player performance analysis by position and tournament

**Enhanced beyond the original with:**
- 📋 **Contract Tracking** - Player contracts, expiration dates, and team obligations  
- 🏆 **Tournament Standings** - Team rankings, win rates, series/game statistics
- 🎮 **Champion Data** - All champions with attributes, stats, and filtering
- ⚔️ **Items Database** - Complete item catalog with stats and tier filtering  
- 👥 **Roster Changes** - Player transfers, team history, and timeline tracking
- 👤 **Player Profiles** - Comprehensive player information with country, birth dates, status
- 🏟️ **Tournament Rosters** - Team compositions for specific tournaments

**Plus all original functionality:**
- 🎯 Games & match details with picks/bans
- 🏢 Regional & tournament data
- 🖼️ Team assets (logos, thumbnails)

## Install

```bash
# With pip
pip install meeps

# With caching support (recommended)
pip install meeps[cache]

# With Poetry
poetry add meeps
poetry add meeps -E cache  # with caching

# Quick verification
python -c "import meeps as mp; print('✅ Import successful')"
```

## Demo

![Demo](https://raw.githubusercontent.com/thomasbarrepitous/meeps/master/leaguepedia_parser_demo.gif)

## Usage

```python
import meeps as mp

# Games & Tournaments
regions = mp.get_regions()
# ['Korea', 'Europe', 'North America', 'China', ...]

tournaments = mp.get_tournaments("Korea", year=2020)
# [{'name': 'LCK/2020 Season/Spring Season', 'region': 'Korea'}, ...]

games = mp.get_games("LCK/2020 Season/Spring Season")
# [Game(team1='T1', team2='GenG', winner='T1', date='2020-02-05'), ...]

# Teams & Assets
logo_url = mp.get_team_logo('T1')
# 'https://static.wikia.nocookie.net/lolesports_gamepedia_en/images/t1_logo.png'

team_assets = mp.get_all_team_assets('T1')
# TeamAssets(logo='...', thumbnail='...', team_name='T1')

active_players = mp.get_active_players('T1')
# [TeamPlayer(name='Faker', role='Mid'), TeamPlayer(name='Gumayusi', role='Bot'), ...]

# Players
player = mp.get_player_by_name('Faker')
# PlayerInfo(name='Faker', country='South Korea', birth_date='1996-05-07', status=ACTIVE)

# Tournament Rosters
rosters = mp.get_tournament_rosters('T1', 'LCK/2024 Season/Summer Season')
# [{'Team': 'T1', 'Tournament': 'LCK/2024...', 'Player': 'Faker', 'Role': 'Mid'}, ...]

# Standings
standings = mp.get_tournament_standings("LCK/2024 Season/Summer Season")
# [Standing(team='T1', place=1, win_series=16, loss_series=2), ...]

# Champions
champions = mp.get_champions_by_attributes("Marksman")
# [Champion(name='Jinx', attributes='Marksman', attack_range=525), ...]

champion = mp.get_champion_by_name("Jinx")
# Champion(name='Jinx', attributes='Marksman', attack_range=525, is_ranged=True)

# Items
ad_items = mp.get_ad_items()
# [Item(name='Infinity Edge', ad=70, total_cost=3400), ...]

crit_items = mp.search_items_by_stat("Crit")
# [Item(name='Infinity Edge', crit=20), Item(name='Stormrazor', crit=15), ...]

infinity_edge = mp.get_item_by_name("Infinity Edge")
# Item(name='Infinity Edge', ad=70, crit=20, total_cost=3400, provides_ad=True)

# Roster Changes
roster_changes = mp.get_team_roster_changes("T1")
# [RosterChange(player='Faker', direction='Join', team='T1', date=2013-01-01), ...]

recent_moves = mp.get_recent_roster_changes(days=30)
# [RosterChange(player='Caps', direction='Leave', team='G2', date=2024-11-15), ...]

# 📊 Player Performance Analytics
# Get individual match statistics
faker_matches = mp.get_player_match_history("Faker", limit=5)
for match in faker_matches:
    print(f"{match.champion}: {match.kda_ratio:.1f} KDA, {match.performance_grade} grade")
    # Azir: 20.0 KDA, S grade

# Team performance analysis
t1_performance = mp.get_team_match_performance("T1", tournament="LCK/2024 Season/Summer Season")
avg_kda = sum(p.kda_ratio for p in t1_performance if p.kda_ratio) / len(t1_performance)
# Calculate team statistics: average KDA, win rates, damage distribution

# Champion meta analysis
azir_stats = mp.get_champion_performance_stats("Azir", tournament="LCK/2024 Season/Summer Season")
win_rate = sum(1 for p in azir_stats if p.did_win) / len(azir_stats) * 100
# Analyze champion effectiveness across different players and tournaments

# Role performance comparison
mid_players = mp.get_role_performance_comparison("LCK/2024 Season/Summer Season", "Mid")
top_performer = max(mid_players, key=lambda p: p.kda_ratio or 0)
# Compare player performance within specific roles

# MVP candidate detection
mvp_candidates = mp.get_tournament_mvp_candidates("LCK/2024 Season/Summer Season", min_games=10)
# Identify top-performing players based on consistency and performance metrics

# 📋 Contract Management
# Get active contracts
active_contracts = mp.get_active_contracts()
# [Contract(player='Faker', team='T1', contract_end='2025-12-31'), ...]

# Check expiring contracts
expiring_soon = mp.get_expiring_contracts(days=90)
# Monitor contract renewals and potential free agents

# Player contract history
faker_contracts = mp.get_player_contracts("Faker")
# Track contract changes and team commitments
```

## 🎯 Common Use Cases

```python
# 📊 Performance Analysis & Fantasy Esports
# Track individual player performance and trends
faker_stats = mp.get_player_match_history("Faker", limit=10)
performance_trend = [game.performance_grade for game in faker_stats]
avg_kda = sum(game.kda_ratio for game in faker_stats if game.kda_ratio) / len(faker_stats)

# Identify MVP candidates for tournaments
mvps = mp.get_tournament_mvp_candidates("LCK/2024 Season/Summer Season")
top_mvp = mvps[0]  # Highest performing player
print(f"Tournament MVP: {top_mvp.player_name} - {top_mvp.kda_ratio:.1f} KDA")

# 🏆 Tournament & Team Analysis
standings = mp.get_tournament_standings("LCK/2024 Season/Summer Season")
top_team = standings[0].team
roster = mp.get_tournament_rosters(top_team, "LCK/2024 Season/Summer Season")

# Analyze team synergy and individual contributions
team_performance = mp.get_team_match_performance(top_team, limit=20)
team_avg_damage = sum(p.damage_to_champions for p in team_performance if p.damage_to_champions)

# 📋 Contract & Roster Management
# Monitor contract expirations for potential transfers
expiring_contracts = mp.get_expiring_contracts(days=180)
free_agents_soon = [c.player for c in expiring_contracts if c.team == "T1"]

# Track roster changes and team building
recent_moves = mp.get_recent_roster_changes(days=7)
team_additions = mp.get_roster_additions(team="T1")

# 🎮 Meta Analysis & Champion Research
# Analyze champion effectiveness across different skill levels
azir_performance = mp.get_champion_performance_stats("Azir")
azir_win_rate = sum(1 for p in azir_performance if p.did_win) / len(azir_performance)

# Compare role effectiveness
mid_players = mp.get_role_performance_comparison("LCK/2024 Season/Summer Season", "Mid")
support_players = mp.get_role_performance_comparison("LEC/2024 Season/Summer Season", "Support")

# Item meta analysis
marksmen = mp.get_champions_by_attributes("Marksman")
crit_items = mp.search_items_by_stat("Crit")
```

## 📚 Data Sources

This library queries [Leaguepedia's Cargo tables](https://lol.fandom.com/wiki/Special:CargoTables) - a structured database of League of Legends esports data.

### Cargo Table Mapping

| Function | Cargo Table | Description |
|----------|-------------|-------------|
| `get_tournaments()` | Tournaments, Leagues | Tournament metadata |
| `get_games()` | ScoreboardGames | Match results and stats |
| `get_game_details()` | ScoreboardGames, ScoreboardPlayers, PicksAndBansS7 | Full match data with players |
| `get_player_by_name()` | Players | Player profiles (49 fields) |
| `get_active_players()` | Tenures, RosterChanges | Current team rosters |
| `get_standings()` | Standings | Tournament rankings |
| `get_champions()` | Champions | Champion stats and attributes |
| `get_items()` | Items | Item stats and costs |
| `get_roster_changes()` | RosterChanges | Player transfers |
| `get_contracts()` | Contracts | Player contract dates |
| `get_scoreboard_players()` | ScoreboardPlayers | Individual match performance |
| `get_tournament_rosters()` | TournamentRosters | Tournament team compositions |

### Tournament Naming Convention

Tournaments use the `OverviewPage` format: `{League}/{Year} Season/{Split}`

| Example | Description |
|---------|-------------|
| `LCK/2024 Season/Summer Season` | LCK Summer 2024 |
| `LEC/2024 Season/Spring Season` | LEC Spring 2024 |
| `Worlds/2024 Season/Main Event` | Worlds 2024 Main Event |
| `MSI/2024 Season/Main Event` | MSI 2024 |

**Tip:** Use `get_tournaments(region, year)` to discover valid tournament names.

### Field Availability

Not all fields are always populated. Common optional fields:

| Dataclass | Optional Fields |
|-----------|-----------------|
| `PlayerInfo` | `birthdate`, `contract`, social media fields, `team` (if free agent) |
| `Champion` | `release_date`, some stat fields for newer champions |
| `ScoreboardPlayer` | `damage_to_champions`, `vision_score` (older matches) |
| `Contract` | `contract_end_text`, `news_id` |

Always check for `None` before using these fields.

### Rate Limiting

Leaguepedia has rate limits. Best practices:

- **Use `limit` parameter** - Don't fetch more data than needed
- **Filter by tournament** - Avoid unbounded queries across all history
- **Add delays for bulk operations** - 1-2 seconds between large queries
- **Expect occasional timeouts** - The library retries automatically (3 attempts)

```python
# Good - bounded query
games = mp.get_games("LCK/2024 Season/Summer Season", limit=10)

# Slow - unbounded, fetches years of data
games = mp.get_games()  # Avoid this
```

### Caching

For heavy usage, enable HTTP-level caching to avoid repeated API calls. The library provides built-in support via `requests-cache`.

**Installation:**

```bash
# Install with cache support
pip install meeps[cache]

# Or add requests-cache separately
pip install requests-cache
```

**Built-in cache support:**

```python
import meeps as mp

# Enable caching (SQLite backend, 1 hour TTL)
mp.enable_cache()

# First call hits the API
standings = mp.get_tournament_standings("LCK/2024 Season/Summer Season")

# Second call returns cached data instantly
standings = mp.get_tournament_standings("LCK/2024 Season/Summer Season")

# Check cache status
print(mp.get_cache_info())
# {'size': 1, 'backend': 'SQLiteCache', 'expire_after': 3600}

# Clear cache when you need fresh data
mp.clear_cache()

# Disable caching
mp.disable_cache()
```

**Configuration options:**

```python
# Custom TTL (24 hours)
mp.enable_cache(expire_after=86400)

# In-memory cache (faster, not persistent)
mp.enable_cache(backend='memory')

# Custom cache location
mp.enable_cache(cache_dir='/path/to/cache')

# No expiration (manual clear only)
mp.enable_cache(expire_after=None)
```

**Manual approach (without built-in support):**

```python
import requests_cache

# Install cache before importing meeps
requests_cache.install_cache('leaguepedia_cache', expire_after=3600)

import meeps as mp
# All requests are now cached automatically
```

**Recommended TTLs by data type:**

| Data Type | Suggested TTL | Reason |
|-----------|---------------|--------|
| Champions, Items | 1 week (604800s) | Rarely changes |
| Tournament standings | 1-6 hours | Updates after matches |
| Match schedules | 1 hour | Can change day-of |
| Roster changes | 1 day (86400s) | Updates periodically |
| Live/recent matches | 5-15 minutes | Frequent updates |

## 📋 Data Types

| Module | Returns | Key Properties |
|--------|---------|----------------|
| **Performance** | `ScoreboardPlayer` | kda_ratio, performance_grade, kill_participation, gold_share |
| **Contracts** | `Contract` | player, team, contract_end, is_active, days_until_expiry |
| **Games** | `Game`, `GameDetails` | teams, winner, date, picks_bans |
| **Teams** | `TeamPlayer`, `TeamAssets` | name, role, logo, thumbnail |
| **Players** | `PlayerInfo` | name, country, birth_date, status |
| **Tournaments** | `Dict` (rosters) | team, tournament, player, role |
| **Standings** | `Standing` | team, place, win_rate, total_games |
| **Champions** | `Champion` | name, attributes, is_ranged, attack_range |
| **Items** | `Item` | name, tier, provides_ad/ap, total_cost |
| **Roster Changes** | `RosterChange` | player, team, direction, is_addition |

## ⚡ Performance Considerations

**For optimal performance with large datasets:**

```python
# ✅ GOOD: Use filters and limits for responsive queries
faker_recent = mp.get_player_match_history("Faker", limit=10)
t1_lck = mp.get_team_match_performance("T1", tournament="LCK/2024 Season/Summer Season")
specific_game = mp.get_game_scoreboard("ESPORTSTMNT01_2024_LCK_Game123")

# ⚠️ SLOW: Large unbounded queries (10+ years of data)
# all_faker_games = mp.get_player_match_history("Faker")  # Takes minutes!
```

**Best Practices:**
- Always use `limit` for exploratory analysis
- Filter by `tournament` for recent data
- Use specific `game_id` for detailed match analysis
- Start with small queries then expand scope as needed

## 📚 More Information

- **Examples**: Comprehensive usage examples in the [`tests` folder](https://github.com/thomasbarrepitous/leaguepedia_parser/tree/master/tests)
- **Development**: See [CLAUDE.md](CLAUDE.md) for development commands and setup
- **Original**: Based on [mrtolkien/leaguepedia_parser](https://github.com/mrtolkien/leaguepedia_parser)
- **Rate Limits**: Leaguepedia API has rate limits - the library handles basic throttling

## 🤝 Contributing

This enhanced fork welcomes contributions! Areas of interest:
- Advanced analytics features (win prediction, meta trends)
- Additional Cargo table parsers (Pentakills, Bans, etc.)
- Performance optimizations for large datasets
- Enhanced visualization integrations
- Better error handling and retry logic
- Documentation improvements

**Major Features:**
- ✅ **ScoreboardPlayers** - Complete match statistics with performance analytics
- ✅ **Contracts** - Player contract tracking and management
- ✅ **Advanced Filtering** - Tournament, role, and time-based queries
- ✅ **Performance Grading** - Automated player performance assessment

