pokeapi_wrapper.py

import requests
import json

BASE_URL = "https://pokeapi.co/api/v2"

def _get(endpoint: str, name_or_id: str) -> str:
    """
    Internal helper to fetch data from PokéAPI and handle errors.

    Args:
        endpoint (str): API endpoint (e.g., 'pokemon', 'item')
        name_or_id (str): Resource name or ID

    Returns:
        str: JSON string response from the API

    Raises:
        ValueError: If the resource is not found or an error occurs
    """
    url = f"{BASE_URL}/{endpoint}/{str(name_or_id).lower()}"
    headers = {
        "Accept": "application/json",
        "Content-Type": "application/json"
    }
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        return json.dumps(response.json())
    raise ValueError(f"❌ {endpoint} '{name_or_id}' not found (HTTP {response.status_code})")


def get_pokemon(name_or_id):
    """
    Get full data for a Pokémon (stats, abilities, types, sprites, etc.).

    Args:
        name_or_id (str or int): Pokémon name or Pokédex ID

    Returns:
        str: Pokémon data
    """
    return _get("pokemon", name_or_id)



def get_pokemon_species(name_or_id):
    """
    Get species-level data for a Pokémon (evolution chain, flavor text, gender ratio, etc.).

    Args:
        name_or_id (str or int): Pokémon name or ID

    Returns:
        str: Pokémon species data
    """
    return _get("pokemon-species", name_or_id)


def get_ability(name_or_id):
    """
    Get details about a specific Pokémon ability (effects, Pokémon with this ability, etc.).

    Args:
        name_or_id (str or int): Ability name or ID

    Returns:
        str: Ability data
    """
    return _get("ability", name_or_id)


def get_type(name_or_id):
    """
    Get data for a specific Pokémon type (damage relations, Pokémon by type, etc.).

    Args:
        name_or_id (str or int): Type name or ID

    Returns:
        str: Type data
    """
    return _get("type", name_or_id)


def get_item(name_or_id):
    """
    Get information on an item (e.g., Potion, Berry, Stone).

    Args:
        name_or_id (str or int): Item name or ID

    Returns:
        str: Item data
    """
    return _get("item", name_or_id)


def get_berry(name_or_id):
    """
    Get data about a specific berry (flavor, firmness, effects, etc.).

    Args:
        name_or_id (str or int): Berry name or ID

    Returns:
        str: Berry data
    """
    return _get("berry", name_or_id)


def get_evolution_chain(chain_id):
    """
    Get full data for an evolution chain (species involved, stages, etc.).

    Args:
        chain_id (int): Evolution chain ID (not Pokémon ID)

    Returns:
        str: Evolution chain data
    """
    return _get("evolution-chain", chain_id)


def get_location(name_or_id):
    """
    Get information on a specific location in the Pokémon world.

    Args:
        name_or_id (str or int): Location name or ID

    Returns:
        str: Location data
    """
    return _get("location", name_or_id)


def get_move(name_or_id):
    """
    Get detailed data for a specific move (power, accuracy, type, effects).

    Args:
        name_or_id (str or int): Move name or ID

    Returns:
        str: Move data
    """
    return _get("move", name_or_id)


def get_stat(name_or_id):
    """
    Get metadata about a base stat (e.g., HP, Attack).

    Args:
        name_or_id (str or int): Stat name or ID

    Returns:
        str: Stat data
    """
    return _get("stat", name_or_id)


def get_egg_group(name_or_id):
    """
    Get information about an egg group (used for Pokémon breeding compatibility).

    Args:
        name_or_id (str or int): Egg group name or ID

    Returns:
        str: Egg group data
    """
    return _get("egg-group", name_or_id)


def get_pokemon_form(name_or_id):
    """
    Get data about a specific form of a Pokémon (e.g., Alolan, Galarian forms).

    Args:
        name_or_id (str or int): Form name or ID

    Returns:
        str: Pokémon form data
    """
    return _get("pokemon-form", name_or_id)


def get_pokemon_habitat(name_or_id):
    """
    Get information about the habitat where a Pokémon is commonly found.

    Args:
        name_or_id (str or int): Habitat name or ID

    Returns:
        str: Habitat data
    """
    return _get("pokemon-habitat", name_or_id)


def get_pokemon_color(name_or_id):
    """
    Get Pokémon categorized by their color (used mainly for Pokédex sorting).

    Args:
        name_or_id (str or int): Color name or ID

    Returns:
        str: Color group data
    """
    return _get("pokemon-color", name_or_id)


def get_pokemon_shape(name_or_id):
    """
    Get Pokémon categorized by shape (used in evolution and form grouping).

    Args:
        name_or_id (str or int): Shape name or ID

    Returns:
        str: Shape group data
    """
    return _get("pokemon-shape", name_or_id)


def get_generation(name_or_id):
    """
    Get data about a Pokémon generation (introduced species, moves, types, etc.).

    Args:
        name_or_id (str or int): Generation name or ID (e.g., 'generation-i')

    Returns:
        str: Generation data
    """
    return _get("generation", name_or_id)


def get_version(name_or_id):
    """
    Get information about a game version (e.g., Red, Blue, Diamond, etc.).

    Args:
        name_or_id (str or int): Version name or ID

    Returns:
        str: Version data
    """
    return _get("version", name_or_id)


def get_version_group(name_or_id):
    """
    Get groupings of game versions (used for shared move sets, regions, etc.).

    Args:
        name_or_id (str or int): Version group name or ID

    Returns:
        str: Version group data
    """
    return _get("version-group", name_or_id)


def get_pokedex(name_or_id):
    """
    Get data for a specific Pokédex (regional or national).

    Args:
        name_or_id (str or int): Pokédex name or ID (e.g., 'kanto', 'national')

    Returns:
        str: Pokédex data
    """
    return _get("pokedex", name_or_id)


def get_region(name_or_id):
    """
    Get details about a region in the Pokémon world (e.g., Kanto, Sinnoh).

    Args:
        name_or_id (str or int): Region name or ID

    Returns:
        str: Region data
    """
    return _get("region", name_or_id)