Metadata-Version: 2.4
Name: biblia-cli-project
Version: 0.1.0
Summary: CLI para consultar versículos bíblicos desde JSON y APIs
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: platformdirs>=4.9.4
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: rich>=14.3.3
Description-Content-Type: text/markdown

# 📖 Biblia CLI

Una herramienta de línea de comandos rápida y basada en Python para buscar y recuperar versículos bíblicos desde archivos JSON locales y APIs externas.

## ¿Qué hace la CLI?

Biblia CLI permite consultar versículos bíblicos de manera eficiente. Soporta búsqueda por referencia (como "Exodo 33:7"), rangos de versículos, búsqueda de texto completo y puede obtener datos desde fuentes locales (archivos JSON) o APIs remotas (como YouVersion).

Características principales:
- **Búsqueda por referencia**: Encuentra versículos específicos o rangos.
- **Búsqueda de texto**: Busca palabras o frases en toda la Biblia usando un índice invertido.
- **Fuentes múltiples**: Soporte para datos locales y APIs externas.
- **Interfaz rica**: Salida formateada con números de versículo en superíndice.
- **Configurable**: Selecciona versiones bíblicas y proveedores.

## Instalación

### Requisitos previos
- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (gestor de paquetes Python)

### Pasos de instalación

1. Clona el repositorio:
```bash
git clone https://github.com/yourusername/biblia-cli.git
cd biblia-cli
```

2. Crea y activa un entorno virtual:
```bash
uv venv
# En Windows:
.venv\Scripts\activate
# En Unix/Linux/macOS:
source .venv/bin/activate
```

3. Instala las dependencias:
```bash
uv sync
```

4. Construye e instala el paquete (opcional para desarrollo):
```bash
uv build
uv run pip install --force-reinstall dist/*.whl
```

## Configuración de .env

Para usar la API de YouVersion, necesitas configurar una clave de API:

1. Copia el archivo de ejemplo:
```bash
cp .env_example .env
```

2. Edita `.env` y agrega tu clave de API de YouVersion:
```
YVP_APP_KEY="tu_clave_de_api_aqui"
```

> **Nota**: La clave de API es necesaria solo si planeas usar fuentes remotas. Para uso local, no es requerida.

## Comandos principales

### Listar versiones disponibles
```bash
biblia versions
```
Lista todas las versiones bíblicas disponibles en español.

### Seleccionar versión activa
```bash
biblia use RV1960
```
Configura la versión bíblica activa para consultas con API.

### Buscar por referencia
```bash
biblia ref "Exodo 33:7"
```
Busca un versículo específico.

### Buscar rangos de versículos
```bash
biblia ref "Exodo 33:7,10"
```
Busca un rango de versículos consecutivos.

### Búsqueda de texto
```bash
biblia buscar "amor"
```
Busca una palabra o frase en toda la Biblia.

### Limitar resultados de búsqueda
```bash
biblia buscar "amor" --limit 5
```
Limita el número de resultados mostrados.

### Mostrar texto completo en búsquedas
```bash
biblia buscar "amor" --show
```
Muestra el texto completo de los versículos en los resultados.

### Mostrar versión
```bash
biblia --version
```
Muestra la versión del CLI.

## Ejemplo con fuente local

Para usar datos locales (archivos JSON), especifica `--source local`:

```bash
biblia ref "Exodo 33:7" --source local
```

Esto buscará en los archivos JSON locales en el directorio `data/`.

## Ejemplo con API

Para usar una API externa (requiere configuración previa):

1. Selecciona una versión:
```bash
biblia use RV1960
```

2. Busca con fuente API:
```bash
biblia ref "Exodo 33:7" --source api
```

O usa `auto` para que el CLI elija automáticamente (local si disponible, API si no):
```bash
biblia ref "Exodo 33:7" --source auto
```

## Estructura del proyecto

```
biblia-cli/
├─ biblia/              # Paquete principal
│   ├─ cli.py          # Interfaz de línea de comandos
│   ├─ bible.py        # Lógica de búsqueda de versículos
│   ├─ search.py       # Búsqueda de texto
│   ├─ indexer.py      # Constructor de índice invertido
│   ├─ refs.py         # Analizador de referencias
│   ├─ loader.py       # Cargador de datos JSON
│   ├─ resolver.py     # Resolución de fuentes
│   ├─ config.py       # Configuración de API
│   ├─ config_store.py # Almacenamiento de configuración
│   ├─ models.py       # Modelos de datos
│   ├─ utils.py        # Utilidades
│   └─ providers/      # Proveedores de datos
│       └─ youversion.py # Cliente de YouVersion API
├─ data/               # Datos bíblicos (archivos JSON)
│   ├─ exodo.json      # Libro de Éxodo
│   └─ index.json      # Índice invertido
├─ tests/              # Pruebas
├─ pyproject.toml      # Configuración del proyecto
├─ .env_example        # Ejemplo de configuración
└─ README.md           # Este archivo
```

## Cómo funciona

1. **Almacenamiento de datos**: El contenido bíblico se almacena en formato JSON, un archivo por libro.
2. **Indexación**: Un índice invertido mapea palabras a versículos para búsquedas rápidas.
3. **Análisis**: Un analizador personalizado maneja nombres de libros con espacios (ej. "1 Corintios").
4. **Formateo**: Los números de versículo se muestran en superíndice para mejor legibilidad.
5. **Proveedores**: Soporte para múltiples fuentes de datos (local y APIs).

## Agregar más libros

1. Crea un nuevo archivo JSON en `data/` siguiendo este formato:
```json
{
  "libro": "Nombre del Libro",
  "capitulos": [
    {
      "capitulo": 1,
      "versiculos": [
        {"versiculo": 1, "texto": "Texto del versículo 1"},
        {"versiculo": 2, "texto": "Texto del versículo 2"}
      ]
    }
  ]
}
```

2. Actualiza el índice ejecutando el indexador.

## Contribuir

¡Las contribuciones son bienvenidas! Por favor, abre un issue o envía un pull request.

## Licencia

Este proyecto está bajo la Licencia MIT.
  "abreviaturas": ["Abr"],
  "capitulos": {
    "1": {
      "1": "Verse text here...",
      "2": "Another verse..."
    }
  }
}
```

2. Rebuild the index to include the new book:
```bash
python -m biblia.indexer
```

## Development

Install development dependencies:
```bash
uv add --dev pytest
```

Run tests:
```bash
uv run pytest
```

## Future Improvements

- Full chapter lookup
- Abbreviation support (e.g., `Jn 3:16`)
- REST API
- Rich terminal output formatting
- PyPI publication

## License

MIT

## Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.
