localdex 0.1.5

A local Pokemon data repository/Pokedex with fast offline access

LocalDex

A fast, offline-first Python library for Pokemon data access. LocalDex provides comprehensive Pokemon information without requiring network requests, making it perfect for applications that need reliable, fast access to Pokemon data.

Features

• 100% Offline: All data is stored locally - no network requests required
• Fast Access: Optimized for quick lookups and searches
• Comprehensive Data: Pokemon, moves, abilities, items, and more
• Flexible Installation: Choose which data sets to include
• Type Hints: Full type support for better development experience
• Multiple Generations: Support for all Pokemon generations
• Competitive Data: Includes battle sets and competitive information

Installation

Basic Installation

pip install localdex

Selective Data Installation

Install only the data you need to minimize package size:

# Core Pokemon data only
pip install localdex[core]

# Specific generation
pip install localdex[gen1]  # Generation 1 only
pip install localdex[gen9]  # Generation 9 only

# Additional data sets
pip install localdex[sprites]      # Pokemon sprites
pip install localdex[competitive]  # Competitive battle data
pip install localdex[learnsets]    # Detailed move learnsets
pip install localdex[items]        # Item data
pip install localdex[abilities]    # Ability data

# Full installation with everything
pip install localdex[full]

Development Installation

git clone https://github.com/yourusername/localdex.git
cd localdex
pip install -e .[dev]

Development & Automation

This project uses GitHub Actions for automated testing, data updates, and PyPI releases. See GITHUB_ACTIONS_SETUP.md for detailed setup instructions.

Quick Setup for Contributors

1. Fork and clone the repository
2. Install dependencies: pip install -e .[dev]
3. Run tests: pytest
4. Update data: python -m localdex.download_data
5. Create pull request

Automated Workflows

• Test: Runs on every PR and push to main
• Data Updates: Weekly automated Pokemon data updates
• Release: Automated PyPI releases on version tags

Quick Start

from localdex import LocalDex

# Initialize the dex
dex = LocalDex()

# Get Pokemon by name
pikachu = dex.get_pokemon("pikachu")
print(f"{pikachu.name} - {pikachu.types}")

# Get Pokemon by ID
charizard = dex.get_pokemon_by_id(6)
print(f"{charizard.name} - HP: {charizard.base_stats.hp}")

# Get Pokemon stats
bulbasaur = dex.get_pokemon("bulbasaur")
print(f"{bulbasaur.name} - Attack: {bulbasaur.base_stats.attack}, Speed: {bulbasaur.base_stats.speed}")

# Get moves
thunderbolt = dex.get_move("thunderbolt")
print(f"{thunderbolt.name} - Power: {thunderbolt.base_power}, Type: {thunderbolt.type}")

# Get abilities (note: use dashes in names like "lightning-rod")
lightning_rod = dex.get_ability("lightning-rod")
print(f"{lightning_rod.name} - {lightning_rod.short_description}")

# Get all Pokemon of a specific type (basic example)
all_pokemon = dex.get_all_pokemon()
fire_pokemon = [p for p in all_pokemon if "Fire" in p.types]
print(f"Fire type Pokemon count: {len(fire_pokemon)}")
print(f"First 5 Fire Pokemon: {[p.name for p in fire_pokemon[:5]]}")

# Get all moves of a specific type
all_moves = dex.get_all_moves()
electric_moves = [m for m in all_moves if m.type == "Electric"]
print(f"Electric moves count: {len(electric_moves)}")
print(f"First 5 Electric moves: {[m.name for m in electric_moves[:5]]}")

API Reference

LocalDex Class

The main class for accessing Pokemon data.

Methods

• get_pokemon(name_or_id: Union[str, int]) -> Pokemon: Get Pokemon by name or ID
• get_pokemon_by_id(id: int) -> Pokemon: Get Pokemon by ID
• get_pokemon_by_name(name: str) -> Pokemon: Get Pokemon by name
• search_pokemon(**filters) -> List[Pokemon]: Search Pokemon with filters
• get_move(name: str) -> Move: Get move by name
• get_ability(name: str) -> Ability: Get ability by name
• get_item(name: str) -> Item: Get item by name
• get_all_pokemon() -> List[Pokemon]: Get all Pokemon
• get_all_moves() -> List[Move]: Get all moves
• get_all_abilities() -> List[Ability]: Get all abilities
• get_all_items() -> List[Item]: Get all items

Search Filters

# Search by type
fire_pokemon = dex.search_pokemon(type="Fire")

