# Pokemon Data Package

A Python package providing offline access to Pokemon random battle data and Smogon competitive sets with automatic updates from official source repositories.

## Features

- **Offline Access**: Bundle data files within the package for immediate use
- **Auto-Updates**: Automatically check for RandBats updates every 24 hours (configurable)
- **Dual Data Sources**: Both RandBats random battle data and Smogon competitive sets
- **Modular Installation**: Install only the generations/formats you need
- **Clean API**: Simple programmatic access to Pokemon data
- **Rich CLI**: Beautiful command-line interface with colored output
- **Multiple Formats**: Support for all Pokemon generations and battle formats
- **Graceful Fallbacks**: Robust error handling and network failure recovery

## Installation

### Standard Installation (All Data Included)
```bash
pip install localsets
```

This installs the complete package with all RandBats and Smogon data files included.

### Installation Without CLI
```bash
pip install localsets[no-cli]
```

This installs the package without the command-line interface, useful for library-only usage.

### Development Installation
```bash
pip install localsets[dev]
```

This includes development dependencies for testing and code quality tools.

## Quick Start

### Programmatic Usage

```python
from localsets import PokemonData, get_pokemon, get_smogon_sets

# Initialize with specific formats
data = PokemonData(
    randbats_formats=['gen9randombattle', 'gen8randombattle'],
    smogon_formats=['gen9ou', 'gen8ou']
)

# RandBats data (random battle)
pikachu_randbats = data.get_randbats('pikachu', 'gen9randombattle')

# Smogon sets (competitive)
pikachu_sets = data.get_smogon_sets('pikachu', 'gen9ou')
life_orb_set = data.get_smogon_set('pikachu', 'gen9ou', 'Life Orb')

# List available Pokemon
randbats_pokemon = data.list_randbats_pokemon('gen9randombattle')
smogon_pokemon = data.list_smogon_pokemon('gen9ou')

# Update RandBats data
data.update_randbats(['gen9randombattle'])  # specific format
data.update_randbats_all()  # all RandBats formats

# Search across all formats
all_results = data.search_all('pikachu')

# Quick access functions
get_pokemon('pikachu', 'gen9randombattle')  # RandBats
get_smogon_sets('pikachu', 'gen9ou')  # Smogon
```

### Command Line Interface

```bash
# RandBats commands
localsets randbats update
localsets randbats get pikachu --format gen9randombattle
localsets randbats list --format gen9randombattle

# Smogon commands
localsets smogon get pikachu gen9ou
localsets smogon get pikachu gen9ou --set "Life Orb"
localsets smogon sets pikachu gen9ou
localsets smogon list gen9ou
localsets smogon search pikachu
localsets smogon formats

# Unified commands
localsets get pikachu --randbats gen9randombattle --smogon gen9ou
localsets formats --all  # show both RandBats and Smogon formats

# Legacy commands (backward compatibility)
localsets update  # same as randbats update
localsets get pikachu  # same as randbats get
localsets list  # same as randbats list
```

## Supported Formats

### RandBats Formats (Random Battle)

| Format | Generation | Type | Description |
|--------|------------|------|-------------|
| `gen1randombattle` | 1 | Singles | Generation 1 random battle |
| `gen2randombattle` | 2 | Singles | Generation 2 random battle |
| `gen3randombattle` | 3 | Singles | Generation 3 random battle |
| `gen4randombattle` | 4 | Singles | Generation 4 random battle |
| `gen5randombattle` | 5 | Singles | Generation 5 random battle |
| `gen6randombattle` | 6 | Singles | Generation 6 random battle |
| `gen7randombattle` | 7 | Singles | Generation 7 random battle |
| `gen7letsgorandombattle` | 7 | Let's Go | Let's Go Pikachu/Eevee format |
| `gen8randombattle` | 8 | Singles | Generation 8 random battle |
| `gen8bdsprandombattle` | 8 | BDSP | Brilliant Diamond/Shining Pearl |
| `gen8randomdoublesbattle` | 8 | Doubles | Generation 8 doubles battle |
| `gen9randombattle` | 9 | Singles | Generation 9 random battle |
| `gen9randomdoublesbattle` | 9 | Doubles | Generation 9 doubles battle |
| `gen9babyrandombattle` | 9 | Baby | Baby Pokemon format |

### Smogon Formats (Competitive Sets)

| Format | Generation | Type | Description |
|--------|------------|------|-------------|
| `gen9ou` | 9 | OU | OverUsed tier |
| `gen9uu` | 9 | UU | UnderUsed tier |
| `gen9ru` | 9 | RU | RarelyUsed tier |
| `gen9nu` | 9 | NU | NeverUsed tier |
| `gen9pu` | 9 | PU | PU tier |
| `gen9ubers` | 9 | Ubers | Ubers tier |
| `gen9doublesou` | 9 | Doubles | Doubles OU |
| `gen9vgc2024` | 9 | VGC | Video Game Championships 2024 |
| `gen8ou` | 8 | OU | OverUsed tier |
| `gen8uu` | 8 | UU | UnderUsed tier |
| `gen8vgc2022` | 8 | VGC | Video Game Championships 2022 |
| `gen8vgc2023` | 8 | VGC | Video Game Championships 2023 |
| ... | ... | ... | ... (similar for all generations) |



## API Reference

### PokemonData Class

The main class for managing Pokemon data from both RandBats and Smogon sources.

#### Constructor
```python
PokemonData(randbats_formats=None, smogon_formats=None, cache_dir=None, auto_update=True)
```

