localsets 0.1.5

Local Pokemon random battle sets (auto-updating) and Smogon competitive sets

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)

pip install localsets

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

Installation Without CLI

pip install localsets[no-cli]

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

Development Installation

pip install localsets[dev]

This includes development dependencies for testing and code quality tools.

Quick Start

Programmatic Usage

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

# 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

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)

{
  "pikachu": {
    "level": 50,
    "abilities": ["Static"],
    "items": ["Light Ball"],
    "moves": ["Thunderbolt", "Quick Attack"]
  }
}

Smogon Sets Format (Competitive)

{
  "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:

{
    "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 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 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

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

Running Tests

python -m pytest tests/

Building Package

python setup.py build
python setup.py sdist bdist_wheel

License

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

Contributing

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

Acknowledgments

• RandBats data sourced from pkmn/randbats
• Smogon data sourced from pkmn/smogon
• Built with Python 3.8+ compatibility
• Uses Click for CLI and Rich for beautiful output