# Search by generation
gen1_pokemon = dex.search_pokemon(generation=1)

# Search by multiple criteria
legendary_fire = dex.search_pokemon(type="Fire", is_legendary=True)

# Search by base stat range
strong_pokemon = dex.search_pokemon(min_attack=100)

Data Models

Pokemon

class Pokemon:
    id: int
    name: str
    types: List[str]
    base_stats: BaseStats
    abilities: Dict[str, Ability]
    moves: List[Move]
    height: float
    weight: float
    description: str
    # ... and more

Move

class Move:
    name: str
    type: str
    category: str
    base_power: int
    accuracy: int
    pp: int
    description: str
    # ... and more

Ability

class Ability:
    name: str
    description: str
    short_description: str
    # ... and more

Data Sets

LocalDex organizes data into logical sets that can be installed independently:

Core Data (core)

• Basic Pokemon information (name, types, base stats)
• Essential for most applications

Generation Data (gen1-gen9)

• Pokemon data for specific generations
• Useful for generation-specific applications

Additional Data Sets

• Sprites (sprites): Pokemon images and sprites
• Competitive (competitive): Battle sets and competitive data
• Learnsets (learnsets): Detailed move learning information
• Items (items): Item data and effects
• Abilities (abilities): Detailed ability information

Examples

Pokemon Battle Simulator

from localdex import LocalDex

dex = LocalDex()

def simulate_battle(pokemon1_name: str, pokemon2_name: str):
    pokemon1 = dex.get_pokemon(pokemon1_name)
    pokemon2 = dex.get_pokemon(pokemon2_name)
    
    print(f"{pokemon1.name} vs {pokemon2.name}")
    print(f"{pokemon1.name} types: {pokemon1.types}")
    print(f"{pokemon2.name} types: {pokemon2.types}")
    
    # Calculate type effectiveness
    for move in pokemon1.moves[:4]:  # First 4 moves
        effectiveness = calculate_effectiveness(move.type, pokemon2.types)
        print(f"{move.name} effectiveness: {effectiveness}x")

simulate_battle("pikachu", "charizard")

Pokemon Team Builder

from localdex import LocalDex

dex = LocalDex()

def build_balanced_team():
    team = []
    
    # Get a water type
    water_pokemon = dex.search_pokemon(type="Water", min_speed=80)
    if water_pokemon:
        team.append(water_pokemon[0])
    
    # Get a fire type
    fire_pokemon = dex.search_pokemon(type="Fire", min_attack=100)
    if fire_pokemon:
        team.append(fire_pokemon[0])
    
    # Get a grass type
    grass_pokemon = dex.search_pokemon(type="Grass", min_special_attack=90)
    if grass_pokemon:
        team.append(grass_pokemon[0])
    
    return team

team = build_balanced_team()
for pokemon in team:
    print(f"{pokemon.name} - {pokemon.types}")

Move Database

from localdex import LocalDex

dex = LocalDex()

def analyze_moves():
    # Get all moves
    all_moves = dex.get_all_moves()
    
    # Find the strongest moves
    strong_moves = [move for move in all_moves if move.base_power >= 120]
    print(f"Strong moves (120+ power): {len(strong_moves)}")
    
    # Find status moves
    status_moves = [move for move in all_moves if move.category == "Status"]
    print(f"Status moves: {len(status_moves)}")
    
    # Find moves by type
    fire_moves = [move for move in all_moves if move.type == "Fire"]
    print(f"Fire moves: {len(fire_moves)}")

analyze_moves()

CLI Usage

LocalDex includes a command-line interface for quick data access:

# Get Pokemon information
localdex pokemon pikachu

# Search Pokemon
localdex search --type Fire --generation 1

# Get move information
localdex move thunderbolt

# Get ability information
localdex ability lightningrod

# List all Pokemon
localdex list-pokemon

# Export data to JSON
localdex export --format json --output pokemon_data.json

Performance

LocalDex is optimized for fast access:

• Memory Efficient: Data is loaded on-demand
• Fast Lookups: Optimized data structures for quick searches
• Caching: Frequently accessed data is cached in memory
• Indexed Searches: Pre-built indexes for common search patterns

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/yourusername/localdex.git
cd localdex
pip install -e .[dev]
pytest  # Run tests
black .  # Format code
mypy .   # Type checking

License

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

Data Sources

LocalDex uses data from:

• Pokemon Showdown
• PokeAPI (for initial data collection)

Changelog

See CHANGELOG.md for a list of changes and version history.