- `randbats_formats`: List of RandBats format names to load (default: all available)
- `smogon_formats`: List of Smogon format names to load (default: all available)
- `cache_dir`: Directory to store cached data (default: system cache)
- `auto_update`: Whether to automatically check for RandBats updates (default: True)

#### RandBats Methods

- `get_randbats(pokemon_name, format_name=None)`: Get RandBats Pokemon data
- `list_randbats_pokemon(format_name)`: List all Pokemon in a RandBats format
- `get_randbats_formats()`: Get list of available RandBats formats
- `update_randbats(formats=None)`: Update RandBats data for specific formats
- `update_randbats_all()`: Update RandBats data for all available formats

#### Smogon Methods

- `get_smogon_sets(pokemon_name, format_name)`: Get all Smogon sets for a Pokemon
- `get_smogon_set(pokemon_name, format_name, set_name)`: Get a specific Smogon set
- `list_smogon_sets(pokemon_name, format_name)`: List all set names for a Pokemon
- `list_smogon_pokemon(format_name)`: List all Pokemon in a Smogon format
- `get_smogon_formats()`: Get list of available Smogon formats
- `search_smogon(pokemon_name)`: Search for a Pokemon across all Smogon formats

#### Unified Methods

- `get_all_formats()`: Get all available formats from both sources
- `search_all(pokemon_name)`: Search for a Pokemon across both sources

#### Backward Compatibility Methods

- `get_pokemon(pokemon_name, format_name=None)`: Alias for `get_randbats`
- `list_pokemon(format_name)`: Alias for `list_randbats_pokemon`
- `get_formats()`: Alias for `get_randbats_formats`
- `update(formats=None)`: Alias for `update_randbats`
- `update_all()`: Alias for `update_randbats_all`

### Quick Access Functions

- `get_pokemon(pokemon_name, format_name=None)`: Quick RandBats lookup
- `get_smogon_sets(pokemon_name, format_name)`: Quick Smogon sets lookup
- `list_pokemon(format_name)`: Quick RandBats format listing
- `list_smogon_pokemon(format_name)`: Quick Smogon format listing
- `update_data(formats=None)`: Quick RandBats data update

## Data Structure Differences

### RandBats Format (Random Battle)
```json
{
  "pikachu": {
    "level": 50,
    "abilities": ["Static"],
    "items": ["Light Ball"],
    "moves": ["Thunderbolt", "Quick Attack"]
  }
}
```

### Smogon Sets Format (Competitive)
```json
{
  "Pikachu": {
    "Life Orb": {
      "item": "Life Orb",
      "ability": "Static",
      "nature": "Naive",
      "evs": {"atk": 252, "spa": 4, "spe": 252},
      "moves": ["Volt Tackle", "Extreme Speed", "Iron Tail", "Knock Off"]
    },
    "Choice Band": {
      "item": "Choice Band",
      "ability": "Static",
      "nature": "Adamant",
      "evs": {"hp": 4, "atk": 252, "spe": 252},
      "moves": ["Volt Tackle", "Extreme Speed", "Iron Tail", "U-turn"]
    }
  }
}
```

## Configuration

The package uses a JSON configuration file located at `~/.cache/localsets/config.json`:

```json
{
    "update_interval_hours": 24,
    "enabled_randbats_formats": ["gen9randombattle", "gen8randombattle"],
    "enabled_smogon_formats": ["gen9ou", "gen8ou"],
    "auto_update": true,
    "cache_dir": "~/.cache/localsets"
}
```

## Data Sources

### RandBats Data
- **Source**: [pkmn/randbats](https://github.com/pkmn/randbats) repository
- **Raw Data**: `https://raw.githubusercontent.com/pkmn/randbats/main/data/`
- **API Metadata**: `https://api.github.com/repos/pkmn/randbats/contents/data`
- **Update Frequency**: Frequent (daily/weekly)

### Smogon Data
- **Source**: [pkmn/smogon](https://github.com/pkmn/smogon) repository
- **Raw Data**: `https://pkmn.github.io/smogon/data/sets/`
- **Update Frequency**: Infrequent (monthly/seasonal)
- **Bundled**: Data is bundled at build time, no runtime updates

## Caching

- **Cache Directory**: `~/.cache/localsets/` (configurable)
- **RandBats Data Files**: `{format_name}.json`
- **RandBats Metadata Files**: `{format_name}_metadata.json`
- **Smogon Data Files**: Bundled in package, no caching
- **Update Tracking**: `last_update` timestamp file (RandBats only)

## Error Handling

The package includes robust error handling:

- **Network Failures**: Graceful fallback to bundled data
- **Invalid JSON**: Skip corrupted files and continue
- **Missing Data**: Create empty data structures
- **Update Failures**: Continue with existing data
- **Smogon 404s**: Skip unavailable formats during build

## Performance

- **Lazy Loading**: Only load requested formats into memory
- **Caching**: Store updated RandBats data locally for fast access
- **Efficient Updates**: Only download changed RandBats files
- **Memory Management**: Automatic cleanup of unused data
- **Static Smogon Data**: No runtime network requests for Smogon data

## Development

### Building from Source

```bash
git clone <repository>
cd localsets
pip install -e .
```

### Running Tests

```bash
python -m pytest tests/
```

### Building Package

```bash
python setup.py build
python setup.py sdist bdist_wheel
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Acknowledgments

- RandBats data sourced from [pkmn/randbats](https://github.com/pkmn/randbats)
- Smogon data sourced from [pkmn/smogon](https://github.com/pkmn/smogon)
- Built with Python 3.8+ compatibility
- Uses Click for CLI and Rich for beautiful output 
