pokemon-stats-reader 0.1.1
Librería para leer y consultar estadísticas de Pokémon desde archivos CSV
License: MIT
Requires Python: >=3.7
Keywords: pokemon, statistics, csv, data-analysis

# Pokemon Stats Reader

[![PyPI version](https://badge.fury.io/py/pokemon-stats-reader.svg)](https://badge.fury.io/py/pokemon-stats-reader)
[![Python Versions](https://img.shields.io/pypi/pyversions/pokemon-stats-reader.svg)](https://pypi.org/project/pokemon-stats-reader/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Librería Python para leer y consultar estadísticas de Pokémon desde archivos CSV.

## Características

- ✅ **Lectura eficiente** de estadísticas desde CSV
- ✅ **Caché integrado** para optimizar consultas repetidas
- ✅ **API simple e intuitiva**
- ✅ **Tres métodos principales** para consultar datos
- ✅ **Powered by pandas** para procesamiento eficiente

## Instalación

```bash
pip install pokemon-stats-reader
```

## Uso Rápido

```python
from pokemon_stats import PokemonStatsReader

# Crear instancia del lector
reader = PokemonStatsReader("estadisticas_grupos.csv")

# 1. Obtener lista de todos los grupos
grupos = reader.get_grupos_pokemon()
print(f"Grupos disponibles: {grupos}")

# 2. Obtener altura media de un grupo
altura = reader.get_altura_media_grupo("monster")
print(f"Altura media del grupo 'monster': {altura}")

# 3. Obtener peso medio de un grupo
peso = reader.get_peso_medio_grupo("water1")
print(f"Peso medio del grupo 'water1': {peso}")
```

## API Reference

### `PokemonStatsReader(csv_path: str)`

Inicializa el lector de estadísticas.

**Parámetros:**
- `csv_path` (str): Ruta al archivo CSV con estadísticas

### `get_grupos_pokemon() -> List[str]`

Obtiene la lista de todos los grupos de Pokémon.

**Retorna:**
- `List[str]`: Lista con nombres de todos los grupos

**Ejemplo:**
```python
grupos = reader.get_grupos_pokemon()
# ['monster', 'water1', 'bug', 'dragon', ...]
```

### `get_altura_media_grupo(grupo: str) -> Optional[float]`

Obtiene la altura media de un grupo específico.

**Parámetros:**
- `grupo` (str): Nombre del grupo

**Retorna:**
- `float`: Altura media del grupo
- `None`: Si el grupo no existe

**Ejemplo:**
```python
altura = reader.get_altura_media_grupo("monster")
# 12.5
```

### `get_peso_medio_grupo(grupo: str) -> Optional[float]`

Obtiene el peso medio de un grupo específico.

**Parámetros:**
- `grupo` (str): Nombre del grupo

**Retorna:**
- `float`: Peso medio del grupo
- `None`: Si el grupo no existe

**Ejemplo:**
```python
peso = reader.get_peso_medio_grupo("water1")
# 425.7
```

## Formato del CSV

El archivo CSV debe tener el siguiente formato:

```csv
grupo,cantidad_pokemon,altura_media,peso_medio
monster,45,12.5,850.3
water1,38,9.2,425.7
bug,28,6.8,145.2
```

**Columnas requeridas:**
- `grupo`: Nombre del grupo de huevo
- `cantidad_pokemon`: Número de Pokémon en el grupo
- `altura_media`: Altura promedio del grupo
- `peso_medio`: Peso promedio del grupo

## Ejemplo Completo

```python
from pokemon_stats import PokemonStatsReader

# Inicializar lector
reader = PokemonStatsReader("estadisticas_grupos.csv")

# Obtener y mostrar todos los grupos
print("=" * 60)
print("GRUPOS DE POKÉMON DISPONIBLES")
print("=" * 60)

grupos = reader.get_grupos_pokemon()
for grupo in grupos:
    altura = reader.get_altura_media_grupo(grupo)
    peso = reader.get_peso_medio_grupo(grupo)
    print(f"\n{grupo.upper()}")
    print(f"  Altura media: {altura}")
    print(f"  Peso medio: {peso}")

print("=" * 60)
```

## Características Avanzadas

### Caché Automático

La librería implementa caché automático para optimizar consultas repetidas:

```python
reader = PokemonStatsReader("datos.csv")

# Primera llamada: lee del CSV
altura1 = reader.get_altura_media_grupo("monster")  # ~10ms

# Segunda llamada: usa caché
altura2 = reader.get_altura_media_grupo("monster")  # ~0.1ms
```

### Obtener Todas las Estadísticas

```python
# Obtener DataFrame completo
df = reader.get_all_stats()
print(df)

# Obtener estadísticas de un grupo específico
stats = reader.get_grupo_stats("monster")
print(stats)
# {'grupo': 'monster', 'cantidad_pokemon': 45, 'altura_media': 12.5, 'peso_medio': 850.3}
```

## Requisitos

- Python >= 3.7
- pandas >= 2.0.0

## Licencia

MIT License - ver archivo [LICENSE](LICENSE) para detalles.

## Contribuir

Las contribuciones son bienvenidas! Por favor:

1. Fork el repositorio
2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
4. Push a la rama (`git push origin feature/AmazingFeature`)
5. Abre un Pull Request

## Testing

```bash
# Instalar dependencias de desarrollo
pip install pytest pytest-cov

# Ejecutar tests
pytest tests/

# Ejecutar tests con cobertura
pytest tests/ --cov=pokemon_stats --cov-report=html
```

## Soporte

Si encuentras algún problema o tienes sugerencias:
- Abre un [issue](https://github.com/tuusuario/pokemon-stats-reader/issues)
- Contacta al autor: tu.email@example.com

## Roadmap

- [ ] Soporte para múltiples formatos (JSON, XML)
- [ ] CLI para consultas desde terminal
- [ ] Visualizaciones gráficas
- [ ] Soporte async para archivos grandes

## Autor

**Tu Nombre** - [GitHub](https://github.com/tuusuario)

## Agradecimientos

- Datos obtenidos de [PokeAPI](https://pokeapi.co/)
- Inspirado en la comunidad de Pokémon

---

**¿Te gusta este proyecto?** ⭐ Dale una estrella en GitHub!